Metadata-Version: 2.5
Name: smythe
Version: 0.8.1
Summary: Generated agent execution graphs with durable, budgeted orchestration
Project-URL: Homepage, https://github.com/petehottelet/smythe
Project-URL: Repository, https://github.com/petehottelet/smythe
Project-URL: Issues, https://github.com/petehottelet/smythe/issues
Project-URL: Changelog, https://github.com/petehottelet/smythe/blob/main/CHANGELOG.md
Project-URL: Security Policy, https://github.com/petehottelet/smythe/security/policy
Author: Pete Hottelet
License-Expression: MIT
License-File: LICENSE
Keywords: agents,checkpointing,dag,llm,multi-agent,orchestration,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: anthropic>=1.5; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: mcp<2,>=1.2; extra == 'all'
Requires-Dist: numpy<3,>=2.0; extra == 'all'
Requires-Dist: openai>=3.8; extra == 'all'
Requires-Dist: openclaw-sdk>=0.1; extra == 'all'
Requires-Dist: pillow==11.1.0; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: scipy<2,>=1.14; extra == 'all'
Requires-Dist: shapely==2.1.2; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.5; extra == 'anthropic'
Provides-Extra: benchmarks
Requires-Dist: anthropic>=1.5; extra == 'benchmarks'
Requires-Dist: crewai>=1.0; extra == 'benchmarks'
Requires-Dist: google-genai>=1.0; extra == 'benchmarks'
Requires-Dist: langchain-openai>=1.0; extra == 'benchmarks'
Requires-Dist: langgraph-checkpoint-sqlite>=3.0; extra == 'benchmarks'
Requires-Dist: langgraph>=1.0; extra == 'benchmarks'
Requires-Dist: openai>=3.8; extra == 'benchmarks'
Requires-Dist: pillow>=10.0; extra == 'benchmarks'
Provides-Extra: dev
Requires-Dist: mcp<2,>=1.2; extra == 'dev'
Requires-Dist: mypy==1.17.1; extra == 'dev'
Requires-Dist: numpy<3,>=2.0; extra == 'dev'
Requires-Dist: pillow==11.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Requires-Dist: scipy<2,>=1.14; extra == 'dev'
Requires-Dist: shapely==2.1.2; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == 'gemini'
Provides-Extra: glyphs
Requires-Dist: numpy<3,>=2.0; extra == 'glyphs'
Requires-Dist: pillow==11.1.0; extra == 'glyphs'
Requires-Dist: scipy<2,>=1.14; extra == 'glyphs'
Requires-Dist: shapely==2.1.2; extra == 'glyphs'
Provides-Extra: jobs
Requires-Dist: pillow>=10.0; extra == 'jobs'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=3.8; extra == 'openai'
Provides-Extra: openclaw
Requires-Dist: openclaw-sdk>=0.1; extra == 'openclaw'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/wordmark.svg" alt="SMYTHE" width="340">
  <p><em>An open-source framework for task-based agent swarms with dynamic parallelization, routing, and execution topology.</em></p>
  <p>
    <a href="https://pypi.org/project/smythe/"><img src="https://raw.githubusercontent.com/petehottelet/smythe/main/assets/badges/pypi.svg" alt="Latest PyPI release"></a>
    <a href="https://github.com/petehottelet/smythe/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush"><img src="https://github.com/petehottelet/smythe/actions/workflows/ci.yml/badge.svg?branch=main&amp;event=push" alt="CI status on main"></a>
    <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/badges/python.svg" alt="Python 3.11, 3.12, and 3.13">
    <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/LICENSE"><img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/badges/license.svg" alt="License: MIT"></a>
  </p>
  <p>
    <a href="#quickstart">Quickstart</a> ·
    <a href="#how-it-works">How it works</a> ·
    <a href="#measured-results">Measured results</a> ·
    <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/docs/index.md">Documentation</a>
  </p>
</div>

**Smythe is a Python framework that plans and runs agent workflows.** Give it a
goal, inspect the generated task graph, and execute independent work in parallel.
Set spending and concurrency limits, verify outputs, and recover saved work after
an interruption.

Use it for research pipelines, document production, and artifact generation
where you need to see what will run and account for what happened.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/glyph_rain/glyph-rain-loop.gif" alt="Animated rain showing only the 192 revised Smythe glyphs" width="900">
</p>
<p align="center"><em><a href="https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/README.md">Glyph Rain</a>: its glyph catalog is compiled, validated, and exported by a Smythe workflow (<a href="https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/svg_v2_results.md">benchmark</a>).</em></p>

<p align="center">
  <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/glyph-design-v2/contact-sheet-128.png">192-glyph sheet</a> ·
  <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/partitions/glyph_svg_v2_256/catalog/contact-sheet-128.png">256-glyph sheet</a> ·
  <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/glyph-design-v2/README.md">Individual SVGs</a> ·
  <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/svg-preview/README.md">Web explorer</a> ·
  <a href="https://github.com/petehottelet/smythe/blob/v0.8.1/docs/current-materials.md">All materials</a>
</p>

## Quickstart

Python 3.11+:

```bash
pip install smythe
```

Plan, run, and recover a workflow with no API key:

```python
from smythe import OfflineProvider, SQLiteWorkflowStore, Swarm, Task

# The plan a model would generate. OfflineProvider returns it to the planner
# and echoes each step, so everything below runs without an API key.
plan = {
    "topology": ["fork_join"],
    "nodes": [
        {"id": "sqlite", "label": "Assess SQLite"},
        {"id": "postgres", "label": "Assess PostgreSQL"},
        {"id": "duckdb", "label": "Assess DuckDB"},
        {"id": "pick", "label": "Recommend one database",
         "depends_on": ["sqlite", "postgres", "duckdb"]},
    ],
}

with SQLiteWorkflowStore("smythe-runs.db") as store:
    swarm = Swarm(
        provider=OfflineProvider(plan=plan),
        run_store=store,
        max_budget_usd=1.00,
        parallel=True,
    )
    graph = swarm.plan(Task("Compare SQLite, PostgreSQL, and DuckDB for a local analytics app."))
    print(graph)  # inspect the generated graph before anything runs

    result = swarm.execute(graph)
    print(result.output)

    replay = swarm.resume(result.execution_id)  # replayed from the journal, no new calls
    print(replay.output == result.output)
```

`print(graph)` shows the graph before anything runs:

```text
TaskGraph(topology="fork-join")
├─ fork (parallel):
│   ├─ agent-sqlite: Assess SQLite
│   ├─ agent-postgres: Assess PostgreSQL
│   └─ agent-duckdb: Assess DuckDB
└─ join: agent-pick: Recommend one database
```

The three assessments run in parallel under the $1 budget, and the SQLite
journal records every call, so `resume` returns the finished run without
calling the provider again.

### With a real model

Install a provider extra, set `OPENAI_API_KEY`, and let
[GPT-6 Astra](https://developers.openai.com/api/docs/models/gpt-6-astra)
write the plan and the answers:

```bash
pip install "smythe[openai]"
```

```python
from smythe import OpenAIResponsesProvider, SQLiteWorkflowStore, Swarm, Task

with SQLiteWorkflowStore("smythe-runs.db") as store:
    swarm = Swarm(
        model="gpt-6-astra",
        provider=OpenAIResponsesProvider(
            reasoning_effort="medium",
            max_output_tokens=8192,
        ),
        run_store=store,
        max_budget_usd=5.00,
        parallel=True,
        max_concurrency=8,
    )
    graph = swarm.plan(Task(
        goal="Compare SQLite, PostgreSQL, and DuckDB for a local analytics app.",
        constraints=["Stay under 400 words", "Recommend one database"],
    ))
    print(graph)
    result = swarm.execute(graph)
    print(result.output)
```

This makes paid API calls under a **$5 run allowance**. The SQLite ledger
accounts for planning and execution, reserves requests before dispatch, and
retains responses for recovery. See [budget scope](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/budgets.md) and
[durable text workflows](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/workflow-accounting.md). Claude and Gemini
install the same way, with `smythe[anthropic]` and `smythe[gemini]`; durable run
stores accept the OpenAI Responses and Claude Messages providers.
[More examples](https://github.com/petehottelet/smythe/blob/v0.8.1/examples/README.md).

## How it works

**The graph defines the work.** Smythe generates a directed acyclic graph for
the task, including dependencies and agent assignments. Inspect or export it
before execution. Use approved templates or a graph you write yourself when
the workflow is already known.

**The execution envelope governs the run.** Budgets, bounded concurrency,
verification, traces, artifacts, and recovery apply as the graph executes.
Durable Jobs add manifest approval, attempt history, selective rerolls, and
local HTML reports.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/diligence_pipeline.svg" alt="Acquisition diligence: parallel specialists, synthesis, adversarial review, and a final memo" width="900">
</p>

The [acquisition-diligence example](https://github.com/petehottelet/smythe/tree/v0.8.1/examples/acquisition_diligence/) shows
three specialists feeding an editor, a red-team review, and a final decision
memo. Its saved graph, trace, and expected output make the workflow inspectable.

| You need to… | Smythe provides |
|---|---|
| Adapt the workflow to the task | Generated graphs, approved templates, and deterministic planning |
| Control spending and parallel work | Request reservations and bounded concurrency |
| Recover interrupted work | Checkpoints, native response replay, and durable job journals |
| Check the deliverable | Output verification and artifact receipts |
| Understand a run | Graph exports, traces, costs, and inspection reports |

[Architecture](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/architecture.md) · [Execution](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/execution.md) ·
[Jobs](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/jobs.md) · [Verification](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/verifier.md) · [MCP tools](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/mcp.md).

## Measured results

Each result links to its protocol and retained records. Charts are generated
from the committed records.

| Study | Recorded result | Scope |
|---|---|---|
| [Framework comparison](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/README.md#corrected-framework-head-to-head-langgraph-and-crewai-2026-07-12) | 77% fewer mean tokens and 28% less mean wall time than CrewAI | Five tasks, three repetitions; matched executor and fixed pipeline; blind judging |
| [Interruption and recovery](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/durability_benchmark.md) | 8 repeated dispatches versus LangGraph's 32 | Three matched hard-kill trials with 64 operations |
| [Generated topology](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/shape_suite.md) | 14% less wall time than a fixed pipeline, planning included | Five task shapes, three repetitions; wall time and observed quality |
| [SVG catalog workflow](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/svg_v2_results.md) | 256 SVGs in 8.06 seconds median; 2.20× the serial baseline | Local compilation, validation, and export of authored designs; no API calls |
| [Glyph generation at scale](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/glyph_screensaver_benchmark.md) | 56.2× faster than serial at concurrency 64 | Controlled offline runs at 64 to 256 nodes; simulated provider latency |
| [Jobs at 5,000 operations](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/jobs_scale_5000_20260907_results.md) | 5,000 accepted artifacts after a hard kill and recovery | One offline campaign with identical fixtures; correctness, not speed |

### Framework efficiency

On a fixed three-stage pipeline, Smythe used **77% fewer tokens and 28% less
wall time than CrewAI** across five tasks and three repetitions per framework,
with the same executor model and blind cross-vendor judging. It also recorded
6% less mean wall time than LangGraph, and the highest observed quality score:
9.73/10, versus 9.53 for both. Token counts describe model usage, not invoice
savings.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/framework_callouts.svg" alt="Smythe uses 77 percent fewer mean tokens and 28 percent less mean wall time than CrewAI on the matched fixed-pipeline suite" width="900">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/framework_comparison.svg" alt="Smythe, LangGraph, and CrewAI: observed blind quality, mean token counts, and mean wall time across 15 runs per framework" width="900">
</p>

### Recovery after interruption

After a hard kill, Smythe repeated **8 calls versus LangGraph's 32**, a 75%
reduction, in each of three matched repetitions. Both finished all 64
operations. [Recovery protocol](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/durability_benchmark.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/recovery.svg" alt="Three matched interruption tests: Smythe repeated 8 dispatches and LangGraph repeated 32 in every repetition; both finished all 64 operations" width="900">
</p>

### Generated execution topology

Across five task shapes, generated plans took **14% less wall time than a fixed
pipeline, planning included**. They used one node for a simple transformation
and 5.3 on average for parallel research. Observed quality averaged 9.47/10
versus 9.33/10, within measured judge variation.
[Task-shape protocol and records](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/shape_suite.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/shape_efficiency.svg" alt="Generated plans adapt node count to the task and reduce mean wall time by 14 percent, including planning, across the task-shape suite" width="900">
</p>

The [200-workflow Astra/Sol study](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/astra_findings.md)
also reports the limits of generated plans: they increased mean time in both
models on its ten synthetic tasks. The frozen rule accepted 191/200 workflows;
human review accepted all eight disputed available answers. One missing usage
receipt limits affected exact cost comparisons. All outcomes remain published.

### Parallel artifact generation

Smythe compiles, validates at four sizes, compares every pair, and exports
**256 SVG glyphs in 8.06 seconds median**, **2.20× faster** than its
concurrency-one baseline with eight process workers. All 36 workflows pass with
identical SVG and pixel hashes across repetitions, with zero API calls.
[Results and scope](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/svg_v2_results.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/svg_v2_workflow.svg" alt="All 36 complete v2 workflows at 192 and 256 glyphs, with medians, ranges and one actual run's stages" width="900">
</p>

Process workers trade more memory for shorter completion time:

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/svg_v2_memory.svg" alt="Measured parent-plus-worker memory at each catalog size and concurrency" width="900">
</p>

At concurrency 64, generating 192 glyphs took **20.5 seconds** versus 1,149.6
seconds serially, **56.2× faster**, and all 192 validated as unique. This is a
controlled offline measurement with 5.8 seconds of simulated provider latency
per call; every 64-, 128-, 192- and 256-node run produced complete sets of
valid, unique tiles. [Glyph protocol and records](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/glyph_screensaver_benchmark.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/glyph_scaling.svg" alt="Controlled offline glyph generation at four graph widths, with all tiles valid and unique at every measured concurrency" width="900">
</p>

### Jobs at 5,000 operations

A durable Jobs campaign was killed mid-run and recovered to **5,000 accepted
artifacts**. Safe resume preserved the 2,492 outputs already accepted and
reissued none of them; eight interrupted operations needed explicit rerolls,
and resuming the completed job made zero new calls. One offline campaign with
identical fixtures, so this shows recovery correctness, not speed.
[Results and independent reconciliation](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/jobs_scale_5000_20260907_results.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.8.1/assets/benchmarks/jobs_scale.svg" alt="One offline Jobs campaign: 2,492 accepted after the kill, 4,992 after safe resume, and 5,000 after eight explicit rerolls" width="900">
</p>

[All benchmarks, charts, and evidence status](https://github.com/petehottelet/smythe/blob/v0.8.1/benchmarks/README.md).

## Project status

**Smythe 0.8.1** is the current library release. See the
[release notes and upgrade guide](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/release-0.8.1.md). The API is pre-1.0;
minor releases may change it. Later source changes appear in the
[changelog](https://github.com/petehottelet/smythe/blob/v0.8.1/CHANGELOG.md#unreleased).

Next priorities are complete-deliverable checks, broader external-task
benchmarks, and separately controlled Astra scheduler and framework studies.
See the [roadmap](https://github.com/petehottelet/smythe/blob/v0.8.1/ROADMAP.md) for status and acceptance criteria.

The [Glyph Rain screensaver](https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/README.md) is an artifact-generation
showcase with source builds and a [web explorer](https://github.com/petehottelet/smythe/blob/v0.8.1/screensaver/svg-preview/README.md).
Precompiled screensaver distribution is paused.

[Documentation](https://github.com/petehottelet/smythe/blob/v0.8.1/docs/index.md) · [Contributing](https://github.com/petehottelet/smythe/blob/v0.8.1/CONTRIBUTING.md) ·
[Releases](https://github.com/petehottelet/smythe/releases) ·
[Security](https://github.com/petehottelet/smythe/blob/v0.8.1/SECURITY.md) · [MIT license](https://github.com/petehottelet/smythe/blob/v0.8.1/LICENSE).
