remdb 0.3.146__py3-none-any.whl → 0.3.181__py3-none-any.whl

rem/agentic/agents/__init__.py

@@ -6,6 +6,8 @@ Use create_agent_from_schema_file() to instantiate agents.
 
 The SSE Simulator is a special programmatic "agent" that generates
 scripted SSE events for testing and demonstration - it doesn't use an LLM.
+
+Agent Manager provides functions for saving/loading user-created agents.
 """
 
 from .sse_simulator import (
@@ -14,9 +16,23 @@ from .sse_simulator import (
     stream_error_demo,
 )
 
+from .agent_manager import (
+    save_agent,
+    get_agent,
+    list_agents,
+    delete_agent,
+    build_agent_spec,
+)
+
 __all__ = [
     # SSE Simulator (programmatic, no LLM)
     "stream_simulator_events",
     "stream_minimal_demo",
     "stream_error_demo",
+    # Agent Manager
+    "save_agent",
+    "get_agent",
+    "list_agents",
+    "delete_agent",
+    "build_agent_spec",
 ]

rem/agentic/agents/agent_manager.py

@@ -0,0 +1,311 @@
+"""
+Agent Manager - Save, load, and manage user-created agents.
+
+This module provides the core functionality for persisting agent schemas
+to the database with user scoping.
+
+Usage:
+    from rem.agentic.agents.agent_manager import save_agent, get_agent, list_agents
+
+    # Save an agent
+    result = await save_agent(
+        name="my-assistant",
+        description="You are a helpful assistant.",
+        user_id="user-123"
+    )
+
+    # Get an agent
+    agent = await get_agent("my-assistant", user_id="user-123")
+
+    # List user's agents
+    agents = await list_agents(user_id="user-123")
+"""
+
+from typing import Any
+from loguru import logger
+
+
+DEFAULT_TOOLS = ["search_rem", "register_metadata"]
+
+
+def build_agent_spec(
+    name: str,
+    description: str,
+    properties: dict[str, Any] | None = None,
+    required: list[str] | None = None,
+    tools: list[str] | None = None,
+    tags: list[str] | None = None,
+    version: str = "1.0.0",
+) -> dict[str, Any]:
+    """
+    Build a valid agent schema spec.
+
+    Args:
+        name: Agent name in kebab-case
+        description: System prompt for the agent
+        properties: Output schema properties
+        required: Required property names
+        tools: Tool names (defaults to search_rem, register_metadata)
+        tags: Categorization tags
+        version: Semantic version
+
+    Returns:
+        Valid agent schema spec dict
+    """
+    # Default properties
+    if properties is None:
+        properties = {
+            "answer": {
+                "type": "string",
+                "description": "Natural language response to the user"
+            }
+        }
+
+    # Default required
+    if required is None:
+        required = ["answer"]
+
+    # Default tools
+    if tools is None:
+        tools = DEFAULT_TOOLS.copy()
+
+    return {
+        "type": "object",
+        "description": description,
+        "properties": properties,
+        "required": required,
+        "json_schema_extra": {
+            "kind": "agent",
+            "name": name,
+            "version": version,
+            "tags": tags or [],
+            "tools": [{"name": t, "description": f"Tool: {t}"} for t in tools],
+        }
+    }
+
+
+async def save_agent(
+    name: str,
+    description: str,
+    user_id: str,
+    properties: dict[str, Any] | None = None,
+    required: list[str] | None = None,
+    tools: list[str] | None = None,
+    tags: list[str] | None = None,
+    version: str = "1.0.0",
+) -> dict[str, Any]:
+    """
+    Save an agent schema to the database.
+
+    Args:
+        name: Agent name in kebab-case (e.g., "code-reviewer")
+        description: The agent's system prompt
+        user_id: User identifier for scoping
+        properties: Output schema properties
+        required: Required property names
+        tools: Tool names
+        tags: Categorization tags
+        version: Semantic version
+
+    Returns:
+        Dict with status, agent_name, version, message
+
+    Raises:
+        RuntimeError: If database is not available
+    """
+    from rem.models.entities import Schema
+    from rem.services.postgres import get_postgres_service
+
+    # Build the spec
+    spec = build_agent_spec(
+        name=name,
+        description=description,
+        properties=properties,
+        required=required,
+        tools=tools,
+        tags=tags,
+        version=version,
+    )
+
+    # Create Schema entity (user-scoped)
+    # Note: tenant_id defaults to "default" for anonymous users
+    schema_entity = Schema(
+        tenant_id=user_id or "default",
+        user_id=user_id,
+        name=name,
+        spec=spec,
+        category="agent",
+        metadata={
+            "version": version,
+            "tags": tags or [],
+            "created_via": "agent_manager",
+        },
+    )
+
+    # Save to database
+    postgres = get_postgres_service()
+    if not postgres:
+        raise RuntimeError("Database not available")
+
+    await postgres.connect()
+    try:
+        await postgres.batch_upsert(
+            records=[schema_entity],
+            model=Schema,
+            table_name="schemas",
+            entity_key_field="name",
+            generate_embeddings=False,
+        )
+        logger.info(f"✅ Agent saved: {name} (user={user_id}, version={version})")
+    finally:
+        await postgres.disconnect()
+
+    return {
+        "status": "success",
+        "agent_name": name,
+        "version": version,
+        "message": f"Agent '{name}' saved successfully.",
+    }
+
+
+async def get_agent(
+    name: str,
+    user_id: str,
+) -> dict[str, Any] | None:
+    """
+    Get an agent schema by name.
+
+    Checks user's schemas first, then falls back to system schemas.
+
+    Args:
+        name: Agent name
+        user_id: User identifier
+
+    Returns:
+        Agent spec dict if found, None otherwise
+    """
+    from rem.services.postgres import get_postgres_service
+
+    postgres = get_postgres_service()
+    if not postgres:
+        return None
+
+    await postgres.connect()
+    try:
+        query = """
+            SELECT spec FROM schemas
+            WHERE LOWER(name) = LOWER($1)
+            AND category = 'agent'
+            AND (user_id = $2 OR user_id IS NULL OR tenant_id = 'system')
+            ORDER BY CASE WHEN user_id = $2 THEN 0 ELSE 1 END
+            LIMIT 1
+        """
+        row = await postgres.fetchrow(query, name, user_id)
+        if row:
+            return row["spec"]
+        return None
+    finally:
+        await postgres.disconnect()
+
+
+async def list_agents(
+    user_id: str,
+    include_system: bool = True,
+) -> list[dict[str, Any]]:
+    """
+    List available agents for a user.
+
+    Args:
+        user_id: User identifier
+        include_system: Include system agents
+
+    Returns:
+        List of agent metadata dicts
+    """
+    from rem.services.postgres import get_postgres_service
+
+    postgres = get_postgres_service()
+    if not postgres:
+        return []
+
+    await postgres.connect()
+    try:
+        if include_system:
+            query = """
+                SELECT name, metadata, user_id, tenant_id
+                FROM schemas
+                WHERE category = 'agent'
+                AND (user_id = $1 OR user_id IS NULL OR tenant_id = 'system')
+                ORDER BY name
+            """
+            rows = await postgres.fetch(query, user_id)
+        else:
+            query = """
+                SELECT name, metadata, user_id, tenant_id
+                FROM schemas
+                WHERE category = 'agent'
+                AND user_id = $1
+                ORDER BY name
+            """
+            rows = await postgres.fetch(query, user_id)
+
+        return [
+            {
+                "name": row["name"],
+                "version": row["metadata"].get("version", "1.0.0") if row["metadata"] else "1.0.0",
+                "tags": row["metadata"].get("tags", []) if row["metadata"] else [],
+                "is_system": row["tenant_id"] == "system" or row["user_id"] is None,
+            }
+            for row in rows
+        ]
+    finally:
+        await postgres.disconnect()
+
+
+async def delete_agent(
+    name: str,
+    user_id: str,
+) -> dict[str, Any]:
+    """
+    Delete a user's agent.
+
+    Only allows deleting user-owned agents, not system agents.
+
+    Args:
+        name: Agent name
+        user_id: User identifier
+
+    Returns:
+        Dict with status and message
+    """
+    from rem.services.postgres import get_postgres_service
+
+    postgres = get_postgres_service()
+    if not postgres:
+        raise RuntimeError("Database not available")
+
+    await postgres.connect()
+    try:
+        # Only delete user's own agents
+        query = """
+            DELETE FROM schemas
+            WHERE LOWER(name) = LOWER($1)
+            AND category = 'agent'
+            AND user_id = $2
+            RETURNING name
+        """
+        row = await postgres.fetchrow(query, name, user_id)
+
+        if row:
+            logger.info(f"🗑️ Agent deleted: {name} (user={user_id})")
+            return {
+                "status": "success",
+                "message": f"Agent '{name}' deleted.",
+            }
+        else:
+            return {
+                "status": "error",
+                "message": f"Agent '{name}' not found or not owned by you.",
+            }
+    finally:
+        await postgres.disconnect()

rem/agentic/context.py

@@ -2,11 +2,15 @@
 Agent execution context and configuration.
 
 Design pattern for session context that can be constructed from:
+- FastAPI Request object (preferred - extracts user from JWT via request.state)
 - HTTP headers (X-User-Id, X-Session-Id, X-Model-Name, X-Is-Eval, etc.)
 - Direct instantiation for testing/CLI
 
+User ID Sources (in priority order):
+1. request.state.user.id - From JWT token validated by auth middleware (SECURE)
+2. X-User-Id header - Fallback for backwards compatibility (less secure)
+
 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")
@@ -128,13 +132,87 @@ class AgentContext(BaseModel):
         logger.debug(f"No user_id from {source}, using None (anonymous/shared data)")
         return None
 
+    @classmethod
+    def from_request(cls, request: "Request") -> "AgentContext":
+        """
+        Construct AgentContext from a FastAPI Request object.
+
+        This is the PREFERRED method for API endpoints. It extracts user_id
+        from the authenticated user in request.state (set by auth middleware
+        from JWT token), which is more secure than trusting X-User-Id header.
+
+        Priority for user_id:
+        1. request.state.user.id - From validated JWT token (SECURE)
+        2. X-User-Id header - Fallback for backwards compatibility
+
+        Args:
+            request: FastAPI Request object
+
+        Returns:
+            AgentContext with user from JWT and other values from headers
+
+        Example:
+            @app.post("/api/v1/chat/completions")
+            async def chat(request: Request, body: ChatRequest):
+                context = AgentContext.from_request(request)
+                # context.user_id is from JWT, not header
+        """
+        from typing import TYPE_CHECKING
+        if TYPE_CHECKING:
+            from starlette.requests import Request
+
+        # Get headers dict
+        headers = dict(request.headers)
+        normalized = {k.lower(): v for k, v in headers.items()}
+
+        # Extract user_id from authenticated user (JWT) - this is the source of truth
+        user_id = None
+        tenant_id = "default"
+
+        if hasattr(request, "state"):
+            user = getattr(request.state, "user", None)
+            if user and isinstance(user, dict):
+                user_id = user.get("id")
+                # Also get tenant_id from authenticated user if available
+                if user.get("tenant_id"):
+                    tenant_id = user.get("tenant_id")
+                if user_id:
+                    logger.debug(f"User ID from JWT: {user_id}")
+
+        # Fallback to X-User-Id header if no authenticated user
+        if not user_id:
+            user_id = normalized.get("x-user-id")
+            if user_id:
+                logger.debug(f"User ID from X-User-Id header (fallback): {user_id}")
+
+        # Override tenant_id from header if provided
+        header_tenant = normalized.get("x-tenant-id")
+        if header_tenant:
+            tenant_id = header_tenant
+
+        # Parse X-Is-Eval header
+        is_eval_str = normalized.get("x-is-eval", "").lower()
+        is_eval = is_eval_str in ("true", "1", "yes")
+
+        return cls(
+            user_id=user_id,
+            tenant_id=tenant_id,
+            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,
+        )
+
     @classmethod
     def from_headers(cls, headers: dict[str, str]) -> "AgentContext":
         """
-        Construct AgentContext from HTTP headers.
+        Construct AgentContext from HTTP headers dict.
+
+        NOTE: Prefer from_request() for API endpoints as it extracts user_id
+        from the validated JWT token in request.state, which is more secure.
 
         Reads standard headers:
-        - X-User-Id: User identifier
+        - X-User-Id: User identifier (fallback - prefer JWT)
         - X-Tenant-Id: Tenant identifier
         - X-Session-Id: Session identifier
         - X-Model-Name: Model override

rem/agentic/context_builder.py

@@ -12,7 +12,7 @@ User Context (on-demand by default):
 - System message includes REM LOOKUP hint for user profile
 - Agent decides whether to load profile based on query
 - More efficient for queries that don't need personalization
-- Example: "User ID: sarah@example.com. To load user profile: Use REM LOOKUP users/sarah@example.com"
+- Example: "User: sarah@example.com. To load user profile: Use REM LOOKUP \"sarah@example.com\""
 
 User Context (auto-inject when enabled):
 - Set CHAT__AUTO_INJECT_USER_CONTEXT=true
@@ -40,7 +40,7 @@ Usage (on-demand, default):
 
     # Messages list structure (on-demand):
     # [
-    #   {"role": "system", "content": "Today's date: 2025-11-22\nUser ID: sarah@example.com\nTo load user profile: Use REM LOOKUP users/sarah@example.com\nSession ID: sess-123\nTo load session history: Use REM LOOKUP messages?session_id=sess-123"},
+    #   {"role": "system", "content": "Today's date: 2025-11-22\nUser: sarah@example.com\nTo load user profile: Use REM LOOKUP \"sarah@example.com\"\nSession ID: sess-123\nTo load session history: Use REM LOOKUP messages?session_id=sess-123"},
     #   {"role": "user", "content": "What's next for the API migration?"}
     # ]
 
@@ -103,6 +103,7 @@ class ContextBuilder:
         headers: dict[str, str],
         new_messages: list[dict[str, str]] | None = None,
         db: PostgresService | None = None,
+        user_id: str | None = None,
     ) -> tuple[AgentContext, list[ContextMessage]]:
         """
         Build complete context from HTTP headers.
@@ -114,7 +115,7 @@ class ContextBuilder:
         - Agent can retrieve full content on-demand using REM LOOKUP
 
         User Context (on-demand by default):
-        - System message includes REM LOOKUP hint: "User ID: {user_id}. To load user profile: Use REM LOOKUP users/{user_id}"
+        - System message includes REM LOOKUP hint: "User: {email}. To load user profile: Use REM LOOKUP \"{email}\""
         - Agent decides whether to load profile based on query
 
         User Context (auto-inject when enabled):
@@ -125,6 +126,7 @@ class ContextBuilder:
             headers: HTTP request headers (case-insensitive)
             new_messages: New messages from current request
             db: Optional PostgresService (creates if None)
+            user_id: Override user_id from JWT token (takes precedence over X-User-Id header)
 
         Returns:
             Tuple of (AgentContext, messages list)
@@ -135,7 +137,7 @@ class ContextBuilder:
 
             # messages structure:
             # [
-            #   {"role": "system", "content": "Today's date: 2025-11-22\nUser ID: sarah@example.com\nTo load user profile: Use REM LOOKUP users/sarah@example.com"},
+            #   {"role": "system", "content": "Today's date: 2025-11-22\nUser: sarah@example.com\nTo load user profile: Use REM LOOKUP \"sarah@example.com\""},
             #   {"role": "user", "content": "Previous message"},
             #   {"role": "assistant", "content": "Start of long response... [REM LOOKUP session-123-msg-1] ...end"},
             #   {"role": "user", "content": "New message"}
@@ -147,6 +149,17 @@ class ContextBuilder:
         # Extract AgentContext from headers
         context = AgentContext.from_headers(headers)
 
+        # Override user_id if provided (from JWT token - takes precedence over header)
+        if user_id is not None:
+            context = AgentContext(
+                user_id=user_id,
+                tenant_id=context.tenant_id,
+                session_id=context.session_id,
+                default_model=context.default_model,
+                agent_schema_uri=context.agent_schema_uri,
+                is_eval=context.is_eval,
+            )
+
         # Initialize DB if not provided and needed (for user context or session history)
         close_db = False
         if db is None and (settings.chat.auto_inject_user_context or context.session_id):
@@ -178,19 +191,29 @@ class ContextBuilder:
                     context_hint += "\n\nNo user context available (anonymous or new user)."
             elif context.user_id:
                 # On-demand: Provide hint to use REM LOOKUP
-                context_hint += f"\n\nUser ID: {context.user_id}"
-                context_hint += f"\nTo load user profile: Use REM LOOKUP users/{context.user_id}"
+                # user_id is UUID5 hash of email - load user to get email for display and LOOKUP
+                user_repo = Repository(User, "users", db=db)
+                user = await user_repo.get_by_id(context.user_id, context.tenant_id)
+                if user and user.email:
+                    # Show email (more useful than UUID) and LOOKUP hint
+                    context_hint += f"\n\nUser: {user.email}"
+                    context_hint += f"\nTo load user profile: Use REM LOOKUP \"{user.email}\""
+                else:
+                    context_hint += f"\n\nUser ID: {context.user_id}"
+                    context_hint += "\nUser profile not available."
 
             # Add system context hint
             messages.append(ContextMessage(role="system", content=context_hint))
 
-            # ALWAYS load session history (if session_id provided) with compression
+            # ALWAYS load session history (if session_id provided)
+            # - Long assistant messages are compressed on load with REM LOOKUP hints
+            # - Tool messages are never compressed (contain structured metadata)
             if context.session_id and settings.postgres.enabled:
                 store = SessionMessageStore(user_id=context.user_id or "default")
                 session_history = await store.load_session_messages(
                     session_id=context.session_id,
                     user_id=context.user_id,
-                    decompress=False,  # Use compressed versions with REM LOOKUP hints
+                    compress_on_load=True,  # Compress long assistant messages
                 )
 
                 # Convert to ContextMessage format
@@ -202,7 +225,7 @@ class ContextBuilder:
                         )
                     )
 
-                logger.debug(f"Loaded {len(session_history)} compressed messages for session {context.session_id}")
+                logger.debug(f"Loaded {len(session_history)} messages for session {context.session_id}")
 
             # Add new messages from request
             if new_messages:
@@ -224,6 +247,9 @@ class ContextBuilder:
         """
         Load user profile from database and format as context.
 
+        user_id is always a UUID5 hash of email (bijection).
+        Looks up user by their id field in the database.
+
         Returns formatted string with:
         - User summary (generated by dreaming worker)
         - Current projects
@@ -237,6 +263,7 @@ class ContextBuilder:
 
         try:
             user_repo = Repository(User, "users", db=db)
+            # user_id is UUID5 hash of email - look up by database id
             user = await user_repo.get_by_id(user_id, tenant_id)
 
             if not user: