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

rem/agentic/context.py

@@ -2,10 +2,18 @@
 Agent execution context and configuration.
 
 Design pattern for session context that can be constructed from:
-- HTTP headers (X-User-Id, X-Session-Id, X-Model-Name)
+- HTTP headers (X-User-Id, X-Session-Id, X-Model-Name, X-Is-Eval, etc.)
 - Direct instantiation for testing/CLI
 
-Key Design Pattern 
+Headers Mapping:
+    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-Is-Eval        → context.is_eval (marks session as evaluation)
+
+Key Design Pattern:
 - AgentContext is passed to agent factory, not stored in agents
 - Enables session tracking across API, CLI, and test execution
 - Supports header-based configuration override (model, schema URI)
@@ -66,6 +74,11 @@ class AgentContext(BaseModel):
         description="Agent schema URI (e.g., 'rem-agents-query-agent')",
     )
 
+    is_eval: bool = Field(
+        default=False,
+        description="Whether this is an evaluation session (set via X-Is-Eval header)",
+    )
+
     model_config = {"populate_by_name": True}
 
     @staticmethod
@@ -73,43 +86,47 @@ class AgentContext(BaseModel):
         user_id: str | None,
         source: str = "context",
         default: str | None = None,
-    ) -> str:
+    ) -> str | None:
         """
-        Get user_id or fallback to default with logging.
+        Get user_id or return None for anonymous access.
 
-        Centralized helper for consistent user_id fallback behavior across
-        API endpoints, MCP tools, CLI commands, and services.
+        User ID convention:
+        - user_id is a deterministic UUID5 hash of the user's email address
+        - Use rem.utils.user_id.email_to_user_id(email) to generate
+        - The JWT's `sub` claim is NOT directly used as user_id
+        - Authentication middleware extracts email from JWT and hashes it
+
+        When user_id is None, queries return data with user_id IS NULL
+        (shared/public data). This is intentional - no fake user IDs.
 
         Args:
-            user_id: User identifier (may be None)
+            user_id: User identifier (UUID5 hash of email, may be None for anonymous)
             source: Source of the call (for logging clarity)
-            default: Default value to use (default: settings.test.effective_user_id)
+            default: Explicit default (only for testing, not auto-generated)
 
         Returns:
-            user_id if provided, otherwise default from settings
+            user_id if provided, explicit default if provided, otherwise None
 
         Example:
-            # In MCP tool
-            user_id = AgentContext.get_user_id_or_default(
-                user_id, source="ask_rem_agent"
-            )
-
-            # In API endpoint
-            user_id = AgentContext.get_user_id_or_default(
-                temp_context.user_id, source="chat_completions"
-            )
+            # Generate user_id from email (done by auth middleware)
+            from rem.utils.user_id import email_to_user_id
+            user_id = email_to_user_id("alice@example.com")
+            # -> "2c5ea4c0-4067-5fef-942d-0a20124e06d8"
 
-            # In CLI command
+            # In MCP tool - anonymous user sees shared data
             user_id = AgentContext.get_user_id_or_default(
-                args.user_id, source="rem ask"
+                user_id, source="ask_rem_agent"
             )
+            # Returns None if not authenticated -> queries WHERE user_id IS NULL
         """
-        if user_id is None:
-            from rem.settings import settings
-            effective_default = default or settings.test.effective_user_id
-            logger.debug(f"No user_id provided from {source}, using '{effective_default}'")
-            return effective_default
-        return user_id
+        if user_id is not None:
+            return user_id
+        if default is not None:
+            logger.debug(f"Using explicit default user_id '{default}' from {source}")
+            return default
+        # No fake user IDs - return None for anonymous/unauthenticated
+        logger.debug(f"No user_id from {source}, using None (anonymous/shared data)")
+        return None
 
     @classmethod
     def from_headers(cls, headers: dict[str, str]) -> "AgentContext":
@@ -122,6 +139,7 @@ class AgentContext(BaseModel):
         - X-Session-Id: Session identifier
         - X-Model-Name: Model override
         - X-Agent-Schema: Agent schema URI
+        - X-Is-Eval: Whether this is an evaluation session (true/false)
 
         Args:
             headers: Dictionary of HTTP headers (case-insensitive)
@@ -134,17 +152,23 @@ class AgentContext(BaseModel):
                 "X-User-Id": "user123",
                 "X-Tenant-Id": "acme-corp",
                 "X-Session-Id": "sess-456",
-                "X-Model-Name": "anthropic:claude-opus-4-20250514"
+                "X-Model-Name": "anthropic:claude-opus-4-20250514",
+                "X-Is-Eval": "true"
             }
             context = AgentContext.from_headers(headers)
         """
         # Normalize header keys to lowercase for case-insensitive lookup
         normalized = {k.lower(): v for k, v in headers.items()}
 
+        # Parse X-Is-Eval header (accepts "true", "1", "yes" as truthy)
+        is_eval_str = normalized.get("x-is-eval", "").lower()
+        is_eval = is_eval_str in ("true", "1", "yes")
+
         return cls(
             user_id=normalized.get("x-user-id"),
             tenant_id=normalized.get("x-tenant-id", "default"),
             session_id=normalized.get("x-session-id"),
             default_model=normalized.get("x-model-name") or settings.llm.default_model,
             agent_schema_uri=normalized.get("x-agent-schema"),
+            is_eval=is_eval,
         )

rem/agentic/llm_provider_models.py

@@ -0,0 +1,301 @@
+"""
+LLM Provider Model Registry.
+
+Defines available LLM models across providers (OpenAI, Anthropic, Google, Cerebras).
+Used by the models API endpoint and for validating model requests.
+
+Future: Models will be stored in database for dynamic management.
+"""
+
+from pydantic import BaseModel, Field
+from typing import Literal
+
+
+class ModelInfo(BaseModel):
+    """Information about a single model."""
+
+    id: str = Field(description="Model ID in provider:model format")
+    object: Literal["model"] = "model"
+    created: int = Field(description="Unix timestamp of model availability")
+    owned_by: str = Field(description="Provider name")
+    description: str | None = Field(default=None, description="Model description")
+    context_window: int | None = Field(default=None, description="Max context tokens")
+    max_output_tokens: int | None = Field(default=None, description="Max output tokens")
+
+
+# Model definitions with 2025 releases
+# Using Unix timestamps for created dates (approximate release dates)
+AVAILABLE_MODELS: list[ModelInfo] = [
+    # ==========================================================================
+    # OpenAI Models (2025)
+    # ==========================================================================
+    # GPT-4.1 series (Released April 14, 2025)
+    ModelInfo(
+        id="openai:gpt-4.1",
+        created=1744588800,  # April 14, 2025
+        owned_by="openai",
+        description="Latest GPT-4 iteration, excels at coding and instruction following. 1M context.",
+        context_window=1047576,
+        max_output_tokens=32768,
+    ),
+    ModelInfo(
+        id="openai:gpt-4.1-mini",
+        created=1744588800,
+        owned_by="openai",
+        description="Small model beating GPT-4o in many benchmarks. 83% cost reduction vs GPT-4o.",
+        context_window=1047576,
+        max_output_tokens=32768,
+    ),
+    ModelInfo(
+        id="openai:gpt-4.1-nano",
+        created=1744588800,
+        owned_by="openai",
+        description="Fastest and cheapest OpenAI model. Ideal for classification and autocompletion.",
+        context_window=1047576,
+        max_output_tokens=32768,
+    ),
+    # GPT-4o (legacy but still supported)
+    ModelInfo(
+        id="openai:gpt-4o",
+        created=1715644800,  # May 13, 2024
+        owned_by="openai",
+        description="Previous flagship multimodal model. Being superseded by GPT-4.1.",
+        context_window=128000,
+        max_output_tokens=16384,
+    ),
+    ModelInfo(
+        id="openai:gpt-4o-mini",
+        created=1721347200,  # July 18, 2024
+        owned_by="openai",
+        description="Cost-efficient smaller GPT-4o variant.",
+        context_window=128000,
+        max_output_tokens=16384,
+    ),
+    # o1 reasoning models
+    ModelInfo(
+        id="openai:o1",
+        created=1733961600,  # December 12, 2024
+        owned_by="openai",
+        description="Advanced reasoning model for complex problems. Extended thinking.",
+        context_window=200000,
+        max_output_tokens=100000,
+    ),
+    ModelInfo(
+        id="openai:o1-mini",
+        created=1726099200,  # September 12, 2024
+        owned_by="openai",
+        description="Smaller reasoning model, fast for coding and math.",
+        context_window=128000,
+        max_output_tokens=65536,
+    ),
+    ModelInfo(
+        id="openai:o3-mini",
+        created=1738195200,  # January 30, 2025
+        owned_by="openai",
+        description="Latest mini reasoning model with improved performance.",
+        context_window=200000,
+        max_output_tokens=100000,
+    ),
+    # ==========================================================================
+    # Anthropic Models (2025)
+    # ==========================================================================
+    # Claude 4.5 series (Latest - November 2025)
+    ModelInfo(
+        id="anthropic:claude-opus-4-5-20251124",
+        created=1732406400,  # November 24, 2025
+        owned_by="anthropic",
+        description="Most capable Claude model. World-class coding with 'effort' parameter control.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-sonnet-4-5-20250929",
+        created=1727568000,  # September 29, 2025
+        owned_by="anthropic",
+        description="Best balance of intelligence and speed. Excellent for coding and agents.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-haiku-4-5-20251101",
+        created=1730419200,  # November 1, 2025
+        owned_by="anthropic",
+        description="Fast and affordable. Sonnet 4 performance at 1/3 cost. Safest Claude model.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    # Claude 4 series
+    ModelInfo(
+        id="anthropic:claude-opus-4-20250514",
+        created=1715644800,  # May 14, 2025
+        owned_by="anthropic",
+        description="World's best coding model. Sustained performance on complex agent workflows.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-sonnet-4-20250514",
+        created=1715644800,  # May 14, 2025
+        owned_by="anthropic",
+        description="Significant upgrade to Sonnet 3.7. Great for everyday tasks.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-opus-4-1-20250805",
+        created=1722816000,  # August 5, 2025
+        owned_by="anthropic",
+        description="Opus 4 upgrade focused on agentic tasks and real-world coding.",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    # Aliases for convenience
+    ModelInfo(
+        id="anthropic:claude-opus-4-5",
+        created=1732406400,
+        owned_by="anthropic",
+        description="Alias for latest Claude Opus 4.5",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-sonnet-4-5",
+        created=1727568000,
+        owned_by="anthropic",
+        description="Alias for latest Claude Sonnet 4.5",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    ModelInfo(
+        id="anthropic:claude-haiku-4-5",
+        created=1730419200,
+        owned_by="anthropic",
+        description="Alias for latest Claude Haiku 4.5",
+        context_window=200000,
+        max_output_tokens=128000,
+    ),
+    # ==========================================================================
+    # Google Models (2025)
+    # ==========================================================================
+    # Gemini 3 (Latest)
+    ModelInfo(
+        id="google:gemini-3-pro",
+        created=1730419200,  # November 2025
+        owned_by="google",
+        description="Most advanced Gemini. State-of-the-art reasoning, 35% better than 2.5 Pro.",
+        context_window=2000000,
+        max_output_tokens=65536,
+    ),
+    # Gemini 2.5 series
+    ModelInfo(
+        id="google:gemini-2.5-pro",
+        created=1727568000,  # September 2025
+        owned_by="google",
+        description="High-capability model with adaptive thinking. 1M context window.",
+        context_window=1000000,
+        max_output_tokens=65536,
+    ),
+    ModelInfo(
+        id="google:gemini-2.5-flash",
+        created=1727568000,
+        owned_by="google",
+        description="Fast and capable. Best for large-scale processing and agentic tasks.",
+        context_window=1000000,
+        max_output_tokens=65536,
+    ),
+    ModelInfo(
+        id="google:gemini-2.5-flash-lite",
+        created=1727568000,
+        owned_by="google",
+        description="Optimized for massive scale. Balances cost and performance.",
+        context_window=1000000,
+        max_output_tokens=32768,
+    ),
+    # Gemini 2.0
+    ModelInfo(
+        id="google:gemini-2.0-flash",
+        created=1733875200,  # December 2024
+        owned_by="google",
+        description="Fast multimodal model with native tool use.",
+        context_window=1000000,
+        max_output_tokens=8192,
+    ),
+    # Gemma open models
+    ModelInfo(
+        id="google:gemma-3",
+        created=1727568000,
+        owned_by="google",
+        description="Open model with text/image input, 140+ languages, 128K context.",
+        context_window=128000,
+        max_output_tokens=8192,
+    ),
+    ModelInfo(
+        id="google:gemma-3n",
+        created=1730419200,
+        owned_by="google",
+        description="Efficient open model for low-resource devices. Multimodal input.",
+        context_window=128000,
+        max_output_tokens=8192,
+    ),
+    # ==========================================================================
+    # Cerebras Models (Ultra-fast inference)
+    # ==========================================================================
+    ModelInfo(
+        id="cerebras:llama-3.3-70b",
+        created=1733875200,  # December 2024
+        owned_by="cerebras",
+        description="Llama 3.3 70B on Cerebras. Ultra-fast inference (~2000 tok/s). Fully compatible with structured output.",
+        context_window=128000,
+        max_output_tokens=8192,
+    ),
+    ModelInfo(
+        id="cerebras:qwen-3-32b",
+        created=1733875200,  # December 2024
+        owned_by="cerebras",
+        description="Qwen 3 32B on Cerebras. Ultra-fast inference (~2400 tok/s). Requires strict schema mode.",
+        context_window=32000,
+        max_output_tokens=8192,
+    ),
+]
+
+# Set of valid model IDs for fast O(1) lookup
+ALLOWED_MODEL_IDS: set[str] = {model.id for model in AVAILABLE_MODELS}
+
+
+def is_valid_model(model_id: str | None) -> bool:
+    """Check if a model ID is in the allowed list."""
+    if model_id is None:
+        return False
+    return model_id in ALLOWED_MODEL_IDS
+
+
+def get_valid_model_or_default(model_id: str | None, default_model: str) -> str:
+    """
+    Return the model_id if it's valid, otherwise return the default.
+
+    Args:
+        model_id: The requested model ID (may be None or invalid)
+        default_model: Fallback model from settings
+
+    Returns:
+        Valid model ID to use
+    """
+    if is_valid_model(model_id):
+        return model_id  # type: ignore[return-value]
+    return default_model
+
+
+def get_model_by_id(model_id: str) -> ModelInfo | None:
+    """
+    Get model info by ID.
+
+    Args:
+        model_id: Model identifier in provider:model format
+
+    Returns:
+        ModelInfo if found, None otherwise
+    """
+    for model in AVAILABLE_MODELS:
+        if model.id == model_id:
+            return model
+    return None

rem/agentic/mcp/tool_wrapper.py

@@ -28,7 +28,12 @@ def create_pydantic_tool(func: Callable[..., Any]) -> Tool:
     return Tool(func)
 
 
-def create_mcp_tool_wrapper(tool_name: str, mcp_tool: Any, user_id: str | None = None) -> Tool:
+def create_mcp_tool_wrapper(
+    tool_name: str,
+    mcp_tool: Any,
+    user_id: str | None = None,
+    description_suffix: str | None = None,
+) -> Tool:
     """
     Create a Pydantic AI Tool from a FastMCP FunctionTool.
 
@@ -40,6 +45,8 @@ def create_mcp_tool_wrapper(tool_name: str, mcp_tool: Any, user_id: str | None =
         tool_name: Name of the MCP tool
         mcp_tool: The FastMCP FunctionTool object
         user_id: Optional user_id to inject into tool calls
+        description_suffix: Optional text to append to the tool's docstring.
+            Used to add schema-specific context (e.g., default table for search_rem).
 
     Returns:
         A Pydantic AI Tool instance
@@ -52,7 +59,11 @@ def create_mcp_tool_wrapper(tool_name: str, mcp_tool: Any, user_id: str | None =
     sig = inspect.signature(tool_func)
     has_user_id = "user_id" in sig.parameters
 
-    # If we need to inject user_id, create a wrapper
+    # Build the docstring with optional suffix
+    base_doc = tool_func.__doc__ or ""
+    final_doc = base_doc + description_suffix if description_suffix else base_doc
+
+    # If we need to inject user_id or modify docstring, create a wrapper
     # Otherwise, use the function directly for better signature preservation
     if user_id and has_user_id:
         async def wrapped_tool(**kwargs) -> Any:
@@ -69,39 +80,123 @@ def create_mcp_tool_wrapper(tool_name: str, mcp_tool: Any, user_id: str | None =
 
         # Copy signature from original function for Pydantic AI inspection
         wrapped_tool.__name__ = tool_name
-        wrapped_tool.__doc__ = tool_func.__doc__
+        wrapped_tool.__doc__ = final_doc
         wrapped_tool.__annotations__ = tool_func.__annotations__
         wrapped_tool.__signature__ = sig  # Important: preserve full signature
 
         logger.debug(f"Creating MCP tool wrapper with user_id injection: {tool_name}")
         return Tool(wrapped_tool)
+    elif description_suffix:
+        # Need to wrap just for docstring modification
+        async def wrapped_tool(**kwargs) -> Any:
+            """Wrapper for docstring modification."""
+            valid_params = set(sig.parameters.keys())
+            filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
+            return await tool_func(**filtered_kwargs)
+
+        wrapped_tool.__name__ = tool_name
+        wrapped_tool.__doc__ = final_doc
+        wrapped_tool.__annotations__ = tool_func.__annotations__
+        wrapped_tool.__signature__ = sig
+
+        logger.debug(f"Creating MCP tool wrapper with description suffix: {tool_name}")
+        return Tool(wrapped_tool)
     else:
         # No injection needed - use original function directly
         logger.debug(f"Creating MCP tool wrapper (no injection): {tool_name}")
         return Tool(tool_func)
 
 
-def create_resource_tool(uri: str, usage: str) -> Tool:
+def create_resource_tool(uri: str, usage: str = "") -> Tool:
     """
     Build a Tool instance from an MCP resource URI.
 
-    This is a placeholder for now. A real implementation would create a
-    tool that reads the content of the resource URI.
+    Creates a tool that fetches the resource content when called.
+    Resources declared in agent YAML become callable tools - this eliminates
+    the artificial MCP distinction between tools and resources.
+
+    Supports both:
+    - Concrete URIs: "rem://schemas" -> tool with no parameters
+    - Template URIs: "patient-profile://field/{field_key}" -> tool with field_key parameter
 
     Args:
-        uri: The resource URI (e.g., "rem://resources/some-id").
-        usage: The description of how to use the tool.
+        uri: The resource URI (concrete or template with {variable} placeholders).
+        usage: The description of what this resource provides.
 
     Returns:
-        A Pydantic AI Tool instance.
+        A Pydantic AI Tool instance that fetches the resource.
+
+    Example:
+        # Concrete URI -> no-param tool
+        tool = create_resource_tool("rem://schemas", "List all agent schemas")
+
+        # Template URI -> parameterized tool
+        tool = create_resource_tool("patient-profile://field/{field_key}", "Get field definition")
+        # Agent calls: get_patient_profile_field(field_key="safety.suicidality")
     """
-    # Placeholder function that would read the resource
-    def read_resource():
-        """Reads content from a resource URI."""
-        return f"Content of {uri}"
+    import json
+    import re
+
+    # Extract template variables from URI (e.g., {field_key}, {domain_name})
+    template_vars = re.findall(r'\{([^}]+)\}', uri)
+
+    # Parse URI to create function name (strip template vars for cleaner name)
+    clean_uri = re.sub(r'\{[^}]+\}', '', uri)
+    parts = clean_uri.replace("://", "_").replace("-", "_").replace("/", "_").replace(".", "_")
+    parts = re.sub(r'_+', '_', parts).strip('_')  # Clean up multiple underscores
+    func_name = f"get_{parts}"
+
+    # Build description including parameter info
+    description = usage or f"Fetch {uri} resource"
+    if template_vars:
+        param_desc = ", ".join(template_vars)
+        description = f"{description}\n\nParameters: {param_desc}"
+
+    if template_vars:
+        # Template URI -> create parameterized tool
+        async def wrapper(**kwargs: Any) -> str:
+            """Fetch MCP resource with substituted parameters."""
+            # Substitute template variables into URI
+            resolved_uri = uri
+            for var in template_vars:
+                if var in kwargs:
+                    resolved_uri = resolved_uri.replace(f"{{{var}}}", str(kwargs[var]))
+                else:
+                    return json.dumps({"error": f"Missing required parameter: {var}"})
+
+            # Import resource loading here to avoid circular imports
+            from rem.api.mcp_router.resources import load_resource
+
+            result = await load_resource(resolved_uri)
+            if isinstance(result, str):
+                return result
+            return json.dumps(result, indent=2)
+
+        # Build parameter annotations for Pydantic AI
+        wrapper.__name__ = func_name
+        wrapper.__doc__ = description
+        # Add type hints for parameters
+        wrapper.__annotations__ = {var: str for var in template_vars}
+        wrapper.__annotations__['return'] = str
+
+        logger.info(f"Built parameterized resource tool: {func_name} (uri: {uri}, params: {template_vars})")
+    else:
+        # Concrete URI -> no-param tool
+        async def wrapper(**kwargs: Any) -> str:
+            """Fetch MCP resource and return contents."""
+            if kwargs:
+                logger.warning(f"Resource tool {func_name} called with unexpected kwargs: {list(kwargs.keys())}")
+
+            from rem.api.mcp_router.resources import load_resource
+
+            result = await load_resource(uri)
+            if isinstance(result, str):
+                return result
+            return json.dumps(result, indent=2)
+
+        wrapper.__name__ = func_name
+        wrapper.__doc__ = description
 
-    read_resource.__name__ = f"read_{uri.replace('://', '_').replace('/', '_')}"
-    read_resource.__doc__ = usage
+        logger.info(f"Built resource tool: {func_name} (uri: {uri})")
 
-    logger.info(f"Built resource tool: {read_resource.__name__} (uri: {uri})")
-    return Tool(read_resource)
+    return Tool(wrapper)