future-agi · azain-commits · Aug 18, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 29, 2026
diff --git a/.github/workflows/sdk-smoke.yml b/.github/workflows/sdk-smoke.yml
@@ -0,0 +1,43 @@
+name: SDK smoke
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  clean-install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install package
+        run: python -m pip install .
+      - name: Run doctor
+        run: agent-learn doctor --quiet
+      - name: Run local text simulation
+        env:
+          AGENT_LEARNING_RUN_EXAMPLE_KEY: smoke
+        run: >-
+          agent-learn simulation run examples/run_manifest.json
+          --output smoke-report.json --quiet
+      - name: Verify simulation report
+        run: >-
+          python -c "import json, pathlib;
+          report=json.loads(pathlib.Path('smoke-report.json').read_text());
+          assert report['status'] == 'ran' and report['report']['results']"
+      - name: Install test dependencies
+        run: python -m pip install '.[livekit]' pytest pytest-asyncio
+      - name: Run engine + dispatch + acceptance tests
+        # Scoped to the suites this PR adds/relies on. The broader tests/ tree has
+        # pre-existing failures unrelated to the voice engine (CLI golden-path,
+        # init presets, plus test_config_and_facades hangs) — track those
+        # separately so this gate stays green and meaningful.
+        run: >-
+          python -m pytest -q
+          tests/runtime/test_livekit_engine.py
+          tests/runtime/test_manifest_engine_dispatch.py
+          tests/test_acceptance_regressions.py
diff --git a/.gitignore b/.gitignore
@@ -13,5 +13,8 @@ coverage/
 .DS_Store
 .env
 .env.*
+!**/.env.example
 artifacts/
+!src/fi/simulate/artifacts/
+!src/fi/simulate/artifacts/*.py
 examples/artifacts/
diff --git a/README.md b/README.md
@@ -98,6 +98,11 @@ Then run the golden path against the bundled example manifests. The
 `required_env` list — that list is CI wiring metadata, not a provider
 credential, so any placeholder value works.
 
+> Prefer the SDK spine over the CLI?
+> [Spec + Runner](docs/simulate/spec-and-runner.md) runs the same simulation as
+> one `SimulationSpec` fed to one `SimulationRunner` — the plug-and-play surface
+> behind every simulation.
+
 Evaluate a suite:
 
 ```bash

diff --git a/docs/cookbooks/index.md b/docs/cookbooks/index.md
@@ -22,7 +22,7 @@ opt_in_lane: false
 
 | | Behavior | Capability | Reliability | Safety |
 | --- | --- | --- | --- | --- |
-| **simulate** | [golden-path-run](../quickstart/golden-path-run.md) · [first-run](../simulate/first-run.md) · [worlds-and-hooks](../simulate/worlds-and-hooks.md) | [simulate-any-framework](../simulate/simulate-any-framework.md) · [memory](../simulate/memory.md) · [multimodal-image](../simulate/multimodal-image.md) · [voice-realtime](../simulate/voice-realtime.md) · [langchain](../frameworks/langchain.md) · [langgraph](../frameworks/langgraph.md) · [llamaindex](../frameworks/llamaindex.md) · [autogen](../frameworks/autogen.md) · [crewai](../frameworks/crewai.md) · [openai-agents](../frameworks/openai-agents.md) · [pydantic-ai](../frameworks/pydantic-ai.md) · [livekit](../frameworks/livekit.md) · [pipecat](../frameworks/pipecat.md) · [browser-use](../frameworks/browser-use.md) · [mcp](../frameworks/mcp.md) · [a2a](../frameworks/a2a.md) · [custom](../frameworks/custom.md) · [openenv](../frameworks/openenv.md) · [persona-scenario-studio](../simulate/persona-scenario-studio.md) | [multi-agent](../simulate/multi-agent.md) · [orchestration](../simulate/orchestration.md) | [golden-path-redteam](../quickstart/golden-path-redteam.md) · [red-team-anything](../redteam/red-team-anything.md) · [corpus](../redteam/corpus.md) · [first-campaign](../redteam/first-campaign.md) · [stored-prompt-injection](../redteam/stored-prompt-injection.md) · [long-horizon](../redteam/long-horizon.md) · [autonomous-task-world](../redteam/autonomous-task-world.md) · [persona-conditioned-attacks](../redteam/persona-conditioned-attacks.md) |
+| **simulate** | [golden-path-run](../quickstart/golden-path-run.md) · [spec-and-runner](../simulate/spec-and-runner.md) · [first-run](../simulate/first-run.md) · [worlds-and-hooks](../simulate/worlds-and-hooks.md) | [simulate-any-framework](../simulate/simulate-any-framework.md) · [memory](../simulate/memory.md) · [multimodal-image](../simulate/multimodal-image.md) · [voice-realtime](../simulate/voice-realtime.md) · [langchain](../frameworks/langchain.md) · [langgraph](../frameworks/langgraph.md) · [llamaindex](../frameworks/llamaindex.md) · [autogen](../frameworks/autogen.md) · [crewai](../frameworks/crewai.md) · [openai-agents](../frameworks/openai-agents.md) · [pydantic-ai](../frameworks/pydantic-ai.md) · [livekit](../frameworks/livekit.md) · [pipecat](../frameworks/pipecat.md) · [browser-use](../frameworks/browser-use.md) · [mcp](../frameworks/mcp.md) · [a2a](../frameworks/a2a.md) · [custom](../frameworks/custom.md) · [openenv](../frameworks/openenv.md) · [persona-scenario-studio](../simulate/persona-scenario-studio.md) | [multi-agent](../simulate/multi-agent.md) · [orchestration](../simulate/orchestration.md) | [golden-path-redteam](../quickstart/golden-path-redteam.md) · [red-team-anything](../redteam/red-team-anything.md) · [corpus](../redteam/corpus.md) · [first-campaign](../redteam/first-campaign.md) · [stored-prompt-injection](../redteam/stored-prompt-injection.md) · [long-horizon](../redteam/long-horizon.md) · [autonomous-task-world](../redteam/autonomous-task-world.md) · [persona-conditioned-attacks](../redteam/persona-conditioned-attacks.md) |
 | **evaluate** | [evaluate-any-task](../eval/evaluate-any-task.md) · [eval-suites](../eval/eval-suites.md) · [artifact-evals](../eval/artifact-evals.md) | [task-evidence](../eval/task-evidence.md) · [eval-hooks](../eval/eval-hooks.md) · [benchmark-overview](../eval/benchmark-overview.md) · [benchmark-coding](../eval/benchmark-coding.md) · [benchmark-voice](../eval/benchmark-voice.md) · [benchmark-pull-rl](../eval/benchmark-pull-rl.md) · [benchmark-write-a-suite](../eval/benchmark-write-a-suite.md) | [judge-reliability](../eval/judge-reliability.md) · [persona-fidelity](../simulate/persona-fidelity.md) · [benchmark-command-graded](../eval/benchmark-command-graded.md) | [causal-attribution](../redteam/causal-attribution.md) · [benchmark-sandboxes](../eval/benchmark-sandboxes.md) |
 | **optimize** | [golden-path-optimize](../quickstart/golden-path-optimize.md) · [optimize-any-agent](../optimize/optimize-any-agent.md) · [optimization-lifecycle](../optimize/optimization-lifecycle.md) · [behavior-and-collaboration](../optimize/behavior-and-collaboration.md) | [world-model](../optimize/world-model.md) · [memory-targets](../optimize/memory-targets.md) · [workflow-profile-matrix](../optimize/workflow-profile-matrix.md) · [optimizer-profile-matrix](../optimize/optimizer-profile-matrix.md) · [agent-control-plane](../optimize/agent-control-plane.md) | [governance](../optimize/governance.md) · [optimizer-portfolio](../optimize/optimizer-portfolio.md) · [backend-routing](../optimize/backend-routing.md) · [multi-agent-targets](../optimize/multi-agent-targets.md) · [eval-suite-optimization](../optimize/eval-suite-optimization.md) | [society-of-agents](../optimize/society-of-agents.md) · [campaign-optimization](../redteam/campaign-optimization.md) · [adaptive-loop](../redteam/adaptive-loop.md) |
 | **promote** | [regression-lifecycle](../simulate/regression-lifecycle.md) | [promote-to-regression](../redteam/promote-to-regression.md) | [golden-path-ci](../quickstart/golden-path-ci.md) · [attack-evolution-shrink](../redteam/attack-evolution-shrink.md) · [capability-profile-freezing](../optimize/capability-profile-freezing.md) | [promote-to-regression](../redteam/promote-to-regression.md) |

diff --git a/docs/index.md b/docs/index.md
@@ -47,7 +47,7 @@ same set `docs/llms.txt` lists) is [cookbooks/index.md](cookbooks/index.md).
 
 | | Behavior | Capability | Reliability | Safety |
 | --- | --- | --- | --- | --- |
-| **simulate** | [first-run](simulate/first-run.md) · [worlds-and-hooks](simulate/worlds-and-hooks.md) | [simulate-any-framework](simulate/simulate-any-framework.md) · 14 [framework pages](cookbooks/index.md#by-framework) | [multi-agent](simulate/multi-agent.md) · [orchestration](simulate/orchestration.md) | [first-campaign](redteam/first-campaign.md) · [stored-prompt-injection](redteam/stored-prompt-injection.md) |
+| **simulate** | [spec-and-runner](simulate/spec-and-runner.md) · [first-run](simulate/first-run.md) · [worlds-and-hooks](simulate/worlds-and-hooks.md) | [simulate-any-framework](simulate/simulate-any-framework.md) · 14 [framework pages](cookbooks/index.md#by-framework) | [multi-agent](simulate/multi-agent.md) · [orchestration](simulate/orchestration.md) | [first-campaign](redteam/first-campaign.md) · [stored-prompt-injection](redteam/stored-prompt-injection.md) |
 | **evaluate** | [eval-suites](eval/eval-suites.md) · [artifact-evals](eval/artifact-evals.md) | [task-evidence](eval/task-evidence.md) | [judge-reliability](eval/judge-reliability.md) | [causal-attribution](redteam/causal-attribution.md) |
 | **optimize** | [optimization-lifecycle](optimize/optimization-lifecycle.md) | [workflow-profile-matrix](optimize/workflow-profile-matrix.md) | [governance](optimize/governance.md) · [optimizer-portfolio](optimize/optimizer-portfolio.md) | [society-of-agents](optimize/society-of-agents.md) |
 | **promote** | [regression-lifecycle](simulate/regression-lifecycle.md) | [promote-to-regression](redteam/promote-to-regression.md) | [attack-evolution-shrink](redteam/attack-evolution-shrink.md) | [promote-to-regression](redteam/promote-to-regression.md) |

diff --git a/docs/llms.txt b/docs/llms.txt
@@ -37,6 +37,7 @@
 - [Persona & Scenario Studio: typed test cases you can measure](docs/simulate/persona-scenario-studio.md): twin=examples/sdk_persona_scenario_studio.py kind=agent-learning.persona-library.v1
 - [The Regression Lifecycle: baseline, compare, promote, replay, shrink](docs/simulate/regression-lifecycle.md): twin=examples/sdk_regression_artifact_suite.py kind=agent-learning.baseline.v1
 - [Simulate Any Framework](docs/simulate/simulate-any-framework.md): twin=examples/sdk_multi_framework_simulation.py kind=agent-learning.suite.v1
+- [The Simulation Spine — One Spec, One Runner](docs/simulate/spec-and-runner.md): twin=examples/sdk_spec_runner_quickstart.py kind=none
 - [Voice loopback: the deterministic audio channel, credential-free](docs/simulate/voice-loopback.md): twin=examples/sdk_voice_loopback.py kind=agent-learning.run.v1
 - [Voice and Realtime: simulate the session before you dial it](docs/simulate/voice-realtime.md): twin=examples/sdk_framework_adapter_realtime_trace.py kind=agent-learning.run.v1
 - [Worlds and Hooks: simulate against executable state](docs/simulate/worlds-and-hooks.md): twin=examples/sdk_world_hooks_optimization.py kind=agent-learning.optimization.v1

diff --git a/docs/simulate/first-run.md b/docs/simulate/first-run.md
@@ -23,6 +23,10 @@ opt_in_lane: false
 > · emits `agent-learning.run.v1` · offline, no credentials.
 > A coding agent can complete this page from the frontmatter alone.
 
+> **New here?** This page is the manifest/CLI front door. To see the same run
+> as the underlying `SimulationSpec` + `SimulationRunner` — the spine every
+> simulation flows through — start with [Spec + Runner](spec-and-runner.md).
+
 ## 1. What you are testing
 
 A simulation run is the kit's atomic unit: one manifest in, one

diff --git a/docs/simulate/spec-and-runner.md b/docs/simulate/spec-and-runner.md
@@ -0,0 +1,134 @@
+---
+kind: agent-learning.docs-page.v1
+track: simulate
+objective: behavior
+stage: simulate
+backing:
+  - examples/sdk_spec_runner_quickstart.py
+artifact_kinds: []
+commands:
+  - python examples/sdk_spec_runner_quickstart.py artifacts/spec-and-runner.json
+postcondition: python -c "import json; p=json.load(open('artifacts/spec-and-runner.json')); assert 'COMPLETED' in p['status'], p['status']; print('ok')"
+claims: []
+doctor_checks:
+  - missing_engine_modules
+  - public_boundary_passed
+opt_in_lane: false
+---
+
+# The Simulation Spine — One Spec, One Runner
+
+> **Twin:** [`examples/sdk_spec_runner_quickstart.py`](../../examples/sdk_spec_runner_quickstart.py)
+> · offline, no credentials.
+> For the full end-to-end tour (real LLM, voice, platform submit, custom
+> worlds) see [`examples/agent_learning_sdk_demo_v2.ipynb`](../../examples/agent_learning_sdk_demo_v2.ipynb).
+
+Under the manifest and CLI surfaces, every simulation — chat, voice, or a
+custom world — runs through **one** spine: a frozen `SimulationSpec` fed to
+**one** `SimulationRunner`. Providers, environments, and agent kinds are
+registry entries, not hardcoded branches. This page runs the smallest version of
+that spine directly, so the moving parts are visible.
+
+| Piece | In the SDK | You supply |
+| --- | --- | --- |
+| **Environment** | a registered plugin (`chat`, `voice`, or your own) that owns the world + action space | pick one, or `@register_environment` your own |
+| **Target** | an ActorSource (`system_prompt` \| callable \| `factory` \| `http` \| `framework`), or any object with `.call()` | drop in your agent |
+| **Scenario** | personas + situations + desired outcomes | describe the test |
+| **Contract** | a frozen `SimulationSpec` tying the three together | declarative, secret-free |
+| **Runner** | one `SimulationRunner` — same spine for chat and voice | `.run(spec, target=...)` |
+
+## 1. Install and check
+
+```bash
+git clone https://github.com/future-agi/agent-learning-kit
+cd agent-learning-kit
+uv sync                     # or: pip install -e .
+uv run agent-learn doctor   # status: passed
+```
+
+## 2. Run the smallest simulation
+
+A synthetic user drives a conversation against a plain `.call()` target through
+the runner. No API key, no network.
+
+```python
+import asyncio
+import fi.alk.simulate as S
+from fi.simulate.agent.wrapper import AgentInput, AgentResponse
+
+
+class EchoAgent:
+    async def call(self, agent_input: AgentInput) -> AgentResponse:
+        last = agent_input.messages[-1]["content"] if agent_input.messages else "hi"
+        return AgentResponse(content=f"You said: {last}. How can I help further?")
+
+
+async def main():
+    print(sorted(S.environment_registry.names()))   # ['chat', 'voice']
+    spec = S.SimulationSpec(
+        run_id="spec_runner_quickstart",
+        environment=S.EnvironmentSpec(
+            adapter=S.EnvironmentAdapters.CHAT,
+            world_kind=S.WorldKinds.CONVERSATION,
+            config={"max_turns": 3, "min_turns": 1},
+        ),
+        target=S.AgentEndpointSpec(adapter=S.TargetAdapters.CALLABLE),
+        simulator=S.SimulatorPolicySpec(adapter=S.SimulatorAdapters.SYNTHETIC_USER),
+        scenario=S.Scenario(name="late-delivery", dataset=[
+            S.Persona(persona={"name": "Morgan", "role": "customer"},
+                      situation="A delivery is 3 days late; ask for status and ETA.",
+                      outcome="Get a clear status and a concrete next step.")]),
+    )
+    report = await S.SimulationRunner().run(spec, target=EchoAgent())
+    print(report.status)
+    print(report.test_cases[0].result.transcript)
+
+
+asyncio.run(main())
+```
+
+The backing twin is the same run, writing the finished report to a path:
+
+```bash
+python examples/sdk_spec_runner_quickstart.py artifacts/spec-and-runner.json
+python -c "import json; p=json.load(open('artifacts/spec-and-runner.json')); assert 'COMPLETED' in p['status']; print('ok')"
+```
+
+Every adapter slot accepts the enum (`S.EnvironmentAdapters.CHAT`) **or** the
+plain string it equals (`"chat"`) — same `spec_hash`. Enums give you
+autocomplete and typo-safety for the built-ins; custom registered names stay
+plain strings.
+
+## 3. Drop in your own agent
+
+`EchoAgent` was passed straight to the runner. Every other way you'd hand the
+kit an agent is an ActorSource resolved through one registry — you declare what
+you have, you never edit the engine:
+
+```python
+S.get_profile("system_prompt").resolve_target({"system_prompt": "...", "model": "gpt-4o"})
+S.get_profile("factory").resolve_target({"target": "mypkg.agents:Support", "factory": True})
+S.get_profile("http").resolve_target({"url": "https://my-agent/turn"})
+S.get_profile("framework").resolve_target({"target": "mypkg:graph"})   # LangGraph / CrewAI / ...
+```
+
+Code-loading kinds (`factory`, `import_object`, `framework`, callable) carry
+`runs_caller_code == True` and are deny-by-default in hosted runs — locally they
+resolve in-process, hosted they route through the sandbox. `http` and
+`system_prompt` are the hosted-safe kinds. Check with
+`S.get_profile("http").runs_caller_code`.
+
+## 4. Where to go next
+
+| Task | Spec + Runner API |
+| --- | --- |
+| Real-LLM chat | `SimulationRunner().run(spec, target=your_llm_object)` |
+| Voice (Vapi / Retell / WebRTC) | `SimulationRunner().run(voice_spec)` — see the v2 notebook §7 |
+| Score a run | `evaluate_agent_report(report.to_legacy())` |
+| Register your own world | `@register_environment("name")` |
+| Submit to the platform | `result_sink=FutureAGIResultSink(...)` |
+
+- Full runnable tour: [`examples/agent_learning_sdk_demo_v2.ipynb`](../../examples/agent_learning_sdk_demo_v2.ipynb).
+- The older manifest/CLI front door: [`first-run.md`](first-run.md) — same
+  concepts, assembled into a `SimulationSpec` underneath.
+- Frameworks as targets: [`simulate-any-framework.md`](simulate-any-framework.md).