Skip to main content

Learning service

alphaswarm_learning is a running service (FastAPI on :8012, plus an MCP surface) built around one Neo4j knowledge graph carrying two co-equal capabilities:

  1. a quant-finance research and pedagogy knowledge base with Socratic agentic tutoring, and
  2. a code / infrastructure intelligence graph over the AlphaSwarm codebase.

Humans and agents both ingest documents and files that expand the graph; user annotations are first-class graph nodes; both retrieve over REST and MCP.

It introduces no datastore the platform does not already run — Neo4j (native vector indexes, Lucene full-text, GDS Leiden), Postgres RLS for service metadata, Redis for task status and caching, and the platform model gateway for LLM and embedding calls. It never touches order, execution or risk-gate code.

This page supersedes two stale descriptions

The org repo table classified this repo seed / "README-only placeholder", and the repo's own README still opens with a "Phase 0 (foundation)" status. Neither matches the code: the ingestion, retrieval, MCP, pedagogy, scholar and code-graph subsystems below all exist and ship with CI.

Subsystems​

AreaWhat it does
graph/Neo4j driver, schema DDL, bitemporal Cypher, migrations, read guard
ingest/ + parsing/Document and code ingestion into the graph
retrieval/GraphRAG retrieval, including text-to-Cypher behind the read guard
pedagogy/Annotations, episodic memory, mastery, compounding, doc sync
scholar/Paper connectors (arXiv, OpenAlex), crawler, tutoring, plans, hypotheses
sokg/Analytics: centrality, Leiden communities, contagion, hypotheses, debate, hygiene
code/The code-intelligence graph (files, modules, classes, functions)
authz/Deny-by-default require_permission chain (ReBAC → ABAC → RBAC)
mcp/16 tools; raw-query tools are analyst/admin audience only

Relationship to the Graph Data Pillar​

Learning is a consumer of the Graph Data Pillar, not a second graph platform. Concretely:

  • The envelope is shared. models/bitemporal.py's Bitemporal is a subclass of alphaswarm_core.graph.envelope.BitemporalStamp — the same valid_from/valid_to/tx_from/tx_to, half-open, UTC. It used to mirror the SOKG envelope by copy.
  • The read guard is shared. graph/read_guard.py takes its write-clause deny-list, LIMIT pattern and result cap from alphaswarm_core.graph.guard. Only the error types and the tenant-filter message are service-local, because the API maps them to HTTP 400.
  • The vocabulary overlap is pinned. NodeLabel / EdgeType stay service-local — the code graph, pedagogy and community labels are learning-plane vocabulary the platform taxonomy has no reason to carry — but a parity test asserts that every member shared with the core taxonomy means the same string, and that every divergence is declared.

Two divergences recorded rather than hidden​

  • DERIVES_FROM vs DERIVED_FROM. Learning spells it one way, the platform taxonomy the other, for the same idea. Renaming learning's is a Neo4j property migration against a live deployment, so it is sequenced with the pillar's schema-convergence work rather than done opportunistically.
  • GROUNDED_IN exists in neither enum. Scholar code refers to an edge grounding a tutoring episode in the chunk it drew on, but no such kind is defined. It is proposed in alphaswarm_core/docs/graph-taxonomy-proposals.md and awaits alphaswarm-graph-expert review — the taxonomy is closed, so adding a member is a governance act, not a code change. Until then, tutor-episode persistence is blocked, deliberately.

Boundaries​

  • No monolith imports. Enforced by a frozen-count ratchet in scripts/ci/check_no_alphaswarm_imports.py that fails on an increase and on a decrease, so the count is a deliberate number rather than a drift.
  • A second guard tracks scholar-tier separation readiness (report-only, with a recorded backlog).
  • Honest CI. The hermetic unit tier runs report-only against a recorded backlog of genuinely-broken tests rather than pretending they pass. Exclusions are conditional — each names an environment a module needs (monolith + KB installed, or live network opted in), never a defect it carries.