remdb 0.3.14__py3-none-any.whl → 0.3.157__py3-none-any.whl

rem/api/routers/chat/completions.py

@@ -1,13 +1,94 @@
 """
 OpenAI-compatible chat completions router for REM.
 
-Design Pattern:
-- Headers map to AgentContext (X-User-Id, X-Tenant-Id, X-Session-Id, X-Agent-Schema)
+Quick Start (Local Development)
+===============================
+
+NOTE: Local dev uses LOCAL databases (Postgres via Docker Compose on port 5050).
+      Do NOT port-forward databases. Only port-forward observability services.
+
+IMPORTANT: Session IDs MUST be UUIDs. Non-UUID session IDs will cause message
+           storage issues and feedback will not work correctly.
+
+1. Port Forwarding (REQUIRED for trace capture and Phoenix sync):
+
+    # Terminal 1: OTEL Collector (HTTP) - sends traces to Phoenix
+    kubectl port-forward -n observability svc/otel-collector-collector 4318:4318
+
+    # Terminal 2: Phoenix UI - view traces at http://localhost:6006
+    kubectl port-forward -n siggy svc/phoenix 6006:6006
+
+2. Get Phoenix API Key (REQUIRED for feedback->Phoenix sync):
+
+    export PHOENIX_API_KEY=$(kubectl get secret -n siggy rem-phoenix-api-key \\
+      -o jsonpath='{.data.PHOENIX_API_KEY}' | base64 -d)
+
+3. Start API with OTEL and Phoenix enabled:
+
+    cd /path/to/remstack/rem
+    source .venv/bin/activate
+    OTEL__ENABLED=true \\
+    PHOENIX__ENABLED=true \\
+    PHOENIX_API_KEY="$PHOENIX_API_KEY" \\
+    uvicorn rem.api.main:app --host 0.0.0.0 --port 8000 --app-dir src
+
+4. Test Chat Request (session_id MUST be a UUID):
+
+    SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
+    curl -s -N -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}'
+
+    # Note: Use 'rem' agent schema (default) for real LLM responses.
+    # The 'simulator' agent is for testing SSE events without LLM calls.
+
+5. Submit Feedback on Response:
+
+    The metadata SSE event contains message_id and trace_id for feedback:
+        event: metadata
+        data: {"message_id": "728882f8-...", "trace_id": "e53c701c...", ...}
+
+    Use session_id (UUID you generated) and message_id to submit feedback:
+
+    curl -X POST http://localhost:8000/api/v1/messages/feedback \\
+      -H 'Content-Type: application/json' \\
+      -H 'X-Tenant-Id: default' \\
+      -d '{
+        "session_id": "<your-uuid-session-id>",
+        "message_id": "<message-id-from-metadata>",
+        "rating": 1,
+        "categories": ["helpful"],
+        "comment": "Good response"
+      }'
+
+    Expected response (201 = synced to Phoenix):
+        {"phoenix_synced": true, "trace_id": "e53c701c...", "span_id": "6432d497..."}
+
+OTEL Architecture
+=================
+
+    REM API --[OTLP/HTTP]--> OTEL Collector --[relay]--> Phoenix
+             (port 4318)    (k8s: observability)         (k8s: siggy)
+
+Environment Variables:
+    OTEL__ENABLED=true              Enable OTEL tracing (required for trace capture)
+    PHOENIX__ENABLED=true           Enable Phoenix integration (required for feedback sync)
+    PHOENIX_API_KEY=<jwt>           Phoenix API key (required for feedback->Phoenix sync)
+    OTEL__COLLECTOR_ENDPOINT        Default: http://localhost:4318
+    OTEL__PROTOCOL                  Default: http (use port 4318, not gRPC 4317)
+
+Design Pattern
+==============
+
+- Headers map to AgentContext (X-User-Id, X-Tenant-Id, X-Session-Id, X-Agent-Schema, X-Is-Eval)
 - ContextBuilder centralizes message construction with user profile + session history
 - Body.model is the LLM model for Pydantic AI
 - X-Agent-Schema header specifies which agent schema to use (defaults to 'rem')
 - Support for streaming (SSE) and non-streaming modes
 - Response format control (text vs json_object)
+- OpenAI-compatible body fields: metadata, store, reasoning_effort, etc.
 
 Context Building Flow:
 1. ContextBuilder.build_from_headers() extracts user_id, session_id from headers
@@ -25,9 +106,10 @@ Context Building Flow:
 Headers Mapping
     X-User-Id        → AgentContext.user_id
     X-Tenant-Id      → AgentContext.tenant_id
-    X-Session-Id     → AgentContext.session_id
+    X-Session-Id     → AgentContext.session_id (use UUID for new sessions)
     X-Model-Name     → AgentContext.default_model (overrides body.model)
     X-Agent-Schema   → AgentContext.agent_schema_uri (defaults to 'rem')
+    X-Is-Eval        → AgentContext.is_eval (sets session mode to EVALUATION)
 
 Default Agent:
     If X-Agent-Schema header is not provided, the system loads 'rem' schema,
@@ -42,6 +124,7 @@ Example Request:
     POST /api/v1/chat/completions
     X-Tenant-Id: acme-corp
     X-User-Id: user123
+    X-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890  # UUID
     X-Agent-Schema: rem  # Optional, this is the default
 
     {
@@ -67,10 +150,12 @@ from loguru import logger
 from ....agentic.context import AgentContext
 from ....agentic.context_builder import ContextBuilder
 from ....agentic.providers.pydantic_ai import create_agent
+from ....models.entities.session import Session, SessionMode
 from ....services.audio.transcriber import AudioTranscriber
+from ....services.postgres.repository import Repository
 from ....services.session import SessionMessageStore, reload_session
 from ....settings import settings
-from ....utils.schema_loader import load_agent_schema
+from ....utils.schema_loader import load_agent_schema, load_agent_schema_async
 from .json_utils import extract_json_resilient
 from .models import (
     ChatCompletionChoice,
@@ -79,14 +164,113 @@ from .models import (
     ChatCompletionUsage,
     ChatMessage,
 )
-from .streaming import stream_openai_response
+from .streaming import stream_openai_response, stream_openai_response_with_save, stream_simulator_response
 
-router = APIRouter(prefix="/v1", tags=["chat"])
+router = APIRouter(prefix="/api/v1", tags=["chat"])
 
 # Default agent schema file
 DEFAULT_AGENT_SCHEMA = "rem"
 
 
+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()
+        if span and span.get_span_context().is_valid:
+            ctx = span.get_span_context()
+            trace_id = format(ctx.trace_id, '032x')
+            span_id = format(ctx.span_id, '016x')
+            return trace_id, span_id
+    except Exception:
+        pass
+    return None, None
+
+
+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
+
+
+async def ensure_session_with_metadata(
+    session_id: str,
+    user_id: str | None,
+    tenant_id: str,
+    is_eval: bool,
+    request_metadata: dict[str, str] | None,
+    agent_schema: str | None = None,
+) -> None:
+    """
+    Ensure session exists and update with metadata/mode.
+
+    If X-Is-Eval header is true, sets session mode to EVALUATION.
+    Merges request metadata with existing session metadata.
+
+    Args:
+        session_id: Session identifier (maps to Session.name)
+        user_id: User identifier
+        tenant_id: Tenant identifier
+        is_eval: Whether this is an evaluation session
+        request_metadata: Metadata from request body to merge
+        agent_schema: Optional agent schema being used
+    """
+    if not settings.postgres.enabled:
+        return
+
+    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
+
+        if existing:
+            # Merge metadata if provided
+            merged_metadata = existing.metadata or {}
+            if request_metadata:
+                merged_metadata.update(request_metadata)
+
+            # Update session if eval flag or new metadata
+            needs_update = False
+            if is_eval and existing.mode != SessionMode.EVALUATION:
+                existing.mode = SessionMode.EVALUATION
+                needs_update = True
+            if request_metadata:
+                existing.metadata = merged_metadata
+                needs_update = True
+
+            if needs_update:
+                await repo.upsert(existing)
+                logger.debug(f"Updated session {session_id} (eval={is_eval}, metadata keys={list(merged_metadata.keys())})")
+        else:
+            # Create new session
+            session = Session(
+                name=session_id,
+                mode=SessionMode.EVALUATION if is_eval else SessionMode.NORMAL,
+                user_id=user_id,
+                tenant_id=tenant_id,
+                agent_schema_uri=agent_schema,
+                metadata=request_metadata or {},
+            )
+            await repo.upsert(session)
+            logger.info(f"Created session {session_id} (eval={is_eval})")
+
+    except Exception as e:
+        # Non-critical - log but don't fail the request
+        logger.error(f"Failed to ensure session metadata: {e}", exc_info=True)
+
+
 @router.post("/chat/completions", response_model=None)
 async def chat_completions(body: ChatCompletionRequest, request: Request):
     """
@@ -102,6 +286,17 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
     | X-Tenant-Id         | Tenant identifier (multi-tenancy)    | AgentContext.tenant_id         | "default"     |
     | X-Session-Id        | Session/conversation identifier      | AgentContext.session_id        | None          |
     | X-Agent-Schema      | Agent schema name                    | AgentContext.agent_schema_uri  | "rem"         |
+    | X-Is-Eval           | Mark as evaluation session           | AgentContext.is_eval           | false         |
+
+    Additional OpenAI-compatible Body Fields:
+    - metadata: Key-value pairs merged with session metadata (max 16 keys)
+    - store: Whether to store for distillation/evaluation
+    - max_completion_tokens: Max tokens to generate (replaces max_tokens)
+    - seed: Seed for deterministic sampling
+    - top_p: Nucleus sampling probability
+    - logprobs: Return log probabilities
+    - reasoning_effort: low/medium/high for o-series models
+    - service_tier: auto/flex/priority/default
 
     Example Models:
     - anthropic:claude-sonnet-4-5-20250929 (Claude 4.5 Sonnet)
@@ -127,15 +322,137 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
     - If CHAT__AUTO_INJECT_USER_CONTEXT=true: User profile auto-loaded and injected
     - New messages saved to database with compression for session continuity
     - When Postgres is disabled, session management is skipped
+
+    Evaluation Sessions:
+    - Set X-Is-Eval: true header to mark session as evaluation
+    - Session mode will be set to EVALUATION
+    - Request metadata is merged with session metadata
+    - Useful for A/B testing, model comparison, and feedback collection
     """
     # Load agent schema: use header value from context or default
     # Extract AgentContext first to get schema name
     temp_context = AgentContext.from_headers(dict(request.headers))
     schema_name = temp_context.agent_schema_uri or DEFAULT_AGENT_SCHEMA
 
+    # Resolve model: use body.model if provided, otherwise settings default
+    if body.model is None:
+        body.model = settings.llm.default_model
+        logger.debug(f"No model specified, using default: {body.model}")
+
+    # Special handling for simulator schema - no LLM, just generates demo SSE events
+    # Check BEFORE loading schema since simulator doesn't need a schema file
+    # Still builds full context and saves messages like a real agent
+    if schema_name == "simulator":
+        logger.info("Using SSE simulator (no LLM)")
+
+        # Build context just like real agents (loads session history, user context)
+        new_messages = [msg.model_dump() for msg in body.messages]
+        context, messages = await ContextBuilder.build_from_headers(
+            headers=dict(request.headers),
+            new_messages=new_messages,
+        )
+
+        # Ensure session exists with metadata and eval mode if applicable
+        if context.session_id:
+            await ensure_session_with_metadata(
+                session_id=context.session_id,
+                user_id=context.user_id,
+                tenant_id=context.tenant_id,
+                is_eval=context.is_eval,
+                request_metadata=body.metadata,
+                agent_schema="simulator",
+            )
+
+        # Get the last user message as prompt
+        prompt = body.messages[-1].content if body.messages else "demo"
+        request_id = f"sim-{uuid.uuid4().hex[:24]}"
+
+        # Generate message IDs upfront for correlation
+        user_message_id = str(uuid.uuid4())
+        assistant_message_id = str(uuid.uuid4())
+
+        # Simulated assistant response content (for persistence)
+        simulated_content = (
+            f"[SSE Simulator Response]\n\n"
+            f"This is a simulated response demonstrating all SSE event types:\n"
+            f"- reasoning events (model thinking)\n"
+            f"- text_delta events (streamed content)\n"
+            f"- progress events (multi-step operations)\n"
+            f"- tool_call events (function invocations)\n"
+            f"- action_request events (UI solicitation)\n"
+            f"- metadata events (confidence, sources, message IDs)\n\n"
+            f"Original prompt: {prompt[:100]}{'...' if len(prompt) > 100 else ''}"
+        )
+
+        # Save messages to database (if session_id and postgres enabled)
+        if settings.postgres.enabled and context.session_id:
+            user_message = {
+                "id": user_message_id,
+                "role": "user",
+                "content": prompt,
+                "timestamp": datetime.utcnow().isoformat(),
+            }
+            assistant_message = {
+                "id": assistant_message_id,
+                "role": "assistant",
+                "content": simulated_content,
+                "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, assistant_message],
+                    user_id=context.user_id,
+                    compress=True,
+                )
+                logger.info(f"Saved simulator conversation to session {context.session_id}")
+            except Exception as e:
+                # Log error but don't fail the request - session storage is non-critical
+                logger.error(f"Failed to save session messages: {e}", exc_info=True)
+
+        if body.stream:
+            return StreamingResponse(
+                stream_simulator_response(
+                    prompt=prompt,
+                    model="simulator-v1.0.0",
+                    # Pass message correlation IDs
+                    message_id=assistant_message_id,
+                    in_reply_to=user_message_id,
+                    session_id=context.session_id,
+                ),
+                media_type="text/event-stream",
+                headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+            )
+        else:
+            # Non-streaming simulator returns simple JSON
+            return ChatCompletionResponse(
+                id=request_id,
+                created=int(time.time()),
+                model="simulator-v1.0.0",
+                choices=[
+                    ChatCompletionChoice(
+                        index=0,
+                        message=ChatMessage(
+                            role="assistant",
+                            content=simulated_content,
+                        ),
+                        finish_reason="stop",
+                    )
+                ],
+                usage=ChatCompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+            )
+
     # Load schema using centralized utility
+    # Enable database fallback to load dynamic agents stored in schemas table
+    # Use async version since we're in an async context (FastAPI endpoint)
+    user_id = temp_context.user_id or settings.test.effective_user_id
     try:
-        agent_schema = load_agent_schema(schema_name)
+        agent_schema = await load_agent_schema_async(
+            schema_name,
+            user_id=user_id,
+        )
     except FileNotFoundError:
         # Fallback to default if specified schema not found
         logger.warning(f"Schema '{schema_name}' not found, falling back to '{DEFAULT_AGENT_SCHEMA}'")
@@ -151,7 +468,7 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
                 detail=f"Agent schema '{schema_name}' not found and default schema unavailable",
             )
 
-    logger.info(f"Using agent schema: {schema_name}, model: {body.model}")
+    logger.debug(f"Using agent schema: {schema_name}, model: {body.model}")
 
     # Check for audio input
     is_audio = request.headers.get("x-chat-is-audio", "").lower() == "true"
@@ -196,6 +513,17 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
 
     logger.info(f"Built context with {len(messages)} total messages (includes history + user context)")
 
+    # Ensure session exists with metadata and eval mode if applicable
+    if context.session_id:
+        await ensure_session_with_metadata(
+            session_id=context.session_id,
+            user_id=context.user_id,
+            tenant_id=context.tenant_id,
+            is_eval=context.is_eval,
+            request_metadata=body.metadata,
+            agent_schema=schema_name,
+        )
+
     # Create agent with schema and model override
     agent = await create_agent(
         context=context,
@@ -212,14 +540,60 @@ 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)
+
         return StreamingResponse(
-            stream_openai_response(agent, prompt, body.model, request_id),
+            stream_openai_response_with_save(
+                agent=agent,
+                prompt=prompt,
+                model=body.model,
+                request_id=request_id,
+                agent_schema=schema_name,
+                session_id=context.session_id,
+                user_id=context.user_id,
+            ),
             media_type="text/event-stream",
             headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
         )
 
     # Non-streaming mode
-    result = await agent.run(prompt)
+    # Create a parent span to capture trace context for message storage
+    trace_id, span_id = None, None
+    tracer = get_tracer()
+
+    if tracer:
+        with tracer.start_as_current_span(
+            "chat_completion",
+            attributes={
+                "session.id": context.session_id or "",
+                "user.id": context.user_id or "",
+                "model": body.model,
+                "agent.schema": context.agent_schema_uri or DEFAULT_AGENT_SCHEMA,
+            }
+        ) as span:
+            # Capture trace context from the span we just created
+            trace_id, span_id = get_current_trace_context()
+            result = await agent.run(prompt)
+    else:
+        # No tracer available, run without tracing
+        result = await agent.run(prompt)
 
     # Determine content format based on response_format request
     if body.response_format and body.response_format.type == "json_object":
@@ -242,25 +616,33 @@ async def chat_completions(body: ChatCompletionRequest, request: Request):
             "role": "user",
             "content": body.messages[-1].content if body.messages else "",
             "timestamp": datetime.utcnow().isoformat(),
+            "trace_id": trace_id,
+            "span_id": span_id,
         }
 
         assistant_message = {
             "role": "assistant",
             "content": content,
             "timestamp": datetime.utcnow().isoformat(),
+            "trace_id": trace_id,
+            "span_id": span_id,
         }
 
-        # Store messages with compression
-        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, assistant_message],
-            user_id=context.user_id,
-            compress=True,
-        )
+        try:
+            # Store messages with compression
+            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, assistant_message],
+                user_id=context.user_id,
+                compress=True,
+            )
 
-        logger.info(f"Saved conversation to session {context.session_id}")
+            logger.info(f"Saved conversation to session {context.session_id}")
+        except Exception as e:
+            # Log error but don't fail the request - session storage is non-critical
+            logger.error(f"Failed to save session messages: {e}", exc_info=True)
 
     return ChatCompletionResponse(
         id=request_id,

rem/api/routers/chat/models.py

@@ -1,17 +1,43 @@
 """
 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
 
+from rem.settings import settings
+
 
 # Request models
 class ChatMessage(BaseModel):
@@ -44,17 +70,26 @@ 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.
     """
 
-    model: str = Field(
-        default="anthropic:claude-sonnet-4-5-20250929",
-        description="Model to use (standard OpenAI field)",
+    # TODO: default should come from settings.llm.default_model at request time
+    # Using None and resolving in endpoint to avoid import-time settings evaluation
+    model: str | None = Field(
+        default=None,
+        description="Model to use. Defaults to LLM__DEFAULT_MODEL from settings.",
     )
     messages: list[ChatMessage] = Field(description="Chat conversation history")
     temperature: float | None = Field(default=None, ge=0, le=2)
@@ -69,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