cairns 0.2.0__tar.gz

cairns-0.2.0/.envrc

@@ -0,0 +1 @@
+use devenv

cairns-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+**/.devenv
+.pytest_cache
+.claude
+**/__pycache__/
+.cairn/
+.env

cairns-0.2.0/.import_linter_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Grimp.
+*

cairns-0.2.0/.import_linter_cache/6ff22d18cc797dcfbda9e438db40df94c9091ca4.data.json

@@ -0,0 +1 @@
+{"cairn.run.spans":[],"cairn.run.show":[["cairn.core",174,"from cairn.core import event_to_dict"],["cairn.run.gc",17,"from .gc import list_runs"],["cairn.core",16,"from cairn.core import Event"],["cairn.run.spans",18,"from .spans import SpanGraph"]],"cairn.tui.messages":[],"cairn.tui.app":[["cairn.core",21,"from cairn.core import CompositeSink, Handle, set_sink, set_store"],["cairn.tui.sinks",34,"from .sinks import TuiInteractionSink, TuiSink"],["cairn.interaction",22,"from cairn.interaction import set_interaction_sink"],["cairn.tui.render",33,"from .render import render_trace_text"],["cairn.core",574,"from cairn.core import reset_sink, reset_store"],["cairn.core",406,"from cairn.core import from_jsonable"],["cairn.tui.widgets",35,"from .widgets import ChoicePanel, ConfirmPanel"],["cairn.run.spans",24,"from cairn.run.spans import SpanGraph"],["cairn.interaction",575,"from cairn.interaction import reset_interaction_sink"],["cairn.run",23,"from cairn.run import RunInfo, RunManager, SymlinkTracker, list_runs"],["cairn.tui.messages",26,"from .messages import ("]],"cairn":[["cairn.run.gc",16,"from cairn.run import ("],["cairn.core",3,"from cairn.core import ("],["cairn.core.step",3,"from cairn.core import ("],["cairn.run",16,"from cairn.run import ("]],"cairn.cli":[["cairn.run",36,"from cairn.run import show_trace"],["cairn.tui",145,"from cairn.tui import browse"],["cairn.run",64,"from cairn.run import show_runs"],["cairn.run.gc",52,"from cairn.run import gc, list_runs"],["cairn.tui",128,"from cairn.tui import run_app"],["cairn.run",30,"from cairn.run import show_runs"],["cairn.run",149,"from cairn.run import show_runs"],["cairn.run",52,"from cairn.run import gc, list_runs"],["cairn.run",80,"from cairn.run import run as cairn_run"],["cairn.run",119,"from cairn.run import gc_outputs, list_runs, remove_run"],["cairn.run",43,"from cairn.run import show_output"]],"cairn.ext":[],"cairn.interaction":[["cairn.core.step",39,"from cairn.core import step"],["cairn.core.context",40,"from cairn.core.context import current_span"]],"cairn.core.hash":[["cairn.core.types",129,"from .types import StepInfo"]],"cairn.core.types":[["cairn.core.hash",16,"from .hash import compute_cairn_id, resolve_hashable"]],"cairn.tui.render":[["cairn.run.show",9,"from cairn.run.show import TRACE_RESERVED, format_cost"]],"cairn.core":[["cairn.core.step",8,"from .step import ("],["cairn.core.sink",45,"from .sink import CompositeSink, JSONLSink, event_to_dict"],["cairn.core.hash",30,"from .hash import ("],["cairn.core.store",46,"from .store import FileStore, MemoryStore, OverlayStore, Store, StoreStats"],["cairn.core.context",18,"from .context import ("],["cairn.core.serial",38,"from .serial import ("],["cairn.core.types",47,"from .types import CacheEntry, SpanMetrics, StepInfo, TaskSpan, TraceRecord"],["cairn.core.patterns",37,"from .patterns import rate_limited, replayable"]],"cairn.core.context":[["cairn.core.types",11,"from .types import TaskSpan"]],"cairn.core.lock":[],"cairn.tui":[["cairn.tui.app",18,"from .app import CairnApp"]],"cairn.core.step":[["cairn.core.types",20,"from .types import CacheEntry, SpanMetrics, StepInfo, TaskSpan, TraceRecord"],["cairn.core.store",12,"from .store import ("],["cairn.core.context",11,"from .context import current_span, emit_event, next_id"]],"cairn.core.testing":[["cairn.core",9,"from cairn.core import set_store"],["cairn.core.store",11,"from .store import MemoryStore"],["cairn.core.context",8,"from .context import Event, MemorySink, reset_id_counter, set_sink"],["cairn.core.context",131,"from .context import reset_sink"],["cairn.core.hash",10,"from .hash import clear_hash_funcs, set_hash_funcs"],["cairn.core.step",130,"from .step import reset_store"]],"cairn.tui.widgets":[],"cairn.tui.sinks":[["cairn.tui.messages",20,"from .messages import ("],["cairn.core",18,"from cairn.core import Event, event_to_dict"]],"cairn.run.gc":[["cairn.core.lock",15,"from cairn.core.lock import gc_exclusive as _gc_exclusive"]],"cairn.ext.claude":[["cairn",16,"from cairn import trace"]],"cairn.core.store":[["cairn.core.serial",20,"from .serial import from_jsonable, to_jsonable"],["cairn.core.types",21,"from .types import CacheEntry, TraceRecord"],["cairn.core.lock",19,"from .lock import store_shared"]],"cairn.run":[["cairn.core",175,"from cairn.core import reset_sink, reset_store  # noqa: PLC0415"],["cairn.run.gc",185,"from .gc import (  # noqa: E402"],["cairn.run.show",193,"from .show import show_output, show_runs, show_trace  # noqa: E402"],["cairn.run.spans",194,"from .spans import SpanGraph  # noqa: E402"],["cairn.core",12,"from cairn.core import Event, FileStore, Handle, JSONLSink, OverlayStore, set_sink, set_store"]],"cairn.core.serial":[],"cairn.core.patterns":[["cairn.core.step",10,"from .step import Handle, cached_output, cached_tracing, step, trace"],["cairn.core.types",11,"from .types import StepInfo, TraceRecord"]],"cairn.core.sink":[["cairn.core.context",10,"from .context import Event"]]}

cairns-0.2.0/.import_linter_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by Grimp.
+# For information about cache directory tags see https://bford.info/cachedir/

cairns-0.2.0/.import_linter_cache/cairn.meta.json

@@ -0,0 +1 @@
+{"cairn.core.patterns": 1776711829.4129565, "cairn.tui.widgets": 1776725754.021825, "cairn.ext": 1777061802.32637, "cairn.run": 1777065258.432119, "cairn.run.show": 1777065290.855728, "cairn.tui": 1776729888.950072, "cairn.tui.sinks": 1776729888.9504905, "cairn.interaction": 1776730680.4906645, "cairn.core": 1777065234.2434435, "cairn.tui.render": 1776729888.9503968, "cairn.core.step": 1777068889.3958, "cairn.cli": 1776729888.9499216, "cairn.core.sink": 1777066204.0551448, "cairn.core.types": 1777064789.6603053, "cairn.run.gc": 1777065279.6702857, "cairn.run.spans": 1777065135.7066474, "cairn.tui.app": 1777066213.3082044, "cairn.core.serial": 1777064703.2457192, "cairn.core.lock": 1777062187.6831, "cairn": 1776697640.5956903, "cairn.tui.messages": 1776729888.950324, "cairn.ext.claude": 1777062502.825604, "cairn.core.hash": 1777064796.0770473, "cairn.core.store": 1777068851.1281378, "cairn.core.context": 1777066220.2757235, "cairn.core.testing": 1776689957.1186948}

cairns-0.2.0/.import_linter_cache/cairns.meta.json

@@ -0,0 +1 @@
+{"cairns.run.spans": 1777908586.6772733, "cairns.core.serial": 1777908821.6975274, "cairns.run": 1777909145.351873, "cairns.ext.claude": 1777908738.108794, "cairns.core.runtime": 1777910918.4830177, "cairns.core.step": 1777910982.8763356, "cairns.tui": 1777910918.484366, "cairns.core.sink": 1777892323.3431523, "cairns.testing": 1777909069.6382208, "cairns.tui.widgets": 1776725754.021825, "cairns.core.lock": 1777910918.4838786, "cairns.patterns.semver": 1777911005.908118, "cairns.core.hash": 1777908821.7029088, "cairns.patterns": 1777908738.0626025, "cairns.core.types": 1777908236.6348233, "cairns.ext": 1777061802.32637, "cairns.core.store": 1777909027.1370761, "cairns.tui.app": 1777908738.0930882, "cairns": 1777908848.0384898, "cairns.cli": 1777911082.101685, "cairns.tui.messages": 1776729888.950324, "cairns.run.show": 1777909027.149721, "cairns.tui.render": 1777908738.0466282, "cairns.core.cairn": 1777910989.1823654, "cairns.interaction": 1777908738.1828606, "cairns.tui.sinks": 1777908738.0774064, "cairns.run.gc": 1777910918.4849072, "cairns.core": 1777910959.412853}

cairns-0.2.0/.import_linter_cache/ea33efcc55ca9faff44446ae7f31abced923d943.data.json

@@ -0,0 +1 @@
+{"cairns.tui.app":[["cairns.core",407,"from cairns.core import from_jsonable"],["cairns.tui.messages",27,"from .messages import ("],["cairns.run",24,"from cairns.run import _make_run_dir, _update_latest  # noqa: PLC2701"],["cairns.tui.widgets",36,"from .widgets import ChoicePanel, ConfirmPanel"],["cairns.run.spans",25,"from cairns.run.spans import SpanGraph"],["cairns.run",23,"from cairns.run import RunDirSink, RunInfo, list_runs"],["cairns.tui.render",34,"from .render import render_trace_text"],["cairns.core",21,"from cairns.core import CompositeSink, FileStore, Handle"],["cairns.tui.sinks",35,"from .sinks import TuiInteractionSink, TuiSink"],["cairns.core.runtime",22,"from cairns.core.runtime import Run"]],"cairns.core.step":[["cairns.core.runtime",11,"from .runtime import current_run, current_span, emit_event"],["cairns.core.cairn",672,"from cairns.core.cairn import Cairn  # noqa: PLC0415"],["cairns.core.types",19,"from .types import Record, SpanMetrics, StepInfo, TaskSpan, TraceRecord"],["cairns.core.store",12,"from .store import ("]],"cairns.run.spans":[],"cairns.patterns":[["cairns.core.types",11,"from cairns.core.types import StepInfo, TraceRecord"],["cairns.core.step",10,"from cairns.core.step import Handle, cached_output, cached_tracing, step, trace"]],"cairns.interaction":[["cairns.core.step",29,"from cairns.core import step"],["cairns.core.runtime",30,"from cairns.core.runtime import InteractionSink, current_run, current_span"]],"cairns.ext.claude":[["cairns",16,"from cairns import trace"]],"cairns.core.serial":[["cairns.core.runtime",44,"from .runtime import active_serializers  # noqa: PLC0415"]],"cairns.core.types":[["cairns.core.hash",16,"from .hash import compute_cairn_id, resolve_hashable"]],"cairns.patterns.semver":[["cairns.core",23,"from cairns.core import Cairn, Record"]],"cairns.core.store":[["cairns.core.lock",19,"from .lock import store_shared"],["cairns.core.serial",20,"from .serial import from_jsonable, to_jsonable"],["cairns.core.types",21,"from .types import Record, TraceRecord"]],"cairns.tui.widgets":[],"cairns.tui.messages":[],"cairns":[["cairns.core",3,"from cairns.core import ("],["cairns.core.step",3,"from cairns.core import ("],["cairns.run.gc",17,"from cairns.run import ("],["cairns.run",17,"from cairns.run import ("],["cairns.patterns",16,"from cairns.patterns import rate_limited, replayable"],["cairns.core.cairn",3,"from cairns.core import ("]],"cairns.core.lock":[],"cairns.run.show":[["cairns.core",174,"from cairns.core import event_to_dict"],["cairns.run.gc",17,"from .gc import list_runs"],["cairns.core",16,"from cairns.core import Event"],["cairns.run.spans",18,"from .spans import SpanGraph"]],"cairns.core":[["cairns.patterns",33,"from cairns.patterns import rate_limited, replayable"],["cairns.core.cairn",28,"from .cairn import Cairn, cairn  # noqa: F401"],["cairns.core.runtime",15,"from .runtime import ("],["cairns.core.sink",39,"from .sink import CompositeSink, JSONLSink, event_to_dict"],["cairns.core.store",40,"from .store import FileStore, MemoryStore, OverlayStore, Store, StoreStats"],["cairns.core.hash",29,"from .hash import ("],["cairns.core.serial",34,"from .serial import ("],["cairns.core.types",41,"from .types import Record, SpanMetrics, StepInfo, TaskSpan, TraceRecord"],["cairns.core.step",8,"from .step import ("]],"cairns.run.gc":[["cairns.core.lock",15,"from cairns.core.lock import gc_exclusive as _gc_exclusive"]],"cairns.ext":[],"cairns.core.sink":[["cairns.core.runtime",10,"from .runtime import Event"]],"cairns.tui.sinks":[["cairns.core",18,"from cairns.core import Event, event_to_dict"],["cairns.tui.messages",20,"from .messages import ("]],"cairns.run":[["cairns.core",11,"from cairns.core import Event, Handle, JSONLSink, OverlayStore"],["cairns.run.gc",246,"from .gc import (  # noqa: E402"],["cairns.core.runtime",12,"from cairns.core.runtime import ("],["cairns.run.show",254,"from .show import show_output, show_runs, show_trace  # noqa: E402"],["cairns.run.spans",255,"from .spans import SpanGraph  # noqa: E402"]],"cairns.core.cairn":[["cairns.core.store",25,"from .store import Store"],["cairns.core.runtime",21,"from .runtime import current_run, current_span"],["cairns.core.types",22,"from .types import Record"]],"cairns.tui.render":[["cairns.run.show",9,"from cairns.run.show import TRACE_RESERVED, format_cost"]],"cairns.testing":[["cairns.core.runtime",8,"from cairns.core.runtime import Runtime, Event, MemorySink, Run"],["cairns.core.store",9,"from cairns.core.store import MemoryStore"]],"cairns.core.hash":[["cairns.core.runtime",90,"from .runtime import active_hash_funcs  # noqa: PLC0415"],["cairns.core.types",143,"from .types import StepInfo"]],"cairns.tui":[["cairns.tui.app",18,"from .app import CairnsApp"]],"cairns.core.runtime":[["cairns.run",245,"from cairns.run import arun as _arun  # noqa: PLC0415"],["cairns.testing",259,"from cairns.testing import Harness  # noqa: PLC0415"],["cairns.core.hash",178,"from .hash import install_defaults as install_hash_defaults  # noqa: PLC0415"],["cairns.core.types",33,"from .types import TaskSpan"],["cairns.core.serial",179,"from .serial import install_defaults as install_serial_defaults  # noqa: PLC0415"],["cairns.core.store",170,"from .store import FileStore  # noqa: PLC0415"],["cairns.core.serial",36,"from .serial import Serializer"],["cairns.core.store",37,"from .store import Store"],["cairns.run",217,"from cairns.run import run as _execute  # noqa: PLC0415"]],"cairns.cli":[["cairns.run",80,"from cairns.run import run as cairn_run"],["cairns.run",30,"from cairns.run import show_runs"],["cairns.run",43,"from cairns.run import show_output"],["cairns.run",36,"from cairns.run import show_trace"],["cairns.run",149,"from cairns.run import show_runs"],["cairns.run",119,"from cairns.run import gc_outputs, list_runs, remove_run"],["cairns.run",52,"from cairns.run import gc, list_runs"],["cairns.tui",145,"from cairns.tui import browse"],["cairns.tui",128,"from cairns.tui import run_app"],["cairns.run",64,"from cairns.run import show_runs"],["cairns.run.gc",52,"from cairns.run import gc, list_runs"]]}

cairns-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathijs Henquet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cairns-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: cairns
+Version: 0.2.0
+Summary: Compute graph orchestration with caching and observability
+Project-URL: Homepage, https://github.com/mathijshenquet/cairns
+Project-URL: Repository, https://github.com/mathijshenquet/cairns
+Project-URL: Issues, https://github.com/mathijshenquet/cairns/issues
+Author-email: Mathijs Henquet <mathijs.henquet@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,async,caching,compute-graph,llm,observability,pipeline,tracing,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rich>=13.0; extra == 'dev'
+Requires-Dist: textual>=3.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: pydantic>=2.0; extra == 'full'
+Requires-Dist: rich>=13.0; extra == 'full'
+Requires-Dist: textual>=3.0; extra == 'full'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Provides-Extra: semver
+Requires-Dist: semver>=3.0; extra == 'semver'
+Provides-Extra: tui
+Requires-Dist: rich>=13.0; extra == 'tui'
+Requires-Dist: textual>=3.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mathijshenquet/cairns/main/docs/logo.jpg" alt="Cairn" width="600">
+</p>
+
+# Cairns
+
+**A microframework for compute graphs with caching, tracing, and replay.**
+
+Think *PyTorch for agent pipelines* — though nothing about it is agent-specific.
+You write ordinary async Python; a `@step` decorator turns each function into a
+tracked, and optionally cached node in a graph that emerges from execution instead of being
+declared up front.
+
+> **Alpha.** Public API names, the on-disk cache format, and the higher-order
+> wrappers may still change between minor versions. Pin a version if you
+> depend on it.
+
+## Why
+
+Declarative graph frameworks (LangGraph, CrewAI, Airflow-style DAGs) force you
+into their node/edge DSL. Cairn goes the other way: the graph **is** your code,
+the framework just instruments it. From that you get:
+
+- **Caching** keyed on `(function identity, body version, resolved args)` — change
+  one function, only its downstream re-executes.
+- **Tracing** — live, structured event log; a built-in TUI renders it.
+- **Resume** — a failed pipeline reruns from the last successful step.
+- **Replay** — cached runs can replay with original timing, indistinguishable
+  from a live execution.
+- **Human-in-the-loop** as a regular async step (`await_input(...)`).
+
+Works for LLM pipelines, scrapers, ETL, long-running research — anything that
+fits into mostly-pure async functions.
+
+## Install
+
+```sh
+pip install cairns[tui]        # TUI is worth having
+pip install cairns[full]       # TUI + pydantic hashing
+```
+
+Or with `uv`:
+
+```sh
+uv add cairns --extra tui
+```
+
+Requires Python 3.12+.
+
+## Hello world
+
+```python
+import asyncio
+from cairns import step, run, trace
+
+@step(memo=True)
+async def fetch(url: str) -> str:
+    trace("fetching", state="running")
+    await asyncio.sleep(0.2)       # pretend HTTP
+    return f"<html>{url}</html>"
+
+@step
+async def extract(html: str) -> int:
+    return len(html)
+
+@step
+async def pipeline(urls: list[str]) -> list[int]:
+    pages = [fetch(u) for u in urls]              # returns Handles; runs concurrently
+    return [await extract(p) for p in pages]      # pages are awaited inside extract
+
+run(pipeline, store_path=".cairns",
+    args=(["https://a", "https://b", "https://c"],))
+```
+
+Run it twice. The second run is instant — every `@step(memo=True)` result is
+looked up by cache key. Edit the body of `extract`, rerun: only `extract`
+re-executes, fetches are cache hits.
+
+## CLI
+
+```sh
+cairns examples/research_fake_llm.py        # run the pipeline, opens TUI if installed
+cairns examples/research_fake_llm.py slow   # run the `slow` entry point
+cairns examples/research_fake_llm.py -f     # clear this entry's cache, then run
+cairns                                      # interactive run browser over past runs
+cairns list                                 # flat list of runs
+cairns show [RUN_ID]                        # print a trace (latest if omitted)
+cairns gc [--before YYYY-MM-DD]             # garbage-collect old runs
+```
+
+Default store is `./.cairns/`. Override with `--store PATH` (or `-s`). Entry
+points default to a function named `main`; pass a second positional arg to
+pick another, e.g. `cairns script.py my_pipeline`.
+
+## Examples
+
+Each example runs standalone with `python examples/<name>.py`, or through the
+CLI with `cairns examples/<name>.py` for the TUI.
+
+| Example | What it shows |
+|---------|---------------|
+| [`scraper.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/scraper.py) | Fan-out + chain, non-AI, fully mocked. Good first look. |
+| [`failure_resume.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/failure_resume.py) | A step fails on item 3; rerun resumes from cache. |
+| [`research_fake_llm.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/research_fake_llm.py) | Fan-out across N subjects, retry loop, rate limiting, simulated 20% API failure rate. No API key needed. |
+| [`hitl.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/hitl.py) | `await_input` inside a step — TUI input widget, stdin fallback. |
+| [`research_haiku.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/research_haiku.py) + [`claude.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/claude.py) | Live research over real AI companies via the `claude` CLI (Haiku). Cached by ISO week — re-runs within the week are free. |
+
+## What you'll see
+
+With `cairns[tui]` installed, the CLI opens a live span tree: each `@step`
+invocation is a row, child steps indent, `trace(...)` calls attach as
+annotations, and `cost={...}` kwargs get summed up the tree. Failures colour
+red, running steps pulse, completed steps show wall time + own time (excluding
+waits on children).
+
+Without the TUI, the same events stream to `.cairns/runs/{entry}-{ts}/trace.jsonl`
+and you can read them with `cairns show`.
+
+## Docs
+
+- [`docs/motivation.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/motivation.md) — the problem and the analogy to PyTorch.
+- [`docs/design.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/design.md) — all primitives, event log, stores, plugin points.
+- [`docs/patterns.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/patterns.md) — comparison against Prefect, LangGraph, Temporal, Flyte, CrewAI across seven patterns.
+
+## Status
+
+Alpha, but the core works:
+
+- `@step`, `Handle`, `trace`, `cached_output/tracing`, `replayable`, `rate_limited`, `await_input` all shipped.
+- File-backed content-addressed store, JSONL trace sink, symlinked run layout, GC.
+- Live TUI for span-tree viewing.
+- 110 tests, covering core + hashing + disk + resume + GC + metrics + patterns.
+
+Possible future work: a web UI, distributed execution, distributed cache store.
+
+Feedback and breakage reports welcome via issues.

cairns-0.2.0/README.md

@@ -0,0 +1,136 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mathijshenquet/cairns/main/docs/logo.jpg" alt="Cairn" width="600">
+</p>
+
+# Cairns
+
+**A microframework for compute graphs with caching, tracing, and replay.**
+
+Think *PyTorch for agent pipelines* — though nothing about it is agent-specific.
+You write ordinary async Python; a `@step` decorator turns each function into a
+tracked, and optionally cached node in a graph that emerges from execution instead of being
+declared up front.
+
+> **Alpha.** Public API names, the on-disk cache format, and the higher-order
+> wrappers may still change between minor versions. Pin a version if you
+> depend on it.
+
+## Why
+
+Declarative graph frameworks (LangGraph, CrewAI, Airflow-style DAGs) force you
+into their node/edge DSL. Cairn goes the other way: the graph **is** your code,
+the framework just instruments it. From that you get:
+
+- **Caching** keyed on `(function identity, body version, resolved args)` — change
+  one function, only its downstream re-executes.
+- **Tracing** — live, structured event log; a built-in TUI renders it.
+- **Resume** — a failed pipeline reruns from the last successful step.
+- **Replay** — cached runs can replay with original timing, indistinguishable
+  from a live execution.
+- **Human-in-the-loop** as a regular async step (`await_input(...)`).
+
+Works for LLM pipelines, scrapers, ETL, long-running research — anything that
+fits into mostly-pure async functions.
+
+## Install
+
+```sh
+pip install cairns[tui]        # TUI is worth having
+pip install cairns[full]       # TUI + pydantic hashing
+```
+
+Or with `uv`:
+
+```sh
+uv add cairns --extra tui
+```
+
+Requires Python 3.12+.
+
+## Hello world
+
+```python
+import asyncio
+from cairns import step, run, trace
+
+@step(memo=True)
+async def fetch(url: str) -> str:
+    trace("fetching", state="running")
+    await asyncio.sleep(0.2)       # pretend HTTP
+    return f"<html>{url}</html>"
+
+@step
+async def extract(html: str) -> int:
+    return len(html)
+
+@step
+async def pipeline(urls: list[str]) -> list[int]:
+    pages = [fetch(u) for u in urls]              # returns Handles; runs concurrently
+    return [await extract(p) for p in pages]      # pages are awaited inside extract
+
+run(pipeline, store_path=".cairns",
+    args=(["https://a", "https://b", "https://c"],))
+```
+
+Run it twice. The second run is instant — every `@step(memo=True)` result is
+looked up by cache key. Edit the body of `extract`, rerun: only `extract`
+re-executes, fetches are cache hits.
+
+## CLI
+
+```sh
+cairns examples/research_fake_llm.py        # run the pipeline, opens TUI if installed
+cairns examples/research_fake_llm.py slow   # run the `slow` entry point
+cairns examples/research_fake_llm.py -f     # clear this entry's cache, then run
+cairns                                      # interactive run browser over past runs
+cairns list                                 # flat list of runs
+cairns show [RUN_ID]                        # print a trace (latest if omitted)
+cairns gc [--before YYYY-MM-DD]             # garbage-collect old runs
+```
+
+Default store is `./.cairns/`. Override with `--store PATH` (or `-s`). Entry
+points default to a function named `main`; pass a second positional arg to
+pick another, e.g. `cairns script.py my_pipeline`.
+
+## Examples
+
+Each example runs standalone with `python examples/<name>.py`, or through the
+CLI with `cairns examples/<name>.py` for the TUI.
+
+| Example | What it shows |
+|---------|---------------|
+| [`scraper.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/scraper.py) | Fan-out + chain, non-AI, fully mocked. Good first look. |
+| [`failure_resume.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/failure_resume.py) | A step fails on item 3; rerun resumes from cache. |
+| [`research_fake_llm.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/research_fake_llm.py) | Fan-out across N subjects, retry loop, rate limiting, simulated 20% API failure rate. No API key needed. |
+| [`hitl.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/hitl.py) | `await_input` inside a step — TUI input widget, stdin fallback. |
+| [`research_haiku.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/research_haiku.py) + [`claude.py`](https://github.com/mathijshenquet/cairns/blob/main/examples/claude.py) | Live research over real AI companies via the `claude` CLI (Haiku). Cached by ISO week — re-runs within the week are free. |
+
+## What you'll see
+
+With `cairns[tui]` installed, the CLI opens a live span tree: each `@step`
+invocation is a row, child steps indent, `trace(...)` calls attach as
+annotations, and `cost={...}` kwargs get summed up the tree. Failures colour
+red, running steps pulse, completed steps show wall time + own time (excluding
+waits on children).
+
+Without the TUI, the same events stream to `.cairns/runs/{entry}-{ts}/trace.jsonl`
+and you can read them with `cairns show`.
+
+## Docs
+
+- [`docs/motivation.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/motivation.md) — the problem and the analogy to PyTorch.
+- [`docs/design.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/design.md) — all primitives, event log, stores, plugin points.
+- [`docs/patterns.md`](https://github.com/mathijshenquet/cairns/blob/main/docs/patterns.md) — comparison against Prefect, LangGraph, Temporal, Flyte, CrewAI across seven patterns.
+
+## Status
+
+Alpha, but the core works:
+
+- `@step`, `Handle`, `trace`, `cached_output/tracing`, `replayable`, `rate_limited`, `await_input` all shipped.
+- File-backed content-addressed store, JSONL trace sink, symlinked run layout, GC.
+- Live TUI for span-tree viewing.
+- 110 tests, covering core + hashing + disk + resume + GC + metrics + patterns.
+
+Possible future work: a web UI, distributed execution, distributed cache store.
+
+Feedback and breakage reports welcome via issues.

cairns-0.2.0/Taskfile.yaml

@@ -0,0 +1,34 @@
+version: "3"
+
+dotenv: [".env"]
+
+tasks:
+  build:
+    desc: Build sdist + wheel into dist/
+    cmds:
+      - rm -rf dist/
+      - uv build
+
+  check:
+    desc: Validate built artifacts (twine check)
+    deps: [build]
+    cmds:
+      - uvx twine check dist/*
+
+  publish:
+    desc: Publish to PyPI. Reads $PYPI_TOKEN from env (loaded from .env via devenv).
+    deps: [check]
+    preconditions:
+      - sh: 'test -n "$PYPI_TOKEN"'
+        msg: "PYPI_TOKEN is not set. Add it to .env (devenv auto-loads dotenv)."
+    cmds:
+      - UV_PUBLISH_TOKEN="$PYPI_TOKEN" uv publish
+
+  publish:test:
+    desc: Publish to TestPyPI. Reads $PYPI_TEST_TOKEN (or $PYPI_TOKEN as fallback).
+    deps: [check]
+    preconditions:
+      - sh: 'test -n "$PYPI_TEST_TOKEN" -o -n "$PYPI_TOKEN"'
+        msg: "Set PYPI_TEST_TOKEN (or PYPI_TOKEN) in .env."
+    cmds:
+      - UV_PUBLISH_TOKEN="${PYPI_TEST_TOKEN:-$PYPI_TOKEN}" uv publish --publish-url https://test.pypi.org/legacy/

cairns-0.2.0/devenv.lock

@@ -0,0 +1,103 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1776718099,
+        "narHash": "sha256-JAR6x8Au4xxk6X7ijhlYETQg0F0OS0ihZ5ARiguDclc=",
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "034b677ee035a29a077ecbaadfb2908719272919",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1767039857,
+        "narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "inputs": {
+        "nixpkgs-src": "nixpkgs-src"
+      },
+      "locked": {
+        "lastModified": 1776348333,
+        "narHash": "sha256-ZyrYhlLGGuN5ieW7pE65meJJYnNz5el9vJtGBEJyDMQ=",
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "efff47329167854ce48541c7ef731bf120753c7e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-python": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1774026014,
+        "narHash": "sha256-UBBQYhyAKayDCi6iCIKShQXWRvwyj5omLPOuSeVjtOY=",
+        "owner": "cachix",
+        "repo": "nixpkgs-python",
+        "rev": "8b6d4103312761d4144b7bf9aebcc2f394b7e325",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "nixpkgs-python",
+        "type": "github"
+      }
+    },
+    "nixpkgs-src": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1775888245,
+        "narHash": "sha256-nwASzrRDD1JBEu/o8ekKYEXm/oJW6EMCzCRdrwcLe90=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "13043924aaa7375ce482ebe2494338e058282925",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-python": "nixpkgs-python"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

cairns-0.2.0/devenv.nix

@@ -0,0 +1,21 @@
+{ pkgs, config, ... }:
+
+{
+  dotenv.enable = true;
+
+  languages.python = {
+    enable = true;
+    uv = {
+      enable = true;
+      sync.enable = true;
+    };
+  };
+
+  packages = [
+    pkgs.pyright
+  ];
+
+  enterShell = ''
+    export PATH="${config.devenv.root}/.devenv/state/venv/bin:$PATH"
+  '';
+}

cairns-0.2.0/devenv.yaml

@@ -0,0 +1,6 @@
+inputs:
+  nixpkgs-python:
+    url: github:cachix/nixpkgs-python
+    inputs:
+      nixpkgs:
+        follows: nixpkgs