Testable AI workflows for the rest of us.

Most AI tooling assumes you have a platform team and a Kubernetes cluster. Heddle assumes you have a laptop — or a few of them — and a problem to solve. Local-first, privacy-first, on-prem-friendly.

Get started in 60 seconds Read the docs

What's moving

Nov 2026

heddle v0.13.0

Docling document processing works out of the box, and reports tables, sections and page counts correctly. The experimental event-sourcing module is removed to make way for a rewrite.
Nov 2026

heddle v0.12.0

Wire text follows two I-JSON rules: no NaN, no repeated member names. Python, .NET, Swift and the JVM now read every message the same way.
Nov 2026

heddle v0.10 & v0.11

One typed frame for every message. The .NET, Swift and JVM SDKs speak it, checked live against a heddle router over NATS.
In design

An event log for durable history

A small log of facts on NATS JetStream and SQLite, where every piece of state can be opened and read. Sized for a small business, not a platform team.
In design

warp

A macOS-first agent that turns a few machines into an ad-hoc cluster for Heddle.

The trade-offs we've made on purpose

Solo and SMB first.

If a feature needs a Kubernetes administrator to operate, it doesn't belong here. You should be able to install a CLI, edit a YAML file, and run a workflow in a browser.

Local before cloud.

The local tier (LM Studio, Ollama) is a first-class citizen, not a fallback. Three model tiers let you pick cost and privacy per step.

Privacy as a default.

Workloads tagged private never leave your machines. Knowledge silos and blind audit patterns prevent the same model from reviewing its own work.

Typed contracts everywhere.

Pydantic messages and per-worker JSON Schemas are the only safety net between actors. No untyped dicts on the wire, ever.

Stateless workers.

Every worker resets between tasks. Horizontal scaling without coordination, deterministic routing, full auditability.

Apple Silicon is a real substrate.

Personal-axis compute deserves a real control plane. Apple Silicon and hyperscaler chips solve different problems; we treat both as first-class.

The Heddle project family

heddle v0.13.0 — active development

The runtime. Python actor-mesh over NATS.

Six shipped workers, a Workshop web UI for testing, RAG pipeline, multi-agent councils, MCP gateway, document processing. The canonical Python framework and the wire-protocol source of truth for the whole family: one typed frame, published JSON Schemas, and conformance fixtures every SDK must pass.

heddle-sdk wire-compatible, pre-release

Foreign-language SDKs. .NET, Swift and JVM, with NATS adapters.

Lets you write Heddle processor workers in C#, Swift, Kotlin or Java against the same wire protocol. Vendored JSON Schemas, transport-agnostic worker bases, runnable echo examples. All three pass heddle's conformance fixtures and interoperate live with a heddle router. Not yet on NuGet, SwiftPM or Maven: build from source.

warp-design design phase

Vision and ADRs for a macOS-first cluster agent.

Pre-implementation design exploration for warp — a Swift daemon that turns Heddle into an ad-hoc personal/SMB cluster orchestrator. mDNS peer discovery, capacity reporting, policy-driven scheduling, cloud-burst, longitudinal hardware advisor. The warp production repository will appear when v0 is ready.

heddle-workspace stable

Agent tooling + workspace lifecycle for Heddle-based projects.

Two pillars in one repo. Agent tooling: shared cross-repo anchors (philosophy, invariants, contract map), user-invokable skills (/heddle-orient, /heddle-preflight, /cross-repo-pr), and subagent definitions (architect, contract reviewer, invariant guard). Workspace lifecycle: an umbrella git repo pattern with a .heddle-workspace.yaml manifest and a bin/workspace CLI (init, link, sync, status, doctor) for bootstrapping, moving between machines, and reconciling divergent local copies.

Get started in 60 seconds

1. Install

pip install heddle-ai[workshop]

2. Configure

heddle setup

Auto-detects LM Studio and Ollama.

3. Try it

heddle workshop

Opens the web UI at localhost:8080.

No servers to run. No configuration files to write. Pick a worker in the browser, paste any text, click Run. When you're ready to scale, Heddle adds a NATS message bus that connects everything for production use.