agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/os/routers/components/components.py

@@ -0,0 +1,475 @@
+import logging
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query
+
+from agno.db.base import AsyncBaseDb, BaseDb
+from agno.db.base import ComponentType as DbComponentType
+from agno.os.auth import get_authentication_dependency
+from agno.os.schema import (
+    BadRequestResponse,
+    ComponentConfigResponse,
+    ComponentCreate,
+    ComponentResponse,
+    ComponentType,
+    ComponentUpdate,
+    ConfigCreate,
+    ConfigUpdate,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    PaginatedResponse,
+    PaginationInfo,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
+from agno.os.settings import AgnoAPISettings
+from agno.registry import Registry
+from agno.utils.log import log_error, log_warning
+from agno.utils.string import generate_id_from_name
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_db_in_config(
+    config: Dict[str, Any],
+    os_db: BaseDb,
+    registry: Optional[Registry] = None,
+) -> Dict[str, Any]:
+    """
+    Resolve db reference in config by looking up in registry or OS db.
+
+    If config contains a db dict with an id, this function will:
+    1. Check if the id matches the OS db
+    2. Check if the id exists in the registry
+    3. Convert the found db to a dict for serialization
+
+    Args:
+        config: The config dict that may contain a db reference
+        os_db: The OS database instance
+        registry: Optional registry containing registered databases
+
+    Returns:
+        Updated config dict with resolved db
+    """
+    component_db = config.get("db")
+    if component_db is not None and isinstance(component_db, dict):
+        component_db_id = component_db.get("id")
+        if component_db_id is not None:
+            resolved_db = None
+            # First check if it matches the OS db
+            if component_db_id == os_db.id:
+                resolved_db = os_db
+            # Then check the registry
+            elif registry is not None:
+                resolved_db = registry.get_db(component_db_id)
+
+            # Store the full db dict for serialization
+            if resolved_db is not None:
+                config["db"] = resolved_db.to_dict()
+            else:
+                log_error(f"Could not resolve db with id: {component_db_id}")
+    elif component_db is None and "db" in config:
+        # Explicitly set to None, remove the key
+        config.pop("db", None)
+
+    return config
+
+
+def get_components_router(
+    os_db: Union[BaseDb, AsyncBaseDb],
+    settings: AgnoAPISettings = AgnoAPISettings(),
+    registry: Optional[Registry] = None,
+) -> APIRouter:
+    """Create components router."""
+    router = APIRouter(
+        dependencies=[Depends(get_authentication_dependency(settings))],
+        tags=["Components"],
+        responses={
+            400: {"description": "Bad Request", "model": BadRequestResponse},
+            401: {"description": "Unauthorized", "model": UnauthenticatedResponse},
+            404: {"description": "Not Found", "model": NotFoundResponse},
+            422: {"description": "Validation Error", "model": ValidationErrorResponse},
+            500: {"description": "Internal Server Error", "model": InternalServerErrorResponse},
+        },
+    )
+    return attach_routes(router=router, os_db=os_db, registry=registry)
+
+
+def attach_routes(
+    router: APIRouter, os_db: Union[BaseDb, AsyncBaseDb], registry: Optional[Registry] = None
+) -> APIRouter:
+    # Component routes require sync database
+    if not isinstance(os_db, BaseDb):
+        raise ValueError("Component routes require a sync database (BaseDb), not an async database.")
+    db: BaseDb = os_db  # Type narrowed after isinstance check
+
+    @router.get(
+        "/components",
+        response_model=PaginatedResponse[ComponentResponse],
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="list_components",
+        summary="List Components",
+        description="Retrieve a paginated list of components with optional filtering by type.",
+    )
+    async def list_components(
+        component_type: Optional[ComponentType] = Query(None, description="Filter by type: agent, team, workflow"),
+        page: int = Query(1, ge=1, description="Page number"),
+        limit: int = Query(20, ge=1, le=100, description="Items per page"),
+    ) -> PaginatedResponse[ComponentResponse]:
+        try:
+            start_time_ms = time.time() * 1000
+            offset = (page - 1) * limit
+
+            components, total_count = db.list_components(
+                component_type=DbComponentType(component_type.value) if component_type else None,
+                limit=limit,
+                offset=offset,
+            )
+
+            total_pages = (total_count + limit - 1) // limit if limit > 0 else 0
+
+            return PaginatedResponse(
+                data=[ComponentResponse(**c) for c in components],
+                meta=PaginationInfo(
+                    page=page,
+                    limit=limit,
+                    total_pages=total_pages,
+                    total_count=total_count,
+                    search_time_ms=round(time.time() * 1000 - start_time_ms, 2),
+                ),
+            )
+        except Exception as e:
+            log_error(f"Error listing components: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=201,
+        operation_id="create_component",
+        summary="Create Component",
+        description="Create a new component (agent, team, or workflow) with initial config.",
+    )
+    async def create_component(
+        body: ComponentCreate,
+    ) -> ComponentResponse:
+        try:
+            component_id = body.component_id
+            if component_id is None:
+                component_id = generate_id_from_name(body.name)
+
+            # TODO: Create links from config
+
+            # Prepare config - ensure it's a dict and resolve db reference
+            config = body.config or {}
+            config = _resolve_db_in_config(config, db, registry)
+
+            # Warn if creating a team without members
+            if body.component_type == ComponentType.TEAM:
+                members = config.get("members")
+                if not members or len(members) == 0:
+                    log_warning(
+                        f"Creating team '{body.name}' without members. "
+                        "If this is unintended, add members to the config."
+                    )
+
+            component, _config = db.create_component_with_config(
+                component_id=component_id,
+                component_type=DbComponentType(body.component_type.value),
+                name=body.name,
+                description=body.description,
+                metadata=body.metadata,
+                config=config,
+                label=body.label,
+                stage=body.stage or "draft",
+                notes=body.notes,
+            )
+
+            return ComponentResponse(**component)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error creating component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_component",
+        summary="Get Component",
+        description="Retrieve a component by ID.",
+    )
+    async def get_component(
+        component_id: str = Path(description="Component ID"),
+    ) -> ComponentResponse:
+        try:
+            component = db.get_component(component_id)
+            if component is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.patch(
+        "/components/{component_id}",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="update_component",
+        summary="Update Component",
+        description="Partially update a component by ID.",
+    )
+    async def update_component(
+        component_id: str = Path(description="Component ID"),
+        body: ComponentUpdate = Body(description="Component fields to update"),
+    ) -> ComponentResponse:
+        try:
+            existing = db.get_component(component_id)
+            if existing is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+
+            update_kwargs: Dict[str, Any] = {"component_id": component_id}
+            if body.name is not None:
+                update_kwargs["name"] = body.name
+            if body.description is not None:
+                update_kwargs["description"] = body.description
+            if body.metadata is not None:
+                update_kwargs["metadata"] = body.metadata
+            if body.component_type is not None:
+                update_kwargs["component_type"] = DbComponentType(body.component_type)
+
+            component = db.upsert_component(**update_kwargs)
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error updating component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.delete(
+        "/components/{component_id}",
+        status_code=204,
+        operation_id="delete_component",
+        summary="Delete Component",
+        description="Delete a component by ID.",
+    )
+    async def delete_component(
+        component_id: str = Path(description="Component ID"),
+    ) -> None:
+        try:
+            deleted = db.delete_component(component_id)
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error deleting component: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs",
+        response_model=List[ComponentConfigResponse],
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="list_configs",
+        summary="List Configs",
+        description="List all configs for a component.",
+    )
+    async def list_configs(
+        component_id: str = Path(description="Component ID"),
+        include_config: bool = Query(True, description="Include full config blob"),
+    ) -> List[ComponentConfigResponse]:
+        try:
+            configs = db.list_configs(component_id, include_config=include_config)
+            return [ComponentConfigResponse(**c) for c in configs]
+        except Exception as e:
+            log_error(f"Error listing configs: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components/{component_id}/configs",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=201,
+        operation_id="create_config",
+        summary="Create Config Version",
+        description="Create a new config version for a component.",
+    )
+    async def create_config(
+        component_id: str = Path(description="Component ID"),
+        body: ConfigCreate = Body(description="Config data"),
+    ) -> ComponentConfigResponse:
+        try:
+            # Resolve db from config if present
+            config_data = body.config or {}
+            config_data = _resolve_db_in_config(config_data, db, registry)
+
+            config = db.upsert_config(
+                component_id=component_id,
+                version=None,  # Always create new
+                config=config_data,
+                label=body.label,
+                stage=body.stage,
+                notes=body.notes,
+                links=body.links,
+            )
+            return ComponentConfigResponse(**config)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error creating config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.patch(
+        "/components/{component_id}/configs/{version}",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="update_config",
+        summary="Update Draft Config",
+        description="Update an existing draft config. Cannot update published configs.",
+    )
+    async def update_config(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+        body: ConfigUpdate = Body(description="Config fields to update"),
+    ) -> ComponentConfigResponse:
+        try:
+            # Resolve db from config if present
+            config_data = body.config
+            if config_data is not None:
+                config_data = _resolve_db_in_config(config_data, db, registry)
+
+            config = db.upsert_config(
+                component_id=component_id,
+                version=version,  # Always update existing
+                config=config_data,
+                label=body.label,
+                stage=body.stage,
+                notes=body.notes,
+                links=body.links,
+            )
+            return ComponentConfigResponse(**config)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error updating config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs/current",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_current_config",
+        summary="Get Current Config",
+        description="Get the current config version for a component.",
+    )
+    async def get_current_config(
+        component_id: str = Path(description="Component ID"),
+    ) -> ComponentConfigResponse:
+        try:
+            config = db.get_config(component_id)
+            if config is None:
+                raise HTTPException(status_code=404, detail=f"No current config for {component_id}")
+            return ComponentConfigResponse(**config)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.get(
+        "/components/{component_id}/configs/{version}",
+        response_model=ComponentConfigResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="get_config",
+        summary="Get Config Version",
+        description="Get a specific config version by number.",
+    )
+    async def get_config_version(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> ComponentConfigResponse:
+        try:
+            config = db.get_config(component_id, version=version)
+
+            if config is None:
+                raise HTTPException(status_code=404, detail=f"Config {component_id} v{version} not found")
+            return ComponentConfigResponse(**config)
+        except HTTPException:
+            raise
+        except Exception as e:
+            log_error(f"Error getting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.delete(
+        "/components/{component_id}/configs/{version}",
+        status_code=204,
+        operation_id="delete_config",
+        summary="Delete Config Version",
+        description="Delete a specific draft config version. Cannot delete published or current configs.",
+    )
+    async def delete_config_version(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> None:
+        try:
+            # Resolve version number
+            deleted = db.delete_config(component_id, version=version)
+            if not deleted:
+                raise HTTPException(status_code=404, detail=f"Config {component_id} v{version} not found")
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error deleting config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    @router.post(
+        "/components/{component_id}/configs/{version}/set-current",
+        response_model=ComponentResponse,
+        response_model_exclude_none=True,
+        status_code=200,
+        operation_id="set_current_config",
+        summary="Set Current Config Version",
+        description="Set a published config version as current (for rollback).",
+    )
+    async def set_current_config(
+        component_id: str = Path(description="Component ID"),
+        version: int = Path(description="Version number"),
+    ) -> ComponentResponse:
+        try:
+            success = db.set_current_version(component_id, version=version)
+            if not success:
+                raise HTTPException(
+                    status_code=404, detail=f"Component {component_id} or config version {version} not found"
+                )
+
+            # Fetch and return updated component
+            component = db.get_component(component_id)
+            if component is None:
+                raise HTTPException(status_code=404, detail=f"Component {component_id} not found")
+
+            return ComponentResponse(**component)
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            log_error(f"Error setting current config: {e}")
+            raise HTTPException(status_code=500, detail="Internal server error")
+
+    return router

agno/os/routers/database.py

@@ -0,0 +1,155 @@
+from typing import TYPE_CHECKING, Optional
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+)
+from fastapi.responses import JSONResponse
+from packaging import version
+
+from agno.db.base import AsyncBaseDb
+from agno.db.migrations.manager import MigrationManager
+from agno.os.auth import get_authentication_dependency
+from agno.os.schema import (
+    BadRequestResponse,
+    InternalServerErrorResponse,
+    NotFoundResponse,
+    UnauthenticatedResponse,
+    ValidationErrorResponse,
+)
+from agno.os.settings import AgnoAPISettings
+from agno.os.utils import (
+    get_db,
+)
+from agno.remote.base import RemoteDb
+from agno.utils.log import log_info
+
+if TYPE_CHECKING:
+    from agno.os.app import AgentOS
+
+
+def get_database_router(
+    os: "AgentOS",
+    settings: AgnoAPISettings = AgnoAPISettings(),
+) -> APIRouter:
+    """Create the database router with comprehensive OpenAPI documentation."""
+    router = APIRouter(
+        dependencies=[Depends(get_authentication_dependency(settings))],
+        responses={
+            400: {"description": "Bad Request", "model": BadRequestResponse},
+            401: {"description": "Unauthorized", "model": UnauthenticatedResponse},
+            404: {"description": "Not Found", "model": NotFoundResponse},
+            422: {"description": "Validation Error", "model": ValidationErrorResponse},
+            500: {"description": "Internal Server Error", "model": InternalServerErrorResponse},
+        },
+    )
+
+    async def _migrate_single_db(db, target_version: Optional[str] = None) -> None:
+        """Migrate a single database."""
+        if isinstance(db, RemoteDb):
+            log_info("Skipping logs for remote DB")
+
+        if target_version:
+            # Use the session table as proxy for the database schema version
+            if isinstance(db, AsyncBaseDb):
+                current_version = await db.get_latest_schema_version(db.session_table_name)
+            else:
+                current_version = db.get_latest_schema_version(db.session_table_name)
+
+            if version.parse(target_version) > version.parse(current_version):  # type: ignore
+                await MigrationManager(db).up(target_version)  # type: ignore
+            else:
+                await MigrationManager(db).down(target_version)  # type: ignore
+        else:
+            # If the target version is not provided, migrate to the latest version
+            await MigrationManager(db).up()  # type: ignore
+
+    @router.post(
+        "/databases/all/migrate",
+        tags=["Database"],
+        operation_id="migrate_all_databases",
+        summary="Migrate All Databases",
+        description=(
+            "Migrate all database schemas to the given target version. "
+            "If a target version is not provided, all databases will be migrated to the latest version."
+        ),
+        responses={
+            200: {
+                "description": "All databases migrated successfully",
+                "content": {
+                    "application/json": {
+                        "example": {"message": "All databases migrated successfully to version 3.0.0"},
+                    }
+                },
+            },
+            500: {"description": "Failed to migrate databases", "model": InternalServerErrorResponse},
+        },
+    )
+    async def migrate_all_databases(target_version: Optional[str] = None):
+        """Migrate all databases."""
+        all_dbs = {db.id: db for db_id, dbs in os.dbs.items() for db in dbs}
+        failed_dbs: dict[str, str] = {}
+
+        for db_id, db in all_dbs.items():
+            try:
+                await _migrate_single_db(db, target_version)
+            except Exception as e:
+                failed_dbs[db_id] = str(e)
+
+        version_msg = f"version {target_version}" if target_version else "latest version"
+        migrated_count = len(all_dbs) - len(failed_dbs)
+
+        if failed_dbs:
+            return JSONResponse(
+                content={
+                    "message": f"Migrated {migrated_count}/{len(all_dbs)} databases to {version_msg}",
+                    "failed": failed_dbs,
+                },
+                status_code=207,  # Multi-Status
+            )
+
+        return JSONResponse(
+            content={"message": f"All databases migrated successfully to {version_msg}"}, status_code=200
+        )
+
+    @router.post(
+        "/databases/{db_id}/migrate",
+        tags=["Database"],
+        operation_id="migrate_database",
+        summary="Migrate Database",
+        description=(
+            "Migrate the given database schema to the given target version. "
+            "If a target version is not provided, the database will be migrated to the latest version."
+        ),
+        responses={
+            200: {
+                "description": "Database migrated successfully",
+                "content": {
+                    "application/json": {
+                        "example": {"message": "Database migrated successfully to version 3.0.0"},
+                    }
+                },
+            },
+            404: {"description": "Database not found", "model": NotFoundResponse},
+            500: {"description": "Failed to migrate database", "model": InternalServerErrorResponse},
+        },
+    )
+    async def migrate_database(db_id: str, target_version: Optional[str] = None):
+        db = await get_db(os.dbs, db_id)
+        if not db:
+            raise HTTPException(status_code=404, detail="Database not found")
+
+        try:
+            await _migrate_single_db(db, target_version)
+
+            version_msg = f"version {target_version}" if target_version else "latest version"
+            return JSONResponse(
+                content={"message": f"Database migrated successfully to {version_msg}"}, status_code=200
+            )
+        except HTTPException:
+            raise
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Failed to migrate database: {str(e)}")
+
+    return router