aegra-api 0.1.0__py3-none-any.whl

aegra_api/config.py

@@ -0,0 +1,204 @@
+"""Configuration management for Aegra HTTP settings"""
+
+import json
+from pathlib import Path
+from typing import TypedDict
+
+import structlog
+
+from aegra_api.settings import settings
+
+logger = structlog.get_logger(__name__)
+
+
+class CorsConfig(TypedDict, total=False):
+    """CORS configuration options"""
+
+    allow_origins: list[str]
+    allow_methods: list[str]
+    allow_headers: list[str]
+    allow_credentials: bool
+    expose_headers: list[str]
+    max_age: int
+
+
+class HttpConfig(TypedDict, total=False):
+    """HTTP configuration options for custom routes"""
+
+    app: str
+    """Import path for custom Starlette/FastAPI app to mount"""
+    enable_custom_route_auth: bool
+    """Apply Aegra authentication dependency to custom routes (uses FastAPI dependencies, not middleware)"""
+    cors: CorsConfig | None
+    """Custom CORS configuration"""
+
+
+class StoreIndexConfig(TypedDict, total=False):
+    """Configuration for vector embeddings in store.
+
+    Enables semantic similarity search using pgvector.
+    See: https://github.com/ibbybuilds/aegra/issues/104
+    """
+
+    dims: int
+    """Embedding vector dimensions (e.g., 1536 for OpenAI text-embedding-3-small)"""
+    embed: str
+    """Embedding model in format '<provider>:<model-id>'
+    Examples:
+    - openai:text-embedding-3-small (1536 dims)
+    - openai:text-embedding-3-large (3072 dims)
+    - bedrock:amazon.titan-embed-text-v2:0 (1024 dims)
+    - cohere:embed-english-v3.0 (1024 dims)
+    """
+    fields: list[str] | None
+    """JSON fields to embed. Defaults to ["$"] (entire document).
+    Examples:
+    - ["$"] - Embed entire document as one unit
+    - ["text", "summary"] - Embed specific top-level fields
+    - ["metadata.title", "content.text"] - JSON path notation
+    """
+
+
+class StoreConfig(TypedDict, total=False):
+    """Store configuration options"""
+
+    index: StoreIndexConfig | None
+    """Vector index configuration for semantic search"""
+
+
+class AuthConfig(TypedDict, total=False):
+    """Auth configuration options."""
+
+    path: str
+    """Import path for auth handler in format './file.py:variable' or 'module:variable'.
+    Examples:
+    - './auth.py:auth' - Load 'auth' from auth.py in project root
+    - './src/auth/firebase.py:auth' - Load from nested path
+    - 'mypackage.auth:auth' - Load from installed package
+    """
+    disable_studio_auth: bool
+    """Disable authentication for LangGraph Studio connections"""
+
+
+def _resolve_config_path() -> Path | None:
+    """Resolve config file path using standard resolution order.
+
+    Resolution order:
+    1) AEGRA_CONFIG env var (absolute or relative path) - returned even if doesn't exist
+    2) aegra.json in CWD
+        3) langgraph.json in CWD (fallback for compatibility)
+
+    Returns:
+        Path to config file or None if not found
+    """
+    # 1) Env var override - return even if doesn't exist (let caller handle error)
+    if env_path := settings.app.AEGRA_CONFIG:
+        return Path(env_path)
+
+    # 2) aegra.json if present
+    aegra_path = Path("aegra.json")
+    if aegra_path.exists():
+        return aegra_path
+
+    # 3) fallback to langgraph.json
+    langgraph_path = Path("langgraph.json")
+    if langgraph_path.exists():
+        return langgraph_path
+
+    return None
+
+
+def load_config() -> dict | None:
+    """Load full config file using standard resolution order.
+
+    Returns:
+        Full config dict or None if not found
+    """
+    config_path = _resolve_config_path()
+    if not config_path:
+        return None
+
+    try:
+        with config_path.open() as f:
+            return json.load(f)
+    except Exception as e:
+        logger.warning(f"Failed to load config from {config_path}: {e}")
+        return None
+
+
+def load_http_config() -> HttpConfig | None:
+    """Load HTTP config from aegra.json or langgraph.json.
+
+    Uses standard config resolution order.
+
+    Returns:
+        HTTP configuration dict or None if not found
+    """
+    config = load_config()
+    if config is None:
+        return None
+
+    http_config = config.get("http")
+    if http_config:
+        config_path = _resolve_config_path()
+        logger.info(f"Loaded HTTP config from {config_path}")
+        return http_config
+
+    return None
+
+
+def load_store_config() -> StoreConfig | None:
+    """Load store config from aegra.json or langgraph.json.
+
+    Uses standard config resolution order.
+
+    Returns:
+        Store configuration dict or None if not found
+    """
+    config = load_config()
+    if config is None:
+        return None
+
+    store_config = config.get("store")
+    if store_config:
+        config_path = _resolve_config_path()
+        logger.info(f"Loaded store config from {config_path}")
+        return store_config
+
+    return None
+
+
+def load_auth_config() -> AuthConfig | None:
+    """Load auth config from aegra.json or langgraph.json.
+
+    Uses standard config resolution order.
+
+    Returns:
+        Auth configuration dict or None if not found
+    """
+    config = load_config()
+    if config is None:
+        return None
+
+    auth_config = config.get("auth")
+    if auth_config:
+        config_path = _resolve_config_path()
+        logger.info(f"Loaded auth config from {config_path}")
+        return auth_config
+
+    return None
+
+
+def get_config_dir() -> Path | None:
+    """Get the directory containing the config file.
+
+    This is used to resolve relative paths in the config file
+    (graphs, http.app, auth.path) relative to the config location.
+
+    Returns:
+        Path to config directory or None if no config found
+    """
+    config_path = _resolve_config_path()
+    if config_path and config_path.exists():
+        return config_path.parent.resolve()
+    return None

aegra_api/constants.py

@@ -0,0 +1,5 @@
+from uuid import UUID
+
+# Standard namespace UUID for deriving deterministic assistant IDs from graph IDs.
+# IMPORTANT: Do not change after initial deploy unless you plan a data migration.
+ASSISTANT_NAMESPACE_UUID = UUID("6ba7b821-9dad-11d1-80b4-00c04fd430c8")

aegra_api/core/app_loader.py

@@ -0,0 +1,91 @@
+"""Custom application loader for dynamic FastAPI/Starlette app imports"""
+
+import importlib
+import importlib.util
+from pathlib import Path
+
+import structlog
+from fastapi import FastAPI
+
+logger = structlog.get_logger(__name__)
+
+
+def load_custom_app(app_import: str, base_dir: Path | None = None) -> FastAPI | None:
+    """Load custom FastAPI app from import path.
+
+    Supports both file-based and module-based imports:
+    - File path: "./custom_routes.py:app" or "/path/to/file.py:app"
+    - Module path: "my_package.custom:app"
+
+    Args:
+        app_import: Import path in format "path/to/file.py:variable" or "module.path:variable"
+        base_dir: Base directory for resolving relative file paths (e.g., config file directory)
+
+    Returns:
+        Loaded FastAPI app instance or None if path is invalid
+
+    Raises:
+        ImportError: If the module or file cannot be imported
+        AttributeError: If the specified variable is not found in the module
+        TypeError: If the loaded object is not a FastAPI application
+    """
+    logger.info(f"Loading custom app from {app_import}")
+
+    if ":" not in app_import:
+        raise ValueError(
+            f"Invalid app import path format: {app_import}. "
+            "Expected format: 'path/to/file.py:variable' or 'module.path:variable'"
+        )
+
+    path, name = app_import.rsplit(":", 1)
+
+    try:
+        # Determine if it's a file path or module path
+        path_obj = Path(path)
+        is_file_path = path_obj.suffix == ".py" or path.startswith("./") or path.startswith("../")
+
+        if is_file_path:
+            # Resolve relative paths from base_dir if provided
+            if not path_obj.is_absolute() and base_dir is not None:
+                path_obj = (base_dir / path_obj).resolve()
+
+            # Import from file path
+            if not path_obj.exists():
+                raise FileNotFoundError(f"Custom app file not found: {path_obj}")
+
+            spec = importlib.util.spec_from_file_location("custom_app_module", str(path_obj))
+            if spec is None or spec.loader is None:
+                raise ImportError(f"Cannot load spec from {path_obj}")
+
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+        else:
+            # Import as a normal module
+            module = importlib.import_module(path)
+
+        # Get the app instance from the module
+        if not hasattr(module, name):
+            raise AttributeError(
+                f"App '{name}' not found in module '{path}'. "
+                f"Available attributes: {[attr for attr in dir(module) if not attr.startswith('_')]}"
+            )
+
+        user_app = getattr(module, name)
+
+        # Validate it's a FastAPI application
+        if not isinstance(user_app, FastAPI):
+            raise TypeError(
+                f"Object '{name}' in module '{path}' is not a FastAPI application. "
+                "Custom apps must be FastAPI instances for proper OpenAPI support.\n"
+                "Please initialize your app using:\n\n"
+                "from fastapi import FastAPI\n\n"
+                "app = FastAPI()\n\n"
+            )
+
+        logger.info(f"Successfully loaded custom app '{name}' from {path}")
+        return user_app
+
+    except ImportError as e:
+        raise ImportError(f"Failed to import app module '{path}': {e}") from e
+    except AttributeError as e:
+        raise AttributeError(f"App '{name}' not found in module '{path}'") from e

aegra_api/core/auth_ctx.py

@@ -0,0 +1,65 @@
+"""Lightweight context-var helpers for passing authenticated user info into graphs.
+
+Graph nodes can access the current request's authentication context by calling
+`get_auth_ctx()`.  The server sets the context for the lifetime of a single run
+(using an async context-manager) so the information is automatically scoped and
+cleaned up.
+
+The structure follows the standard auth context format so that
+libraries expecting `Auth.types.BaseAuthContext` work unchanged.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from langgraph_sdk import Auth  # type: ignore
+from starlette.authentication import AuthCredentials, BaseUser
+
+# Internal context-var storing the current auth context (or None when absent)
+_AuthCtx: contextvars.ContextVar[Auth.types.BaseAuthContext | None] = contextvars.ContextVar(  # type: ignore[attr-defined]
+    "AuthContext", default=None
+)
+
+
+def get_auth_ctx() -> Auth.types.BaseAuthContext | None:  # type: ignore[attr-defined]
+    """Return the current authentication context or ``None`` if not set."""
+    return _AuthCtx.get()
+
+
+@asynccontextmanager
+async def with_auth_ctx(
+    user: BaseUser | None,
+    permissions: list[str] | AuthCredentials | None = None,
+) -> AsyncIterator[None]:
+    """Temporarily set the auth context for the duration of an async block.
+
+    Parameters
+    ----------
+    user
+        The authenticated user (or ``None`` for anonymous access).
+    permissions
+        Either a Starlette ``AuthCredentials`` instance or a list of permission
+        strings.  ``None`` means no permissions.
+    """
+    # Normalize the permissions list
+    scopes: list[str] = []
+    if isinstance(permissions, AuthCredentials):
+        scopes = list(permissions.scopes)
+    elif isinstance(permissions, list):
+        scopes = permissions
+
+    if user is None and not scopes:
+        token = _AuthCtx.set(None)
+    else:
+        token = _AuthCtx.set(
+            Auth.types.BaseAuthContext(  # type: ignore[attr-defined]
+                user=user, permissions=scopes
+            )
+        )
+    try:
+        yield
+    finally:
+        _AuthCtx.reset(token)

aegra_api/core/auth_deps.py

@@ -0,0 +1,186 @@
+"""Authentication dependencies for FastAPI endpoints"""
+
+from typing import Annotated, Any
+
+from fastapi import Depends, HTTPException, Request
+
+from aegra_api.core.auth_middleware import get_auth_backend
+from aegra_api.models.auth import User
+
+
+def _extract_user_data(user_obj: Any) -> dict[str, Any]:
+    """Extract user data from various object types.
+
+    Handles dict, objects with to_dict(), and objects with dict() methods.
+
+    Args:
+        user_obj: User object from authentication middleware
+
+    Returns:
+        Dictionary containing user data
+    """
+    if isinstance(user_obj, dict):
+        return user_obj
+    if hasattr(user_obj, "to_dict"):
+        return user_obj.to_dict()
+    if hasattr(user_obj, "dict"):
+        return user_obj.dict()
+    # Fallback: try to extract known attributes
+    return {
+        "identity": getattr(user_obj, "identity", str(user_obj)),
+        "is_authenticated": getattr(user_obj, "is_authenticated", True),
+    }
+
+
+def _to_user_model(user: Any) -> User:
+    """Convert auth result to User model.
+
+    Args:
+        user: User object from auth backend (LangGraphUser, dict, etc.)
+
+    Returns:
+        User model instance with all fields preserved
+    """
+    user_data = _extract_user_data(user)
+
+    # Ensure identity exists
+    if "identity" not in user_data:
+        raise HTTPException(status_code=401, detail="User identity not provided")
+
+    # Set display_name default if not provided
+    if user_data.get("display_name") is None:
+        user_data["display_name"] = user_data["identity"]
+
+    # Pass all fields through to User model (extra fields allowed via ConfigDict)
+    return User(**user_data)
+
+
+async def require_auth(request: Request) -> User:
+    """FastAPI dependency for authentication.
+
+    Replaces Starlette AuthenticationMiddleware by calling the auth backend directly.
+    This allows FastAPI to properly track dependencies for OpenAPI generation.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        User object with authentication context including any extra fields
+
+    Raises:
+        HTTPException: If user is not authenticated
+    """
+    backend = get_auth_backend()
+
+    try:
+        result = await backend.authenticate(request)
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=str(e)) from e
+
+    if result is None:
+        # No auth configured - for now, require auth if backend exists
+        # (This will be handled by noop auth in the backend)
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    credentials, user = result
+
+    # Set request.scope for backward compatibility
+    # (Some code might still read request.scope["user"] or request.user)
+    request.scope["user"] = user
+    request.scope["auth"] = credentials
+    # Also set request.user for Starlette compatibility
+    if not hasattr(request, "user"):
+        request.user = user
+
+    # Convert to User model
+    return _to_user_model(user)
+
+
+# Type alias for cleaner route signatures
+AuthenticatedUser = Annotated[User, Depends(require_auth)]
+
+# For applying to entire routers
+auth_dependency = [Depends(require_auth)]
+
+
+def get_current_user(request: Request) -> User:
+    """
+    Legacy: Extract current user from request context set by middleware or dependency.
+
+    This function reads from request.scope["user"] which is set by either:
+    - The new require_auth() dependency (preferred)
+    - The old AuthenticationMiddleware (for backward compatibility)
+
+    This function passes ALL fields from auth handlers through to the User model,
+    allowing custom auth handlers to return extra fields (e.g., subscription_tier,
+    team_id) that will be accessible on the User object.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        User object with authentication context including any extra fields
+
+    Raises:
+        HTTPException: If user is not authenticated
+    """
+    # Try reading from request.scope first (set by require_auth dependency)
+    user = request.scope.get("user")
+    if user is None:
+        # Fallback to request.user (set by middleware)
+        if not hasattr(request, "user") or request.user is None:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        user = request.user
+
+    if hasattr(user, "is_authenticated") and not user.is_authenticated:
+        raise HTTPException(status_code=401, detail="Invalid authentication")
+
+    # Convert to User model
+    return _to_user_model(user)
+
+
+def get_user_id(user: User = Depends(get_current_user)) -> str:
+    """
+    Helper dependency to get user ID safely.
+
+    Args:
+        user: User object from get_current_user dependency
+
+    Returns:
+        User identity string
+    """
+    return user.identity
+
+
+def require_permission(permission: str):
+    """
+    Create a dependency that requires a specific permission.
+
+    Args:
+        permission: Required permission string
+
+    Returns:
+        Dependency function that checks for the permission
+
+    Example:
+        @app.get("/admin")
+        def admin_endpoint(user: User = Depends(require_permission("admin"))):
+            return {"message": "Admin access granted"}
+    """
+
+    def permission_dependency(user: User = Depends(get_current_user)) -> User:
+        if permission not in user.permissions:
+            raise HTTPException(status_code=403, detail=f"Permission '{permission}' required")
+        return user
+
+    return permission_dependency
+
+
+def require_authenticated(request: Request) -> User:
+    """
+    Simplified dependency that just ensures user is authenticated.
+
+    This is equivalent to get_current_user but with a clearer name
+    for endpoints that just need any authenticated user.
+    """
+    return get_current_user(request)