smythe 0.2.0__tar.gz

smythe-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,45 @@
+---
+name: Bug report
+about: Report incorrect or unexpected behavior
+title: "[bug] "
+labels: bug
+assignees: ''
+---
+
+## Summary
+
+A clear, one-paragraph description of the bug.
+
+## Reproduction
+
+Minimal code that reproduces the issue. A failing test against the smythe
+test suite is ideal.
+
+```python
+# Smallest possible repro
+```
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened. Include the full traceback if there is one.
+
+```
+# Paste traceback here
+```
+
+## Environment
+
+- smythe version (or commit SHA if installed from source):
+- Python version (`python --version`):
+- OS:
+- Provider extras installed (anthropic / openai / gemini / openclaw / none):
+- Model name (e.g. `claude-mythos`, `gpt-4o`, `gemini-3-pro`):
+
+## Additional context
+
+Anything else that might help — relevant logs, configuration snippets,
+related issues, hypotheses.

smythe-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/petehottelet/smythe/security/advisories/new
+    about: Report a security issue privately via GitHub Security Advisories. Do not open a public issue for security bugs.

smythe-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,36 @@
+---
+name: Feature request
+about: Propose a new capability or enhancement
+title: "[feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem are you trying to solve? What use case is currently awkward
+or impossible?
+
+## Proposed solution
+
+What you'd like to see. Sketch the API or behavior if you have one in mind.
+
+```python
+# Optional: sketch of the proposed API
+```
+
+## Alternatives considered
+
+Other approaches you thought about, and why this one is preferred.
+
+## Scope and breaking changes
+
+- Does this change the public API? If so, how?
+- Are there backward-compatible incremental steps?
+- Roughly how big is this — a single function, a new module, or a multi-sprint
+  initiative?
+
+## Additional context
+
+Links to relevant issues, prior art in other frameworks (LangGraph, CrewAI,
+AutoGen, etc.), or specs.

smythe-0.2.0/.github/ISSUE_TEMPLATE/release-checklist.md

@@ -0,0 +1,34 @@
+---
+name: Release checklist
+about: Steps for cutting a release to PyPI
+title: "Release vX.Y.Z"
+labels: roadmap
+---
+
+# Release Checklist
+
+## Preflight
+
+- [ ] `pyproject.toml` version has been bumped (PyPI never allows re-uploading a version).
+- [ ] `smythe/__init__.py` `__version__` matches.
+- [ ] `CHANGELOG.md` has a section for this version.
+- [ ] README install instructions mention `pip install smythe`.
+- [ ] Tests pass locally.
+- [ ] Build passes locally with `python -m build`.
+- [ ] Package validates with `python -m twine check dist/*`.
+- [ ] Built wheel installs and imports in a fresh venv.
+
+## GitHub
+
+- [ ] `.github/workflows/publish.yml` exists on the default branch.
+- [ ] GitHub environment `pypi` exists (Settings → Environments).
+- [ ] Release notes are drafted.
+- [ ] Git tag matches the package version, e.g. `v0.2.0`.
+
+## PyPI
+
+- [ ] Pending/trusted publisher exists for `petehottelet/smythe`.
+- [ ] Publisher workflow is `publish.yml`.
+- [ ] Publisher environment is `pypi`.
+- [ ] Release workflow publishes successfully.
+- [ ] `pip install smythe` works from a clean venv after release.

smythe-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!-- Thanks for contributing to smythe! Please fill out the sections below. -->
+
+## Summary
+
+What does this PR change, and why? One or two sentences focused on the "why"
+rather than the "what".
+
+## Linked issue
+
+Closes #<issue-number> <!-- or "Refs #..." if not closing -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] New feature (non-breaking)
+- [ ] Breaking change (API or behavior change — call out the migration path)
+- [ ] Documentation only
+- [ ] Test / CI / tooling only
+
+## Testing
+
+How did you verify this change?
+
+- [ ] Added new tests covering this change
+- [ ] Existing tests cover this change
+- [ ] Manually exercised — describe how:
+
+```
+# Paste relevant test output, or describe the manual run
+```
+
+## Checklist
+
+- [ ] `ruff check smythe/ tests/` passes locally
+- [ ] `pytest tests/` passes locally on at least one supported Python version
+- [ ] [CHANGELOG.md](../CHANGELOG.md) updated under `[Unreleased]` for any
+      user-facing change
+- [ ] Public API additions/changes are documented in docstrings and
+      [Readme.md](../Readme.md) where appropriate
+- [ ] No "created with X" attribution in commit messages
+- [ ] No emojis in code or commit messages (unless explicitly requested)
+
+## Breaking changes
+
+If this is a breaking change, describe the migration path users should follow.

smythe-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check smythe/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-asyncio pytest-cov
+
+      - name: Run tests
+        run: python -m pytest tests/ -v --cov=smythe --cov-report=term --cov-report=xml
+
+      - name: Upload coverage report (artifact)
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: warn

smythe-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+# Trusted publishing: PyPI's pending publisher is configured to trust
+# exactly this workflow filename (publish.yml) and the `pypi` GitHub
+# environment. No API token — GitHub OIDC via id-token: write.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

smythe-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Local working notes (TODOs, project instructions, scratch)
+00_project_files/

smythe-0.2.0/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable changes to **smythe** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+with the pre-1.0 stability note below.
+
+## Versioning policy (pre-1.0)
+
+While the project is on a `0.x` line, the public API is **not yet stable**:
+
+- `0.x` minor bumps (e.g. `0.1.0` -> `0.2.0`) MAY include backward-incompatible changes.
+  Each minor release will document its breaking changes in this file.
+- `0.x.y` patch bumps (e.g. `0.1.0` -> `0.1.1`) are **non-breaking** and contain only
+  bug fixes, documentation, or internal improvements.
+- The first stable release will be `1.0.0`. Until then, pin to a specific minor
+  version (`smythe~=0.1.0`) if API stability matters to you.
+
+---
+
+## [Unreleased]
+
+Future work tracked in [ROADMAP.md](ROADMAP.md).
+
+---
+
+## [0.2.0] - 2026-07-05
+
+First PyPI release. The v0.2 line makes agents real: they use tools, survive
+crashes, and everything they do is visible.
+
+### Added
+
+- **Provider tool contract** — neutral tool-calling types (`ToolSpec`, `ToolCall`,
+  `ToolResult`, `ChatMessage`) and `Provider.chat()`, mapped to native tool use on
+  Anthropic, OpenAI, and Gemini. First milestone of MCP tool support
+  (plans/04-mcp-tool-support.md).
+- **MCP tool support** — agents consume MCP servers as tool sources
+  (`pip install smythe[mcp]`): `MCPServerSpec` (stdio + streamable HTTP) with
+  `env_passthrough` secret handling (variable names in config, values resolved
+  from the environment — never serialized), per-server `allowed_tools` with a
+  large-toolset warning, per-call timeouts, and cancellation-safe teardown.
+  `MCPSkillProvider` grounds capability-based assignment in real tools, and the
+  `LLMArchitect` planning prompt now includes an available-agents/tools
+  inventory so plans exploit the toolset. Examples: offline filesystem
+  (bundled server), GitHub (allowlisted), and generic SaaS over HTTP.
+  Docs and threat model: docs/mcp.md.
+- **Tool-calling loop** — nodes whose Swarm has a `tool_runtime` run a bounded
+  tool loop: `max_tool_iterations` circuit breaker (per node and per Swarm),
+  mid-loop budget enforcement, per-call trace entries, tool failures fed back to
+  the model as error results, and `timeout_s` covering the whole loop. Budget
+  recording moved into the loop via the new accumulating `Sentinel.add_cost()`;
+  `node.metadata["cost_usd"]` is now cumulative across a node's provider calls.
+  `ToolRuntime` / `ToolSession` define the interface the MCP runtime implements
+  next (plans/04 M2).
+- **Graph export** — `ExecutionGraph.to_mermaid()` (with node-status styling),
+  `to_dot()`, and `to_json()` (with per-node cost).
+- **`OfflineProvider`** — deterministic, no-network provider; every example runs
+  offline and CI smoke-tests them with API keys stripped.
+- **OpenAI-compatible `base_url`** on `OpenAIProvider` (env: `OPENAI_BASE_URL`) for
+  Ollama, LM Studio, vLLM, and other compatible endpoints.
+- **Release workflow** — tag-triggered PyPI publishing via trusted publishing, plus
+  README badges and a public [ROADMAP.md](ROADMAP.md).
+
+- **Durable, resumable execution** — `Swarm(checkpoint_store=...)` persists the full
+  execution state (graph, node results, agents, budget consumed) after every node.
+  `swarm.resume(execution_id)` picks up from the last completed node; finished nodes
+  are never re-executed and cost accounting continues against the original cap.
+  Ships with `FileCheckpointStore` (one JSON file per execution, atomic writes) and a
+  `CheckpointStore` ABC for custom backends. Format documented in
+  docs/checkpoint-format.md; demonstrated in examples/04_resume_after_crash.py.
+
+- **Per-node timeouts** — `Node.timeout_s` (also settable in YAML) caps the wall-clock
+  time of a single execution attempt in both executors; timeouts are handled by the
+  node's failure policy like any other error.
+- **Concurrency cap** — `AsyncExecutor(max_concurrency=...)` bounds in-flight provider
+  calls; exposed as `Swarm(max_concurrency=...)` with a default of 8.
+- **`examples/` directory** — three runnable scripts (YAML quickstart, dynamic LLM
+  planning, budget-capped parallel run) that work offline via a built-in demo provider.
+
+### Changed
+
+- README aligned with shipped behavior: recursive subgraph decomposition, approval
+  gates, and performance-history routing are now explicitly labeled roadmap items.
+- Executor and AsyncExecutor share a single provider-call path
+  (`ExecutorBase.acall_node`), removing duplicated prompt-building logic.
+
+### Fixed
+
+- Deflaked `test_registry_cache_expires_after_ttl` (deterministic clock instead of
+  `time.sleep`).
+
+---
+
+## [0.1.0] - 2026-03-28
+
+Initial public release.
+
+### Added — Core runtime
+
+- **Task -> Architect -> Graph -> Executor -> Synthesizer pipeline.** The full
+  orchestration loop from a `Task` through plan generation, parallel or serial
+  execution, and output synthesis.
+- **`ExecutionGraph` DAG model** with first-class topology
+  (`SERIAL`, `FORK_JOIN`, `BROADCAST_REDUCE`), per-node status (`PENDING`,
+  `RUNNING`, `COMPLETED`, `FAILED`, `SKIPPED`), failure policies
+  (`HALT`, `SKIP`, `RETRY`), and dependency edges with cycle, duplicate-ID,
+  and unknown-dependency validation.
+- **Three-tier architect routing via `WhiteRabbit`** — deterministic
+  (template-based), constrained (LLM with strict topology vocabulary), and
+  autonomous (`LLMArchitect`, full freedom). Routes by classifier prompt or
+  explicit override.
+- **`Architect` implementations** — `SimpleArchitect` (single-node fallback),
+  `DeterministicArchitect` (template-based), `ConstrainedArchitect`
+  (LLM with restricted topology vocabulary), `LLMArchitect` (autonomous,
+  with JSON-mode planning and context-preserving retries on malformed output).
+- **`AsyncExecutor`** — concurrent DAG execution with topological wave
+  scheduling, deadlock detection, and partial-reservation rollback on
+  budget exhaustion mid-wave.
+- **`Executor`** — serial DAG execution with the same failure-policy
+  semantics as the async executor.
+- **`Sentinel` budget guardrails** — reservation/record/release protocol
+  for safe concurrent cost tracking, with hard USD caps and per-node
+  cost attribution.
+- **`Synthesizer`** with three strategies: `CONCATENATE` (zero-cost join),
+  `STRUCTURED` (JSON shallow-merge), and `LLM_MERGE` (provider-backed
+  intelligent synthesis with optional budget and tracer integration).
+- **`Tracer`** — structured per-node spans with start/end/error hooks
+  and a JSON-serializable summary for downstream observability.
+- **`Registry` and `Agent`/`AgentProfile`** — persistent agent identities
+  with capabilities, persona, and append-only execution history.
+- **`PlannerMemory`** — JSONL-backed outcome store for the architect
+  feedback loop (recall surface implemented; closing the loop into
+  prompt context is on the roadmap).
+- **YAML pipeline loader** (`Swarm.from_yaml`) — declare a graph and
+  agent registry in YAML and execute it directly.
+- **Skills system** (`SkillRef`, `SkillProvider`, `CapabilityMapper`)
+  for capability hydration from external skill inventories.
+
+### Added — LLM providers
+
+- **`AnthropicProvider`** — async wrapper over the official `anthropic` SDK.
+- **`OpenAIProvider`** — async wrapper over the official `openai` SDK.
+- **`GeminiProvider`** — async wrapper over the official `google-genai` SDK,
+  including support for `gemini-3-pro-image-preview` and other Gemini models.
+- **Auto-detection** in `Swarm` — picks the right provider from the model
+  name prefix (`claude*`, `gpt*`/`o1`/`o3`/`o4`, `gemini*`).
+- **`OpenClawSkillProvider`** — adapter for OpenClaw `AgentSkills`,
+  translating SDK skill objects into `SkillRef`s for capability hydration.
+
+### Added — Testing & CI
+
+- **240 passing tests, 3 skipped** across the full suite, including
+  dedicated test files for router edge cases, tracer/span lifecycle,
+  agent model invariants, and a full pipeline integration suite.
+- **Shared test fixtures** in `tests/helpers.py` (mock providers,
+  failing providers, classifier mocks, fixed architects, completed-graph
+  builder).
+- **GitHub Actions CI** ([.github/workflows/ci.yml](.github/workflows/ci.yml))
+  with `ruff` lint and a `pytest` matrix across Python 3.11 / 3.12 / 3.13.
+
+### Fixed
+
+- **Async exception masking** — `AsyncExecutor` cascading failures no
+  longer mask the original exception with a `RuntimeError`.
+- **Partial-reservation leak in `AsyncExecutor`** — if `Sentinel.reserve()`
+  fails partway through a wave, all previously successful reservations in
+  that wave are now released before the exception propagates.
+- **Synthesizer model passthrough** — `LLM_MERGE` synthesis now receives the
+  swarm's configured model instead of an empty string.
+- **Direct-graph validation** — `Swarm.execute(graph)` (with a pre-built
+  `ExecutionGraph` instead of a `Task`) now runs `graph.validate()` before
+  execution.
+- **Executor dependency guard** — `Executor._walk` now raises a clear
+  `ValueError` (instead of a `KeyError`) when a node depends on an unknown
+  node ID.
+- **`LLMArchitect` retry robustness** — `aplan` now also recovers from
+  `TypeError` during LLM-response parsing, not only `ValueError`.
+
+### Documentation
+
+- **`Readme.md`** — full pitch, four worked examples (fork-join, broadcast-reduce,
+  YAML pipeline, agent registry), API reference for the public surface,
+  installation instructions for each provider extra, and an "Async usage"
+  section documenting `asyncio.run()` limitations and recommending the
+  async APIs (`aplan`, `execute_async`).
+- **`LICENSE`** — MIT.
+
+### Known issues
+
+- **`tests/test_skills_registry.py::test_registry_cache_expires_after_ttl`** is
+  timing-flaky on Windows under suite load. The test uses a 50ms TTL with a
+  60ms sleep, which is too tight for `time.sleep()` precision on Windows.
+  Passes consistently in isolation. Tracked for fix in 0.1.1.
+
+[Unreleased]: https://github.com/petehottelet/smythe/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/petehottelet/smythe/releases/tag/v0.1.0

smythe-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,135 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers via a private GitHub message to
+[@petehottelet](https://github.com/petehottelet) or by opening a confidential
+[security advisory](https://github.com/petehottelet/smythe/security/advisories/new)
+on this repository.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations