Metadata-Version: 2.4
Name: fathom-rules
Version: 0.2.0
Summary: Deterministic reasoning runtime for AI agents, built on CLIPS via clipspy
Project-URL: Homepage, https://github.com/kraken-networks/fathom
Project-URL: Repository, https://github.com/kraken-networks/fathom
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.14
Requires-Dist: clipspy<1.1,>=1.0.6
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: asyncpg; extra == 'all'
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: grpcio-tools; extra == 'all'
Requires-Dist: grpcio>=1.60; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: prometheus-client; extra == 'all'
Requires-Dist: prometheus-fastapi-instrumentator; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'all'
Requires-Dist: redis[hiredis]; extra == 'all'
Requires-Dist: rich>=13; extra == 'all'
Requires-Dist: typer[all]>=0.12; extra == 'all'
Requires-Dist: uvicorn>=0.20; extra == 'all'
Provides-Extra: attestation
Requires-Dist: cryptography>=42.0; extra == 'attestation'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'attestation'
Provides-Extra: cli
Requires-Dist: rich>=13; extra == 'cli'
Requires-Dist: typer[all]>=0.12; extra == 'cli'
Provides-Extra: fleet
Requires-Dist: redis[hiredis]; extra == 'fleet'
Provides-Extra: fleet-pg
Requires-Dist: asyncpg; extra == 'fleet-pg'
Provides-Extra: grpc
Requires-Dist: grpcio-tools; extra == 'grpc'
Requires-Dist: grpcio>=1.60; extra == 'grpc'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: metrics
Requires-Dist: prometheus-client; extra == 'metrics'
Requires-Dist: prometheus-fastapi-instrumentator; extra == 'metrics'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: uvicorn>=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.

**Status:** Design Draft
**License:** MIT
**Language:** Python 3.14+
**Package Manager:** uv

---

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

## Quick Start

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

```python
from fathom import Engine

engine = Engine()
engine.load_templates("templates/")
engine.load_rules("rules/")

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 'secret' insufficient for 'top-secret' data"
print(result.duration_us)  # 47
```

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

**As a library:**
```python
from fathom import Engine
engine = Engine.from_rules("rules/")
result = engine.evaluate()
```

**As a sidecar:**
```bash
docker run -p 8080:8080 -v ./rules:/rules kraken/fathom:latest
curl -X POST localhost:8080/v1/evaluate -d '{"facts": [...], "ruleset": "access-control"}'
```

**As an MCP tool:**
```python
from fathom.integrations.mcp import FathomMCPServer
server = FathomMCPServer(engine)
server.serve()
```

## Rule Packs

Pre-built rule collections (planned):

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

## Performance Targets

| Operation | Target |
|-----------|--------|
| Single rule evaluation | < 100µs |
| 100-rule evaluation | < 500µs |
| Fact assertion | < 10µs |
| YAML compilation | < 50ms |

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

## Development

```bash
git clone <repo-url>
cd fathom
uv sync
uv run pytest
```

See [design.md](design.md) for the full specification and roadmap.

## License

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

---

Maintained by [Kraken Networks](https://github.com/kraken-networks)
