aeonic-agentguard-sdk-python 0.1.0__py3-none-any.whl

aeonic/core/introspection.py

@@ -0,0 +1,468 @@
+"""
+Route Introspection - Discover and register agent routes at SDK initialization.
+
+This module implements deferred route introspection for FastAPI and Django,
+allowing the SDK to discover all agent routes before any requests are made.
+"""
+
+import logging
+from typing import Any, Optional
+
+from aeonic.core.types import AgentContext
+
+logger = logging.getLogger("aeonic")
+
+
+def introspect_routes(app: Any) -> None:
+    """
+    Introspect routes from FastAPI or Django app and register agents.
+
+    This function:
+    - Detects the framework automatically
+    - Walks the route/URL pattern registry
+    - Matches routes to agent metadata
+    - Registers all discovered agents
+
+    Args:
+        app: FastAPI or Django app instance (None for Django auto-detection)
+    """
+    try:
+        framework = _detect_framework(app)
+
+        if framework == "fastapi":
+            if app is None:
+                logger.warning("[Aeonic] FastAPI introspection requires app instance")
+                return
+            _introspect_fastapi_routes(app)
+        elif framework == "django":
+            # Django can introspect even without app (uses get_resolver())
+            _introspect_django_routes(app)
+        else:
+            # Try Django as fallback if app is None
+            if app is None:
+                try:
+                    import django  # noqa: F401
+
+                    _introspect_django_routes(None)
+                except ImportError:
+                    logger.warning("[Aeonic] Unknown framework - cannot introspect routes")
+            else:
+                logger.warning("[Aeonic] Unknown framework - cannot introspect routes")
+
+    except Exception as e:
+        logger.warning(f"[Aeonic] Route introspection failed: {e}")
+        import traceback
+
+        logger.error(f"[Aeonic] Traceback: {traceback.format_exc()}")
+
+
+def _detect_framework(app: Any) -> Optional[str]:
+    """
+    Detect framework type from app instance.
+
+    Args:
+        app: Application instance
+
+    Returns:
+        "fastapi", "django", or None if unknown
+    """
+    # FastAPI detection
+    if hasattr(app, "routes") or hasattr(app, "router"):
+        return "fastapi"
+
+    # Django detection
+    if hasattr(app, "url_patterns") or hasattr(app, "urlpatterns"):
+        return "django"
+
+    # Try to detect Django by checking if it's a module with get_resolver
+    try:
+        from django.urls import get_resolver  # noqa: F401
+
+        # If app is a Django URLConf module
+        if hasattr(app, "__name__"):
+            return "django"
+    except ImportError:
+        pass
+
+    return None
+
+
+def _introspect_fastapi_routes(app: Any) -> None:
+    """
+    Introspect FastAPI routes and register agents.
+
+    FastAPI stores routes in app.routes or app.router.routes.
+    Each route has: path, methods, endpoint (handler function), and dependencies.
+
+    For FastAPI, we need to check the route's dependencies list to find with_agent() calls.
+
+    Args:
+        app: FastAPI app instance
+    """
+    try:
+        from aeonic.adapters.fastapi import get_agent_metadata
+        from aeonic.core.agent_registry import register_agent
+        from aeonic.core.init import get_config
+
+        # Get routes
+        routes = getattr(app, "routes", None)
+        if routes is None and hasattr(app, "router"):
+            routes = getattr(app.router, "routes", [])
+
+        if not routes:
+            logger.warning("[Aeonic] No routes found - routes may not have been added yet.")
+            logger.warning(
+                "[Aeonic] ⚠️  Ensure routes are defined before init() runs, or increase introspection_delay_ms."
+            )
+            logger.info(
+                "[Aeonic] ℹ️  Agents will be tracked at runtime on first request (fallback mode)."
+            )
+            return
+
+        config = get_config()
+        service_name = config.get("service_name")
+        agent_count = 0
+
+        for route in routes:
+            # Skip non-APIRoute routes (like Mount, etc.)
+            if not hasattr(route, "endpoint"):
+                continue
+
+            # Skip FastAPI auto-generated routes by checking route type
+            route_type = type(route).__name__
+            if route_type not in ["APIRoute", "APIRouter"]:
+                # Skip Mount, StaticFiles, etc.
+                continue
+
+            # Get route path first - FastAPI routes have 'path' attribute
+            route_path = getattr(route, "path", None)
+            if route_path is None:
+                # Try alternative attribute names
+                route_path = getattr(route, "path_regex", None)
+                if route_path:
+                    # Convert regex pattern to path (remove ^$ and regex syntax)
+                    import re
+
+                    route_path = re.sub(r"^\^|\$$", "", str(route_path))
+                    route_path = re.sub(r"\\", "", route_path)
+                else:
+                    # Try to get from path_operation
+                    if hasattr(route, "path_operation"):
+                        route_path = getattr(route.path_operation, "path", None)
+                    if route_path is None:
+                        route_path = ""
+
+            # Check if this route has dependencies
+            agent_context: Optional[AgentContext] = None
+
+            # Try to get dependencies from the route
+            if hasattr(route, "dependant") and hasattr(route.dependant, "dependencies"):
+                # Check each dependency for agent metadata
+                for i, dep in enumerate(route.dependant.dependencies):
+                    if hasattr(dep, "call"):
+                        agent_context = get_agent_metadata(dep.call)
+                        if agent_context:
+                            break
+                        else:
+                            # Fallback: try to find metadata by checking closure
+                            # FastAPI might wrap the dependency, so function IDs don't match
+                            if hasattr(dep.call, "__closure__") and dep.call.__closure__:
+                                for cell_idx, cell in enumerate(dep.call.__closure__):
+                                    try:
+                                        value = cell.cell_contents
+                                        # Check if closure contains our agent context (with source key)
+                                        if isinstance(value, dict):
+                                            if value.get("source") == "manual":
+                                                agent_context = value  # type: ignore[assignment]
+                                                break
+                                            # Also check for agent dict by keys (name, type, model)
+                                            # The closure might have the original agent dict without 'source'
+                                            if (
+                                                "name" in value
+                                                and "type" in value
+                                                and "model" in value
+                                            ):
+                                                # This looks like an agent context - add source and use it
+                                                agent_context = {
+                                                    **value,
+                                                    "source": "manual",
+                                                }  # type: ignore[assignment]
+                                                break
+                                        # Check if closure contains a function with our metadata
+                                        if callable(value) and hasattr(
+                                            value, "__aeonic_metadata__"
+                                        ):
+                                            agent_context = getattr(value, "__aeonic_metadata__")  # type: ignore[assignment]
+                                            break
+                                    except (ValueError, AttributeError) as e:
+                                        logger.error(
+                                            f"[Aeonic] Could not inspect closure cell {cell_idx}: {e}"
+                                        )
+                                        continue
+                                if agent_context:
+                                    break
+
+            # Also try checking the endpoint directly (in case it's decorated)
+            if not agent_context:
+                agent_context = get_agent_metadata(route.endpoint)
+                # if not agent_context:
+                #     logger.warning("[Aeonic] ✗ No metadata found in endpoint")
+
+            if not agent_context:
+                # No agent metadata found - skip this route
+                # Only routes with with_agent() should be registered
+                # logger.warning(
+                #     f"[Aeonic] Skipping route {route_path} - no agent metadata found (route does not use with_agent())"
+                # )
+                continue
+
+            # Filter out FastAPI auto-generated routes
+            if route_path in ["/openapi.json", "/docs", "/redoc", "/openapi.yaml"]:
+                logger.warning(f"[Aeonic] Skipping auto-generated FastAPI route: {route_path}")
+                continue
+
+            # Get route methods (FastAPI routes have a methods attribute)
+            methods = getattr(route, "methods", None)
+            if methods is None:
+                # Try to get from path_operation
+                if hasattr(route, "path_operation"):
+                    methods = getattr(route.path_operation, "methods", None)
+                if methods is None:
+                    methods = {"GET"}  # Default
+
+            # Convert methods to list if it's a set
+            if isinstance(methods, set):
+                methods = list(methods)
+            elif not isinstance(methods, (list, tuple)):
+                methods = [methods] if methods else ["GET"]
+
+            # Register agent for each HTTP method
+            for method in methods:
+                # Convert to string and uppercase
+                method = str(method).upper()
+
+                # Skip HEAD and OPTIONS if they're auto-generated
+                if method in ["HEAD", "OPTIONS"]:
+                    continue
+
+                register_agent(
+                    name=agent_context.get("name", ""),
+                    agent_type=agent_context.get("type"),
+                    model=agent_context.get("model"),
+                    route_path=route_path,
+                    http_method=method,
+                    framework="fastapi",
+                    service_name=service_name,
+                )
+
+                agent_count += 1
+
+        if agent_count == 0:
+            logger.warning("[Aeonic] No agent routes found during introspection")
+
+    except Exception as e:
+        logger.warning(f"[Aeonic] FastAPI introspection failed: {e}")
+
+
+def _introspect_django_routes(app: Any) -> None:
+    """
+    Introspect Django URL patterns and register agents.
+
+    Django stores URL patterns in urlpatterns, accessible via get_resolver().
+    We need to walk the pattern tree recursively to handle include() patterns.
+
+    Args:
+        app: Django app instance (or URLConf module, or None for auto-detection)
+    """
+    try:
+        from django.urls import get_resolver
+
+        from aeonic.adapters.django import get_agent_metadata
+        from aeonic.core.agent_registry import register_agent
+        from aeonic.core.init import get_config
+
+        resolver = get_resolver()
+        config = get_config()
+        service_name = config.get("service_name")
+
+        agent_count = [0]  # Use list to allow mutation in nested function
+
+        def walk_url_patterns(patterns: Any, prefix: str = "") -> None:
+            """Recursively walk URL patterns."""
+            for pattern in patterns:
+                try:
+                    # Handle nested patterns (include())
+                    if hasattr(pattern, "url_patterns"):
+                        # Get the pattern prefix
+                        pattern_str = str(pattern.pattern) if hasattr(pattern, "pattern") else ""
+                        walk_url_patterns(pattern.url_patterns, prefix + pattern_str)
+                    else:
+                        # Individual route
+                        pattern_str = str(pattern.pattern) if hasattr(pattern, "pattern") else ""
+                        path = prefix + pattern_str
+
+                        # Get the view callback
+                        if not hasattr(pattern, "callback") or pattern.callback is None:
+                            continue
+
+                        # Try to get agent metadata
+                        agent_context = get_agent_metadata(pattern.callback)
+                        if not agent_context:
+                            continue
+
+                        # Django doesn't store HTTP methods in URL patterns
+                        # We need to check the view's allowed methods
+                        methods = _get_view_methods(pattern.callback)
+
+                        # If no methods found, skip this view (methods must be explicitly defined)
+                        if not methods:
+                            continue
+
+                        for method in methods:
+                            register_agent(
+                                name=agent_context.get("name", ""),
+                                agent_type=agent_context.get("type"),
+                                model=agent_context.get("model"),
+                                route_path=(f"/{path}" if not path.startswith("/") else path),
+                                http_method=method,
+                                framework="django",
+                                service_name=service_name,
+                            )
+
+                            agent_count[0] += 1
+
+                except Exception as e:
+                    # Skip problematic patterns
+                    logger.error(f"[Aeonic] Skipped pattern: {e}")
+                    continue
+
+        # Start walking from root patterns
+        url_patterns = resolver.url_patterns
+        if not url_patterns:
+            logger.warning("[Aeonic] No URL patterns found")
+            return
+
+        walk_url_patterns(url_patterns)
+
+        if agent_count[0] == 0:
+            logger.warning("[Aeonic] No agent routes found during introspection")
+
+    except ImportError:
+        logger.error("[Aeonic] Django not installed - cannot introspect Django routes")
+    except Exception as e:
+        logger.error(f"[Aeonic] Django introspection failed: {e}")
+
+
+def _get_view_methods(view_func: Any) -> list:
+    """
+    Get HTTP methods supported by a Django view.
+
+    Args:
+        view_func: Django view function or class
+
+    Returns:
+        List of HTTP methods (e.g., ["GET", "POST"])
+        Returns empty list if methods cannot be determined (only registers explicitly defined methods)
+    """
+    try:
+        # Function-based view - check if it has http_method_names attribute
+        # (This is set by decorators like @require_http_methods)
+        if hasattr(view_func, "http_method_names"):
+            methods = [
+                m.upper()
+                for m in view_func.http_method_names
+                if m.lower() not in ["head", "options"]
+            ]
+            if methods:
+                return methods
+
+        # Class-based view - check the view class
+        if hasattr(view_func, "view_class"):
+            view_class = view_func.view_class
+            if hasattr(view_class, "http_method_names"):
+                methods = [
+                    m.upper()
+                    for m in view_class.http_method_names
+                    if m.lower() not in ["head", "options"]
+                ]
+                if methods:
+                    return methods
+
+        # Check for as_view (CBV)
+        if hasattr(view_func, "cls"):
+            cls = view_func.cls
+            if hasattr(cls, "http_method_names"):
+                methods = [
+                    m.upper() for m in cls.http_method_names if m.lower() not in ["head", "options"]
+                ]
+                if methods:
+                    return methods
+
+        # Try to check if view has method restrictions via decorators
+        # Check for @require_http_methods or similar decorators
+        if hasattr(view_func, "__wrapped__"):
+            # Check the wrapped function (might have method restrictions)
+            wrapped = view_func.__wrapped__
+            if hasattr(wrapped, "http_method_names"):
+                methods = [
+                    m.upper()
+                    for m in wrapped.http_method_names
+                    if m.lower() not in ["head", "options"]
+                ]
+                if methods:
+                    return methods
+
+        # For function-based views without explicit method restrictions,
+        # try to infer methods from the view's code
+        # Check if view uses request.POST, request.body (POST) or request.GET (GET)
+        try:
+            import inspect
+
+            # Get the actual function (unwrap decorators)
+            actual_func = view_func
+            while hasattr(actual_func, "__wrapped__"):
+                actual_func = actual_func.__wrapped__
+
+            # Get source code
+            try:
+                source = inspect.getsource(actual_func)
+                methods = []
+
+                # Check for POST indicators
+                if (
+                    "request.POST" in source
+                    or "request.body" in source
+                    or "request.method" in source
+                    and "POST" in source
+                ):
+                    methods.append("POST")
+
+                # Check for GET indicators
+                if "request.GET" in source or (
+                    "request.method" in source and "GET" in source and "POST" not in source
+                ):
+                    # Only add GET if POST wasn't found (to avoid both)
+                    if "POST" not in methods:
+                        methods.append("GET")
+
+                if methods:
+                    return [m.upper() for m in methods]
+            except (OSError, TypeError):
+                # Can't get source code (might be C extension or other)
+                pass
+        except Exception:
+            pass
+
+        # If we still can't determine, return empty list
+        # Users should use @require_http_methods(['POST']) to explicitly define methods
+        logger.warning(
+            f"[Aeonic] Could not determine HTTP methods for view {getattr(view_func, '__name__', 'unknown')}. "
+            f"Use @require_http_methods(['POST']) decorator to explicitly define supported methods. "
+            f"Skipping method registration for this view."
+        )
+        return []
+
+    except Exception as e:
+        logger.error(f"[Aeonic] Error determining view methods: {e}")
+        # Return empty list - be conservative
+        return []