Files

tegwick 986ac4d40b Add hub-core package, docs, and State Hub integration scaffold

Extract the first reusable slice (models, schemas, routers, MCP, migrations)
from state-hub with INTENT/SCOPE, agent instructions, workplan, and aligned
inter_hub capability registry index.

2026-06-16 02:39:36 +02:00

5.2 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, workstreams, 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`	Host dev-hub; imports hub-core factories; keeps workstream/task/decision logic
`the-custodian`	Owns extraction boundary doc and CUST-WP-0025 workplan
`reuse-surface`	Federation hub for capability indexes; not a runtime dependency of hub-core
`ops-hub`	Future consumer; operations-specific 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)

5.2 KiB Raw Blame History