remdb 0.3.0__py3-none-any.whl

rem/api/routers/chat/models.py

@@ -0,0 +1,124 @@
+"""
+OpenAI-compatible API models for chat completions.
+
+Design Pattern 
+- Full OpenAI compatibility for drop-in replacement
+- Support for streaming (SSE) and non-streaming modes
+- Response format control (text vs json_object)
+- Headers map to AgentContext (X-User-Id, X-Tenant-Id, X-Agent-Schema, etc.)
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+# Request models
+class ChatMessage(BaseModel):
+    """OpenAI chat message format."""
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str | None = None
+    name: str | None = None
+    tool_call_id: str | None = None
+
+
+class ResponseFormat(BaseModel):
+    """
+    Response format specification (OpenAI-compatible).
+
+    - text: Plain text response
+    - json_object: Best-effort JSON extraction from agent output
+    """
+
+    type: Literal["text", "json_object"] = Field(
+        default="text",
+        description="Response format type. Use 'json_object' to enable JSON mode.",
+    )
+
+
+class ChatCompletionRequest(BaseModel):
+    """
+    OpenAI chat completion request format.
+
+    Compatible with OpenAI's /v1/chat/completions endpoint.
+
+    Headers Map to AgentContext:
+    - X-User-Id → context.user_id
+    - X-Tenant-Id → context.tenant_id
+    - X-Session-Id → context.session_id
+    - X-Agent-Schema → context.agent_schema_uri
+
+    Note: Model is specified in body.model (standard OpenAI field), not headers.
+    """
+
+    model: str = Field(
+        default="anthropic:claude-sonnet-4-5-20250929",
+        description="Model to use (standard OpenAI field)",
+    )
+    messages: list[ChatMessage] = Field(description="Chat conversation history")
+    temperature: float | None = Field(default=None, ge=0, le=2)
+    max_tokens: int | None = Field(default=None, ge=1)
+    stream: bool = Field(default=False, description="Enable SSE streaming")
+    n: int | None = Field(default=1, ge=1, le=1, description="Number of completions (must be 1)")
+    stop: str | list[str] | None = None
+    presence_penalty: float | None = Field(default=None, ge=-2, le=2)
+    frequency_penalty: float | None = Field(default=None, ge=-2, le=2)
+    user: str | None = Field(default=None, description="Unique user identifier")
+    response_format: ResponseFormat | None = Field(
+        default=None,
+        description="Response format. Set type='json_object' to enable JSON mode.",
+    )
+
+
+# Response models
+class ChatCompletionUsage(BaseModel):
+    """Token usage statistics."""
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class ChatCompletionMessageDelta(BaseModel):
+    """Streaming delta for chat completion."""
+
+    role: Literal["system", "user", "assistant"] | None = None
+    content: str | None = None
+
+
+class ChatCompletionChoice(BaseModel):
+    """Chat completion choice (non-streaming)."""
+
+    index: int
+    message: ChatMessage
+    finish_reason: Literal["stop", "length", "content_filter", "tool_calls"] | None
+
+
+class ChatCompletionStreamChoice(BaseModel):
+    """Chat completion choice (streaming)."""
+
+    index: int
+    delta: ChatCompletionMessageDelta
+    finish_reason: Literal["stop", "length", "content_filter"] | None = None
+
+
+class ChatCompletionResponse(BaseModel):
+    """OpenAI chat completion response (non-streaming)."""
+
+    id: str
+    object: Literal["chat.completion"] = "chat.completion"
+    created: int
+    model: str
+    choices: list[ChatCompletionChoice]
+    usage: ChatCompletionUsage
+
+
+class ChatCompletionStreamResponse(BaseModel):
+    """OpenAI chat completion chunk (streaming)."""
+
+    id: str
+    object: Literal["chat.completion.chunk"] = "chat.completion.chunk"
+    created: int
+    model: str
+    choices: list[ChatCompletionStreamChoice]

rem/api/routers/chat/streaming.py

@@ -0,0 +1,185 @@
+"""
+OpenAI-compatible streaming relay for Pydantic AI agents.
+
+Design Pattern:
+- Uses Pydantic AI's agent.iter() to capture full execution including tool calls
+- Streams tool call events with [Calling: tool_name] markers
+- Streams text content deltas as they arrive
+- Proper OpenAI SSE format with data: prefix and [DONE] terminator
+- Error handling with graceful degradation
+
+Key Insight 
+- agent.run_stream() stops after first output, missing tool calls
+- agent.iter() provides complete execution with tool call visibility
+- Use PartStartEvent to detect tool calls
+- Use PartDeltaEvent with TextPartDelta for content streaming
+
+SSE Format:
+    data: {"id": "chatcmpl-...", "choices": [{"delta": {"content": "..."}}]}\\n\\n
+    data: [DONE]\\n\\n
+"""
+
+import json
+import time
+import uuid
+from typing import AsyncGenerator
+
+from loguru import logger
+from pydantic_ai.agent import Agent
+from pydantic_ai.messages import (
+    PartDeltaEvent,
+    PartStartEvent,
+    TextPartDelta,
+    ToolCallPart,
+)
+
+from .models import (
+    ChatCompletionMessageDelta,
+    ChatCompletionStreamChoice,
+    ChatCompletionStreamResponse,
+)
+
+
+async def stream_openai_response(
+    agent: Agent,
+    prompt: str,
+    model: str,
+    request_id: str | None = None,
+) -> AsyncGenerator[str, None]:
+    """
+    Stream Pydantic AI agent responses in OpenAI SSE format with tool call events.
+
+    Design Pattern:
+    1. Use agent.iter() for complete execution (not run_stream())
+    2. Iterate over nodes to capture model requests and tool executions
+    3. Stream tool call start events as [Calling: tool_name]
+    4. Stream text content deltas as they arrive
+    5. Send final chunk with finish_reason="stop"
+    6. Send OpenAI termination marker [DONE]
+
+    Args:
+        agent: Pydantic AI agent instance
+        prompt: User prompt to run
+        model: Model name for response metadata
+        request_id: Optional request ID (generates UUID if not provided)
+
+    Yields:
+        SSE-formatted strings: "data: {json}\\n\\n"
+
+    Example Stream:
+        data: {"id": "chatcmpl-123", "choices": [{"delta": {"role": "assistant", "content": ""}}]}
+
+        data: {"id": "chatcmpl-123", "choices": [{"delta": {"content": "[Calling: search]"}}]}
+
+        data: {"id": "chatcmpl-123", "choices": [{"delta": {"content": "Found 3 results..."}}]}
+
+        data: {"id": "chatcmpl-123", "choices": [{"delta": {}, "finish_reason": "stop"}]}
+
+        data: [DONE]
+    """
+    if request_id is None:
+        request_id = f"chatcmpl-{uuid.uuid4().hex[:24]}"
+
+    created_at = int(time.time())
+    is_first_chunk = True
+
+    try:
+        # Use agent.iter() to get complete execution with tool calls
+        # run_stream() stops after first output, missing tool calls
+        async with agent.iter(prompt) as agent_run:
+            async for node in agent_run:
+                # Check if this is a model request node (includes tool calls)
+                if Agent.is_model_request_node(node):
+                    # Stream events from model request
+                    async with node.stream(agent_run.ctx) as request_stream:
+                        async for event in request_stream:
+                            # Tool call start event
+                            if isinstance(event, PartStartEvent) and isinstance(
+                                event.part, ToolCallPart
+                            ):
+                                logger.info(f"🔧 {event.part.tool_name}")
+
+                                tool_call_chunk = ChatCompletionStreamResponse(
+                                    id=request_id,
+                                    created=created_at,
+                                    model=model,
+                                    choices=[
+                                        ChatCompletionStreamChoice(
+                                            index=0,
+                                            delta=ChatCompletionMessageDelta(
+                                                role="assistant" if is_first_chunk else None,
+                                                content=f"[Calling: {event.part.tool_name}]",
+                                            ),
+                                            finish_reason=None,
+                                        )
+                                    ],
+                                )
+                                is_first_chunk = False
+                                yield f"data: {tool_call_chunk.model_dump_json()}\n\n"
+
+                            # Text content delta
+                            elif isinstance(event, PartDeltaEvent) and isinstance(
+                                event.delta, TextPartDelta
+                            ):
+                                content_chunk = ChatCompletionStreamResponse(
+                                    id=request_id,
+                                    created=created_at,
+                                    model=model,
+                                    choices=[
+                                        ChatCompletionStreamChoice(
+                                            index=0,
+                                            delta=ChatCompletionMessageDelta(
+                                                role="assistant" if is_first_chunk else None,
+                                                content=event.delta.content_delta,
+                                            ),
+                                            finish_reason=None,
+                                        )
+                                    ],
+                                )
+                                is_first_chunk = False
+                                yield f"data: {content_chunk.model_dump_json()}\n\n"
+
+                # Check if this is a tool execution node
+                elif Agent.is_call_tools_node(node):
+                    # Stream tool execution - tools complete here
+                    async with node.stream(agent_run.ctx) as tools_stream:
+                        async for event in tools_stream:
+                            # We can log tool completion here if needed
+                            # For now, we already logged the call start above
+                            pass
+
+        # Final chunk with finish_reason
+        final_chunk = ChatCompletionStreamResponse(
+            id=request_id,
+            created=created_at,
+            model=model,
+            choices=[
+                ChatCompletionStreamChoice(
+                    index=0,
+                    delta=ChatCompletionMessageDelta(),
+                    finish_reason="stop",
+                )
+            ],
+        )
+        yield f"data: {final_chunk.model_dump_json()}\n\n"
+
+        # OpenAI termination marker
+        yield "data: [DONE]\n\n"
+
+    except Exception as e:
+        import traceback
+
+        error_msg = str(e)
+        logger.error(f"Streaming error: {error_msg}")
+        logger.error(traceback.format_exc())
+
+        # Send error as final chunk
+        error_data = {
+            "error": {
+                "message": error_msg,
+                "type": "internal_error",
+                "code": "stream_error",
+            }
+        }
+        yield f"data: {json.dumps(error_data)}\n\n"
+        yield "data: [DONE]\n\n"

rem/auth/README.md

@@ -0,0 +1,258 @@
+# OAuth 2.1 Authentication
+
+OAuth 2.1 compliant authentication with Google and Microsoft Entra ID.
+
+## Features
+
+- **OAuth 2.1 Security Best Practices**
+  - PKCE (Proof Key for Code Exchange) - mandatory for all flows
+  - State parameter for CSRF protection
+  - Nonce for ID token replay protection
+  - Token validation with JWKS
+
+- **Supported Providers**
+  - Google OAuth 2.0 / OIDC
+  - Microsoft Entra ID (Azure AD) OIDC
+
+- **Minimal Code**
+  - Leverages Authlib for standards compliance
+  - Authlib handles PKCE, token exchange, JWKS validation
+  - Clean integration with FastAPI
+
+## Installation
+
+```bash
+pip install authlib httpx
+```
+
+## Configuration
+
+### Google OAuth Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create OAuth 2.0 credentials
+3. Add authorized redirect URI: `http://localhost:8000/api/auth/google/callback`
+4. Set environment variables:
+
+```bash
+AUTH__ENABLED=true
+AUTH__SESSION_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
+
+AUTH__GOOGLE__CLIENT_ID=your-client-id.apps.googleusercontent.com
+AUTH__GOOGLE__CLIENT_SECRET=your-client-secret
+AUTH__GOOGLE__REDIRECT_URI=http://localhost:8000/api/auth/google/callback
+```
+
+### Microsoft Entra ID Setup
+
+1. Go to [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps)
+2. Register new application
+3. Create client secret under "Certificates & secrets"
+4. Add redirect URI: `http://localhost:8000/api/auth/microsoft/callback`
+5. Add API permissions: Microsoft Graph > User.Read (delegated)
+6. Set environment variables:
+
+```bash
+AUTH__ENABLED=true
+AUTH__SESSION_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
+
+AUTH__MICROSOFT__CLIENT_ID=your-application-id
+AUTH__MICROSOFT__CLIENT_SECRET=your-client-secret
+AUTH__MICROSOFT__REDIRECT_URI=http://localhost:8000/api/auth/microsoft/callback
+AUTH__MICROSOFT__TENANT=common  # or your tenant ID
+```
+
+**Tenant options:**
+- `common` - Multi-tenant + personal Microsoft accounts
+- `organizations` - Work/school accounts only
+- `consumers` - Personal Microsoft accounts only
+- `{tenant-id}` - Single tenant (specific organization)
+
+## Usage
+
+### 1. Start the API server
+
+```bash
+cd rem
+uv run python -m rem.api.main
+```
+
+### 2. Initiate login
+
+Navigate to:
+- Google: `http://localhost:8000/api/auth/google/login`
+- Microsoft: `http://localhost:8000/api/auth/microsoft/login`
+
+### 3. OAuth Flow
+
+```
+User                Browser                API Server              OAuth Provider
+  |                    |                       |                         |
+  |-- Click Login ---->|                       |                         |
+  |                    |-- GET /auth/google/login -->                    |
+  |                    |                       |-- Generate PKCE ------->|
+  |                    |                       |   (code_verifier)       |
+  |                    |<-- Redirect to Google --|                       |
+  |<-- Show Google login --|                   |                         |
+  |                    |                       |                         |
+  |-- Enter credentials -->                    |                         |
+  |                    |-- Authorize ----------------------->|            |
+  |                    |<-- Redirect with code ----------------|          |
+  |                    |                       |                         |
+  |                    |-- GET /auth/google/callback?code=xyz ---------->|
+  |                    |                       |-- Exchange code ------->|
+  |                    |                       |   + code_verifier       |
+  |                    |                       |<-- Tokens --------------|
+  |                    |                       |-- Validate ID token --->|
+  |                    |                       |   (JWKS)                |
+  |                    |<-- Set session cookie --|                       |
+  |<-- Redirect to app ---|                   |                         |
+```
+
+### 4. Access protected endpoints
+
+After login, session cookie is set automatically:
+
+```bash
+# Get current user
+curl http://localhost:8000/api/auth/me \
+  -H "Cookie: rem_session=..."
+
+# Protected API endpoint
+curl http://localhost:8000/api/v1/chat/completions \
+  -H "Cookie: rem_session=..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "anthropic:claude-sonnet-4-5-20250929",
+    "messages": [{"role": "user", "content": "Hello"}]
+  }'
+```
+
+### 5. Logout
+
+```bash
+curl -X POST http://localhost:8000/api/auth/logout \
+  -H "Cookie: rem_session=..."
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/auth/google/login` | Initiate Google OAuth flow |
+| GET | `/api/auth/google/callback` | Google OAuth callback |
+| GET | `/api/auth/microsoft/login` | Initiate Microsoft OAuth flow |
+| GET | `/api/auth/microsoft/callback` | Microsoft OAuth callback |
+| POST | `/api/auth/logout` | Clear session |
+| GET | `/api/auth/me` | Get current user info |
+
+## Security Features
+
+### OAuth 2.1 Compliance
+
+- **PKCE**: All flows use code_challenge (S256 method)
+- **State**: CSRF protection on all authorization requests
+- **Nonce**: ID token replay protection
+- **No implicit flow**: Only authorization code flow supported
+- **JWKS validation**: ID tokens validated with provider's public keys
+
+### Session Security
+
+- **HTTPOnly cookies**: Session cookies not accessible to JavaScript
+- **SameSite=Lax**: CSRF protection for cookie-based auth
+- **Secure flag**: HTTPS-only cookies in production
+- **Short expiration**: 1 hour session lifetime (configurable)
+
+### Middleware Protection
+
+- Protects `/api/v1/*` endpoints
+- Excludes `/api/auth/*` and public endpoints
+- Returns 401 for API requests (JSON)
+- Redirects to login for browser requests
+
+## Provider-Specific Features
+
+### Google
+
+- **Hosted domain restriction**: Limit to Google Workspace domain
+- **Offline access**: Request refresh tokens
+- **Incremental authorization**: Add scopes incrementally
+
+```bash
+AUTH__GOOGLE__HOSTED_DOMAIN=example.com  # Google Workspace only
+```
+
+### Microsoft
+
+- **Multi-tenant support**: common/organizations/consumers
+- **Conditional access**: Honors Entra ID policies
+- **Microsoft Graph**: Access user profile via Graph API
+
+```bash
+AUTH__MICROSOFT__TENANT=common           # Multi-tenant
+AUTH__MICROSOFT__TENANT=organizations    # Work/school only
+AUTH__MICROSOFT__TENANT=consumers        # Personal accounts
+AUTH__MICROSOFT__TENANT=contoso.com      # Single tenant
+```
+
+## Architecture
+
+```
+rem/src/rem/auth/
+├── __init__.py              # Module exports
+├── README.md                # This file
+├── middleware.py            # FastAPI auth middleware
+├── providers/               # OAuth provider implementations
+│   ├── __init__.py
+│   ├── base.py             # Base OAuth provider (kept for reference)
+│   ├── google.py           # Google provider (kept for reference)
+│   └── microsoft.py        # Microsoft provider (kept for reference)
+```
+
+**Note**: Provider classes in `providers/` are kept for reference but not used.
+The implementation uses Authlib's built-in provider support via `server_metadata_url`.
+
+## Testing
+
+```bash
+# Test Google login flow
+open http://localhost:8000/api/auth/google/login
+
+# Test Microsoft login flow
+open http://localhost:8000/api/auth/microsoft/login
+
+# Check current user
+curl http://localhost:8000/api/auth/me
+```
+
+## Troubleshooting
+
+### "Authentication is disabled"
+
+Set `AUTH__ENABLED=true` in environment or `.env` file.
+
+### "Unknown provider: google"
+
+Check that `AUTH__GOOGLE__CLIENT_ID` is set. The router only registers providers with valid credentials.
+
+### Redirect URI mismatch
+
+Ensure redirect URI in environment matches exactly what's registered with provider:
+- Google: Check Google Cloud Console > Credentials
+- Microsoft: Check Azure Portal > App registrations > Authentication
+
+### PKCE errors
+
+Authlib handles PKCE automatically. If you see PKCE errors:
+1. Clear browser cookies and sessions
+2. Ensure session middleware is registered before auth router
+3. Check that `AUTH__SESSION_SECRET` is set
+
+## References
+
+- [OAuth 2.1 Draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11)
+- [OIDC Core](https://openid.net/specs/openid-connect-core-1_0.html)
+- [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636)
+- [Authlib Documentation](https://docs.authlib.org/en/latest/)
+- [Google OAuth](https://developers.google.com/identity/protocols/oauth2)
+- [Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/)

rem/auth/__init__.py

@@ -0,0 +1,26 @@
+"""
+REM Authentication Module.
+
+OAuth 2.1 compliant authentication with support for:
+- Google OAuth
+- Microsoft Entra ID (Azure AD) OIDC
+- Custom OIDC providers
+
+Design Pattern:
+- Provider-agnostic base classes
+- PKCE (Proof Key for Code Exchange) for all flows
+- State parameter for CSRF protection
+- Nonce for ID token replay protection
+- Token validation with JWKS
+- Clean separation: providers/ for OAuth logic, middleware.py for FastAPI integration
+"""
+
+from .providers.base import OAuthProvider
+from .providers.google import GoogleOAuthProvider
+from .providers.microsoft import MicrosoftOAuthProvider
+
+__all__ = [
+    "OAuthProvider",
+    "GoogleOAuthProvider",
+    "MicrosoftOAuthProvider",
+]

rem/auth/middleware.py

@@ -0,0 +1,100 @@
+"""
+OAuth Authentication Middleware for FastAPI.
+
+Protects API endpoints by requiring valid session.
+Redirects unauthenticated requests to login page.
+
+Design Pattern:
+- Check session for user on protected paths
+- Return 401 for API calls (JSON)
+- Redirect to login for browser requests (HTML)
+- Exclude auth endpoints and public paths
+
+Usage:
+    from rem.auth.middleware import AuthMiddleware
+
+    app.add_middleware(
+        AuthMiddleware,
+        protected_paths=["/api/v1"],
+        excluded_paths=["/api/auth", "/health"],
+    )
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse
+from loguru import logger
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """
+    Authentication middleware using session-based auth.
+
+    Checks for valid user session on protected paths.
+    Compatible with OAuth flows from auth router.
+    """
+
+    def __init__(
+        self,
+        app,
+        protected_paths: list[str] | None = None,
+        excluded_paths: list[str] | None = None,
+    ):
+        """
+        Initialize auth middleware.
+
+        Args:
+            app: ASGI application
+            protected_paths: Paths that require authentication
+            excluded_paths: Paths to exclude from auth check
+        """
+        super().__init__(app)
+        self.protected_paths = protected_paths or ["/api/v1"]
+        self.excluded_paths = excluded_paths or ["/api/auth", "/health", "/docs", "/openapi.json"]
+
+    async def dispatch(self, request: Request, call_next):
+        """
+        Check authentication for protected paths.
+
+        Args:
+            request: HTTP request
+            call_next: Next middleware in chain
+
+        Returns:
+            Response (401/redirect if unauthorized, normal response if authorized)
+        """
+        path = request.url.path
+
+        # Check if path is protected
+        is_protected = any(path.startswith(p) for p in self.protected_paths)
+        is_excluded = any(path.startswith(p) for p in self.excluded_paths)
+
+        # Skip auth check for excluded paths
+        if not is_protected or is_excluded:
+            return await call_next(request)
+
+        # Check for valid session
+        user = request.session.get("user")
+        if not user:
+            logger.warning(f"Unauthorized access attempt: {path}")
+
+            # Return 401 for API requests (JSON)
+            # Check Accept header to determine if client expects JSON
+            accept = request.headers.get("accept", "")
+            if "application/json" in accept or path.startswith("/api/"):
+                return JSONResponse(
+                    status_code=401,
+                    content={"detail": "Authentication required"},
+                    headers={
+                        "WWW-Authenticate": 'Bearer realm="REM API"',
+                    },
+                )
+
+            # Redirect to login for browser requests
+            # TODO: Store original URL for post-login redirect
+            return RedirectResponse(url="/api/auth/google/login", status_code=302)
+
+        # Add user to request state for downstream handlers
+        request.state.user = user
+
+        return await call_next(request)