jdsl 0.6.2__tar.gz

jdsl-0.6.2/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - harness
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - pyproject.toml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-${{ runner.os }}-${{ hashFiles('mkdocs.yml') }}
+          path: ~/.cache/pip
+          restore-keys: |
+            mkdocs-${{ runner.os }}-
+
+      - name: Install docs dependencies
+        run: pip install "mkdocs>=1.6,<2" "mkdocs-material>=9.5,<10" "mkdocstrings[python]>=0.26,<1" "pymdown-extensions<12.2"
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Configure Git Credentials
+        if: github.event_name != 'pull_request'
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Deploy docs
+        if: github.event_name != 'pull_request'
+        run: mkdocs gh-deploy --force --strict --no-history

jdsl-0.6.2/.github/workflows/python-publish.yml

@@ -0,0 +1,55 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

jdsl-0.6.2/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+uv.lock
+
+dist/
+
+# Environments & secrets
+.venv/
+.env
+.env.*
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+.claude/
+.opencode
+
+# Local agent config (auto-launches servers; per-checkout, like .claude/)
+.mcp.json
+
+# Compiled behavior packages: build outputs / scratch compile dirs.
+# (Committed example fixtures live under examples/ and are tracked explicitly.)
+*.jdsl
+/pkgs/
+/pkgs.jdslpkg
+
+VERSION_RELEASE.md
+
+# Docs build output and local-only docs drafts / experiments.
+site/
+docs/*_next_steps.md
+docs/*_experiment.ipynb
+docs/draft/
+jdsl-linux-x64.tar.gz

jdsl-0.6.2/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync            # installs jdsl (editable) + dev tools
+uv run pytest      # run the suite
+uv run ruff check jdsl jdsl_harness examples test
+```
+
+Python ≥ 3.11, [uv](https://docs.astral.sh/uv/) for everything.
+
+## Style
+
+Terse and dense, in the spirit of tinygrad — small files, one concept each, no
+ceremony. Specifics:
+
+- **Line length 120**, 4-space indent (ruff enforces both).
+- Absolute imports only (`from jdsl.tree import ...`).
+- Docstrings explain *why*, not *what the code obviously does*.
+- Prefer a plain function to a class; prefer a combinator to a config object.
+- Keep the public surface (`jdsl/__init__.py`) small and obvious.
+
+Run `uv run ruff check jdsl jdsl_harness examples test` before opening a PR; CI
+expects it clean.
+
+## Tests are required
+
+Every PR that changes behavior needs tests, and the suite must stay **fast and
+offline** — no network, no real API keys.
+
+- Tests live in `test/`, one file per module (`test_tree.py`, `test_dsl.py`, …).
+- The LLM is never called for real. Use the `fake_model` fixture (see
+  `test/conftest.py`): a `LanguageModel`-shaped stub whose replies you script,
+  and which records every call so you can assert on the prompt/system/model.
+- Cover the branch you touched: a happy path *and* a failure path. Behavior-tree
+  nodes have two outcomes (`SUCCESS`/`FAILURE`) — test both.
+
+```bash
+uv run pytest -q            # all
+uv run pytest test/test_dsl.py -q
+```
+
+## Adding an example
+
+Examples are teaching material and must run as-is.
+
+1. Put a single-file script in `examples/`, named for what it demonstrates.
+2. Start with a module docstring: what it shows, and the exact `uv run jdsl run
+   examples/greeter.py` command (with any `-i key=value` inputs).
+3. Deterministic examples need no key; LLM examples read one from `.env`.
+4. Add a one-line entry to `examples/README.md`.
+5. Keep external-service calls robust (timeouts, a descriptive User-Agent) — an
+   example that crashes on a flaky network teaches nothing.
+
+## Scope of a good PR
+
+One idea per PR. New node type, new provider, new example, or a bug fix — not
+all four. If you're adding a node, it needs: the node in `jdsl/tree.py`, a
+combinator in `jdsl/dsl.py`, an export in `jdsl/__init__.py`, a row in
+`docs/api.md`, and tests.

jdsl-0.6.2/LICENSE

@@ -0,0 +1,8 @@
+Copyright © 2026, Cantor Industries.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jdsl-0.6.2/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: jdsl
+Version: 0.6.2
+Summary: Declarative behavior-tree agents with DSPy-style signatures, run by a tree-walking interpreter over DeepSeek / Anthropic / OpenAI.
+Author: Machar Kook
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.49
+Requires-Dist: mcp>=1.2
+Requires-Dist: openai>=1.40
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: typer>=0.12
+Requires-Dist: typesafe-sdk>=0.7.2
+Provides-Extra: harness
+Requires-Dist: mcp>=1.2; extra == 'harness'
+Provides-Extra: tui
+Requires-Dist: textual>=0.50; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# jdsl
+
+<p align="center">
+  <img src="docs/for_respected_human.png" alt="jdsl logo" width="240" />
+</p>
+
+> Declarative **behavior-tree agents** as clean Python combinators, run by a
+> **tree-walking interpreter** over DeepSeek / Anthropic / OpenAI — with
+> **DSPy-style signatures** on the LLM leaves.
+
+Determinism lives in the tree (`seq` / `sel` / `act`); the model enters only at
+`predict` leaves, typed by a signature like `"message -> category"`. No codegen,
+no object-literal DSL — the tree structure *is* the call structure.
+
+```python
+from jdsl import tool, root, seq, sel, act, check, predict, ref, store
+
+@tool
+def route_to_billing(): print("→ billing")
+@tool
+def route_to_support(): print("→ support")
+@tool
+def route_to_human():   print("→ human")
+
+skill = (
+    root("Triage", system="Classify inbound messages: billing, support, other.")
+    .model("deepseek-chat")                       # provider inferred from the id
+    .do(seq(
+        predict("message -> category"),           # the model classifies…
+        sel(                                      # …and the tree branches on it
+            seq(check("category", "billing"), act(route_to_billing)),
+            seq(check("category", "support"), act(route_to_support)),
+            act(route_to_human),                  # fallback
+        ),
+    ))
+)
+
+ctx = skill.run(message="I was double charged.")
+print(ctx.blackboard["category"])                 # -> "billing"
+```
+
+…and the model can drive **your** tools. A `react` leaf hands it your `@tool`s and
+lets it pick and chain them (native function-calling):
+
+```python
+from jdsl import tool, root, react
+
+@tool
+def distance_km(origin: str, destination: str) -> int: ...   # your Python
+@tool
+def drive_hours(km: int) -> float: ...
+
+skill = root("Trip").model("deepseek-chat").do(
+    react("request -> answer", tools=[distance_km, drive_hours])
+)
+skill.run(request="Driving Nairobi to Mombasa — how long?")
+```
+
+```
+ > distance_km(origin='Nairobi', destination='Mombasa') -> 485
+ > drive_hours(km=485)                                  -> 6.1
+answer: About 6.1 hours.
+```
+
+Triage steers the model with the tree; `react` lets the model steer your tools.
+Full version: [examples/trip.py](examples/trip.py).
+
+## Skill authoring TUI
+
+JDSL includes a compact terminal workbench for building restricted behavior
+trees without writing the initial Python DSL:
+
+```bash
+uv run --extra tui jdsl tui
+```
+
+<p align="center">
+  <img src="docs/tui.png" alt="JDSL skill authoring TUI" width="960" />
+</p>
+
+Add sequence, selector, action, guard, predict, react, and repeat nodes; edit
+their properties; validate the tree; and save a portable `.jdsl` package. See
+the [TUI guide](docs/tui.md) for the authoring workflow.
+
+The workbench uses the Gruvbox Material palette, adapted from
+[sainnhe/gruvbox-material](https://github.com/sainnhe/gruvbox-material) and
+[curbol/omarchy-gruvbox-material](https://github.com/curbol/omarchy-gruvbox-material).
+Truecolor terminals are recommended (`COLORTERM=truecolor`). Use `Ctrl+M` to
+toggle reduced motion and `Ctrl+G` to switch between ASCII-safe and Unicode glyphs.
+
+## Install & run
+
+### Quick install (curl)
+
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash
+```
+
+Or with options:
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --version 0.6.0 --no-modify-path
+```
+
+Requires Python ≥ 3.11. The curl installer includes the harness dependency as
+well as the runtime CLI. After install:
+```bash
+jdsl about                 # banner + quickstart
+jdsl run examples/greeter.py
+```
+
+Upgrade a previous curl installation with:
+
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --uninstall
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --version 0.6.0
+```
+
+The installed CLI also supports `jdsl uninstall`; captures and provider
+credentials are preserved.
+
+### Development (uv)
+
+Requires [uv](https://docs.astral.sh/uv/) and Python ≥ 3.11.
+
+```bash
+uv sync
+
+uv run jdsl run examples/greeter.py                       # deterministic, no key
+echo 'DEEPSEEK_API_KEY=sk-...' >> .env                    # or ANTHROPIC_API_KEY=...
+uv run jdsl run examples/triage.py                        # LLM-driven
+uv run pytest                                             # tests (no network)
+```
+
+The **provider is inferred from the model id**: `deepseek-chat` → DeepSeek,
+`claude-*` → Anthropic, `gpt-*`/`o*` → OpenAI. A `.env` in the working directory
+is loaded automatically.
+
+## The API in one screen
+
+| Combinator | Meaning |
+| ---------- | ------- |
+| `root(name, system=…)` | Entry point. Chain `.model(id)` then `.do(child)`. |
+| `seq(*children)` | Run in order; fail fast (behavior-tree AND). |
+| `sel(*children)` | Try until one succeeds (behavior-tree OR). |
+| `repeat(child, until=…, max=n)` | Loop `child` until `until` succeeds or `max` passes (retry/refine). |
+| `invert(child)` · `optional(child)` | Decorators: flip a status · fail-soft (a failing step won't abort its `seq`). |
+| `timeout(child, seconds=…)` · `oneshot(child)` | Decorators: bound wall-clock time · run once per run, replay the status. |
+| `act(fn, *args)` | Leaf calling a `@tool`; literal args are type-checked. |
+| `ref("key")` | An `act` argument resolved from the blackboard at run time. |
+| `store(act(…), "key")` | Capture an action's return value onto the blackboard. |
+| `check("key", value)` | Guard leaf on `blackboard["key"]`; string matches are case/whitespace-lenient. |
+| `predict("a -> b")` | DSPy-style LLM leaf: reads inputs, writes outputs. |
+| `react("q -> a", tools=[…])` | Agentic leaf: the model calls `@tool`s in a loop (function-calling) until it answers. |
+
+## Layout
+
+```
+jdsl/          the runtime core — dsl, tree (interpreter), context, provider, render, cli
+  trace/       canonical trace events, sinks, storage, redaction, replay
+  ir/          Behavior IR: schema, safe guard expressions, validation, lowering
+  package/     .jdsl manifest, tool contracts, provenance, export + loader
+jdsl_harness/  capture + behavior compiler (separate package; optional [harness] extra)
+plugins/       Claude Code plugin + Gemini CLI extension (trace capture)
+examples/      runnable skills — see examples/README.md
+test/          pytest suite (no network; LLM leaves use fakes)
+docs/          concepts, API reference, providers, harness & compiler
+```
+
+## Behavior harness & compiler
+
+jdsl can also *compile* observed frontier-model behavior into portable policy a
+smaller frozen model runs. The harness captures canonical traces, mines and
+verifies reusable structure (exact dataflow, sequencing, guards, recovery), and
+leaves only irreducible semantic decisions as typed signatures — exported as a
+deterministic `.jdsl`.
+
+```bash
+jdsl harness serve                 # local capture daemon
+jdsl capture inspect <id>          # exact-lineage report
+jdsl compile <id> --out retail.jdsl
+jdsl package run retail.jdsl --tools tools.py --model <small-model>
+```
+
+See [docs/harness_usage.md](docs/harness_usage.md) for the hands-on guide (all
+three capture tiers, compile, verify, run) and [docs/harness.md](docs/harness.md)
+for the design-to-code map.
+
+## Docs
+
+- [docs/index.md](https://cantor-industries.github.io/jdsl-py/) — MkDocs homepage
+- [docs/quickstart.md](docs/quickstart.md) — install and first runs
+- [docs/examples.md](docs/examples.md) — guide to the runnable examples
+- [docs/concepts.md](docs/concepts.md) — behavior trees, the blackboard, signatures, why no codegen
+- [docs/api.md](docs/api.md) — full combinator + node reference
+- [docs/providers.md](docs/providers.md) — models, keys, `.env`, routing
+- [docs/tui.md](docs/tui.md) — skill authoring TUI
+- [docs/harness_usage.md](docs/harness_usage.md) — hands-on: capture, compile, verify, run
+- [docs/harness.md](docs/harness.md) — capture harness and behavior compiler overview
+- [docs/packages.md](docs/packages.md) — `.jdsl` package format and binding
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, tests, adding examples
+
+## Status
+
+Work in progress. The interpreter, combinator API, signatures, and the
+Anthropic / OpenAI-compatible (DeepSeek, OpenAI) backends run today. Not yet
+built: Google provider, and the DSPy-defining **optimization** step (tuning
+prompts against a metric) — the natural next direction now the runtime exists.
+
+## License
+
+O`Saasy · Author: Cantor Industries

jdsl-0.6.2/README.md

@@ -0,0 +1,211 @@
+# jdsl
+
+<p align="center">
+  <img src="docs/for_respected_human.png" alt="jdsl logo" width="240" />
+</p>
+
+> Declarative **behavior-tree agents** as clean Python combinators, run by a
+> **tree-walking interpreter** over DeepSeek / Anthropic / OpenAI — with
+> **DSPy-style signatures** on the LLM leaves.
+
+Determinism lives in the tree (`seq` / `sel` / `act`); the model enters only at
+`predict` leaves, typed by a signature like `"message -> category"`. No codegen,
+no object-literal DSL — the tree structure *is* the call structure.
+
+```python
+from jdsl import tool, root, seq, sel, act, check, predict, ref, store
+
+@tool
+def route_to_billing(): print("→ billing")
+@tool
+def route_to_support(): print("→ support")
+@tool
+def route_to_human():   print("→ human")
+
+skill = (
+    root("Triage", system="Classify inbound messages: billing, support, other.")
+    .model("deepseek-chat")                       # provider inferred from the id
+    .do(seq(
+        predict("message -> category"),           # the model classifies…
+        sel(                                      # …and the tree branches on it
+            seq(check("category", "billing"), act(route_to_billing)),
+            seq(check("category", "support"), act(route_to_support)),
+            act(route_to_human),                  # fallback
+        ),
+    ))
+)
+
+ctx = skill.run(message="I was double charged.")
+print(ctx.blackboard["category"])                 # -> "billing"
+```
+
+…and the model can drive **your** tools. A `react` leaf hands it your `@tool`s and
+lets it pick and chain them (native function-calling):
+
+```python
+from jdsl import tool, root, react
+
+@tool
+def distance_km(origin: str, destination: str) -> int: ...   # your Python
+@tool
+def drive_hours(km: int) -> float: ...
+
+skill = root("Trip").model("deepseek-chat").do(
+    react("request -> answer", tools=[distance_km, drive_hours])
+)
+skill.run(request="Driving Nairobi to Mombasa — how long?")
+```
+
+```
+ > distance_km(origin='Nairobi', destination='Mombasa') -> 485
+ > drive_hours(km=485)                                  -> 6.1
+answer: About 6.1 hours.
+```
+
+Triage steers the model with the tree; `react` lets the model steer your tools.
+Full version: [examples/trip.py](examples/trip.py).
+
+## Skill authoring TUI
+
+JDSL includes a compact terminal workbench for building restricted behavior
+trees without writing the initial Python DSL:
+
+```bash
+uv run --extra tui jdsl tui
+```
+
+<p align="center">
+  <img src="docs/tui.png" alt="JDSL skill authoring TUI" width="960" />
+</p>
+
+Add sequence, selector, action, guard, predict, react, and repeat nodes; edit
+their properties; validate the tree; and save a portable `.jdsl` package. See
+the [TUI guide](docs/tui.md) for the authoring workflow.
+
+The workbench uses the Gruvbox Material palette, adapted from
+[sainnhe/gruvbox-material](https://github.com/sainnhe/gruvbox-material) and
+[curbol/omarchy-gruvbox-material](https://github.com/curbol/omarchy-gruvbox-material).
+Truecolor terminals are recommended (`COLORTERM=truecolor`). Use `Ctrl+M` to
+toggle reduced motion and `Ctrl+G` to switch between ASCII-safe and Unicode glyphs.
+
+## Install & run
+
+### Quick install (curl)
+
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash
+```
+
+Or with options:
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --version 0.6.0 --no-modify-path
+```
+
+Requires Python ≥ 3.11. The curl installer includes the harness dependency as
+well as the runtime CLI. After install:
+```bash
+jdsl about                 # banner + quickstart
+jdsl run examples/greeter.py
+```
+
+Upgrade a previous curl installation with:
+
+```bash
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --uninstall
+curl -fsSL https://cantorindustries.com/jdsl-py/install.sh | bash -s -- --version 0.6.0
+```
+
+The installed CLI also supports `jdsl uninstall`; captures and provider
+credentials are preserved.
+
+### Development (uv)
+
+Requires [uv](https://docs.astral.sh/uv/) and Python ≥ 3.11.
+
+```bash
+uv sync
+
+uv run jdsl run examples/greeter.py                       # deterministic, no key
+echo 'DEEPSEEK_API_KEY=sk-...' >> .env                    # or ANTHROPIC_API_KEY=...
+uv run jdsl run examples/triage.py                        # LLM-driven
+uv run pytest                                             # tests (no network)
+```
+
+The **provider is inferred from the model id**: `deepseek-chat` → DeepSeek,
+`claude-*` → Anthropic, `gpt-*`/`o*` → OpenAI. A `.env` in the working directory
+is loaded automatically.
+
+## The API in one screen
+
+| Combinator | Meaning |
+| ---------- | ------- |
+| `root(name, system=…)` | Entry point. Chain `.model(id)` then `.do(child)`. |
+| `seq(*children)` | Run in order; fail fast (behavior-tree AND). |
+| `sel(*children)` | Try until one succeeds (behavior-tree OR). |
+| `repeat(child, until=…, max=n)` | Loop `child` until `until` succeeds or `max` passes (retry/refine). |
+| `invert(child)` · `optional(child)` | Decorators: flip a status · fail-soft (a failing step won't abort its `seq`). |
+| `timeout(child, seconds=…)` · `oneshot(child)` | Decorators: bound wall-clock time · run once per run, replay the status. |
+| `act(fn, *args)` | Leaf calling a `@tool`; literal args are type-checked. |
+| `ref("key")` | An `act` argument resolved from the blackboard at run time. |
+| `store(act(…), "key")` | Capture an action's return value onto the blackboard. |
+| `check("key", value)` | Guard leaf on `blackboard["key"]`; string matches are case/whitespace-lenient. |
+| `predict("a -> b")` | DSPy-style LLM leaf: reads inputs, writes outputs. |
+| `react("q -> a", tools=[…])` | Agentic leaf: the model calls `@tool`s in a loop (function-calling) until it answers. |
+
+## Layout
+
+```
+jdsl/          the runtime core — dsl, tree (interpreter), context, provider, render, cli
+  trace/       canonical trace events, sinks, storage, redaction, replay
+  ir/          Behavior IR: schema, safe guard expressions, validation, lowering
+  package/     .jdsl manifest, tool contracts, provenance, export + loader
+jdsl_harness/  capture + behavior compiler (separate package; optional [harness] extra)
+plugins/       Claude Code plugin + Gemini CLI extension (trace capture)
+examples/      runnable skills — see examples/README.md
+test/          pytest suite (no network; LLM leaves use fakes)
+docs/          concepts, API reference, providers, harness & compiler
+```
+
+## Behavior harness & compiler
+
+jdsl can also *compile* observed frontier-model behavior into portable policy a
+smaller frozen model runs. The harness captures canonical traces, mines and
+verifies reusable structure (exact dataflow, sequencing, guards, recovery), and
+leaves only irreducible semantic decisions as typed signatures — exported as a
+deterministic `.jdsl`.
+
+```bash
+jdsl harness serve                 # local capture daemon
+jdsl capture inspect <id>          # exact-lineage report
+jdsl compile <id> --out retail.jdsl
+jdsl package run retail.jdsl --tools tools.py --model <small-model>
+```
+
+See [docs/harness_usage.md](docs/harness_usage.md) for the hands-on guide (all
+three capture tiers, compile, verify, run) and [docs/harness.md](docs/harness.md)
+for the design-to-code map.
+
+## Docs
+
+- [docs/index.md](https://cantor-industries.github.io/jdsl-py/) — MkDocs homepage
+- [docs/quickstart.md](docs/quickstart.md) — install and first runs
+- [docs/examples.md](docs/examples.md) — guide to the runnable examples
+- [docs/concepts.md](docs/concepts.md) — behavior trees, the blackboard, signatures, why no codegen
+- [docs/api.md](docs/api.md) — full combinator + node reference
+- [docs/providers.md](docs/providers.md) — models, keys, `.env`, routing
+- [docs/tui.md](docs/tui.md) — skill authoring TUI
+- [docs/harness_usage.md](docs/harness_usage.md) — hands-on: capture, compile, verify, run
+- [docs/harness.md](docs/harness.md) — capture harness and behavior compiler overview
+- [docs/packages.md](docs/packages.md) — `.jdsl` package format and binding
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, tests, adding examples
+
+## Status
+
+Work in progress. The interpreter, combinator API, signatures, and the
+Anthropic / OpenAI-compatible (DeepSeek, OpenAI) backends run today. Not yet
+built: Google provider, and the DSPy-defining **optimization** step (tuning
+prompts against a metric) — the natural next direction now the runtime exists.
+
+## License
+
+O`Saasy · Author: Cantor Industries