alphaswarm-graph

Catalog date: 2026-06-24.

The alphaswarm-graph service is the implementation of the multi-tenant Self-Organizing Knowledge Graph (SOKG). It provides the recursive discovery engine, the graph-topology metrics pipeline, and the tenant-scoped store + service surfaces that feed the Quant Agent Platform (QAP).

Role

• Recursive Discovery: Runs the LangGraph-based loop to expand the concept layer.
• Topology Analysis: Computes scale-free fits, community detection (Leiden), and centralities.
• Entity Grounding: Validates proposed triples against the FIBO/GICS/FIGI entity layer (ungrounded triples are quarantined, never written).
• Evidence Storage: Persists backtest results as evidence edges with confidence scores.

Multi-tenancy

Every store / agent / metrics / ontology operation carries a GraphTenantContext, and the store stamps tenant_id server-side — a caller can never speak for another tenant. Tenancy follows the platform cell/silo lattice via two isolation modes:

• Shared cell (IsolationMode.SHARED_CELL): one Neo4j database shared by many tenants; every node/edge is keyed by tenant_id, and shared-cell reads must constrain on $tenant_id.
• Dedicated silo (IsolationMode.DEDICATED_SILO): the tenant owns a dedicated Neo4j database ({prefix}-{tenant_id}); the database boundary is the isolation boundary. Arbitrary write Cypher is permitted only in this mode.

A TenantRegistry (the data-plane analog of kb_silo_registry) maps each tenant to its TenantGraphBinding; per-tenant connection secrets resolve through the alphaswarm_core SecretStore / CredentialKey port. The GraphTenantManager composes routing + authorization + tenant lifecycle (provision / deprovision / federated cross-tenant reads over the composite Fabric database). Dedicated-silo provisioning is delegated to the control plane via the SiloProvisioner port (HTTP-only; the service never imports the controller).

Authorization

A pluggable GraphAuthorizer gates every read / write / admin / cross-tenant action before the data plane is touched. The default in-process evaluator allows same-tenant access, permits hierarchical reads of a declared parent_tenant_id, and denies cross-tenant access unless the principal is privileged (admin:cluster scope or alphaswarm-superadmin). Concrete SpiceDB / Cedar / OPA adapters register under an alias selected by ALPHASWARM_GRAPH_AUTHORIZER_ALIAS.

Surfaces

• HTTP (alphaswarm-graph-api): /graph/* REST — tenant provisioning, structured node/edge upserts, read-only Cypher, metrics, evidence, and federated reads. Tenancy comes from X-Alphaswarm-Tenant-Id (and optional -Principal-Id / -Roles / -Scopes) or upstream request.state; it fails closed when absent.
• MCP (alphaswarm-graph-mcp): the three mcp-neo4j-cypher-style tools — get-graph-schema, read-graph-cypher (read transaction, auto-approvable), write-graph-cypher (human approval; dedicated-silo only) — plus graph-metrics. Carries the per-MCP audience alphaswarm://mcp/graph (AGENTS rule 49).

Dependencies

• Neo4j Enterprise: Primary graph store, multi-database isolation, and GDS analytics.
• ArcticDB: S3-backed time-series storage for bulk instrument data (graph stores pointers, not bulk series).
• LLM Gateway: Reasoning calls route through the injected router_complete-backed model — the service never constructs a vendor SDK client directly.

Configuration

The service is configured via alphaswarm_graph.core.settings (ALPHASWARM_GRAPH_*, read through the get_settings() singleton):

Key	Description	Default
NEO4J_URI	Neo4j Bolt URI	bolt://localhost:7687
NEO4J_USER	Auth user	neo4j
NEO4J_PASSWORD	Auth password	password
NEO4J_DATABASE	Shared-cell database	neo4j
DEFAULT_ISOLATION_MODE	Isolation for unregistered tenants	shared_cell
COMPOSITE_DATABASE	Composite/Fabric DB for cross-tenant reads	fabric
DEDICATED_DATABASE_PREFIX	Dedicated silo db = {prefix}-{tenant_id}	tenant
AUTHORIZER_ALIAS	Selects the authorizer adapter	default
MCP_AUDIENCE	Per-MCP audience claim	alphaswarm://mcp/graph
ARCTIC_S3_PATH	S3 path for ArcticDB	s3://alphaswarm-data/arctic/

Optional dependencies live behind extras ([metrics], [agent], [ontology], [api], [mcp]); the core library imports with none installed.

Observability

• Graph Health: Tracked via node_count, edge_count, and powerlaw_alpha.
• Discovery Rate: Number of newly connected node-pairs per iteration.
• Evidence Yield: Ratio of discovered concepts that pass OOS backtesting.

Repository

• alphaswarm_graph/