remdb 0.3.7__py3-none-any.whl → 0.3.133__py3-none-any.whl

rem/__init__.py

@@ -1,2 +1,129 @@
-def hello() -> str:
-    return "Hello from rem!"
+"""
+REM - Resources, Entities, Moments.
+
+A bio-inspired memory system for agentic AI, built on FastAPI.
+
+Usage (API mode):
+    from rem import create_app
+
+    # Create REM app (FastAPI with MCP server pre-configured)
+    app = create_app()
+
+    # Extend like any FastAPI app
+    @app.get("/my-endpoint")
+    async def my_endpoint():
+        return {"custom": True}
+
+    # Add routers
+    app.include_router(my_router)
+
+    # Access MCP server directly (FastMCP instance)
+    @app.mcp_server.tool()
+    async def my_custom_tool(query: str) -> dict:
+        '''Custom MCP tool for my application.'''
+        return {"result": "..."}
+
+    @app.mcp_server.resource("custom://config")
+    async def get_config() -> str:
+        '''Custom resource.'''
+        return '{"setting": "value"}'
+
+Usage (model registration - works with or without API):
+    import rem
+    from rem.models.core import CoreModel
+
+    @rem.register_model
+    class CustomEntity(CoreModel):
+        name: str
+        custom_field: str
+
+    # Or register multiple:
+    rem.register_models(ModelA, ModelB)
+
+    # Then schema generation includes your models:
+    # rem db schema generate
+"""
+
+from .registry import (
+    # Model registration
+    register_model,
+    register_models,
+    get_model_registry,
+    clear_model_registry,
+    # Schema path registration
+    register_schema_path,
+    register_schema_paths,
+    get_schema_paths,
+    get_schema_path_registry,
+    clear_schema_path_registry,
+)
+
+
+def create_app():
+    """
+    Create and return a FastAPI application with REM features pre-configured.
+
+    The returned app has:
+    - MCP server mounted at /api/v1/mcp
+    - Chat completions endpoint at /api/v1/chat/completions
+    - Health check at /health
+    - OpenAPI docs at /docs
+
+    The app exposes `app.mcp_server` (FastMCP instance) for adding custom
+    tools, resources, and prompts.
+
+    Returns:
+        FastAPI application with .mcp_server attribute
+
+    Example:
+        from rem import create_app
+
+        app = create_app()
+
+        # Add custom endpoint
+        @app.get("/custom")
+        async def custom():
+            return {"custom": True}
+
+        # Add custom MCP tool
+        @app.mcp_server.tool()
+        async def my_tool(query: str) -> dict:
+            return {"result": query}
+    """
+    from .api.main import create_app as _create_app
+    return _create_app()
+
+
+# Lazy app instance - created on first access
+_app = None
+
+
+def get_app():
+    """
+    Get or create the default REM app instance.
+
+    For most cases, use create_app() to get a fresh instance.
+    This is provided for convenience in simple scripts.
+    """
+    global _app
+    if _app is None:
+        _app = create_app()
+    return _app
+
+
+__all__ = [
+    # App creation
+    "create_app",
+    "get_app",
+    # Model registration
+    "register_model",
+    "register_models",
+    "get_model_registry",
+    "clear_model_registry",
+    # Schema path registration
+    "register_schema_path",
+    "register_schema_paths",
+    "get_schema_paths",
+    "get_schema_path_registry",
+    "clear_schema_path_registry",
+]

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,22 @@
 """
 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.
 """
 
-__all__ = []
+from .sse_simulator import (
+    stream_simulator_events,
+    stream_minimal_demo,
+    stream_error_demo,
+)
+
+__all__ = [
+    # SSE Simulator (programmatic, no LLM)
+    "stream_simulator_events",
+    "stream_minimal_demo",
+    "stream_error_demo",
+]