remdb 0.3.114__py3-none-any.whl → 0.3.172__py3-none-any.whl

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,11 @@ 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,
+    # Mutable container to capture tool calls for persistence
+    # Format: list of {"tool_name": str, "tool_id": str, "arguments": dict, "result": any}
+    tool_calls_out: list | None = None,
 ) -> AsyncGenerator[str, None]:
     """
     Stream Pydantic AI agent responses with rich SSE events.
@@ -143,6 +149,9 @@ async def stream_openai_response(
     pending_tool_completions: list[tuple[str, str]] = []
     # Track if metadata was registered via register_metadata tool
     metadata_registered = False
+    # Track pending tool calls with full data for persistence
+    # Maps tool_id -> {"tool_name": str, "tool_id": str, "arguments": dict}
+    pending_tool_data: dict[str, dict] = {}
 
     try:
         # Emit initial progress event
@@ -156,6 +165,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):
@@ -288,6 +305,13 @@ async def stream_openai_response(
                                     arguments=args_dict
                                 ))
 
+                                # Track tool call data for persistence (especially register_metadata)
+                                pending_tool_data[tool_id] = {
+                                    "tool_name": tool_name,
+                                    "tool_id": tool_id,
+                                    "arguments": args_dict,
+                                }
+
                                 # Update progress
                                 current_step = 2
                                 total_steps = 4  # Added tool execution step
@@ -366,6 +390,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 +402,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 +425,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,
@@ -406,6 +434,15 @@ async def stream_openai_response(
                                         hidden=False,
                                     ))
 
+                                # Capture tool call with result for persistence
+                                # Special handling for register_metadata - always capture full data
+                                if tool_calls_out is not None and tool_id in pending_tool_data:
+                                    tool_data = pending_tool_data[tool_id]
+                                    tool_data["result"] = result_content
+                                    tool_data["is_metadata"] = is_metadata_event
+                                    tool_calls_out.append(tool_data)
+                                    del pending_tool_data[tool_id]
+
                                 if not is_metadata_event:
                                     # Normal tool completion - emit ToolCallEvent
                                     result_str = str(result_content)
@@ -528,6 +565,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,9 +739,20 @@ 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 = []
 
+    # Capture tool calls for persistence (especially register_metadata)
+    tool_calls: list = []
+
     async for chunk in stream_openai_response(
         agent=agent,
         prompt=prompt,
@@ -709,6 +760,9 @@ 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
+        tool_calls_out=tool_calls,  # Capture tool calls for persistence
     ):
         yield chunk
 
@@ -727,22 +781,75 @@ async def stream_openai_response_with_save(
             except (json.JSONDecodeError, KeyError, IndexError):
                 pass  # Skip non-JSON or malformed chunks
 
-    # After streaming completes, save the assistant response
-    if settings.postgres.enabled and session_id and accumulated_content:
-        full_content = "".join(accumulated_content)
-        assistant_message = {
-            "role": "assistant",
-            "content": full_content,
-            "timestamp": to_iso(utc_now()),
-        }
-        try:
-            store = SessionMessageStore(user_id=user_id or settings.test.effective_user_id)
-            await store.store_session_messages(
-                session_id=session_id,
-                messages=[assistant_message],
-                user_id=user_id,
-                compress=True,  # Compress long assistant responses
-            )
-            logger.debug(f"Saved assistant response to session {session_id} ({len(full_content)} chars)")
-        except Exception as e:
-            logger.error(f"Failed to save assistant response: {e}", exc_info=True)
+    # After streaming completes, save tool calls and assistant response
+    # Note: All messages stored UNCOMPRESSED. Compression happens on reload.
+    if settings.postgres.enabled and session_id:
+        # 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")
+        timestamp = to_iso(utc_now())
+
+        messages_to_store = []
+
+        # First, store tool call messages (message_type: "tool")
+        for tool_call in tool_calls:
+            tool_message = {
+                "role": "tool",
+                "content": json.dumps(tool_call.get("result", {}), default=str),
+                "timestamp": timestamp,
+                "trace_id": captured_trace_id,
+                "span_id": captured_span_id,
+                # Store tool call details in a way that can be reconstructed
+                "tool_call_id": tool_call.get("tool_id"),
+                "tool_name": tool_call.get("tool_name"),
+                "tool_arguments": tool_call.get("arguments"),
+            }
+            messages_to_store.append(tool_message)
+
+        # Then store assistant text response (if any)
+        if accumulated_content:
+            full_content = "".join(accumulated_content)
+            assistant_message = {
+                "id": message_id,  # Use pre-generated ID for consistency with metadata event
+                "role": "assistant",
+                "content": full_content,
+                "timestamp": timestamp,
+                "trace_id": captured_trace_id,
+                "span_id": captured_span_id,
+            }
+            messages_to_store.append(assistant_message)
+
+        if messages_to_store:
+            try:
+                store = SessionMessageStore(user_id=user_id or settings.test.effective_user_id)
+                await store.store_session_messages(
+                    session_id=session_id,
+                    messages=messages_to_store,
+                    user_id=user_id,
+                    compress=False,  # Store uncompressed; compression happens on reload
+                )
+                logger.debug(
+                    f"Saved {len(tool_calls)} tool calls and "
+                    f"{'assistant response' if accumulated_content else 'no text'} "
+                    f"to session {session_id}"
+                )
+            except Exception as e:
+                logger.error(f"Failed to save session messages: {e}", exc_info=True)
+
+        # Update session description with session_name (non-blocking, after all yields)
+        for tool_call in tool_calls:
+            if tool_call.get("tool_name") == "register_metadata" and tool_call.get("is_metadata"):
+                session_name = tool_call.get("arguments", {}).get("session_name")
+                if session_name:
+                    try:
+                        from ....models.entities import Session
+                        from ....services.postgres import Repository
+                        repo = Repository(Session, table_name="sessions")
+                        session = await repo.get_by_id(session_id)
+                        if session and session.description != session_name:
+                            session.description = session_name
+                            await repo.update(session)
+                            logger.debug(f"Updated session {session_id} description to '{session_name}'")
+                    except Exception as e:
+                        logger.warning(f"Failed to update session description: {e}")
+                    break

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/api/routers/messages.py

@@ -134,7 +134,6 @@ async def list_messages(
     ),
     limit: int = Query(default=50, ge=1, le=100, description="Max results to return"),
     offset: int = Query(default=0, ge=0, description="Offset for pagination"),
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> MessageListResponse:
     """
     List messages with optional filters.
@@ -158,15 +157,18 @@ async def list_messages(
 
     repo = Repository(Message, table_name="messages")
 
+    # Get current user for logging
+    current_user = get_current_user(request)
+    jwt_user_id = current_user.get("id") if current_user else None
+
     # If mine=true, force filter to current user's ID from JWT
     effective_user_id = user_id
     if mine:
-        current_user = get_current_user(request)
         if current_user:
             effective_user_id = current_user.get("id")
 
     # Build user-scoped filters (admin can see all, regular users see only their own)
-    filters = await get_user_filter(request, x_user_id=effective_user_id, x_tenant_id=x_tenant_id)
+    filters = await get_user_filter(request, x_user_id=effective_user_id)
 
     # Apply optional filters
     if session_id:
@@ -174,6 +176,13 @@ async def list_messages(
     if message_type:
         filters["message_type"] = message_type
 
+    # Log the query parameters for debugging
+    logger.debug(
+        f"[messages] Query: session_id={session_id} | "
+        f"jwt_user_id={jwt_user_id} | "
+        f"filters={filters}"
+    )
+
     # For date filtering, we need custom SQL (not supported by basic Repository)
     # For now, fetch all matching base filters and filter in Python
     # TODO: Extend Repository to support date range filters
@@ -206,6 +215,12 @@ async def list_messages(
     # Get total count for pagination info
     total = await repo.count(filters)
 
+    # Log result count
+    logger.debug(
+        f"[messages] Result: returned={len(messages)} | total={total} | "
+        f"session_id={session_id}"
+    )
+
     return MessageListResponse(data=messages, total=total, has_more=has_more)
 
 
@@ -213,7 +228,6 @@ async def list_messages(
 async def get_message(
     request: Request,
     message_id: str,
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> Message:
     """
     Get a specific message by ID.
@@ -236,7 +250,7 @@ async def get_message(
         raise HTTPException(status_code=503, detail="Database not enabled")
 
     repo = Repository(Message, table_name="messages")
-    message = await repo.get_by_id(message_id, x_tenant_id)
+    message = await repo.get_by_id(message_id)
 
     if not message:
         raise HTTPException(status_code=404, detail=f"Message '{message_id}' not found")
@@ -263,7 +277,6 @@ async def list_sessions(
     mode: SessionMode | None = Query(default=None, description="Filter by session mode"),
     page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
     page_size: int = Query(default=50, ge=1, le=100, description="Number of results per page"),
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> SessionsQueryResponse:
     """
     List sessions with optional filters and page-based pagination.
@@ -288,7 +301,7 @@ async def list_sessions(
     repo = Repository(Session, table_name="sessions")
 
     # Build user-scoped filters (admin can see all, regular users see only their own)
-    filters = await get_user_filter(request, x_user_id=user_id, x_tenant_id=x_tenant_id)
+    filters = await get_user_filter(request, x_user_id=user_id)
     if mode:
         filters["mode"] = mode.value
 
@@ -319,7 +332,6 @@ async def create_session(
     request_body: SessionCreateRequest,
     user: dict = Depends(require_admin),
     x_user_id: str = Header(alias="X-User-Id", default="default"),
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> Session:
     """
     Create a new session.
@@ -334,7 +346,6 @@ async def create_session(
 
     Headers:
     - X-User-Id: User identifier (owner of the session)
-    - X-Tenant-Id: Tenant identifier
 
     Returns:
         Created session object
@@ -354,7 +365,7 @@ async def create_session(
         prompt=request_body.prompt,
         agent_schema_uri=request_body.agent_schema_uri,
         user_id=effective_user_id,
-        tenant_id=x_tenant_id,
+        tenant_id="default",  # tenant_id not used for filtering, set to default
     )
 
     repo = Repository(Session, table_name="sessions")
@@ -372,7 +383,6 @@ async def create_session(
 async def get_session(
     request: Request,
     session_id: str,
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> Session:
     """
     Get a specific session by ID.
@@ -395,11 +405,11 @@ async def get_session(
         raise HTTPException(status_code=503, detail="Database not enabled")
 
     repo = Repository(Session, table_name="sessions")
-    session = await repo.get_by_id(session_id, x_tenant_id)
+    session = await repo.get_by_id(session_id)
 
     if not session:
         # Try finding by name
-        sessions = await repo.find({"name": session_id, "tenant_id": x_tenant_id}, limit=1)
+        sessions = await repo.find({"name": session_id}, limit=1)
         if sessions:
             session = sessions[0]
         else:
@@ -420,7 +430,6 @@ async def update_session(
     request: Request,
     session_id: str,
     request_body: SessionUpdateRequest,
-    x_tenant_id: str = Header(alias="X-Tenant-Id", default="default"),
 ) -> Session:
     """
     Update an existing session.
@@ -450,7 +459,7 @@ async def update_session(
         raise HTTPException(status_code=503, detail="Database not enabled")
 
     repo = Repository(Session, table_name="sessions")
-    session = await repo.get_by_id(session_id, x_tenant_id)
+    session = await repo.get_by_id(session_id)
 
     if not session:
         raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")

rem/api/routers/query.py

@@ -216,7 +216,7 @@ class QueryResponse(BaseModel):
 @router.post("/query", response_model=QueryResponse)
 async def execute_query(
     request: QueryRequest,
-    x_user_id: str = Header(..., description="User ID for query isolation"),
+    x_user_id: str | None = Header(default=None, description="User ID for query isolation (optional, uses default if not provided)"),
 ) -> QueryResponse:
     """
     Execute a REM query.
@@ -265,6 +265,9 @@ async def execute_query(
 
         rem_service = RemService(db)
 
+        # Use effective_user_id from settings if not provided
+        effective_user_id = x_user_id or settings.test.effective_user_id
+
         if request.mode == QueryMode.STAGED_PLAN:
             # Staged plan mode - execute multi-stage query plan
             # TODO: Implementation pending in RemService.execute_staged_plan()
@@ -295,7 +298,7 @@ async def execute_query(
 
             result = await rem_service.ask_rem(
                 natural_query=request.query,
-                tenant_id=x_user_id,
+                tenant_id=effective_user_id,
                 llm_model=request.model,
                 plan_mode=request.plan_only,
             )
@@ -333,7 +336,7 @@ async def execute_query(
             rem_query = RemQuery.model_validate({
                 "query_type": query_type,
                 "parameters": parameters,
-                "user_id": x_user_id,
+                "user_id": effective_user_id,
             })
 
             result = await rem_service.execute_query(rem_query)

rem/auth/__init__.py

@@ -1,26 +1,36 @@
 """
 REM Authentication Module.
 
-OAuth 2.1 compliant authentication with support for:
+Authentication with support for:
+- Email passwordless login (verification codes)
 - 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
+- PKCE (Proof Key for Code Exchange) for OAuth 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
+- Clean separation: providers/ for auth logic, middleware.py for FastAPI integration
+
+Email Auth Flow:
+1. POST /api/auth/email/send-code with {email}
+2. User receives code via email
+3. POST /api/auth/email/verify with {email, code}
+4. Session created, user authenticated
 """
 
 from .providers.base import OAuthProvider
+from .providers.email import EmailAuthProvider, EmailAuthResult
 from .providers.google import GoogleOAuthProvider
 from .providers.microsoft import MicrosoftOAuthProvider
 
 __all__ = [
     "OAuthProvider",
+    "EmailAuthProvider",
+    "EmailAuthResult",
     "GoogleOAuthProvider",
     "MicrosoftOAuthProvider",
 ]