Metadata-Version: 2.5
Name: smythe
Version: 0.7.0
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>=0.40; 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>=0.40; extra == 'anthropic'
Provides-Extra: benchmarks
Requires-Dist: anthropic>=0.40; 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: 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.8; 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.7.0/assets/wordmark.svg" alt="SMYTHE" width="340">

  <p><em>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"><img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/assets/badges/ci.svg" alt="CI checks"></a>
    <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/assets/badges/python.svg" alt="Python 3.11, 3.12, and 3.13">
    <a href="https://github.com/petehottelet/smythe/blob/v0.7.0/LICENSE"><img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/assets/badges/license.svg" alt="License: MIT"></a>
  </p>

  <p>
    <a href="#glyph-rain">Glyph Rain</a> ·
    <a href="#benchmarks">Benchmarks</a> ·
    <a href="#quickstart">Quickstart</a> ·
    <a href="#why-smythe">Why Smythe</a> ·
    <a href="https://github.com/petehottelet/smythe/blob/v0.7.0/docs/index.md">Documentation</a>
  </p>
</div>

**Give Smythe a goal. It generates an inspectable task graph and executes it
with bounded concurrency, execution budgets, verification, traces, and recovery.** The graph defines the work; the durable execution envelope governs the run.

**Measured against CrewAI on the matched framework suite: 77% fewer tokens
and 28% less wall time.** Five tasks, three repetitions, the same executor
model and pipeline, with blind cross-vendor judging.

## Glyph Rain

One workflow creates and validates 192 original SVG glyphs.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/screensaver/svg-preview/preview.png" alt="Classic code rain with the reference character set and occasional original Smythe glyphs" width="900">
</p>

**Explore:** [Run the web explorer](https://github.com/petehottelet/smythe/blob/v0.7.0/screensaver/svg-preview/README.md) ·
[Complete 192-glyph contact sheet](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/partitions/glyph_svg_v1/catalog/contact-sheet.png) ·
[56 reference glyphs](https://github.com/petehottelet/smythe/blob/v0.7.0/screensaver/svg-preview/reference/contact-sheet.png) ·
[24-glyph calibration sheet](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/partitions/glyph_svg_v1/catalog/calibration-sheet.png) ·
[Individual SVGs and manifest](https://github.com/petehottelet/smythe/tree/v0.7.0/benchmarks/partitions/glyph_svg_v1/catalog/).
In 3D mode, arrow keys move through the field; Space pauses, R resets the view, and F enters
fullscreen. Touch controls are included.
The [current browser review](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/partitions/glyph_rain_reference_v1/performance-preview-review-20260907.json)
binds this screenshot and passes 31 rendering and interaction checks.
A separate ten-minute travel and resize check passed 57 cycles.
[Rendering measurements and stability report](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/renderer_performance_20260907_results.md).

**Native downloads:** [Windows `.scr`](https://github.com/petehottelet/smythe/raw/refs/heads/main/screensaver/dist/SmytheGlyphRain.scr) ·
[macOS universal `.zip`](https://github.com/petehottelet/smythe/raw/refs/heads/main/screensaver/dist/GlyphRain-macos-universal.zip) ·
[Linux x86-64 `.tar.gz`](https://github.com/petehottelet/smythe/raw/refs/heads/main/screensaver/dist/SmytheGlyphRain-linux-x86_64.tar.gz) ·
[Native source and setup](https://github.com/petehottelet/smythe/blob/v0.7.0/screensaver/README.md).

All three downloads now use the current SVG shapes: **56 reference glyphs plus
192 original Smythe glyphs**, with the reference blank slot and a 10% original
mix. Filled contours preserve curves, counters, and detached marks.
The compiled packages passed rendering and motion checks on Windows,
Apple Silicon, Intel Mac, and Ubuntu 22.04/24.04.
[Checksums and verification](https://github.com/petehottelet/smythe/blob/v0.7.0/screensaver/README.md#native-verification).
macOS uses an ad-hoc signature; Linux requires X11.
The native savers use layered trails; the web explorer provides the REGL effect,
3D navigation, and pixel settings.

The web renderer adapts [m8e](https://github.com/m8e/matrix-rain),
a fork of Rezmason, under its MIT license. It uses the reference's rain,
glyph rendering, bloom, and palette pipeline. Native packages also include the
licensed reference artwork and its MIT notice. Smythe's 192 added shapes have
independently authored contours from a [measured style brief](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/glyph-rain-plan.md).
[Credits, licenses, and artwork provenance](https://github.com/petehottelet/smythe/blob/v0.7.0/screensaver/README.md#credits-and-references).

## Benchmarks

The glyph workload measures parallel artifact generation. Separate matched
suites measure recovery, framework overhead, and generated plans. Each result
links to its protocol and committed records.

### Original SVG generation

**192 original SVG glyphs in 4.03 seconds median**, including generation,
complete validation, and assembly. The best tested configuration used eight
process workers and ran **2.95× faster** than process execution at concurrency 1.
All 30 workflows delivered complete, accepted catalogs with identical hashes.

The new workflow measures fresh contour construction, full style and
distinctness checks, and delivery of the SVG catalog and raster atlas.
It runs locally through Smythe from a calibrated procedural grammar, with no
simulated delay and **$0 provider API charges**. Hardware and design work are
outside that API-cost figure.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/assets/benchmarks/svg_workflow.svg" alt="Complete SVG workflow times across thread and process configurations, with all repetitions and a measured stage breakdown" width="900">
</p>

[Workflow results and protocol](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/svg_glyph_benchmark.md) ·
[Raw record](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/results/glyph_svg_v1.json).

### Glyph generation and scaling

**192 verified glyphs in 20.5 seconds.** At concurrency 64, the glyph workload
ran **56.2× faster** than serial execution. This is a controlled offline
measurement with 5.8 seconds of simulated provider latency per call.
All measured 64-, 128-, 192-, and 256-node runs produced complete sets of valid,
unique tiles. This measures artifact generation, not screensaver frame rate.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/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>

[Glyph protocol and records](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/glyph_screensaver_benchmark.md).

### Jobs at 5,000 operations

**5,000 accepted artifacts after a hard process kill and recovery.** Safe
resume completed 2,500 pending operations and preserved the 2,492 already
accepted outputs. Eight interrupted operations required explicit rerolls;
their original unknown call records remain in the ledger. No accepted
operation was reissued; resuming the completed job made
zero new calls.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/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>

One Windows campaign, concurrency eight, identical 1×1 PNG fixtures, and
**$0 provider API charges**. This tests durable recovery on the frozen
schema-v3 runtime; glyph generation, model quality, and the later schema-v4
operator features have separate evidence.
[Results, complete archive, and independent reconciliation](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/jobs_scale_5000_20260907_results.md).

### Recovery after interruption

A separate matched durability test measures work repeated after a hard kill.
Smythe repeated **8 calls versus LangGraph's 32**, a **75% reduction**, across
three repetitions. [Recovery protocol](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/durability_benchmark.md).

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/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>

### Framework efficiency

The framework suite compares orchestration on a fixed pipeline. Smythe used
**77% fewer tokens and 28% less wall time than CrewAI** across five tasks and
three repetitions per framework. All runs use the same executor model and
three-stage pipeline, with blind cross-vendor judging.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/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.7.0/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>

Smythe also recorded **6% less mean wall time than LangGraph**. Its observed
quality score was **9.73/10**, versus 9.53 for both comparisons. These are
suite results; token counts describe model usage, not invoice savings.
[Protocol and records](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/README.md#corrected-framework-head-to-head-langgraph-and-crewai-2026-07-12).

### Generated execution topology

The task-shape suite compares generated plans with a fixed pipeline across
five task shapes. Smythe recorded **14% less wall time**, including planning.
It used one node for a simple transformation and an average of 5.3 for parallel
research. Observed quality averaged 9.47/10 versus 9.33/10, within measured
judge variation.

<p align="center">
  <img src="https://raw.githubusercontent.com/petehottelet/smythe/v0.7.0/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>

[Task-shape protocol and records](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/shape_suite.md).

Charts are generated from committed records. The [benchmark index](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/README.md)
documents each comparison, its scope, and its evidence status.

## Why Smythe

| Generated execution topology | Durable execution envelope |
|---|---|
| Generate a DAG from the goal with `LLMArchitect` | Bound active calls with `max_concurrency` |
| Select approved templates with `ConstrainedArchitect` | Reserve supported text-workflow phases in one `run_store` ledger |
| Build exact workflows with `DeterministicArchitect` | Save node results and resume from checkpoints |
| Inspect and export plans with their complete task | Validate artifacts and recover verification decisions |
| Reuse successful graphs as templates | Trace calls, costs, failures, and revisions |

Agents use MCP tools, generate images, and pass artifacts to downstream nodes.
Durable Jobs add manifest validation, plan approvals, an attempt journal,
selective rerolls, detached workers on supported hosts, durable pauses, read-only inspection,
and portable exports. Inspect
prompts, responses, costs, and artifact receipts in a local HTML report.
Lease epochs reject stale-worker journal writes after ownership changes.
Persistent artifact namespaces and exclusive file publication preserve accepted
outputs across custom run IDs and shared output directories.
File checkpoints flush complete snapshots before atomic publication, using
independent temporary files for separate store instances.
Iterative graph traversal passes [5,000-node dependency-chain checks](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/execution.md#deep-graphs),
including complete offline serial execution and atomic revision validation.
[Saved graph policies](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/workflow-accounting.md#freeze-graph-limits) bound node
count, execution models, retries, and regeneration across planning and recovery.

[Architecture](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/architecture.md) · [Task handoffs](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/tasks.md) · [Jobs and CLI](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/jobs.md) ·
[Failure policies](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/execution.md) · [Cost guardrails](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/budgets.md) ·
[MCP](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/mcp.md) · [Verification](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/verifier.md) ·
[Native Astra and Sol Responses](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/openai-responses.md) ·
[Durable text accounting](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/workflow-accounting.md) ·
[All guides and examples](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/index.md).

## Quickstart

Python 3.11+. Install Smythe 0.7.0 with the provider used below:

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

Set `OPENAI_API_KEY`, then generate and inspect a text-only plan with
[GPT-6 Astra](https://developers.openai.com/api/docs/models/gpt-6-astra):

```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,
    )
    task = Task(
        goal="Compare SQLite, PostgreSQL, and DuckDB for a local analytics app.",
        constraints=[
            "Keep the comparison under 400 words",
            "Explain the tradeoffs and recommend one database",
        ],
    )
    graph = swarm.plan(task)
    print(graph)

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

This example makes paid API calls under a **$5 run allowance**. The
[Responses provider](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/openai-responses.md) supplies native usage receipts
and model-specific prices; the [SQLite workflow ledger](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/workflow-accounting.md)
includes planning and execution, reserves each request before dispatch, and
replays saved responses locally during recovery. Up to eight execution nodes
run concurrently. Anthropic and Gemini use the `smythe[anthropic]` and
`smythe[gemini]` extras outside this managed text-workflow path.

Try the complete acquisition-diligence workflow without an API key:

```bash
git clone https://github.com/petehottelet/smythe.git
cd smythe
pip install -e ".[dev]"
python examples/acquisition_diligence/run.py
```

Three specialists work in parallel, an editor assembles their findings, a red
team challenges the draft, and a final node writes the decision memo.
[Graph, trace, and expected output](https://github.com/petehottelet/smythe/tree/v0.7.0/examples/acquisition_diligence/).

## Coming soon

- **Native exploration:** bring the web exposure pipeline, camera controls,
  and settings to Windows, macOS, and Linux, then verify them against the
  [implementation plan](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/glyph-rain-plan.md).
- **Native distribution:** notarized macOS downloads and native Wayland integration.
- **Renderer performance:** meet the 1080p frame-interval target with the new
  glyphs, then verify visible presentation and GPU timing. The
  [six-session headless study](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/renderer_performance_20260907_results.md)
  measured 56.21–56.24 draws/second and retained every result; its pacing target
  was not met.
- **Broader evidence:** bounded paid scale trials, repeated live glyph sweeps, and
  human-calibrated quality comparisons with saved outputs and judge reasoning.
- **Astra benchmarks:** matched model and orchestration comparisons with full
  usage accounting and blind quality scoring. The 13-task pack and schedules
  for 12 pilot and 200 main workflows are prepared. The
  [pilot runner](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/astra_runtime.md) binds spending allocations,
  source hashes, and recoverable trial identities. Live execution awaits the
  campaign allowance and [calibration gates](https://github.com/petehottelet/smythe/blob/v0.7.0/benchmarks/astra_benchmark_plan.md).

[Specifications and priorities](https://github.com/petehottelet/smythe/blob/v0.7.0/ROADMAP.md#coming-soon) ·
[Repository review](https://github.com/petehottelet/smythe/blob/v0.7.0/docs/project-review-2026-09-06.md).

Smythe is pre-1.0; minor releases may change APIs.
[Release history](https://github.com/petehottelet/smythe/blob/v0.7.0/CHANGELOG.md) · [Contributing](https://github.com/petehottelet/smythe/blob/v0.7.0/CONTRIBUTING.md) ·
[Security](https://github.com/petehottelet/smythe/blob/v0.7.0/SECURITY.md) · [MIT license](https://github.com/petehottelet/smythe/blob/v0.7.0/LICENSE).
