Fathom

A modern Python-first expert system runtime built on CLIPS. Define rules in YAML. Evaluate in microseconds. Zero hallucinations.

Part of the Kraken stack: Fathom (reasoning engine) · Nautilus (policy data broker) · Stargraph (agent-graph framework).

Current version: 0.12.0

License: MIT

Language: Python 3.12+ (primary), Go and TypeScript SDKs in progress

Package Manager: uv

Maintained by: Kraken Networks

Why Fathom?

Every AI agent framework lets agents decide what to do by guessing. For most tasks, that's fine.

For some tasks, guessing is unacceptable:

• Policy enforcement — "Is this agent allowed to do this?" can't be a maybe.
• Data routing — "Which databases should this query hit?" can't hallucinate a source.
• Compliance — "Did this fleet operate within NIST 800-53 controls?" needs a provable answer.
• Classification — "What clearance level does this data require?" is not a prompt engineering problem.

Fathom provides deterministic, explainable, auditable reasoning using CLIPS — a battle-tested expert system — wrapped in a modern Python library with YAML-first rule authoring.

Install

uv add fathom-rules

Quick Start

from fathom import Engine

# Loads templates/, modules/, functions/, and rules/ from a project directory
engine = Engine.from_rules("policy/")

engine.assert_fact("agent", {
    "id": "agent-alpha",
    "clearance": "secret",
    "purpose": "threat-analysis",
    "session_id": "sess-001",
})

engine.assert_fact("data_request", {
    "agent_id": "agent-alpha",
    "target": "hr_records",
    "classification": "top-secret",
    "action": "read",
})

result = engine.evaluate()
print(result.decision)       # "deny"
print(result.reason)         # "Agent clearance is below the data classification (no read up)"
print(result.duration_us)    # ~90 (microseconds; varies by machine)

See the Getting Started guide for a full walkthrough.

What Ships Today

Core runtime (Python)

• YAML compiler for templates, rules, modules, and functions
• Forward-chaining evaluation with rule + module traces
• Working memory persistence across evaluations within a session
• Classification-aware operators (below, meets_or_exceeds, dominates, compartments)
• Temporal operators (count_exceeds, rate_exceeds, changed_within, last_n, distinct_count, sequence_detected)
• Rule-assertion actions (then.assert + bind) and user-defined Python functions (Engine.register_function)
• Structured JSON audit log with append-only sinks
• Ed25519 attestation service for signed evaluation results
• Fleet reasoning with Redis and Postgres backends for shared working memory

Integrations

• FastAPI REST server with bearer-token auth and rule-path jailing
• gRPC server with bearer-token auth (see protos/fathom.proto)
• MCP tool server (FathomMCPServer) for agent discovery
• Framework adapters — LangChain callback handler, CrewAI before-tool-call hook, OpenAI Agents SDK tool guardrail, Google ADK before-tool callback. Each is allowlist-only: the call proceeds when the decision is exactly allow, and every other outcome raises PolicyViolation (ADK returns an error dict instead)
• CLI — fathom validate, fathom compile, fathom test, fathom bench, fathom info, fathom status, fathom verify-artifact, fathom verify-chain, fathom repl
• Docker sidecar (Debian slim + uv)
• Prometheus metrics export (/metrics endpoint)
• Policy Studio — browser UI over a real engine, shipped as its own package (packages/fathom-studio/, run with uv run fathom-studio). See Running Policy Studio

Rule packs

• fathom-owasp-agentic — OWASP Agentic Top 10 mitigations
• fathom-nist-800-53 — Access control, audit, information flow
• fathom-hipaa — PHI handling, minimum necessary, breach triggers
• fathom-cmmc — CMMC Level 2+ controls
• fathom-ssvc — SSVC supplier, deployer, and CISA vulnerability-triage trees (144 rules)

SDKs (in progress)

• fathom-go — REST + gRPC client (packages/fathom-go/); unit and integration suites run in CI, not yet published to a Go proxy
• fathom-ts — @fathom-rules/sdk (packages/fathom-ts/); hand-written client covering 4 of the 10 REST endpoints, vitest suite required in CI, not yet published to npm

Integrations that are scaffolded, partial, or planned are catalogued in Planned Integrations.

Core Primitives

Key Differentiator: Working Memory

Unlike stateless policy engines (OPA, Cedar), Fathom maintains working memory across evaluations within a session:

• Cumulative reasoning — "This agent accessed PII from 3 sources — deny the 4th."
• Temporal patterns — "Denial rate spiked 400% in 10 minutes — escalate."
• Cross-fact inference — "Agent A passed data to Agent B, who is requesting external access — violation."

Integration Shapes

As a library

from fathom import Engine
engine = Engine.from_rules("rules/")
result = engine.evaluate()

As a REST sidecar

docker run -p 8080:8080 -v ./rules:/rules ghcr.io/krakennet/fathom:latest
curl -H "Authorization: Bearer $TOKEN" -X POST localhost:8080/v1/evaluate \
  -d '{"facts": [...], "ruleset": "access-control"}'

As a gRPC sidecar

# protos/fathom.proto — regenerate Go/TS clients from the proto
grpcurl -H "authorization: Bearer $TOKEN" \
  -d '{"facts": [...]}' localhost:50051 fathom.v1.Fathom/Evaluate

As an MCP tool

from fathom.integrations.mcp_server import FathomMCPServer
server = FathomMCPServer(engine)
server.serve()

Documentation

Docs live under docs/ and build with MkDocs Material (Diátaxis information architecture).

Entry points:

• Getting Started
• Tutorials
• How-to Guides
• Concepts
• Reference
• Configuration — every FATHOM_* variable and the gRPC TLS setup

Performance Targets

Measured by scripts/benchmark.py and enforced on every pull request by CI's bench job, which fails the build if a median regresses past its target. Compilation is stated per rule because it scales with pack size: the packaged SSVC pack is 144 rules. The numbers above are what the benchmark reports on a developer machine; CI enforces them with a 2x allowance (--slack 2.0) because GitHub's shared runners measured 1.2x to 1.9x slower than that machine across five consecutive runs of the same job. Run python scripts/benchmark.py with no slack to hold your own hardware to the published numbers directly.

Related Projects

• Bosun: Agent governance built on Fathom (fleet analysis, compliance attestation)
• Nautilus: Intelligent data broker built on Fathom (multi-source routing, classification-aware scoping)
• Stargraph: Workgraph, AI orchestration framework built on Fathom

Development

git clone https://github.com/KrakenNet/fathom.git
cd fathom
uv sync --all-extras            # --all-extras is required for the full test suite

uv run pytest                   # engine, integrations, and Studio suites
uv run ruff check src/ tests/   # lint
uv run mypy src/                # type check
uv run pytest --cov=fathom      # coverage report
uv run mkdocs serve             # docs preview

Run the live REST server locally:

uv run uvicorn fathom.integrations.rest:app --reload

See CONTRIBUTING.md for full development guidelines and CHANGELOG.md for release notes.

Stability

Fathom is pre-1.0. VERSIONING.md names the surfaces that are covered — fathom.__all__, the YAML authoring keys, the REST/gRPC/MCP contracts, and the CLI — states what a 0.x minor and patch bump each mean for them, and defines the deprecation period. The symbol list there is checked against the package on every test run.

Star History

License

MIT — see LICENSE for details.

Maintained by Kraken Networks · krakennetworks.com · krakn.ai