amd-gaia 0.14.1__py3-none-any.whl

gaia/api/agent_registry.py

@@ -0,0 +1,238 @@
+# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""
+Agent Registry - Exposes GAIA agents as OpenAI "models"
+
+GAIA doesn't manage LLM models (Lemonade does that). Instead, we expose
+GAIA agents as "models" in the OpenAI API, allowing users to select which
+agent type they want to use.
+
+Example:
+    User selects "gaia-code" model -> Routes to CodeAgent
+    User selects "gaia-jira" model -> Routes to JiraAgent
+
+This is a simple hardcoded mapping for users to select agent types.
+"""
+
+import logging
+import os
+import time
+from typing import Any, Dict, List
+
+from gaia.agents.base.agent import Agent
+from gaia.agents.base.api_agent import ApiAgent
+from gaia.api.sse_handler import SSEOutputHandler
+
+logger = logging.getLogger(__name__)
+
+
+# Hardcoded agent mappings: "model" name -> (Agent class, init params)
+# These are the "models" exposed in /v1/models and selectable in VSCode
+AGENT_MODELS = {
+    "gaia-code": {
+        "class_name": "gaia.agents.routing.agent.RoutingAgent",
+        "init_params": {
+            "api_mode": True,  # Skip interactive questions, use defaults/best-guess
+            "silent_mode": True,
+            "streaming": False,
+            "max_steps": 100,
+        },
+        "description": "Intelligent routing agent that detects language/project type and routes to CodeAgent",
+    }
+}
+
+
+# Apply environment variable overrides to all agent init_params
+# These are set by app.py when starting the API server with debug flags
+def _apply_env_overrides():
+    """
+    Read environment variables set by `gaia api start` and override agent init_params.
+
+    Environment variables:
+        GAIA_API_DEBUG: Enable debug logging and console output
+        GAIA_API_SHOW_PROMPTS: Display prompts sent to LLM
+        GAIA_API_STREAMING: Enable real-time streaming of LLM responses
+        GAIA_API_STEP_THROUGH: Enable step-through debugging mode
+    """
+    debug = os.environ.get("GAIA_API_DEBUG") == "1"
+    show_prompts = os.environ.get("GAIA_API_SHOW_PROMPTS") == "1"
+    streaming = os.environ.get("GAIA_API_STREAMING") == "1"
+
+    # Apply overrides to all agents
+    for model_id, config in AGENT_MODELS.items():
+        init_params = config["init_params"]
+
+        # When debug is enabled, disable silent_mode to show console output
+        if debug:
+            init_params["debug"] = True
+            init_params["silent_mode"] = False
+            logger.info(f"Debug mode enabled for {model_id}")
+
+        if show_prompts:
+            init_params["show_prompts"] = True
+            logger.info(f"Show prompts enabled for {model_id}")
+
+        if streaming:
+            init_params["streaming"] = True
+            logger.info(f"Streaming enabled for {model_id}")
+
+
+# Apply environment overrides at module import time
+_apply_env_overrides()
+
+
+class AgentRegistry:
+    """
+    Registry that exposes GAIA agents as OpenAI-compatible "models".
+
+    Note: These aren't LLM models - they're GAIA agent types.
+    Lemonade handles the actual LLM models underneath.
+    """
+
+    def __init__(self):
+        """Initialize registry with hardcoded agents"""
+        self._loaded_classes: Dict[str, type] = {}
+
+    def _load_agent_class(self, class_path: str) -> type:
+        """
+        Dynamically load agent class from module path.
+
+        Args:
+            class_path: Full module path (e.g., "gaia.agents.code.agent.CodeAgent")
+
+        Returns:
+            Agent class
+        """
+        if class_path in self._loaded_classes:
+            return self._loaded_classes[class_path]
+
+        module_path, class_name = class_path.rsplit(".", 1)
+        module = __import__(module_path, fromlist=[class_name])
+        cls = getattr(module, class_name)
+
+        self._loaded_classes[class_path] = cls
+        return cls
+
+    def get_agent(self, model_id: str) -> Agent:
+        """
+        Instantiate and return agent for model ID with SSE output handler.
+
+        Args:
+            model_id: Model ID (e.g., "gaia-code", "gaia-jira")
+
+        Returns:
+            Agent instance configured for API streaming
+
+        Raises:
+            ValueError: If model_id not found
+
+        Example:
+            >>> registry = AgentRegistry()
+            >>> agent = registry.get_agent("gaia-code")
+            >>> result = agent.process_query("Write hello world")
+        """
+        if model_id not in AGENT_MODELS:
+            available = ", ".join(AGENT_MODELS.keys())
+            raise ValueError(
+                f"Model '{model_id}' not found. " f"Available models: {available}"
+            )
+
+        config = AGENT_MODELS[model_id]
+
+        try:
+            agent_class = self._load_agent_class(config["class_name"])
+            init_params = config["init_params"].copy()
+
+            # Check if debug mode is enabled
+            debug_mode = os.environ.get("GAIA_API_DEBUG") == "1"
+
+            # API layer always uses SSEOutputHandler for streaming to clients
+            # Pass debug_mode flag to control verbosity
+            init_params["output_handler"] = SSEOutputHandler(debug_mode=debug_mode)
+
+            if debug_mode:
+                logger.debug(f"Creating agent {model_id} with debug mode enabled")
+
+            return agent_class(**init_params)
+        except ImportError as e:
+            logger.error(f"Failed to load agent {model_id}: {e}")
+            raise ValueError(f"Agent {model_id} not available: {e}")
+
+    def list_models(self) -> List[Dict[str, Any]]:
+        """
+        Return OpenAI-compatible model list.
+
+        Note: These are GAIA agents exposed as "models", not LLM models.
+
+        Returns:
+            List of model metadata dicts for /v1/models endpoint
+
+        Example:
+            >>> registry = AgentRegistry()
+            >>> models = registry.list_models()
+            >>> [m["id"] for m in models]
+            ['gaia-code', 'gaia-jira']
+        """
+        models = []
+
+        for model_id, config in AGENT_MODELS.items():
+            try:
+                # Try to load agent to get metadata (if it implements ApiAgent)
+                agent_class = self._load_agent_class(config["class_name"])
+                agent = agent_class(**config["init_params"])
+
+                # Get model info (custom if ApiAgent, default otherwise)
+                if isinstance(agent, ApiAgent):
+                    model_info = agent.get_model_info()
+                    logger.debug(
+                        f"Agent {model_id} provides custom model info: {model_info}"
+                    )
+                else:
+                    model_info = {
+                        "max_input_tokens": 8192,
+                        "max_output_tokens": 4096,
+                    }
+                    logger.debug(f"Agent {model_id} using default model info")
+            except Exception as e:
+                # Agent not available or initialization failed, use defaults
+                logger.warning(f"Agent {model_id} not available ({e}), using defaults")
+                model_info = {
+                    "max_input_tokens": 8192,
+                    "max_output_tokens": 4096,
+                }
+
+            models.append(
+                {
+                    "id": model_id,
+                    "object": "model",
+                    "created": int(time.time()),
+                    "owned_by": "amd-gaia",
+                    "description": config.get("description", ""),
+                    **model_info,
+                }
+            )
+
+        return models
+
+    def model_exists(self, model_id: str) -> bool:
+        """
+        Check if model ID exists.
+
+        Args:
+            model_id: Model ID to check
+
+        Returns:
+            True if model exists, False otherwise
+
+        Example:
+            >>> registry = AgentRegistry()
+            >>> registry.model_exists("gaia-code")
+            True
+            >>> registry.model_exists("nonexistent")
+            False
+        """
+        return model_id in AGENT_MODELS
+
+
+# Global registry instance
+registry = AgentRegistry()

gaia/api/app.py

@@ -0,0 +1,305 @@
+# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""
+CLI entry point for GAIA OpenAI-compatible API server
+
+This module provides command-line interface for managing the API server.
+
+Usage:
+    gaia api start [--host HOST] [--port PORT] [--background]
+    gaia api status
+    gaia api stop
+"""
+
+import argparse
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def start_server(
+    host: str = "localhost",
+    port: int = 8080,
+    background: bool = False,
+    debug: bool = False,
+    show_prompts: bool = False,
+    streaming: bool = False,
+    step_through: bool = False,
+) -> None:
+    """
+    Start the API server.
+
+    Args:
+        host: Host to bind to (default: localhost)
+        port: Port to bind to (default: 8080)
+        background: Run in background if True, foreground otherwise
+        debug: Enable debug logging
+        show_prompts: Display prompts sent to LLM
+        streaming: Enable real-time streaming of LLM responses
+        step_through: Enable step-through debugging mode
+
+    Example:
+        >>> start_server("localhost", 8080, background=True)
+        ✅ GAIA API server started in background (PID: 12345)
+        >>> start_server("localhost", 8080, debug=True, show_prompts=True)
+        ✅ GAIA API server started with debug mode enabled
+    """
+    # Set environment variables for agent configuration
+    # These will be read by agent_registry.py when agents are instantiated
+    if debug:
+        os.environ["GAIA_API_DEBUG"] = "1"
+    if show_prompts:
+        os.environ["GAIA_API_SHOW_PROMPTS"] = "1"
+    if streaming:
+        os.environ["GAIA_API_STREAMING"] = "1"
+    if step_through:
+        os.environ["GAIA_API_STEP_THROUGH"] = "1"
+
+    if background:
+        # Start in background
+        log_file = Path("gaia_api.log")
+        with open(log_file, "w", encoding="utf-8") as f:
+            proc = subprocess.Popen(
+                [
+                    sys.executable,
+                    "-m",
+                    "uvicorn",
+                    "gaia.api.openai_server:app",
+                    "--host",
+                    host,
+                    "--port",
+                    str(port),
+                ],
+                stdout=f,
+                stderr=f,
+            )
+        print(f"✅ GAIA API server started in background (PID: {proc.pid})")
+        print(f"📝 Logs: {log_file}")
+        print(f"🌐 URL: http://{host}:{port}")
+        if debug or show_prompts or streaming or step_through:
+            print("\n🐛 Debug features enabled:")
+            if debug:
+                print("  • Debug logging")
+            if show_prompts:
+                print("  • Show prompts")
+            if streaming:
+                print("  • LLM streaming")
+            if step_through:
+                print("  • Step-through mode")
+        print("\nAvailable endpoints:")
+        print(f"  • POST http://{host}:{port}/v1/chat/completions")
+        print(f"  • GET  http://{host}:{port}/v1/models")
+        print(f"  • GET  http://{host}:{port}/health")
+    else:
+        # Start in foreground
+        import uvicorn
+
+        print(f"🚀 Starting GAIA API server on http://{host}:{port}")
+        if debug or show_prompts or streaming or step_through:
+            print("\n🐛 Debug features enabled:")
+            if debug:
+                print("  • Debug logging")
+            if show_prompts:
+                print("  • Show prompts")
+            if streaming:
+                print("  • LLM streaming")
+            if step_through:
+                print("  • Step-through mode")
+        print("\nAvailable endpoints:")
+        print(f"  • POST http://{host}:{port}/v1/chat/completions")
+        print(f"  • GET  http://{host}:{port}/v1/models")
+        print(f"  • GET  http://{host}:{port}/health")
+        print("\nPress Ctrl+C to stop\n")
+
+        # Set uvicorn log level based on debug flag
+        log_level = "debug" if debug else "info"
+        uvicorn.run(
+            "gaia.api.openai_server:app", host=host, port=port, log_level=log_level
+        )
+
+
+def check_status() -> None:
+    """
+    Check if API server is running.
+
+    This will be implemented in a future version.
+    For now, it just prints a message.
+    """
+    print("Status check not yet implemented")
+    print("Try: curl http://localhost:8080/health")
+
+
+def stop_server(port: int = 8080) -> None:
+    """
+    Stop the API server by finding and killing processes on the port.
+
+    Args:
+        port: Port number to stop server on (default: 8080)
+
+    Returns:
+        None
+    """
+    import platform
+    import signal
+
+    system = platform.system()
+
+    try:
+        if system == "Windows":
+            # Windows: Use netstat to find PID, then taskkill to stop it
+            result = subprocess.run(
+                ["netstat", "-ano"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+
+            # Parse netstat output to find PIDs listening on the port
+            pids = set()
+            for line in result.stdout.splitlines():
+                if f":{port}" in line and "LISTENING" in line:
+                    # Line format: "  TCP    0.0.0.0:8080    0.0.0.0:0    LISTENING    12345"
+                    parts = line.split()
+                    if parts and parts[-1].isdigit():
+                        pids.add(parts[-1])
+
+            if pids:
+                for pid in pids:
+                    try:
+                        subprocess.run(
+                            ["taskkill", "/F", "/PID", pid],
+                            capture_output=True,
+                            timeout=5,
+                            check=False,
+                        )
+                        print(f"🛑 Stopped API server process (PID: {pid})")
+                    except (
+                        subprocess.TimeoutExpired,
+                        subprocess.CalledProcessError,
+                    ) as e:
+                        print(f"⚠️  Failed to stop PID {pid}: {e}")
+                print("✅ API server stopped")
+            else:
+                print("ℹ️  No API server found running on port {port}")
+
+        else:
+            # Linux/Mac: Use lsof to find PID, then kill it
+            result = subprocess.run(
+                ["lsof", "-ti", f":{port}"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+
+            pids = result.stdout.strip().split("\n")
+            pids = [pid for pid in pids if pid]  # Filter empty strings
+
+            if pids:
+                for pid in pids:
+                    try:
+                        os.kill(int(pid), signal.SIGTERM)
+                        print(f"🛑 Stopped API server process (PID: {pid})")
+                    except (ProcessLookupError, ValueError) as e:
+                        print(f"⚠️  Failed to stop PID {pid}: {e}")
+                print("✅ API server stopped")
+            else:
+                print(f"ℹ️  No API server found running on port {port}")
+
+    except FileNotFoundError as e:
+        print(f"❌ Required command not found: {e}")
+        print("To stop manually, find the process using the port:")
+        if system == "Windows":
+            print(f"  netstat -ano | findstr :{port}")
+            print("  taskkill /F /PID <PID>")
+        else:
+            print(f"  lsof -ti :{port}")
+            print("  kill -9 <PID>")
+    except subprocess.TimeoutExpired:
+        print(f"❌ Timeout while trying to stop server on port {port}")
+    except Exception as e:
+        print(f"❌ Error stopping server: {e}")
+
+
+def main() -> None:
+    """
+    CLI entry point for API server commands.
+
+    Example:
+        $ gaia api start
+        $ gaia api start --host 0.0.0.0 --port 8000 --background
+        $ gaia api status
+        $ gaia api stop
+    """
+    parser = argparse.ArgumentParser(description="GAIA OpenAI-compatible API server")
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # Start command
+    start_parser = subparsers.add_parser("start", help="Start API server")
+    start_parser.add_argument(
+        "--host", default="localhost", help="Host to bind to (default: localhost)"
+    )
+    start_parser.add_argument(
+        "--port", type=int, default=8080, help="Port to bind to (default: 8080)"
+    )
+    start_parser.add_argument(
+        "--background", action="store_true", help="Run in background"
+    )
+    start_parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    start_parser.add_argument(
+        "--show-prompts",
+        action="store_true",
+        help="Display prompts sent to LLM",
+    )
+    start_parser.add_argument(
+        "--streaming",
+        action="store_true",
+        help="Enable real-time streaming of LLM responses",
+    )
+    start_parser.add_argument(
+        "--step-through",
+        action="store_true",
+        help="Enable step-through debugging mode (pause at each agent step)",
+    )
+
+    # Status command
+    subparsers.add_parser("status", help="Check server status")
+
+    # Stop command
+    stop_parser = subparsers.add_parser("stop", help="Stop server")
+    stop_parser.add_argument(
+        "--port", type=int, default=8080, help="Port number (default: 8080)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        start_server(
+            args.host,
+            args.port,
+            args.background,
+            getattr(args, "debug", False),
+            getattr(args, "show_prompts", False),
+            getattr(args, "streaming", False),
+            getattr(args, "step_through", False),
+        )
+    elif args.command == "status":
+        check_status()
+    elif args.command == "stop":
+        stop_server(getattr(args, "port", 8080))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()