btech-agent-lab 1.9.0__py3-none-any.whl

agent_lab/__init__.py

@@ -0,0 +1,52 @@
+"""Agent-Lab: a framework for building AI agent applications with FastAPI.
+
+Public surface for downstream apps:
+
+- ``create_app`` / ``RouterMount`` — assemble the FastAPI application.
+- ``Container`` — subclass to add providers (services, MCP registrars, ...).
+- ``RegisterAgent`` — decorate AgentBase subclasses; discovered via
+  ``create_app(scan_packages=[...])`` or ``agent_lab.agents`` entry points.
+- ``ConfigSource`` — supply configuration from YAML, Vault, or a custom source.
+"""
+
+from agent_lab.app_factory import RouterMount, bind_agent_registry, create_app
+from agent_lab.core.config import (
+    ConfigSource,
+    VaultConfigSource,
+    YamlConfigSource,
+    default_config_source,
+)
+from agent_lab.core.container import Container
+from agent_lab.infrastructure.metrics.tracing_backends import TracingBackend
+from agent_lab.interface.mcp.registrar import McpRegistrar
+from agent_lab.services.agent_types.base import (
+    AgentBase,
+    AgentUtils,
+    ContactSupportAgentBase,
+    SupervisedWorkflowAgentBase,
+    WebAgentBase,
+    WorkflowAgentBase,
+)
+from agent_lab.services.agent_types.registration import RegisterAgent
+from agent_lab.services.agent_types.registry import AgentRegistry
+
+__all__ = [
+    "AgentBase",
+    "AgentRegistry",
+    "AgentUtils",
+    "ConfigSource",
+    "ContactSupportAgentBase",
+    "Container",
+    "McpRegistrar",
+    "RegisterAgent",
+    "RouterMount",
+    "SupervisedWorkflowAgentBase",
+    "TracingBackend",
+    "VaultConfigSource",
+    "WebAgentBase",
+    "WorkflowAgentBase",
+    "YamlConfigSource",
+    "bind_agent_registry",
+    "create_app",
+    "default_config_source",
+]

agent_lab/app_factory.py

@@ -0,0 +1,350 @@
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from importlib import resources
+from urllib.parse import urlencode
+
+from dependency_injector import providers
+from fastapi import APIRouter, FastAPI, HTTPException, Request
+from starlette.middleware.cors import CORSMiddleware
+from starlette.responses import FileResponse, JSONResponse
+from starlette.staticfiles import StaticFiles
+from typing_extensions import List, Optional, Sequence
+
+from agent_lab.core.config import ConfigSource, default_config_source, load_config
+from agent_lab.core.container import Container
+from agent_lab.infrastructure.auth.user import map_user
+from agent_lab.infrastructure.metrics.logging_middleware import LoggingMiddleware
+from agent_lab.interface.mcp.server import build_mcp_server
+from agent_lab.services.agent_types import discovery
+from agent_lab.services.agent_types.registry import AgentRegistry
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RouterMount:
+    """A router plus the auth policy for its routes.
+
+    Patterns in ``auth_exclude_patterns`` are added to the Keycloak middleware
+    exclude list, so a mount without them defaults to authenticated.
+    """
+
+    router: APIRouter
+    prefix: str
+    tags: List[str]
+    auth_exclude_patterns: List[str] = field(default_factory=list)
+    requires_auth_enabled: bool = False
+
+
+def create_app(
+    *,
+    container: Optional[Container] = None,
+    scan_packages: Sequence[str] = (),
+    config_source: Optional[ConfigSource] = None,
+    extra_routers: Sequence[RouterMount] = (),
+    mcp_instructions: Sequence[str] = (),
+) -> FastAPI:
+    """Builds the FastAPI application (composition root).
+
+    Downstream apps pass their own container subclass instance, the packages
+    to scan for @RegisterAgent classes, a config source, extra RouterMounts,
+    and MCP instruction fragments — extension happens through these
+    parameters, never by editing library code.
+    """
+    discovery.scan_packages(scan_packages)
+    discovery.load_entry_point_agents()
+
+    container = container or Container()
+    load_config(container, config_source or default_config_source())
+    bind_agent_registry(container)
+
+    mounts = _builtin_router_mounts() + list(extra_routers)
+
+    mcp_registrars = container.mcp_registrars()
+    mcp_server = build_mcp_server(
+        container, mcp_registrars, extra_instructions=tuple(mcp_instructions)
+    )
+    mcp_app = mcp_server.http_app(path="/", stateless_http=True)
+
+    application = FastAPI(
+        title=os.getenv("SERVICE_NAME", "Agent-Lab"),
+        version=os.getenv("SERVICE_VERSION", "snapshot"),
+        dependencies=[],
+        lifespan=mcp_app.lifespan,
+    )
+    application.container = container
+
+    setup_tracing(container, application)
+    setup_auth(container, application, mounts)
+    setup_routers(container, application, mounts)
+    application.mount("/mcp", mcp_app)
+    setup_resource_metadata(container, application)
+    setup_exception_handlers(application)
+    setup_middleware(application)
+    setup_mcp_slash_rewrite(application)
+    setup_mcp_authorize_resource_rewrite(container, application)
+    setup_static(container, application)
+
+    return application
+
+
+def bind_agent_registry(container: Container) -> None:
+    """Binds the agent registry to a live container instance.
+
+    create_app() calls this automatically; call it directly only when using a
+    Container outside the app factory (tests, notebooks, scripts). The
+    registry resolves each agent's extra_deps off the live container
+    instance; providers.Self() breaks under container subclassing, so the
+    binding happens at the composition root.
+    """
+    container.agent_registry.override(
+        providers.Singleton(AgentRegistry, container=container)
+    )
+
+
+def _builtin_router_mounts() -> List[RouterMount]:
+    from agent_lab.interface.api.agents.endpoints import router as agents_router
+    from agent_lab.interface.api.attachments.endpoints import (
+        router as attachments_router,
+    )
+    from agent_lab.interface.api.auth.endpoints import router as auth_router
+    from agent_lab.interface.api.integrations.endpoints import (
+        router as integrations_router,
+    )
+    from agent_lab.interface.api.language_models.endpoints import (
+        router as language_models_router,
+    )
+    from agent_lab.interface.api.messages.endpoints import router as messages_router
+    from agent_lab.interface.api.status.endpoints import router as status_router
+
+    return [
+        RouterMount(auth_router, "/auth", ["auth"], requires_auth_enabled=True),
+        RouterMount(agents_router, "/agents", ["agents"]),
+        RouterMount(attachments_router, "/attachments", ["attachments"]),
+        RouterMount(integrations_router, "/integrations", ["integrations"]),
+        RouterMount(language_models_router, "/llms", ["llms"]),
+        RouterMount(messages_router, "/messages", ["messages"]),
+        RouterMount(status_router, "/status", ["status"]),
+    ]
+
+
+def setup_auth(container, application, mounts: List[RouterMount]):
+    config = container.config()
+    if config["auth"]["enabled"]:
+        from fastapi_keycloak_middleware import (
+            KeycloakConfiguration,
+            setup_keycloak_middleware,
+        )
+
+        keycloak_config = KeycloakConfiguration(
+            url=config["auth"]["url"],
+            realm=config["auth"]["realm"],
+            client_id=config["auth"]["client_id"],
+            client_secret=config["auth"]["client_secret"],
+        )
+
+        exclude_patterns = [
+            "/auth/login(/|$)",
+            "/auth/renew(/|$)",
+            "/auth/exchange(/|$)",
+            "/openapi.json(/|$)",
+            "/status/",
+            ".*well-known/",
+            "/mcp(/.*)?$",
+            "/static/",
+        ]
+        for mount in mounts:
+            exclude_patterns.extend(mount.auth_exclude_patterns)
+
+        setup_keycloak_middleware(
+            application,
+            keycloak_configuration=keycloak_config,
+            exclude_patterns=exclude_patterns,
+            user_mapper=map_user,
+        )
+
+    else:
+        logger.warning("Authentication disabled")
+
+
+def setup_resource_metadata(container: Container, application: FastAPI):
+    config = container.config()
+    if not config["auth"]["enabled"]:
+        return
+
+    base_url = config["api_base_url"]
+    authorization_server = f"{base_url}/mcp"
+
+    def build_resource_metadata(request: Request) -> dict:
+        user_agent = request.headers.get("user-agent") or ""
+        resource = base_url if not user_agent else f"{base_url}/mcp"
+        return {
+            "resource": resource,
+            "authorization_servers": [authorization_server],
+            "scopes_supported": ["openid", "profile", "email"],
+            "bearer_methods_supported": ["header"],
+        }
+
+    @application.get("/.well-known/oauth-protected-resource/mcp")
+    async def oauth_protected_resource_metadata(request: Request):
+        return JSONResponse(build_resource_metadata(request))
+
+    @application.get("/.well-known/oauth-protected-resource/mcp/")
+    async def oauth_protected_resource_metadata_slash(request: Request):
+        return JSONResponse(build_resource_metadata(request))
+
+    auth_server_metadata = {
+        "issuer": authorization_server,
+        "authorization_endpoint": f"{authorization_server}/authorize",
+        "token_endpoint": f"{authorization_server}/token",
+        "registration_endpoint": f"{authorization_server}/register",
+        "scopes_supported": ["openid", "profile", "email"],
+        "response_types_supported": ["code"],
+        "grant_types_supported": ["authorization_code", "refresh_token"],
+        "token_endpoint_auth_methods_supported": [
+            "client_secret_post",
+            "client_secret_basic",
+        ],
+        "code_challenge_methods_supported": ["S256"],
+    }
+
+    @application.get("/.well-known/oauth-authorization-server/mcp")
+    async def oauth_authorization_server_metadata():
+        return JSONResponse(auth_server_metadata)
+
+    @application.get("/.well-known/oauth-authorization-server/mcp/")
+    async def oauth_authorization_server_metadata_slash():
+        return JSONResponse(auth_server_metadata)
+
+
+def setup_routers(
+    container: Container, application: FastAPI, mounts: List[RouterMount]
+):
+    config = container.config()
+    for mount in mounts:
+        if mount.requires_auth_enabled and not config["auth"]["enabled"]:
+            continue
+        application.include_router(mount.router, prefix=mount.prefix, tags=mount.tags)
+
+
+def setup_exception_handlers(application: FastAPI):
+    @application.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException):
+        match = re.match(r"^(\d+):", exc.detail)
+        if match:
+            status_code = int(match.group(1))
+            detail = exc.detail[len(match.group(0)) :].strip()
+        else:
+            status_code = exc.status_code
+            detail = exc.detail
+
+        return JSONResponse(
+            status_code=status_code,
+            content={"detail": detail},
+        )
+
+
+def setup_tracing(container: Container, application: FastAPI):
+    tracer = container.tracer()
+    tracer.setup(application)
+
+
+def setup_middleware(application: FastAPI):
+    application.add_middleware(
+        LoggingMiddleware,
+    )
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+def setup_mcp_slash_rewrite(application: FastAPI):
+    @application.middleware("http")
+    async def mcp_slash_rewrite(request: Request, call_next):
+        if request.url.path == "/mcp":
+            scope = request.scope
+            scope["path"] = "/mcp/"
+            scope["raw_path"] = b"/mcp/"
+        return await call_next(request)
+
+
+def setup_mcp_authorize_resource_rewrite(container: Container, application: FastAPI):
+    config = container.config()
+    if not config["auth"]["enabled"]:
+        return
+
+    bare = config["api_base_url"].rstrip("/")
+    target = f"{bare}/mcp"
+
+    def is_bare(value: str) -> bool:
+        return value.rstrip("/") == bare
+
+    @application.middleware("http")
+    async def mcp_authorize_resource_rewrite(request: Request, call_next):
+        if request.url.path == "/mcp/authorize":
+            items = list(request.query_params.multi_items())
+            if any(k == "resource" and is_bare(v) for k, v in items):
+                rewritten = [
+                    (k, target if (k == "resource" and is_bare(v)) else v)
+                    for k, v in items
+                ]
+                request.scope["query_string"] = urlencode(rewritten).encode("ascii")
+        return await call_next(request)
+
+
+def setup_static(container: Container, application: FastAPI):
+    _setup_branding(application)
+    _setup_spa_fallback(container, application)
+
+
+def _setup_spa_fallback(container: Container, application: FastAPI):
+    """Serves a static site (e.g. a SPA build) from a configured directory.
+
+    Gated behind the optional ``static.enabled`` config key and a no-op by
+    default. The 404→index fallback fires on any HTML-accepting 404 site-wide,
+    which is only correct for ``mount_path: "/"`` (the default). A configured
+    but missing directory fails fast at boot.
+    """
+    static_config = container.config().get("static") or {}
+    if not static_config.get("enabled", False):
+        return
+
+    directory = static_config["directory"]
+    index_file = os.path.join(directory, static_config.get("index_file", "index.html"))
+
+    @application.middleware("http")
+    async def spa_fallback(request: Request, call_next):
+        response = await call_next(request)
+        accept = request.headers.get("accept", "")
+        if response.status_code == 404 and "text/html" in accept:
+            return FileResponse(index_file)
+        return response
+
+    application.mount(
+        path=static_config.get("mount_path", "/"),
+        app=StaticFiles(directory=directory, html=True),
+        name="static",
+    )
+
+
+def _setup_branding(application: FastAPI):
+    # Resolved via importlib.resources so the logo is found when agent_lab is
+    # an installed wheel, independent of the process working directory.
+    logo_file = str(resources.files("agent_lab").joinpath("static", "logo.svg"))
+
+    # Cache-Control is set on the FileResponse directly: FastAPI only merges
+    # dependency-set headers (e.g. cache_control()) into non-Response returns.
+    @application.get("/static/logo.svg")
+    async def logo() -> FileResponse:
+        return FileResponse(
+            logo_file,
+            media_type="image/svg+xml",
+            headers={"Cache-Control": "public, max-age=86400, s-maxage=86400"},
+        )

agent_lab/core/config.py

@@ -0,0 +1,86 @@
+import os
+from abc import ABC, abstractmethod
+
+
+class ConfigSource(ABC):
+    """Strategy for loading the application configuration dictionary.
+
+    Downstream apps provide their own subclass (or wrap these) to add keys or
+    use a different secrets backend, and pass it to ``create_app(config_source=...)``.
+    """
+
+    @abstractmethod
+    def load(self) -> dict:
+        pass
+
+
+class YamlConfigSource(ConfigSource):
+    def __init__(self, path: str):
+        self.path = path
+
+    def load(self) -> dict:
+        import yaml
+
+        with open(self.path) as config_file:
+            return yaml.safe_load(config_file)
+
+
+class VaultConfigSource(ConfigSource):
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        engine_path: str = "secret",
+        secret_path: str = "app_secrets",
+    ):
+        self.url = url
+        self.token = token
+        self.engine_path = engine_path
+        self.secret_path = secret_path
+
+    def load(self) -> dict:
+        import hvac
+
+        client = hvac.Client(url=self.url, token=self.token, verify=False)
+        app_secrets = client.secrets.kv.read_secret_version(
+            raise_on_deleted_version=False,
+            path=self.secret_path,
+            mount_point=self.engine_path,
+        )["data"]["data"]
+        return {
+            "api_base_url": app_secrets["api_base_url"],
+            "cdp_url": app_secrets["cdp_url"],
+            "auth": {
+                "enabled": app_secrets["auth_enabled"],
+                "url": app_secrets["auth_url"],
+                "realm": app_secrets["auth_realm"],
+                "client_id": app_secrets["auth_client_id"],
+                "client_secret": app_secrets["auth_client_secret"],
+            },
+            "vault": {"url": self.url, "token": self.token},
+            "broker": {"url": app_secrets["broker_url"]},
+            "db": {
+                "url": app_secrets["db_url"],
+                "vectors": app_secrets["db_vectors"],
+                "checkpoints": app_secrets["db_checkpoints"],
+            },
+        }
+
+
+def default_config_source() -> ConfigSource:
+    if os.getenv("DOCKER"):
+        return YamlConfigSource("config-docker.yml")
+    if os.getenv("TESTING"):
+        return YamlConfigSource("config-test.yml")
+    if os.getenv("DEVELOPING"):
+        return YamlConfigSource("config-dev.yml")
+    return VaultConfigSource(
+        url=os.getenv("VAULT_URL"),
+        token=os.getenv("VAULT_TOKEN"),
+        engine_path=os.getenv("VAULT_ENGINE_PATH", "secret"),
+        secret_path=os.getenv("VAULT_SECRET_PATH", "app_secrets"),
+    )
+
+
+def load_config(container, source: ConfigSource) -> None:
+    container.config.from_dict(source.load())