rollout v0.3.0

divshekhar · divshekhar · commit 12701aaff42d · 2026-02-27T17:55:00.000+05:30
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,32 @@ All notable changes to this project will be 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).
 
+## [0.3.0] - 2026-02-27
+
+### Added
+
+- **Sub-agents & handoff** — `spawn(task=...)`, `handoff(AgentClass, task)` with optional memory transfer and budget inheritance.
+- **Handoff interception** — `events.before(Hook.HANDOFF_START, fn)`; raise `HandoffBlockedError` to block; `HandoffRetryRequested` for retry.
+- **Audit logging** — `AuditLog`, `JsonlAuditBackend`; `Agent(audit=...)`, `Pipeline(audit=...)`, `DynamicPipeline(audit=...)`.
+- **HITL** — `@syrin.tool(requires_approval=True)`; `ApprovalGate` protocol; hooks: HITL_PENDING, HITL_APPROVED, HITL_REJECTED.
+- **Circuit breaker** — `CircuitBreaker` for LLM/provider failures; CLOSED → OPEN → HALF_OPEN; configurable fallback.
+- **Budget-aware context** — Context tier selection by budget percent remaining.
+- **Dependency Injection** — `Agent(deps=...)`, `RunContext[Deps]`; tools receive `ctx.deps` (excluded from LLM schema).
+- **Dynamic Pipeline** — Improved hooks and events API; flow diagram in docs/dynamic-pipeline.md.
+- **Manual validation** — `docs/MANUAL_VALIDATION.md` with run commands for examples.
+
+### Changed
+
+- **API validation** — Agent, Model, Memory, Loop validate inputs at construction; clear errors for wrong types.
+- **agent.response(user_input)** — Validates `user_input` is `str`; friendly error for `None`/`int`/`dict`.
+- **Example paths** — Fixed run instructions (`08_streaming`, `07_multi_agent`).
+
+### Fixed
+
+- Chaos stress test fixes: Agent/Loop validation; Loop `max_iterations < 1` no longer causes UnboundLocalError. Model `_provider_kwargs` passed to provider.
+
+---
+
 ## [0.2.0] - 2026-02-26
 
 ### Added
diff --git a/README.md b/README.md
@@ -39,6 +39,8 @@
 
 Syrin gives you budgeting, thresholds, hooks, observability, context, memory, guardrails, and checkpoints in one lightweight library—so you can answer these questions instead of wondering.
 
+> **Jupyter / cookbook user?** Run [examples/getting_started.ipynb](examples/getting_started.ipynb) to see Syrin in action—install, run each cell, and explore.
+
 ---
 
 ## Comparison: Syrin vs. LangChain, LangGraph, AutoGen
@@ -85,7 +87,8 @@ print(f"Cost: ${result.cost:.4f}  |  Budget used: ${result.budget_used:.4f}")
 
 Pass your API key explicitly. The run is capped at $0.50; when the budget is exceeded, the agent stops.
 
-**No API key?** Examples and docs use `Model.Almock()` by default; comment it out and uncomment the real model when you have an API key.
+**No API key?** Examples and docs use `Model.Almock()` by default; swap to a real model when you have an API key.
+
 
 ---
 
diff --git a/docs/BREAKING_CHANGES_V0.3.0.md b/docs/BREAKING_CHANGES_V0.3.0.md
diff --git a/examples/07_multi_agent/README.md b/examples/07_multi_agent/README.md
@@ -1,4 +1,4 @@
-# 03_multi_agent — Multi-agent orchestration
+# 07_multi_agent — Multi-agent orchestration
 
 - **handoff.py** — Agent handoff between specialized agents
 - **spawn.py** — Parent spawns child agent (task vs no-task)
diff --git a/examples/07_multi_agent/__init__.py b/examples/07_multi_agent/__init__.py
@@ -1 +1 @@
-"""03_multi_agent — Multi-agent orchestration examples."""
+"""07_multi_agent — Multi-agent orchestration examples."""
diff --git a/examples/07_multi_agent/dynamic_pipeline_basic.py b/examples/07_multi_agent/dynamic_pipeline_basic.py
@@ -5,7 +5,7 @@
 - run(task, mode="parallel")
 - Basic orchestration without full debugging
 
-Run: python -m examples.03_multi_agent.dynamic_pipeline_basic
+Run: python -m examples.07_multi_agent.dynamic_pipeline_basic
 """
 
 from pathlib import Path
diff --git a/examples/07_multi_agent/dynamic_pipeline_full.py b/examples/07_multi_agent/dynamic_pipeline_full.py
@@ -10,8 +10,8 @@
 For key-less runs: set USE_ALMOCK=1 in .env (agents may not spawn; mock returns no plan).
 
 Run from repo root:
-  python -m examples.03_multi_agent.dynamic_pipeline_full
-  python examples/03_multi_agent/dynamic_pipeline_full.py
+  python -m examples.07_multi_agent.dynamic_pipeline_full
+  python examples/07_multi_agent/dynamic_pipeline_full.py
 """
 
 import os
diff --git a/examples/07_multi_agent/handoff.py b/examples/07_multi_agent/handoff.py
@@ -5,7 +5,7 @@
 - Context transfer via memory
 - Budget transfer between agents
 
-Run: python -m examples.03_multi_agent.handoff
+Run: python -m examples.07_multi_agent.handoff
 """
 
 from __future__ import annotations
diff --git a/examples/07_multi_agent/pipeline.py b/examples/07_multi_agent/pipeline.py
@@ -5,7 +5,7 @@
 - Parallel pipeline execution
 - Pipeline with budget
 
-Run: python -m examples.03_multi_agent.pipeline
+Run: python -m examples.07_multi_agent.pipeline
 """
 
 from __future__ import annotations
diff --git a/examples/07_multi_agent/spawn.py b/examples/07_multi_agent/spawn.py
@@ -5,7 +5,7 @@
 - spawn(task="...") returns Response
 - spawn() without task returns child Agent instance
 
-Run: python -m examples.03_multi_agent.spawn
+Run: python -m examples.07_multi_agent.spawn
 """
 
 from __future__ import annotations
diff --git a/examples/08_streaming/README.md b/examples/08_streaming/README.md
@@ -1,4 +1,4 @@
-# 05_streaming — Streaming output
+# 08_streaming — Streaming output
 
 - **stream_sync.py** — agent.stream() for synchronous token-by-token output
 - **stream_async.py** — agent.astream() for async streaming
diff --git a/examples/08_streaming/__init__.py b/examples/08_streaming/__init__.py
@@ -1 +1 @@
-"""05_streaming — Streaming output examples."""
+"""08_streaming — Streaming output examples."""
diff --git a/examples/08_streaming/stream_async.py b/examples/08_streaming/stream_async.py
@@ -4,7 +4,7 @@
 - agent.astream(input) for async token-by-token output
 - async for chunk in agent.astream(...)
 
-Run: python -m examples.05_streaming.stream_async
+Run: python -m examples.08_streaming.stream_async
 """
 
 import asyncio
diff --git a/examples/08_streaming/stream_sync.py b/examples/08_streaming/stream_sync.py
@@ -5,7 +5,7 @@
 - Collecting chunks into full text
 - StreamChunk properties (index, text, is_final)
 
-Run: python -m examples.05_streaming.stream_sync
+Run: python -m examples.08_streaming.stream_sync
 """
 
 from pathlib import Path
diff --git a/examples/getting_started.ipynb b/examples/getting_started.ipynb
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# 03_multi_agent — Multi-agent orchestration`
	`1`	`+# 07_multi_agent — Multi-agent orchestration`
`2`	`2`
`3`	`3`	`- handoff.py — Agent handoff between specialized agents`
`4`	`4`	`- spawn.py — Parent spawns child agent (task vs no-task)`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-"""03_multi_agent — Multi-agent orchestration examples."""`
	`1`	`+"""07_multi_agent — Multi-agent orchestration examples."""`