epistemic-graph AGENTS.md

AGENTS.md — Epistemic Graph Compute Engine

Claude Code loads this file via CLAUDE.md (@AGENTS.md import) — the two stay in sync. Edit this file, not CLAUDE.md.

Project Name: epistemic-graph Ecosystem Prefix: EG / EPG Key Concepts: CONCEPT:EG-KG.compute.graph-compute-engine (High-Performance Graph Compute Engine), CONCEPT:EG-KG.query.wire-protocol (Tokio Service Layer), CONCEPT:AU-KG.memory.mementified-context (Rust-Native Finance), CONCEPT:EG-KG.compute.rust-native-training-loss (Data Science Primitives), CONCEPT:AU-KG.domains.legal-automation (Rust-Accelerated Reasoning), CONCEPT:EG-KG.txn.per-graph-write-isolation (Lock-Free Compute + Engine Observability)

---

Overview

Unified Rust-native computation engine for the agent-packages ecosystem. Consolidates graph operations, quantitative finance, data science, AST analysis, and OWL reasoning into a single high-performance binary.

Transport (important — this changed): the engine is exposed to Python out-of-process via a long-running Tokio service speaking length-prefixed MessagePack over Unix Domain Sockets (default) or TCP, authenticated with HMAC-SHA256. eg2. is the sole request envelope: every served request carries a verified principal, tenant, audience, effective agent, policy version, scopes, timestamp, nonce, and idempotency key. The server MUST NOT open a listener without the security feature, a non-empty signing secret, deployment policy values, a durable replay ledger, and a signer-key registry (see docs/service_mode.md#authentication-protocol).

Two deployment shapes, one performance discipline (this edict evolved — see history). (a) Out-of-process (the horizontal-scale default): Python talks to a long-running Tokio engine over the socket — GIL-free, so one engine backs many graph-os clients and scales independently; the wheel ships the epistemic-graph-server binary + a pure-Python client (bindings = "bin"). (b) Unified single binary (the self-contained default — EVOLVING): for a self-contained deployment (one graph-os, no horizontal fan-out) the engine is embedded in-process via PyO3 — one binary, one lifecycle, no socket serialize/round-trip, no cross-image drift — and is preferred wherever it consolidates with no hot-path cost. The rule that keeps BOTH shapes fast is the same and non-negotiable: engine calls MUST stay BATCHED (one call = one batch op over graph-resident data, never a per-element Python loop) and the engine's tokio/compute internals MUST stay pure Rust — so Python never bottlenecks the hot path in either shape. Rust-native/optimized is the default; PyO3 MUST sit only at that batched boundary, and MUST NOT appear in a per-op inner loop. (History: PyO3 was originally removed outright to stay GIL-free and horizontally scalable — the right call for a shared, scaled engine. It is now restored as the OPT-IN unified path because a self-contained deployment gains a single consolidated binary with no measured downside, and the batching discipline preserves the original performance goal that motivated the removal. scripts/check_no_pyo3.sh therefore scopes to the scale-out build, not the unified one.)