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 (The Intelligence and Communication Layer)

Hermes Agent is the central daemon handling both channel I/O and high-level reasoning. Developed by NousResearch, it provides a sophisticated agentic framework that:

  • Manages multi-channel communication: Natively supports Telegram, Discord, Slack, WhatsApp, and other platforms.
  • Handles agentic loops: Executes the primary AIAgent core loop, managing user interactions and decision-making.
  • Interfaces with knowledge: Accesses Eidos via the Model Context Protocol (MCP) to query the knowledge graph and persistent memory.
  • Enforces security boundaries: Implements strict systemd hardening including NoNewPrivileges, ProtectSystem=strict, and scoped ReadWritePaths.

Hermes operates as the “nervous system” of Sokrates, while Eidos serves as the “memory.” This separation allows proprietary reasoning logic and knowledge to be isolated within secure boundaries while maintaining rich user interactions.

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