opus-agent-base 0.1.0__tar.gz

opus_agent_base-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+dist

opus_agent_base-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

opus_agent_base-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: opus-agent-base
+Version: 0.1.0
+Summary: Base framework for Opus AI Agents
+Author-email: Sathish <sathish316@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.40.21
+Requires-Dist: chromadb>=1.1.1
+Requires-Dist: fastmcp>=2.12.4
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic-ai-slim[anthropic,openai,retries]>=0.8.1
+Requires-Dist: pydantic-ai>=0.8.1
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rapidfuzz>=3.14.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: singleton-decorator>=1.0.0
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: typer>=0.19.2

opus_agent_base-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "opus-agent-base"
+version = "0.1.0"
+description = "Base framework for Opus AI Agents"
+authors = [
+    { name = "Sathish", email = "sathish316@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "boto3>=1.40.21",
+    "pydantic-ai>=0.8.1",
+    "pydantic-ai-slim[anthropic,openai,retries]>=0.8.1",
+    "tenacity>=8.2.0",
+    "httpx>=0.24.0",
+    "singleton-decorator>=1.0.0",
+    "fastmcp>=2.12.4",
+    "typer>=0.19.2",
+    "tiktoken>=0.12.0",
+    "chromadb>=1.1.1",
+    "rapidfuzz>=3.14.1",
+    "prompt-toolkit>=3.0.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.scripts]
+opus-agent-base = "opus_agent_base:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opus_agent_base"]

opus_agent_base-0.1.0/src/opus_agent_base/__init__.py

@@ -0,0 +1,21 @@
+"""
+Opus Agent Base - Core framework for building AI agents.
+"""
+
+__version__ = "0.1.0"
+
+
+def main() -> None:
+    """Entry point for opus-agent-base CLI."""
+    # Lazy import to avoid circular dependencies
+    from opus_agent_base.cli.cli import create_cli_app
+
+    app = create_cli_app(
+        agent_name="Opus Agent Base",
+        agent_description="Base framework for Opus AI Agents",
+        agent_version=__version__,
+    )
+    app()
+
+
+__all__ = ["main", "__version__"]

opus_agent_base-0.1.0/src/opus_agent_base/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent management and execution modules."""

opus_agent_base-0.1.0/src/opus_agent_base/agent/agent_builder.py

@@ -0,0 +1,91 @@
+from opus_agent_base.config.config_manager import ConfigManager
+from opus_agent_base.prompt.instructions_manager import InstructionsManager
+from opus_agent_base.model.model_manager import ModelManager
+from opus_agent_base.tools.custom_tool import CustomTool
+from opus_agent_base.tools.higher_order_tool import HigherOrderTool
+from opus_agent_base.tools.meta_tool import MetaTool
+from opus_agent_base.tools.fastmcp_server_config import FastMCPServerConfig
+from opus_agent_base.tools.mcp_manager import MCPManager
+
+from typing import Any
+from pydantic_ai import Agent
+
+
+class AgentBuilder:
+    """Builder for the agent"""
+
+    def __init__(self, config_manager: ConfigManager):
+        self.config_manager = config_manager
+        self.custom_tools: list[CustomTool] = []
+        self.higher_order_tools: list[HigherOrderTool] = []
+        self.meta_tools: list[MetaTool] = []
+        self.mcp_servers_config: list[FastMCPServerConfig] = []
+
+    def name(self, name: str):
+        self.name = name
+        return self
+
+    def set_system_prompt_keys(self, system_prompt_keys: list[str]):
+        self.system_prompt_keys = system_prompt_keys
+        return self
+
+    def add_instructions_manager(
+        self, instructions_manager: InstructionsManager = None
+    ):
+        if instructions_manager is not None:
+            self.instructions_manager = instructions_manager
+        else:
+            self.instructions_manager = InstructionsManager()
+        return self
+
+    def instruction(self, key: str, file: str):
+        self.instructions_manager.put_from_file(key, file)
+        return self
+
+    def add_model_manager(self):
+        self.model_manager = ModelManager(self.config_manager)
+        return self
+
+    def custom_tool(self, custom_tool: CustomTool):
+        self.custom_tools.append(custom_tool)
+        return self
+
+    def higher_order_tool(self, higher_order_tool: HigherOrderTool):
+        self.higher_order_tools.append(higher_order_tool)
+        return self
+
+    def meta_tool(self, meta_tool: MetaTool):
+        self.meta_tools.append(meta_tool)
+        return self
+
+    def add_mcp_server_config(self, mcp_server_config: FastMCPServerConfig):
+        self.mcp_servers_config.append(mcp_server_config)
+        return self
+
+    def add_mcp_servers_config(self, mcp_servers_config: list[FastMCPServerConfig]):
+        self.mcp_servers_config.extend(mcp_servers_config)
+        return self
+
+    def set_deps_type(self, deps_type: Any):
+        self.deps_type = deps_type
+        return self
+
+    def set_output_type(self, output_type: Any):
+        self.output_type = output_type
+        return self
+
+    def build_simple_agent(self) -> Agent:
+        system_prompt = "\n".join(
+            self.instructions_manager.get(key) for key in self.system_prompt_keys
+        )
+        agent_kwargs = {
+            "system_prompt": system_prompt,
+            "model": self.model_manager.get_model(),
+            "tools": [],
+        }
+
+        # Add output_type if set
+        if hasattr(self, "output_type") and self.output_type is not None:
+            agent_kwargs["output_type"] = self.output_type
+
+        return Agent(**agent_kwargs)

opus_agent_base-0.1.0/src/opus_agent_base/agent/agent_manager.py

@@ -0,0 +1,157 @@
+import json
+import logging
+
+from fastmcp.client.client import ClientSession
+from mcp.types import Tool as MCPTool
+from pydantic_ai import Agent
+from pydantic_ai.tools import Tool
+from singleton_decorator import singleton
+
+from opus_agent_base.agent.agent_builder import AgentBuilder
+from opus_agent_base.common.logging_config import console_log
+from opus_agent_base.tools.custom_tools_manager import CustomToolsManager
+from opus_agent_base.tools.mcp_manager import MCPManager
+from opus_agent_base.tools.higher_order_tools_manager import HigherOrderToolsManager
+from opus_agent_base.tools.meta_tools_manager import MetaToolsManager
+
+logger = logging.getLogger(__name__)
+
+
+@singleton
+class AgentManager:
+    """
+    Manager for the agent
+    """
+
+    def __init__(self, name: str, builder: AgentBuilder):
+        self.name = name
+        self.config_manager = builder.config_manager
+        self.system_prompt_keys = builder.system_prompt_keys
+        self.instructions_manager = builder.instructions_manager
+        self.model_manager = builder.model_manager
+        self.custom_tools = builder.custom_tools
+        self.higher_order_tools = builder.higher_order_tools
+        self.meta_tools = builder.meta_tools
+        self.mcp_servers_config = builder.mcp_servers_config
+
+    async def initialize_agent(self):
+        # System prompt
+        logger.info("Initializing Agent")
+        agent_system_prompt = "\n".join(
+            self.instructions_manager.get(key)
+            for key in self.system_prompt_keys
+        )
+
+        # Initialize MCP servers
+        await self.initialize_mcp_servers()
+
+        # Initialize Agent tools
+        await self.initialize_agent_tools()
+
+        # Initialize Agent
+        self.agent = Agent(
+            system_prompt=agent_system_prompt,
+            model=self.model_manager.get_model(),
+            tools=self.agent_tools,
+        )
+
+        # Add custom tools to Agent
+        self.custom_tools_manager = CustomToolsManager(
+            self.config_manager,
+            self.instructions_manager,
+            self.model_manager,
+            self.agent,
+        )
+        self.custom_tools_manager.initialize_tools(self.custom_tools)
+
+        # Add higher order tools to Agent
+        self.higher_order_tools_manager = HigherOrderToolsManager(
+            self.config_manager, self.agent, self.fastmcp_client_context
+        )
+        await self.higher_order_tools_manager.initialize_tools(self.higher_order_tools)
+
+        # Add meta tools to Agent
+        self.meta_tools_manager = MetaToolsManager(self.config_manager, self.agent)
+        meta_tools = await self.meta_tools_manager.initialize_tools(self.meta_tools)
+
+        logger.info("Agent initialized")
+
+    async def initialize_mcp_servers(self):
+        # Initialize MCP manager and MCP servers
+        logger.info("Initializing MCP servers")
+        self.mcp_manager = MCPManager(self.config_manager)
+        self.mcp_manager.add_mcp_servers(self.mcp_servers_config)
+        logger.info("MCP servers initialized")
+
+    async def initialize_agent_tools(self):
+        # Initialize Agent tools
+        self.agent_tools = []
+        self.fastmcp_client_context = await self.mcp_manager.initialize_fastmcp_client_context()
+        await self.mcp_manager.inspect_fastmcp_client_tools()
+
+        async def tools_initializer(session: ClientSession):
+            enabled_tools = {}
+            logger.info("Initializing agent tools")
+            client_tools = await session.list_tools()
+            for tool in client_tools:
+                tool_prefix = tool.name.split("_")[0]
+                if tool_prefix in self.config_manager.get_setting(
+                    "mcp_config.allowed_tool_prefixes", []
+                ):
+                    if tool.name in self.config_manager.get_setting(
+                        "mcp_config.allowed_tools"
+                    ).get(tool_prefix, []):
+                        logger.debug(f"Wrapping FastMCP tool: {tool.name}")
+                        self.agent_tools.append(self._wrap_tool(tool, self.fastmcp_client_context))
+                        self._log_enabled_tools(enabled_tools, tool_prefix, tool.name)
+                else:
+                    self._log_enabled_tools(enabled_tools, tool_prefix, tool.name)
+                    self.agent_tools.append(self._wrap_tool(tool, self.fastmcp_client_context))
+            return enabled_tools
+
+        if self.fastmcp_client_context is not None:
+            result = await self.fastmcp_client_context(tools_initializer)
+            console_log(f"Enabled tools: {result}")
+
+        # Initialize Meta tools
+        result = await self.initialize_meta_tools()
+        logger.info(f"Enabled Meta tools: {result}")
+
+    async def initialize_meta_tools(self):
+        # Initialize Meta tools
+        result = []
+        logger.info("Initializing Meta tools")
+        for meta_tool in self.meta_tools:
+            await meta_tool.setup_tool()
+            agent_tool = await meta_tool.build_agent_tool()
+            self.agent_tools.append(agent_tool)
+            result.append(meta_tool.name)
+
+        logger.info("Meta tools initialized")
+        return result
+
+    def get_agent(self):
+        return self.agent
+
+    def _wrap_tool(self, tool: MCPTool, fastmcp_client_context) -> Tool:
+        async def mcp_tool_function(**kwargs):
+            """Dynamically created tool function for MCP tool"""
+
+            async def execute_tool(client: ClientSession):
+                result = await client.call_tool(tool.name, kwargs)
+                return result
+
+            result = await fastmcp_client_context(execute_tool)
+            return result
+
+        return Tool.from_schema(
+            name=tool.name,
+            description=tool.description,
+            json_schema=tool.inputSchema,
+            function=mcp_tool_function,
+        )
+
+    def _log_enabled_tools(self, enabled_tools, tool_prefix, tool_name):
+        if tool_prefix not in enabled_tools:
+            enabled_tools[tool_prefix] = set()
+        enabled_tools[tool_prefix].add(tool_name)

opus_agent_base-0.1.0/src/opus_agent_base/agent/agent_runner.py

@@ -0,0 +1,52 @@
+import logging
+
+from opus_agent_base.agent.agent_builder import AgentBuilder
+from opus_agent_base.agent.agent_manager import AgentManager
+from opus_agent_base.common.logging_config import console_log, quick_setup
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRunner:
+    def __init__(
+        self,
+        agent_builder: AgentBuilder,
+    ):
+        self.agent_builder = agent_builder
+        self.agent_manager = None
+        self.agent = None
+        self._setup_logging()
+
+    def _setup_logging(self):
+        log_level = self.agent_builder.config_manager.get_setting("debug.log_level", "ERROR")
+        quick_setup(log_level=log_level)
+
+    async def run_agent(self):
+        """Run Agent CLI using PydanticAI CLI"""
+        try:
+            console_log("🚀 Starting Agent...")
+            # Initialize Agent
+            if self.agent is None:
+                self.agent_manager = AgentManager(
+                  self.agent_builder.name,
+                  self.agent_builder
+                )
+                await self.agent_manager.initialize_agent()
+                self.agent = self.agent_manager.get_agent()
+
+            console_log("✅ Agent started")
+            await self.agent.to_cli()
+
+        except ExceptionGroup as eg:
+            console_log("❌ Exception running agent")
+            logger.error("Exception running agent:")
+            for e in eg.exceptions:
+                import traceback
+                traceback.print_exception(e)
+            raise
+        except KeyboardInterrupt:
+            console_log("\n🛑 Agent interrupted")
+            logger.debug("Agent interrupted by user")
+        finally:
+            console_log("🏁 Agent session ended")
+            logger.debug("Agent session ended")

opus_agent_base-0.1.0/src/opus_agent_base/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI interface for Opus agents."""

opus_agent_base-0.1.0/src/opus_agent_base/cli/cli.py

@@ -0,0 +1,293 @@
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+import typer
+from prompt_toolkit import PromptSession
+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.styles import Style
+from rich.console import Console
+from rich.table import Table
+
+from opus_agent_base.config.config_command_manager import ConfigCommandManager
+from opus_agent_base.config.config_manager import ConfigManager
+from opus_agent_base.ui.logo import display_logo
+
+# Setup rich console for pretty output
+console = Console()
+logger = logging.getLogger(__name__)
+
+config_manager = ConfigManager()
+config_command_manager = ConfigCommandManager(config_manager, console)
+
+
+def create_cli_app(
+    agent_name: str, agent_description: str, agent_version: str, agent_runner: callable = None
+) -> typer.Typer:
+    """Creates a Typer app for the agent CLI."""
+    app = typer.Typer(
+        name=agent_name,
+        help=agent_description,
+        rich_markup_mode="rich",
+    )
+
+    def run_cli_mode(run_agent_on_startup: bool = False):
+        """Run the admin mode with slash commands."""
+        display_logo(console)
+        # Set up command history file
+        history_dir = Path.home() / ".opusai"
+        history_dir.mkdir(exist_ok=True)
+        history_file = history_dir / ".admin_history"
+
+        # Set up command completion for all available commands and subcommands
+        command_completer = WordCompleter(
+            [
+                "/help",
+                "/agent",
+                "/todo-agent",
+                "/sde-agent",
+                "/config",
+                "/config init",
+                "/config list",
+                "/config get",
+                "/config set",
+                "/config delete",
+                "/status",
+                "/clear",
+                "/exit",
+                "/quit",
+            ],
+            ignore_case=True,
+            sentence=True,
+        )
+
+        # Create custom style for prompt
+        prompt_style = Style.from_dict(
+            {
+                "prompt": "bold ansiblue",
+            }
+        )
+
+        # Create prompt session with history, auto-suggestions, and completion
+        session = PromptSession(
+            history=FileHistory(str(history_file)),
+            auto_suggest=AutoSuggestFromHistory(),
+            completer=command_completer,
+            complete_while_typing=True,
+            style=prompt_style,
+        )
+
+        # Run agent on startup if requested
+        if run_agent_on_startup:
+            try:
+                if agent_runner:
+                    asyncio.run(agent_runner())
+                else:
+                    console.print("[yellow]No agent runner provided[/yellow]")
+            except KeyboardInterrupt:
+                console.print("\n[dim]Agent interrupted. Returning to CLI...[/dim]")
+            except Exception as e:
+                import traceback
+
+                console.print(f"[red]Agent error: {e}[/red]")
+                console.print("[dim]Stacktrace:[/dim]")
+                console.print(traceback.format_exc())
+
+        while True:
+            try:
+                # Use prompt_toolkit for input with command history support
+                command = session.prompt([("class:prompt", "\nopus> ")]).strip()
+
+                if not command:
+                    continue
+
+                if not command.startswith("/"):
+                    console.print(
+                        "[yellow]Commands must start with '/'. Type /help for available commands.[/yellow]"
+                    )
+                    continue
+
+                # Parse command
+                parts = command[1:].split()
+                if not parts:
+                    continue
+
+                cmd = parts[0].lower()
+                args = parts[1:] if len(parts) > 1 else []
+
+                # Handle commands
+                if cmd == "exit" or cmd == "quit":
+                    console.print("[green]Goodbye![/green]")
+                    break
+                elif cmd == "help":
+                    show_admin_help()
+                elif cmd == "agent":
+                    if agent_runner:
+                        asyncio.run(agent_runner())
+                    else:
+                        console.print("[yellow]No agent runner configured[/yellow]")
+                elif cmd == "todo-agent":
+                    from opus_todo_agent.todo_agent_runner import run_todo_agent
+
+                    asyncio.run(run_todo_agent())
+                elif cmd == "sde-agent":
+                    from opus_sde_agent.sde_agent_runner import run_sde_agent
+
+                    asyncio.run(run_sde_agent())
+                elif cmd == "config":
+                    config_command_manager.handle_config_command(args)
+                elif cmd == "status":
+                    show_status()
+                elif cmd == "clear":
+                    os.system("clear" if os.name == "posix" else "cls")
+                else:
+                    console.print(f"[red]Unknown command: /{cmd}[/red]")
+                    console.print("Type [bold]/help[/bold] for available commands.")
+
+            except KeyboardInterrupt:
+                console.print("\n[green]Goodbye![/green]")
+                break
+            except EOFError:
+                console.print("\n[green]Goodbye![/green]")
+                break
+            except Exception as e:
+                console.print(f"[red]Error: {e}[/red]")
+                sys.exit(1)
+
+    def show_admin_help():
+        """Show help for admin commands."""
+        table = Table(title="Admin Mode Commands")
+        table.add_column("Command", style="cyan", no_wrap=True)
+        table.add_column("Description", style="white")
+
+        commands = [
+            ("/help", "Show this help message"),
+            ("/agent", "Run Agent mode"),
+            ("/config init", "Initialize config file from sample template"),
+            ("/config list", "List all configuration settings"),
+            ("/config get <key>", "Get a specific configuration setting"),
+            (
+                "/config set <key> <value>",
+                "Set a configuration setting",
+            ),
+            ("/config delete <key>", "Delete a configuration setting"),
+            ("/status", "Show agent status and configuration"),
+            ("/clear", "Clear the screen"),
+            ("/exit, /quit", "Exit admin mode"),
+        ]
+
+        for cmd, desc in commands:
+            table.add_row(cmd, desc)
+
+        console.print(table)
+
+        # Add helpful tips
+        console.print("\n[bold cyan]💡 Navigation & Editing Tips:[/bold cyan]")
+        tips_table = Table(show_header=False, box=None, padding=(0, 2))
+        tips_table.add_column("Key", style="yellow")
+        tips_table.add_column("Action", style="dim white")
+
+        tips = [
+            ("↑/↓", "Navigate command history"),
+            ("Tab", "Auto-complete commands"),
+            ("→", "Accept auto-suggestion"),
+            ("Ctrl+C", "Cancel / Exit"),
+            ("Ctrl+L", "Clear screen"),
+            ("Ctrl+A/E", "Jump to start/end of line"),
+        ]
+
+        for key, action in tips:
+            tips_table.add_row(key, action)
+
+        console.print(tips_table)
+        console.print(
+            "\n[dim]Config keys support dot notation (e.g., todoist.api_key)[/dim]"
+        )
+
+    def show_status():
+        """Show agent status and configuration."""
+        table = Table(title="Agent Status")
+        table.add_column("Component", style="cyan")
+        table.add_column("Status", style="white")
+
+        # Check environment variables
+        required_env_vars = [
+            "OPENAI_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "GOOGLE_OAUTH_CLIENT_ID",
+            "GOOGLE_OAUTH_CLIENT_SECRET",
+            "SLACK_MCP_XOXC_TOKEN",
+            "SLACK_MCP_XOXD_TOKEN",
+            "SLACK_MCP_XOXP_TOKEN",
+        ]
+
+        for var in required_env_vars:
+            value = os.getenv(var)
+            status = "[green]Set[/green]" if value else "[red]Not Set[/red]"
+            table.add_row(var, status)
+
+        # Configuration file status
+        config_exists = config_manager.config_file.exists()
+        config_status = (
+            "[green]Exists[/green]" if config_exists else "[yellow]Not Found[/yellow]"
+        )
+        table.add_row("Config File", config_status)
+        table.add_row("Config Path", str(config_manager.config_file))
+
+        if config_exists:
+            config = config_manager.load_config()
+            table.add_row("Config Settings", str(len(config)))
+
+        console.print(table)
+
+    @app.command()
+    def main(
+        agent: bool = typer.Option(
+            False,
+            "--agent",
+            "-ai",
+            help="Start in Agent mode with slash commands for configuration",
+        ),
+        todo: bool = typer.Option(
+            False,
+            "--todo-agent",
+            "-todo",
+            help="Start in TODO Agent mode",
+        ),
+        sde: bool = typer.Option(
+            False,
+            "--sde-agent",
+            "-sde",
+            help="Start in SDE Agent mode",
+        ),
+        admin: bool = typer.Option(
+            False,
+            "--admin",
+            "-a",
+            help="Start in admin mode with slash commands for configuration",
+        ),
+        version: bool = typer.Option(
+            False, "--version", "-v", help="Show version information"
+        ),
+    ):
+        f"""
+        {agent_name} - {agent_description}.
+
+        Use --admin to enter configuration mode with slash commands.
+        """
+        if version:
+            console.print(f"[bold blue]{agent_name}[/bold blue] v{agent_version}")
+            console.print(agent_description)
+            return
+
+        if admin:
+            run_cli_mode(run_agent_on_startup=False)
+        else:
+            # Run the configured agent (if provided) or enter CLI mode
+            run_cli_mode(run_agent_on_startup=True)
+
+    return app

opus_agent_base-0.1.0/src/opus_agent_base/common/__init__.py

@@ -0,0 +1 @@
+"""Common utilities and helpers."""