agentory 0.1.0__tar.gz

agentory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathis Kristoffer Arends
+
+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.

agentory-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: agentory
+Version: 0.1.0
+Summary: Minimal agent runtime with MCP integration, declarative tools, and streaming
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: py-llmify>=0.3.0
+Provides-Extra: openai
+Requires-Dist: py-llmify[openai]>=0.3.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: py-llmify[anthropic]>=0.3.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: py-llmify[all]>=0.3.0; extra == "all"
+Dynamic: license-file
+
+# agentory
+
+A lightweight Python library for building tool-calling agents.
+
+## Installation
+
+```bash
+pip install agentory
+```
+
+Install only the providers you actually need
+
+```bash
+pip install "agentory[openai]" # + azure
+pip install "agentory[anthropic]"
+pip install "agentory[all]"
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import asyncio
+from llmify import ChatOpenAI
+from agentory import Agent, Tools, ToolCallEvent
+
+tools = Tools()
+
+@tools.action("Return the current UTC time as an ISO-8601 string.")
+def get_time() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
+async def main():
+    llm = ChatOpenAI(model="gpt-5.4-mini")
+    agent = Agent(
+        instructions="You are a helpful assistant.",
+        llm=llm,
+        tools=tools,
+    )
+    async for event in agent.run("What time is it?"):
+        if isinstance(event, ToolCallEvent):
+            print(f"[tool] {event.tool_name}: {event.status}")
+        else:
+            print(event)
+
+asyncio.run(main())
+```
+
+## Core API
+
+### `Agent`
+
+```python
+Agent(
+    instructions: str,
+    llm: ChatOpenAI | ChatAzureOpenAI | ChatAnthropic,
+    tools: Tools | None = None,
+    mcp_servers: list[MCPServer] | None = None,
+    skills: list[Skill] | None = None,
+    max_iterations: int = 10,
+    context: T | None = None,
+)
+```
+
+The main agent class. Call `agent.run(task)` to get an `AsyncIterator[StreamEvent]` that yields either plain `str` chunks or `ToolCallEvent` objects.
+
+`context` is an arbitrary value injected into every tool function that declares a `context` parameter.
+
+### `Tools`
+
+A registry that turns plain functions into LLM-callable tools.
+
+```python
+tools = Tools()
+
+@tools.action("Fetch the content of a URL.", status=lambda a: a["url"])
+async def fetch(url: str) -> str:
+    ...
+```
+
+- **`description`** – shown to the LLM in the tool schema.
+- **`name`** – overrides the function name.
+- **`status`** – a string or callable producing a human-readable status shown during streaming.
+
+Type hints on parameters are automatically converted to JSON Schema. Use `Annotated[str, "description"]` to attach per-parameter descriptions.
+
+### `Tool`
+
+Low-level dataclass representing a single tool. Usually created via `Tools.action`; useful when constructing tools manually or from MCP servers.
+
+### `Skill`
+
+A piece of reusable instructions injected into the system prompt inside a `<skill>` block.
+
+```python
+from pathlib import Path
+from agentory import Skill
+
+skill = Skill.from_path(Path("my_skill.md"))
+# or load SKILL.md from a directory:
+skill = Skill.from_directory(Path("skills/my_skill/"))
+
+agent = Agent(instructions="...", llm=llm, skills=[skill])
+```
+
+Skill files use optional YAML frontmatter for `name` and `description`:
+
+```markdown
+---
+name: web-search
+description: Search the web for information
+---
+
+Use the search tool whenever the user asks about recent events...
+```
+
+### `MCPServerStdio`
+
+Connects to any [Model Context Protocol](https://modelcontextprotocol.io) server over stdio and exposes its tools to the agent.
+
+```python
+from agentory import Agent, MCPServerStdio
+
+server = MCPServerStdio(
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+)
+
+async with server:
+    agent = Agent(instructions="...", llm=llm, mcp_servers=[server])
+    async for event in agent.run("List files in /tmp"):
+        print(event)
+```
+
+**Options:**
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `command` | — | Executable to spawn |
+| `args` | `[]` | Arguments for the command |
+| `env` | `None` | Extra environment variables (inherits current env when `None`) |
+| `cache_tools_list` | `True` | Cache tool discovery after first call |
+| `allowed_tools` | `None` | Whitelist of tool names to expose |
+
+### `StreamEvent`
+
+```python
+type StreamEvent = str | ToolCallEvent
+```
+
+Events yielded by `agent.run()`. A plain `str` is a text chunk from the LLM; a `ToolCallEvent` signals that a tool is being called.
+
+```python
+@dataclass
+class ToolCallEvent:
+    tool_name: str
+    status: str | None
+```

agentory-0.1.0/README.md

@@ -0,0 +1,159 @@
+# agentory
+
+A lightweight Python library for building tool-calling agents.
+
+## Installation
+
+```bash
+pip install agentory
+```
+
+Install only the providers you actually need
+
+```bash
+pip install "agentory[openai]" # + azure
+pip install "agentory[anthropic]"
+pip install "agentory[all]"
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import asyncio
+from llmify import ChatOpenAI
+from agentory import Agent, Tools, ToolCallEvent
+
+tools = Tools()
+
+@tools.action("Return the current UTC time as an ISO-8601 string.")
+def get_time() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
+async def main():
+    llm = ChatOpenAI(model="gpt-5.4-mini")
+    agent = Agent(
+        instructions="You are a helpful assistant.",
+        llm=llm,
+        tools=tools,
+    )
+    async for event in agent.run("What time is it?"):
+        if isinstance(event, ToolCallEvent):
+            print(f"[tool] {event.tool_name}: {event.status}")
+        else:
+            print(event)
+
+asyncio.run(main())
+```
+
+## Core API
+
+### `Agent`
+
+```python
+Agent(
+    instructions: str,
+    llm: ChatOpenAI | ChatAzureOpenAI | ChatAnthropic,
+    tools: Tools | None = None,
+    mcp_servers: list[MCPServer] | None = None,
+    skills: list[Skill] | None = None,
+    max_iterations: int = 10,
+    context: T | None = None,
+)
+```
+
+The main agent class. Call `agent.run(task)` to get an `AsyncIterator[StreamEvent]` that yields either plain `str` chunks or `ToolCallEvent` objects.
+
+`context` is an arbitrary value injected into every tool function that declares a `context` parameter.
+
+### `Tools`
+
+A registry that turns plain functions into LLM-callable tools.
+
+```python
+tools = Tools()
+
+@tools.action("Fetch the content of a URL.", status=lambda a: a["url"])
+async def fetch(url: str) -> str:
+    ...
+```
+
+- **`description`** – shown to the LLM in the tool schema.
+- **`name`** – overrides the function name.
+- **`status`** – a string or callable producing a human-readable status shown during streaming.
+
+Type hints on parameters are automatically converted to JSON Schema. Use `Annotated[str, "description"]` to attach per-parameter descriptions.
+
+### `Tool`
+
+Low-level dataclass representing a single tool. Usually created via `Tools.action`; useful when constructing tools manually or from MCP servers.
+
+### `Skill`
+
+A piece of reusable instructions injected into the system prompt inside a `<skill>` block.
+
+```python
+from pathlib import Path
+from agentory import Skill
+
+skill = Skill.from_path(Path("my_skill.md"))
+# or load SKILL.md from a directory:
+skill = Skill.from_directory(Path("skills/my_skill/"))
+
+agent = Agent(instructions="...", llm=llm, skills=[skill])
+```
+
+Skill files use optional YAML frontmatter for `name` and `description`:
+
+```markdown
+---
+name: web-search
+description: Search the web for information
+---
+
+Use the search tool whenever the user asks about recent events...
+```
+
+### `MCPServerStdio`
+
+Connects to any [Model Context Protocol](https://modelcontextprotocol.io) server over stdio and exposes its tools to the agent.
+
+```python
+from agentory import Agent, MCPServerStdio
+
+server = MCPServerStdio(
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+)
+
+async with server:
+    agent = Agent(instructions="...", llm=llm, mcp_servers=[server])
+    async for event in agent.run("List files in /tmp"):
+        print(event)
+```
+
+**Options:**
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `command` | — | Executable to spawn |
+| `args` | `[]` | Arguments for the command |
+| `env` | `None` | Extra environment variables (inherits current env when `None`) |
+| `cache_tools_list` | `True` | Cache tool discovery after first call |
+| `allowed_tools` | `None` | Whitelist of tool names to expose |
+
+### `StreamEvent`
+
+```python
+type StreamEvent = str | ToolCallEvent
+```
+
+Events yielded by `agent.run()`. A plain `str` is a text chunk from the LLM; a `ToolCallEvent` signals that a tool is being called.
+
+```python
+@dataclass
+class ToolCallEvent:
+    tool_name: str
+    status: str | None
+```

agentory-0.1.0/agentory/__init__.py

@@ -0,0 +1,17 @@
+from .agent import Agent
+from .mcp import MCPServer, MCPServerStdio
+from .skills import Skill
+from .tools import Tools
+from .tools.views import Tool
+from .views import StreamEvent, ToolCallEvent
+
+__all__ = [
+    "Agent",
+    "MCPServer",
+    "MCPServerStdio",
+    "Skill",
+    "StreamEvent",
+    "Tool",
+    "ToolCallEvent",
+    "Tools",
+]

agentory-0.1.0/agentory/agent.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from llmify import ChatModel
+from llmify.messages import (
+    AssistantMessage,
+    SystemMessage,
+    ToolResultMessage,
+    UserMessage,
+)
+
+from agentory.skills import Skill
+from agentory.tools.tools import Tools
+from agentory.views import StreamEvent, ToolCallEvent
+
+if TYPE_CHECKING:
+    from agentory.mcp.server import MCPServer
+
+
+logger = logging.getLogger(__name__)
+
+
+class Agent[T]:
+    def __init__(
+        self,
+        instructions: str,
+        llm: ChatModel,
+        tools: Tools | None = None,
+        mcp_servers: list[MCPServer] | None = None,
+        skills: list[Skill] | None = None,
+        max_iterations: int = 10,
+        context: T | None = None,
+    ) -> None:
+        self.llm = llm
+        self._instructions = instructions
+        self.tools = tools or Tools()
+        self.tools.set_context(context)
+
+        self._mcp_servers = mcp_servers or []
+        self._skills = skills or []
+        self._max_iterations = max_iterations
+        self._context: T | None = context
+
+        self._history = [SystemMessage(content=self._build_system_prompt())]
+
+    def _build_system_prompt(self) -> str:
+        if not self._skills:
+            return self._instructions
+        skills_block = "\n\n".join(skill.render() for skill in self._skills)
+        return f"{self._instructions}\n\n<skills>\n{skills_block}\n</skills>"
+
+    async def __aenter__(self) -> Agent[T]:
+        await self._connect_mcp_servers()
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self._cleanup_mcp_servers()
+
+    async def run(self, task: str) -> AsyncIterator[StreamEvent]:
+        self._history.append(UserMessage(content=task))
+        schema = self.tools.to_schema() or None
+        iterations = 0
+
+        while True:
+            if iterations >= self._max_iterations:
+                yield "[max iterations reached]"
+                return
+            iterations += 1
+
+            response = await self.llm.invoke(self._history, tools=schema)
+
+            if not response.tool_calls:
+                content = response.completion or ""
+                self._history.append(AssistantMessage(content=content))
+                yield content
+                return
+
+            self._history.append(
+                AssistantMessage(content=None, tool_calls=response.tool_calls)
+            )
+
+            for call in response.tool_calls:
+                tool = self.tools.get(call.function.name)
+                tool_args = json.loads(call.function.arguments)
+                yield ToolCallEvent(
+                    tool_name=call.function.name,
+                    status=tool.render_status(tool_args) if tool else None,
+                )
+                try:
+                    result = await self.tools.execute(call.function.name, tool_args)
+                except Exception as e:
+                    result = json.dumps({"error": str(e), "tool": call.function.name})
+
+                self._history.append(
+                    ToolResultMessage(tool_call_id=call.id, content=result)
+                )
+                self._history.append(
+                    ToolResultMessage(tool_call_id=call.id, content=result)
+                )
+
+    async def _connect_mcp_servers(self) -> None:
+        for server in self._mcp_servers:
+            await server.connect()
+            await self.tools.register_mcp_server(server)
+
+    async def _cleanup_mcp_servers(self) -> None:
+        for server in self._mcp_servers:
+            await server.cleanup()
+
+    def reset(self) -> None:
+        self._history = [SystemMessage(content=self._build_system_prompt())]

agentory-0.1.0/agentory/mcp/__init__.py

@@ -0,0 +1,3 @@
+from .server import MCPServer, MCPServerStdio
+
+__all__ = ["MCPServer", "MCPServerStdio"]

agentory-0.1.0/agentory/mcp/schemas.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class JsonRpcRequest(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    jsonrpc: str = "2.0"
+    id: int
+    method: str
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class JsonRpcNotification(BaseModel):
+    jsonrpc: str = "2.0"
+    method: str
+    params: dict[str, Any] | None = None
+
+
+class JsonRpcError(BaseModel):
+    code: int
+    message: str
+    data: Any = None
+
+
+class JsonRpcResponse(BaseModel):
+    jsonrpc: str
+    id: int | None = None
+    result: dict[str, Any] | None = None
+    error: JsonRpcError | None = None
+
+    def unwrap(self) -> dict[str, Any]:
+        if self.error:
+            raise RuntimeError(f"MCP error: {self.error.model_dump()}")
+        return self.result or {}
+
+
+class ClientInfo(BaseModel):
+    name: str
+    version: str
+
+
+class InitializeParams(BaseModel):
+    protocolVersion: str = "2024-11-05"
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    clientInfo: ClientInfo
+
+
+class MCPServerStdioConfig(BaseModel):
+    command: str
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] | None = None
+    cache_tools_list: bool = True
+    allowed_tools: list[str] | None = None
+
+
+class MCPToolInputSchema(BaseModel):
+    properties: dict[str, Any] = Field(default_factory=dict)
+    required: list[str] = Field(default_factory=list)
+
+
+class MCPToolDefinition(BaseModel):
+    name: str
+    description: str | None = None
+    inputSchema: MCPToolInputSchema = Field(default_factory=MCPToolInputSchema)
+
+
+class MCPToolsListResult(BaseModel):
+    tools: list[MCPToolDefinition] = Field(default_factory=list)