openagent-framework 0.1.1__py3-none-any.whl

openagent/__init__.py

@@ -0,0 +1,5 @@
+from openagent.agent import Agent
+from openagent.config import load_config
+
+__version__ = "0.1.1"
+__all__ = ["Agent", "load_config"]

openagent/agent.py

@@ -0,0 +1,262 @@
+"""Core Agent class: orchestrates model, MCP tools, and memory."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator
+
+from openagent.models.base import BaseModel, ModelResponse
+from openagent.memory.db import MemoryDB
+from openagent.memory.manager import MemoryManager
+from openagent.mcp.client import MCPRegistry, MCPTools
+
+logger = logging.getLogger(__name__)
+
+MAX_TOOL_ITERATIONS = 10
+
+
+class Agent:
+    """Main agent class. Ties together a model, MCP tools, and memory.
+
+    Usage:
+        agent = Agent(
+            name="assistant",
+            model=ClaudeAPI(model="claude-sonnet-4-6"),
+            system_prompt="You are a helpful assistant.",
+            mcp_tools=[MCPTools(command=["npx", "..."])],
+            memory=MemoryDB("agent.db"),
+        )
+        response = await agent.run("Hello!", user_id="user-1")
+    """
+
+    def __init__(
+        self,
+        name: str = "agent",
+        model: BaseModel | None = None,
+        system_prompt: str = "You are a helpful assistant.",
+        mcp_tools: list[MCPTools] | None = None,
+        mcp_registry: MCPRegistry | None = None,
+        memory: MemoryDB | str | None = None,
+        auto_extract_memory: bool = True,
+        history_limit: int = 50,
+        knowledge_dir: str = "./memories",
+    ):
+        self.name = name
+        self.model = model
+        self.system_prompt = system_prompt
+        self.auto_extract_memory = auto_extract_memory
+
+        # MCP
+        if mcp_registry:
+            self._mcp = mcp_registry
+        else:
+            self._mcp = MCPRegistry()
+            for tool in (mcp_tools or []):
+                self._mcp.add(tool)
+
+        # Memory
+        if isinstance(memory, str):
+            self._db = MemoryDB(memory)
+        elif isinstance(memory, MemoryDB):
+            self._db = memory
+        else:
+            self._db = None
+
+        self._memory: MemoryManager | None = None
+        if self._db:
+            self._memory = MemoryManager(
+                self._db, auto_extract=auto_extract_memory,
+                history_limit=history_limit, knowledge_dir=knowledge_dir,
+            )
+
+        self._initialized = False
+
+    async def initialize(self) -> None:
+        """Connect MCP servers and initialize memory DB."""
+        if self._initialized:
+            return
+        await self._mcp.connect_all()
+        if self._db:
+            await self._db.connect()
+        if self._memory:
+            await self._memory.initialize_knowledge()
+
+        # For Claude CLI: pass MCP server configs so CLI can use them
+        from openagent.models.claude_cli import ClaudeCLI
+        if isinstance(self.model, ClaudeCLI):
+            mcp_configs = self._build_cli_mcp_configs()
+            if mcp_configs:
+                self.model.set_mcp_servers(mcp_configs)
+
+        self._initialized = True
+
+    def _build_cli_mcp_configs(self) -> dict[str, dict]:
+        """Build MCP server configs in Claude CLI format for --mcp-config."""
+        configs = {}
+        for server in self._mcp._servers:
+            if server.command:
+                full_cmd = server.command + server.args
+                configs[server.name] = {
+                    "command": full_cmd[0],
+                    "args": full_cmd[1:],
+                }
+                if server.env:
+                    configs[server.name]["env"] = server.env
+                if server._cwd:
+                    configs[server.name]["cwd"] = server._cwd
+        return configs
+
+    async def shutdown(self) -> None:
+        """Close all connections."""
+        await self._mcp.close_all()
+        if self._db:
+            await self._db.close()
+        self._initialized = False
+
+    async def run(
+        self,
+        message: str,
+        user_id: str = "",
+        session_id: str | None = None,
+        attachments: list[dict] | None = None,
+    ) -> str:
+        """Run the agent with a user message. Returns the final text response.
+
+        Handles the full tool-use loop: send -> tool call -> execute -> send result -> repeat.
+        """
+        if not self.model:
+            raise RuntimeError("No model configured. Set agent.model before calling run().")
+
+        await self.initialize()
+
+        # Session + history
+        current_session_id = None
+        history: list[dict[str, Any]] = []
+        system = self.system_prompt
+
+        if self._memory:
+            current_session_id = await self._memory.ensure_session(self.name, user_id, session_id)
+            history = await self._memory.get_history(current_session_id)
+
+            # Inject long-term memories + relevant knowledge into system prompt
+            mem_context = await self._memory.build_memory_context(self.name, user_id, query=message)
+            if mem_context:
+                system = f"{system}\n\n{mem_context}"
+
+        # Build messages — prepend attachment descriptions if present
+        if attachments:
+            att_desc = " ".join(f"[Attached {a.get('type','file')}: {a.get('filename','')}]" for a in attachments)
+            message = f"{att_desc}\n{message}" if message else att_desc
+
+        messages = list(history)
+        messages.append({"role": "user", "content": message})
+
+        # Store user message
+        if self._memory and current_session_id:
+            await self._memory.store_message(current_session_id, "user", message)
+
+        # Get available tools
+        tools = self._mcp.all_tools() or None
+
+        # Tool-use loop
+        for _ in range(MAX_TOOL_ITERATIONS):
+            response = await self.model.generate(messages, system=system, tools=tools)
+
+            if response.tool_calls:
+                # Add assistant message with tool calls
+                assistant_msg: dict[str, Any] = {
+                    "role": "assistant",
+                    "content": response.content,
+                    "tool_calls": [
+                        {"id": tc.id, "name": tc.name, "arguments": tc.arguments}
+                        for tc in response.tool_calls
+                    ],
+                }
+                messages.append(assistant_msg)
+                if self._memory and current_session_id:
+                    await self._memory.store_message(
+                        current_session_id, "assistant", response.content,
+                        tool_calls=assistant_msg["tool_calls"],
+                    )
+
+                # Execute each tool call
+                for tc in response.tool_calls:
+                    try:
+                        result = await self._mcp.call_tool(tc.name, tc.arguments)
+                    except Exception as e:
+                        result = f"Error calling tool {tc.name}: {e}"
+                        logger.error(result)
+
+                    tool_msg = {
+                        "role": "tool",
+                        "content": result,
+                        "tool_call_id": tc.id,
+                    }
+                    messages.append(tool_msg)
+                    if self._memory and current_session_id:
+                        await self._memory.store_message(
+                            current_session_id, "tool", result, tool_call_id=tc.id,
+                        )
+            else:
+                # No tool calls — we have the final response
+                if self._memory and current_session_id:
+                    await self._memory.store_message(current_session_id, "assistant", response.content)
+
+                # Extract memories in background
+                if self._memory and self.auto_extract_memory:
+                    try:
+                        await self._memory.extract_and_store_memories(
+                            self.model, self.name, user_id, messages,
+                        )
+                    except Exception as e:
+                        logger.warning(f"Memory extraction failed: {e}")
+
+                return response.content
+
+        # Exceeded max iterations
+        return response.content if response else "I wasn't able to complete the request."
+
+    async def stream_run(
+        self,
+        message: str,
+        user_id: str = "",
+        session_id: str | None = None,
+    ) -> AsyncIterator[str]:
+        """Stream the agent's response. Does not support tool use in streaming mode."""
+        if not self.model:
+            raise RuntimeError("No model configured.")
+
+        await self.initialize()
+
+        history: list[dict[str, Any]] = []
+        system = self.system_prompt
+        current_session_id = None
+
+        if self._memory:
+            current_session_id = await self._memory.ensure_session(self.name, user_id, session_id)
+            history = await self._memory.get_history(current_session_id)
+            mem_context = await self._memory.build_memory_context(self.name, user_id)
+            if mem_context:
+                system = f"{system}\n\n{mem_context}"
+
+        messages = list(history)
+        messages.append({"role": "user", "content": message})
+
+        if self._memory and current_session_id:
+            await self._memory.store_message(current_session_id, "user", message)
+
+        full_response = []
+        async for chunk in self.model.stream(messages, system=system):
+            full_response.append(chunk)
+            yield chunk
+
+        content = "".join(full_response)
+        if self._memory and current_session_id:
+            await self._memory.store_message(current_session_id, "assistant", content)
+
+    async def __aenter__(self):
+        await self.initialize()
+        return self
+
+    async def __aexit__(self, *args):
+        await self.shutdown()

openagent/channels/__init__.py

@@ -0,0 +1,3 @@
+from openagent.channels.base import BaseChannel
+
+__all__ = ["BaseChannel"]

openagent/channels/base.py

@@ -0,0 +1,91 @@
+"""Base channel interface and shared utilities."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openagent.agent import Agent
+
+
+@dataclass
+class Attachment:
+    """A file/image/voice attachment from or to a channel."""
+    type: str          # "image", "file", "voice", "video"
+    path: str          # local file path
+    filename: str
+    mime_type: str | None = None
+    caption: str | None = None
+
+
+# Pattern for response markers: [IMAGE:/path/to/file.png] [FILE:/path] [VOICE:/path]
+_MARKER_PATTERN = re.compile(r'\[(IMAGE|FILE|VOICE|VIDEO):([^\]]+)\]')
+
+_MARKER_TYPE_MAP = {
+    "IMAGE": "image",
+    "FILE": "file",
+    "VOICE": "voice",
+    "VIDEO": "video",
+}
+
+
+def parse_response_markers(text: str) -> tuple[str, list[Attachment]]:
+    """Extract file markers from agent response text.
+
+    Returns (clean_text, attachments).
+    Markers like [IMAGE:/path/to/chart.png] are removed from text
+    and returned as Attachment objects.
+    """
+    attachments: list[Attachment] = []
+    for match in _MARKER_PATTERN.finditer(text):
+        marker_type = match.group(1)
+        file_path = match.group(2).strip()
+        att_type = _MARKER_TYPE_MAP.get(marker_type, "file")
+        filename = Path(file_path).name
+        attachments.append(Attachment(
+            type=att_type,
+            path=file_path,
+            filename=filename,
+        ))
+
+    clean_text = _MARKER_PATTERN.sub("", text).strip()
+    return clean_text, attachments
+
+
+def format_attachments_for_prompt(attachments: list[Attachment], caption: str = "") -> str:
+    """Build a prompt string describing attachments for the agent."""
+    parts = []
+    for att in attachments:
+        parts.append(f"[Attached {att.type}: {att.filename}]")
+    prefix = " ".join(parts)
+    if caption:
+        return f"{prefix}\n{caption}"
+    return prefix
+
+
+class BaseChannel(ABC):
+    """Abstract base for messaging channels (Telegram, Discord, WhatsApp, etc.).
+
+    Each channel manages per-user sessions via the agent's memory system.
+    """
+
+    def __init__(self, agent: Agent):
+        self.agent = agent
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start listening for messages."""
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the channel."""
+        ...
+
+    def _user_session_id(self, platform: str, user_id: str) -> str:
+        """Generate a consistent session ID from platform + user ID."""
+        return f"{platform}:{self.agent.name}:{user_id}"

openagent/channels/discord.py

@@ -0,0 +1,136 @@
+"""Discord channel using discord.py. Supports text, images, files, attachments."""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openagent.channels.base import BaseChannel, Attachment, parse_response_markers
+
+if TYPE_CHECKING:
+    from openagent.agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class DiscordChannel(BaseChannel):
+    """Discord bot channel with full media support.
+
+    Usage:
+        channel = DiscordChannel(agent=agent, token="BOT_TOKEN")
+        await channel.start()
+    """
+
+    def __init__(self, agent: Agent, token: str):
+        super().__init__(agent)
+        self.token = token
+        self._client = None
+
+    async def start(self) -> None:
+        try:
+            import discord
+        except ImportError:
+            raise ImportError(
+                "discord.py is required for Discord channel. "
+                "Install it with: pip install openagent[discord]"
+            )
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+        client = discord.Client(intents=intents)
+        self._client = client
+
+        @client.event
+        async def on_ready():
+            logger.info(f"Discord bot '{self.agent.name}' connected as {client.user}")
+
+        @client.event
+        async def on_message(message: discord.Message):
+            if message.author == client.user:
+                return
+
+            is_dm = isinstance(message.channel, discord.DMChannel)
+            is_mentioned = client.user in message.mentions if client.user else False
+            if not is_dm and not is_mentioned:
+                return
+
+            content = message.content
+            if is_mentioned and client.user:
+                content = content.replace(f"<@{client.user.id}>", "").strip()
+
+            user_id = str(message.author.id)
+            session_id = self._user_session_id("discord", user_id)
+            attachments: list[dict] = []
+
+            # Download attachments
+            if message.attachments:
+                tmp_dir = tempfile.mkdtemp(prefix="openagent_dc_")
+                for att in message.attachments:
+                    try:
+                        path = str(Path(tmp_dir) / att.filename)
+                        await att.save(path)
+                        ct = att.content_type or ""
+                        if ct.startswith("image/"):
+                            att_type = "image"
+                        elif ct.startswith("audio/") or att.filename.endswith((".ogg", ".mp3", ".wav")):
+                            att_type = "voice"
+                        elif ct.startswith("video/"):
+                            att_type = "video"
+                        else:
+                            att_type = "file"
+                        attachments.append({"type": att_type, "path": path, "filename": att.filename})
+                    except Exception as e:
+                        logger.error(f"Failed to download Discord attachment: {e}")
+
+            if not content and not attachments:
+                return
+
+            try:
+                async with message.channel.typing():
+                    response = await self.agent.run(
+                        message=content,
+                        user_id=user_id,
+                        session_id=session_id,
+                        attachments=attachments if attachments else None,
+                    )
+
+                await self._send_response(message.channel, response)
+            except Exception as e:
+                logger.error(f"Discord handler error: {e}")
+                await message.channel.send("Sorry, something went wrong.")
+
+        logger.info(f"Starting Discord bot for agent '{self.agent.name}'")
+        await client.start(self.token)
+
+    async def _send_response(self, channel, response: str) -> None:
+        """Send agent response, handling file markers."""
+        import discord
+
+        clean_text, attachments = parse_response_markers(response)
+
+        # Send attachments
+        files = []
+        for att in attachments:
+            path = Path(att.path)
+            if path.exists():
+                files.append(discord.File(str(path), filename=att.filename))
+
+        if files:
+            # Discord allows up to 10 files per message
+            for i in range(0, len(files), 10):
+                batch = files[i:i + 10]
+                text_chunk = clean_text[:2000] if i == 0 and clean_text else None
+                await channel.send(content=text_chunk, files=batch)
+                if i == 0 and clean_text:
+                    clean_text = clean_text[2000:]
+
+        # Send remaining text
+        if clean_text:
+            for i in range(0, len(clean_text), 2000):
+                await channel.send(clean_text[i:i + 2000])
+
+    async def stop(self) -> None:
+        if self._client:
+            await self._client.close()

openagent/channels/telegram.py

@@ -0,0 +1,161 @@
+"""Telegram channel using python-telegram-bot. Supports text, images, files, voice."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openagent.channels.base import BaseChannel, Attachment, parse_response_markers
+
+if TYPE_CHECKING:
+    from openagent.agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class TelegramChannel(BaseChannel):
+    """Telegram bot channel with full media support.
+
+    Usage:
+        channel = TelegramChannel(agent=agent, token="BOT_TOKEN")
+        await channel.start()
+    """
+
+    def __init__(self, agent: Agent, token: str):
+        super().__init__(agent)
+        self.token = token
+        self._app = None
+
+    async def _handle_message(self, update, context) -> None:
+        """Handle any incoming message (text, photo, voice, file, video)."""
+        if not update.message:
+            return
+
+        msg = update.message
+        user_id = str(msg.from_user.id)
+        session_id = self._user_session_id("telegram", user_id)
+        text = msg.caption or msg.text or ""
+        attachments: list[dict] = []
+
+        # Download media to temp dir
+        tmp_dir = tempfile.mkdtemp(prefix="openagent_tg_")
+
+        try:
+            if msg.photo:
+                photo = msg.photo[-1]  # highest resolution
+                file = await photo.get_file()
+                path = str(Path(tmp_dir) / f"photo_{photo.file_unique_id}.jpg")
+                await file.download_to_drive(path)
+                attachments.append({"type": "image", "path": path, "filename": Path(path).name})
+
+            if msg.voice:
+                file = await msg.voice.get_file()
+                path = str(Path(tmp_dir) / f"voice_{msg.voice.file_unique_id}.ogg")
+                await file.download_to_drive(path)
+                attachments.append({"type": "voice", "path": path, "filename": Path(path).name})
+
+            if msg.audio:
+                file = await msg.audio.get_file()
+                fname = msg.audio.file_name or f"audio_{msg.audio.file_unique_id}"
+                path = str(Path(tmp_dir) / fname)
+                await file.download_to_drive(path)
+                attachments.append({"type": "file", "path": path, "filename": fname})
+
+            if msg.document:
+                file = await msg.document.get_file()
+                fname = msg.document.file_name or f"doc_{msg.document.file_unique_id}"
+                path = str(Path(tmp_dir) / fname)
+                await file.download_to_drive(path)
+                attachments.append({"type": "file", "path": path, "filename": fname})
+
+            if msg.video:
+                file = await msg.video.get_file()
+                fname = msg.video.file_name or f"video_{msg.video.file_unique_id}.mp4"
+                path = str(Path(tmp_dir) / fname)
+                await file.download_to_drive(path)
+                attachments.append({"type": "video", "path": path, "filename": fname})
+
+            if not text and not attachments:
+                return
+
+            response = await self.agent.run(
+                message=text,
+                user_id=user_id,
+                session_id=session_id,
+                attachments=attachments if attachments else None,
+            )
+
+            await self._send_response(msg, response)
+
+        except Exception as e:
+            logger.error(f"Telegram handler error: {e}")
+            await msg.reply_text("Sorry, something went wrong.")
+
+    async def _send_response(self, msg, response: str) -> None:
+        """Send agent response, handling file markers."""
+        clean_text, attachments = parse_response_markers(response)
+
+        # Send attachments
+        for att in attachments:
+            try:
+                path = Path(att.path)
+                if not path.exists():
+                    continue
+                if att.type == "image":
+                    await msg.reply_photo(photo=open(path, "rb"), caption=att.caption)
+                elif att.type == "voice":
+                    await msg.reply_voice(voice=open(path, "rb"))
+                elif att.type == "video":
+                    await msg.reply_video(video=open(path, "rb"), caption=att.caption)
+                else:
+                    await msg.reply_document(document=open(path, "rb"), filename=att.filename)
+            except Exception as e:
+                logger.error(f"Failed to send attachment {att.filename}: {e}")
+
+        # Send text (split on 4096 char limit)
+        if clean_text:
+            for i in range(0, len(clean_text), 4096):
+                await msg.reply_text(clean_text[i:i + 4096])
+
+    async def _handle_start(self, update, context) -> None:
+        await update.message.reply_text(
+            f"Hello! I'm {self.agent.name}. Send me a message, photo, voice, or file."
+        )
+
+    async def start(self) -> None:
+        try:
+            from telegram.ext import ApplicationBuilder, MessageHandler, CommandHandler, filters
+        except ImportError:
+            raise ImportError(
+                "python-telegram-bot is required for Telegram channel. "
+                "Install it with: pip install openagent[telegram]"
+            )
+
+        self._app = ApplicationBuilder().token(self.token).build()
+        self._app.add_handler(CommandHandler("start", self._handle_start))
+        # Handle all content types
+        self._app.add_handler(MessageHandler(
+            filters.TEXT | filters.PHOTO | filters.VOICE | filters.AUDIO |
+            filters.Document.ALL | filters.VIDEO,
+            self._handle_message,
+        ))
+
+        logger.info(f"Starting Telegram bot for agent '{self.agent.name}'")
+        await self._app.initialize()
+        await self._app.start()
+        await self._app.updater.start_polling()
+
+        # Keep alive until stopped
+        self._stop_event = asyncio.Event()
+        await self._stop_event.wait()
+
+    async def stop(self) -> None:
+        if hasattr(self, '_stop_event'):
+            self._stop_event.set()
+        if self._app:
+            await self._app.updater.stop()
+            await self._app.stop()
+            await self._app.shutdown()