coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hub-core/SCOPE.md
tegwick 118d4fdcfe
Some checks failed
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details
feat(ecosystem): hub-core library lane for three-repo stack (HUB-WP-0003) 
Add slugify_or_default for core-hub parity, bump to 0.2.0, document ecosystem
position in INTENT/SCOPE/README, wire capability relations to state-hub and
core-hub, and extend utils tests. Part of CUST-WP-0057 consolidation.
2026-07-11 01:26:47 +02:00

5.3 KiB
Raw Blame History

SCOPE — hub-core

Updated: 2026-06-16

One-liner

Reusable Python package of FastAPI router factories, SQLAlchemy models, Pydantic schemas, MCP tooling, and migration scaffolds for FOS hub services.

Core idea

hub-core is a library boundary between shared hub infrastructure and host-specific hub implementations. Host repositories depend on hub-core as an editable or published package; they run the actual HTTP/MCP service, own deployment, and add domain tables and workflows on top.

In scope

  • hub_core Python package — models, schemas, routers, MCP server wrapper, utilities, events, database helpers
  • Router factories with host-injected sessions, models, and callbacks (domains, repos, messages, progress, capabilities, TPSC, policy)
  • Alembic migration scaffold for core tables adopters extend
  • Tests under tests/ proving import seams and MCP behavior
  • Package metadata — pyproject.toml, hatchling wheel build
  • Capability registry scaffold — registry/ per helix_forge federation contract (entries added when reusable behaviors are registered)
  • Documentation — README.md, INTENT.md, SCOPE.md, pointer to extraction boundary in the-custodian

Out of scope

  • Long-running hub service, Docker image, or production URL for hub-core itself
  • Dev-hub tables: topics, workplans, tasks, decisions, dependencies, SBOM, token accounting, kaizen agents
  • State Hub dashboard UI, consistency sync scripts, and workplan file authority
  • Custodian canon content and constitution maintenance
  • Plaintext secrets, environment-specific connection strings committed to git
  • Replacing or wrapping non-hub application domains (feature-control, reuse-surface, etc.)

What is possible now

After the CUST-WP-0025 first slice (2026-06-06 — 2026-06-07):

Capability Status
Install as editable package pip install -e . / uv equivalent
Import core models and schemas hub_core.models, hub_core.schemas
Mount generic routers in a host FastAPI app hub_core.routers.create_*_router
Run generic MCP tools via HubCoreMCPServer hub_core.mcp
Apply core-schema migration template hub_core/migrations/versions/0001_core_schema.py
Adopt shared slug/pagination/path utilities hub_core.utils
Expose risk/alert progress read views /progress/risks, /progress/alerts patterns
State Hub incremental adoption Schemas, messages, policy, TPSC, progress, domains, capability catalog routers imported 
cd ~/hub-core
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/pytest -q

What is not possible yet

  • Published PyPI package — consumed via editable path or private index only
  • Standalone hub-core serve — no CLI entrypoint; hosts own uvicorn
  • Complete State Hub decoupling — dev-hub routes and models still live in state-hub
  • ops-hub / fin-hub adoption — planned; not verified in this repo
  • Capability registry entries — scaffold only (capabilities: []); no registered reusable behaviors yet
  • Gitea federation publish — repo not yet on Gitea; blocks T01 in reuse-surface WP-0015

Current state

Item Value
Package version 0.1.0 (hub_core.__version__)
Python >=3.12
Dependencies FastAPI, FastMCP, SQLAlchemy, Pydantic, httpx
Tests pytest under tests/
Registry Empty capability index; federation scaffold present
Primary consumer state-hub (editable dependency, router/schema import in progress)
Extraction workplan CUST-WP-0025 (custodian domain)

Repository layout

hub-core/
├── INTENT.md
├── SCOPE.md
├── README.md
├── pyproject.toml
├── hub_core/
│   ├── models/
│   ├── schemas/
│   ├── routers/
│   ├── mcp/
│   ├── migrations/
│   ├── utils/
│   ├── database.py
│   └── events.py
├── registry/
│   ├── capabilities/
│   └── indexes/capabilities.yaml
└── tests/

Boundaries with sibling repos

Repo Boundary
state-hub Primary host — mounts router factories and MCP composition; owns workplans/tasks
core-hub Secondary consumer — imports utils/schemas; owns /api/v2 framework tables locally
the-custodian Owns ecosystem architecture (hub-ecosystem-architecture.md) and extraction boundary
reuse-surface Federation hub for capability indexes; not a runtime dependency of hub-core
ops-hub Consumer of core-hub /api/v2; operations tables stay local

Workplan convention

Hub-core extraction and package work is tracked under custodian workplans (for example CUST-WP-0025). Host adoption milestones are tracked in state-hub workplans (for example CUST-WP-0048).

When hub-core gains repo-local workplans, prefer a stable prefix agreed with custodian operators (for example HUBCORE-WP-####).

Getting oriented

  • Product intent: INTENT.md
  • Extraction boundary: /home/worsch/the-custodian/docs/hub-core-extraction-boundary.md
  • Package entry: hub_core/__init__.py, hub_core/routers/__init__.py
  • Consumer example: /home/worsch/state-hub (editable hub-core dependency)
  • Federation registry: registry/README.md (reuse-surface contract)