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/nodes.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/ | MERGE, find, get, delete for typed relationships. Decomposed into edges.py, nodes.py, vectors.py, github.py, factory.py. |
| 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/vector_index.py | 1024-dim eidos_embeddings index, legacy migration. Extracted from driver.py in April 2026 SRP refactor. |
| MCP integration | Shipped | eidos/pyproject.toml | fastapi-mcp dependency present |
| Agent runner endpoint (POST /api/v1/agents/curator) | Shipped | eidos/src/eidos/api/endpoints/agents.py | HTTP bridge for running curator agent; used by Hermes plugin via httpx |
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 |
EmbeddingServiceProtocol | Shipped | core/src/sokrates_core/protocols.py | Runtime-checkable protocol for embedding services; DI interface for VoyageEmbeddingService and future local models (DGX Spark) |
ModelRouter | Shipped | core/src/sokrates_core/protocols.py | Resolves pydantic-ai model identifiers from deployment config; env-overridable per use-case (e.g., SOKRATES_LLM_MODEL_CLASSIFIER) |
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 |
| Ontological classifier | Shipped | hyle/src/hyle/classifier.py | pydantic-ai Agent via ModelRouter (default: google-gla:gemini-3.1-pro-preview). Classifies schemas into Entity/Process/Law/Observation. |
| 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 (multi-source parsing) | Shipped | wiki/src/wiki/normalize/ | Claude Code sessions, Claude.ai conversations, memory files, documents → NormalizedDocument JSON |
| Embed (Voyage AI) | Shipped | wiki/src/wiki/embed/ | Voyage-context-3 contextualized embeddings, batch logic |
| Discover (topic clustering) | Shipped | wiki/src/wiki/discover/ | DBSCAN + LDA topic extraction, PCA visualization |
| Extract (entity extraction) | Shipped | wiki/src/wiki/extract/ | Cluster → WikiNode synthesis, inter-node edge 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 | ctl/hermes/ | Registers tool for Hermes to invoke curator via HTTP bridge to Eidos /api/v1/agents/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 | pydantic-ai Agent via ModelRouter (default: google-gla:gemini-3.1-pro-preview) classifies schemas into Entity/Process/Law/Observation. |
| 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 | plugins/ai-sentinel/ | 5 scanner subagents, tiered significance, email delivery |
| Wiki Sentinel (vault maintenance) | Shipped | 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