RouteKitAI 0.2.0__tar.gz → 0.2.1__tar.gz

{routekitai-0.2.0/src/RouteKitAI.egg-info → routekitai-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RouteKitAI
-Version: 0.2.0
+Version: 0.2.1
 Summary: An agent development + orchestration framework
 Author: Mohamed Ghassen Brahim
 License: MIT
@@ -41,6 +41,9 @@ Requires-Dist: sentence-transformers>=2.2.0; extra == "optional"
 Requires-Dist: faiss-cpu>=1.7.4; extra == "optional"
 Requires-Dist: openai>=1.0.0; extra == "optional"
 Requires-Dist: nest-asyncio>=1.5.0; extra == "optional"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Dynamic: license-file
 
 # RouteKitAI
@@ -60,6 +63,8 @@ Dynamic: license-file
 
 ---
 
+> **⚠️ Early stage**: RouteKitAI is still in very early development. APIs may change, and some features are experimental. Use with caution in production.
+
 RouteKitAI is a Python framework for building AI agents with **graph-based orchestration**, **built-in tracing**, and **deterministic replay**. Unlike other frameworks, RouteKitAI treats observability and testability as first-class features from day one.
 
 ## ✨ Features
@@ -202,6 +207,7 @@ asyncio.run(main())
 Check out the [`examples/`](examples/) directory for complete examples:
 
 - **[Basic Agent](examples/basic.py)** / **[Hello RouteKit](examples/hello_routekit.py)**: Simple agent with tools
+- **[Real agent with Anthropic](examples/anthropic_agent.py)**: Live Claude agent with tool use (requires `ANTHROPIC_API_KEY`)
 - **[Graph Orchestration](examples/graph_agent.py)** / **[Graph Policy](examples/graph_policy.py)**: Multi-agent workflows
 - **[Supervisor Pattern](examples/supervisor_agent.py)** / **[Supervisor Policy](examples/supervisor_policy.py)**: Supervisor delegating to sub-agents
 - **[ReAct / Plan–Execute / Function Calling](examples/react_policy.py)**, **[Plan–Execute](examples/plan_execute_policy.py)**, **[Function Calling](examples/function_calling_policy.py)**: Policy examples
@@ -305,8 +311,29 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and:
 
 ## 📋 Requirements
 
-- Python 3.11 or higher
-- Pydantic 2.0+
+**Core (always installed):**
+
+- Python 3.11+
+- [Pydantic](https://docs.pydantic.dev/) 2.x
+- [NumPy](https://numpy.org/) 1.24+
+- [httpx](https://www.python-httpx.org/) 0.24+
+
+**Optional extras:**
+
+| Extra | Purpose |
+|-------|---------|
+| `[dev]` | CLI, tests, linting, type checking (pytest, mypy, ruff, rich, typer, safety, bandit) |
+| `[ui]` | Web UI for traces: `routekitai serve` (FastAPI, Uvicorn) |
+| `[optional]` | Vector memory, OpenAI adapter (sentence-transformers, faiss, openai, nest-asyncio) |
+| `[docs]` | Build documentation locally (MkDocs, MkDocs Material) |
+
+Examples:
+
+```bash
+pip install "RouteKitAI[dev]"       # development + CLI
+pip install "RouteKitAI[dev,ui]"    # + trace web UI
+pip install "RouteKitAI[docs]"      # build docs: mkdocs build / mkdocs serve
+```
 
 ## 📄 License
 

{routekitai-0.2.0 → routekitai-0.2.1}/README.md

@@ -15,6 +15,8 @@
 
 ---
 
+> **⚠️ Early stage**: RouteKitAI is still in very early development. APIs may change, and some features are experimental. Use with caution in production.
+
 RouteKitAI is a Python framework for building AI agents with **graph-based orchestration**, **built-in tracing**, and **deterministic replay**. Unlike other frameworks, RouteKitAI treats observability and testability as first-class features from day one.
 
 ## ✨ Features
@@ -157,6 +159,7 @@ asyncio.run(main())
 Check out the [`examples/`](examples/) directory for complete examples:
 
 - **[Basic Agent](examples/basic.py)** / **[Hello RouteKit](examples/hello_routekit.py)**: Simple agent with tools
+- **[Real agent with Anthropic](examples/anthropic_agent.py)**: Live Claude agent with tool use (requires `ANTHROPIC_API_KEY`)
 - **[Graph Orchestration](examples/graph_agent.py)** / **[Graph Policy](examples/graph_policy.py)**: Multi-agent workflows
 - **[Supervisor Pattern](examples/supervisor_agent.py)** / **[Supervisor Policy](examples/supervisor_policy.py)**: Supervisor delegating to sub-agents
 - **[ReAct / Plan–Execute / Function Calling](examples/react_policy.py)**, **[Plan–Execute](examples/plan_execute_policy.py)**, **[Function Calling](examples/function_calling_policy.py)**: Policy examples
@@ -260,8 +263,29 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and:
 
 ## 📋 Requirements
 
-- Python 3.11 or higher
-- Pydantic 2.0+
+**Core (always installed):**
+
+- Python 3.11+
+- [Pydantic](https://docs.pydantic.dev/) 2.x
+- [NumPy](https://numpy.org/) 1.24+
+- [httpx](https://www.python-httpx.org/) 0.24+
+
+**Optional extras:**
+
+| Extra | Purpose |
+|-------|---------|
+| `[dev]` | CLI, tests, linting, type checking (pytest, mypy, ruff, rich, typer, safety, bandit) |
+| `[ui]` | Web UI for traces: `routekitai serve` (FastAPI, Uvicorn) |
+| `[optional]` | Vector memory, OpenAI adapter (sentence-transformers, faiss, openai, nest-asyncio) |
+| `[docs]` | Build documentation locally (MkDocs, MkDocs Material) |
+
+Examples:
+
+```bash
+pip install "RouteKitAI[dev]"       # development + CLI
+pip install "RouteKitAI[dev,ui]"    # + trace web UI
+pip install "RouteKitAI[docs]"      # build docs: mkdocs build / mkdocs serve
+```
 
 ## 📄 License
 

{routekitai-0.2.0 → routekitai-0.2.1}/docs/api-reference.md

@@ -105,7 +105,7 @@ Overview of the main public APIs in RouteKitAI. For full signatures and docstrin
 |--------|-------------|
 | **FakeModel** | Local model with preloaded responses (no API key). |
 | **OpenAIChatModel** | OpenAI chat API. |
-| **AnthropicChatModel** | Anthropic API (if installed). |
+| **AnthropicModel** | Anthropic Claude (Messages API). |
 | **AzureOpenAIChatModel** | Azure OpenAI (if installed). |
 
 ---

{routekitai-0.2.0 → routekitai-0.2.1}/docs/guides/providers.md

@@ -58,14 +58,21 @@ model = OpenAIChatModel(
 
 ## Anthropic
 
-Uses the Anthropic API. Install the optional dependency and use the provider (if exposed in the package):
+Uses the Anthropic Messages API (Claude). No extra install beyond RouteKitAI; the provider uses `httpx` (already a dependency).
 
 ```python
-# Check routekitai.providers for exact import
-from routekitai.providers.anthropic import AnthropicChatModel  # if available
+import os
+from routekitai.providers import AnthropicModel
+
+model = AnthropicModel(
+    name="claude-3-5-sonnet-20241022",
+    api_key=os.environ.get("ANTHROPIC_API_KEY"),
+)
 ```
 
-Configure with `ANTHROPIC_API_KEY` and the desired model name.
+- **api_key** — Prefer `ANTHROPIC_API_KEY` environment variable.
+- **name** — Model name (e.g. `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`).
+- **base_url** — Optional; defaults to `https://api.anthropic.com/v1`.
 
 ## Azure OpenAI
 

routekitai-0.2.1/examples/anthropic_agent.py

@@ -0,0 +1,107 @@
+"""Example: Real agent with Anthropic Claude.
+
+This example runs a live agent using Anthropic's Claude model with tool use.
+The agent can answer questions and call tools (e.g. echo) in a ReAct loop.
+
+To run this example:
+1. Set your Anthropic API key: export ANTHROPIC_API_KEY='your-api-key-here'
+2. (Optional) Set model: export ANTHROPIC_MODEL='claude-sonnet-4-5-20250929'
+   If you get a 404 "model not found", list models at https://docs.anthropic.com/en/api/models
+   and set ANTHROPIC_MODEL to a model ID available in your account.
+3. Install httpx (required by Anthropic provider): pip install httpx
+4. Run: python examples/anthropic_agent.py
+
+Note: This example uses real Anthropic API calls and will consume API credits.
+   Ensure your Anthropic account has sufficient credits (Plans & Billing).
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+from routekitai import Agent
+from routekitai.core.message import MessageRole
+from routekitai.core.policies import ReActPolicy
+from routekitai.core.tools import EchoTool
+from routekitai.providers.anthropic import AnthropicModel
+
+
+async def main() -> None:
+    """Run a real agent with Anthropic Claude."""
+    print("Running real agent example with Anthropic Claude...")
+    print("=" * 60)
+
+    api_key = os.getenv("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "ANTHROPIC_API_KEY environment variable not set. "
+            "Please set it with: export ANTHROPIC_API_KEY='your-api-key-here'"
+        )
+
+    # Model: use ANTHROPIC_MODEL env var or a default (see https://docs.anthropic.com/en/api/models)
+    model_id = os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-5-20250929")
+    model = AnthropicModel(
+        name=model_id,
+        api_key=api_key,
+        provider="anthropic",
+    )
+
+    agent = Agent(
+        name="claude_agent",
+        model=model,
+        tools=[EchoTool()],
+        policy=ReActPolicy(max_iterations=25),
+    )
+
+    print(f"✓ Using Anthropic API (model: {model_id})")
+    print("✓ Agent has echo tool available")
+    print()
+
+    # Run the agent with a prompt that may trigger tool use
+    prompt = (
+        "What is 2 + 2? Give the number only. "
+        "Then use the echo tool to echo the word 'done' so I know you finished."
+    )
+    print("Prompt:", prompt)
+    print("-" * 60)
+
+    async with model:
+        result = await agent.run(prompt)
+
+    print()
+    print("=" * 60)
+    print("Agent run completed!")
+    print("=" * 60)
+    print("\nOutput:")
+    output_text = (result.output.content or "").strip()
+    if output_text:
+        print(output_text)
+    else:
+        # Fallback when model returned no final text (e.g. after tool use)
+        last_with_content = None
+        for msg in reversed(result.messages):
+            if msg.role == MessageRole.ASSISTANT and (msg.content or "").strip():
+                last_with_content = msg.content.strip()
+                break
+        if last_with_content:
+            print(last_with_content)
+        else:
+            # Show tool results if any
+            tool_results = [
+                str(msg.tool_result.get("result", msg.content))
+                for msg in result.messages
+                if msg.role == MessageRole.TOOL and msg.tool_result
+            ]
+            if tool_results:
+                print("(no final text; tool results: ", ", ".join(tool_results), ")")
+            else:
+                print("(no text output)")
+
+    trace_path = Path(".routekit") / "traces" / f"{result.trace_id}.jsonl"
+    print(f"\nTrace ID: {result.trace_id}")
+    if trace_path.exists():
+        print(f"Trace saved to: {trace_path}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{routekitai-0.2.0 → routekitai-0.2.1}/pyproject.toml

@@ -55,6 +55,10 @@ optional = [
     "openai>=1.0.0",
     "nest-asyncio>=1.5.0",
 ]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.0.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/MedGhassen/RouteKit"

{routekitai-0.2.0 → routekitai-0.2.1/src/RouteKitAI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RouteKitAI
-Version: 0.2.0
+Version: 0.2.1
 Summary: An agent development + orchestration framework
 Author: Mohamed Ghassen Brahim
 License: MIT
@@ -41,6 +41,9 @@ Requires-Dist: sentence-transformers>=2.2.0; extra == "optional"
 Requires-Dist: faiss-cpu>=1.7.4; extra == "optional"
 Requires-Dist: openai>=1.0.0; extra == "optional"
 Requires-Dist: nest-asyncio>=1.5.0; extra == "optional"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Dynamic: license-file
 
 # RouteKitAI
@@ -60,6 +63,8 @@ Dynamic: license-file
 
 ---
 
+> **⚠️ Early stage**: RouteKitAI is still in very early development. APIs may change, and some features are experimental. Use with caution in production.
+
 RouteKitAI is a Python framework for building AI agents with **graph-based orchestration**, **built-in tracing**, and **deterministic replay**. Unlike other frameworks, RouteKitAI treats observability and testability as first-class features from day one.
 
 ## ✨ Features
@@ -202,6 +207,7 @@ asyncio.run(main())
 Check out the [`examples/`](examples/) directory for complete examples:
 
 - **[Basic Agent](examples/basic.py)** / **[Hello RouteKit](examples/hello_routekit.py)**: Simple agent with tools
+- **[Real agent with Anthropic](examples/anthropic_agent.py)**: Live Claude agent with tool use (requires `ANTHROPIC_API_KEY`)
 - **[Graph Orchestration](examples/graph_agent.py)** / **[Graph Policy](examples/graph_policy.py)**: Multi-agent workflows
 - **[Supervisor Pattern](examples/supervisor_agent.py)** / **[Supervisor Policy](examples/supervisor_policy.py)**: Supervisor delegating to sub-agents
 - **[ReAct / Plan–Execute / Function Calling](examples/react_policy.py)**, **[Plan–Execute](examples/plan_execute_policy.py)**, **[Function Calling](examples/function_calling_policy.py)**: Policy examples
@@ -305,8 +311,29 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and:
 
 ## 📋 Requirements
 
-- Python 3.11 or higher
-- Pydantic 2.0+
+**Core (always installed):**
+
+- Python 3.11+
+- [Pydantic](https://docs.pydantic.dev/) 2.x
+- [NumPy](https://numpy.org/) 1.24+
+- [httpx](https://www.python-httpx.org/) 0.24+
+
+**Optional extras:**
+
+| Extra | Purpose |
+|-------|---------|
+| `[dev]` | CLI, tests, linting, type checking (pytest, mypy, ruff, rich, typer, safety, bandit) |
+| `[ui]` | Web UI for traces: `routekitai serve` (FastAPI, Uvicorn) |
+| `[optional]` | Vector memory, OpenAI adapter (sentence-transformers, faiss, openai, nest-asyncio) |
+| `[docs]` | Build documentation locally (MkDocs, MkDocs Material) |
+
+Examples:
+
+```bash
+pip install "RouteKitAI[dev]"       # development + CLI
+pip install "RouteKitAI[dev,ui]"    # + trace web UI
+pip install "RouteKitAI[docs]"      # build docs: mkdocs build / mkdocs serve
+```
 
 ## 📄 License
 

{routekitai-0.2.0 → routekitai-0.2.1}/src/RouteKitAI.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ docs/guides/providers.md
 docs/guides/running-agents.md
 docs/guides/tracing-and-replay.md
 examples/__init__.py
+examples/anthropic_agent.py
 examples/basic.py
 examples/eval_regression.py
 examples/function_calling_policy.py

{routekitai-0.2.0 → routekitai-0.2.1}/src/RouteKitAI.egg-info/requires.txt

@@ -13,6 +13,10 @@ typer>=0.9.0
 safety>=2.0.0
 bandit>=1.7.0
 
+[docs]
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+
 [optional]
 sentence-transformers>=2.2.0
 faiss-cpu>=1.7.4

{routekitai-0.2.0 → routekitai-0.2.1}/src/routekitai/__init__.py

@@ -1,6 +1,6 @@
 """RouteKitAI: An agent development + orchestration framework."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 # Import hooks first to ensure ToolFilter is defined before Agent
 from routekitai.core import (

{routekitai-0.2.0 → routekitai-0.2.1}/src/routekitai/core/policies.py

@@ -25,7 +25,8 @@ class ReActPolicy(Policy):
     Simple loop: model -> decide tool -> tool -> model -> final
     """
 
-    max_iterations: int = 10
+    def __init__(self, max_iterations: int = 10) -> None:
+        self.max_iterations = max_iterations
 
     async def plan(self, state: dict[str, Any]) -> list[Action]:
         """Plan next action in ReAct loop.

{routekitai-0.2.0 → routekitai-0.2.1}/src/routekitai/core/runtime.py

@@ -543,6 +543,14 @@ class Runtime(BaseModel):
                 output_message = Message.assistant(final_response.content)
                 messages.append(output_message)
 
+        # If final output has no content (e.g. model returned empty after tool use),
+        # use the last assistant message that had content so the run result is useful.
+        if not (output_message.content or "").strip() and messages:
+            for msg in reversed(messages):
+                if msg.role == MessageRole.ASSISTANT and (msg.content or "").strip():
+                    output_message = msg
+                    break
+
         # Import here to avoid circular import
         from routekitai.core.agent import RunResult
 

{routekitai-0.2.0 → routekitai-0.2.1}/src/routekitai/providers/__init__.py

@@ -1,9 +1,11 @@
 """Model providers for RouteKit."""
 
+from routekitai.providers.anthropic import AnthropicModel
 from routekitai.providers.local import FakeModel
 from routekitai.providers.openai import OpenAIChatModel
 
 __all__ = [
+    "AnthropicModel",
     "OpenAIChatModel",
     "FakeModel",
 ]

{routekitai-0.2.0 → routekitai-0.2.1}/src/routekitai/providers/anthropic.py

@@ -75,7 +75,11 @@ class AnthropicModel(Model):
         return self._client
 
     def _message_to_anthropic(self, message: Message) -> dict[str, Any]:
-        """Convert routkitai Message to Anthropic format."""
+        """Convert routkitai Message to Anthropic format.
+
+        Anthropic requires all messages to have non-empty content except the
+        optional final assistant message. We ensure content is never empty.
+        """
         role_map = {
             MessageRole.SYSTEM: "system",
             MessageRole.USER: "user",
@@ -84,13 +88,15 @@ class AnthropicModel(Model):
         # Anthropic doesn't support tool role messages directly
         if message.role == MessageRole.TOOL:
             # Convert tool messages to user messages with tool result
-            return {
-                "role": "user",
-                "content": f"Tool result: {message.content}",
-            }
+            content = (
+                f"Tool result: {message.content}" if message.content else "Tool result: (no output)"
+            )
+            return {"role": "user", "content": content}
+        # API rejects empty or whitespace-only content; use a non-whitespace placeholder
+        content = message.content if (message.content and message.content.strip()) else "(no text)"
         return {
             "role": role_map.get(message.role, "user"),
-            "content": message.content,
+            "content": content,
         }
 
     def _tools_to_anthropic(self, tools: list[Tool]) -> list[dict[str, Any]]:
@@ -208,9 +214,19 @@ class AnthropicModel(Model):
             )
 
         except httpx.HTTPStatusError as e:
-            raise ModelError(
-                f"Anthropic API error: {e.response.status_code} - {e.response.text}"
-            ) from e
+            msg = f"Anthropic API error: {e.response.status_code}"
+            try:
+                body = e.response.json()
+                err = body.get("error") or {}
+                if isinstance(err, dict) and err.get("message"):
+                    msg = f"{msg} - {err['message']}"
+                else:
+                    msg = f"{msg} - {e.response.text}"
+            except Exception:
+                msg = f"{msg} - {e.response.text}"
+            if e.response.status_code == 404 and "model" in msg.lower():
+                msg += " Use a model ID from https://docs.anthropic.com/en/api/models or set ANTHROPIC_MODEL."
+            raise ModelError(msg) from e
         except Exception as e:
             raise ModelError(f"Failed to call Anthropic API: {e}") from e