agent-framework-devui 0.0.1a0__py3-none-any.whl → 1.0.0b251001__py3-none-any.whl

agent_framework_devui/__init__.py

@@ -0,0 +1,151 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent Framework DevUI - Debug interface with OpenAI compatible API server."""
+
+import importlib.metadata
+import logging
+import webbrowser
+from typing import Any
+
+from ._server import DevServer
+from .models import AgentFrameworkRequest, OpenAIError, OpenAIResponse, ResponseStreamEvent
+from .models._discovery_models import DiscoveryResponse, EntityInfo, EnvVarRequirement
+
+logger = logging.getLogger(__name__)
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+
+def serve(
+    entities: list[Any] | None = None,
+    entities_dir: str | None = None,
+    port: int = 8080,
+    host: str = "127.0.0.1",
+    auto_open: bool = False,
+    cors_origins: list[str] | None = None,
+    ui_enabled: bool = True,
+    tracing_enabled: bool = False,
+) -> None:
+    """Launch Agent Framework DevUI with simple API.
+
+    Args:
+        entities: List of entities for in-memory registration (IDs auto-generated)
+        entities_dir: Directory to scan for entities
+        port: Port to run server on
+        host: Host to bind server to
+        auto_open: Whether to automatically open browser
+        cors_origins: List of allowed CORS origins
+        ui_enabled: Whether to enable the UI
+        tracing_enabled: Whether to enable OpenTelemetry tracing
+    """
+    import re
+
+    import uvicorn
+
+    # Validate host parameter early for security
+    if not re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0|[a-zA-Z0-9.-]+)$", host):
+        raise ValueError(f"Invalid host: {host}. Must be localhost, IP address, or valid hostname")
+
+    # Validate port parameter
+    if not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError(f"Invalid port: {port}. Must be integer between 1 and 65535")
+
+    # Configure tracing environment variables if enabled
+    if tracing_enabled:
+        import os
+
+        # Only set if not already configured by user
+        if not os.environ.get("ENABLE_OTEL"):
+            os.environ["ENABLE_OTEL"] = "true"
+            logger.info("Set ENABLE_OTEL=true for tracing")
+
+        if not os.environ.get("ENABLE_SENSITIVE_DATA"):
+            os.environ["ENABLE_SENSITIVE_DATA"] = "true"
+            logger.info("Set ENABLE_SENSITIVE_DATA=true for tracing")
+
+        if not os.environ.get("OTLP_ENDPOINT"):
+            os.environ["OTLP_ENDPOINT"] = "http://localhost:4317"
+            logger.info("Set OTLP_ENDPOINT=http://localhost:4317 for tracing")
+
+    # Create server with direct parameters
+    server = DevServer(
+        entities_dir=entities_dir, port=port, host=host, cors_origins=cors_origins, ui_enabled=ui_enabled
+    )
+
+    # Register in-memory entities if provided
+    if entities:
+        logger.info(f"Registering {len(entities)} in-memory entities")
+        # Store entities for later registration during server startup
+        server._pending_entities = entities
+
+    app = server.get_app()
+
+    if auto_open:
+
+        def open_browser() -> None:
+            import http.client
+            import re
+            import time
+
+            # Validate host and port for security
+            if not re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0|[a-zA-Z0-9.-]+)$", host):
+                logger.warning(f"Invalid host for auto-open: {host}")
+                return
+
+            if not isinstance(port, int) or not (1 <= port <= 65535):
+                logger.warning(f"Invalid port for auto-open: {port}")
+                return
+
+            # Wait for server to be ready by checking health endpoint
+            browser_url = f"http://{host}:{port}"
+
+            for _ in range(30):  # 15 second timeout (30 * 0.5s)
+                try:
+                    # Use http.client for safe connection handling (standard library)
+                    conn = http.client.HTTPConnection(host, port, timeout=1)
+                    try:
+                        conn.request("GET", "/health")
+                        response = conn.getresponse()
+                        if response.status == 200:
+                            webbrowser.open(browser_url)
+                            return
+                    finally:
+                        conn.close()
+                except (http.client.HTTPException, OSError, TimeoutError):
+                    pass
+                time.sleep(0.5)
+
+            # Fallback: open browser anyway after timeout
+            webbrowser.open(browser_url)
+
+        import threading
+
+        threading.Thread(target=open_browser, daemon=True).start()
+
+    logger.info(f"Starting Agent Framework DevUI on {host}:{port}")
+    uvicorn.run(app, host=host, port=port, log_level="info")
+
+
+def main() -> None:
+    """CLI entry point for devui command."""
+    from ._cli import main as cli_main
+
+    cli_main()
+
+
+# Export main public API
+__all__ = [
+    "AgentFrameworkRequest",
+    "DevServer",
+    "DiscoveryResponse",
+    "EntityInfo",
+    "EnvVarRequirement",
+    "OpenAIError",
+    "OpenAIResponse",
+    "ResponseStreamEvent",
+    "main",
+    "serve",
+]

agent_framework_devui/_cli.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Command line interface for Agent Framework DevUI."""
+
+import argparse
+import logging
+import os
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure logging for the server."""
+    log_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    logging.basicConfig(level=getattr(logging, level.upper()), format=log_format, datefmt="%Y-%m-%d %H:%M:%S")
+
+
+def create_cli_parser() -> argparse.ArgumentParser:
+    """Create the command line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="devui",
+        description="Launch Agent Framework DevUI - Debug interface with OpenAI compatible API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  devui                             # Scan current directory
+  devui ./agents                    # Scan specific directory
+  devui --port 8000                 # Custom port
+  devui --headless                  # API only, no UI
+  devui --tracing                   # Enable OpenTelemetry tracing
+        """,
+    )
+
+    parser.add_argument(
+        "directory", nargs="?", default=".", help="Directory to scan for entities (default: current directory)"
+    )
+
+    parser.add_argument("--port", "-p", type=int, default=8080, help="Port to run server on (default: 8080)")
+
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind server to (default: 127.0.0.1)")
+
+    parser.add_argument("--no-open", action="store_true", help="Don't automatically open browser")
+
+    parser.add_argument("--headless", action="store_true", help="Run without UI (API only)")
+
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Logging level (default: INFO)",
+    )
+
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload for development")
+
+    parser.add_argument("--tracing", action="store_true", help="Enable OpenTelemetry tracing for Agent Framework")
+
+    parser.add_argument("--version", action="version", version=f"Agent Framework DevUI {get_version()}")
+
+    return parser
+
+
+def get_version() -> str:
+    """Get the package version."""
+    try:
+        from . import __version__
+
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def validate_directory(directory: str) -> str:
+    """Validate and normalize the entities directory."""
+    if not directory:
+        directory = "."
+
+    abs_dir = os.path.abspath(directory)
+
+    if not os.path.exists(abs_dir):
+        print(f"❌ Error: Directory '{directory}' does not exist", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+    if not os.path.isdir(abs_dir):
+        print(f"❌ Error: '{directory}' is not a directory", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+    return abs_dir
+
+
+def print_startup_info(entities_dir: str, host: str, port: int, ui_enabled: bool, reload: bool) -> None:
+    """Print startup information."""
+    print("🤖 Agent Framework DevUI")  # noqa: T201
+    print("=" * 50)  # noqa: T201
+    print(f"📁 Entities directory: {entities_dir}")  # noqa: T201
+    print(f"🌐 Server URL: http://{host}:{port}")  # noqa: T201
+    print(f"🎨 UI enabled: {'Yes' if ui_enabled else 'No'}")  # noqa: T201
+    print(f"🔄 Auto-reload: {'Yes' if reload else 'No'}")  # noqa: T201
+    print("=" * 50)  # noqa: T201
+    print("🔍 Scanning for entities...")  # noqa: T201
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = create_cli_parser()
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(args.log_level)
+
+    # Validate directory
+    entities_dir = validate_directory(args.directory)
+
+    # Extract parameters directly from args
+    ui_enabled = not args.headless
+
+    # Print startup info
+    print_startup_info(entities_dir, args.host, args.port, ui_enabled, args.reload)
+
+    # Import and start server
+    try:
+        from . import serve
+
+        serve(
+            entities_dir=entities_dir,
+            port=args.port,
+            host=args.host,
+            auto_open=not args.no_open,
+            ui_enabled=ui_enabled,
+            tracing_enabled=args.tracing,
+        )
+
+    except KeyboardInterrupt:
+        print("\n👋 Shutting down Agent Framework DevUI...")  # noqa: T201
+        sys.exit(0)
+    except Exception as e:
+        logger.exception("Failed to start server")
+        print(f"❌ Error: {e}", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()