remdb 0.3.118__py3-none-any.whl → 0.3.146__py3-none-any.whl

rem/api/routers/chat/models.py

@@ -1,14 +1,38 @@
 """
 OpenAI-compatible API models for chat completions.
 
-Design Pattern 
+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.)
+- Headers map to AgentContext for session/context control
+- Body fields for OpenAI-compatible parameters + metadata
+
+Headers (context control):
+    X-User-Id        → context.user_id (user identifier)
+    X-Tenant-Id      → context.tenant_id (multi-tenancy, default: "default")
+    X-Session-Id     → context.session_id (conversation continuity)
+    X-Agent-Schema   → context.agent_schema_uri (which agent to use, default: "rem")
+    X-Model-Name     → context.default_model (model override)
+    X-Chat-Is-Audio  → triggers audio transcription ("true"/"false")
+    X-Is-Eval        → context.is_eval (marks session as evaluation, sets mode=EVALUATION)
+
+Body Fields (OpenAI-compatible + extensions):
+    model            → LLM model (e.g., "openai:gpt-4.1", "anthropic:claude-sonnet-4-5-20250929")
+    messages         → Chat conversation history
+    temperature      → Sampling temperature (0-2)
+    max_tokens       → Max tokens (deprecated, use max_completion_tokens)
+    max_completion_tokens → Max tokens to generate
+    stream           → Enable SSE streaming
+    metadata         → Key-value pairs merged with session metadata (for evals/experiments)
+    store            → Whether to store for distillation/evaluation
+    seed             → Deterministic sampling seed
+    top_p            → Nucleus sampling probability
+    reasoning_effort → low/medium/high for o-series models
+    service_tier     → auto/flex/priority/default
 """
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
@@ -46,10 +70,17 @@ class ChatCompletionRequest(BaseModel):
     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
+        X-User-Id        → context.user_id
+        X-Tenant-Id      → context.tenant_id (default: "default")
+        X-Session-Id     → context.session_id
+        X-Agent-Schema   → context.agent_schema_uri (default: "rem")
+        X-Model-Name     → context.default_model
+        X-Chat-Is-Audio  → triggers audio transcription
+        X-Is-Eval        → context.is_eval (sets session mode=EVALUATION)
+
+    Body Fields for Metadata/Evals:
+        metadata         → Key-value pairs merged with session metadata
+        store            → Whether to store for distillation/evaluation
 
     Note: Model is specified in body.model (standard OpenAI field), not headers.
     """
@@ -73,6 +104,49 @@ class ChatCompletionRequest(BaseModel):
         default=None,
         description="Response format. Set type='json_object' to enable JSON mode.",
     )
+    # Additional OpenAI-compatible fields
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description="Key-value pairs attached to the request (max 16 keys, 64/512 char limits). "
+        "Merged with session metadata for persistence.",
+    )
+    store: bool | None = Field(
+        default=None,
+        description="Whether to store for distillation/evaluation purposes.",
+    )
+    max_completion_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description="Max tokens to generate (replaces deprecated max_tokens).",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Seed for deterministic sampling (best effort).",
+    )
+    top_p: float | None = Field(
+        default=None,
+        ge=0,
+        le=1,
+        description="Nucleus sampling probability. Use temperature OR top_p, not both.",
+    )
+    logprobs: bool | None = Field(
+        default=None,
+        description="Whether to return log probabilities for output tokens.",
+    )
+    top_logprobs: int | None = Field(
+        default=None,
+        ge=0,
+        le=20,
+        description="Number of most likely tokens to return at each position (requires logprobs=true).",
+    )
+    reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+        default=None,
+        description="Reasoning effort for o-series models (low/medium/high).",
+    )
+    service_tier: Literal["auto", "flex", "priority", "default"] | None = Field(
+        default=None,
+        description="Service tier for processing (flex is 50% cheaper but slower).",
+    )
 
 
 # Response models

rem/api/routers/chat/otel_utils.py

@@ -0,0 +1,33 @@
+"""OTEL utilities for chat routers."""
+
+from loguru import logger
+
+
+def get_tracer():
+    """Get the OpenTelemetry tracer for chat completions."""
+    try:
+        from opentelemetry import trace
+        return trace.get_tracer("rem.chat.completions")
+    except Exception:
+        return None
+
+
+def get_current_trace_context() -> tuple[str | None, str | None]:
+    """Get trace_id and span_id from current OTEL context.
+
+    Returns:
+        Tuple of (trace_id, span_id) as hex strings, or (None, None) if not available.
+    """
+    try:
+        from opentelemetry import trace
+
+        span = trace.get_current_span()
+        ctx = span.get_span_context()
+        if ctx.is_valid:
+            trace_id = format(ctx.trace_id, '032x')
+            span_id = format(ctx.span_id, '016x')
+            return trace_id, span_id
+    except Exception as e:
+        logger.debug(f"Could not get trace context: {e}")
+
+    return None, None

rem/api/routers/chat/sse_events.py

@@ -321,7 +321,13 @@ class MetadataEvent(BaseModel):
     # Agent info
     agent_schema: str | None = Field(
         default=None,
-        description="Name of the agent schema used for this response (e.g., 'rem', 'Siggy')"
+        description="Name of the agent schema used for this response (e.g., 'rem', 'query-assistant')"
+    )
+
+    # Session info
+    session_name: str | None = Field(
+        default=None,
+        description="Short 1-3 phrase name for the session topic (e.g., 'Prescription Drug Questions', 'AWS Setup Help')"
     )
 
     # Quality indicators
@@ -350,6 +356,16 @@ class MetadataEvent(BaseModel):
         description="Token count for this response"
     )
 
+    # Trace context for observability (deterministic, captured from OTEL)
+    trace_id: str | None = Field(
+        default=None,
+        description="OTEL trace ID for correlating with Phoenix/observability systems"
+    )
+    span_id: str | None = Field(
+        default=None,
+        description="OTEL span ID for correlating with Phoenix/observability systems"
+    )
+
     # System flags
     flags: list[str] | None = Field(
         default=None,

rem/api/routers/chat/streaming.py

@@ -47,6 +47,7 @@ from pydantic_ai.messages import (
     ToolCallPart,
 )
 
+from .otel_utils import get_current_trace_context, get_tracer
 from .models import (
     ChatCompletionMessageDelta,
     ChatCompletionStreamChoice,
@@ -73,6 +74,8 @@ async def stream_openai_response(
     session_id: str | None = None,
     # Agent info for metadata
     agent_schema: str | None = None,
+    # Mutable container to capture trace context (deterministic, not AI-dependent)
+    trace_context_out: dict | None = None,
 ) -> AsyncGenerator[str, None]:
     """
     Stream Pydantic AI agent responses with rich SSE events.
@@ -156,6 +159,14 @@ async def stream_openai_response(
 
         # Use agent.iter() to get complete execution with tool calls
         async with agent.iter(prompt) as agent_run:
+            # Capture trace context IMMEDIATELY inside agent execution
+            # This is deterministic - it's the OTEL context from Pydantic AI instrumentation
+            # NOT dependent on any AI-generated content
+            captured_trace_id, captured_span_id = get_current_trace_context()
+            if trace_context_out is not None:
+                trace_context_out["trace_id"] = captured_trace_id
+                trace_context_out["span_id"] = captured_span_id
+
             async for node in agent_run:
                 # Check if this is a model request node (includes tool calls)
                 if Agent.is_model_request_node(node):
@@ -366,6 +377,8 @@ async def stream_openai_response(
                                     registered_sources = result_content.get("sources")
                                     registered_references = result_content.get("references")
                                     registered_flags = result_content.get("flags")
+                                    # Session naming
+                                    registered_session_name = result_content.get("session_name")
                                     # Risk assessment fields
                                     registered_risk_level = result_content.get("risk_level")
                                     registered_risk_score = result_content.get("risk_score")
@@ -376,6 +389,7 @@ async def stream_openai_response(
 
                                     logger.info(
                                         f"📊 Metadata registered: confidence={registered_confidence}, "
+                                        f"session_name={registered_session_name}, "
                                         f"risk_level={registered_risk_level}, sources={registered_sources}"
                                     )
 
@@ -398,6 +412,7 @@ async def stream_openai_response(
                                         in_reply_to=in_reply_to,
                                         session_id=session_id,
                                         agent_schema=agent_schema,
+                                        session_name=registered_session_name,
                                         confidence=registered_confidence,
                                         sources=registered_sources,
                                         model_version=model,
@@ -528,6 +543,9 @@ async def stream_openai_response(
                 model_version=model,
                 latency_ms=latency_ms,
                 token_count=token_count,
+                # Include deterministic trace context captured from OTEL
+                trace_id=captured_trace_id,
+                span_id=captured_span_id,
             ))
 
         # Mark all progress complete
@@ -699,6 +717,14 @@ async def stream_openai_response_with_save(
     from ....services.session import SessionMessageStore
     from ....settings import settings
 
+    # Pre-generate message_id so it can be sent in metadata event
+    # This allows frontend to use it for feedback before DB persistence
+    message_id = str(uuid.uuid4())
+
+    # Mutable container for capturing trace context from inside agent execution
+    # This is deterministic - captured from OTEL instrumentation, not AI-generated
+    trace_context: dict = {}
+
     # Accumulate content during streaming
     accumulated_content = []
 
@@ -709,6 +735,8 @@ async def stream_openai_response_with_save(
         request_id=request_id,
         agent_schema=agent_schema,
         session_id=session_id,
+        message_id=message_id,
+        trace_context_out=trace_context,  # Pass container to capture trace IDs
     ):
         yield chunk
 
@@ -730,10 +758,16 @@ async def stream_openai_response_with_save(
     # After streaming completes, save the assistant response
     if settings.postgres.enabled and session_id and accumulated_content:
         full_content = "".join(accumulated_content)
+        # Get captured trace context from container (deterministically captured inside agent execution)
+        captured_trace_id = trace_context.get("trace_id")
+        captured_span_id = trace_context.get("span_id")
         assistant_message = {
+            "id": message_id,  # Use pre-generated ID for consistency with metadata event
             "role": "assistant",
             "content": full_content,
             "timestamp": to_iso(utc_now()),
+            "trace_id": captured_trace_id,
+            "span_id": captured_span_id,
         }
         try:
             store = SessionMessageStore(user_id=user_id or settings.test.effective_user_id)
@@ -743,6 +777,6 @@ async def stream_openai_response_with_save(
                 user_id=user_id,
                 compress=True,  # Compress long assistant responses
             )
-            logger.debug(f"Saved assistant response to session {session_id} ({len(full_content)} chars)")
+            logger.debug(f"Saved assistant response {message_id} to session {session_id} ({len(full_content)} chars)")
         except Exception as e:
             logger.error(f"Failed to save assistant response: {e}", exc_info=True)

rem/api/routers/feedback.py

@@ -7,16 +7,64 @@ Endpoints:
     POST /api/v1/messages/feedback - Submit feedback on a message
 
 Trace Integration:
-- Feedback can reference trace_id/span_id for OTEL integration
-- Phoenix sync attaches feedback as span annotations (async)
+- Feedback auto-resolves trace_id/span_id from the message in the database
+- Phoenix sync attaches feedback as span annotations when trace info is available
+
+HTTP Status Codes:
+- 201: Feedback saved AND synced to Phoenix as annotation (phoenix_synced=true)
+- 200: Feedback accepted and saved to DB, but NOT synced to Phoenix
+       (missing trace_id/span_id, Phoenix disabled, or sync failed)
+
+IMPORTANT - Testing Requirements:
+    ╔════════════════════════════════════════════════════════════════════════════════════════════════════╗
+    ║  1. Use 'rem' agent (NOT 'simulator') - only real agents capture traces                            ║
+    ║  2. Session IDs MUST be UUIDs - use python3 -c "import uuid; print(uuid.uuid4())"                  ║
+    ║  3. Port-forward OTEL collector: kubectl port-forward -n observability                             ║
+    ║       svc/otel-collector-collector 4318:4318                                                       ║
+    ║  4. Port-forward Phoenix: kubectl port-forward -n siggy svc/phoenix 6006:6006                      ║
+    ║  5. Set environment variables when starting the API:                                               ║
+    ║       OTEL__ENABLED=true PHOENIX__ENABLED=true PHOENIX_API_KEY=<jwt> uvicorn ...                   ║
+    ║  6. Get PHOENIX_API_KEY:                                                                           ║
+    ║       kubectl get secret -n siggy rem-phoenix-api-key -o jsonpath='{.data.PHOENIX_API_KEY}'        ║
+    ║         | base64 -d                                                                                ║
+    ╚════════════════════════════════════════════════════════════════════════════════════════════════════╝
+
+Usage:
+    # 1. Send a chat message with X-Session-Id header (MUST be UUID!)
+    SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
+    curl -X POST http://localhost:8000/api/v1/chat/completions \\
+        -H "Content-Type: application/json" \\
+        -H "X-Session-Id: $SESSION_ID" \\
+        -H "X-Agent-Schema: rem" \\
+        -d '{"messages": [{"role": "user", "content": "hello"}], "stream": true}'
+
+    # 2. Extract message_id from the 'metadata' SSE event:
+    #    event: metadata
+    #    data: {"message_id": "728882f8-...", "trace_id": "e53c701c...", ...}
+
+    # 3. Submit feedback referencing that message (trace_id auto-resolved from DB)
+    curl -X POST http://localhost:8000/api/v1/messages/feedback \\
+        -H "Content-Type: application/json" \\
+        -H "X-Tenant-Id: default" \\
+        -d '{
+            "session_id": "'$SESSION_ID'",
+            "message_id": "<message-id-from-metadata>",
+            "rating": 1,
+            "categories": ["helpful"],
+            "comment": "Great response!"
+        }'
+
+    # 4. Check response:
+    #    - 201 + phoenix_synced=true = annotation synced to Phoenix (check Phoenix UI at :6006)
+    #    - 200 + phoenix_synced=false = feedback saved but not synced (missing trace info)
 """
 
-from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi import APIRouter, Header, HTTPException, Request, Response
 from loguru import logger
 from pydantic import BaseModel, Field
 
 from ..deps import get_user_id_from_request
-from ...models.entities import Feedback, Message
+from ...models.entities import Feedback
 from ...services.postgres import Repository
 from ...settings import settings
 
@@ -73,9 +121,10 @@ class FeedbackResponse(BaseModel):
 # =============================================================================
 
 
-@router.post("/messages/feedback", response_model=FeedbackResponse, status_code=201)
+@router.post("/messages/feedback", response_model=FeedbackResponse)
 async def submit_feedback(
     request: Request,
+    response: Response,
     request_body: FeedbackCreateRequest,
     x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> FeedbackResponse:
@@ -89,8 +138,12 @@ async def submit_feedback(
     - Provided explicitly in the request
     - Auto-resolved from the message if message_id is provided
 
+    HTTP Status Codes:
+    - 201: Feedback saved AND synced to Phoenix (phoenix_synced=true)
+    - 200: Feedback accepted but NOT synced (missing trace info, disabled, or failed)
+
     Returns:
-        Created feedback object
+        Created feedback object with phoenix_synced indicating sync status
     """
     if not settings.postgres.enabled:
         raise HTTPException(status_code=503, detail="Database not enabled")
@@ -102,11 +155,44 @@ async def submit_feedback(
     span_id = request_body.span_id
 
     if request_body.message_id and (not trace_id or not span_id):
-        message_repo = Repository(Message, table_name="messages")
-        message = await message_repo.get_by_id(request_body.message_id, x_tenant_id)
-        if message:
-            trace_id = trace_id or message.trace_id
-            span_id = span_id or message.span_id
+        # Look up message by ID to get trace context
+        # Note: Messages are stored with tenant_id=user_id (not x_tenant_id header)
+        # so we query by ID only - UUIDs are globally unique
+        from ...services.postgres import PostgresService
+        import uuid
+
+        logger.info(f"Looking up trace context for message_id={request_body.message_id}")
+
+        # Convert message_id string to UUID for database query
+        try:
+            message_uuid = uuid.UUID(request_body.message_id)
+        except ValueError as e:
+            logger.warning(f"Invalid message_id format '{request_body.message_id}': {e}")
+            message_uuid = None
+
+        if message_uuid:
+            db = PostgresService()
+            # Ensure connection (same pattern as Repository)
+            if not db.pool:
+                await db.connect()
+
+            if db.pool:
+                query = """
+                    SELECT trace_id, span_id FROM messages
+                    WHERE id = $1 AND deleted_at IS NULL
+                    LIMIT 1
+                """
+                async with db.pool.acquire() as conn:
+                    row = await conn.fetchrow(query, message_uuid)
+                    logger.info(f"Database query result for message {request_body.message_id}: row={row}")
+                    if row:
+                        trace_id = trace_id or row["trace_id"]
+                        span_id = span_id or row["span_id"]
+                        logger.info(f"Found trace context for message {request_body.message_id}: trace_id={trace_id}, span_id={span_id}")
+                    else:
+                        logger.warning(f"No message found in database with id={request_body.message_id}")
+            else:
+                logger.warning(f"Database pool not available for message lookup after connect attempt")
 
     feedback = Feedback(
         session_id=request_body.session_id,
@@ -130,9 +216,43 @@ async def submit_feedback(
         f"message={request_body.message_id}, rating={request_body.rating}"
     )
 
-    # TODO: Async sync to Phoenix if trace_id/span_id available
-    if trace_id and span_id:
-        logger.debug(f"Feedback has trace info: trace={trace_id}, span={span_id}")
+    # Sync to Phoenix if trace_id/span_id available and Phoenix is enabled
+    phoenix_synced = False
+    phoenix_annotation_id = None
+
+    if trace_id and span_id and settings.phoenix.enabled:
+        try:
+            from ...services.phoenix import PhoenixClient
+
+            phoenix_client = PhoenixClient()
+            phoenix_annotation_id = phoenix_client.sync_user_feedback(
+                span_id=span_id,
+                rating=request_body.rating,
+                categories=request_body.categories,
+                comment=request_body.comment,
+                feedback_id=str(result.id),
+                trace_id=trace_id,
+            )
+
+            if phoenix_annotation_id:
+                phoenix_synced = True
+                # Update the feedback record with sync status
+                result.phoenix_synced = True
+                result.phoenix_annotation_id = phoenix_annotation_id
+                await repo.upsert(result)
+                logger.info(f"Feedback synced to Phoenix: annotation_id={phoenix_annotation_id}")
+            else:
+                logger.warning(f"Phoenix sync returned no annotation ID for feedback {result.id}")
+
+        except Exception as e:
+            logger.error(f"Failed to sync feedback to Phoenix: {e}")
+            # Don't fail the request if Phoenix sync fails
+    elif trace_id and span_id:
+        logger.debug(f"Feedback has trace info but Phoenix disabled: trace={trace_id}, span={span_id}")
+
+    # Set HTTP status code based on Phoenix sync result
+    # 201 = synced to Phoenix, 200 = accepted but not synced
+    response.status_code = 201 if phoenix_synced else 200
 
     return FeedbackResponse(
         id=str(result.id),

rem/auth/middleware.py

@@ -6,6 +6,7 @@ Supports anonymous access with rate limiting when allow_anonymous=True.
 MCP endpoints are always protected unless explicitly disabled.
 
 Design Pattern:
+- Check X-API-Key header first (if API key auth enabled)
 - Check session for user on protected paths
 - Check Bearer token for dev token (non-production only)
 - MCP paths always require authentication (protected service)
@@ -20,6 +21,12 @@ Access Modes (configured in settings.auth):
 - mcp_requires_auth=true (default): MCP always requires login regardless of allow_anonymous
 - mcp_requires_auth=false: MCP follows normal allow_anonymous rules (dev only)
 
+API Key Authentication (configured in settings.api):
+- api_key_enabled=true: Require X-API-Key header for protected endpoints
+- api_key: The secret key to validate against
+- Provides simple programmatic access without OAuth flow
+- X-API-Key header takes precedence over session auth
+
 Dev Token Support (non-production only):
 - GET /api/auth/dev/token returns a Bearer token for test-user
 - Include as: Authorization: Bearer dev_<signature>
@@ -82,6 +89,39 @@ class AuthMiddleware(BaseHTTPMiddleware):
         self.mcp_requires_auth = mcp_requires_auth
         self.mcp_path = mcp_path
 
+    def _check_api_key(self, request: Request) -> dict | None:
+        """
+        Check for valid X-API-Key header.
+
+        Returns:
+            API key user dict if valid, None otherwise
+        """
+        # Only check if API key auth is enabled
+        if not settings.api.api_key_enabled:
+            return None
+
+        # Check for X-API-Key header
+        api_key = request.headers.get("x-api-key")
+        if not api_key:
+            return None
+
+        # Validate against configured API key
+        if settings.api.api_key and api_key == settings.api.api_key:
+            logger.debug("X-API-Key authenticated")
+            return {
+                "id": "api-key-user",
+                "email": "api@rem.local",
+                "name": "API Key User",
+                "provider": "api-key",
+                "tenant_id": "default",
+                "tier": "pro",  # API key users get full access
+                "roles": ["user"],
+            }
+
+        # Invalid API key
+        logger.warning("Invalid X-API-Key provided")
+        return None
+
     def _check_dev_token(self, request: Request) -> dict | None:
         """
         Check for valid dev token in Authorization header (non-production only).
@@ -105,7 +145,7 @@ class AuthMiddleware(BaseHTTPMiddleware):
         # Verify dev token
         from ..api.routers.dev import verify_dev_token
         if verify_dev_token(token):
-            logger.debug(f"Dev token authenticated as test-user")
+            logger.debug("Dev token authenticated as test-user")
             return {
                 "id": "test-user",
                 "email": "test@rem.local",
@@ -142,6 +182,31 @@ class AuthMiddleware(BaseHTTPMiddleware):
         if not is_protected or is_excluded:
             return await call_next(request)
 
+        # Check for X-API-Key header first (if enabled)
+        api_key_user = self._check_api_key(request)
+        if api_key_user:
+            request.state.user = api_key_user
+            request.state.is_anonymous = False
+            return await call_next(request)
+
+        # If API key auth is enabled but no valid key provided, reject immediately
+        if settings.api.api_key_enabled:
+            # Check if X-API-Key header was provided but invalid
+            if request.headers.get("x-api-key"):
+                logger.warning(f"Invalid X-API-Key for: {path}")
+                return JSONResponse(
+                    status_code=401,
+                    content={"detail": "Invalid API key"},
+                    headers={"WWW-Authenticate": 'ApiKey realm="REM API"'},
+                )
+            # No API key provided when required
+            logger.debug(f"Missing X-API-Key for: {path}")
+            return JSONResponse(
+                status_code=401,
+                content={"detail": "API key required. Include X-API-Key header."},
+                headers={"WWW-Authenticate": 'ApiKey realm="REM API"'},
+            )
+
         # Check for dev token (non-production only)
         dev_user = self._check_dev_token(request)
         if dev_user: