agentensemble 0.2.0__tar.gz → 0.4.0__tar.gz

agentensemble-0.4.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to AgentEnsemble will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-31
+
+### Fixed
+- `ReActAgent` can now be constructed without `MISTRAL_API_KEY` (matching `HybridAgent` and
+  `RouterAgent`); `run()` / `astream()` raise a clear `RuntimeError` until an LLM is configured.
+  Previously the constructor raised `ValueError`, which broke 6 tests and any offline usage.
+- `SearchTool`'s DuckDuckGo fallback works again: `langchain-community` now needs the `ddgs`
+  package (the `search` extra previously installed the old `duckduckgo-search`).
+- `SearchTool` creates its backend lazily on first use, so it can be registered in a
+  `ToolRegistry` without optional dependencies; a missing backend raises an `ImportError` with
+  the `pip install 'agentensemble[search]'` hint. Unknown providers still fail fast.
+- Tool schema type inference uses identity checks (`ann is str`), not equality.
+
+### Added
+- `MISTRAL_MODEL` environment variable to choose the default model for `MistralLLMProvider`.
+- `__version__` read from installed package metadata (`importlib.metadata`).
+- GitHub Actions CI (ruff lint + format check, pytest on Python 3.10–3.13).
+- New tests: ReActAgent tool-calling loop with a fake LLM, SearchTool behaviour, version, model
+  override (64 tests total).
+- SECURITY.md, CODE_OF_CONDUCT.md, issue/PR templates, Dependabot, CITATION.cff.
+
+### Changed
+- Requires Python 3.10+ (3.9 is end-of-life); classifiers for 3.10–3.13.
+- Packaging is `pyproject.toml`-only (removed `setup.py` and `requirements.txt`), PEP 639
+  `license = "MIT"`, LICENSE and CHANGELOG shipped in the sdist.
+- Dependency floors raised to the versions the code actually needs: `langchain>=1.1`,
+  `langchain-core>=1.0`, `langchain-community>=0.3`, `langchain-mistralai>=0.2`. The unused
+  direct `langgraph` dependency was dropped (it is still installed transitively by `langchain`).
+- `dev` extra now includes `build` and `twine`; `black` replaced by `ruff format`.
+- Codebase formatted with `ruff format` and modernised type hints (`X | None`).
+
+## [0.3.0] - 2026-03-10
+
+### Added
+- Observability (`TraceHooks`, token usage, cost estimation), human-in-the-loop
+  (`interrupt_before_tools`), architecture diagram.
+
+## [0.2.0] - 2026-03-10
+
+### Added
+- `RouterAgent`, `PlannerAgent`, `WorkflowGraph`, tracing.
+
+## [0.1.0] - 2025-12-09
+
+### Added
+- Initial release
+- ReActAgent implementation
+- StateGraphAgent implementation
+- RAGAgent with fallback strategies
+- HybridAgent with intelligent routing
+- Ensemble orchestration patterns (Supervisor, Swarm, Pipeline)
+- Tool ecosystem (Search, Scraper, RAG, Validator)
+- Tool registry for centralized management
+- Testing framework (AgentComparison, Benchmark, Metrics)
+- Base agent class and state management
+- Comprehensive documentation
+
+### Infrastructure
+- Python 3.9+ support
+- pyproject.toml for modern packaging
+- Development dependencies (pytest, black, ruff, mypy)
+- MIT License
+- Contributing guidelines
+

agentensemble-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Irfan Ali
+
+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.
+
+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.

{agentensemble-0.2.0 → agentensemble-0.4.0}/MANIFEST.in

@@ -1,6 +1,6 @@
 include README.md
+include LICENSE
+include CHANGELOG.md
 include pyproject.toml
 recursive-include agentensemble *.py
 recursive-include agentensemble py.typed
-exclude LICENSE
-

{agentensemble-0.2.0/agentensemble.egg-info → agentensemble-0.4.0}/PKG-INFO

@@ -1,41 +1,47 @@
 Metadata-Version: 2.4
 Name: agentensemble
-Version: 0.2.0
-Summary: Orchestrate AI agents in perfect harmony - A comprehensive Python framework for building, testing, and orchestrating multi-agent AI systems
+Version: 0.4.0
+Summary: Build, orchestrate, trace, and test multi-agent LLM systems in Python: ReAct, RAG, router, planner, workflow graphs, swarms, debates, and pipelines.
 Author-email: Irfan Ali <irfanali29@hotmail.com>
 Maintainer-email: Irfan Ali <irfanali29@hotmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/irfanalidv/AgentEnsemble
 Project-URL: Documentation, https://github.com/irfanalidv/AgentEnsemble#readme
 Project-URL: Repository, https://github.com/irfanalidv/AgentEnsemble
 Project-URL: Issues, https://github.com/irfanalidv/AgentEnsemble/issues
-Keywords: ai-agents,multi-agent,orchestration,langgraph,langchain,rag,agent-testing,agentic-ai,state-graph,react-agent
-Classifier: Development Status :: 3 - Alpha
+Project-URL: Changelog, https://github.com/irfanalidv/AgentEnsemble/blob/main/CHANGELOG.md
+Keywords: ai-agents,multi-agent,multi-agent-systems,agent-orchestration,orchestration,llm,langchain,langgraph,mistral,rag,react-agent,tool-calling,function-calling,agent-testing,agentic-ai,state-graph,workflow,tracing
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: langchain>=0.1.0
-Requires-Dist: langchain-core>=0.1.0
-Requires-Dist: langchain-community>=0.0.20
-Requires-Dist: langchain-mistralai>=0.1.0
-Requires-Dist: langgraph>=0.0.20
+License-File: LICENSE
+Requires-Dist: langchain>=1.1.0
+Requires-Dist: langchain-core>=1.0.0
+Requires-Dist: langchain-community>=0.3.0
+Requires-Dist: langchain-mistralai>=0.2.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: typing-extensions>=4.5.0
 Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
-Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
 Provides-Extra: observability
 Requires-Dist: langsmith>=0.1.0; extra == "observability"
 Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
@@ -44,23 +50,93 @@ Requires-Dist: chromadb>=0.4.0; extra == "rag"
 Requires-Dist: sentence-transformers>=2.2.0; extra == "rag"
 Requires-Dist: langchain-text-splitters>=0.0.1; extra == "rag"
 Requires-Dist: beautifulsoup4>=4.12.0; extra == "rag"
-Requires-Dist: langchain-mistralai>=0.1.0; extra == "rag"
 Provides-Extra: search
-Requires-Dist: duckduckgo-search>=4.0.0; extra == "search"
+Requires-Dist: ddgs>=9.0.0; extra == "search"
 Requires-Dist: google-search-results>=2.4.2; extra == "search"
 Provides-Extra: all
-Requires-Dist: agentensemble[dev,observability,rag,search]; extra == "all"
+Requires-Dist: agentensemble[observability,rag,search]; extra == "all"
+Dynamic: license-file
+
+<div align="center">
 
 # AgentEnsemble
 
-**Production-ready multi-agent orchestration for Python**
+**Build, orchestrate, trace, and test multi-agent LLM systems in Python.**
 
-AgentEnsemble is a modern framework for building and orchestrating AI agent systems. Designed for clarity, extensibility, and production use—comparable to LangGraph, CrewAI, and AutoGen.
+ReAct, RAG, router, planner, workflow graphs, swarms, debates, and pipelines, with sessions,
+tracing, retries, and human-in-the-loop approval built in.
 
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![PyPI version](https://img.shields.io/pypi/v/agentensemble)](https://pypi.org/project/agentensemble/)
+[![PyPI version](https://img.shields.io/pypi/v/agentensemble.svg)](https://pypi.org/project/agentensemble/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentensemble.svg)](https://pypi.org/project/agentensemble/)
+[![Tests](https://github.com/irfanalidv/AgentEnsemble/actions/workflows/tests.yml/badge.svg)](https://github.com/irfanalidv/AgentEnsemble/actions/workflows/tests.yml)
 [![PyPI Downloads](https://static.pepy.tech/badge/agentensemble)](https://pepy.tech/projects/agentensemble)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/irfanalidv/AgentEnsemble/blob/main/LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+</div>
+
+---
+
+AgentEnsemble is a framework for building and orchestrating AI agent systems, designed for clarity,
+extensibility, and production use. It covers similar ground to LangGraph, CrewAI, and AutoGen.
+
+## Installation
+
+```bash
+pip install agentensemble                 # core: agents, orchestration, graphs, memory, tracing
+pip install "agentensemble[search]"       # + DuckDuckGo / Serper web search for SearchTool
+pip install "agentensemble[rag]"          # + Chroma, sentence-transformers, loaders for RAGTool
+pip install "agentensemble[observability]" # + LangSmith / OpenTelemetry
+pip install "agentensemble[all]"          # everything above
+```
+
+Requires Python 3.10+.
+
+## Quick start (no API key needed)
+
+Graph workflows, state-graph agents, and the planner run without any LLM:
+
+```python
+from agentensemble import WorkflowGraph
+
+
+def analyze(s):
+    return {"context": {**s.get("context", {}), "done": True}, "current_node": "summarize"}
+
+
+def summarize(s):
+    return {"result": f"Summary for: {s['query']}", "current_node": "end"}
+
+
+graph = (
+    WorkflowGraph(entry="start", exit_nodes=["end"])
+    .add_node("start", lambda s: {"current_node": "analyze"})
+    .add_node("analyze", analyze)
+    .add_node("summarize", summarize)
+    .add_edge("start", "analyze")
+    .add_edge("analyze", "summarize")
+    .add_edge("summarize", "end")
+)
+print(graph.run("What is multi-agent AI?")["result"])
+# Summary for: What is multi-agent AI?
+```
+
+LLM-powered agents (`ReActAgent`, `HybridAgent`, `RouterAgent`, `StructuredAgent`) use Mistral by
+default. Set `MISTRAL_API_KEY`, or pass any `LLMProvider` implementation via `llm=...`.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `MISTRAL_API_KEY` | Required for the default Mistral LLM provider (ReAct, Hybrid, Router, Structured agents). |
+| `MISTRAL_MODEL` | Optional default model for `MistralLLMProvider` (default: `mistral-large-latest`). Use e.g. `mistral-small-latest` if your plan doesn't include the large model. |
+| `SERPER_API_KEY` | Optional. When set, `SearchTool()` uses Serper; otherwise it falls back to DuckDuckGo (needs the `search` extra). |
+
+Copy `.env.example` to `.env` and fill in your keys (`KEY=value`, no spaces around `=`); the
+package loads `.env` automatically via `python-dotenv`.
+
+Without an API key, LLM agents can still be constructed (and inspected or registered); calling
+`run()` raises a clear `RuntimeError` explaining how to configure an LLM.
 
 ---
 
@@ -76,33 +152,51 @@ AgentEnsemble is a modern framework for building and orchestrating AI agent syst
 ## Architecture
 
 <p align="center">
-  <img src="docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="800"/>
+  <img src="https://raw.githubusercontent.com/irfanalidv/AgentEnsemble/main/docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="900"/>
 </p>
 
-*Architecture, functionalities, and use cases — what AgentEnsemble is capable of.*
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        AgentEnsemble                             │
-├─────────────┬─────────────┬─────────────┬───────────────────────┤
-│   Agents    │ Orchestration│   Tools     │ Memory & Runner       │
-├─────────────┼─────────────┼─────────────┼───────────────────────┤
-│ ReActAgent  │ Ensemble    │ SearchTool  │ Session (InMemory,    │
-│ StateGraph  │ Supervisor  │ RAGTool     │ SQLite)               │
-│ RAGAgent    │ Swarm       │ @function_  │ Runner + RunConfig    │
-│ HybridAgent │ Pipeline    │ tool        │ TraceHooks            │
-│ RouterAgent │ Debate      │ Validation  │                       │
-│ PlannerAgent│             │             │                       │
-└─────────────┴─────────────┴─────────────┴───────────────────────┘
-```
+### Framework layers
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│                              AgentEnsemble — Layered Architecture                          │
+├─────────────────┬─────────────────────┬─────────────────────┬────────────────────────────┤
+│     AGENTS      │   ORCHESTRATION      │       TOOLS         │    MEMORY & RUNNER          │
+├─────────────────┼─────────────────────┼─────────────────────┼────────────────────────────┤
+│ ReActAgent      │ Supervisor          │ SearchTool          │ Session (InMemory, SQLite)  │
+│ StateGraphAgent │ Swarm (parallel)    │ RAGTool             │ RunConfig, RunHooks        │
+│ RAGAgent        │ Pipeline (seq)     │ @function_tool      │ TraceHooks (usage, cost)    │
+│ HybridAgent     │ Debate (consensus)  │ ValidationTool      │ interrupt_before_tools      │
+│ RouterAgent     │ Ensemble + Router   │ ToolRegistry         │ retries, session memory     │
+│ PlannerAgent    │ WorkflowGraph       │                     │                             │
+└─────────────────┴─────────────────────┴─────────────────────┴────────────────────────────┘
+         │                    │                    │                         │
+         └────────────────────┴────────────────────┴─────────────────────────┘
+                                          │
+                              ┌───────────▼───────────┐
+                              │   Use Case Spectrum   │
+                              └───────────────────────┘
+```
+
+### Use case spectrum
+
+| Layer | Use cases |
+|-------|-----------|
+| **Research & fact-checking** | ReActAgent + SearchTool; Swarm for parallel verification |
+| **Document Q&A** | RAGAgent + RAGTool; index URLs, ask questions |
+| **Multi-agent coordination** | Supervisor, Swarm, Pipeline; RouterAgent for LLM-based selection |
+| **Debate & consensus** | DebateOrchestrator; solvers propose → aggregator votes |
+| **Custom workflows** | WorkflowGraph (DAG), StateGraphAgent (nodes), PlannerAgent (decompose) |
+| **Human-in-loop** | `interrupt_before_tools` — pause before sensitive tools, resume with approval |
+| **Production pipelines** | Runner + RunConfig, retries, TraceHooks (usage/cost), Session memory |
 
 ---
 
-## Quick Start
+## LLM quick start
 
 ```bash
-pip install agentensemble
-# Optional: pip install agentensemble[search,rag]
+pip install "agentensemble[search]"
+export MISTRAL_API_KEY=...
 ```
 
 ```python
@@ -119,7 +213,7 @@ print(result["result"])
 
 ## Examples — Code + Output
 
-Each example is runnable. Requires `.env` with `MISTRAL_API_KEY` and `SERPER_API_KEY` (see `.env.example` for format).
+Each example is runnable. Requires `MISTRAL_API_KEY` (and the `search` extra for `SearchTool`; `SERPER_API_KEY` is optional). Outputs below are from the author's runs; LLM answers will vary.
 
 ---
 
@@ -148,10 +242,12 @@ enable machine learning with artificial neural networks.
 ```python
 from agentensemble import ReActAgent, SearchTool, function_tool
 
+
 @function_tool(description="Get current weather for a city")
 def get_weather(city: str) -> str:
     return f"Weather in {city}: 72°F, partly cloudy"
 
+
 agent = ReActAgent(tools=[SearchTool(), get_weather], max_iterations=4)
 result = agent.run("What is the weather in Paris?")
 print(result["result"])
@@ -264,7 +360,9 @@ researcher = ReActAgent(name="researcher", tools=[SearchTool()], max_iterations=
 validator = ReActAgent(name="validator", tools=[SearchTool()], max_iterations=2)
 
 router = RouterAgent(agents={"researcher": researcher, "validator": validator})
-ensemble = Ensemble(conductor="supervisor", agents={"researcher": researcher, "validator": validator}, router=router)
+ensemble = Ensemble(
+    conductor="supervisor", agents={"researcher": researcher, "validator": validator}, router=router
+)
 result = ensemble.perform("Latest developments in quantum computing")
 for name, r in result["results"].items():
     print(f"Routed to {name}: {r['result'][:120]}...")
@@ -284,9 +382,11 @@ Routed to researcher: Here are the latest developments in quantum computing:
 ```python
 from agentensemble import PlannerAgent, StateGraphAgent
 
+
 def worker(state):
     return {"result": f"Processed: {state.query}"}
 
+
 executor = StateGraphAgent(name="worker", nodes={"start": worker})
 executor._route = lambda s, c: "end"
 
@@ -311,12 +411,15 @@ Result: Processed: Search for information... --- Processed: Summarize key findin
 ```python
 from agentensemble import WorkflowGraph
 
+
 def analyze(s):
     return {"context": {**s.get("context", {}), "done": True}, "current_node": "summarize"}
 
+
 def summarize(s):
     return {"result": f"Summary for: {s['query']}", "current_node": "end"}
 
+
 graph = (
     WorkflowGraph(entry="start", exit_nodes=["end"])
     .add_node("start", lambda s: {"current_node": "analyze"})
@@ -346,8 +449,14 @@ from agentensemble import ReActAgent, Runner, RunConfig, RunHooks, InMemorySessi
 session = InMemorySession(session_id="chat-1")
 agent = ReActAgent(name="chatbot", tools=[SearchTool()], session=session, max_iterations=3)
 
-def on_start(q, _): print(f"→ User: {q[:50]}...")
-def on_end(r): print(f"← Agent: {r['result'][:80]}...\n")
+
+def on_start(q, _):
+    print(f"→ User: {q[:50]}...")
+
+
+def on_end(r):
+    print(f"← Agent: {r['result'][:80]}...\n")
+
 
 config = RunConfig(hooks=RunHooks(on_start=on_start, on_end=on_end))
 
@@ -367,7 +476,69 @@ Runner.run(agent, "What about its population?", config=config)  # Remembers cont
 
 ---
 
-### 11. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
+### 11. TraceHooks — Observability, token usage, cost estimation
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, TraceHooks, SearchTool
+
+agent = ReActAgent(name="research", tools=[SearchTool()], max_iterations=3)
+hooks = TraceHooks()
+
+config = RunConfig(trace_hooks=hooks)
+result = Runner.run(agent, "Who won the 2024 Nobel Prize in Physics?", config=config)
+
+print(result["result"][:100], "...")
+print("Usage:", result["metadata"].get("total_usage"))
+print("Cost (USD):", result["metadata"].get("cost_usd"))
+print("Events:", [e.type.value for e in hooks.events])
+```
+
+**Output:**
+
+```
+The 2024 Nobel Prize in Physics was awarded jointly to John J. Hopfield and Geoffrey E. Hinton...
+Usage: {'input_tokens': 1247, 'output_tokens': 89, 'total_tokens': 1336}
+Cost (USD): 0.00293
+Events: ['run_start', 'llm_start', 'llm_end', 'tool_start', 'tool_end', 'llm_start', 'llm_end', 'run_end']
+```
+
+---
+
+### 12. Human-in-loop — Pause before sensitive tools, resume with approval
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, function_tool
+
+
+@function_tool(description="Execute a payment")
+def execute_payment(amount: float, recipient: str) -> str:
+    return f"Paid ${amount} to {recipient}"
+
+
+agent = ReActAgent(tools=[execute_payment], max_iterations=2)
+config = RunConfig(interrupt_before_tools=["execute_payment"])
+
+result = Runner.run(agent, "Pay $50 to Alice", config=config)
+
+if result.get("__interrupted__"):
+    print("Paused for approval:", result["pending_tool"])
+    # Simulate human approval
+    result = Runner.run(
+        agent, "...", config=config, resume=result["run_state"], resume_value="Paid $50 to Alice"
+    )
+print(result["result"])
+```
+
+**Output:**
+
+```
+Paused for approval: {'name': 'execute_payment', 'arguments': {'amount': 50.0, 'recipient': 'Alice'}}
+Paid $50 to Alice
+```
+
+---
+
+### 13. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
 
 ```python
 from agentensemble import RAGAgent, RAGTool
@@ -388,17 +559,19 @@ manageable subtasks that can be executed by specialized agents...
 
 ---
 
-### 12. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
+### 14. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
 
 ```python
 from pydantic import BaseModel, Field
 from agentensemble import StructuredAgent
 
+
 class ProductReview(BaseModel):
     product: str = Field(description="Product name")
     rating: int = Field(description="1-5 stars")
     summary: str = Field(description="Brief summary")
 
+
 agent = StructuredAgent(response_format=ProductReview)
 result = agent.run("Review: iPhone 15 Pro - 5 stars, excellent camera and battery")
 print(result["structured_response"])
@@ -415,9 +588,15 @@ ProductReview(product='iPhone 15 Pro', rating=5, summary='Excellent camera and b
 
 ```python
 from agentensemble import (
-    ReActAgent, PlannerAgent, StateGraphAgent,
-    SwarmOrchestrator, DebateOrchestrator,
-    Runner, RunConfig, RunHooks, SearchTool,
+    ReActAgent,
+    PlannerAgent,
+    StateGraphAgent,
+    SwarmOrchestrator,
+    DebateOrchestrator,
+    Runner,
+    RunConfig,
+    RunHooks,
+    SearchTool,
 )
 
 # 1. Executor: ReActAgent with search
@@ -469,7 +648,7 @@ pip install agentensemble[search]
 PYTHONPATH=. python examples/showcase_all.py
 ```
 
-Runs all 10 demos with real API calls.
+Runs all demos with real API calls.
 
 ---
 
@@ -507,7 +686,8 @@ Runs all 10 demos with real API calls.
 
 - **Session** — `InMemorySession`, `SQLiteSession` for multi-turn context
 - **Runner** — `Runner.run()`, `Runner.arun()` with `RunConfig`, `RunHooks`, retries
-- **TraceHooks** — Observability for runs, LLM calls, tools
+- **TraceHooks** — Observability: run/LLM/tool events, token usage, cost estimation
+- **Human-in-loop** — `interrupt_before_tools=["pay", "send_email"]` to pause for approval
 
 ---
 
@@ -542,7 +722,8 @@ agentensemble/
 | Graph workflows    | WorkflowGraph, StateGraph | Native       | No     | No      |
 | Debate pattern     | DebateOrchestrator        | Manual       | Yes    | Yes     |
 | Session memory     | InMemory, SQLite          | Checkpointer | No     | No      |
-| Observability      | TraceHooks                | LangSmith    | No     | No      |
+| Observability      | TraceHooks, usage, cost   | LangSmith    | No     | No      |
+| Human-in-loop     | interrupt_before_tools    | interrupt()  | No     | No      |
 
 ---
 
@@ -550,21 +731,34 @@ agentensemble/
 
 - **Retries**: `RunConfig(max_retries=2, retry_on=(RateLimitError, TimeoutError))`
 - **Session**: `Runner.run(agent, query, config=RunConfig(session=SQLiteSession()))`
-- **Tracing**: Attach `TraceHooks` to capture run/LLM/tool events
+- **Tracing**: `RunConfig(trace_hooks=TraceHooks())` — captures run/LLM/tool events, usage, cost
+- **Human-in-loop**: `RunConfig(interrupt_before_tools=["pay"])` — pause before sensitive tools; resume with `Runner.run(agent, ..., resume=run_state, resume_value="Approved")`
 - **Benchmarks**: `AgentComparison`, `Benchmark.research_tasks()`, `Metrics`
 
 ---
 
 ## Documentation
 
-- **[Showcase](examples/showcase_all.py)** — Run all 10 features with real API output
+- **[Showcase](examples/showcase_all.py)** — Run the features end to end with real API calls
+- [Changelog](CHANGELOG.md)
 - [Examples](examples/) — `quickstart`, `react_llm`, `swarm`, `pipeline`, `streaming`, `debate`, `rag`, `research_agent`, `graph_workflow`, `runner`, `structured_output`
 - [Roadmap](docs/ROADMAP_2025.md) — Planned improvements
 
-> **Note:** Ensure `docs/agentensemble-architecture.png` is committed so the architecture diagram renders on GitHub.
-
 ---
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/irfanalidv/AgentEnsemble/blob/main/CONTRIBUTING.md)
+and the [Code of Conduct](https://github.com/irfanalidv/AgentEnsemble/blob/main/CODE_OF_CONDUCT.md).
+
+```bash
+git clone https://github.com/irfanalidv/AgentEnsemble.git && cd AgentEnsemble
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest
+```
+
+Security issues: please follow [SECURITY.md](https://github.com/irfanalidv/AgentEnsemble/blob/main/SECURITY.md).
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/irfanalidv/AgentEnsemble/blob/main/LICENSE).