remdb 0.3.242__py3-none-any.whl

rem/agentic/__init__.py

@@ -0,0 +1,54 @@
+"""
+REM Agentic Framework.
+
+Provider-agnostic agent orchestration with JSON Schema agents,
+MCP tool integration, and structured output.
+"""
+
+from .context import AgentContext
+from .query import AgentQuery
+from .schema import (
+    AgentSchema,
+    AgentSchemaMetadata,
+    MCPToolReference,
+    MCPResourceReference,
+    validate_agent_schema,
+    create_agent_schema,
+)
+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
+    "AgentContext",
+    "AgentQuery",
+    # Schema Protocol
+    "AgentSchema",
+    "AgentSchemaMetadata",
+    "MCPToolReference",
+    "MCPResourceReference",
+    "validate_agent_schema",
+    "create_agent_schema",
+    # Agent Factories
+    "create_agent_from_schema_file",
+    "create_agent",
+    "AgentRuntime",
+    # 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/README.md

@@ -0,0 +1,155 @@
+# REM Agents
+
+Built-in agents for REM system operations.
+
+## Overview
+
+This folder contains specialized agents that provide high-level interfaces for REM operations. These agents use LLMs to interpret natural language and convert it to structured REM queries.
+
+## REM Query Agent
+
+**File**: `rem_query_agent.py`
+
+Converts natural language questions into structured REM queries with PostgreSQL dialect awareness.
+
+### Features
+
+- **Query Type Selection**: Automatically chooses optimal query type (LOOKUP, FUZZY, SEARCH, SQL, TRAVERSE)
+- **PostgreSQL Dialect Aware**: Knows when to use KV_STORE vs primary tables
+- **Token Optimized**: Minimal output fields for fast generation and low cost
+- **Confidence Scoring**: Returns confidence (0-1) with reasoning for low scores
+- **Multi-Step Planning**: Can break complex queries into multiple REM calls
+
+### Usage
+
+#### Simple Query
+
+```python
+from rem.agentic.agents import ask_rem
+
+# Convert natural language to REM query
+result = await ask_rem("Show me Sarah Chen")
+
+print(result.query_type)  # QueryType.LOOKUP
+print(result.parameters)  # {"entity_key": "sarah-chen"}
+print(result.confidence)  # 1.0
+```
+
+#### With Custom Model
+
+```python
+# Use fast, cheap model for query generation
+result = await ask_rem(
+    "Find documents about databases",
+    llm_model="gpt-4o-mini"
+)
+
+print(result.query_type)  # QueryType.SEARCH
+print(result.parameters)
+# {
+#     "query_text": "database",
+#     "table_name": "resources",
+#     "field_name": "content",
+#     "limit": 10
+# }
+```
+
+#### Integration with RemService
+
+```python
+from rem.services.rem import RemService
+
+# RemService automatically uses REM Query Agent
+result = await rem_service.ask_rem(
+    natural_query="What does Sarah manage?",
+    tenant_id="acme-corp"
+)
+
+# Returns:
+# {
+#     "query_output": {
+#         "query_type": "TRAVERSE",
+#         "parameters": {"start_key": "sarah-chen", "max_depth": 1, "rel_type": "manages"},
+#         "confidence": 0.85,
+#         "reasoning": "TRAVERSE query to find entities Sarah manages via graph edges"
+#     },
+#     "results": [...],  # Executed query results (if confidence >= 0.7)
+#     "natural_query": "What does Sarah manage?"
+# }
+```
+
+### Query Types
+
+| Type | Description | When to Use | Example |
+|------|-------------|-------------|---------|
+| `LOOKUP` | O(1) entity lookup by natural key | User references specific entity by name | "Show me Sarah Chen" |
+| `FUZZY` | Trigram text similarity (pg_trgm) | Partial/misspelled names, approximate matches | "Find people named Sara" |
+| `SEARCH` | Semantic vector similarity | Conceptual questions, semantic similarity | "Documents about databases" |
+| `SQL` | Direct table queries with WHERE | Temporal, filtered, or aggregate queries | "Meetings in Q4 2024" |
+| `TRAVERSE` | Recursive graph traversal | Relationships, connections, "what's related" | "What does Sarah manage?" |
+
+### Configuration
+
+Set the model for REM Query Agent in your environment:
+
+```bash
+# .env
+LLM__QUERY_AGENT_MODEL=gpt-4o-mini  # Fast, cheap model recommended
+```
+
+If not set, uses `settings.llm.default_model`.
+
+### Output Schema
+
+```python
+class REMQueryOutput(BaseModel):
+    query_type: QueryType  # Selected query type
+    parameters: dict       # Query parameters
+    confidence: float      # 0.0-1.0 confidence score
+    reasoning: str | None  # Only if confidence < 0.7 or multi-step
+    multi_step: list[dict] | None  # For complex queries
+```
+
+### Design Philosophy
+
+1. **Token Efficiency**: Output is concise by design
+   - Reasoning only included when needed (low confidence or multi-step)
+   - Minimal fields to reduce generation time and cost
+
+2. **PostgreSQL Awareness**: Agent knows the database schema
+   - LOOKUP/FUZZY use UNLOGGED KV_STORE (fast cache)
+   - SEARCH joins KV_STORE + embeddings_<table>
+   - SQL queries primary tables directly
+   - TRAVERSE follows graph_edges JSONB field
+
+3. **Progressive Complexity**: Prefer simple queries over complex
+   - LOOKUP is fastest (O(1))
+   - FUZZY uses indexed trigrams
+   - SEARCH requires embedding generation
+   - SQL scans tables (filtered)
+   - TRAVERSE is recursive (most complex)
+
+4. **Confidence-Based Execution**: RemService auto-executes if confidence >= 0.7
+   - High confidence: Execute immediately
+   - Low confidence: Return query + reasoning for review
+
+### Testing
+
+See `tests/unit/agentic/agents/test_rem_query_agent.py` for unit tests.
+
+Tests cover:
+- Schema structure validation
+- Output model creation
+- Confidence validation
+- Multi-step query support
+
+Integration tests with actual LLM execution require API keys and are in `tests/integration/`.
+
+## Future Agents
+
+Additional agents can be added following the same pattern:
+
+- **Entity Summarization Agent**: Summarize entity relationships
+- **Query Explanation Agent**: Explain REM query results in natural language
+- **Schema Discovery Agent**: Discover available tables and fields
+- **Data Quality Agent**: Identify data quality issues in entities

rem/agentic/agents/__init__.py

@@ -0,0 +1,38 @@
+"""
+REM Agents - Specialized agents for REM operations.
+
+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.
+"""
+
+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,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()