Sokrates Implementation Status
What exists, what’s designed, and what’s still research. Updated after each major milestone.
Context: The Technical Architecture Whitepaper describes the full vision. This page tracks which parts of that vision have working code.
Status Legend
| Status | Meaning |
|---|---|
| Shipped | In production or running on dev box. Code exists, tests pass. |
| In Progress | Active development. Partial implementation exists. |
| Designed | Architecture defined in wiki/whitepaper. No implementation code. |
| Research | Exploratory. May inform future architecture but no commitment to build. |
Core Type System (Hyle)
| Component | Status | Code Location | Notes |
|---|---|---|---|
BaseNode base class | Shipped | eidos/src/eidos/domain/models/hyle.py | UUID id, timestamps, source provenance, Neo4j serialization |
HyleMeta metaclass | Shipped | eidos/src/eidos/domain/models/hyle.py | Extends Pydantic ModelMetaclass, fail-at-construction registration |
NodeRegistry | Shipped | eidos/src/eidos/domain/models/hyle.py | Living registry with versioning, observer hooks, dynamic discriminated union |
@node decorator | Shipped | eidos/src/eidos/domain/models/hyle.py | Graph labels, indexes, constraints, repository binding, source provenance |
| Four primitives (Entity, Process, Law, Observation) | Shipped | eidos/src/eidos/domain/models/primitives.py | All four with correct fields and embedding support |
| Typed edges (ParticipatesIn, Constrains, Evidences, etc.) | Shipped | eidos/src/eidos/domain/models/edges.py | 7 edge types with discriminated union, Neo4j serialization (neo4j_type(), to_neo4j_properties()) |
_defer_registration for abstract intermediaries | Shipped | eidos/src/eidos/domain/models/hyle.py | Prevents abstract classes from polluting registry |
Knowledge Graph (Eidos API)
| Component | Status | Code Location | Notes |
|---|---|---|---|
| FastAPI application with lifespan management | Shipped | eidos/src/eidos/main.py | Neo4j + embeddings init. Redis and OAuth removed in April 2026 refactor. |
| Health endpoint | Shipped | eidos/src/eidos/api/endpoints/core.py | Neo4j connectivity check |
| Unified Query DSL (POST /query) | Shipped | eidos/src/eidos/api/endpoints/unified_query.py | Full QueryDSL with specs, similarity, relationships, debug mode. Consolidated from 6 endpoints. |
NodeRepository[T] generic repository | Shipped | eidos/src/eidos/infrastructure/repositories/memory.py | persist/find/get/delete/persist_many/exists/count with type safety |
EdgeRepository typed edge CRUD | Shipped | eidos/src/eidos/infrastructure/repositories/edges.py | relate/relate_many/find/get/delete for BaseEdge subtypes |
EdgeQueries centralized Cypher | Shipped | eidos/src/eidos/infrastructure/neo4j/queries.py | MERGE, find, get, delete for typed relationships |
| Specification pattern | Shipped | eidos/src/eidos/domain/specifications/ | Composable predicates with Cypher generation |
| Cypher query builder (fluent, state-machine validated) | Shipped | eidos/src/eidos/infrastructure/neo4j/query_builder/ | PatternBuilder, LiteralString safety, clause sequencing |
| Filter compiler | Shipped | eidos/src/eidos/infrastructure/neo4j/filter_compiler.py | Operators, logical groups, null checks |
| Neo4j vector index management | Shipped | eidos/src/eidos/infrastructure/neo4j/driver.py | 1024-dim eidos_embeddings index, legacy migration |
| MCP integration | Shipped | eidos/pyproject.toml | fastapi-mcp dependency present |
Embeddings & Search
| Component | Status | Code Location | Notes |
|---|---|---|---|
| Voyage AI embedding service | Shipped | eidos/src/eidos/infrastructure/embeddings/voyage.py | Circuit breaker, retry, batch support |
| Embedding cache (Neo4j-backed) | Shipped | eidos/src/eidos/infrastructure/embeddings/cache.py | Model-aware, 30-day expiry, hit counting |
| Embedding service factory + builder | Shipped | eidos/src/eidos/infrastructure/embeddings/factory.py | Protocol-based DI, validation |
| Cosine / Euclidean search strategies | Shipped | eidos/src/eidos/domain/search/strategies.py | Protocol-based strategy pattern |
| Similarity specification (Cypher generation) | Shipped | eidos/src/eidos/domain/specifications/similarity.py | Reduce-based cosine in Cypher |
Connectors
| Component | Status | Code Location | Notes |
|---|---|---|---|
| Git repository indexer | Shipped | eidos/src/eidos/services/git_connector_service.py | Walk, filter, embed, semantic code search |
| Confluence connector | Shipped | eidos/src/eidos/services/confluence_connector_service.py | Space listing, page indexing, semantic search |
| GitHub webhook + reconciliation | Shipped | eidos/src/eidos/api/endpoints/github.py, services/github/ | HMAC auth, push events, stale node cleanup |
| Code analysis & AST segmentation | Shipped | eidos/src/eidos/services/code_processor.py | Function/class extraction, importance scoring |
| Obsidian vault loader | Shipped | wiki/src/wiki/load/vault.py | Loads wiki vault pages as typed nodes into Neo4j |
Shared Infrastructure (sokrates-core)
Extracted April 2026 from eidos/core/ into standalone workspace package (core/src/sokrates_core/). All workspace members depend on it.
| Component | Status | Code Location | Notes |
|---|---|---|---|
| Circuit breaker (generic) | Shipped | core/src/sokrates_core/circuit_breaker.py | Configurable thresholds, state machine, retry wrapper |
| Error hierarchy (ApplicationError tree) | Shipped | core/src/sokrates_core/errors/ | Typed codes, levels, structured details (base, concrete, context) |
@with_error_handling decorator | Shipped | core/src/sokrates_core/decorators.py | Sync/async, error context capture, ErrorHandlerProtocol |
@with_session decorator | Shipped | core/src/sokrates_core/decorators.py | Async session injection (generic, not Neo4j-specific) |
| Structlog + Logfire integration | Shipped | core/src/sokrates_core/logging/ | Structured JSON, contextvars, OTEL via Logfire |
| Error context tracing (trace_id) | Shipped | core/src/sokrates_core/errors/context.py | UUID trace, structured capture |
Schema Ingestion (DMCG Pipeline — Hyle)
Full 6-stage pipeline shipped April 2026. Proven end-to-end: NorthWind OpenAPI spec → 11 typed node classes + 22 edge mappings → Neo4j (22 nodes, 18 relationships).
| Component | Status | Code Location | Notes |
|---|---|---|---|
| OpenAPI spec parser | Shipped | hyle/src/hyle/spec_parser.py | Extracts schemas, scalar fields, $ref relationships, FK field detection |
DMCG code generation (--base-class hyle.BaseNode) | Shipped | hyle/src/hyle/generator.py | Python API wrapper around datamodel-code-generator |
| Gemini ontological classifier | Shipped | hyle/src/hyle/classifier.py | Classifies schemas into Entity/Process/Law/Observation. classification_override for deterministic CI. |
| Post-DMCG transformer | Shipped | hyle/src/hyle/transformer.py | Injects node_type: Literal[...], rewrites base classes to primitives, strips $ref fields, preserves FK scalars, adds @node decorator |
| Typed edge mapper | Shipped | hyle/src/hyle/edge_mapper.py | Maps $ref relationships to typed edges (ParticipatesIn/Evidences/Constrains/DependsOn) with direction normalization |
importlib hot-loading | Shipped | hyle/src/hyle/loader.py | Loads transformed module, HyleMeta fires, NodeRegistry auto-registers types |
HylePipeline orchestrator | Shipped | hyle/src/hyle/pipeline.py | Chains all 6 stages end-to-end |
| Declarative data fetcher | Shipped | hyle/src/hyle/fetch/ | EndpointConfig model with auth + pagination discriminated unions. HttpxFetcher generic executor. Config factory from SpecInfo. |
GraphWriter (Neo4j persistence) | Shipped | hyle/src/hyle/persist.py | Natural key MERGE for nodes, FK-based edge creation from EdgeManifest. Proven with NorthWind → Neo4j. |
| Schema healing (detect change → regenerate → reload) | Designed | Technical Architecture Whitepaper §2.3 | E0.2 (SOK-88): version-namespaced modules, importlib.reload() |
Wiki Pipeline
| Component | Status | Code Location | Notes |
|---|---|---|---|
| Normalize (HTML → markdown) | Shipped | wiki/src/wiki/normalize.py | Confluence HTML to clean markdown |
| Embed (Voyage AI) | Shipped | wiki/src/wiki/embed.py | Voyage-4-large, 1024-dim |
| Discover (topic clustering) | Shipped | wiki/src/wiki/discover/ | HDBSCAN + LDA topic extraction |
| Extract (entity extraction) | Shipped | wiki/src/wiki/extract.py | Gemini-powered entity extraction |
| Synthesize (cross-document) | Shipped | wiki/src/wiki/synthesize.py | Gemini-powered document synthesis |
| Load (Neo4j) | Shipped | wiki/src/wiki/load/vault.py | Obsidian vault → typed nodes in Neo4j |
Curator Agent
| Component | Status | Code Location | Notes |
|---|---|---|---|
| Pydantic-AI curator agent | Shipped | agents/src/agents/curator/agent.py | System prompt, tools, structured CurationReport output |
| CurationReport / CurationProposal models | Shipped | agents/src/agents/curator/models.py | Actions: merge, archive, flag_obsolete, flag_contradiction |
| EidosClient HTTP wrapper | Shipped | agents/src/agents/curator/client.py | Async client for curator-to-Eidos communication |
| Hermes plugin (run_curator tool) | Shipped | hermes-plugin/sokrates/ | Registers tool for Hermes to invoke curator |
| Cron-triggered curator runs | Designed | — | Hermes cron config not yet wired |
| Telegram approval flow | Designed | — | Curator proposals surfaced for human approval before execution |
| Action execution (merge/archive/delete) | Designed | — | Curator proposes but cannot yet execute approved actions |
Observer Pattern Wiring
| Component | Status | Code Location | Notes |
|---|---|---|---|
NodeRegistry.on_register() hook mechanism | Shipped | eidos/src/eidos/domain/models/hyle.py:74 | Observer hooks fire on type registration |
| Eidos subscribes to registry hooks | Designed | — | E0.3 (SOK-89). No code subscribes yet. Technical Architecture Whitepaper §1.2 describes auto-creating Neo4j constraints and triggering relationship inference on registration. |
Semantic Enrichment
| Component | Status | Code Location / Wiki Reference | Notes |
|---|---|---|---|
| Ontological classification (auto-primitive assignment) | Shipped | hyle/src/hyle/classifier.py | Gemini 3.1 Pro Preview classifies schemas into Entity/Process/Law/Observation. Deterministic override for CI. |
| Gemma 4 31B Dense integration | Designed | Technical Architecture Whitepaper §3 | Will replace Gemini API with on-device Gemma for enrichment |
| Semantic field enrichment | Designed | Technical Architecture Whitepaper §3.1 | — |
| Cross-source entity resolution | Designed | Technical Architecture Whitepaper §3.1 | — |
| LoRA fine-tuning pipeline | Designed | Technical Architecture Whitepaper §3.3, §5.1 | — |
GQL Query Builder
| Component | Status | Wiki Reference | Notes |
|---|---|---|---|
| GQL AST layer | Designed | Hyle Graph-Native ORM with Dynamic Schema Registry | Current query builder targets Cypher only |
| Dialect serializers (Cypher, GQL, Fabric) | Designed | Technical Architecture Whitepaper §4.6 | — |
Hypergraph Metalayer
| Component | Status | Wiki Reference | Notes |
|---|---|---|---|
| Generating queries (hyperedges as computation) | Designed | Technical Architecture Whitepaper §4.1 | — |
| Three-layer architecture (ground facts → queries → metalayer) | Designed | Technical Architecture Whitepaper §4.2 | — |
| Materialization policy (MATERIALIZED / VIRTUAL) | Designed | Technical Architecture Whitepaper §4.4 | — |
| Differential evaluation | Designed | Technical Architecture Whitepaper §4.5 | — |
| Metalayer DSL | Designed | Hyle Graph-Native ORM with Dynamic Schema Registry | — |
Self-Evolution Harness
| Component | Status | Wiki Reference | Notes |
|---|---|---|---|
| DSPy module wrapping | Designed | Technical Architecture Whitepaper §5.3 | — |
| GEPA prompt evolution | Designed | Technical Architecture Whitepaper §5.3 | — |
| Atropos RL environments | Designed | Technical Architecture Whitepaper §5.3 | — |
| Metalayer query evolution | Research | Technical Architecture Whitepaper §5.3 | — |
| Cognitive antibodies | Research | Technical Architecture Whitepaper §5.3 | — |
Hardware & Fleet
| Component | Status | Wiki Reference | Notes |
|---|---|---|---|
| GMKtec dev box (sokrates-dev) | Shipped | nixos/ | Running NixOS, Docker stack, Hermes Agent |
| CWWK N305 customer box (sokrates-box) | Shipped | nixos/ | Locked down, nftables egress whitelist, fleet management. Budget option. |
| DGX Spark deployment | Designed | Technical Architecture Whitepaper §5 | Primary target for on-device inference. No NixOS config yet. |
| DGX Station GB300 fleet command | Research | Technical Architecture Whitepaper §5.6 | — |
| Basis Genesis Engine | Shipped | — | Pre-seeds basis from external sources before customer engagements |
| Cross-fleet basis learning | Designed | Technical Architecture Whitepaper §9 | — |
Cognitive Architecture
| Component | Status | Wiki Reference | Notes |
|---|---|---|---|
| Strange loop / self-directed cognition | Research | Technical Architecture Whitepaper §5.4 | Pure research direction |
| Metacognitive daemons | Research | Technical Architecture Whitepaper §5.4 | — |
| Negative space compression | Research | Technical Architecture Whitepaper §5.3 | — |
Automation & Plugins
| Component | Status | Code Location | Notes |
|---|---|---|---|
| AI Sentinel (daily briefing agent) | Shipped | bundles/plugins/ai-sentinel/ | 5 scanner subagents, tiered significance, email delivery |
| Wiki Sentinel (vault maintenance) | Shipped | bundles/plugins/wiki-sentinel/ | Reviews git logs, updates wiki pages, /wiki-update command |
Related
- Technical Architecture Whitepaper — full vision document
- Executive Summary — The Autonomous AI Department — non-technical overview
- Sokrates System Architecture — current system architecture
- Sokrates Core Architecture and Service Layers — service layer detail
- Hyle Graph-Native ORM with Dynamic Schema Registry — Hyle deep dive
- Eidos Curator Agent and Hyle Ontological Framework — curator detail