remdb 0.3.133__py3-none-any.whl → 0.3.157__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,310 @@
+"""
+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)
+    schema_entity = Schema(
+        tenant_id=user_id,
+        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_builder.py

@@ -184,13 +184,15 @@ class ContextBuilder:
             # 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 +204,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:

rem/agentic/mcp/tool_wrapper.py

@@ -107,7 +107,7 @@ def create_mcp_tool_wrapper(
         return Tool(tool_func)
 
 
-def create_resource_tool(uri: str, usage: str = "") -> Tool:
+def create_resource_tool(uri: str, usage: str = "", mcp_server: Any = None) -> Tool:
     """
     Build a Tool instance from an MCP resource URI.
 
@@ -122,6 +122,9 @@ def create_resource_tool(uri: str, usage: str = "") -> Tool:
     Args:
         uri: The resource URI (concrete or template with {variable} placeholders).
         usage: The description of what this resource provides.
+        mcp_server: Optional FastMCP server instance to resolve resources from.
+            If provided, resources are resolved from this server's registry.
+            If not provided, falls back to REM's built-in load_resource().
 
     Returns:
         A Pydantic AI Tool instance that fetches the resource.
@@ -131,7 +134,7 @@ def create_resource_tool(uri: str, usage: str = "") -> 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")
+        tool = create_resource_tool("patient-profile://field/{field_key}", "Get field definition", mcp_server=mcp)
         # Agent calls: get_patient_profile_field(field_key="safety.suicidality")
     """
     import json
@@ -156,7 +159,29 @@ def create_resource_tool(uri: str, usage: str = "") -> Tool:
         # Template URI -> create parameterized tool
         async def wrapper(**kwargs: Any) -> str:
             """Fetch MCP resource with substituted parameters."""
-            # Substitute template variables into URI
+            import asyncio
+            import inspect
+
+            # Try to resolve from MCP server's resource templates first
+            if mcp_server is not None:
+                try:
+                    # Get resource templates from MCP server
+                    templates = await mcp_server.get_resource_templates()
+                    if uri in templates:
+                        template = templates[uri]
+                        # Call the template's underlying function directly
+                        # The fn expects the template variables as kwargs
+                        fn_result = template.fn(**kwargs)
+                        # Handle both sync and async functions
+                        if inspect.iscoroutine(fn_result):
+                            fn_result = await fn_result
+                        if isinstance(fn_result, str):
+                            return fn_result
+                        return json.dumps(fn_result, indent=2)
+                except Exception as e:
+                    logger.warning(f"Failed to resolve resource {uri} from MCP server: {e}")
+
+            # Fallback: substitute template variables and use load_resource
             resolved_uri = uri
             for var in template_vars:
                 if var in kwargs:
@@ -164,9 +189,7 @@ def create_resource_tool(uri: str, usage: str = "") -> Tool:
                 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
@@ -184,11 +207,30 @@ def create_resource_tool(uri: str, usage: str = "") -> Tool:
         # Concrete URI -> no-param tool
         async def wrapper(**kwargs: Any) -> str:
             """Fetch MCP resource and return contents."""
+            import asyncio
+            import inspect
+
             if kwargs:
                 logger.warning(f"Resource tool {func_name} called with unexpected kwargs: {list(kwargs.keys())}")
 
+            # Try to resolve from MCP server's resources first
+            if mcp_server is not None:
+                try:
+                    resources = await mcp_server.get_resources()
+                    if uri in resources:
+                        resource = resources[uri]
+                        # Call the resource's underlying function
+                        fn_result = resource.fn()
+                        if inspect.iscoroutine(fn_result):
+                            fn_result = await fn_result
+                        if isinstance(fn_result, str):
+                            return fn_result
+                        return json.dumps(fn_result, indent=2)
+                except Exception as e:
+                    logger.warning(f"Failed to resolve resource {uri} from MCP server: {e}")
+
+            # Fallback to load_resource
             from rem.api.mcp_router.resources import load_resource
-
             result = await load_resource(uri)
             if isinstance(result, str):
                 return result

rem/agentic/providers/phoenix.py

@@ -94,6 +94,82 @@ def _check_phoenix_available() -> bool:
     return PHOENIX_AVAILABLE
 
 
+def validate_evaluator_credentials(
+    model_name: str | None = None,
+) -> tuple[bool, str | None]:
+    """Validate that the evaluator's LLM provider has working credentials.
+
+    Performs a minimal API call to verify credentials before running experiments.
+    This prevents running expensive agent tasks only to have evaluations fail.
+
+    Args:
+        model_name: Model to validate (defaults to claude-sonnet-4-5-20250929)
+
+    Returns:
+        Tuple of (success: bool, error_message: str | None)
+        - (True, None) if credentials are valid
+        - (False, "error description") if validation fails
+
+    Example:
+        >>> success, error = validate_evaluator_credentials()
+        >>> if not success:
+        ...     print(f"Evaluator validation failed: {error}")
+        ...     return
+    """
+    if not _check_phoenix_available():
+        return False, "arize-phoenix package not installed"
+
+    from phoenix.evals import OpenAIModel, AnthropicModel
+
+    # Default model (check env var first)
+    if model_name is None:
+        import os
+        model_name = os.environ.get("EVALUATOR_MODEL", "claude-sonnet-4-5-20250929")
+
+    # Parse provider
+    if ":" in model_name:
+        provider, phoenix_model_name = model_name.split(":", 1)
+    else:
+        if model_name.startswith("claude"):
+            provider = "anthropic"
+        else:
+            provider = "openai"
+        phoenix_model_name = model_name
+
+    try:
+        # Create LLM wrapper
+        if provider.lower() == "anthropic":
+            llm = AnthropicModel(
+                model=phoenix_model_name,
+                temperature=0.0,
+                top_p=None,
+            )
+        else:
+            llm = OpenAIModel(model=phoenix_model_name, temperature=0.0)
+
+        # Test with minimal prompt
+        logger.info(f"Validating evaluator credentials for {provider}:{phoenix_model_name}")
+        response = llm("Say 'ok' if you can read this.")
+
+        if response and len(response) > 0:
+            logger.info(f"Evaluator credentials validated successfully for {provider}")
+            return True, None
+        else:
+            return False, f"Empty response from {provider} model"
+
+    except Exception as e:
+        error_msg = str(e)
+        # Extract meaningful error from common API errors
+        if "credit balance is too low" in error_msg.lower():
+            return False, f"Anthropic API credits exhausted. Add credits at https://console.anthropic.com/settings/billing"
+        elif "api key" in error_msg.lower() or "authentication" in error_msg.lower():
+            return False, f"{provider.capitalize()} API key missing or invalid. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable."
+        elif "rate limit" in error_msg.lower():
+            return False, f"{provider.capitalize()} rate limit exceeded. Wait and retry."
+        else:
+            return False, f"{provider.capitalize()} API error: {error_msg[:200]}"
+
+
 # =============================================================================
 # NAME SANITIZATION
 # =============================================================================
@@ -207,8 +283,9 @@ def create_phoenix_evaluator(
 
     # Default model (use Claude Sonnet 4.5 for evaluators)
     if model_name is None:
-        model_name = "claude-sonnet-4-5-20250929"
-        logger.debug(f"Using default evaluator model: {model_name}")
+        import os
+        model_name = os.environ.get("EVALUATOR_MODEL", "claude-sonnet-4-5-20250929")
+        logger.debug(f"Using evaluator model: {model_name}")
 
     logger.info(f"Creating Phoenix evaluator: {evaluator_name} with model={model_name}")
 
@@ -589,33 +666,26 @@ Please evaluate the agent's answer according to the evaluation criteria."""
 
             logger.debug(f"Created {len(evaluations)} evaluations")
 
-            # Phoenix run_experiment expects a single EvaluationResult, not a list.
-            # Return the overall score with detailed evaluations in metadata.
-            from phoenix.experiments.evaluators.base import EvaluationResult
-
+            # Phoenix client expects a dict with score, label, explanation
+            # (not the old EvaluationResult class)
             overall_eval = next(
                 (e for e in evaluations if e["name"] == "overall"),
                 {"score": 0.0, "label": "unknown", "explanation": None}
             )
 
-            return EvaluationResult(
-                score=overall_eval.get("score"),
-                label=overall_eval.get("label"),
-                explanation=overall_eval.get("explanation"),
-                metadata={
-                    "evaluations": evaluations,
-                    "raw_response": response_json,
-                }
-            )
+            return {
+                "score": overall_eval.get("score", 0.0),
+                "label": overall_eval.get("label", "unknown"),
+                "explanation": overall_eval.get("explanation"),
+            }
 
         except Exception as e:
             logger.error(f"Evaluator error: {e}")
-            from phoenix.experiments.evaluators.base import EvaluationResult
-            return EvaluationResult(
-                score=0.0,
-                label="error",
-                explanation=f"Evaluator failed: {str(e)}",
-            )
+            return {
+                "score": 0.0,
+                "label": "error",
+                "explanation": f"Evaluator failed: {str(e)}",
+            }
 
     return evaluator_fn