Metadata-Version: 2.4
Name: nautilus-rkm
Version: 0.1.4
Summary: Nautilus data broker + reasoning engine: intent-aware scoped query execution, multi-agent handoffs, LLM intent analysis, and forensic escalation via Fathom rules
Author: se-jo-ma
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/KrakenNet/nautilus
Project-URL: Repository, https://github.com/KrakenNet/nautilus
Project-URL: Documentation, https://nautilus.krakn.ai
Project-URL: Changelog, https://github.com/KrakenNet/nautilus/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/KrakenNet/nautilus/issues
Keywords: fathom,policy,broker,security,scope,clips,ai-agent,data-broker,routing,audit,attestation,compliance,nist,hipaa,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Framework :: FastAPI
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fathom-rules>=0.3.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: pgvector>=0.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyjwt>=2.12.1
Requires-Dist: cryptography>=46.0.7
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: httpx>=0.27
Requires-Dist: elasticsearch<10,>=8
Requires-Dist: neo4j>=5
Requires-Dist: mcp>=1.12
Requires-Dist: sse-starlette>=2.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: jinja2>=3.1
Requires-Dist: influxdb-client>=1.40
Requires-Dist: aiobotocore>=2.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: pyright>=1.1.370; extra == "dev"
Requires-Dist: pip-licenses>=5.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: pytest-recording>=0.13; extra == "dev"
Requires-Dist: testcontainers[elasticsearch,neo4j]>=4.0; extra == "dev"
Requires-Dist: locust>=2.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Requires-Dist: copier>=9.0; extra == "dev"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
Requires-Dist: prometheus-client>=0.20; extra == "otel"
Provides-Extra: llm-anthropic
Requires-Dist: anthropic>=0.40; extra == "llm-anthropic"
Provides-Extra: llm-openai
Requires-Dist: openai>=1.50; extra == "llm-openai"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: mike>=2.1; extra == "docs"
Dynamic: license-file

# Nautilus

> Policy-first data broker for AI agents. One call plans, routes, enforces, attests, and audits.

[![PyPI](https://img.shields.io/pypi/v/nautilus-rkm.svg)](https://pypi.org/project/nautilus-rkm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/KrakenNet/nautilus/actions/workflows/ci.yml/badge.svg)](https://github.com/KrakenNet/nautilus/actions/workflows/ci.yml)
[![Docs](https://github.com/KrakenNet/nautilus/actions/workflows/docs-deploy.yml/badge.svg)](https://krakennet.github.io/nautilus/)

**Current version:** 0.1.3
**License:** MIT
**Language:** Python 3.13+
**Package Manager:** uv
**Maintained by:** [KrakenNet](https://github.com/KrakenNet)

---

## Why Nautilus?

Every AI agent framework gives agents direct access to data. For most tasks, that's fine.

For some tasks, unchecked access is unacceptable:

- **Policy routing** — "Which databases should this query hit?" can't be the agent's choice.
- **Scope enforcement** — "What rows is this agent allowed to see?" needs provable constraints.
- **Audit** — "What data did this agent touch, and why?" requires a tamper-evident trail.
- **Attestation** — "Can we prove this routing decision happened?" needs a signed token.

Nautilus provides **deterministic, policy-first data brokering** using Fathom — a CLIPS-based expert system — to route, scope, and attest every request.

## Install

```bash
uv add nautilus-rkm
```

## Quick Start

```python
from nautilus import Broker

broker = Broker.from_config("nautilus.yaml")
try:
    response = broker.request(
        "agent-alpha",
        "Find vulnerabilities for CVE-2026-1234",
        {"clearance": "unclassified", "purpose": "threat-analysis", "session_id": "s1"},
    )
    print(response.data)                # {"main-db": [...]}
    print(response.sources_queried)     # ["main-db"]
    print(response.sources_denied)      # ["classified-db"]
    print(response.attestation_token)   # signed JWS
    print(response.duration_ms)         # 47
finally:
    broker.close()
```

See the [Getting Started guide](https://krakennet.github.io/nautilus//getting-started/) for a full walkthrough.

## What Ships Today

**Core runtime**
- `Broker` facade with sync/async APIs (`request`, `arequest`, `from_config`, `afrom_config`)
- Fathom-based policy router for intent-aware source selection and scope enforcement
- Per-source scope constraints (WHERE-clause fragments) with injection-safe field validation
- Ed25519 JWS attestation service for signed routing decisions
- JSONL audit sink with per-request, append-only entries (fsync'd)
- Pattern-matching and LLM-based intent analysis (Anthropic, OpenAI)
- Cross-agent handoff reasoning with session-backed escalation detection

**Adapters (8 built-in)**
- PostgreSQL, PgVector, Elasticsearch, Neo4j, REST, ServiceNow, InfluxDB, S3
- Pluggable via entry points and the [Adapter SDK](https://krakennet.github.io/nautilus//reference/adapter-sdk/)

**Transports**
- FastAPI REST server (`POST /v1/request`, health/readiness probes)
- MCP transport (stdio and HTTP modes)
- CLI: `nautilus serve`, `nautilus health`, `nautilus version`

**Rule packs**
- `data-routing-nist` — NIST clearance/classification routing rules
- `data-routing-hipaa` — HIPAA-compliant routing rules

## What You Get Per Request

| Step | What happens |
|------|-------------|
| **Intent analysis** | Classify intent into data types, entities, temporal scope, sensitivity |
| **Policy routing** | Fathom evaluates `(clearance, purpose, source)` — route, scope, or deny |
| **Adapter fan-out** | Routed sources execute concurrently with per-adapter error isolation |
| **Attestation** | Ed25519 JWS signed over routing decision, bound to `request_id` |
| **Audit** | JSONL entry appended per request — success, denial, or error |

## Key Differentiator: Session-Aware Routing

Unlike stateless policy engines, Nautilus maintains working memory across requests within a session:

- **Cumulative exposure** — "This agent accessed PII from 3 sources — deny the 4th."
- **Cross-agent handoffs** — "Agent A is passing `secret` data to Agent B who has `unclassified` clearance — deny."
- **Escalation detection** — "Anomalous access pattern detected — escalate for forensic review."

## Integration Shapes

**As a library**
```python
from nautilus import Broker
broker = Broker.from_config("nautilus.yaml")
response = broker.request("agent-id", "intent", context)
```

**As a REST sidecar**
```bash
nautilus serve --config nautilus.yaml --transport rest --bind 0.0.0.0:8000
curl -H "X-API-Key: $KEY" -X POST localhost:8000/v1/request \
  -d '{"agent_id": "agent-alpha", "intent": "...", "context": {...}}'
```

**As an MCP server**
```bash
nautilus serve --config nautilus.yaml --transport mcp
```

**Air-gapped mode**
```bash
nautilus serve --config nautilus.yaml --air-gapped
```

## Configuration

A `nautilus.yaml` declares sources, rules, analysis, audit, and attestation:

```yaml
sources:
  - id: main-db
    adapter: postgres
    dsn: ${DATABASE_URL}
    classification: confidential
    data_types: [users, orders]

rules:
  paths: [./rules/]

attestation:
  enabled: true

audit:
  sink: file
  path: ./audit.jsonl
```

## Documentation

Full documentation is available at [nautilus.krakn.ai](https://krakennet.github.io/nautilus/).

- [Getting Started](https://krakennet.github.io/nautilus//getting-started/)
- [Concepts](https://krakennet.github.io/nautilus//concepts/)
- [How-to Guides](https://krakennet.github.io/nautilus//how-to/)
- [Reference](https://krakennet.github.io/nautilus//reference/)

## Related Projects

- **[Fathom](https://github.com/KrakenNet/fathom)** — Deterministic reasoning runtime that powers Nautilus routing
- **Bosun** — Agent governance built on Fathom (fleet analysis, compliance attestation)

## Development

```bash
git clone https://github.com/KrakenNet/nautilus.git
cd nautilus
uv sync
uv run pytest -m unit            # fast suite, no containers
uv run pytest -m integration     # full e2e, boots PostgreSQL via testcontainers
uv run ruff check && uv run ruff format --check && uv run pyright
uv run mkdocs serve              # docs preview
```

See [CHANGELOG.md](CHANGELOG.md) for release notes.

## Contributing

We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request. All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## Security

To report a security vulnerability, please see our [Security Policy](SECURITY.md). Do not open a public issue for security concerns.

## License

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