smythe 0.8.2

An open-source framework for task-based agent swarms with dynamic parallelization, routing, and execution topology.

Quickstart · How it works · Measured results · Documentation

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 results.

Glyph Rain is Smythe's parallel-processing example: each glyph is an independent task, and Smythe runs the tasks concurrently.

Example Task: Smythe generated 192 glyphs in 20.5 seconds, 56.2× faster than serial. Smythe runs the glyph set as one 192-node fan-out graph, one node per glyph, with up to 64 nodes; run one node at a time, the same graph took 1,149.6 seconds. Controlled offline run with fixed latency per call measures Smythe's scheduling. Glyphs are compiled, validated, and exported in parallel: 256 SVG glyphs in 8.06 seconds median with eight process workers, 2.20× faster than one worker, with no API calls. Fan-out benchmark · SVG workflow benchmark

192-glyph sheet · 256-glyph sheet · Individual SVGs · Web explorer · All materials

Quickstart

Python 3.11+:

pip install smythe

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

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:

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 write the plan and the answers:

pip install "smythe[openai]"

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=50.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 $50 run allowance. The SQLite ledger accounts for planning and execution, reserves requests before dispatch, and retains responses for recovery. See budget scope and durable text workflows. 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.

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.

The acquisition-diligence example 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.

Architecture · Execution · Jobs · Verification · MCP tools.

Measured results

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

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.

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.

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.

The 200-workflow Astra/Sol study 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.

Process workers trade more memory for shorter completion time:

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.

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.

All benchmarks, charts, and evidence status.

Project status

Smythe 0.8.2 is the current library release. See the release notes and upgrade guide.

Next priorities are complete-deliverable checks, broader external-task benchmarks, and separately controlled Astra scheduler and framework studies. See the roadmap for status and acceptance criteria.

The Glyph Rain screensaver is an artifact-generation showcase with source builds and a web explorer. Screensaver distribution is source only, but you're welcome to compile your own binary.

Documentation · Contributing · Releases · Security · MIT license.