agentinc-sdk 0.2.0__py3-none-any.whl

agentinc/sdk/__init__.py

@@ -0,0 +1,39 @@
+from .agent import Agent
+from .protocol import AgentFactory, AgentProtocol, ToolProtocol
+from .raw import RawAdapter
+from .schemas import (
+    AgentInput,
+    AgentOutput,
+    DataConfig,
+    MCPConfig,
+    MemoryConfig,
+    Message,
+    ModelConfig,
+    ToolCall,
+    ToolSchema,
+)
+from .tool import ToolWrapper, tool
+
+__all__ = [
+    # Core
+    "Agent",
+    "AgentProtocol",
+    "ToolProtocol",
+    "AgentFactory",
+    # Schemas
+    "AgentInput",
+    "AgentOutput",
+    "Message",
+    "ToolCall",
+    "ToolSchema",
+    # Config
+    "ModelConfig",
+    "MemoryConfig",
+    "MCPConfig",
+    "DataConfig",
+    # Tools
+    "ToolWrapper",
+    "tool",
+    # Deprecated
+    "RawAdapter",
+]

agentinc/sdk/agent.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Callable
+from typing import Any, AsyncIterator
+
+from .memory import memory_for
+from .memory.base import Memory
+from .providers import provider_for
+from .providers.base import Provider
+from .schemas import (
+    AgentInput,
+    AgentOutput,
+    DataConfig,
+    MCPConfig,
+    MemoryConfig,
+    Message,
+    ModelConfig,
+    ToolCall,
+    ToolSchema,
+)
+from .tool import ToolWrapper, _build_schema
+
+log = logging.getLogger("agentinc.sdk.agent")
+
+
+def _wrap_tool(fn: Callable) -> ToolWrapper:
+    if isinstance(fn, ToolWrapper):
+        return fn
+    schema = _build_schema(fn, name=fn.__name__, description=fn.__doc__ or "")
+    return ToolWrapper(fn=fn, schema=schema)
+
+
+class Agent:
+    """
+    High-level agent that wires together a provider, tools, MCP servers,
+    Redis memory, and optional context into a single AgentProtocol-compatible object.
+
+    Usage::
+
+        agent = Agent(
+            role="You are a helpful assistant.",
+            model={"model": "gpt-4o-mini", "api_key": "sk-…"},
+            tools=[my_function],
+            memory={"type": "redis", "connection": "redis://localhost:6379"},
+        )
+        serve(agent, name="my-agent", port=8000)
+    """
+
+    def __init__(
+        self,
+        role: str,
+        model: ModelConfig,
+        tools: list[Callable] | None = None,
+        mcps: list[MCPConfig] | None = None,
+        memory: MemoryConfig | None = None,
+        context: str | None = None,
+        data: DataConfig | None = None,
+    ) -> None:
+        self._role = role
+        self._context = context
+        self._model_config = model
+
+        self._provider: Provider = provider_for(model)
+        self._memory: Memory | None = memory_for(memory) if memory else None
+        self._mcp_configs: list[MCPConfig] = mcps or []
+
+        # Wrap plain functions as ToolWrapper instances
+        self._local_tools: dict[str, ToolWrapper] = {
+            w.schema().name: w for w in (_wrap_tool(t) for t in (tools or []))
+        }
+
+        # MCP tool registry — populated on first run()
+        self._mcp_tools: dict[str, Any] = {}
+        self._mcp_ready = False
+
+        if data is not None:
+            log.debug("data= parameter accepted but not yet implemented (reserved for RAG)")
+
+    # ------------------------------------------------------------------
+    # AgentProtocol
+    # ------------------------------------------------------------------
+
+    async def run(self, input: AgentInput) -> AsyncIterator[AgentOutput]:
+        if self._mcp_configs and not self._mcp_ready:
+            await self._init_mcp()
+
+        session_id = input.metadata.get("session_id") or str(uuid.uuid4())
+
+        # Load history from memory backend (empty list if no memory configured)
+        persisted: list[Message] = []
+        if self._memory:
+            persisted = await self._memory.load(session_id)
+
+        # Merge caller-supplied history (takes precedence) with persisted history
+        history = persisted if not input.history else list(input.history)
+
+        # Build system prompt
+        system_parts = [self._role]
+        if self._context:
+            system_parts.append(self._context)
+
+        messages: list[dict] = [{"role": "system", "content": "\n\n".join(system_parts)}]
+        for msg in history:
+            messages.append(self._message_to_dict(msg))
+        messages.append({"role": "user", "content": input.message})
+
+        # Collect all tool schemas
+        tool_schemas = [w.schema() for w in self._local_tools.values()]
+        tool_schemas += [
+            ToolSchema(name=name, description=spec["description"], parameters=spec["parameters"])
+            for name, spec in self._mcp_tools.items()
+        ]
+
+        # Agentic loop
+        new_messages: list[dict] = []
+        while True:
+            tool_calls_batch: list[ToolCall] = []
+
+            async for chunk in self._provider.complete(messages + new_messages, tool_schemas):
+                if chunk.tool_calls:
+                    tool_calls_batch.extend(chunk.tool_calls)
+                elif chunk.content:
+                    yield chunk
+                if chunk.done:
+                    break
+
+            if not tool_calls_batch:
+                yield AgentOutput(content="", done=True)
+                break
+
+            # Append assistant tool-call turn
+            new_messages.append({
+                "role": "assistant",
+                "tool_calls": [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {"name": tc.name, "arguments": str(tc.arguments)},
+                    }
+                    for tc in tool_calls_batch
+                ],
+            })
+
+            # Dispatch all tool calls and append results
+            for tc in tool_calls_batch:
+                result = await self._dispatch_tool(tc)
+                new_messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": result,
+                })
+
+        # Persist updated history
+        if self._memory:
+            updated = list(history) + [
+                Message(role="user", content=input.message),
+                *[
+                    Message(role=m["role"], content=m.get("content", ""))
+                    for m in new_messages
+                    if m["role"] in ("assistant", "tool") and m.get("content")
+                ],
+            ]
+            await self._memory.save(session_id, updated)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _dispatch_tool(self, tc: ToolCall) -> str:
+        if tc.name in self._local_tools:
+            return await self._local_tools[tc.name].call(tc)
+        if tc.name in self._mcp_tools:
+            return await self._call_mcp_tool(tc)
+        return f"Error: tool '{tc.name}' not found"
+
+    async def _init_mcp(self) -> None:
+        for config in self._mcp_configs:
+            try:
+                tools = await _fetch_mcp_tools(config)
+                self._mcp_tools.update(tools)
+            except Exception:
+                log.exception("Failed to initialise MCP server: %s", config)
+        self._mcp_ready = True
+
+    async def _call_mcp_tool(self, tc: ToolCall) -> str:
+        spec = self._mcp_tools.get(tc.name)
+        if spec is None:
+            return f"Error: MCP tool '{tc.name}' not found"
+        try:
+            result = await _invoke_mcp_tool(spec["config"], tc.name, tc.arguments)
+            return result
+        except Exception as exc:
+            return f"Error calling MCP tool '{tc.name}': {exc}"
+
+    @staticmethod
+    def _message_to_dict(msg: Message) -> dict:
+        d: dict = {"role": msg.role, "content": msg.content or ""}
+        if msg.tool_calls:
+            d["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {"name": tc.name, "arguments": str(tc.arguments)},
+                }
+                for tc in msg.tool_calls
+            ]
+        if msg.tool_call_id:
+            d["tool_call_id"] = msg.tool_call_id
+        return d
+
+
+# ------------------------------------------------------------------
+# MCP helpers (lazy-import mcp package)
+# ------------------------------------------------------------------
+
+async def _fetch_mcp_tools(config: MCPConfig) -> dict[str, dict]:
+    """Connect to an MCP server and return its tool schemas."""
+    try:
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+        from mcp.client.sse import sse_client
+    except ImportError:
+        raise ImportError(
+            "MCP support requires the mcp extra: pip install 'agentinc-sdk[mcp]'"
+        )
+
+    tools: dict[str, dict] = {}
+
+    if config["type"] == "stdio":
+        server_params = StdioServerParameters(
+            command=config["command"],
+            args=config.get("args", []),
+        )
+        async with stdio_client(server_params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.list_tools()
+                for tool in result.tools:
+                    tools[tool.name] = {
+                        "description": tool.description or "",
+                        "parameters": tool.inputSchema or {"type": "object", "properties": {}},
+                        "config": config,
+                    }
+
+    elif config["type"] == "sse":
+        async with sse_client(config["url"]) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.list_tools()
+                for tool in result.tools:
+                    tools[tool.name] = {
+                        "description": tool.description or "",
+                        "parameters": tool.inputSchema or {"type": "object", "properties": {}},
+                        "config": config,
+                    }
+
+    return tools
+
+
+async def _invoke_mcp_tool(config: MCPConfig, name: str, arguments: dict) -> str:
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    from mcp.client.sse import sse_client
+
+    if config["type"] == "stdio":
+        server_params = StdioServerParameters(
+            command=config["command"],
+            args=config.get("args", []),
+        )
+        async with stdio_client(server_params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(name, arguments)
+                return str(result.content)
+
+    elif config["type"] == "sse":
+        async with sse_client(config["url"]) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(name, arguments)
+                return str(result.content)
+
+    return "Error: unsupported MCP transport"

agentinc/sdk/memory/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ..schemas import MemoryConfig
+from .base import Memory
+
+
+def memory_for(config: MemoryConfig) -> Memory:
+    if config["type"] == "redis":
+        from .redis import RedisMemory
+        return RedisMemory(config)
+    raise ValueError(f"Unsupported memory type: {config['type']!r}")
+
+
+__all__ = ["Memory", "memory_for"]

agentinc/sdk/memory/base.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..schemas import Message
+
+
+@runtime_checkable
+class Memory(Protocol):
+    async def load(self, session_id: str) -> list[Message]: ...
+    async def save(self, session_id: str, history: list[Message]) -> None: ...
+    async def clear(self, session_id: str) -> None: ...

agentinc/sdk/memory/redis.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+import logging
+
+from ..schemas import MemoryConfig, Message
+
+log = logging.getLogger("agentinc.sdk.memory.redis")
+
+_TTL = 86400  # 24 hours
+_KEY_PREFIX = "agentinc:session"
+
+
+class RedisMemory:
+    def __init__(self, config: MemoryConfig) -> None:
+        try:
+            import redis.asyncio as aioredis
+        except ImportError:
+            raise ImportError(
+                "Redis memory requires the memory extra: "
+                "pip install 'agentinc-sdk[memory]'"
+            )
+        self._redis = aioredis.from_url(
+            config["connection"],
+            username=config.get("user"),
+            password=config.get("password"),
+            decode_responses=True,
+        )
+
+    def _key(self, session_id: str) -> str:
+        return f"{_KEY_PREFIX}:{session_id}:history"
+
+    async def load(self, session_id: str) -> list[Message]:
+        raw = await self._redis.get(self._key(session_id))
+        if not raw:
+            return []
+        try:
+            return [Message(**m) for m in json.loads(raw)]
+        except Exception:
+            log.warning("Failed to deserialise history for session %s", session_id)
+            return []
+
+    async def save(self, session_id: str, history: list[Message]) -> None:
+        payload = json.dumps([m.model_dump() for m in history])
+        await self._redis.set(self._key(session_id), payload, ex=_TTL)
+
+    async def clear(self, session_id: str) -> None:
+        await self._redis.delete(self._key(session_id))

agentinc/sdk/protocol.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Protocol, runtime_checkable
+
+from .schemas import AgentInput, AgentOutput, ToolCall, ToolSchema
+
+
+@runtime_checkable
+class ToolProtocol(Protocol):
+    def schema(self) -> ToolSchema: ...
+    async def call(self, tool_call: ToolCall) -> str: ...
+
+
+@runtime_checkable
+class AgentProtocol(Protocol):
+    def run(self, input: AgentInput) -> AsyncIterator[AgentOutput]: ...
+
+
+AgentFactory = Any

agentinc/sdk/providers/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from ..schemas import ModelConfig
+from .base import Provider
+
+
+def provider_for(config: ModelConfig) -> Provider:
+    """Return the correct Provider instance based on model name or base_url."""
+    model = config["model"]
+    base_url = config.get("base_url")
+
+    if base_url:
+        from .openai import OpenAIProvider
+        return OpenAIProvider(config)
+
+    if model.startswith("claude"):
+        from .anthropic import AnthropicProvider
+        return AnthropicProvider(config)
+
+    if model.startswith("gemini"):
+        from .gemini import GeminiProvider
+        return GeminiProvider(config)
+
+    # Default: OpenAI (covers gpt-*, o1-*, o3-*, etc.)
+    from .openai import OpenAIProvider
+    return OpenAIProvider(config)
+
+
+__all__ = ["Provider", "provider_for"]

agentinc/sdk/providers/anthropic.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import logging
+from typing import AsyncIterator
+
+from ..schemas import AgentOutput, ModelConfig, ToolCall, ToolSchema
+
+log = logging.getLogger("agentinc.sdk.providers.anthropic")
+
+_SYSTEM_KEY = "__system__"
+
+
+def _strip_system(messages: list[dict]) -> tuple[str, list[dict]]:
+    """Pull the system message out; Anthropic takes it as a separate param."""
+    system = ""
+    rest = []
+    for m in messages:
+        if m["role"] == "system":
+            system = m.get("content", "")
+        else:
+            rest.append(m)
+    return system, rest
+
+
+class AnthropicProvider:
+    def __init__(self, config: ModelConfig) -> None:
+        try:
+            import anthropic as _anthropic
+            self._anthropic = _anthropic
+        except ImportError:
+            raise ImportError(
+                "Anthropic provider requires the anthropic extra: "
+                "pip install 'agentinc-sdk[anthropic]'"
+            )
+        self._client = self._anthropic.AsyncAnthropic(api_key=config["api_key"])
+        self._model = config["model"]
+
+    async def complete(
+        self,
+        messages: list[dict],
+        tools: list[ToolSchema],
+        stream: bool = True,
+    ) -> AsyncIterator[AgentOutput]:
+        system, msgs = _strip_system(messages)
+
+        anthropic_tools = (
+            [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "input_schema": t.parameters,
+                }
+                for t in tools
+            ]
+            if tools
+            else []
+        )
+
+        kwargs: dict = dict(
+            model=self._model,
+            max_tokens=4096,
+            messages=msgs,
+        )
+        if system:
+            kwargs["system"] = system
+        if anthropic_tools:
+            kwargs["tools"] = anthropic_tools
+
+        if stream:
+            async for chunk in self._stream(kwargs):
+                yield chunk
+        else:
+            async for chunk in self._blocking(kwargs):
+                yield chunk
+
+    async def _stream(self, kwargs: dict) -> AsyncIterator[AgentOutput]:
+        async with self._client.messages.stream(**kwargs) as stream:
+            async for text in stream.text_stream:
+                yield AgentOutput(content=text, done=False)
+
+            msg = await stream.get_final_message()
+
+        if msg.stop_reason == "tool_use":
+            tool_calls = []
+            for block in msg.content:
+                if block.type == "tool_use":
+                    tool_calls.append(
+                        ToolCall(id=block.id, name=block.name, arguments=block.input or {})
+                    )
+            yield AgentOutput(tool_calls=tool_calls, done=False)
+        else:
+            yield AgentOutput(content="", done=True)
+
+    async def _blocking(self, kwargs: dict) -> AsyncIterator[AgentOutput]:
+        msg = await self._client.messages.create(**kwargs)
+
+        if msg.stop_reason == "tool_use":
+            tool_calls = []
+            for block in msg.content:
+                if block.type == "tool_use":
+                    tool_calls.append(
+                        ToolCall(id=block.id, name=block.name, arguments=block.input or {})
+                    )
+            yield AgentOutput(tool_calls=tool_calls, done=False)
+        else:
+            text = "".join(b.text for b in msg.content if hasattr(b, "text"))
+            yield AgentOutput(content=text, done=True)

agentinc/sdk/providers/base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import AsyncIterator, Protocol, runtime_checkable
+
+from ..schemas import AgentOutput, ToolSchema
+
+
+@runtime_checkable
+class Provider(Protocol):
+    async def complete(
+        self,
+        messages: list[dict],
+        tools: list[ToolSchema],
+        stream: bool = True,
+    ) -> AsyncIterator[AgentOutput]: ...

agentinc/sdk/providers/gemini.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import logging
+from typing import AsyncIterator
+
+from ..schemas import AgentOutput, ModelConfig, ToolCall, ToolSchema
+
+log = logging.getLogger("agentinc.sdk.providers.gemini")
+
+
+def _to_gemini_messages(messages: list[dict]) -> tuple[str, list[dict]]:
+    """Convert OpenAI-style messages to Gemini contents + system instruction."""
+    system = ""
+    contents = []
+    for m in messages:
+        role = m["role"]
+        content = m.get("content", "")
+        if role == "system":
+            system = content
+        elif role == "assistant":
+            contents.append({"role": "model", "parts": [{"text": content}]})
+        elif role == "tool":
+            contents.append({
+                "role": "user",
+                "parts": [{"function_response": {
+                    "name": m.get("name", ""),
+                    "response": {"result": content},
+                }}],
+            })
+        else:
+            contents.append({"role": "user", "parts": [{"text": content}]})
+    return system, contents
+
+
+class GeminiProvider:
+    def __init__(self, config: ModelConfig) -> None:
+        try:
+            from google import genai
+            from google.genai import types as genai_types
+            self._genai = genai
+            self._types = genai_types
+        except ImportError:
+            raise ImportError(
+                "Gemini provider requires the gemini extra: "
+                "pip install 'agentinc-sdk[gemini]'"
+            )
+        self._client = genai.Client(api_key=config["api_key"])
+        self._model = config["model"]
+
+    async def complete(
+        self,
+        messages: list[dict],
+        tools: list[ToolSchema],
+        stream: bool = True,
+    ) -> AsyncIterator[AgentOutput]:
+        system, contents = _to_gemini_messages(messages)
+
+        gemini_tools = None
+        if tools:
+            function_declarations = [
+                self._types.FunctionDeclaration(
+                    name=t.name,
+                    description=t.description,
+                    parameters=t.parameters,
+                )
+                for t in tools
+            ]
+            gemini_tools = [self._types.Tool(function_declarations=function_declarations)]
+
+        config_kwargs: dict = {}
+        if system:
+            config_kwargs["system_instruction"] = system
+        if gemini_tools:
+            config_kwargs["tools"] = gemini_tools
+
+        gen_config = self._types.GenerateContentConfig(**config_kwargs) if config_kwargs else None
+
+        if stream:
+            async for chunk in self._stream(contents, gen_config):
+                yield chunk
+        else:
+            async for chunk in self._blocking(contents, gen_config):
+                yield chunk
+
+    async def _stream(self, contents, gen_config) -> AsyncIterator[AgentOutput]:
+        kwargs = {"model": self._model, "contents": contents}
+        if gen_config:
+            kwargs["config"] = gen_config
+
+        async for chunk in await self._client.aio.models.generate_content_stream(**kwargs):
+            if chunk.function_calls:
+                tool_calls = [
+                    ToolCall(id=fc.id or fc.name, name=fc.name, arguments=dict(fc.args or {}))
+                    for fc in chunk.function_calls
+                ]
+                yield AgentOutput(tool_calls=tool_calls, done=False)
+                return
+            if chunk.text:
+                yield AgentOutput(content=chunk.text, done=False)
+
+        yield AgentOutput(content="", done=True)
+
+    async def _blocking(self, contents, gen_config) -> AsyncIterator[AgentOutput]:
+        kwargs = {"model": self._model, "contents": contents}
+        if gen_config:
+            kwargs["config"] = gen_config
+
+        response = await self._client.aio.models.generate_content(**kwargs)
+
+        if response.function_calls:
+            tool_calls = [
+                ToolCall(id=fc.id or fc.name, name=fc.name, arguments=dict(fc.args or {}))
+                for fc in response.function_calls
+            ]
+            yield AgentOutput(tool_calls=tool_calls, done=False)
+        else:
+            yield AgentOutput(content=response.text or "", done=True)