Metadata-Version: 2.5
Name: cairndev
Version: 0.1.3
Summary: A governed control plane for AI and ML work: pipelines that fine-tune, evaluate, compress and serve models, with approval, policy, budget and lineage on every step
Project-URL: Homepage, https://cairndev.sh
Project-URL: Documentation, https://docs.cairndev.sh
Project-URL: Source, https://github.com/cairndev-sh/cairn
Project-URL: Issues, https://github.com/cairndev-sh/cairn/issues
Author: cairn maintainers
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: cairn-client
Requires-Dist: fastapi[standard]>=0.115.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: jmespath>=1.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-mcp-adapters>=0.2.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: langgraph>=0.4.0
Requires-Dist: litellm>=1.50.0
Requires-Dist: opentelemetry-instrumentation-logging
Requires-Dist: opentelemetry-sdk==1.41.1
Requires-Dist: packaging>=23.0
Requires-Dist: pwdlib[argon2]>=0.2.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: referencing>=0.37.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: tomlkit>=0.13.0
Requires-Dist: typer>=0.12.0
Provides-Extra: auth
Requires-Dist: pwdlib[argon2]>=0.2.0; extra == 'auth'
Provides-Extra: dataflow-engine
Requires-Dist: duckdb>=1.0; extra == 'dataflow-engine'
Requires-Dist: polars>=1.0; extra == 'dataflow-engine'
Requires-Dist: pyarrow>=15; extra == 'dataflow-engine'
Provides-Extra: dev
Requires-Dist: blockbuster<1.6,>=1.5.20; extra == 'dev'
Requires-Dist: deepeval>=1.5.0; extra == 'dev'
Requires-Dist: httpx>=0.28.0; extra == 'dev'
Requires-Dist: langgraph-cli[inmem]>=0.1.50; extra == 'dev'
Requires-Dist: moto>=5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: hello
Requires-Dist: cairn-pack-hello[all]; extra == 'hello'
Provides-Extra: infisical
Requires-Dist: infisicalsdk>=1.0.0; extra == 'infisical'
Provides-Extra: kernel
Requires-Dist: boto3>=1.34.0; extra == 'kernel'
Requires-Dist: jmespath>=1.0; extra == 'kernel'
Requires-Dist: jsonschema>=4.26.0; extra == 'kernel'
Requires-Dist: pydantic-settings>=2.6.0; extra == 'kernel'
Requires-Dist: pydantic>=2.7; extra == 'kernel'
Requires-Dist: pyyaml>=6.0; extra == 'kernel'
Provides-Extra: metaflow
Requires-Dist: cairn-operator-dataflow-metaflow; extra == 'metaflow'
Requires-Dist: metaflow>=2.12; extra == 'metaflow'
Provides-Extra: nats
Requires-Dist: nats-py>=2.6.0; extra == 'nats'
Provides-Extra: oauth
Requires-Dist: authlib>=1.3.0; extra == 'oauth'
Provides-Extra: optuna
Requires-Dist: optuna>=4.0; extra == 'optuna'
Provides-Extra: pii
Requires-Dist: presidio-analyzer>=2.2; extra == 'pii'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'pii'
Provides-Extra: rag
Requires-Dist: fastembed>=0.3.0; extra == 'rag'
Requires-Dist: google-genai>=1.0.0; extra == 'rag'
Requires-Dist: llama-cloud>=0.1.0; extra == 'rag'
Requires-Dist: llama-index-core>=0.12.0; extra == 'rag'
Requires-Dist: onnxruntime<=1.20.1; (platform_system == 'Darwin' and platform_machine == 'x86_64') and extra == 'rag'
Requires-Dist: trafilatura>=2.0.0; extra == 'rag'
Provides-Extra: rag-pgvector
Requires-Dist: asyncpg>=0.29.0; extra == 'rag-pgvector'
Requires-Dist: pgvector>=0.3.0; extra == 'rag-pgvector'
Provides-Extra: rag-pinecone
Requires-Dist: pinecone-client>=3.0.0; extra == 'rag-pinecone'
Provides-Extra: rag-qdrant
Requires-Dist: qdrant-client>=1.9.0; extra == 'rag-qdrant'
Provides-Extra: rag-sqlite-vec
Requires-Dist: sqlite-vec>=0.1.0; extra == 'rag-sqlite-vec'
Provides-Extra: rerank-cohere
Requires-Dist: cohere>=5.0; extra == 'rerank-cohere'
Provides-Extra: rerank-cross-encoder
Requires-Dist: sentence-transformers>=3.0; extra == 'rerank-cross-encoder'
Provides-Extra: runtime-dbos
Requires-Dist: dbos>=2.0; extra == 'runtime-dbos'
Provides-Extra: runtime-postgres
Requires-Dist: langgraph-checkpoint-postgres>=3.0.0; extra == 'runtime-postgres'
Provides-Extra: runtime-sqlite
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0; extra == 'runtime-sqlite'
Provides-Extra: runtime-temporal
Requires-Dist: temporalio[langgraph]>=1.28.0; extra == 'runtime-temporal'
Provides-Extra: skypilot
Requires-Dist: cairn-operator-dataflow-skypilot; extra == 'skypilot'
Requires-Dist: skypilot[aws,kubernetes,runpod,ssh,vast]>=0.13; extra == 'skypilot'
Provides-Extra: ssh
Requires-Dist: asyncssh>=2.14; extra == 'ssh'
Provides-Extra: storage-postgres
Requires-Dist: asyncpg>=0.29.0; extra == 'storage-postgres'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'telemetry'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'telemetry'
Provides-Extra: train
Requires-Dist: datasets<4.4,>=4.3; extra == 'train'
Requires-Dist: peft<0.21,>=0.20; extra == 'train'
Requires-Dist: torch<2.12,>=2.11; extra == 'train'
Requires-Dist: transformers<5.6,>=5.5; extra == 'train'
Description-Content-Type: text/markdown

<p align="center">
  <img src="./assets/logo.svg" alt="cairn" width="88">
</p>

<h1 align="center">cairn</h1>

<p align="center">
  <b>An open-source control plane for governed ModelOps.</b><br>
  Fine-tune, evaluate, promote, and serve models as single governed commands —
  cost-capped before the GPU spins up, policy-gated, and audited end to end.
</p>

<p align="center">
  <a href="https://docs.cairndev.sh"><img alt="Docs" src="https://img.shields.io/badge/docs-cairndev.sh-3b82f6"></a>
  <a href="https://cairndev.sh"><img alt="Website" src="https://img.shields.io/badge/website-cairndev.sh-111827"></a>
  <img alt="Python" src="https://img.shields.io/badge/python-3.12%2B-3776ab">
  <img alt="Status" src="https://img.shields.io/badge/status-early%20access-f59e0b">
</p>

<p align="center">
  <a href="https://docs.cairndev.sh">Docs</a> ·
  <a href="https://docs.cairndev.sh/installation/">Install</a> ·
  <a href="https://docs.cairndev.sh/modelops/">ModelOps lifecycle</a> ·
  <a href="https://docs.cairndev.sh/governance/">Governance</a> ·
  <a href="https://cairndev.sh">Waitlist</a>
</p>

---

## What is cairn?

cairn runs the work behind AI as **governed commands**. You declare an
outcome — gate a dataset, fine-tune a model, evaluate it against a baseline,
promote it, serve it — and cairn drives the tools underneath, enforces the
guardrails, and records exactly what ran.

The engine is **domain-neutral**. Everything that knows about a *domain* lives
in a **pack**; everything that touches a *tool* is an **operator**. The engine
never imports a pack — that one-way dependency is what lets the same machinery
run fine-tuning, dataset checks, model evaluation, or incident response, and
lets any operator inherit the budget, policy gate, and audit for free.

cairn is **open source** (Apache 2.0) and **self-hosted by default**: your
keys, your GPUs, your logs — nothing leaves your perimeter. A **managed
cloud** is in private beta for teams who would rather not run it themselves;
the engine is the same either way.

## Why governed?

This is what separates cairn from a bare agent loop or a black-box tool — the
work runs behind deterministic guardrails you can inspect afterward:

- **Hard budget** — every run accrues cost in a scope; over the cap it raises
  `BudgetExceeded`, so a fine-tune can't quietly overspend.
- **Policy + human approval** — proposed actions pass declarative policy rules
  before any executor runs; high-risk ones (promote a model, destroy a
  resource) pause for a human and resume durably from a checkpoint.
- **Reproducible runs** — every run stores its validated inputs, a content-
  addressed schema hash, and the exact operators it resolved to. Replay any run;
  explain any result.
- **Tamper-evident audit** — every model call, tool call, and approval lands in
  a hash-chained, append-only log: what ran, what it cost, who approved it.
- **Citation validation** — for synthesized answers, every identifier the model
  cites is exact-string-matched against its context; unmatched citations are
  stripped.

## Quickstart

The engine ships as the `cairndev` distribution (import name `cairn`). The `cairndev` wheel
carries the builtin operator packs (14) and the core contracts (13); their sources live under
`packages/` in this repository. The public release is five wheels: `cairndev`, `cairn-client`,
the optional Metaflow and SkyPilot engines, and the example pack `cairn-pack-hello`.

```bash
git clone https://github.com/cairndev-sh/cairn && cd cairn
uv sync --extra dev
uv run cairn --help
```

A domain pack is a data wheel the engine discovers through an entry point; the example
pack shows the shape, and a governed run is a declared pipeline:

```bash
CAIRN_PACK_PATH=examples/hello-cairn uv run cairn pipeline ls
CAIRN_PACK_PATH=examples/hello-cairn uv run cairn pipeline explain hello-cairn/profile-and-publish
```

Those are the commands the public CI job runs on every change. The container image is
built from `Dockerfile.engine`, the Helm chart lives under `deploy/helm/cairn`, and the
optional extras are `auth`, `dataflow-engine`, `dev`, `hello`, `infisical`, `kernel`, `metaflow`, `nats`, `oauth`, `optuna`, `pii`, `rag`, `rag-pgvector`, `rag-pinecone`, `rag-qdrant`, `rag-sqlite-vec`, `rerank-cohere`, `rerank-cross-encoder`, `runtime-dbos`, `runtime-postgres`, `runtime-sqlite`, `runtime-temporal`, `skypilot`, `ssh`, `storage-postgres`, `telemetry`, `train`.
Full setup: [Installation](https://docs.cairndev.sh/installation/) ·
[CLI reference](https://docs.cairndev.sh/reference/cli/).

## The ModelOps lifecycle

Each stage is a normal governed run; chained together they form one auditable
spine — as a template's subgraphs, or as an explicit
[pipeline](https://docs.cairndev.sh/pipelines/).

```mermaid
flowchart LR
  D[Gate dataset] --> P[Prep · scrub · split]
  P --> T[Train · local or remote GPU]
  T --> E[Evaluate · deterministic gates]
  E --> H{{Human approval}}
  H --> R[Register · MLflow]
  R --> S[Serve · vLLM]
```

Deterministic gates decide pass/fail; LLM judges are advisory and off by
default. Promotion pauses for a human. Read the walkthrough in the
[ModelOps docs](https://docs.cairndev.sh/modelops/).

## One engine, many surfaces

The same governed core is driven from two places in this repository:

- **CLI** — the full control surface: run, preflight, replay, approve, deploy.
  → [CLI reference](https://docs.cairndev.sh/reference/cli/)
- **HTTP + SSE API** — every control-plane action is an endpoint, including live
  run streaming. → [HTTP API](https://docs.cairndev.sh/reference/http-api/)

## Documentation

| | |
|---|---|
| [Overview](https://docs.cairndev.sh/) | What cairn is and the governance thesis |
| [Architecture](https://docs.cairndev.sh/architecture/) | Engine, packs, profiles, request lifecycle |
| [Packs](https://docs.cairndev.sh/concepts/packs/) · [Operators](https://docs.cairndev.sh/concepts/operators/) | The pack contract and the operator contract |
| [Governance](https://docs.cairndev.sh/governance/) | Policies, HITL gates, budget, audit |
| [Pipelines](https://docs.cairndev.sh/pipelines/) | Chain governed workflows with gates and events |
| [Deployment](https://docs.cairndev.sh/deployment/) | The compose stack: one `.env`, profile toggles |
| [Operators catalog](https://docs.cairndev.sh/reference/operators/) | Every shipped operator, by domain |

## Status & license

cairn is in **early access** and under active development. The API and command
surface may still change between releases; see [`CHANGELOG.md`](./CHANGELOG.md).

Licensed under the **Apache License 2.0** — see [`LICENSE`](./LICENSE).
Contributions are welcome: read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first.
Interested in the managed cloud or a say in what ships next?
**[Join the waitlist](https://cairndev.sh).**
