fathom

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.14.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, within_scope, in_compartment, has_compartments) and the fathom-dominates built-in
• 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, fathom mcp, fathom convert
• 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

Load one by name with Engine.load_pack("<name>"):

• owasp-agentic — OWASP Agentic Top 10 mitigations
• nist-800-53 — Access control, audit, information flow
• hipaa — PHI handling, minimum necessary, breach triggers
• cmmc — CMMC Level 2+ controls
• ssvc — SSVC supplier, deployer, and CISA vulnerability-triage trees (144 rules)
• schema-denoising — promotes a relation to stable schema once enough extracted facts carry it
• conflict-detection — reports contradictions between claims about the same subject as conflict facts

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

Primitive	Purpose	CLIPS Construct
Templates	Define fact schemas with typed slots	deftemplate
Facts	Typed instances asserted into working memory	working memory
Rules	Pattern-matching logic with conditions and actions	defrule
Modules	Namespace rules with controlled execution order	defmodule
Functions	Reusable logic for conditions and actions	deffunction

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

# ./rules/access-control/ holds a ruleset (templates/, rules/, ...);
# the image serves rulesets from /rules (FATHOM_RULESET_ROOT).
export TOKEN=change-me
docker run -p 8080:8080 -e FATHOM_API_TOKEN="$TOKEN" \
  -v "$PWD/rules:/rules:ro" ghcr.io/krakennet/fathom:latest
curl -X POST localhost:8080/v1/evaluate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"facts": [], "ruleset": "access-control"}'

As a gRPC sidecar

# Server: fathom.integrations.grpc_server.serve(), TLS by default
# (docs/reference/configuration.md#grpc-tls). It has no reflection, so
# grpcurl reads protos/fathom.proto — regenerate Go/TS clients from it too.
grpcurl -import-path protos -proto fathom.proto \
  -H "authorization: Bearer $TOKEN" \
  -d '{"ruleset": "access-control", "facts": []}' \
  localhost:50051 fathom.v1.FathomService/Evaluate

As an MCP tool

from fathom.integrations.mcp_server import FathomMCPServer
server = FathomMCPServer("rules/")
server.run()  # stdio

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

Operation	Target
Single rule evaluation	< 100µs
100-rule evaluation	< 500µs
Fact assertion	< 25µs
YAML compilation	< 2ms per rule

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, the CLI, the rule packs and pack format, the framework integrations, the Rego converter, and the Redis/Postgres fleet stores — 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