Sókrates Wiki

Sokrates Core Architecture and Service Layers

4 min read

Sokrates Core Architecture and Service Layers

Summary

The Sokrates system is architected as a containerized stack comprising three primary services: Eidos (the knowledge layer), Hermes Agent (the intelligence and communication layer), and Neo4j (the graph database). This structure facilitates a clean separation between data persistence, semantic indexing, multi-channel communication, and high-level reasoning processes.

Details

The Sokrates stack is deployed as a set of three Docker containers running on NixOS appliances. These components work in concert to provide the “outsourced AI department” functionality, moving from raw data ingestion to complex reasoning and user-facing interactions.

sokrates-core (Shared Infrastructure)

Extracted April 2026 from eidos/core/ into a standalone workspace package (core/src/sokrates_core/). All workspace members depend on it. Provides:

  • Error hierarchy: ApplicationError tree with typed codes, levels, and structured ErrorDetails models. Auto-instrumented by Logfire.
  • Decorators: @with_error_handling (sync/async), @with_session (driver-agnostic session injection).
  • Circuit breaker: CircuitBreaker with configurable thresholds, state machine, and RetryWithCircuitBreaker wrapper.
  • Structured logging: structlog + Logfire integration, context vars, OTEL.

Eidos (The Knowledge Layer)

Eidos is the central API and ORM layer, implemented as a FastAPI application using Python 3.13. It follows a clean architecture pattern:

  • api/: REST endpoints — unified query DSL, code indexing, Confluence integration, GitHub webhooks, health, admin. Consolidated from six routers into a coherent API surface (April 2026 refactor removed Redis, OAuth, and conversation memory subsystems).
  • domain/: Core models for the Hyle ontology (Entity, Process, Law, Observation), typed edges (BaseEdge discriminated union), search strategies, and composable filtering DSL.
  • infrastructure/: NodeRepository[T] (generic node CRUD: persist/find/get/delete/persist_many/exists/count), EdgeRepository (typed edge CRUD: relate/relate_many/find/get/delete), Neo4j driver, CypherQueryBuilder (fluent, state-machine validated), Voyage AI embeddings with Neo4j-backed cache.
  • services/: Git connector, Confluence connector, GitHub webhook + reconciliation, code processing.

Key API endpoints:

  • POST /api/v1/code/index: Indexes local or GitHub repositories for semantic code search.
  • POST /api/v1/unified/query: JSON-based DSL for complex similarity searches and graph traversals.
  • GET /health: Neo4j connectivity check.

Hermes Agent (Channel I/O)

Hermes Agent is the communication periphery — the “ears and mouth” of the system. Built on the NousResearch Hermes Agent Framework, it provides:

  • Multi-channel communication: Telegram, Discord, Slack, WhatsApp, Teams, email. Message routing, session management, heartbeats.
  • Plugin system: Skills format for packaging tools and automations.
  • SOUL.md personality: Persistent identity across sessions.
  • Security hardening: NoNewPrivileges, ProtectSystem=strict, scoped ReadWritePaths. Holds channel credentials but no customer system credentials.

Sókrates Agent (The Intelligence Layer)

The Sókrates Agent is the proprietary brain — multi-mode orchestration via Pydantic-AI agents with Logfire telemetry. It cycles through four modes (see Technical Architecture Whitepaper §5.2):

  1. Socratic Interrogation — examining the knowledge graph for anomalies and incomplete regions.
  2. Topology Mapping — evaluating hyperedges, updating the organisational model.
  3. Inefficiency Surfacing — authoring new generating queries that capture discovered patterns.
  4. Validation — checking termination, non-empty results, and acyclicity.

The intelligence layer queries Eidos via MCP, consults the basis, and dispatches research sub-agents. On DGX Spark boxes, inference runs locally via finetuned Gemma 4 31B Dense. On CWWK N305 boxes, inference routes to Anthropic (Claude) by default, with future routing to Fleet Command.

Hermes operates as the “nervous system,” Eidos as the “memory,” and the Sókrates Agent as the “brain.” The periphery/intelligence split is a security boundary: a channel compromise cannot reach customer operational data.

Hyle (Schema Ingestion Pipeline)

Hyle is a workspace package (hyle/) that ingests OpenAPI specs and produces typed, persisted knowledge graphs. Shipped April 2026 with a 6-stage pipeline proven on NorthWind (11 entity types, 22 edge mappings):

  1. SpecParser — extracts schemas, scalar fields, $ref relationships, FK field detection
  2. Generator — DMCG (datamodel-code-generator) produces Pydantic v2 models inheriting from BaseNode
  3. Classifier — Gemini classifies schemas into Entity/Process/Law/Observation primitives
  4. Transformer — injects node_type: Literal[...], rewrites base classes to primitives, strips $ref fields, preserves FK scalars
  5. EdgeMapper — maps $ref relationships to typed edges with direction normalization
  6. Loader — importlib hot-loads the module, HyleMeta auto-registers types in NodeRegistry

Additional components:

  • Data fetcher (hyle/src/hyle/fetch/): Declarative httpx client. EndpointConfig model encodes auth (discriminated union), pagination strategy (discriminated union), and response shape. Generic executor yields raw dicts.
  • GraphWriter (hyle/src/hyle/persist.py): Writes nodes via natural key MERGE and edges via FK-based resolution from EdgeManifest. No UUID mapping needed — source system natural keys are the identity.

Infrastructure and Deployment

The stack utilizes Neo4j 5 Community Edition as its primary data store, accessible via ports 7474 and 7687. The system is designed to be self-contained; images are built via Nix flakes and generally do not rely on host-side volume mounts for application code, which resides in /app/src/ within the containers.

On the host NixOS system, the directory /var/lib/sokrates/ is reserved for persistent data, secrets, and MCP (Model Context Protocol) configurations. The uv workspace (pyproject.toml at root) manages 9 packages: eidos, hyle, wiki, agents, sokrates-core, three bundles (cowork, code, compound), and sokrates-ctl.

Graph View

Backlinks