Metadata-Version: 2.4
Name: darkmatter-sdk
Version: 0.2.0
Summary: Replay, fork, and verify any AI workflow. Execution record for AI agent pipelines.
Home-page: https://darkmatterhub.ai
Author: Ben Gunvl
Author-email: hello@darkmatterhub.ai
Project-URL: Documentation, https://darkmatterhub.ai/docs
Project-URL: Source, https://github.com/bengunvl/darkmatter
Project-URL: Changelog, https://github.com/bengunvl/darkmatter/releases
Keywords: ai agents llm execution record replay fork verify lineage audit anthropic openai langgraph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1.0; extra == "langgraph"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: langgraph>=0.1.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# darkmatter

**Replay, fork, and verify any AI workflow.**

The execution record for AI agent pipelines. Works across any model, framework, or provider.

```bash
pip install darkmatter
darkmatter demo        # try it now â€” no signup required
```

## What it does

DarkMatter records every step of your AI pipeline as a cryptographically linked chain. You can then:

- **Replay** any workflow from root to tip, step by step
- **Fork** from any checkpoint to branch without losing the original
- **Verify** that a chain is intact and unmodified
- **Diff** two runs to see exactly what changed
- **Export** a portable proof artifact anyone can verify

Works with any model (Claude, GPT-4o, Gemini, local models) and any framework (LangGraph, LangChain, CrewAI, raw API calls).

## Quick start

```python
import darkmatter as dm
import os

os.environ["DARKMATTER_API_KEY"] = "dm_sk_..."  # get free key at darkmatterhub.ai/signup

# Commit agent output
ctx = dm.commit(
    to_agent_id="agent-writer-01",
    payload={
        "input":  "Analyze Q1 earnings",
        "output": {"summary": "APAC up 34%", "confidence": 0.94},
    },
    agent={"role": "researcher", "provider": "anthropic", "model": "claude-opus-4-6"},
)

# Chain commits by passing parent_id
ctx2 = dm.commit(
    to_agent_id="agent-reviewer-01",
    payload={"input": ctx["payload"]["output"], "output": "Approved."},
    parent_id=ctx["id"],
)

# Replay the full chain
replay = dm.replay(ctx2["id"])
print(f"{replay['totalSteps']} steps, chain intact: {replay['chainIntact']}")

# Verify integrity
result = dm.verify(ctx2["id"])
print(f"chain_intact: {result['chain_intact']}")
```

## LangGraph integration (one line)

```python
from langgraph.graph import StateGraph, END
from darkmatter.integrations.langgraph import DarkMatterTracer

# Your existing graph â€” unchanged
app = workflow.compile()

# Add DarkMatter â€” one line
app = DarkMatterTracer(app, agent_id="MY_AGENT_ID", to_agent_id="MY_AGENT_ID")

# Use exactly as before â€” every node auto-commits
result = app.invoke({"input": "Write a report"})
```

## Anthropic SDK integration

```python
import anthropic
from darkmatter.integrations.anthropic import dm_client

# Wrap your existing client â€” one line
client = dm_client(anthropic.Anthropic(), agent_id="agent-01", to_agent_id="agent-01")

# Use exactly as before â€” every call auto-commits
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Analyze Q1 earnings"}]
)
print(client.last_ctx_id)  # ctx_1234567890_abc123
```

## OpenAI SDK integration

```python
import openai
from darkmatter.integrations.openai import dm_client

client = dm_client(openai.OpenAI(), agent_id="agent-01", to_agent_id="agent-01")
response = client.chat.completions.create(model="gpt-4o", messages=[...])
print(client.last_ctx_id)
```

## Single agent / single developer

You do not need multiple agents. DarkMatter works for a single developer debugging their own pipeline:

```python
import darkmatter as dm

# Run your pipeline step by step
for i, step in enumerate(pipeline_steps):
    result = run_step(step)
    ctx = dm.commit(
        to_agent_id=MY_AGENT_ID,
        payload={"input": step, "output": result},
        parent_id=ctx["id"] if i > 0 else None,
    )

# Replay it
replay = dm.replay(ctx["id"])
for step in replay["replay"]:
    print(step["step"], step["payload"])
```

## Diff two runs

```python
# Run the same pipeline twice (or compare original vs fork)
d = dm.diff(run1_ctx_id, run2_ctx_id)
print(f"{d['changedSteps']} steps changed")
for step in d["steps"]:
    if step["diff"]["modelChanged"]:
        print(f"Step {step['step']}: {step['a']['model']} â†’ {step['b']['model']}")
```

## Search your history

```python
# Find all checkpoints from claude on a specific trace
results = dm.search(model="claude-opus-4-6", event="checkpoint", trace_id="trc_abc")
for ctx in results["results"]:
    print(ctx["id"], ctx["payload"]["output"])
```

## API reference

| Function | Description |
|---|---|
| `dm.commit(to_agent_id, payload, ...)` | Commit context, returns Context Passport |
| `dm.pull()` | Pull contexts addressed to this agent |
| `dm.replay(ctx_id)` | Replay full chain root â†’ tip |
| `dm.fork(ctx_id, ...)` | Fork from a checkpoint |
| `dm.verify(ctx_id)` | Verify chain integrity |
| `dm.export(ctx_id)` | Export portable proof artifact |
| `dm.search(q, model, ...)` | Search execution history |
| `dm.diff(ctx_id_a, ctx_id_b)` | Diff two chains step-by-step |
| `dm.me()` | Agent identity |

## Links

- [Documentation](https://darkmatterhub.ai/docs)
- [Live demo](https://darkmatterhub.ai/demo)
- [Get API key](https://darkmatterhub.ai/signup)
- [GitHub](https://github.com/bengunvl/darkmatter)
- [Context Passport spec](https://contextpassport.com)

## License

MIT
