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

rem/agentic/README.md

@@ -640,6 +640,82 @@ If `query_agent_model` is not set, the agent uses `settings.llm.default_model`.
 - PostgreSQL dialect aware (knows about KV_STORE, embeddings tables)
 - Can generate multi-step query plans for complex questions
 
+## SSE Simulator
+
+The SSE Simulator is a **programmatic** event generator (not an LLM-based agent) that produces
+a scripted sequence of SSE events for testing and demonstrating the streaming protocol.
+
+### Purpose
+
+- Frontend development without LLM costs
+- Testing SSE parsing and rendering
+- Demonstrating the full event protocol
+- Load testing streaming infrastructure
+
+### Usage
+
+```python
+from rem.agentic.agents import stream_simulator_events
+from rem.api.routers.chat.sse_events import format_sse_event
+
+# Generate all event types
+async for event in stream_simulator_events("demo"):
+    print(format_sse_event(event))
+
+# Minimal demo (text + done only)
+from rem.agentic.agents import stream_minimal_demo
+async for event in stream_minimal_demo("Hello world!"):
+    print(event)
+
+# Error simulation
+from rem.agentic.agents import stream_error_demo
+async for event in stream_error_demo(error_after_words=10):
+    print(event)
+```
+
+### Event Sequence
+
+The full simulator produces events in this order:
+
+1. **Reasoning** (4 steps) - Model thinking process
+2. **Progress** (step 1/4) - Starting
+3. **Tool calls** (2 tools) - Simulated tool invocations
+4. **Progress** (step 2/4) - Generating
+5. **Text deltas** - Streamed markdown content
+6. **Progress** (step 3/4) - Formatting
+7. **Metadata** - Confidence, sources, flags
+8. **Progress** (step 4/4) - Preparing actions
+9. **Action request** - Feedback card with buttons and inputs
+10. **Progress** (all complete)
+11. **Done** - Stream completion
+
+### Configuration Options
+
+```python
+await stream_simulator_events(
+    prompt="demo",
+    delay_ms=50,              # Delay between events
+    include_reasoning=True,   # Emit reasoning events
+    include_progress=True,    # Emit progress events
+    include_tool_calls=True,  # Emit tool call events
+    include_actions=True,     # Emit action request at end
+    include_metadata=True,    # Emit metadata event
+)
+```
+
+### HTTP Endpoint
+
+Use the simulator via the chat completions endpoint:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "X-Agent-Schema: simulator" \
+  -d '{"messages": [{"role": "user", "content": "demo"}], "stream": true}'
+```
+
+See `rem/api/README.md` for full SSE event protocol documentation.
+
 ## Future Work
 
 - [ ] Phoenix evaluator integration

rem/agentic/__init__.py

@@ -17,6 +17,14 @@ from .schema import (
 )
 from .providers.pydantic_ai import create_agent_from_schema_file, create_agent, AgentRuntime
 from .query_helper import ask_rem, REMQueryOutput
+from .llm_provider_models import (
+    ModelInfo,
+    AVAILABLE_MODELS,
+    ALLOWED_MODEL_IDS,
+    is_valid_model,
+    get_valid_model_or_default,
+    get_model_by_id,
+)
 
 __all__ = [
     # Context and Query
@@ -36,4 +44,11 @@ __all__ = [
     # REM Query Helpers
     "ask_rem",
     "REMQueryOutput",
+    # LLM Provider Models
+    "ModelInfo",
+    "AVAILABLE_MODELS",
+    "ALLOWED_MODEL_IDS",
+    "is_valid_model",
+    "get_valid_model_or_default",
+    "get_model_by_id",
 ]

rem/agentic/agents/__init__.py

@@ -1,8 +1,38 @@
 """
 REM Agents - Specialized agents for REM operations.
 
-All agents are defined as YAML schemas in src/rem/schemas/agents/.
+Most agents are defined as YAML schemas in src/rem/schemas/agents/.
 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.
 """
 
-__all__ = []
+from .sse_simulator import (
+    stream_simulator_events,
+    stream_minimal_demo,
+    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()