Metadata-Version: 2.5
Name: fathom-rules
Version: 0.11.0
Summary: Deterministic reasoning runtime for AI agents, built on CLIPS via clipspy
Project-URL: Homepage, https://krakn.ai
Project-URL: Documentation, https://fathom.krakn.ai
Project-URL: Repository, https://github.com/KrakenNet/fathom
Project-URL: Changelog, https://github.com/KrakenNet/fathom/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/KrakenNet/fathom/issues
Author-email: Kraken Networks <info@krakennetworks.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,ai-safety,clips,compliance,deterministic,expert-system,guardrails,hipaa,langchain,mcp,nist,owasp,policy-engine,rules-engine,symbolic-ai,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: clipspy<1.1,>=1.0.6
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: all
Requires-Dist: asyncpg<1,>=0.29; extra == 'all'
Requires-Dist: crewai<2,>=0.80; extra == 'all'
Requires-Dist: cryptography<51,>=42.0; extra == 'all'
Requires-Dist: fastapi<1,>=0.100; extra == 'all'
Requires-Dist: google-adk<3,>=1.0; extra == 'all'
Requires-Dist: grpcio-tools<2,>=1.60; extra == 'all'
Requires-Dist: grpcio<2,>=1.60; extra == 'all'
Requires-Dist: langchain-core<2,>=0.2; extra == 'all'
Requires-Dist: mcp<3,>=1.28.1; extra == 'all'
Requires-Dist: openai-agents<1,>=0.1; extra == 'all'
Requires-Dist: prometheus-client<1,>=0.20; extra == 'all'
Requires-Dist: prometheus-fastapi-instrumentator<9,>=7; extra == 'all'
Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'all'
Requires-Dist: redis[hiredis]<9,>=5; extra == 'all'
Requires-Dist: rich<16,>=13; extra == 'all'
Requires-Dist: typer[all]<1,>=0.12; extra == 'all'
Requires-Dist: uvicorn<1,>=0.20; extra == 'all'
Provides-Extra: attestation
Requires-Dist: cryptography<51,>=42.0; extra == 'attestation'
Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'attestation'
Provides-Extra: cli
Requires-Dist: rich<16,>=13; extra == 'cli'
Requires-Dist: typer[all]<1,>=0.12; extra == 'cli'
Provides-Extra: crewai
Requires-Dist: crewai<2,>=0.80; extra == 'crewai'
Provides-Extra: docs
Requires-Dist: mike<3,>=2.1; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs-redirects<2,>=1.2; extra == 'docs'
Requires-Dist: mkdocs-swagger-ui-tag<1,>=0.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]<2,>=0.24; extra == 'docs'
Requires-Dist: pdoc<17,>=14.0; extra == 'docs'
Provides-Extra: fleet
Requires-Dist: redis[hiredis]<9,>=5; extra == 'fleet'
Provides-Extra: fleet-pg
Requires-Dist: asyncpg<1,>=0.29; extra == 'fleet-pg'
Provides-Extra: google-adk
Requires-Dist: google-adk<3,>=1.0; extra == 'google-adk'
Provides-Extra: grpc
Requires-Dist: grpcio-tools<2,>=1.60; extra == 'grpc'
Requires-Dist: grpcio<2,>=1.60; extra == 'grpc'
Provides-Extra: langchain
Requires-Dist: langchain-core<2,>=0.2; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=1.28.1; extra == 'mcp'
Provides-Extra: metrics
Requires-Dist: prometheus-client<1,>=0.20; extra == 'metrics'
Requires-Dist: prometheus-fastapi-instrumentator<9,>=7; extra == 'metrics'
Provides-Extra: openai-agents
Requires-Dist: openai-agents<1,>=0.1; extra == 'openai-agents'
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.100; extra == 'server'
Requires-Dist: uvicorn<1,>=0.20; extra == 'server'
Description-Content-Type: text/markdown

# Fathom

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

[![PyPI](https://img.shields.io/pypi/v/fathom-rules.svg)](https://pypi.org/project/fathom-rules/)
[![Docs](https://img.shields.io/badge/docs-krakennet.github.io%2Ffathom-blue)](https://krakennet.github.io/fathom/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/KrakenNet/fathom/actions/workflows/ci.yml/badge.svg)](https://github.com/KrakenNet/fathom/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/pypi/dm/fathom-rules.svg)](https://pypi.org/project/fathom-rules/)
[![codecov](https://codecov.io/gh/KrakenNet/fathom/branch/main/graph/badge.svg)](https://codecov.io/gh/KrakenNet/fathom)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/E6Cf8WFDf)

> **Part of the [Kraken](https://github.com/KrakenNet) stack:** [**Fathom**](https://github.com/KrakenNet/fathom) (reasoning engine) · [Nautilus](https://github.com/KrakenNet/nautilus) (policy data broker) · [Stargraph](https://github.com/KrakenNet/stargraph) (agent-graph framework).

**Current version:** 0.11.0 <!-- x-release-please-version -->

**License:** MIT

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

**Package Manager:** uv

**Maintained by:** [Kraken Networks](https://github.com/KrakenNet)

---

## 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

```bash
uv add fathom-rules
```

## Quick Start

```python
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](docs/getting-started.md) 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](docs/how-to/policy-studio.md)

**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](docs/reference/planned-integrations.md).

## 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**

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

**As a REST sidecar**

```bash
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**

```bash
# 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**

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

## Documentation

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

Entry points:

- [Getting Started](docs/getting-started.md)
- [Tutorials](docs/tutorials/index.md)
- [How-to Guides](docs/how-to/index.md)
- [Concepts](docs/concepts/index.md)
- [Reference](docs/reference/index.md)
- [Configuration](docs/reference/configuration.md) — 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](https://github.com/krakenNet/bosun):** Agent governance built on Fathom (fleet analysis, compliance attestation)
- **[Nautilus](https://github.com/krakenNet/nautilus):** Intelligent data broker built on Fathom (multi-source routing, classification-aware scoping)
- **[Stargraph](https://github.com/KrakenNet/stargraph):** Workgraph, AI orchestration framework built on Fathom

## Development

```bash
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:

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines and [CHANGELOG.md](CHANGELOG.md) for release notes.

## Stability

Fathom is pre-1.0. [VERSIONING.md](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

<a href="https://star-history.com/#KrakenNet/fathom&Date">
  <img src="https://api.star-history.com/svg?repos=KrakenNet/fathom&type=Date" alt="Star History Chart" width="600">
</a>

## License

MIT — see [LICENSE](LICENSE) for details.

---

Maintained by [Kraken Networks](https://github.com/KrakenNet) · [krakennetworks.com](https://krakennetworks.com) · [krakn.ai](https://krakn.ai)
