stirrup 0.1.0__py3-none-any.whl

stirrup/utils/text.py

@@ -0,0 +1,11 @@
+def truncate_msg(msg: str, max_length: int) -> str:
+    """Truncate long messages by removing middle portion, keeping start and end with ellipsis indicator."""
+    msg_len = len(msg)
+    if msg_len <= max_length:
+        return msg
+    else:
+        return (
+            msg[: max_length // 2]
+            + f"\n... This content has been truncated from an original {msg_len} characters to stay below {max_length} characters ...\n"
+            + msg[-max_length // 2 :]
+        )

stirrup-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.3
+Name: stirrup
+Version: 0.1.0
+Summary: The lightweight foundation for building agents
+Keywords: ai,agent,llm,openai,anthropic,tools,framework
+Author: Artificial Analysis, Inc.
+Author-email: Artificial Analysis, Inc. <info@artificialanalysis.ai>
+License: MIT License
+         
+         Copyright (c) 2025 Artificial Analysis
+         
+         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.
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: filetype>=1.0.0
+Requires-Dist: httpx>=0.20.0
+Requires-Dist: json-schema-to-pydantic>=0.2.0
+Requires-Dist: moviepy>=2.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pillow>=10.4.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=5.0.0
+Requires-Dist: trafilatura>=1.9.0
+Requires-Dist: stirrup[litellm,e2b,docker,mcp] ; extra == 'all'
+Requires-Dist: docker>=7.0.0 ; extra == 'docker'
+Requires-Dist: python-dotenv>=1.0.0 ; extra == 'docker'
+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: Homepage, https://github.com/ArtificialAnalysis/Stirrup
+Project-URL: Repository, https://github.com/ArtificialAnalysis/Stirrup
+Provides-Extra: all
+Provides-Extra: docker
+Provides-Extra: e2b
+Provides-Extra: litellm
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="">
+    <picture>
+        <img alt="Stirrup" src="assets/stirrup-banner.png" width="700">
+    </picture>
+  </a>
+  <br></br>
+  <h1>The lightweight foundation for building agents</h1>
+<br>
+</div>
+
+
+<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>
+</p>
+
+
+Stirrup is a lightweight framework, or starting point template, for building agents. It differs from other agent frameworks by:
+
+- **Working with the model, not against it:** Stirrup gets out of the way and lets the model choose its own approach to completing tasks (similar to Claude Code). Many frameworks impose rigid workflows that can degrade results.
+- **Best practices and tools built-in:** We analyzed the leading agents (Claude Code, Codex, and others) to understand and incorporate best practices relating to topics like context management and foundational tools (e.g., code execution).
+- **Fully customizable:** Use Stirrup as a package or as a starting template to build your own fully customized agents.
+
+## Features
+
+- **Essential tools built-in:**
+  - Online search / web browsing
+  - Code execution (local, Docker container, E2B sandbox)
+  - MCP client
+  - Document input and output
+- **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
+- **Multimodal support:** Process images, video, and audio with automatic format conversion
+
+## Installation
+
+```bash
+# Core framework
+uv pip install stirrup      # or: uv add stirrup
+
+# With all optional components
+uv 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]
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from stirrup import Agent
+from stirrup.clients.chat_completions_client import ChatCompletionsClient
+
+
+async def main() -> None:
+    """Run an agent that searches the web and creates a chart."""
+
+    # Create client using ChatCompletionsClient
+    # Automatically uses OPENROUTER_API_KEY environment variable
+    client = ChatCompletionsClient(
+        base_url="https://openrouter.ai/api/v1",
+        model="anthropic/claude-sonnet-4.5",
+    )
+
+    # As no tools are provided, the agent will use the default tools, which consist of:
+    # - Web tools (web search and web fetching, note web search requires BRAVE_API_KEY)
+    # - Local code execution tool (to execute shell commands)
+    agent = Agent(client=client, name="agent", max_turns=15)
+
+    # Run with session context - handles tool lifecycle, logging and file outputs
+    async with agent.session(output_dir="./output/getting_started_example") as session:
+        finish_params, history, metadata = await session.run(
+            """
+            What is the population of Australia over the last 3 years? Search the web to find out and create a
+            simple chart using matplotlib showing the current population per year."""
+        )
+
+        print("Finish params: ", finish_params)
+        print("History: ", history)
+        print("Metadata: ", metadata)
+
+
+if __name__ == "__main__":
+    asyncio.run(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.
+
+## How It Works
+
+- **`Agent`** - Configures and runs the agent loop until a finish tool is called or max turns reached
+- **`session()`** - Context manager that sets up tools, manages files, and handles cleanup
+- **`Tool`** - Define tools with Pydantic parameters
+- **`ToolProvider`** - Manage tools that require lifecycle (connections, temp directories, etc.)
+- **`DEFAULT_TOOLS`** - Standard tools included by default: code execution and web tools
+
+## Using Other LLM Providers
+
+For non-OpenAI providers, change the base URL of the `ChatCompletionsClient`, use the `LiteLLMClient` (requires installation of optional `stirrup[litellm]` dependencies), or create your own client.
+
+### OpenAI-Compatible APIs
+
+```python
+# Create client using Deepseek's OpenAI-compatible endpoint
+client = ChatCompletionsClient(
+    base_url="https://api.deepseek.com",
+    model="deepseek-chat",  # or "deepseek-reasoner" for R1
+    api_key=os.environ["DEEPSEEK_API_KEY"],
+)
+
+agent = Agent(client=client, name="deepseek_agent")
+```
+
+### LiteLLM (Anthropic, Google, etc.)
+
+```python
+# Create LiteLLM client for Anthropic Claude
+# See https://docs.litellm.ai/docs/providers for all supported providers
+client = LiteLLMClient(
+    model_slug="anthropic/claude-sonnet-4-5",
+    max_tokens=200_000,
+)
+
+# Pass client to Agent - model info comes from client.model_slug
+agent = Agent(
+    client=client,
+    name="claude_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.
+
+## Default Tools
+
+When you create an `Agent` without specifying tools, it uses `DEFAULT_TOOLS`:
+
+| Tool Provider               | Tools Provided            | Description                                                  |
+| --------------------------- | ------------------------- | ------------------------------------------------------------ |
+| `LocalCodeExecToolProvider` | `code_exec`               | Execute shell commands in an isolated temp directory         |
+| `WebToolProvider`           | `web_fetch`, `web_search` | Fetch web pages and search (search requires `BRAVE_API_KEY`) |
+
+## Extending with Pre-Built Tools
+
+```python
+import asyncio
+
+from stirrup import Agent
+from stirrup.clients.chat_completions_client import ChatCompletionsClient
+from stirrup.tools import CALCULATOR_TOOL, DEFAULT_TOOLS
+
+# Create client for OpenRouter
+client = ChatCompletionsClient(
+    base_url="https://openrouter.ai/api/v1",
+    model="anthropic/claude-sonnet-4.5",
+)
+
+# Create agent with default tools + calculator tool
+agent = Agent(
+    client=client,
+    name="web_calculator_agent",
+    tools=[*DEFAULT_TOOLS, CALCULATOR_TOOL],
+)
+```
+
+## Defining Custom Tools
+
+```python
+from pydantic import BaseModel, Field
+
+from stirrup import Agent, Tool, ToolResult, ToolUseCountMetadata
+from stirrup.clients.chat_completions_client import ChatCompletionsClient
+from stirrup.tools import DEFAULT_TOOLS
+
+
+class GreetParams(BaseModel):
+    """Parameters for the greet tool."""
+
+    name: str = Field(description="Name of the person to greet")
+    formal: bool = Field(default=False, description="Use formal greeting")
+
+
+def greet(params: GreetParams) -> ToolResult[ToolUseCountMetadata]:
+    greeting = f"Good day, {params.name}." if params.formal else f"Hey {params.name}!"
+
+    return ToolResult(
+        content=greeting,
+        metadata=ToolUseCountMetadata(),
+    )
+
+
+GREET_TOOL = Tool(
+    name="greet",
+    description="Greet someone by name",
+    parameters=GreetParams,
+    executor=greet,
+)
+
+# Create client for OpenRouter
+client = ChatCompletionsClient(
+    base_url="https://openrouter.ai/api/v1",
+    model="anthropic/claude-sonnet-4.5",
+)
+
+# Add custom tool to default tools
+agent = Agent(
+    client=client,
+    name="greeting_agent",
+    tools=[*DEFAULT_TOOLS, GREET_TOOL],
+)
+```
+
+## 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
+
+## Documentation
+
+Full documentation: [artificialanalysis.github.io/Stirrup](https://artificialanalysis.github.io/Stirrup)
+
+Build and serve locally:
+
+```bash
+uv run mkdocs serve
+```
+
+## Development
+
+```bash
+# Format and lint code
+uv run ruff format
+uv run ruff check
+
+# Type check
+uv run ty check
+
+# Run tests
+uv run pytest tests
+```
+
+## License
+
+Licensed under the [MIT LICENSE](LICENSE).

stirrup-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+stirrup/__init__.py,sha256=Dol0Uui-gBslpplfEUrgxkqqJWr1ucZJej5finNvCeI,1869
+stirrup/clients/__init__.py,sha256=oO8VMHmbUhoxFyC0JLQs_kUFNSRlvTj5xz0FgzBb98E,405
+stirrup/clients/chat_completions_client.py,sha256=p_EeXqRuo6mWnzgMhy22SWdHE6_OXIRyABvCKgHdnu4,7586
+stirrup/clients/litellm_client.py,sha256=J-HDv7ZZTkNYC-aeSNyd7xTDd_5r8DEeXOPz9eQMC7A,4985
+stirrup/clients/utils.py,sha256=Yyeh6unQSvqgDTDhjpD5DoRu_wP_nWfsNv9DGXQwgo8,5452
+stirrup/constants.py,sha256=h3NzsePJ4FKpImTpV5xtFeJarKb67jR_6n89tNOkQYs,523
+stirrup/core/__init__.py,sha256=ReBVl7B9h_FNkZ77vCx2xlfuK1JuQ0yTSXrEgc4tONU,39
+stirrup/core/agent.py,sha256=8nHlcyh5Ji3_vXSH6dPbKvFCV7Q7cmnJcSaj0Sy-zto,49158
+stirrup/core/exceptions.py,sha256=CzLVAi7Ns-t9BWSkqQUCB7ypVHAesV2s4a09-i0NXyQ,213
+stirrup/core/models.py,sha256=ONiCFC9NcoeArX4629n9s5FNLi02ynqZRiCxJbzhr1Q,21061
+stirrup/prompts/__init__.py,sha256=e4bpTktBaFPuO_bIW5DelGNWtT6_NIUqnD2lRv8n89I,796
+stirrup/prompts/base_system_prompt.txt,sha256=KZ2_JhJ91u4oMqRZvhuAp99nb6ZkXkJdVbIRN6drVME,348
+stirrup/prompts/message_summarizer.txt,sha256=uQoTxreMuC42rTGSZmoH1Dnj06WrEQb0gLkDvVMhosQ,1173
+stirrup/prompts/message_summarizer_bridge.txt,sha256=sWbfnHtI6RWemBIyQsnqHMGpnU-E6FTbfUC6rvkEHLY,372
+stirrup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stirrup/tools/__init__.py,sha256=ohyeMvXb6oURiAyoHi0VmC9ksZSRyGleT341VNzHCy4,2714
+stirrup/tools/calculator.py,sha256=JkuGmGZJtaKbC4vHVrIph4aTjlGcFMhhv5MB1ntqgv4,1278
+stirrup/tools/code_backends/__init__.py,sha256=O3Rs76r0YcQ27voTrx_zuhIEFawK3b1TQdKi70MORG8,987
+stirrup/tools/code_backends/base.py,sha256=Nx0tTDX4GKoBWQK2F953vSsFgWCcOd_1WNtYCA4FG4o,17021
+stirrup/tools/code_backends/docker.py,sha256=xtQmAwGkXc9jKlrN2ydYn66HpQ8cQW1b-4bTmN87S4U,29616
+stirrup/tools/code_backends/e2b.py,sha256=1V52m1pQ4uBjGRL9iBeJik2beWURLupODCFtAtng9sE,13696
+stirrup/tools/code_backends/local.py,sha256=6KOn-4aoySHVElitqWX5yN_WDrpJkQlsgSif2q0hYi8,18903
+stirrup/tools/finish.py,sha256=K_NxwOwdvncT2QTua2A_8lZ9MwK4WQQ5FL2gdUrE29c,936
+stirrup/tools/mcp.py,sha256=4wWYae95y8Bs7e36hHwnxRfVVj0PABrsRStw492lLaw,18749
+stirrup/tools/view_image.py,sha256=zazCpZMtLOD6lplLPYGNQ8JeYfc0oUDJoUUyVAp3AMU,3126
+stirrup/tools/web.py,sha256=2yfBJsu8GgFI7Oh1dFlXwNaXth6WQfGpbJFU-rV-yuI,12261
+stirrup/utils/__init__.py,sha256=4kcuExrphSXqgxRgu1q8_Z6Rrb9aAZpIo4Xq4S9Twuk,230
+stirrup/utils/logging.py,sha256=3Li6MhjLJWwaXHDZ06EjgW42XDL6V3ZDt9rccV_ZYZ4,34292
+stirrup/utils/text.py,sha256=3lGlcXFzQ-Mclsbu7wJciG3CcHvQ_Sk98tqOZxYLlGw,479
+stirrup-0.1.0.dist-info/WHEEL,sha256=xDCZ-UyfvkGuEHPeI7BcJzYKIZzdqN8A8o1M5Om8IyA,79
+stirrup-0.1.0.dist-info/METADATA,sha256=dUTUx3W620GhVbZBqXuaI6nwR-4Q6vLmfiE_4BE1S6A,12003
+stirrup-0.1.0.dist-info/RECORD,,

stirrup-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.17
+Root-Is-Purelib: true
+Tag: py3-none-any