Metadata-Version: 2.4
Name: swarm-at-sdk
Version: 0.6.1
Summary: Git-native settlement protocol for AI agent workflows
Project-URL: Homepage, https://swarm.at
Project-URL: Documentation, https://swarm.at/SPEC.html
Project-URL: Public Ledger, https://github.com/Mediaeater/swarm-at-ledger
Author-email: Mediaeater <m@swarm.at>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,coordination,ledger,settlement,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: click>=8.0; extra == 'all'
Requires-Dist: crewai>=0.30; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: haystack-ai>=2.0; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: openai-agents>=0.1; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: pyautogen>=0.2; extra == 'all'
Requires-Dist: pyjwt>=2.8; extra == 'all'
Requires-Dist: slowapi>=0.1.9; extra == 'all'
Requires-Dist: starlette>=0.27; extra == 'all'
Requires-Dist: strands-agents>=0.1; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == 'autogen'
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: haystack
Requires-Dist: haystack-ai>=2.0; extra == 'haystack'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: pyjwt>=2.8; extra == 'server'
Requires-Dist: slowapi>=0.1.9; extra == 'server'
Requires-Dist: starlette>=0.27; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'server'
Provides-Extra: strands
Requires-Dist: strands-agents>=0.1; extra == 'strands'
Description-Content-Type: text/markdown

# swarm.at

Settlement protocol for AI agent workflows. Every agent action commits to a hash-chained, tamper-evident ledger backed by git.

<!-- mcp-name: io.github.Mediaeater/swarm-at -->

## Install

```bash
pip install swarm-at-sdk
```

With framework adapters:

```bash
pip install swarm-at-sdk[langgraph]   # LangGraph
pip install swarm-at-sdk[autogen]     # AutoGen
pip install swarm-at-sdk[crewai]      # CrewAI
pip install swarm-at-sdk[openai]      # OpenAI Assistants
pip install swarm-at-sdk[all]         # Everything
```

## Quick Start

One-liner settlement for any agent:

```python
from swarm_at import settle

result = settle(agent="my-agent", task="research", data={"findings": "..."})
assert result.status.value == "SETTLED"
```

Full control with `SettlementContext`:

```python
from swarm_at import SettlementContext

ctx = SettlementContext()  # local engine + ledger
r1 = ctx.settle(agent="agent-a", task="step-1")
r2 = ctx.settle(agent="agent-a", task="step-2")  # auto-chains hashes
```

Point at a remote API:

```bash
export SWARM_API_URL=https://api.swarm.at
export SWARM_API_KEY=sk-...
```

```python
from swarm_at import settle
settle(agent="remote-agent", task="classify")  # uses HTTP
```

## Settlement Tiers

Start in sandbox, move to production when ready.

| Tier | Behavior |
|------|----------|
| `SANDBOX` | Log-only. No ledger writes. Returns synthetic hashes. Safe to experiment. |
| `STAGING` | Writes to ledger but skips chain enforcement. Good for integration testing. |
| `PRODUCTION` | Full verification: hash-chain integrity, confidence thresholds, shadow audits. |

```bash
export SWARM_TIER=sandbox  # or staging, production (default)
```

## Framework Adapters

Drop-in settlement for the major agent frameworks. No framework imports required.

**LangGraph:**
```python
from swarm_at.adapters.langgraph import SwarmNodeWrapper

wrapper = SwarmNodeWrapper(agent="research-agent")

@wrapper.wrap
def research_node(state):
    return {"findings": "..."}
```

**AutoGen:**
```python
from swarm_at.adapters.autogen import SwarmReplyCallback

callback = SwarmReplyCallback()
agent.register_reply([autogen.Agent], callback.on_reply)
```

**CrewAI:**
```python
from swarm_at.adapters.crewai import SwarmTaskCallback

callback = SwarmTaskCallback()
crew = Crew(agents=[...], tasks=[...], task_callback=callback.on_task_complete)
```

**OpenAI Assistants:**
```python
from swarm_at.adapters.openai_assistants import SwarmRunHandler

handler = SwarmRunHandler(assistant_id="asst_abc123")
handler.settle_run(run, messages)
```

## Authorship Provenance

Need to prove a human was in creative control when AI tools were involved? `WritingSession` records every decision to the settlement ledger and produces a verifiable provenance report — implementing the [Human-AI Agency Spectrum](https://narrative.new) framework (Ghuneim, 2026).

```python
from swarm_at import WritingSession
from swarm_at.authorship import CreativePhase

session = WritingSession(writer="jane-doe", tool="claude-sonnet-4-5")

# Human creative decisions (L4-L5 agency)
session.direct(action="premise", chose="noir detective", phase=CreativePhase.CONCEPT)

# AI-assisted drafting (L1-L3 agency)
session.prompt(text="Write the opening scene", phase=CreativePhase.SCENE)
session.generate(output_hash="<sha256-of-output>", model="claude-sonnet-4-5")

# Human edits to AI output
session.revise(description="Rewrote opening, cut 40%", kept_ratio=0.35)

# Verifiable provenance report
report = session.report()
print(report.work_agency)       # 0.92 (weighted phase score, 0.0-1.0)
print(report.safe_harbor)       # True (>= 0.90 threshold)
print(report.chain_verified)    # True (hash-chain intact)
print(report.to_text())         # Human-readable report for legal/editorial review
```

The report maps work agency scores to compliance frameworks: USCO copyright, WGA credit, SAG-AFTRA consent, and EU AI Act marking requirements. Scores >= 90% trigger the professional safe harbor. Behavioral flags warn about anchoring (high kept_ratio), satisficing (consecutive AI outputs without review), and missing foundation (AI generation before human direction).

Sessions are in-memory by default. Set `SWARM_SESSION_PATH` to persist to JSONL:

```bash
export SWARM_SESSION_PATH=sessions.jsonl
```

## Run

```bash
# API server
uvicorn swarm_at.api.main:app

# MCP server (stdio)
python -m swarm_at.mcp
```

## Discovery

Discoverable by LLMs, crawlers, and agent frameworks out of the box.

| Endpoint | What |
|----------|------|
| [`/llms.txt`](https://api.swarm.at/llms.txt) | LLM-readable protocol summary |
| [`/.well-known/agent-card.json`](https://api.swarm.at/.well-known/agent-card.json) | A2A agent-to-agent discovery card |
| [`/.well-known/openapi.json`](https://api.swarm.at/.well-known/openapi.json) | OpenAPI 3.1 spec |
| [`/.well-known/ai-plugin.json`](https://api.swarm.at/.well-known/ai-plugin.json) | ChatGPT plugin manifest |
| [`/.well-known/mcp.json`](https://api.swarm.at/.well-known/mcp.json) | MCP server discovery |
| [`/.well-known/security.txt`](https://api.swarm.at/.well-known/security.txt) | Security contact (RFC 9116) |
| [`/discovery`](https://api.swarm.at/discovery) | Discovery hub (all endpoints) |
| [`/robots.txt`](https://api.swarm.at/robots.txt) | Crawler guidance |
| [`/sitemap.xml`](https://api.swarm.at/sitemap.xml) | API sitemap |
| [`/public/schema`](https://api.swarm.at/public/schema) | Protocol schema |
| [`/public/jsonld`](https://api.swarm.at/public/jsonld) | Schema.org JSON-LD |
| [`/public/blueprints`](https://api.swarm.at/public/blueprints) | Blueprint catalog |
| [`/badge/{agent_id}`](https://api.swarm.at/badge/swarm-at) | SVG trust badge |

Agent self-check (auth required):

```bash
curl -H "Authorization: Bearer $SWARM_API_KEY" \
  "https://api.swarm.at/v1/whoami?agent_id=my-agent"
```

Returns trust level, reputation, tool permissions, cooldown status, and promotion path.

<details>
<summary><h2>Core Concepts</h2></summary>

| Concept | What it does |
|---------|-------------|
| **Settlement Engine** | Verify proposals (hash-chain + confidence + divergence), commit to ledger |
| **Settlement Tiers** | Graduated adoption: SANDBOX (log-only) / STAGING / PRODUCTION |
| **Trust-Tiered Identity** | Agents earn authority: UNTRUSTED → PROVISIONAL → TRUSTED → SENIOR |
| **Process Chaining** | Atomic transactions (Beads) chain into workflows (Molecules) |
| **Git-Native Ledger** | Ledger backed by git. Branch, merge, `git log` for audit |
| **Shadow Auditor** | Cross-model divergence detection with escrow on disagreement |
| **Consensus** | Multi-agent stake/verify/finalize with configurable thresholds |
| **Framework Adapters** | First-class LangGraph, AutoGen, CrewAI, OpenAI Assistants integration |

</details>

<details>
<summary><h2>Settlement Types</h2></summary>

75 types covering knowledge verification, agent behaviors, prediction markets, protocol operations, compliance, security, infrastructure, data processing, notifications, experiments, and discovery.

**Knowledge verification:** text-fingerprint, qa-verification, fact-extraction, classification, summarization, translation-audit, data-validation, code-review, sentiment-analysis, logical-reasoning, unit-conversion, geo-validation, timeline-ordering, regex-verification, schema-validation

**Agent behaviors:** code-generation, code-edit, code-refactor, bug-fix, test-authoring, codebase-search, web-research, planning, debugging, shell-execution, file-operation, git-operation, dependency-management, agent-handoff, consensus-vote, task-delegation, documentation, api-integration, deployment, conversation-turn

</details>

## Public Ledger

The live settlement record is published at [github.com/Mediaeater/swarm-at-ledger](https://github.com/Mediaeater/swarm-at-ledger). Every entry is independently verifiable.

## Test

```bash
pytest tests/ -v
```

1322 tests. ~16s.

---

© 2026 Mediaeater. All rights reserved.

