stirrup 0.1.1__tar.gz → 0.1.3__tar.gz

{stirrup-0.1.1 → stirrup-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stirrup
-Version: 0.1.1
+Version: 0.1.3
 Summary: The lightweight foundation for building agents
 Keywords: ai,agent,llm,openai,anthropic,tools,framework
 Author: Artificial Analysis, Inc.
@@ -54,7 +54,7 @@ Requires-Dist: e2b-code-interpreter>=2.3.0 ; extra == 'e2b'
 Requires-Dist: litellm>=1.79.3 ; extra == 'litellm'
 Requires-Dist: mcp>=1.9.0 ; extra == 'mcp'
 Requires-Python: >=3.12
-Project-URL: Documentation, https://artificialanalysis.github.io/Stirrup
+Project-URL: Documentation, https://stirrup.artificialanalysis.ai
 Project-URL: Homepage, https://github.com/ArtificialAnalysis/Stirrup
 Project-URL: Repository, https://github.com/ArtificialAnalysis/Stirrup
 Provides-Extra: all
@@ -65,7 +65,7 @@ Provides-Extra: mcp
 Description-Content-Type: text/markdown
 
 <div align="center">
-  <a href="">
+  <a href="https://stirrup.artificialanalysis.ai">
     <picture>
         <img alt="Stirrup" src="https://github.com/ArtificialAnalysis/Stirrup/blob/048653717d8662b0b81d152a037995af1c926afc/assets/stirrup-banner.png?raw=true" width="700">
     </picture>
@@ -79,7 +79,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://pypi.python.org/pypi/stirrup"><img src="https://img.shields.io/pypi/v/stirrup" alt="PyPI version" /></a>&nbsp;<!--
   --><a href="https://github.com/ArtificialAnalysis/Stirrup/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ArtificialAnalysis/Stirrup" alt="License" /></a>&nbsp;<!--
-  --><a href="https://artificialanalysis.github.io/Stirrup"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
+  --><a href="https://stirrup.artificialanalysis.ai"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
 </p>
 
 
@@ -96,6 +96,7 @@ Stirrup is a lightweight framework, or starting point template, for building age
   - Code execution (local, Docker container, E2B sandbox)
   - MCP client
   - Document input and output
+- **Skills system:** Extend agent capabilities with modular, domain-specific instruction packages
 - **Flexible tool execution:** A generic `Tool` class allows easy tool definition and extension
 - **Context management:** Automatically summarizes conversation history when approaching context limits
 - **Flexible provider support:** Pre-built support for OpenAI-compatible APIs and LiteLLM, or bring your own client
@@ -105,16 +106,16 @@ Stirrup is a lightweight framework, or starting point template, for building age
 
 ```bash
 # Core framework
-uv pip install stirrup      # or: uv add stirrup
+pip install stirrup      # or: uv add stirrup
 
 # With all optional components
-uv pip install stirrup[all]  # or: uv add stirrup[all]
+pip install 'stirrup[all]'  # or: uv add 'stirrup[all]'
 
 # Individual extras
-uv pip install stirrup[litellm]  # or: uv add stirrup[litellm]
-uv pip install stirrup[docker]   # or: uv add stirrup[docker]
-uv pip install stirrup[e2b]      # or: uv add stirrup[e2b]
-uv pip install stirrup[mcp]      # or: uv add stirrup[mcp]
+pip install 'stirrup[litellm]'  # or: uv add 'stirrup[litellm]'
+pip install 'stirrup[docker]'   # or: uv add 'stirrup[docker]'
+pip install 'stirrup[e2b]'      # or: uv add 'stirrup[e2b]'
+pip install 'stirrup[mcp]'      # or: uv add 'stirrup[mcp]'
 ```
 
 ## Quick Start
@@ -160,6 +161,24 @@ if __name__ == "__main__":
 
 > **Note:** This example uses OpenRouter. Set `OPENROUTER_API_KEY` in your environment before running. Web search requires a `BRAVE_API_KEY`. The agent will still work without it, but web search will be unavailable.
 
+## Full Customization
+
+For using Stirrup as a foundation for your own fully customized agent, you can clone and import Stirrup locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/ArtificialAnalysis/Stirrup.git
+cd stirrup
+
+# Install in editable mode
+pip install -e .      # or: uv venv && uv pip install -e .
+
+# Or with all optional dependencies
+pip install -e '.[all]'  # or: uv venv && uv pip install -e '.[all]'
+```
+
+See the [Full Customization guide](https://stirrup.artificialanalysis.ai/extending/full-customization/) for more details.
+
 ## How It Works
 
 - **`Agent`** - Configures and runs the agent loop until a finish tool is called or max turns reached
@@ -188,6 +207,7 @@ agent = Agent(client=client, name="deepseek_agent")
 ### LiteLLM (Anthropic, Google, etc.)
 
 ```python
+# Ensure LiteLLM is added with: pip install 'stirrup[litellm]'  # or: uv add 'stirrup[litellm]'
 # Create LiteLLM client for Anthropic Claude
 # See https://docs.litellm.ai/docs/providers for all supported providers
 client = LiteLLMClient(
@@ -202,7 +222,7 @@ agent = Agent(
 )
 ```
 
-See [LiteLLM Example](https://artificialanalysis.github.io/Stirrup/examples/#litellm-multi-provider-support) or [Deepseek Example](https://artificialanalysis.github.io/Stirrup/examples/#openai-compatible-apis-deepseek-vllm-ollama) for complete examples.
+See [LiteLLM Example](https://stirrup.artificialanalysis.ai/examples/#litellm-multi-provider-support) or [Deepseek Example](https://stirrup.artificialanalysis.ai/examples/#openai-compatible-apis-deepseek-vllm-ollama) for complete examples.
 
 ## Default Tools
 
@@ -285,14 +305,14 @@ agent = Agent(
 
 ## Next Steps
 
-- [Getting Started](https://artificialanalysis.github.io/Stirrup/getting-started/) - Installation and first agent tutorial
-- [Core Concepts](https://artificialanalysis.github.io/Stirrup/concepts/) - Understand Agent, Tools, and Sessions
-- [Examples](https://artificialanalysis.github.io/Stirrup/examples/) - Working examples for common patterns
-- [Creating Tools](https://artificialanalysis.github.io/Stirrup/guides/tools/) - Build your own tools
+- [Getting Started](https://stirrup.artificialanalysis.ai/getting-started/) - Installation and first agent tutorial
+- [Core Concepts](https://stirrup.artificialanalysis.ai/concepts/) - Understand Agent, Tools, and Sessions
+- [Examples](https://stirrup.artificialanalysis.ai/examples/) - Working examples for common patterns
+- [Creating Tools](https://stirrup.artificialanalysis.ai/guides/tools/) - Build your own tools
 
 ## Documentation
 
-Full documentation: [artificialanalysis.github.io/Stirrup](https://artificialanalysis.github.io/Stirrup)
+Full documentation: [artificialanalysis.github.io/Stirrup](https://stirrup.artificialanalysis.ai)
 
 Build and serve locally:
 

{stirrup-0.1.1 → stirrup-0.1.3}/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <a href="">
+  <a href="https://stirrup.artificialanalysis.ai">
     <picture>
         <img alt="Stirrup" src="https://github.com/ArtificialAnalysis/Stirrup/blob/048653717d8662b0b81d152a037995af1c926afc/assets/stirrup-banner.png?raw=true" width="700">
     </picture>
@@ -13,7 +13,7 @@
 <p align="center">
   <a href="https://pypi.python.org/pypi/stirrup"><img src="https://img.shields.io/pypi/v/stirrup" alt="PyPI version" /></a>&nbsp;<!--
   --><a href="https://github.com/ArtificialAnalysis/Stirrup/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ArtificialAnalysis/Stirrup" alt="License" /></a>&nbsp;<!--
-  --><a href="https://artificialanalysis.github.io/Stirrup"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
+  --><a href="https://stirrup.artificialanalysis.ai"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
 </p>
 
 
@@ -30,6 +30,7 @@ Stirrup is a lightweight framework, or starting point template, for building age
   - Code execution (local, Docker container, E2B sandbox)
   - MCP client
   - Document input and output
+- **Skills system:** Extend agent capabilities with modular, domain-specific instruction packages
 - **Flexible tool execution:** A generic `Tool` class allows easy tool definition and extension
 - **Context management:** Automatically summarizes conversation history when approaching context limits
 - **Flexible provider support:** Pre-built support for OpenAI-compatible APIs and LiteLLM, or bring your own client
@@ -39,16 +40,16 @@ Stirrup is a lightweight framework, or starting point template, for building age
 
 ```bash
 # Core framework
-uv pip install stirrup      # or: uv add stirrup
+pip install stirrup      # or: uv add stirrup
 
 # With all optional components
-uv pip install stirrup[all]  # or: uv add stirrup[all]
+pip install 'stirrup[all]'  # or: uv add 'stirrup[all]'
 
 # Individual extras
-uv pip install stirrup[litellm]  # or: uv add stirrup[litellm]
-uv pip install stirrup[docker]   # or: uv add stirrup[docker]
-uv pip install stirrup[e2b]      # or: uv add stirrup[e2b]
-uv pip install stirrup[mcp]      # or: uv add stirrup[mcp]
+pip install 'stirrup[litellm]'  # or: uv add 'stirrup[litellm]'
+pip install 'stirrup[docker]'   # or: uv add 'stirrup[docker]'
+pip install 'stirrup[e2b]'      # or: uv add 'stirrup[e2b]'
+pip install 'stirrup[mcp]'      # or: uv add 'stirrup[mcp]'
 ```
 
 ## Quick Start
@@ -94,6 +95,24 @@ if __name__ == "__main__":
 
 > **Note:** This example uses OpenRouter. Set `OPENROUTER_API_KEY` in your environment before running. Web search requires a `BRAVE_API_KEY`. The agent will still work without it, but web search will be unavailable.
 
+## Full Customization
+
+For using Stirrup as a foundation for your own fully customized agent, you can clone and import Stirrup locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/ArtificialAnalysis/Stirrup.git
+cd stirrup
+
+# Install in editable mode
+pip install -e .      # or: uv venv && uv pip install -e .
+
+# Or with all optional dependencies
+pip install -e '.[all]'  # or: uv venv && uv pip install -e '.[all]'
+```
+
+See the [Full Customization guide](https://stirrup.artificialanalysis.ai/extending/full-customization/) for more details.
+
 ## How It Works
 
 - **`Agent`** - Configures and runs the agent loop until a finish tool is called or max turns reached
@@ -122,6 +141,7 @@ agent = Agent(client=client, name="deepseek_agent")
 ### LiteLLM (Anthropic, Google, etc.)
 
 ```python
+# Ensure LiteLLM is added with: pip install 'stirrup[litellm]'  # or: uv add 'stirrup[litellm]'
 # Create LiteLLM client for Anthropic Claude
 # See https://docs.litellm.ai/docs/providers for all supported providers
 client = LiteLLMClient(
@@ -136,7 +156,7 @@ agent = Agent(
 )
 ```
 
-See [LiteLLM Example](https://artificialanalysis.github.io/Stirrup/examples/#litellm-multi-provider-support) or [Deepseek Example](https://artificialanalysis.github.io/Stirrup/examples/#openai-compatible-apis-deepseek-vllm-ollama) for complete examples.
+See [LiteLLM Example](https://stirrup.artificialanalysis.ai/examples/#litellm-multi-provider-support) or [Deepseek Example](https://stirrup.artificialanalysis.ai/examples/#openai-compatible-apis-deepseek-vllm-ollama) for complete examples.
 
 ## Default Tools
 
@@ -219,14 +239,14 @@ agent = Agent(
 
 ## Next Steps
 
-- [Getting Started](https://artificialanalysis.github.io/Stirrup/getting-started/) - Installation and first agent tutorial
-- [Core Concepts](https://artificialanalysis.github.io/Stirrup/concepts/) - Understand Agent, Tools, and Sessions
-- [Examples](https://artificialanalysis.github.io/Stirrup/examples/) - Working examples for common patterns
-- [Creating Tools](https://artificialanalysis.github.io/Stirrup/guides/tools/) - Build your own tools
+- [Getting Started](https://stirrup.artificialanalysis.ai/getting-started/) - Installation and first agent tutorial
+- [Core Concepts](https://stirrup.artificialanalysis.ai/concepts/) - Understand Agent, Tools, and Sessions
+- [Examples](https://stirrup.artificialanalysis.ai/examples/) - Working examples for common patterns
+- [Creating Tools](https://stirrup.artificialanalysis.ai/guides/tools/) - Build your own tools
 
 ## Documentation
 
-Full documentation: [artificialanalysis.github.io/Stirrup](https://artificialanalysis.github.io/Stirrup)
+Full documentation: [artificialanalysis.github.io/Stirrup](https://stirrup.artificialanalysis.ai)
 
 Build and serve locally:
 

{stirrup-0.1.1 → stirrup-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stirrup"
-version = "0.1.1"
+version = "0.1.3"
 description = "The lightweight foundation for building agents"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -45,7 +45,7 @@ all = ["stirrup[litellm,e2b,docker,mcp]"]
 
 [project.urls]
 Homepage = "https://github.com/ArtificialAnalysis/Stirrup"
-Documentation = "https://artificialanalysis.github.io/Stirrup"
+Documentation = "https://stirrup.artificialanalysis.ai"
 Repository = "https://github.com/ArtificialAnalysis/Stirrup"
 
 [build-system]

{stirrup-0.1.1 → stirrup-0.1.3}/src/stirrup/__init__.py

@@ -35,6 +35,7 @@ from stirrup.core.models import (
     AssistantMessage,
     AudioContentBlock,
     ChatMessage,
+    EmptyParams,
     ImageContentBlock,
     LLMClient,
     SubAgentMetadata,
@@ -58,6 +59,7 @@ __all__ = [
     "AudioContentBlock",
     "ChatMessage",
     "ContextOverflowError",
+    "EmptyParams",
     "ImageContentBlock",
     "LLMClient",
     "SubAgentMetadata",

{stirrup-0.1.1 → stirrup-0.1.3}/src/stirrup/clients/chat_completions_client.py

@@ -67,7 +67,6 @@ class ChatCompletionsClient(LLMClient):
         *,
         base_url: str | None = None,
         api_key: str | None = None,
-        supports_audio_input: bool = False,
         reasoning_effort: str | None = None,
         timeout: float | None = None,
         max_retries: int = 2,
@@ -82,7 +81,6 @@ class ChatCompletionsClient(LLMClient):
                 Use for OpenAI-compatible providers (e.g., 'http://localhost:8000/v1').
             api_key: API key for authentication. If None, reads from OPENROUTER_API_KEY
                 environment variable.
-            supports_audio_input: Whether the model supports audio inputs. Defaults to False.
             reasoning_effort: Reasoning effort level for extended thinking models
                 (e.g., 'low', 'medium', 'high'). Only used with o1/o3 style models.
             timeout: Request timeout in seconds. If None, uses OpenAI SDK default.
@@ -92,7 +90,6 @@ class ChatCompletionsClient(LLMClient):
         """
         self._model = model
         self._max_tokens = max_tokens
-        self._supports_audio_input = supports_audio_input
         self._reasoning_effort = reasoning_effort
         self._kwargs = kwargs or {}
 

{stirrup-0.1.1 → stirrup-0.1.3}/src/stirrup/clients/litellm_client.py

@@ -7,7 +7,7 @@ Requires the litellm extra: `pip install stirrup[litellm]`
 """
 
 import logging
-from typing import Any
+from typing import Any, Literal
 
 try:
     from litellm import acompletion
@@ -38,6 +38,8 @@ __all__ = [
 
 LOGGER = logging.getLogger(__name__)
 
+type ReasoningEffort = Literal["none", "minimal", "low", "medium", "high", "xhigh", "default"]
+
 
 class LiteLLMClient(LLMClient):
     """LiteLLM-based client supporting multiple LLM providers with unified interface.
@@ -49,8 +51,8 @@ class LiteLLMClient(LLMClient):
         self,
         model_slug: str,
         max_tokens: int,
-        supports_audio_input: bool = False,
-        reasoning_effort: str | None = None,
+        api_key: str | None = None,
+        reasoning_effort: ReasoningEffort | None = None,
         kwargs: dict[str, Any] | None = None,
     ) -> None:
         """Initialize LiteLLM client with model configuration and capabilities.
@@ -58,15 +60,13 @@ class LiteLLMClient(LLMClient):
         Args:
             model_slug: Model identifier for LiteLLM (e.g., 'anthropic/claude-3-5-sonnet-20241022')
             max_tokens: Maximum context window size in tokens
-            supports_audio_input: Whether the model supports audio inputs
             reasoning_effort: Reasoning effort level for extended thinking models (e.g., 'medium', 'high')
             kwargs: Additional arguments to pass to LiteLLM completion calls
         """
         self._model_slug = model_slug
-        self._supports_video_input = False
-        self._supports_audio_input = supports_audio_input
         self._max_tokens = max_tokens
-        self._reasoning_effort = reasoning_effort
+        self._reasoning_effort: ReasoningEffort | None = reasoning_effort
+        self._api_key = api_key
         self._kwargs = kwargs or {}
 
     @property
@@ -92,6 +92,8 @@ class LiteLLMClient(LLMClient):
             tools=to_openai_tools(tools) if tools else None,
             tool_choice="auto" if tools else None,
             max_tokens=self._max_tokens,
+            reasoning_effort=self._reasoning_effort,
+            api_key=self._api_key,
             **self._kwargs,
         )
 
@@ -103,14 +105,20 @@ class LiteLLMClient(LLMClient):
             )
 
         msg = choice["message"]
-
         reasoning: Reasoning | None = None
         if getattr(msg, "reasoning_content", None) is not None:
             reasoning = Reasoning(content=msg.reasoning_content)
         if getattr(msg, "thinking_blocks", None) is not None and len(msg.thinking_blocks) > 0:
-            reasoning = Reasoning(
-                signature=msg.thinking_blocks[0]["signature"], content=msg.thinking_blocks[0]["content"]
-            )
+            if len(msg.thinking_blocks) > 1:
+                raise ValueError("Found multiple thinking blocks in the response")
+
+            signature = msg.thinking_blocks[0].get("thinking_signature", None)
+            content = msg.thinking_blocks[0].get("thinking", None)
+
+            if signature is None and content is None:
+                raise ValueError("Signature and content not found in the thinking block response")
+
+            reasoning = Reasoning(signature=signature, content=content)
 
         usage = r["usage"]
 
@@ -119,6 +127,7 @@ class LiteLLMClient(LLMClient):
                 tool_call_id=tc.get("id"),
                 name=tc["function"]["name"],
                 arguments=tc["function"].get("arguments", "") or "",
+                signature=tc.get("provider_specific_fields", {}).get("thought_signature", None),
             )
             for tc in (msg.get("tool_calls") or [])
         ]

{stirrup-0.1.1 → stirrup-0.1.3}/src/stirrup/clients/utils.py

@@ -12,6 +12,7 @@ from stirrup.core.models import (
     AudioContentBlock,
     ChatMessage,
     Content,
+    EmptyParams,
     ImageContentBlock,
     SystemMessage,
     Tool,
@@ -47,7 +48,7 @@ def to_openai_tools(tools: dict[str, Tool]) -> list[dict[str, Any]]:
             "name": t.name,
             "description": t.description,
         }
-        if t.parameters is not None:
+        if t.parameters is not EmptyParams:
             function["parameters"] = t.parameters.model_json_schema()
         tool_payload: dict[str, Any] = {
             "type": "function",
@@ -139,6 +140,10 @@ def to_openai_messages(msgs: list[ChatMessage]) -> list[dict[str, Any]]:
                     tool_dict = tool.model_dump()
                     tool_dict["id"] = tool.tool_call_id
                     tool_dict["type"] = "function"
+                    if tool.signature is not None:
+                        tool_dict["provider_specific_fields"] = {
+                            "thought_signature": tool.signature,
+                        }
                     tool_dict["function"] = {
                         "name": tool.name,
                         "arguments": tool.arguments,

{stirrup-0.1.1 → stirrup-0.1.3}/src/stirrup/constants.py

@@ -1,14 +1,18 @@
+from typing import Literal
+
 # Tool naming
-FINISH_TOOL_NAME = "finish"
+FINISH_TOOL_NAME: Literal["finish"] = "finish"
 
 # Agent execution limits
 AGENT_MAX_TURNS = 30  # Maximum agent turns before forced termination
 CONTEXT_SUMMARIZATION_CUTOFF = 0.7  # Context window usage threshold (0.0-1.0) that triggers message summarization
+TURNS_REMAINING_WARNING_THRESHOLD = 20
 
 # Media resolution limits
 RESOLUTION_1MP = 1_000_000  # 1 megapixel - default max resolution for images
 RESOLUTION_480P = 640 * 480  # 480p video resolution
 
 # Code execution
-SUBMISSION_SANDBOX_TIMEOUT = 60 * 10  # 10 minutes
+SANDBOX_TIMEOUT = 60 * 10  # 10 minutes
+SANDBOX_REQUEST_TIMEOUT = 60 * 3  # 3 minutes
 E2B_SANDBOX_TEMPLATE_ALIAS = "e2b-sandbox"