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

rem/agentic/agents/sse_simulator.py

@@ -265,6 +265,8 @@ async def stream_simulator_events(
             message_id=message_id,
             in_reply_to=in_reply_to,
             session_id=session_id,
+            # Session info
+            session_name="SSE Demo Session",
             # Quality indicators
             confidence=0.95,
             sources=["rem/api/routers/chat/sse_events.py", "rem/agentic/agents/sse_simulator.py"],

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
@@ -126,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)
@@ -138,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/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,12 +80,27 @@ 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}")

rem/agentic/otel/setup.py

@@ -158,6 +158,7 @@ def setup_instrumentation() -> None:
             base_exporter = GRPCExporter(
                 endpoint=settings.otel.collector_endpoint,
                 timeout=settings.otel.export_timeout,
+                insecure=settings.otel.insecure,
             )
         else:  # http
             base_exporter = HTTPExporter(

rem/agentic/providers/pydantic_ai.py

@@ -591,6 +591,22 @@ async def create_agent(
 
         set_agent_resource_attributes(agent_schema=agent_schema)
 
+    # Extract schema metadata for search_rem tool description suffix
+    # This allows entity schemas to add context-specific notes to the search_rem tool
+    search_rem_suffix = None
+    if metadata:
+        # Check for default_search_table in metadata (set by entity schemas)
+        extra = agent_schema.get("json_schema_extra", {}) if agent_schema else {}
+        default_table = extra.get("default_search_table")
+        has_embeddings = extra.get("has_embeddings", False)
+
+        if default_table:
+            # Build description suffix for search_rem
+            search_rem_suffix = f"\n\nFor this schema, use `search_rem` to query `{default_table}`. "
+            if has_embeddings:
+                search_rem_suffix += f"SEARCH works well on {default_table} (has embeddings). "
+            search_rem_suffix += f"Example: `SEARCH \"your query\" FROM {default_table} LIMIT 10`"
+
     # Add tools from MCP server (in-process, no subprocess)
     if mcp_server_configs:
         for server_config in mcp_server_configs:
@@ -614,9 +630,17 @@ async def create_agent(
                     mcp_tools_dict = await mcp_server.get_tools()
 
                     for tool_name, tool_func in mcp_tools_dict.items():
-                        wrapped_tool = create_mcp_tool_wrapper(tool_name, tool_func, user_id=context.user_id if context else None)
+                        # Add description suffix to search_rem tool if schema specifies a default table
+                        tool_suffix = search_rem_suffix if tool_name == "search_rem" else None
+
+                        wrapped_tool = create_mcp_tool_wrapper(
+                            tool_name,
+                            tool_func,
+                            user_id=context.user_id if context else None,
+                            description_suffix=tool_suffix,
+                        )
                         tools.append(wrapped_tool)
-                        logger.debug(f"Loaded MCP tool: {tool_name}")
+                        logger.debug(f"Loaded MCP tool: {tool_name}" + (" (with schema suffix)" if tool_suffix else ""))
 
                     logger.info(f"Loaded {len(mcp_tools_dict)} tools from MCP server: {server_id} (in-process)")
 

rem/api/main.py

@@ -376,10 +376,13 @@ def create_app() -> FastAPI:
 
     app.include_router(chat_router)
     app.include_router(models_router)
+    # shared_sessions_router MUST be before messages_router
+    # because messages_router has /sessions/{session_id} which would match
+    # before the more specific /sessions/shared-with-me routes
+    app.include_router(shared_sessions_router)
     app.include_router(messages_router)
     app.include_router(feedback_router)
     app.include_router(admin_router)
-    app.include_router(shared_sessions_router)
     app.include_router(query_router)
 
     # Register auth router (if enabled)

rem/api/mcp_router/server.py

@@ -127,10 +127,12 @@ def create_mcp_server(is_local: bool = False) -> FastMCP:
             "AVAILABLE TOOLS\n"
             "═══════════════════════════════════════════════════════════════════════════\n"
             "\n"
-            "• rem_query - Execute REM queries (LOOKUP, FUZZY, SEARCH, SQL, TRAVERSE)\n"
-            "• ask_rem - Natural language to REM query conversion\n"
+            "• search_rem - Execute REM queries (LOOKUP, FUZZY, SEARCH, SQL, TRAVERSE)\n"
+            "• ask_rem_agent - Natural language to REM query conversion\n"
             "  - plan_mode=True: Hints agent to use TRAVERSE with depth=0 for edge analysis\n"
-            "• parse_and_ingest_file - Ingest files from local paths (local server only), s3://, or https://\n"
+            "• ingest_into_rem - Ingest files from local paths (local server only), s3://, or https://\n"
+            "• list_schema - List all database schemas (tables) with row counts\n"
+            "• get_schema - Get detailed schema for a specific table (columns, types, indexes)\n"
             "\n"
             "═══════════════════════════════════════════════════════════════════════════\n"
             "AVAILABLE RESOURCES (Read-Only)\n"
@@ -175,7 +177,9 @@ def create_mcp_server(is_local: bool = False) -> FastMCP:
     # Register REM tools
     from .tools import (
         ask_rem_agent,
+        get_schema,
         ingest_into_rem,
+        list_schema,
         read_resource,
         register_metadata,
         search_rem,
@@ -185,6 +189,8 @@ def create_mcp_server(is_local: bool = False) -> FastMCP:
     mcp.tool()(ask_rem_agent)
     mcp.tool()(read_resource)
     mcp.tool()(register_metadata)
+    mcp.tool()(list_schema)
+    mcp.tool()(get_schema)
 
     # File ingestion tool (with local path support for local servers)
     # Wrap to inject is_local parameter

rem/api/mcp_router/tools.py

@@ -15,6 +15,9 @@ Available Tools:
 - ask_rem_agent: Natural language to REM query conversion via agent
 - ingest_into_rem: Full file ingestion pipeline (read + store + parse + chunk)
 - read_resource: Access MCP resources (for Claude Desktop compatibility)
+- register_metadata: Register response metadata for SSE MetadataEvent
+- list_schema: List all schemas (tables, agents) in the database with row counts
+- get_schema: Get detailed schema for a table (columns, types, indexes)
 """
 
 from functools import wraps
@@ -603,7 +606,9 @@ async def register_metadata(
     references: list[str] | None = None,
     sources: list[str] | None = None,
     flags: list[str] | None = None,
-    # Risk assessment fields (used by mental health agents like Siggy)
+    # Session naming
+    session_name: str | None = None,
+    # Risk assessment fields (used by specialized agents)
     risk_level: str | None = None,
     risk_score: int | None = None,
     risk_reasoning: str | None = None,
@@ -636,6 +641,11 @@ async def register_metadata(
         flags: Optional flags for the response (e.g., "needs_review",
             "uncertain", "incomplete", "crisis_alert").
 
+        session_name: Short 1-3 phrase name describing the session topic.
+            Used by the UI to label conversations in the sidebar.
+            Examples: "Prescription Drug Questions", "AWS Setup Help",
+            "Python Code Review", "Travel Planning".
+
         risk_level: Risk level indicator (e.g., "green", "orange", "red").
             Used by mental health agents for C-SSRS style assessment.
         risk_score: Numeric risk score (e.g., 0-6 for C-SSRS).
@@ -660,7 +670,7 @@ async def register_metadata(
             sources=["REM database lookup"]
         )
 
-        # Mental health risk assessment (Siggy-style)
+        # Risk assessment example
         register_metadata(
             confidence=0.9,
             risk_level="green",
@@ -703,6 +713,10 @@ async def register_metadata(
         "flags": flags,
     }
 
+    # Add session name if provided
+    if session_name is not None:
+        result["session_name"] = session_name
+
     # Add risk assessment fields if provided
     if risk_level is not None:
         result["risk_level"] = risk_level
@@ -718,3 +732,311 @@ async def register_metadata(
         result["extra"] = extra
 
     return result
+
+
+@mcp_tool_error_handler
+async def list_schema(
+    include_system: bool = False,
+    user_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    List all schemas (tables) in the REM database.
+
+    Returns metadata about all available tables including their names,
+    row counts, and descriptions. Use this to discover what data is
+    available before constructing queries.
+
+    Args:
+        include_system: If True, include PostgreSQL system tables (pg_*, information_schema).
+                       Default False shows only REM application tables.
+        user_id: Optional user identifier (defaults to authenticated user or "default")
+
+    Returns:
+        Dict with:
+        - status: "success" or "error"
+        - tables: List of table metadata dicts with:
+            - name: Table name
+            - schema: Schema name (usually "public")
+            - estimated_rows: Approximate row count
+            - description: Table comment if available
+
+    Examples:
+        # List all REM schemas
+        list_schema()
+
+        # Include system tables
+        list_schema(include_system=True)
+    """
+    rem_service = await get_rem_service()
+    user_id = AgentContext.get_user_id_or_default(user_id, source="list_schema")
+
+    # Query information_schema for tables
+    schema_filter = ""
+    if not include_system:
+        schema_filter = """
+            AND table_schema = 'public'
+            AND table_name NOT LIKE 'pg_%'
+            AND table_name NOT LIKE '_pg_%'
+        """
+
+    query = f"""
+        SELECT
+            t.table_schema,
+            t.table_name,
+            pg_catalog.obj_description(
+                (quote_ident(t.table_schema) || '.' || quote_ident(t.table_name))::regclass,
+                'pg_class'
+            ) as description,
+            (
+                SELECT reltuples::bigint
+                FROM pg_class c
+                JOIN pg_namespace n ON n.oid = c.relnamespace
+                WHERE c.relname = t.table_name
+                AND n.nspname = t.table_schema
+            ) as estimated_rows
+        FROM information_schema.tables t
+        WHERE t.table_type = 'BASE TABLE'
+        {schema_filter}
+        ORDER BY t.table_schema, t.table_name
+    """
+
+    # Access postgres service directly from cache
+    postgres_service = _service_cache.get("postgres")
+    if not postgres_service:
+        postgres_service = rem_service._postgres
+
+    rows = await postgres_service.fetch(query)
+
+    tables = []
+    for row in rows:
+        tables.append({
+            "name": row["table_name"],
+            "schema": row["table_schema"],
+            "estimated_rows": int(row["estimated_rows"]) if row["estimated_rows"] else 0,
+            "description": row["description"],
+        })
+
+    logger.info(f"Listed {len(tables)} schemas for user {user_id}")
+
+    return {
+        "tables": tables,
+        "count": len(tables),
+    }
+
+
+@mcp_tool_error_handler
+async def get_schema(
+    table_name: str,
+    include_indexes: bool = True,
+    include_constraints: bool = True,
+    columns: list[str] | None = None,
+    user_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Get detailed schema information for a specific table.
+
+    Returns column definitions, data types, constraints, and indexes.
+    Use this to understand table structure before writing SQL queries.
+
+    Args:
+        table_name: Name of the table to inspect (e.g., "resources", "moments")
+        include_indexes: Include index information (default True)
+        include_constraints: Include constraint information (default True)
+        columns: Optional list of specific columns to return. If None, returns all columns.
+        user_id: Optional user identifier (defaults to authenticated user or "default")
+
+    Returns:
+        Dict with:
+        - status: "success" or "error"
+        - table_name: Name of the table
+        - columns: List of column definitions with:
+            - name: Column name
+            - type: PostgreSQL data type
+            - nullable: Whether NULL is allowed
+            - default: Default value if any
+            - description: Column comment if available
+        - indexes: List of indexes (if include_indexes=True)
+        - constraints: List of constraints (if include_constraints=True)
+        - primary_key: Primary key column(s)
+
+    Examples:
+        # Get full schema for resources table
+        get_schema(table_name="resources")
+
+        # Get only specific columns
+        get_schema(
+            table_name="resources",
+            columns=["id", "name", "created_at"]
+        )
+
+        # Get schema without indexes
+        get_schema(
+            table_name="moments",
+            include_indexes=False
+        )
+    """
+    rem_service = await get_rem_service()
+    user_id = AgentContext.get_user_id_or_default(user_id, source="get_schema")
+
+    # Access postgres service
+    postgres_service = _service_cache.get("postgres")
+    if not postgres_service:
+        postgres_service = rem_service._postgres
+
+    # Verify table exists
+    exists_query = """
+        SELECT EXISTS (
+            SELECT 1 FROM information_schema.tables
+            WHERE table_schema = 'public' AND table_name = $1
+        )
+    """
+    exists = await postgres_service.fetchval(exists_query, table_name)
+    if not exists:
+        return {
+            "status": "error",
+            "error": f"Table '{table_name}' not found in public schema",
+        }
+
+    # Get columns
+    columns_filter = ""
+    if columns:
+        placeholders = ", ".join(f"${i+2}" for i in range(len(columns)))
+        columns_filter = f"AND column_name IN ({placeholders})"
+
+    columns_query = f"""
+        SELECT
+            c.column_name,
+            c.data_type,
+            c.udt_name,
+            c.is_nullable,
+            c.column_default,
+            c.character_maximum_length,
+            c.numeric_precision,
+            pg_catalog.col_description(
+                (quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))::regclass,
+                c.ordinal_position
+            ) as description
+        FROM information_schema.columns c
+        WHERE c.table_schema = 'public'
+        AND c.table_name = $1
+        {columns_filter}
+        ORDER BY c.ordinal_position
+    """
+
+    params = [table_name]
+    if columns:
+        params.extend(columns)
+
+    column_rows = await postgres_service.fetch(columns_query, *params)
+
+    column_defs = []
+    for row in column_rows:
+        # Build a more readable type string
+        data_type = row["data_type"]
+        if row["character_maximum_length"]:
+            data_type = f"{data_type}({row['character_maximum_length']})"
+        elif row["udt_name"] in ("int4", "int8", "float4", "float8"):
+            # Use common type names
+            type_map = {"int4": "integer", "int8": "bigint", "float4": "real", "float8": "double precision"}
+            data_type = type_map.get(row["udt_name"], data_type)
+        elif row["udt_name"] == "vector":
+            data_type = "vector"
+
+        column_defs.append({
+            "name": row["column_name"],
+            "type": data_type,
+            "nullable": row["is_nullable"] == "YES",
+            "default": row["column_default"],
+            "description": row["description"],
+        })
+
+    result = {
+        "table_name": table_name,
+        "columns": column_defs,
+        "column_count": len(column_defs),
+    }
+
+    # Get primary key
+    pk_query = """
+        SELECT a.attname as column_name
+        FROM pg_index i
+        JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+        WHERE i.indrelid = $1::regclass
+        AND i.indisprimary
+        ORDER BY array_position(i.indkey, a.attnum)
+    """
+    pk_rows = await postgres_service.fetch(pk_query, table_name)
+    result["primary_key"] = [row["column_name"] for row in pk_rows]
+
+    # Get indexes
+    if include_indexes:
+        indexes_query = """
+            SELECT
+                i.relname as index_name,
+                am.amname as index_type,
+                ix.indisunique as is_unique,
+                ix.indisprimary as is_primary,
+                array_agg(a.attname ORDER BY array_position(ix.indkey, a.attnum)) as columns
+            FROM pg_index ix
+            JOIN pg_class i ON i.oid = ix.indexrelid
+            JOIN pg_class t ON t.oid = ix.indrelid
+            JOIN pg_am am ON am.oid = i.relam
+            JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+            WHERE t.relname = $1
+            GROUP BY i.relname, am.amname, ix.indisunique, ix.indisprimary
+            ORDER BY i.relname
+        """
+        index_rows = await postgres_service.fetch(indexes_query, table_name)
+        result["indexes"] = [
+            {
+                "name": row["index_name"],
+                "type": row["index_type"],
+                "unique": row["is_unique"],
+                "primary": row["is_primary"],
+                "columns": row["columns"],
+            }
+            for row in index_rows
+        ]
+
+    # Get constraints
+    if include_constraints:
+        constraints_query = """
+            SELECT
+                con.conname as constraint_name,
+                con.contype as constraint_type,
+                array_agg(a.attname ORDER BY array_position(con.conkey, a.attnum)) as columns,
+                pg_get_constraintdef(con.oid) as definition
+            FROM pg_constraint con
+            JOIN pg_class t ON t.oid = con.conrelid
+            JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(con.conkey)
+            WHERE t.relname = $1
+            GROUP BY con.conname, con.contype, con.oid
+            ORDER BY con.contype, con.conname
+        """
+        constraint_rows = await postgres_service.fetch(constraints_query, table_name)
+
+        # Map constraint types to readable names
+        type_map = {
+            "p": "PRIMARY KEY",
+            "u": "UNIQUE",
+            "f": "FOREIGN KEY",
+            "c": "CHECK",
+            "x": "EXCLUSION",
+        }
+
+        result["constraints"] = []
+        for row in constraint_rows:
+            # contype is returned as bytes (char type), decode it
+            con_type = row["constraint_type"]
+            if isinstance(con_type, bytes):
+                con_type = con_type.decode("utf-8")
+            result["constraints"].append({
+                "name": row["constraint_name"],
+                "type": type_map.get(con_type, con_type),
+                "columns": row["columns"],
+                "definition": row["definition"],
+            })
+
+    logger.info(f"Retrieved schema for table '{table_name}' with {len(column_defs)} columns")
+
+    return result