remdb 0.3.202__py3-none-any.whl → 0.3.226__py3-none-any.whl

rem/api/routers/admin.py

@@ -31,6 +31,8 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Background
 from loguru import logger
 from pydantic import BaseModel
 
+from .common import ErrorResponse
+
 from ..deps import require_admin
 from ...models.entities import Message, Session, SessionMode
 from ...services.postgres import Repository
@@ -103,7 +105,13 @@ class SystemStats(BaseModel):
 # =============================================================================
 
 
-@router.get("/users", response_model=UserListResponse)
+@router.get(
+    "/users",
+    response_model=UserListResponse,
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def list_all_users(
     user: dict = Depends(require_admin),
     limit: int = Query(default=50, ge=1, le=100),
@@ -155,7 +163,13 @@ async def list_all_users(
     return UserListResponse(data=summaries, total=total, has_more=has_more)
 
 
-@router.get("/sessions", response_model=SessionListResponse)
+@router.get(
+    "/sessions",
+    response_model=SessionListResponse,
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def list_all_sessions(
     user: dict = Depends(require_admin),
     user_id: str | None = Query(default=None, description="Filter by user ID"),
@@ -202,7 +216,13 @@ async def list_all_sessions(
     return SessionListResponse(data=sessions, total=total, has_more=has_more)
 
 
-@router.get("/messages", response_model=MessageListResponse)
+@router.get(
+    "/messages",
+    response_model=MessageListResponse,
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def list_all_messages(
     user: dict = Depends(require_admin),
     user_id: str | None = Query(default=None, description="Filter by user ID"),
@@ -252,7 +272,13 @@ async def list_all_messages(
     return MessageListResponse(data=messages, total=total, has_more=has_more)
 
 
-@router.get("/stats", response_model=SystemStats)
+@router.get(
+    "/stats",
+    response_model=SystemStats,
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def get_system_stats(
     user: dict = Depends(require_admin),
 ) -> SystemStats:

rem/api/routers/auth.py

@@ -101,6 +101,8 @@ from authlib.integrations.starlette_client import OAuth
 from pydantic import BaseModel, EmailStr
 from loguru import logger
 
+from .common import ErrorResponse
+
 from ...settings import settings
 from ...services.postgres.service import PostgresService
 from ...services.user_service import UserService
@@ -159,7 +161,14 @@ class EmailVerifyRequest(BaseModel):
     code: str
 
 
-@router.post("/email/send-code")
+@router.post(
+    "/email/send-code",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid request or email rejected"},
+        500: {"model": ErrorResponse, "description": "Failed to send login code"},
+        501: {"model": ErrorResponse, "description": "Email auth or database not configured"},
+    },
+)
 async def send_email_code(request: Request, body: EmailSendCodeRequest):
     """
     Send a login code to an email address.
@@ -221,7 +230,14 @@ async def send_email_code(request: Request, body: EmailSendCodeRequest):
         await db.disconnect()
 
 
-@router.post("/email/verify")
+@router.post(
+    "/email/verify",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid or expired code"},
+        500: {"model": ErrorResponse, "description": "Failed to verify login code"},
+        501: {"model": ErrorResponse, "description": "Email auth or database not configured"},
+    },
+)
 async def verify_email_code(request: Request, body: EmailVerifyRequest):
     """
     Verify login code and create session with JWT tokens.
@@ -319,7 +335,13 @@ async def verify_email_code(request: Request, body: EmailVerifyRequest):
 # =============================================================================
 
 
-@router.get("/{provider}/login")
+@router.get(
+    "/{provider}/login",
+    responses={
+        400: {"model": ErrorResponse, "description": "Unknown OAuth provider"},
+        501: {"model": ErrorResponse, "description": "Authentication is disabled"},
+    },
+)
 async def login(provider: str, request: Request):
     """
     Initiate OAuth flow with provider.
@@ -361,7 +383,13 @@ async def login(provider: str, request: Request):
     return await client.authorize_redirect(request, redirect_uri)
 
 
-@router.get("/{provider}/callback")
+@router.get(
+    "/{provider}/callback",
+    responses={
+        400: {"model": ErrorResponse, "description": "Authentication failed or unknown provider"},
+        501: {"model": ErrorResponse, "description": "Authentication is disabled"},
+    },
+)
 async def callback(provider: str, request: Request):
     """
     OAuth callback endpoint.
@@ -498,7 +526,12 @@ async def logout(request: Request):
     return {"message": "Logged out successfully"}
 
 
-@router.get("/me")
+@router.get(
+    "/me",
+    responses={
+        401: {"model": ErrorResponse, "description": "Not authenticated"},
+    },
+)
 async def me(request: Request):
     """
     Get current user information from session or JWT.
@@ -536,7 +569,12 @@ class TokenRefreshRequest(BaseModel):
     refresh_token: str
 
 
-@router.post("/token/refresh")
+@router.post(
+    "/token/refresh",
+    responses={
+        401: {"model": ErrorResponse, "description": "Invalid or expired refresh token"},
+    },
+)
 async def refresh_token(body: TokenRefreshRequest):
     """
     Refresh access token using refresh token.
@@ -601,7 +639,12 @@ async def refresh_token(body: TokenRefreshRequest):
     return result
 
 
-@router.post("/token/verify")
+@router.post(
+    "/token/verify",
+    responses={
+        401: {"model": ErrorResponse, "description": "Missing, invalid, or expired token"},
+    },
+)
 async def verify_token(request: Request):
     """
     Verify an access token is valid.
@@ -665,7 +708,12 @@ def verify_dev_token(token: str) -> bool:
     return token == expected
 
 
-@router.get("/dev/token")
+@router.get(
+    "/dev/token",
+    responses={
+        401: {"model": ErrorResponse, "description": "Dev tokens not available in production"},
+    },
+)
 async def get_dev_token(request: Request):
     """
     Get a development token for testing (non-production only).
@@ -701,7 +749,13 @@ async def get_dev_token(request: Request):
     }
 
 
-@router.get("/dev/mock-code/{email}")
+@router.get(
+    "/dev/mock-code/{email}",
+    responses={
+        401: {"model": ErrorResponse, "description": "Mock codes not available in production"},
+        404: {"model": ErrorResponse, "description": "No code found for email"},
+    },
+)
 async def get_mock_code(email: str, request: Request):
     """
     Get the mock login code for testing (non-production only).

rem/api/routers/chat/completions.py

@@ -164,7 +164,7 @@ from .models import (
     ChatCompletionUsage,
     ChatMessage,
 )
-from .streaming import stream_openai_response, stream_openai_response_with_save, stream_simulator_response
+from .streaming import stream_openai_response, stream_openai_response_with_save, stream_simulator_response, save_user_message
 
 router = APIRouter(prefix="/api/v1", tags=["chat"])
 
@@ -215,7 +215,7 @@ async def ensure_session_with_metadata(
     Merges request metadata with existing session metadata.
 
     Args:
-        session_id: Session identifier (maps to Session.name)
+        session_id: Session UUID from X-Session-Id header
         user_id: User identifier
         tenant_id: Tenant identifier
         is_eval: Whether this is an evaluation session
@@ -228,12 +228,8 @@ async def ensure_session_with_metadata(
     try:
         repo = Repository(Session, table_name="sessions")
 
-        # Try to load existing session by name (session_id is the name field)
-        existing_list = await repo.find(
-            filters={"name": session_id, "tenant_id": tenant_id},
-            limit=1,
-        )
-        existing = existing_list[0] if existing_list else None
+        # Look up session by UUID (id field)
+        existing = await repo.get_by_id(session_id)
 
         if existing:
             # Merge metadata if provided
@@ -254,9 +250,10 @@ async def ensure_session_with_metadata(
                 await repo.upsert(existing)
                 logger.debug(f"Updated session {session_id} (eval={is_eval}, metadata keys={list(merged_metadata.keys())})")
         else:
-            # Create new session
+            # Create new session with the provided UUID as the id
             session = Session(
-                name=session_id,
+                id=session_id,  # Use the provided UUID as session id
+                name=session_id,  # Default name to UUID, can be updated later with LLM-generated name
                 mode=SessionMode.EVALUATION if is_eval else SessionMode.NORMAL,
                 user_id=user_id,
                 tenant_id=tenant_id,
@@ -513,7 +510,7 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
 
     # Load raw session history for proper pydantic-ai message_history format
     # This enables proper tool call/return pairing for LLM API compatibility
-    from ....services.session import SessionMessageStore, session_to_pydantic_messages
+    from ....services.session import SessionMessageStore, session_to_pydantic_messages, audit_session_history
     from ....agentic.schema import get_system_prompt
 
     pydantic_message_history = None
@@ -535,6 +532,15 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
                     system_prompt=agent_system_prompt,
                 )
                 logger.debug(f"Converted {len(raw_session_history)} session messages to {len(pydantic_message_history)} pydantic-ai messages (with system prompt)")
+
+                # Audit session history if enabled (for debugging)
+                audit_session_history(
+                    session_id=context.session_id,
+                    agent_name=schema_name or "default",
+                    prompt=body.messages[-1].content if body.messages else "",
+                    raw_session_history=raw_session_history,
+                    pydantic_messages_count=len(pydantic_message_history),
+                )
         except Exception as e:
             logger.warning(f"Failed to load session history for message_history: {e}")
             # Fall back to old behavior (concatenated prompt)
@@ -576,24 +582,13 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
 
     # Streaming mode
     if body.stream:
-        # Save user message before streaming starts
-        if settings.postgres.enabled and context.session_id:
-            user_message = {
-                "role": "user",
-                "content": body.messages[-1].content if body.messages else "",
-                "timestamp": datetime.utcnow().isoformat(),
-            }
-            try:
-                store = SessionMessageStore(user_id=context.user_id or settings.test.effective_user_id)
-                await store.store_session_messages(
-                    session_id=context.session_id,
-                    messages=[user_message],
-                    user_id=context.user_id,
-                    compress=False,  # User messages are typically short
-                )
-                logger.debug(f"Saved user message to session {context.session_id}")
-            except Exception as e:
-                logger.error(f"Failed to save user message: {e}", exc_info=True)
+        # Save user message before streaming starts (using shared utility)
+        if context.session_id:
+            await save_user_message(
+                session_id=context.session_id,
+                user_id=context.user_id,
+                content=body.messages[-1].content if body.messages else "",
+            )
 
         return StreamingResponse(
             stream_openai_response_with_save(

rem/api/routers/chat/sse_events.py

@@ -321,7 +321,11 @@ 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', 'query-assistant')"
+        description="Name of the top-level agent schema (e.g., 'siggy', 'rem')"
+    )
+    responding_agent: str | None = Field(
+        default=None,
+        description="Name of the agent that produced this response (may differ from agent_schema if delegated via ask_agent)"
     )
 
     # Session info

rem/api/routers/chat/streaming.py

@@ -165,12 +165,14 @@ 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 which agent is actually responding (may be child agent if delegated)
+    responding_agent: str | None = None
     # 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] = {}
 
     # Import context functions for multi-agent support
-    from ....agentic.context import set_current_context
+    from ....agentic.context import set_current_context, set_event_sink
 
     # Set up context for multi-agent propagation
     # This allows child agents (via ask_agent tool) to access parent context
@@ -180,6 +182,12 @@ async def stream_openai_response(
         previous_context = get_current_context()
         set_current_context(agent_context)
 
+    # Set up event sink for child agent event proxying
+    # Child agents (via ask_agent) will push their events here
+    import asyncio
+    child_event_sink: asyncio.Queue = asyncio.Queue()
+    set_event_sink(child_event_sink)
+
     try:
         # Emit initial progress event
         current_step = 1
@@ -419,6 +427,73 @@ async def stream_openai_response(
                 elif Agent.is_call_tools_node(node):
                     async with node.stream(agent_run.ctx) as tools_stream:
                         async for tool_event in tools_stream:
+                            # First, drain any child agent events that were pushed while tool was executing
+                            # This handles ask_agent streaming - child events are proxied here
+                            while not child_event_sink.empty():
+                                try:
+                                    child_event = child_event_sink.get_nowait()
+                                    event_type = child_event.get("type", "")
+                                    child_agent = child_event.get("agent_name", "child")
+
+                                    if event_type == "child_tool_start":
+                                        # Emit child tool start as a nested tool call
+                                        child_tool_id = f"call_{uuid.uuid4().hex[:8]}"
+                                        # Ensure arguments is a dict or None (not empty string)
+                                        child_args = child_event.get("arguments")
+                                        if not isinstance(child_args, dict):
+                                            child_args = None
+                                        yield format_sse_event(ToolCallEvent(
+                                            tool_name=f"{child_agent}:{child_event.get('tool_name', 'tool')}",
+                                            tool_id=child_tool_id,
+                                            status="started",
+                                            arguments=child_args,
+                                        ))
+                                    elif event_type == "child_content":
+                                        # Emit child content as assistant content
+                                        # Track which child agent is responding
+                                        responding_agent = child_agent
+                                        content = child_event.get("content", "")
+                                        if content:
+                                            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=content,
+                                                        ),
+                                                        finish_reason=None,
+                                                    )
+                                                ],
+                                            )
+                                            is_first_chunk = False
+                                            yield f"data: {content_chunk.model_dump_json()}\n\n"
+                                    elif event_type == "child_tool_result":
+                                        # Emit child tool completion
+                                        result = child_event.get("result", {})
+                                        # Emit metadata event for child agent if it registered metadata
+                                        if isinstance(result, dict) and result.get("_metadata_event"):
+                                            responding_agent = result.get("agent_schema") or responding_agent
+                                            yield format_sse_event(MetadataEvent(
+                                                message_id=message_id,
+                                                session_id=session_id,
+                                                agent_schema=agent_schema,
+                                                responding_agent=responding_agent,
+                                                confidence=result.get("confidence"),
+                                                extra={"risk_level": result.get("risk_level")} if result.get("risk_level") else None,
+                                            ))
+                                        yield format_sse_event(ToolCallEvent(
+                                            tool_name=f"{child_agent}:tool",
+                                            tool_id=f"call_{uuid.uuid4().hex[:8]}",
+                                            status="completed",
+                                            result=str(result)[:200] if result else None,
+                                        ))
+                                except Exception as e:
+                                    logger.warning(f"Error processing child event: {e}")
+
                             # Tool result event - emit completion
                             if isinstance(tool_event, FunctionToolResultEvent):
                                 # Get the tool name/id from the pending queue (FIFO)
@@ -451,6 +526,10 @@ async def stream_openai_response(
                                     registered_recommended_action = result_content.get("recommended_action")
                                     # Extra fields
                                     registered_extra = result_content.get("extra")
+                                    # Only set responding_agent if not already set by child events
+                                    # Child agents should take precedence - they're the actual responders
+                                    if not responding_agent:
+                                        responding_agent = result_content.get("agent_schema")
 
                                     logger.info(
                                         f"📊 Metadata registered: confidence={registered_confidence}, "
@@ -477,6 +556,7 @@ async def stream_openai_response(
                                         in_reply_to=in_reply_to,
                                         session_id=session_id,
                                         agent_schema=agent_schema,
+                                        responding_agent=responding_agent,
                                         session_name=registered_session_name,
                                         confidence=registered_confidence,
                                         sources=registered_sources,
@@ -502,6 +582,11 @@ async def stream_openai_response(
                                     del pending_tool_data[tool_id]
 
                                 if not is_metadata_event:
+                                    # NOTE: text_response fallback is DISABLED
+                                    # Child agents now stream content via child_content events (above)
+                                    # which provides real-time streaming. The text_response in tool
+                                    # result would duplicate that content, so we skip it entirely.
+
                                     # Normal tool completion - emit ToolCallEvent
                                     # For finalize_intake, send full result dict for frontend
                                     if tool_name == "finalize_intake" and isinstance(result_content, dict):
@@ -624,6 +709,7 @@ async def stream_openai_response(
                 in_reply_to=in_reply_to,
                 session_id=session_id,
                 agent_schema=agent_schema,
+                responding_agent=responding_agent,
                 confidence=1.0,  # Default to 100% confidence
                 model_version=model,
                 latency_ms=latency_ms,
@@ -716,6 +802,8 @@ async def stream_openai_response(
         yield "data: [DONE]\n\n"
 
     finally:
+        # Clean up event sink for multi-agent streaming
+        set_event_sink(None)
         # Restore previous context for multi-agent support
         # This ensures nested agent calls don't pollute the parent's context
         if agent_context is not None:
@@ -823,6 +911,47 @@ async def stream_minimal_simulator(
         yield sse_string
 
 
+async def save_user_message(
+    session_id: str,
+    user_id: str | None,
+    content: str,
+) -> None:
+    """
+    Save user message to database before streaming.
+
+    This is a shared utility used by both API and CLI to ensure consistent
+    user message storage.
+
+    Args:
+        session_id: Session ID for message storage
+        user_id: User ID for message storage
+        content: The user's message content
+    """
+    from ....utils.date_utils import utc_now, to_iso
+    from ....services.session import SessionMessageStore
+    from ....settings import settings
+
+    if not settings.postgres.enabled or not session_id:
+        return
+
+    user_msg = {
+        "role": "user",
+        "content": 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=[user_msg],
+            user_id=user_id,
+            compress=False,
+        )
+        logger.debug(f"Saved user message to session {session_id}")
+    except Exception as e:
+        logger.error(f"Failed to save user message: {e}", exc_info=True)
+
+
 async def stream_openai_response_with_save(
     agent: Agent,
     prompt: str,
@@ -842,6 +971,9 @@ async def stream_openai_response_with_save(
     This accumulates all text content during streaming and saves it to the database
     after the stream completes.
 
+    NOTE: Call save_user_message() BEFORE this function to save the user's message.
+    This function only saves tool calls and assistant responses.
+
     Args:
         agent: Pydantic AI agent instance
         prompt: User prompt
@@ -899,6 +1031,9 @@ async def stream_openai_response_with_save(
                         delta = data["choices"][0].get("delta", {})
                         content = delta.get("content")
                         if content:
+                            # DEBUG: Check for [Calling markers in content
+                            if "[Calling" in content:
+                                logger.warning(f"DEBUG: Found [Calling in content chunk: {repr(content[:100])}")
                             accumulated_content.append(content)
             except (json.JSONDecodeError, KeyError, IndexError):
                 pass  # Skip non-JSON or malformed chunks
@@ -931,8 +1066,34 @@ async def stream_openai_response_with_save(
             messages_to_store.append(tool_message)
 
         # Then store assistant text response (if any)
+        # Priority: direct TextPartDelta content > tool call text_response
+        # When an agent delegates via ask_agent, the child's text_response becomes
+        # the parent's assistant response (the parent is just orchestrating)
+        full_content = None
+
         if accumulated_content:
             full_content = "".join(accumulated_content)
+            logger.warning(f"DEBUG: Using accumulated_content ({len(accumulated_content)} chunks, {len(full_content)} chars)")
+            logger.warning(f"DEBUG: First 200 chars: {repr(full_content[:200])}")
+        else:
+            logger.warning("DEBUG: accumulated_content is empty, checking text_response fallback")
+            # No direct text from TextPartDelta - check tool results for text_response
+            # This handles multi-agent delegation where child agent output is the response
+            for tool_call in tool_calls:
+                if not tool_call:
+                    continue
+                result = tool_call.get("result")
+                if isinstance(result, dict) and result.get("text_response"):
+                    text_response = result["text_response"]
+                    if text_response and str(text_response).strip():
+                        full_content = str(text_response)
+                        logger.debug(
+                            f"Using text_response from {tool_call.get('tool_name', 'tool')} "
+                            f"({len(full_content)} chars) as assistant message"
+                        )
+                        break
+
+        if full_content:
             assistant_message = {
                 "id": message_id,  # Use pre-generated ID for consistency with metadata event
                 "role": "assistant",
@@ -954,7 +1115,7 @@ async def stream_openai_response_with_save(
                 )
                 logger.debug(
                     f"Saved {len(tool_calls)} tool calls and "
-                    f"{'assistant response' if accumulated_content else 'no text'} "
+                    f"{'assistant response' if full_content else 'no text'} "
                     f"to session {session_id}"
                 )
             except Exception as e:

rem/api/routers/common.py

@@ -0,0 +1,18 @@
+"""
+Common models shared across API routers.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response format for HTTPException errors.
+
+    This is different from FastAPI's HTTPValidationError which is used
+    for Pydantic validation failures (422 errors with loc/msg/type array).
+
+    HTTPException errors return this simpler format:
+        {"detail": "Error message here"}
+    """
+
+    detail: str = Field(description="Error message describing what went wrong")

rem/api/routers/dev.py

@@ -11,6 +11,7 @@ Endpoints:
 from fastapi import APIRouter, HTTPException, Request
 from loguru import logger
 
+from .common import ErrorResponse
 from ...settings import settings
 
 router = APIRouter(prefix="/api/dev", tags=["dev"])
@@ -45,7 +46,12 @@ def verify_dev_token(token: str) -> bool:
     return token == expected
 
 
-@router.get("/token")
+@router.get(
+    "/token",
+    responses={
+        401: {"model": ErrorResponse, "description": "Dev tokens not available in production"},
+    },
+)
 async def get_dev_token(request: Request):
     """
     Get a development token for testing (non-production only).

rem/api/routers/feedback.py

@@ -63,6 +63,8 @@ from fastapi import APIRouter, Header, HTTPException, Request, Response
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ..deps import get_user_id_from_request
 from ...models.entities import Feedback
 from ...services.postgres import Repository
@@ -121,7 +123,13 @@ class FeedbackResponse(BaseModel):
 # =============================================================================
 
 
-@router.post("/messages/feedback", response_model=FeedbackResponse)
+@router.post(
+    "/messages/feedback",
+    response_model=FeedbackResponse,
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def submit_feedback(
     request: Request,
     response: Response,