remdb 0.3.202__py3-none-any.whl → 0.3.226__py3-none-any.whl

rem/api/routers/messages.py

@@ -16,6 +16,7 @@ Endpoints:
 """
 
 from datetime import datetime
+from enum import Enum
 from typing import Literal
 from uuid import UUID
 
@@ -23,6 +24,8 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ..deps import (
     get_current_user,
     get_user_filter,
@@ -38,6 +41,18 @@ from ...utils.date_utils import parse_iso, utc_now
 router = APIRouter(prefix="/api/v1")
 
 
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+class SortOrder(str, Enum):
+    """Sort order for list queries."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
 # =============================================================================
 # Request/Response Models
 # =============================================================================
@@ -134,7 +149,14 @@ class SessionsQueryResponse(BaseModel):
 # =============================================================================
 
 
-@router.get("/messages", response_model=MessageListResponse, tags=["messages"])
+@router.get(
+    "/messages",
+    response_model=MessageListResponse,
+    tags=["messages"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def list_messages(
     request: Request,
     mine: bool = Query(default=False, description="Only show my messages (uses JWT identity)"),
@@ -151,6 +173,7 @@ async def list_messages(
     ),
     limit: int = Query(default=50, ge=1, le=100, description="Max results to return"),
     offset: int = Query(default=0, ge=0, description="Offset for pagination"),
+    sort: SortOrder = Query(default=SortOrder.DESC, description="Sort order by created_at (asc or desc)"),
 ) -> MessageListResponse:
     """
     List messages with optional filters.
@@ -166,8 +189,9 @@ async def list_messages(
     - session_id: Filter by conversation session
     - start_date/end_date: Filter by creation time range (ISO 8601 format)
     - message_type: Filter by role (user, assistant, system, tool)
+    - sort: Sort order by created_at (asc or desc, default: desc)
 
-    Returns paginated results ordered by created_at descending.
+    Returns paginated results ordered by created_at.
     """
     if not settings.postgres.enabled:
         raise HTTPException(status_code=503, detail="Database not enabled")
@@ -189,6 +213,7 @@ async def list_messages(
 
     # Apply optional filters
     if session_id:
+        # session_id is the session UUID - use directly
         filters["session_id"] = session_id
     if message_type:
         filters["message_type"] = message_type
@@ -200,12 +225,15 @@ async def list_messages(
         f"filters={filters}"
     )
 
+    # Build order_by clause based on sort parameter
+    order_by = f"created_at {sort.value.upper()}"
+
     # For date filtering, we need custom SQL (not supported by basic Repository)
     # For now, fetch all matching base filters and filter in Python
     # TODO: Extend Repository to support date range filters
     messages = await repo.find(
         filters,
-        order_by="created_at DESC",
+        order_by=order_by,
         limit=limit + 1,  # Fetch one extra to determine has_more
         offset=offset,
     )
@@ -241,7 +269,16 @@ async def list_messages(
     return MessageListResponse(data=messages, total=total, has_more=has_more)
 
 
-@router.get("/messages/{message_id}", response_model=Message, tags=["messages"])
+@router.get(
+    "/messages/{message_id}",
+    response_model=Message,
+    tags=["messages"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Message not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def get_message(
     request: Request,
     message_id: str,
@@ -287,7 +324,14 @@ async def get_message(
 # =============================================================================
 
 
-@router.get("/sessions", response_model=SessionsQueryResponse, tags=["sessions"])
+@router.get(
+    "/sessions",
+    response_model=SessionsQueryResponse,
+    tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled or connection failed"},
+    },
+)
 async def list_sessions(
     request: Request,
     user_id: str | None = Query(default=None, description="Filter by user ID (admin only for cross-user)"),
@@ -400,7 +444,15 @@ async def list_sessions(
     )
 
 
-@router.post("/sessions", response_model=Session, status_code=201, tags=["sessions"])
+@router.post(
+    "/sessions",
+    response_model=Session,
+    status_code=201,
+    tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def create_session(
     request_body: SessionCreateRequest,
     user: dict = Depends(require_admin),
@@ -452,7 +504,16 @@ async def create_session(
     return result  # type: ignore
 
 
-@router.get("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+@router.get(
+    "/sessions/{session_id}",
+    response_model=Session,
+    tags=["sessions"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Session not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def get_session(
     request: Request,
     session_id: str,
@@ -465,7 +526,7 @@ async def get_session(
     - Admin users: Can access any session
 
     Args:
-        session_id: UUID or name of the session
+        session_id: UUID of the session
 
     Returns:
         Session object if found
@@ -481,12 +542,7 @@ async def get_session(
     session = await repo.get_by_id(session_id)
 
     if not session:
-        # Try finding by name
-        sessions = await repo.find({"name": session_id}, limit=1)
-        if sessions:
-            session = sessions[0]
-        else:
-            raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
+        raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
 
     # Check access: admin or owner
     current_user = get_current_user(request)
@@ -498,7 +554,16 @@ async def get_session(
     return session
 
 
-@router.put("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+@router.put(
+    "/sessions/{session_id}",
+    response_model=Session,
+    tags=["sessions"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Session not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def update_session(
     request: Request,
     session_id: str,

rem/api/routers/models.py

@@ -15,6 +15,8 @@ from typing import Literal
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from rem.agentic.llm_provider_models import (
     ModelInfo,
     AVAILABLE_MODELS,
@@ -57,7 +59,13 @@ async def list_models() -> ModelsResponse:
     return ModelsResponse(data=AVAILABLE_MODELS)
 
 
-@router.get("/models/{model_id:path}", response_model=ModelInfo)
+@router.get(
+    "/models/{model_id:path}",
+    response_model=ModelInfo,
+    responses={
+        404: {"model": ErrorResponse, "description": "Model not found"},
+    },
+)
 async def get_model(model_id: str) -> ModelInfo:
     """
     Get information about a specific model.

rem/api/routers/query.py

@@ -86,6 +86,8 @@ from fastapi import APIRouter, Header, HTTPException
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ...services.postgres import get_postgres_service
 from ...services.rem.service import RemService
 from ...services.rem.parser import RemQueryParser
@@ -213,7 +215,16 @@ class QueryResponse(BaseModel):
     )
 
 
-@router.post("/query", response_model=QueryResponse)
+@router.post(
+    "/query",
+    response_model=QueryResponse,
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid query or missing required fields"},
+        500: {"model": ErrorResponse, "description": "Query execution failed"},
+        501: {"model": ErrorResponse, "description": "Feature not yet implemented"},
+        503: {"model": ErrorResponse, "description": "Database not configured or unavailable"},
+    },
+)
 async def execute_query(
     request: QueryRequest,
     x_user_id: str | None = Header(default=None, description="User ID for query isolation (optional, uses default if not provided)"),

rem/api/routers/shared_sessions.py

@@ -18,6 +18,8 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ..deps import get_current_user, require_auth
 from ...models.entities import (
     Message,
@@ -83,6 +85,10 @@ class ShareSessionResponse(BaseModel):
     response_model=ShareSessionResponse,
     status_code=201,
     tags=["sessions"],
+    responses={
+        400: {"model": ErrorResponse, "description": "Session already shared with this user"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def share_session(
     request: Request,
@@ -175,6 +181,10 @@ async def share_session(
     "/sessions/{session_id}/share/{shared_with_user_id}",
     status_code=200,
     tags=["sessions"],
+    responses={
+        404: {"model": ErrorResponse, "description": "Share not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def remove_session_share(
     request: Request,
@@ -250,6 +260,9 @@ async def remove_session_share(
     "/sessions/shared-with-me",
     response_model=SharedWithMeResponse,
     tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def get_shared_with_me(
     request: Request,
@@ -328,6 +341,9 @@ async def get_shared_with_me(
     "/sessions/shared-with-me/{owner_user_id}/messages",
     response_model=SharedMessagesResponse,
     tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def get_shared_messages(
     request: Request,

rem/cli/commands/ask.py

@@ -71,16 +71,18 @@ async def run_agent_streaming(
     max_turns: int = 10,
     context: AgentContext | None = None,
     max_iterations: int | None = None,
+    user_message: str | None = None,
 ) -> None:
     """
-    Run agent in streaming mode using agent.iter() with usage limits.
+    Run agent in streaming mode using the SAME code path as the API.
 
-    Design Pattern:
-    - Use agent.iter() for complete execution with tool call visibility
-    - run_stream() stops after first output, missing tool calls
-    - Stream tool call markers: [Calling: tool_name]
-    - Stream text content deltas as they arrive
-    - Show final structured result
+    This uses stream_openai_response_with_save from the API to ensure:
+    1. Tool calls are saved as separate "tool" messages (not embedded in content)
+    2. Assistant response is clean text only (no [Calling: ...] markers)
+    3. CLI testing is equivalent to API testing
+
+    The CLI displays tool calls as [Calling: tool_name] for visibility,
+    but these are NOT saved to the database.
 
     Args:
         agent: Pydantic AI agent
@@ -88,88 +90,66 @@ async def run_agent_streaming(
         max_turns: Maximum turns for agent execution (not used in current API)
         context: Optional AgentContext for session persistence
         max_iterations: Maximum iterations/requests (from agent schema or settings)
+        user_message: The user's original message (for database storage)
     """
-    from pydantic_ai import UsageLimits
-    from rem.utils.date_utils import to_iso_with_z, utc_now
+    import json
+    from rem.api.routers.chat.streaming import stream_openai_response_with_save, save_user_message
 
     logger.info("Running agent in streaming mode...")
 
     try:
-        # Import event types for streaming
-        from pydantic_ai import Agent as PydanticAgent
-        from pydantic_ai.messages import PartStartEvent, PartDeltaEvent, TextPartDelta, ToolCallPart
-
-        # Accumulate assistant response for session persistence
-        assistant_response_parts = []
-
-        # Use agent.iter() to get complete execution with tool calls
-        usage_limits = UsageLimits(request_limit=max_iterations) if max_iterations else None
-        async with agent.iter(prompt, usage_limits=usage_limits) as agent_run:
-            async for node in agent_run:
-                # Check if this is a model request node (includes tool calls and text)
-                if PydanticAgent.is_model_request_node(node):
-                    # Stream events from model request
-                    request_stream: Any
-                    async with node.stream(agent_run.ctx) as request_stream:
-                        async for event in request_stream:
-                            # Tool call start event
-                            if isinstance(event, PartStartEvent) and isinstance(
-                                event.part, ToolCallPart
-                            ):
-                                tool_marker = f"\n[Calling: {event.part.tool_name}]"
-                                print(tool_marker, flush=True)
-                                assistant_response_parts.append(tool_marker)
-
-                            # Text content delta
-                            elif isinstance(event, PartDeltaEvent) and isinstance(
-                                event.delta, TextPartDelta
-                            ):
-                                print(event.delta.content_delta, end="", flush=True)
-                                assistant_response_parts.append(event.delta.content_delta)
-
-        print("\n")  # Final newline after streaming
-
-        # Get final result from agent_run
-        result = agent_run.result
-        if hasattr(result, "output"):
-            logger.info("Final structured result:")
-            output = result.output
-            from rem.agentic.serialization import serialize_agent_result
-            output_json = json.dumps(serialize_agent_result(output), indent=2)
-            print(output_json)
-            assistant_response_parts.append(f"\n{output_json}")
-
-        # Save session messages (if session_id provided and postgres enabled)
-        if context and context.session_id and settings.postgres.enabled:
-            from ...services.session.compression import SessionMessageStore
-
-            # Extract just the user query from prompt
-            # Prompt format from ContextBuilder: system + history + user message
-            # We need to extract the last user message
-            user_message_content = prompt.split("\n\n")[-1] if "\n\n" in prompt else prompt
-
-            user_message = {
-                "role": "user",
-                "content": user_message_content,
-                "timestamp": to_iso_with_z(utc_now()),
-            }
-
-            assistant_message = {
-                "role": "assistant",
-                "content": "".join(assistant_response_parts),
-                "timestamp": to_iso_with_z(utc_now()),
-            }
-
-            # Store messages with compression
-            store = SessionMessageStore(user_id=context.user_id or settings.test.effective_user_id)
-            await store.store_session_messages(
+        # Save user message BEFORE streaming (same as API, using shared utility)
+        if context and context.session_id and user_message:
+            await save_user_message(
                 session_id=context.session_id,
-                messages=[user_message, assistant_message],
                 user_id=context.user_id,
-                compress=True,
+                content=user_message,
             )
 
-            logger.debug(f"Saved conversation to session {context.session_id}")
+        # Use the API streaming code path for consistency
+        # This properly handles tool calls and message persistence
+        model_name = getattr(agent, 'model', 'unknown')
+        if hasattr(model_name, 'model_name'):
+            model_name = model_name.model_name
+        elif hasattr(model_name, 'name'):
+            model_name = model_name.name
+        else:
+            model_name = str(model_name)
+
+        async for chunk in stream_openai_response_with_save(
+            agent=agent.agent if hasattr(agent, 'agent') else agent,
+            prompt=prompt,
+            model=model_name,
+            session_id=context.session_id if context else None,
+            user_id=context.user_id if context else None,
+            agent_context=context,
+        ):
+            # Parse SSE chunks for CLI display
+            if chunk.startswith("event: tool_call"):
+                # Extract tool call info from next data line
+                continue
+            elif chunk.startswith("data: ") and not chunk.startswith("data: [DONE]"):
+                try:
+                    data_str = chunk[6:].strip()
+                    if data_str:
+                        data = json.loads(data_str)
+                        # Check for tool_call event
+                        if data.get("type") == "tool_call":
+                            tool_name = data.get("tool_name", "tool")
+                            status = data.get("status", "")
+                            if status == "started":
+                                print(f"\n[Calling: {tool_name}]", flush=True)
+                        # Check for text content (OpenAI format)
+                        elif "choices" in data and data["choices"]:
+                            delta = data["choices"][0].get("delta", {})
+                            content = delta.get("content")
+                            if content:
+                                print(content, end="", flush=True)
+                except (json.JSONDecodeError, KeyError, IndexError):
+                    pass
+
+        print("\n")  # Final newline after streaming
+        logger.info("Final structured result:")
 
     except Exception as e:
         logger.error(f"Agent execution failed: {e}")
@@ -549,7 +529,7 @@ async def _ask_async(
 
     # Run agent with session persistence
     if stream:
-        await run_agent_streaming(agent, prompt, max_turns=max_turns, context=context)
+        await run_agent_streaming(agent, prompt, max_turns=max_turns, context=context, user_message=query)
     else:
         await run_agent_non_streaming(
             agent,

rem/cli/commands/process.py

@@ -206,9 +206,9 @@ def process_ingest(
                 if category:
                     entity_data["category"] = category
 
-                # Scoping: user_id for private data, None for public/shared
-                # tenant_id=None and user_id=None means PUBLIC data (visible to all)
-                entity_data["tenant_id"] = user_id  # None = public/shared
+                # Scoping: user_id for private data, "public" for shared
+                # tenant_id="public" is the default for shared knowledge bases
+                entity_data["tenant_id"] = user_id or "public"
                 entity_data["user_id"] = user_id  # None = public/shared
 
                 # For ontologies, add URI

rem/schemas/agents/rem.yaml

@@ -124,7 +124,7 @@ json_schema_extra:
 
   # Explicit resource declarations for reference data
   resources:
-    - uri: rem://schemas
+    - uri: rem://agents
       name: Agent Schemas List
       description: List all available agent schemas in the system
     - uri: rem://status

rem/services/postgres/repository.py

@@ -31,17 +31,27 @@ if TYPE_CHECKING:
     from .service import PostgresService
 
 
+# Singleton instance for connection pool reuse
+_postgres_instance: "PostgresService | None" = None
+
+
 def get_postgres_service() -> "PostgresService | None":
     """
-    Get PostgresService instance with connection string from settings.
+    Get PostgresService singleton instance.
 
     Returns None if Postgres is disabled.
+    Uses singleton pattern to prevent connection pool exhaustion.
     """
+    global _postgres_instance
+
     if not settings.postgres.enabled:
         return None
-    
-    from .service import PostgresService
-    return PostgresService()
+
+    if _postgres_instance is None:
+        from .service import PostgresService
+        _postgres_instance = PostgresService()
+
+    return _postgres_instance
 
 T = TypeVar("T", bound=BaseModel)
 

rem/services/session/__init__.py

@@ -1,12 +1,13 @@
 """Session management services for conversation persistence and compression."""
 
 from .compression import MessageCompressor, SessionMessageStore
-from .pydantic_messages import session_to_pydantic_messages
+from .pydantic_messages import audit_session_history, session_to_pydantic_messages
 from .reload import reload_session
 
 __all__ = [
     "MessageCompressor",
     "SessionMessageStore",
+    "audit_session_history",
     "reload_session",
     "session_to_pydantic_messages",
 ]

rem/services/session/compression.py

@@ -188,21 +188,19 @@ class SessionMessageStore:
         Ensure session exists, creating it if necessary.
 
         Args:
-            session_id: Session identifier (maps to Session.name)
+            session_id: Session UUID from X-Session-Id header
             user_id: Optional user identifier
         """
         try:
-            # Check if session already exists by name
-            existing = await self._session_repo.find(
-                filters={"name": session_id},
-                limit=1,
-            )
+            # Check if session already exists by UUID
+            existing = await self._session_repo.get_by_id(session_id)
             if existing:
                 return  # Session already exists
 
-            # Create new session
+            # Create new session with the provided UUID as id
             session = Session(
-                name=session_id,
+                id=session_id,  # Use the provided UUID as session id
+                name=session_id,  # Default name to UUID, can be updated later
                 user_id=user_id or self.user_id,
                 tenant_id=self.user_id,  # tenant_id set to user_id for scoping
             )
@@ -321,7 +319,7 @@ class SessionMessageStore:
         Ensures session exists before storing messages.
 
         Args:
-            session_id: Session identifier (maps to Session.name)
+            session_id: Session UUID
             messages: List of messages to store
             user_id: Optional user identifier
             compress: Whether to compress messages (default: True)

rem/services/session/pydantic_messages.py

@@ -208,3 +208,69 @@ def session_to_pydantic_messages(
 
     logger.debug(f"Converted {len(session_history)} stored messages to {len(messages)} pydantic-ai messages")
     return messages
+
+
+def audit_session_history(
+    session_id: str,
+    agent_name: str,
+    prompt: str,
+    raw_session_history: list[dict[str, Any]],
+    pydantic_messages_count: int,
+) -> None:
+    """
+    Dump session history to a YAML file for debugging.
+
+    Only runs when DEBUG__AUDIT_SESSION=true. Writes to DEBUG__AUDIT_DIR (default /tmp).
+    Appends to the same file for a session, so all agent invocations are in one place.
+
+    Args:
+        session_id: The session identifier
+        agent_name: Name of the agent being invoked
+        prompt: The prompt being sent to the agent
+        raw_session_history: The raw session messages from the database
+        pydantic_messages_count: Count of converted pydantic-ai messages
+    """
+    from ...settings import settings
+
+    if not settings.debug.audit_session:
+        return
+
+    try:
+        import yaml
+        from pathlib import Path
+        from ...utils.date_utils import utc_now, to_iso
+
+        audit_dir = Path(settings.debug.audit_dir)
+        audit_dir.mkdir(parents=True, exist_ok=True)
+        audit_file = audit_dir / f"{session_id}.yaml"
+
+        # Create entry for this agent invocation
+        entry = {
+            "timestamp": to_iso(utc_now()),
+            "agent_name": agent_name,
+            "prompt": prompt,
+            "raw_history_count": len(raw_session_history),
+            "pydantic_messages_count": pydantic_messages_count,
+            "raw_session_history": raw_session_history,
+        }
+
+        # Load existing data or create new
+        existing_data: dict[str, Any] = {"session_id": session_id, "invocations": []}
+        if audit_file.exists():
+            with open(audit_file) as f:
+                loaded = yaml.safe_load(f)
+                if loaded:
+                    # Ensure session_id is always present (backfill if missing)
+                    existing_data = {
+                        "session_id": loaded.get("session_id", session_id),
+                        "invocations": loaded.get("invocations", []),
+                    }
+
+        # Append this invocation
+        existing_data["invocations"].append(entry)
+
+        with open(audit_file, "w") as f:
+            yaml.dump(existing_data, f, default_flow_style=False, allow_unicode=True)
+        logger.info(f"DEBUG: Session audit updated: {audit_file}")
+    except Exception as e:
+        logger.warning(f"DEBUG: Failed to dump session audit: {e}")