sinas 0.1.0__py3-none-any.whl

sinas/integrations/fastapi.py

@@ -0,0 +1,288 @@
+"""FastAPI integration for SINAS authentication and authorization.
+
+This module provides zero-boilerplate SINAS auth for FastAPI applications.
+
+Example:
+    ```python
+    from fastapi import FastAPI, Depends
+    from sinas.integrations.fastapi import SinasAuth
+
+    app = FastAPI()
+    sinas = SinasAuth(base_url="http://localhost:51245")
+
+    # Auto-authenticated endpoints
+    @app.get("/chats")
+    async def get_chats(client: SinasClient = Depends(sinas)):
+        return client.chats.list()
+
+    # Permission-protected endpoints
+    @app.delete("/users/{user_id}")
+    async def delete_user(
+        user_id: str,
+        client: SinasClient = Depends(sinas.require("sinas.users.delete:all"))
+    ):
+        return client.users.delete(user_id)
+
+    # Include auto-generated auth routes
+    app.include_router(sinas.router, prefix="/auth")
+    ```
+"""
+
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional
+
+try:
+    from fastapi import APIRouter, Depends, Header, HTTPException, status
+    from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+    from pydantic import BaseModel, EmailStr
+except ImportError:
+    raise ImportError(
+        "FastAPI integration requires fastapi and pydantic. "
+        "Install with: pip install 'sinas[fastapi]'"
+    )
+
+if TYPE_CHECKING:
+    from sinas.client import SinasClient
+
+from sinas import SinasAPIError, SinasAuthError, SinasClient
+
+
+class LoginRequest(BaseModel):
+    """Login request body."""
+
+    email: EmailStr
+
+
+class VerifyOTPRequest(BaseModel):
+    """OTP verification request body."""
+
+    session_id: str
+    otp_code: str
+
+
+class SinasAuth:
+    """FastAPI dependency for SINAS authentication and authorization.
+
+    This class provides:
+    - Automatic token extraction from Authorization header
+    - Per-request SinasClient instantiation with user token
+    - Permission checking decorators
+    - Auto-generated auth endpoints (login, verify-otp, me)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token_url: str = "/auth/token",
+        auto_error: bool = True,
+    ) -> None:
+        """Initialize SINAS FastAPI auth.
+
+        Args:
+            base_url: Base URL for SINAS API.
+            token_url: URL for token endpoint (for OpenAPI docs).
+            auto_error: Whether to automatically raise HTTPException on auth errors.
+        """
+        self.base_url = base_url
+        self.auto_error = auto_error
+        self._security = HTTPBearer(auto_error=auto_error)
+
+        # Create router with auto-generated auth endpoints
+        self.router = self._create_auth_router()
+
+    async def __call__(
+        self,
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(HTTPBearer(auto_error=False)),
+    ) -> "SinasClient":
+        """Extract token and return authenticated SinasClient.
+
+        This is the main dependency - use it with Depends(sinas_auth).
+
+        Args:
+            credentials: HTTP Bearer credentials from Authorization header.
+
+        Returns:
+            Authenticated SinasClient instance.
+
+        Raises:
+            HTTPException: If authentication fails (when auto_error=True).
+        """
+        if not credentials:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Missing authentication credentials",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            # Return unauthenticated client
+            return SinasClient(base_url=self.base_url)
+
+        token = credentials.credentials
+
+        # Create client with user's token
+        client = SinasClient(base_url=self.base_url, token=token)
+
+        # Optionally validate token by fetching user info
+        # This adds one extra request but ensures the token is valid
+        try:
+            await self._validate_token(client)
+        except SinasAuthError:
+            if self.auto_error:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Invalid or expired token",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+
+        return client
+
+    async def _validate_token(self, client: "SinasClient") -> None:
+        """Validate token by calling /auth/me endpoint.
+
+        Args:
+            client: SINAS client with token.
+
+        Raises:
+            SinasAuthError: If token is invalid.
+        """
+        # This will raise SinasAuthError if token is invalid
+        client.auth.get_me()
+
+    def require(self, *permissions: str) -> Callable:
+        """Create a dependency that requires specific permissions.
+
+        Args:
+            *permissions: One or more permission strings (e.g., "sinas.chats.read:own").
+
+        Returns:
+            FastAPI dependency function that checks permissions.
+
+        Example:
+            ```python
+            @app.delete("/chats/{chat_id}")
+            async def delete_chat(
+                chat_id: str,
+                client: SinasClient = Depends(sinas.require("sinas.chats.delete:own"))
+            ):
+                client.chats.delete(chat_id)
+            ```
+        """
+
+        async def permission_checker(
+            client: "SinasClient" = Depends(self),
+        ) -> "SinasClient":
+            """Check if user has required permissions."""
+            try:
+                user = client.auth.get_me()
+                user_permissions = set(user.get("permissions", []))
+
+                # Check if user has any of the required permissions
+                has_permission = False
+                for perm in permissions:
+                    if self._check_permission(perm, user_permissions):
+                        has_permission = True
+                        break
+
+                if not has_permission:
+                    raise HTTPException(
+                        status_code=status.HTTP_403_FORBIDDEN,
+                        detail=f"Missing required permission: {' OR '.join(permissions)}",
+                    )
+
+                return client
+            except SinasAuthError:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Authentication required",
+                )
+
+        return permission_checker
+
+    def _check_permission(self, required: str, user_permissions: set) -> bool:
+        """Check if user has a specific permission.
+
+        Supports wildcards like "sinas.chats.*" or "sinas.*:all".
+
+        Args:
+            required: Required permission string.
+            user_permissions: Set of user's permissions.
+
+        Returns:
+            True if user has the permission.
+        """
+        # Direct match
+        if required in user_permissions:
+            return True
+
+        # Check for wildcard matches
+        # e.g., user has "sinas.*" and needs "sinas.chats.read:own"
+        for user_perm in user_permissions:
+            if "*" in user_perm:
+                # Simple wildcard matching
+                parts = user_perm.split(".")
+                required_parts = required.split(".")
+
+                match = True
+                for i, part in enumerate(parts):
+                    if i >= len(required_parts):
+                        match = False
+                        break
+                    if part == "*":
+                        continue
+                    if part != required_parts[i]:
+                        match = False
+                        break
+
+                if match:
+                    return True
+
+        return False
+
+    def _create_auth_router(self) -> APIRouter:
+        """Create auto-generated authentication routes.
+
+        Returns:
+            FastAPI router with /login, /verify-otp, and /me endpoints.
+        """
+        router = APIRouter(tags=["authentication"])
+
+        # Unauthenticated client for login/verify
+        base_client = SinasClient(base_url=self.base_url)
+
+        @router.post("/login")
+        async def login(request: LoginRequest) -> Dict[str, Any]:
+            """Initiate login by sending OTP to email."""
+            try:
+                return base_client.auth.login(request.email)
+            except SinasAPIError as e:
+                raise HTTPException(
+                    status_code=e.status_code or status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=str(e),
+                )
+
+        @router.post("/verify-otp")
+        async def verify_otp(request: VerifyOTPRequest) -> Dict[str, Any]:
+            """Verify OTP and return access token."""
+            try:
+                return base_client.auth.verify_otp(request.session_id, request.otp_code)
+            except SinasAPIError as e:
+                raise HTTPException(
+                    status_code=e.status_code or status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=str(e),
+                )
+
+        @router.get("/me")
+        async def get_current_user(client: "SinasClient" = Depends(self)) -> Dict[str, Any]:
+            """Get current authenticated user info."""
+            try:
+                return client.auth.get_me()
+            except SinasAuthError:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Authentication required",
+                )
+
+        return router
+
+
+# Convenience alias
+SinasFastAPI = SinasAuth

sinas/integrations/routers.py

@@ -0,0 +1,324 @@
+"""FastAPI routers for SINAS Runtime API endpoints.
+
+This module provides ready-to-mount FastAPI routers that proxy requests to SINAS Runtime API.
+Each router handles authentication automatically and forwards requests to the backend.
+"""
+
+from typing import Any, Dict, List, Optional
+
+try:
+    from fastapi import APIRouter, Depends, Request
+    from fastapi.responses import StreamingResponse
+except ImportError:
+    raise ImportError(
+        "FastAPI integration requires fastapi. "
+        "Install with: pip install 'sinas[fastapi]'"
+    )
+
+from sinas import SinasClient
+from sinas.integrations.fastapi import SinasAuth
+
+
+def create_state_router(base_url: str, prefix: str = "") -> APIRouter:
+    """Create a FastAPI router for state management endpoints.
+
+    Args:
+        base_url: SINAS API base URL.
+        prefix: Optional prefix for routes (e.g., "/states").
+
+    Returns:
+        FastAPI router with state endpoints.
+
+    Example:
+        ```python
+        app.include_router(create_state_router("http://localhost:51245"), prefix="/runtime/states")
+        ```
+    """
+    router = APIRouter(tags=["states"])
+    auth = SinasAuth(base_url=base_url)
+
+    @router.post(prefix or "")
+    async def create_state(
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Create a new state entry."""
+        body = await request.json()
+        return client.state.set(**body)
+
+    @router.get(prefix or "")
+    async def list_states(
+        namespace: Optional[str] = None,
+        visibility: Optional[str] = None,
+        assistant_id: Optional[str] = None,
+        tags: Optional[str] = None,
+        search: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 100,
+        client: SinasClient = Depends(auth)
+    ) -> List[Dict[str, Any]]:
+        """List state entries."""
+        return client.state.list(
+            namespace=namespace,
+            visibility=visibility,
+            assistant_id=assistant_id,
+            tags=tags,
+            search=search,
+            skip=skip,
+            limit=limit
+        )
+
+    @router.get(f"{prefix}/{{state_id}}")
+    async def get_state(
+        state_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Get a specific state entry."""
+        return client.state.get(state_id)
+
+    @router.put(f"{prefix}/{{state_id}}")
+    async def update_state(
+        state_id: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Update a state entry."""
+        body = await request.json()
+        return client.state.update(state_id, **body)
+
+    @router.delete(f"{prefix}/{{state_id}}")
+    async def delete_state(
+        state_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Delete a state entry."""
+        return client.state.delete(state_id)
+
+    return router
+
+
+def create_chat_router(base_url: str, prefix: str = "") -> APIRouter:
+    """Create a FastAPI router for chat endpoints.
+
+    Args:
+        base_url: SINAS API base URL.
+        prefix: Optional prefix for routes (e.g., "/chats").
+
+    Returns:
+        FastAPI router with chat endpoints.
+
+    Example:
+        ```python
+        app.include_router(create_chat_router("http://localhost:51245"), prefix="/runtime/chats")
+        ```
+    """
+    router = APIRouter(tags=["chats"])
+    auth = SinasAuth(base_url=base_url)
+
+    @router.post("/agents/{namespace}/{agent_name}/chats")
+    async def create_chat(
+        namespace: str,
+        agent_name: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Create a new chat with an agent."""
+        body = await request.json()
+        return client.chats.create(namespace, agent_name, **body)
+
+    @router.post(f"{prefix}/{{chat_id}}/messages")
+    async def send_message(
+        chat_id: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Send a message to a chat."""
+        body = await request.json()
+        return client.chats.send(chat_id, body["content"])
+
+    @router.post(f"{prefix}/{{chat_id}}/messages/stream")
+    async def stream_message(
+        chat_id: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ):
+        """Stream a message to a chat."""
+        body = await request.json()
+
+        async def event_generator():
+            for chunk in client.chats.stream(chat_id, body["content"]):
+                yield f"data: {chunk}\n\n"
+
+        return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+    @router.get(prefix or "")
+    async def list_chats(
+        client: SinasClient = Depends(auth)
+    ) -> List[Dict[str, Any]]:
+        """List all chats for the current user."""
+        return client.chats.list()
+
+    @router.get(f"{prefix}/{{chat_id}}")
+    async def get_chat(
+        chat_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Get a chat with all messages."""
+        return client.chats.get(chat_id)
+
+    @router.put(f"{prefix}/{{chat_id}}")
+    async def update_chat(
+        chat_id: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Update a chat."""
+        body = await request.json()
+        return client.chats.update(chat_id, **body)
+
+    @router.delete(f"{prefix}/{{chat_id}}")
+    async def delete_chat(
+        chat_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> None:
+        """Delete a chat."""
+        client.chats.delete(chat_id)
+        return None
+
+    return router
+
+
+def create_webhook_router(base_url: str, prefix: str = "") -> APIRouter:
+    """Create a FastAPI router for webhook execution endpoints.
+
+    Args:
+        base_url: SINAS API base URL.
+        prefix: Optional prefix for routes (e.g., "/webhooks").
+
+    Returns:
+        FastAPI router with webhook endpoints.
+
+    Example:
+        ```python
+        app.include_router(create_webhook_router("http://localhost:51245"), prefix="/runtime/webhooks")
+        ```
+    """
+    router = APIRouter(tags=["webhooks"])
+    auth = SinasAuth(base_url=base_url)
+
+    @router.api_route(
+        f"{prefix}/{{path:path}}",
+        methods=["GET", "POST", "PUT", "DELETE", "PATCH"]
+    )
+    async def execute_webhook(
+        path: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Execute a webhook."""
+        body = None
+        if request.method in ["POST", "PUT", "PATCH"]:
+            body = await request.json() if request.headers.get("content-type") == "application/json" else None
+
+        return client.webhooks.run(
+            path=path,
+            method=request.method,
+            body=body,
+            query=dict(request.query_params)
+        )
+
+    return router
+
+
+def create_executions_router(base_url: str, prefix: str = "") -> APIRouter:
+    """Create a FastAPI router for execution endpoints.
+
+    Args:
+        base_url: SINAS API base URL.
+        prefix: Optional prefix for routes (e.g., "/executions").
+
+    Returns:
+        FastAPI router with execution endpoints.
+
+    Example:
+        ```python
+        app.include_router(create_executions_router("http://localhost:51245"), prefix="/runtime/executions")
+        ```
+    """
+    router = APIRouter(tags=["executions"])
+    auth = SinasAuth(base_url=base_url)
+
+    @router.get(prefix or "")
+    async def list_executions(
+        function_name: Optional[str] = None,
+        status: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 100,
+        client: SinasClient = Depends(auth)
+    ) -> List[Dict[str, Any]]:
+        """List executions."""
+        return client.executions.list(
+            function_name=function_name,
+            status=status,
+            skip=skip,
+            limit=limit
+        )
+
+    @router.get(f"{prefix}/{{execution_id}}")
+    async def get_execution(
+        execution_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Get execution details."""
+        return client.executions.get(execution_id)
+
+    @router.get(f"{prefix}/{{execution_id}}/steps")
+    async def get_execution_steps(
+        execution_id: str,
+        client: SinasClient = Depends(auth)
+    ) -> List[Dict[str, Any]]:
+        """Get execution steps."""
+        return client.executions.get_steps(execution_id)
+
+    @router.post(f"{prefix}/{{execution_id}}/continue")
+    async def continue_execution(
+        execution_id: str,
+        request: Request,
+        client: SinasClient = Depends(auth)
+    ) -> Dict[str, Any]:
+        """Continue a paused execution."""
+        body = await request.json()
+        return client.executions.continue_execution(execution_id, body["input"])
+
+    return router
+
+
+def create_runtime_router(base_url: str, include_auth: bool = False) -> APIRouter:
+    """Create a complete runtime router with all endpoints.
+
+    Args:
+        base_url: SINAS API base URL.
+        include_auth: Whether to include auth endpoints (login, verify-otp, etc.).
+
+    Returns:
+        FastAPI router with all runtime endpoints.
+
+    Example:
+        ```python
+        app.include_router(create_runtime_router("http://localhost:51245"), prefix="/runtime")
+        ```
+    """
+    router = APIRouter()
+
+    # Include individual routers
+    router.include_router(create_state_router(base_url), prefix="/states")
+    router.include_router(create_chat_router(base_url), prefix="/chats")
+    router.include_router(create_webhook_router(base_url), prefix="/webhooks")
+    router.include_router(create_executions_router(base_url), prefix="/executions")
+
+    # Optionally include auth endpoints
+    if include_auth:
+        auth = SinasAuth(base_url=base_url)
+        router.include_router(auth.router, prefix="/auth")
+
+    return router