agentropic 0.1.0__tar.gz

agentropic-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env

agentropic-0.1.0/LICENSE

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

agentropic-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: agentropic
+Version: 0.1.0
+Summary: A minimal, hackable agentic framework: LLM calls via litellm, @tool-decorated functions, and MCP server support.
+Author-email: Vishal Tiwari <vishaltiwari.up2019@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,agents,ai,litellm,llm,mcp,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# agentropic
+
+A small, hackable agentic framework in ~500 lines you fully own and can read
+top to bottom in an afternoon:
+
+- **LLM calls** go through [litellm](https://github.com/BerriAI/litellm), so you get
+  every provider (OpenAI, Anthropic, Gemini, Ollama, Bedrock, 100+ more) for free.
+- **`@tool` decorator** turns any python function into an LLM-callable tool with
+  an auto-generated JSON schema (from type hints + docstring).
+- **MCP support** — connect to any Model Context Protocol server (stdio or SSE)
+  and its tools show up in your agent automatically, indistinguishable from
+  local tools.
+- **Agent loop** handles the call → tool-call → tool-result → call cycle for you,
+  with memory, streaming, and a max-iteration safety valve.
+
+## Install (once published)
+
+```bash
+pip install agentropic
+```
+
+## Quick start
+
+```python
+import asyncio
+from agentropic import Agent, tool
+
+@tool()
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"It's sunny in {city}."
+
+async def main():
+    agent = Agent(
+        name="assistant",
+        model="gpt-4o-mini",         # any litellm model string
+        instructions="You are helpful and concise.",
+        tools=[get_weather],
+    )
+    print(await agent.arun("What's the weather in Paris?"))
+
+asyncio.run(main())
+```
+
+Sync usage: `agent.run("...")` (wraps `arun` in `asyncio.run` for you).
+
+## Using MCP servers
+
+```python
+from agentropic import Agent
+from agentropic.mcp import StdioServer
+
+agent = Agent(
+    name="fs-agent",
+    model="gpt-4o-mini",
+    mcp_servers=[
+        StdioServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."]),
+    ],
+)
+print(await agent.arun("List the files in the current directory."))
+```
+
+Requires the optional MCP dependency: `pip install "agentropic[mcp]"`.
+
+## Architecture
+
+```
+src/agentropic/
+├── __init__.py     # public API surface
+├── agent.py         # the run loop: LLM <-> tools <-> memory
+├── llm.py            # thin litellm wrapper (swap providers here)
+├── tools.py           # @tool decorator, Tool, ToolRegistry, schema generation
+├── memory.py           # in-memory conversation history (swap for your own store)
+└── mcp/
+    └── client.py        # MCP stdio/SSE client -> Tool adapter
+```
+
+Everything is a plain, editable python file — no hidden magic, no plugin
+registry you can't inspect. Read `agent.py` first; that's the whole loop.
+
+## Extending it
+
+- **Custom memory / persistence**: implement `.add()`, `.get()`, `.clear()`
+  matching `Memory` and pass `memory=YourMemory()` to `Agent`.
+- **Streaming with tool calls**: `astream()` currently falls back to a
+  non-streamed `arun()` when tools are registered — extend it if you need
+  token-level streaming mid-tool-loop.
+- **Multi-agent handoff**: compose multiple `Agent` instances and route
+  between them yourself, or wrap one agent's `arun` as a tool for another.
+
+## Publishing your fork to PyPI
+
+1. **Pick a unique name** and check it's free:
+   `pip index versions your-name` or just search on https://pypi.org.
+   Update `name` in `pyproject.toml` (and rename the `src/agentropic` folder
+   if you want the import name to match).
+
+2. **Bump the version** in `pyproject.toml` and `src/agentropic/__init__.py`
+   (`__version__`).
+
+3. **Install build tooling**:
+   ```bash
+   pip install build twine
+   ```
+
+4. **Build**:
+   ```bash
+   python -m build
+   ```
+   This produces `dist/agentropic-0.1.0.tar.gz` and `dist/agentropic-0.1.0-py3-none-any.whl`.
+
+5. **Test on TestPyPI first** (highly recommended):
+   ```bash
+   python -m twine upload --repository testpypi dist/*
+   pip install --index-url https://test.pypi.org/simple/ agentropic
+   ```
+   You'll need a free account at https://test.pypi.org and an API token
+   (Account Settings → API tokens). Use `__token__` as the username and the
+   token (starting `pypi-...`) as the password, or store it in `~/.pypirc`:
+   ```ini
+   [testpypi]
+   username = __token__
+   password = pypi-...your-token...
+   ```
+
+6. **Publish for real** once it installs and works:
+   ```bash
+   python -m twine upload dist/*
+   ```
+   (needs an API token from https://pypi.org/manage/account/ the same way).
+
+7. **Every future release**: bump the version number, `python -m build` again
+   (delete the old `dist/` first), `twine upload dist/*`.
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — do whatever you want with it.

agentropic-0.1.0/README.md

@@ -0,0 +1,144 @@
+# agentropic
+
+A small, hackable agentic framework in ~500 lines you fully own and can read
+top to bottom in an afternoon:
+
+- **LLM calls** go through [litellm](https://github.com/BerriAI/litellm), so you get
+  every provider (OpenAI, Anthropic, Gemini, Ollama, Bedrock, 100+ more) for free.
+- **`@tool` decorator** turns any python function into an LLM-callable tool with
+  an auto-generated JSON schema (from type hints + docstring).
+- **MCP support** — connect to any Model Context Protocol server (stdio or SSE)
+  and its tools show up in your agent automatically, indistinguishable from
+  local tools.
+- **Agent loop** handles the call → tool-call → tool-result → call cycle for you,
+  with memory, streaming, and a max-iteration safety valve.
+
+## Install (once published)
+
+```bash
+pip install agentropic
+```
+
+## Quick start
+
+```python
+import asyncio
+from agentropic import Agent, tool
+
+@tool()
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"It's sunny in {city}."
+
+async def main():
+    agent = Agent(
+        name="assistant",
+        model="gpt-4o-mini",         # any litellm model string
+        instructions="You are helpful and concise.",
+        tools=[get_weather],
+    )
+    print(await agent.arun("What's the weather in Paris?"))
+
+asyncio.run(main())
+```
+
+Sync usage: `agent.run("...")` (wraps `arun` in `asyncio.run` for you).
+
+## Using MCP servers
+
+```python
+from agentropic import Agent
+from agentropic.mcp import StdioServer
+
+agent = Agent(
+    name="fs-agent",
+    model="gpt-4o-mini",
+    mcp_servers=[
+        StdioServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."]),
+    ],
+)
+print(await agent.arun("List the files in the current directory."))
+```
+
+Requires the optional MCP dependency: `pip install "agentropic[mcp]"`.
+
+## Architecture
+
+```
+src/agentropic/
+├── __init__.py     # public API surface
+├── agent.py         # the run loop: LLM <-> tools <-> memory
+├── llm.py            # thin litellm wrapper (swap providers here)
+├── tools.py           # @tool decorator, Tool, ToolRegistry, schema generation
+├── memory.py           # in-memory conversation history (swap for your own store)
+└── mcp/
+    └── client.py        # MCP stdio/SSE client -> Tool adapter
+```
+
+Everything is a plain, editable python file — no hidden magic, no plugin
+registry you can't inspect. Read `agent.py` first; that's the whole loop.
+
+## Extending it
+
+- **Custom memory / persistence**: implement `.add()`, `.get()`, `.clear()`
+  matching `Memory` and pass `memory=YourMemory()` to `Agent`.
+- **Streaming with tool calls**: `astream()` currently falls back to a
+  non-streamed `arun()` when tools are registered — extend it if you need
+  token-level streaming mid-tool-loop.
+- **Multi-agent handoff**: compose multiple `Agent` instances and route
+  between them yourself, or wrap one agent's `arun` as a tool for another.
+
+## Publishing your fork to PyPI
+
+1. **Pick a unique name** and check it's free:
+   `pip index versions your-name` or just search on https://pypi.org.
+   Update `name` in `pyproject.toml` (and rename the `src/agentropic` folder
+   if you want the import name to match).
+
+2. **Bump the version** in `pyproject.toml` and `src/agentropic/__init__.py`
+   (`__version__`).
+
+3. **Install build tooling**:
+   ```bash
+   pip install build twine
+   ```
+
+4. **Build**:
+   ```bash
+   python -m build
+   ```
+   This produces `dist/agentropic-0.1.0.tar.gz` and `dist/agentropic-0.1.0-py3-none-any.whl`.
+
+5. **Test on TestPyPI first** (highly recommended):
+   ```bash
+   python -m twine upload --repository testpypi dist/*
+   pip install --index-url https://test.pypi.org/simple/ agentropic
+   ```
+   You'll need a free account at https://test.pypi.org and an API token
+   (Account Settings → API tokens). Use `__token__` as the username and the
+   token (starting `pypi-...`) as the password, or store it in `~/.pypirc`:
+   ```ini
+   [testpypi]
+   username = __token__
+   password = pypi-...your-token...
+   ```
+
+6. **Publish for real** once it installs and works:
+   ```bash
+   python -m twine upload dist/*
+   ```
+   (needs an API token from https://pypi.org/manage/account/ the same way).
+
+7. **Every future release**: bump the version number, `python -m build` again
+   (delete the old `dist/` first), `twine upload dist/*`.
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — do whatever you want with it.

agentropic-0.1.0/examples/basic_agent.py

@@ -0,0 +1,47 @@
+"""
+Run with:  OPENAI_API_KEY=sk-... python examples/basic_agent.py
+(or set whichever env var litellm expects for your chosen model provider)
+"""
+import asyncio
+
+from agentropic import Agent, tool
+from agentropic.mcp import StdioServer
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+
+@tool()
+def get_weather(city: str) -> str:
+    """Get the current weather for a given city."""
+    # Pretend implementation — replace with a real API call.
+    return f"It's sunny and 28C in {city}."
+
+
+@tool(name="add_numbers", description="Add two numbers together.")
+def add(a: int, b: int) -> int:
+    return a + b
+
+
+async def main():
+    agent = Agent(
+        name="assistant",
+        model="gemini/gemini-2.5-flash-lite",  
+        api_key=os.getenv("api_key"),  
+        instructions="You are a concise, helpful assistant. Use tools when needed.",
+        tools=[get_weather, add],
+        # Optional: pull in tools from a live MCP server too.
+        # mcp_servers=[StdioServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])],
+        max_iterations=6,
+    )
+
+    reply = await agent.arun("What's the weather in Tokyo, and what's 12 + 30?")
+    print(reply)
+
+    # Multi-turn: memory carries over automatically.
+    reply2 = await agent.arun("Say that last sum again, but doubled.")
+    print(reply2)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentropic-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentropic"
+version = "0.1.0"
+description = "A minimal, hackable agentic framework: LLM calls via litellm, @tool-decorated functions, and MCP server support."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Vishal Tiwari", email = "vishaltiwari.up2019@gmail.com" }
+]
+keywords = ["llm", "agent", "agents", "litellm", "mcp", "tools", "ai"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "litellm>=1.40.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0"]
+dev = ["pytest", "pytest-asyncio", "build", "twine"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentropic"]

agentropic-0.1.0/src/agentropic/__init__.py

@@ -0,0 +1,22 @@
+from .agent import Agent, AgentError
+from .tools import tool, Tool, ToolRegistry
+from .llm import LLMClient, LLMResponse
+from .memory import Memory
+from .mcp.client import MCPConnection, StdioServer, SSEServer, MCPServerConfig
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentError",
+    "tool",
+    "Tool",
+    "ToolRegistry",
+    "LLMClient",
+    "LLMResponse",
+    "Memory",
+    "MCPConnection",
+    "StdioServer",
+    "SSEServer",
+    "MCPServerConfig",
+]

agentropic-0.1.0/src/agentropic/agent.py

@@ -0,0 +1,159 @@
+"""The Agent: ties together an LLMClient, a ToolRegistry, memory, and
+optional MCP servers into a single run()/arun() loop that:
+  1. sends messages + tool schemas to the LLM
+  2. if the LLM asks for tool calls, executes them and feeds results back
+  3. repeats until the LLM returns a final answer or max_iterations hits
+"""
+from __future__ import annotations
+
+import json
+import typing as t
+
+from .llm import LLMClient
+from .memory import Memory
+from .tools import Tool, ToolRegistry
+from .mcp.client import MCPConnection, MCPServerConfig
+
+
+class AgentError(Exception):
+    pass
+
+
+class Agent:
+    def __init__(
+        self,
+        name: str,
+        model: str,
+        instructions: str = "You are a helpful assistant.",
+        tools: t.Optional[list] = None,
+        mcp_servers: t.Optional[list[MCPServerConfig]] = None,
+        memory: t.Optional[Memory] = None,
+        max_iterations: int = 10,
+        api_key: t.Optional[str] = None,
+        api_base: t.Optional[str] = None,
+        temperature: float = 0.7,
+        **llm_kwargs,
+    ):
+        self.name = name
+        self.instructions = instructions
+        self.registry = ToolRegistry(tools)
+        self.mcp_servers = mcp_servers or []
+        self.memory = memory or Memory()
+        self.max_iterations = max_iterations
+        self.llm = LLMClient(
+            model=model,
+            api_key=api_key,
+            api_base=api_base,
+            temperature=temperature,
+            extra_params=llm_kwargs,
+        )
+        self._mcp_tools_loaded = False
+
+    # -- tool management -------------------------------------------------
+
+    def add_tool(self, item: t.Union[Tool, t.Callable]) -> Tool:
+        return self.registry.add(item)
+
+    async def _load_mcp_tools(self) -> None:
+        if self._mcp_tools_loaded or not self.mcp_servers:
+            return
+        for server_config in self.mcp_servers:
+            async with MCPConnection(server_config) as conn:
+                for mcp_tool in await conn.list_tools():
+                    self.registry.add(mcp_tool)
+        self._mcp_tools_loaded = True
+
+    # -- message building --------------------------------------------------
+
+    def _build_messages(self, user_input: str) -> list[dict]:
+        messages = [{"role": "system", "content": self.instructions}]
+        messages.extend(self.memory.get())
+        messages.append({"role": "user", "content": user_input})
+        return messages
+
+    async def _execute_tool_call(self, tool_call) -> dict:
+        name = tool_call.function.name
+        try:
+            args = json.loads(tool_call.function.arguments or "{}")
+        except json.JSONDecodeError:
+            args = {}
+
+        tl = self.registry.get(name)
+        if tl is None:
+            result = f"Error: tool '{name}' is not registered."
+        else:
+            try:
+                result = await tl.acall(**args)
+            except Exception as exc:  # tool errors go back to the LLM, not raised
+                result = f"Error calling tool '{name}': {exc}"
+
+        return {
+            "role": "tool",
+            "tool_call_id": tool_call.id,
+            "name": name,
+            "content": str(result),
+        }
+
+    # -- public API ---------------------------------------------------------
+
+    def run(self, user_input: str) -> str:
+        import asyncio
+
+        return asyncio.run(self.arun(user_input))
+
+    async def arun(self, user_input: str) -> str:
+        await self._load_mcp_tools()
+
+        messages = self._build_messages(user_input)
+        self.memory.add("user", user_input)
+
+        tools_schema = self.registry.to_openai_tools() or None
+
+        for _ in range(self.max_iterations):
+            response = await self.llm.acomplete(messages, tools=tools_schema)
+
+            if response.tool_calls:
+                assistant_msg = {
+                    "role": "assistant",
+                    "content": response.content or "",
+                    "tool_calls": response.tool_calls,
+                }
+                messages.append(assistant_msg)
+                self.memory.add("assistant", response.content or "", tool_calls=response.tool_calls)
+
+                for tool_call in response.tool_calls:
+                    tool_msg = await self._execute_tool_call(tool_call)
+                    messages.append(tool_msg)
+                    self.memory.add(
+                        "tool", tool_msg["content"], tool_call_id=tool_msg["tool_call_id"], name=tool_msg["name"]
+                    )
+                continue  # let the LLM see tool results and respond again
+
+            # No tool calls -> final answer
+            self.memory.add("assistant", response.content or "")
+            return response.content or ""
+
+        raise AgentError(
+            f"Agent '{self.name}' hit max_iterations ({self.max_iterations}) without a final answer."
+        )
+
+    async def astream(self, user_input: str) -> t.AsyncIterator[str]:
+        """Simple streaming for the common case of no tool calls needed.
+        For tool-using turns, falls back to a non-streamed arun() call."""
+        await self._load_mcp_tools()
+        messages = self._build_messages(user_input)
+        tools_schema = self.registry.to_openai_tools() or None
+
+        # Peek: if tools exist, we can't safely stream+detect tool_calls with
+        # this minimal implementation, so just delegate to arun().
+        if tools_schema:
+            result = await self.arun(user_input)
+            yield result
+            return
+
+        self.memory.add("user", user_input)
+        full = ""
+        async for chunk in self.llm.astream(messages):
+            full += chunk
+            yield chunk
+        self.memory.add("assistant", full)

agentropic-0.1.0/src/agentropic/llm.py

@@ -0,0 +1,84 @@
+"""
+Thin wrapper around litellm so the rest of the library never talks to
+litellm directly. Swapping the underlying call layer later only means
+touching this one file.
+"""
+from __future__ import annotations
+
+import typing as t
+
+import litellm
+
+
+class LLMResponse(t.NamedTuple):
+    content: t.Optional[str]
+    tool_calls: list  # list of litellm/OpenAI-style tool call objects
+    raw: t.Any
+    finish_reason: t.Optional[str]
+
+
+class LLMClient:
+    def __init__(
+        self,
+        model: str,
+        api_key: t.Optional[str] = None,
+        api_base: t.Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: t.Optional[int] = None,
+        extra_params: t.Optional[dict] = None,
+    ):
+        self.model = model
+        self.api_key = api_key
+        self.api_base = api_base
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.extra_params = extra_params or {}
+
+    def _base_kwargs(self, messages: list, tools: t.Optional[list], stream: bool) -> dict:
+        kwargs: dict = dict(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            stream=stream,
+            **self.extra_params,
+        )
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        if self.api_base:
+            kwargs["api_base"] = self.api_base
+        if self.max_tokens:
+            kwargs["max_tokens"] = self.max_tokens
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+        return kwargs
+
+    @staticmethod
+    def _parse(response) -> LLMResponse:
+        choice = response.choices[0]
+        message = choice.message
+        return LLMResponse(
+            content=message.content,
+            tool_calls=message.tool_calls or [],
+            raw=response,
+            finish_reason=choice.finish_reason,
+        )
+
+    def complete(self, messages: list, tools: t.Optional[list] = None) -> LLMResponse:
+        kwargs = self._base_kwargs(messages, tools, stream=False)
+        response = litellm.completion(**kwargs)
+        return self._parse(response)
+
+    async def acomplete(self, messages: list, tools: t.Optional[list] = None) -> LLMResponse:
+        kwargs = self._base_kwargs(messages, tools, stream=False)
+        response = await litellm.acompletion(**kwargs)
+        return self._parse(response)
+
+    async def astream(self, messages: list, tools: t.Optional[list] = None):
+        """Yields raw chunk deltas (str) as they arrive."""
+        kwargs = self._base_kwargs(messages, tools, stream=True)
+        response = await litellm.acompletion(**kwargs)
+        async for chunk in response:
+            delta = chunk.choices[0].delta
+            if delta and delta.content:
+                yield delta.content

agentropic-0.1.0/src/agentropic/mcp/__init__.py

@@ -0,0 +1,3 @@
+from .client import MCPConnection, StdioServer, SSEServer, MCPServerConfig
+
+__all__ = ["MCPConnection", "StdioServer", "SSEServer", "MCPServerConfig"]

agentropic-0.1.0/src/agentropic/mcp/client.py

@@ -0,0 +1,103 @@
+"""
+MCP integration. Wraps the official `mcp` python SDK so that any tool
+exposed by an MCP server (stdio or SSE/HTTP) shows up as a normal
+agentum Tool, callable exactly like a local @tool function.
+"""
+from __future__ import annotations
+
+import typing as t
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+
+from ..tools import Tool  # populated by package __init__ patch below (see note)
+
+
+@dataclass
+class StdioServer:
+    """Launch a local MCP server as a subprocess, e.g. `npx some-mcp-server`."""
+
+    command: str
+    args: list[str] = None  # type: ignore[assignment]
+    env: t.Optional[dict] = None
+    name: str = "stdio-server"
+
+    def __post_init__(self):
+        self.args = self.args or []
+
+
+@dataclass
+class SSEServer:
+    """Connect to a remote MCP server over SSE/HTTP."""
+
+    url: str
+    headers: t.Optional[dict] = None
+    name: str = "sse-server"
+
+
+MCPServerConfig = t.Union[StdioServer, SSEServer]
+
+
+class MCPConnection:
+    """
+    One live connection to one MCP server. Use as an async context manager:
+
+        async with MCPConnection(StdioServer("npx", ["-y", "some-mcp"])) as conn:
+            tools = await conn.list_tools()
+    """
+
+    def __init__(self, config: MCPServerConfig):
+        self.config = config
+        self._stack = AsyncExitStack()
+        self._session = None
+
+    async def __aenter__(self) -> "MCPConnection":
+        # Imported lazily so `agentum` works even if the optional `mcp`
+        # package isn't installed unless MCP features are actually used.
+        from mcp import ClientSession
+        from mcp.client.stdio import stdio_client, StdioServerParameters
+
+        if isinstance(self.config, StdioServer):
+            params = StdioServerParameters(
+                command=self.config.command, args=self.config.args, env=self.config.env
+            )
+            read, write = await self._stack.enter_async_context(stdio_client(params))
+        else:
+            from mcp.client.sse import sse_client
+
+            read, write = await self._stack.enter_async_context(
+                sse_client(self.config.url, headers=self.config.headers)
+            )
+
+        self._session = await self._stack.enter_async_context(ClientSession(read, write))
+        await self._session.initialize()
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self._stack.aclose()
+
+    async def list_tools(self) -> list[Tool]:
+        result = await self._session.list_tools()
+        tools = []
+        for mcp_tool in result.tools:
+            tools.append(self._to_agentum_tool(mcp_tool))
+        return tools
+
+    def _to_agentum_tool(self, mcp_tool) -> Tool:
+        async def _call(**kwargs):
+            res = await self._session.call_tool(mcp_tool.name, arguments=kwargs)
+            # MCP returns a list of content blocks; flatten text blocks.
+            parts = []
+            for block in res.content:
+                text = getattr(block, "text", None)
+                parts.append(text if text is not None else str(block))
+            return "\n".join(parts)
+
+        return Tool(
+            name=mcp_tool.name,
+            description=mcp_tool.description or f"MCP tool {mcp_tool.name}",
+            parameters=mcp_tool.inputSchema or {"type": "object", "properties": {}},
+            func=None,  # not used; calls are routed through _mcp_call
+            is_async=True,
+            source="mcp",
+            _mcp_call=_call,
+        )

agentropic-0.1.0/src/agentropic/memory.py

@@ -0,0 +1,23 @@
+"""Minimal conversation memory. Swap out with your own by implementing
+the same three methods (add, get, clear) if you need persistence."""
+from __future__ import annotations
+
+import typing as t
+
+
+class Memory:
+    def __init__(self, max_messages: t.Optional[int] = None):
+        self._messages: list[dict] = []
+        self.max_messages = max_messages
+
+    def add(self, role: str, content: t.Any, **extra) -> None:
+        msg = {"role": role, "content": content, **extra}
+        self._messages.append(msg)
+        if self.max_messages and len(self._messages) > self.max_messages:
+            self._messages = self._messages[-self.max_messages :]
+
+    def get(self) -> list[dict]:
+        return list(self._messages)
+
+    def clear(self) -> None:
+        self._messages.clear()

agentropic-0.1.0/src/agentropic/tools.py

@@ -0,0 +1,192 @@
+"""
+Tool system: turns plain python functions into LLM-callable tools with
+auto-generated JSON-schema, via a simple @tool decorator.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import typing as t
+from dataclasses import dataclass, field
+
+try:
+    from pydantic import BaseModel
+except ImportError:  # pydantic is a hard dependency, but keep this defensive
+    BaseModel = None  # type: ignore
+
+
+_PY_TO_JSON_TYPE = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+    type(None): "null",
+}
+
+
+def _annotation_to_schema(annotation: t.Any) -> dict:
+    """Best-effort conversion of a python type hint to a JSON schema fragment."""
+    if annotation is inspect._empty:
+        return {"type": "string"}
+
+    origin = t.get_origin(annotation)
+
+    # Optional[X] / Union[X, None]
+    if origin is t.Union:
+        args = [a for a in t.get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return _annotation_to_schema(args[0])
+        return {"anyOf": [_annotation_to_schema(a) for a in args]}
+
+    # list[X] / List[X]
+    if origin in (list, t.List):
+        args = t.get_args(annotation)
+        item_schema = _annotation_to_schema(args[0]) if args else {"type": "string"}
+        return {"type": "array", "items": item_schema}
+
+    # Literal["a", "b"]
+    if origin is t.Literal:
+        values = list(t.get_args(annotation))
+        py_type = type(values[0]) if values else str
+        schema = {"type": _PY_TO_JSON_TYPE.get(py_type, "string")}
+        schema["enum"] = values
+        return schema
+
+    # Pydantic model as a parameter -> nested object schema
+    if BaseModel is not None and inspect.isclass(annotation) and issubclass(annotation, BaseModel):
+        return annotation.model_json_schema()
+
+    if annotation in _PY_TO_JSON_TYPE:
+        return {"type": _PY_TO_JSON_TYPE[annotation]}
+
+    # Fallback: treat as string so the LLM always has *something* to work with
+    return {"type": "string"}
+
+
+def _build_parameters_schema(func: t.Callable) -> dict:
+    sig = inspect.signature(func)
+    hints = t.get_type_hints(func)
+    properties: dict = {}
+    required: list[str] = []
+
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+        annotation = hints.get(name, param.annotation)
+        schema = _annotation_to_schema(annotation)
+        if param.default is inspect._empty:
+            required.append(name)
+        properties[name] = schema
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+
+
+@dataclass
+class Tool:
+    """A callable tool exposed to the agent/LLM."""
+
+    name: str
+    description: str
+    parameters: dict
+    func: t.Callable
+    is_async: bool = False
+    # Set for tools that come from an MCP server rather than local python.
+    source: str = "local"
+    _mcp_call: t.Optional[t.Callable[..., t.Awaitable]] = field(default=None, repr=False)
+
+    def to_openai_schema(self) -> dict:
+        """The format litellm/OpenAI-style function calling expects."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    async def acall(self, **kwargs) -> t.Any:
+        if self._mcp_call is not None:
+            return await self._mcp_call(**kwargs)
+        if self.is_async:
+            return await self.func(**kwargs)
+        return await asyncio.to_thread(self.func, **kwargs)
+
+    def call(self, **kwargs) -> t.Any:
+        if self.is_async or self._mcp_call is not None:
+            return asyncio.run(self.acall(**kwargs))
+        return self.func(**kwargs)
+
+
+def tool(name: t.Optional[str] = None, description: t.Optional[str] = None):
+    """
+    Decorator that turns a function into a Tool.
+
+        @tool()
+        def get_weather(city: str) -> str:
+            '''Get the current weather for a city.'''
+            ...
+
+    Decorated functions keep working as normal python functions; the Tool
+    metadata is attached as `func._tool`.
+    """
+
+    def decorator(func: t.Callable) -> t.Callable:
+        tool_name = name or func.__name__
+        doc = (description or inspect.getdoc(func) or "").strip()
+        params_schema = _build_parameters_schema(func)
+        is_async = inspect.iscoroutinefunction(func)
+
+        built = Tool(
+            name=tool_name,
+            description=doc or f"Tool named {tool_name}",
+            parameters=params_schema,
+            func=func,
+            is_async=is_async,
+        )
+        func._tool = built  # type: ignore[attr-defined]
+        return func
+
+    return decorator
+
+
+class ToolRegistry:
+    """Holds every tool an agent can use, local or MCP-sourced."""
+
+    def __init__(self, tools: t.Optional[list] = None):
+        self._tools: dict[str, Tool] = {}
+        for item in tools or []:
+            self.add(item)
+
+    def add(self, item: t.Union[Tool, t.Callable]) -> Tool:
+        resolved = item._tool if hasattr(item, "_tool") else item
+        if not isinstance(resolved, Tool):
+            raise TypeError(
+                "add() expects a Tool, or a function decorated with @tool()"
+            )
+        self._tools[resolved.name] = resolved
+        return resolved
+
+    def remove(self, name: str) -> None:
+        self._tools.pop(name, None)
+
+    def get(self, name: str) -> t.Optional[Tool]:
+        return self._tools.get(name)
+
+    def list(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def to_openai_tools(self) -> list[dict]:
+        return [tl.to_openai_schema() for tl in self._tools.values()]
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools

agentropic-0.1.0/tests/test_agent.py

@@ -0,0 +1,40 @@
+import pytest
+
+from agentropic.tools import tool, ToolRegistry, Tool
+
+
+def test_tool_decorator_builds_schema():
+    @tool()
+    def greet(name: str, excited: bool = False) -> str:
+        """Say hello to someone."""
+        return f"Hello {name}!" + ("!!!" if excited else "")
+
+    built: Tool = greet._tool
+    assert built.name == "greet"
+    assert "name" in built.parameters["properties"]
+    assert "name" in built.parameters["required"]
+    assert "excited" not in built.parameters["required"]
+    assert built.call(name="Ada") == "Hello Ada!"
+
+
+def test_registry_openai_schema():
+    @tool()
+    def noop() -> str:
+        """Does nothing."""
+        return "ok"
+
+    registry = ToolRegistry([noop])
+    schema = registry.to_openai_tools()
+    assert schema[0]["function"]["name"] == "noop"
+    assert registry.get("noop") is not None
+
+
+@pytest.mark.asyncio
+async def test_async_tool_call():
+    @tool()
+    async def slow_add(a: int, b: int) -> int:
+        """Add two numbers asynchronously."""
+        return a + b
+
+    result = await slow_add._tool.acall(a=2, b=3)
+    assert result == 5