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

rem/cli/main.py

@@ -22,17 +22,30 @@ except Exception:
     __version__ = "unknown"
 
 
+def _configure_logger(level: str):
+    """Configure loguru with custom level icons."""
+    logger.remove()
+
+    # Configure level icons - only warnings and errors get visual indicators
+    logger.level("DEBUG", icon=" ")
+    logger.level("INFO", icon=" ")
+    logger.level("WARNING", icon="🟠")
+    logger.level("ERROR", icon="🔴")
+    logger.level("CRITICAL", icon="🔴")
+
+    logger.add(
+        sys.stderr,
+        level=level,
+        format="<green>{time:HH:mm:ss}</green> | {level.icon} <level>{level: <8}</level> | <level>{message}</level>",
+    )
+
+
 @click.group()
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
 @click.version_option(version=__version__, prog_name="rem")
 def cli(verbose: bool):
     """REM - Resources Entities Moments system CLI."""
-    if verbose:
-        logger.remove()
-        logger.add(sys.stderr, level="DEBUG")
-    else:
-        logger.remove()
-        logger.add(sys.stderr, level="INFO")
+    _configure_logger("DEBUG" if verbose else "INFO")
 
 
 @cli.group()
@@ -65,6 +78,12 @@ def dreaming():
     pass
 
 
+@cli.group()
+def cluster():
+    """Kubernetes cluster deployment and management."""
+    pass
+
+
 # Register commands
 from .commands.schema import register_commands as register_schema_commands
 from .commands.db import register_commands as register_db_commands
@@ -76,17 +95,21 @@ from .commands.configure import register_command as register_configure_command
 from .commands.serve import register_command as register_serve_command
 from .commands.mcp import register_command as register_mcp_command
 from .commands.scaffold import scaffold as scaffold_command
+from .commands.cluster import register_commands as register_cluster_commands
+from .commands.session import register_command as register_session_command
 
 register_schema_commands(schema)
 register_db_commands(db)
 register_process_commands(process)
 register_dreaming_commands(dreaming)
+register_cluster_commands(cluster)
 register_ask_command(cli)
 register_configure_command(cli)
 register_serve_command(cli)
 register_mcp_command(cli)
 cli.add_command(experiments_group)
 cli.add_command(scaffold_command)
+register_session_command(cli)
 
 
 def main():

rem/config.py

@@ -15,7 +15,7 @@ File Format (~/.rem/config.yaml):
       pool_max_size: 20
 
     llm:
-      default_model: anthropic:claude-sonnet-4-5-20250929
+      default_model: openai:gpt-4.1
       openai_api_key: sk-...
       anthropic_api_key: sk-ant-...
 
@@ -95,9 +95,16 @@ def load_config() -> dict[str, Any]:
     """
     Load configuration from ~/.rem/config.yaml.
 
+    Set REM_SKIP_CONFIG=1 to skip loading the config file (useful when using .env files).
+
     Returns:
-        Configuration dictionary (empty if file doesn't exist)
+        Configuration dictionary (empty if file doesn't exist or skipped)
     """
+    # Allow skipping config file via environment variable
+    if os.environ.get("REM_SKIP_CONFIG", "").lower() in ("1", "true", "yes"):
+        logger.debug("Skipping config file (REM_SKIP_CONFIG is set)")
+        return {}
+
     config_path = get_config_path()
 
     if not config_path.exists():
@@ -216,7 +223,7 @@ def get_default_config() -> dict[str, Any]:
             "pool_max_size": 20,
         },
         "llm": {
-            "default_model": "anthropic:claude-sonnet-4-5-20250929",
+            "default_model": "openai:gpt-4.1",
             "default_temperature": 0.5,
             # API keys will be prompted for in wizard
             # "openai_api_key": "",

rem/models/core/core_model.py

@@ -52,7 +52,13 @@ class CoreModel(BaseModel):
         default=None, description="Tenant identifier for multi-tenancy isolation"
     )
     user_id: Optional[str] = Field(
-        default=None, description="Owner user identifier (tenant-scoped)"
+        default=None,
+        description=(
+            "Owner user identifier (tenant-scoped). This is a VARCHAR(256), not a UUID, "
+            "to allow flexibility for external identity providers. Typically generated as "
+            "a hash of the user's email address. In future, other strong unique claims "
+            "(e.g., OAuth sub, verified phone) could also be used for generation."
+        ),
     )
     graph_edges: list[dict] = Field(
         default_factory=list,

rem/models/core/experiment.py

@@ -138,18 +138,14 @@ class DatasetReference(BaseModel):
 
     path: str = Field(
         description=(
-            "Path to dataset:\n"
+            "Path to dataset. Format is inferred from file extension.\n"
+            "Supported: .csv, .tsv, .parquet, .json, .jsonl, .xlsx, .ods, .avro, .ipc\n"
             "- Git: Relative path from experiment root (e.g., 'datasets/ground_truth.csv')\n"
-            "- S3: Full S3 URI (e.g., 's3://bucket/experiments/my-exp/datasets/ground_truth.csv')\n"
+            "- S3: Full S3 URI (e.g., 's3://bucket/experiments/my-exp/datasets/data.parquet')\n"
             "- Hybrid: S3 URI for data, Git path for schema"
         )
     )
 
-    format: Literal["csv", "jsonl", "parquet", "json"] = Field(
-        default="csv",
-        description="Dataset file format"
-    )
-
     schema_path: str | None = Field(
         default=None,
         description=(
@@ -262,8 +258,7 @@ class ExperimentConfig(BaseModel):
     datasets:
       ground_truth:
         location: git
-        path: datasets/ground_truth.csv
-        format: csv
+        path: datasets/ground_truth.csv  # format inferred from extension
     results:
       location: git
       base_path: results/
@@ -288,12 +283,10 @@ class ExperimentConfig(BaseModel):
       ground_truth:
         location: s3
         path: s3://rem-prod/experiments/cv-parser-production/datasets/ground_truth.parquet
-        format: parquet
         schema_path: datasets/schema.yaml  # Schema in Git for documentation
       test_cases:
         location: s3
         path: s3://rem-prod/experiments/cv-parser-production/datasets/test_cases.jsonl
-        format: jsonl
     results:
       location: hybrid
       base_path: s3://rem-prod/experiments/cv-parser-production/results/
@@ -318,6 +311,15 @@ class ExperimentConfig(BaseModel):
         )
     )
 
+    task: str = Field(
+        default="general",
+        description=(
+            "Task name for organizing experiments by purpose.\n"
+            "Used with agent name to form directory: {agent}/{task}/\n"
+            "Examples: 'risk-assessment', 'classification', 'general'"
+        )
+    )
+
     description: str = Field(
         description="Human-readable description of experiment purpose and goals"
     )
@@ -410,6 +412,24 @@ class ExperimentConfig(BaseModel):
 
         return v
 
+    @field_validator("task")
+    @classmethod
+    def validate_task(cls, v: str) -> str:
+        """Validate task name follows conventions."""
+        if not v:
+            return "general"  # Default value
+
+        if not v.islower():
+            raise ValueError("Task name must be lowercase")
+
+        if " " in v:
+            raise ValueError("Task name cannot contain spaces (use hyphens)")
+
+        if not all(c.isalnum() or c == "-" for c in v):
+            raise ValueError("Task name can only contain lowercase letters, numbers, and hyphens")
+
+        return v
+
     @field_validator("tags")
     @classmethod
     def validate_tags(cls, v: list[str]) -> list[str]:
@@ -420,6 +440,15 @@ class ExperimentConfig(BaseModel):
         """Get the experiment directory path."""
         return Path(base_path) / self.name
 
+    def get_agent_task_dir(self, base_path: str = ".experiments") -> Path:
+        """
+        Get the experiment directory path organized by agent/task.
+
+        Returns: Path like .experiments/{agent}/{task}/
+        This is the recommended structure for S3 export compatibility.
+        """
+        return Path(base_path) / self.agent_schema_ref.name / self.task
+
     def get_config_path(self, base_path: str = ".experiments") -> Path:
         """Get the path to experiment.yaml file."""
         return self.get_experiment_dir(base_path) / "experiment.yaml"
@@ -428,6 +457,22 @@ class ExperimentConfig(BaseModel):
         """Get the path to README.md file."""
         return self.get_experiment_dir(base_path) / "README.md"
 
+    def get_evaluator_filename(self) -> str:
+        """
+        Get the evaluator filename with task prefix.
+
+        Returns: {agent_name}-{task}.yaml (e.g., siggy-risk-assessment.yaml)
+        """
+        return f"{self.agent_schema_ref.name}-{self.task}.yaml"
+
+    def get_s3_export_path(self, bucket: str, version: str = "v0") -> str:
+        """
+        Get the S3 path for exporting this experiment.
+
+        Returns: s3://{bucket}/{version}/datasets/calibration/experiments/{agent}/{task}/
+        """
+        return f"s3://{bucket}/{version}/datasets/calibration/experiments/{self.agent_schema_ref.name}/{self.task}"
+
     def to_yaml(self) -> str:
         """Export configuration as YAML string."""
         import yaml
@@ -483,6 +528,7 @@ class ExperimentConfig(BaseModel):
 ## Configuration
 
 **Status**: `{self.status.value}`
+**Task**: `{self.task}`
 **Tags**: {', '.join(f'`{tag}`' for tag in self.tags) if self.tags else 'None'}
 
 ## Agent Schema
@@ -494,6 +540,7 @@ class ExperimentConfig(BaseModel):
 ## Evaluator Schema
 
 - **Name**: `{self.evaluator_schema_ref.name}`
+- **File**: `{self.get_evaluator_filename()}`
 - **Type**: `{self.evaluator_schema_ref.type}`
 
 ## Datasets
@@ -504,7 +551,6 @@ class ExperimentConfig(BaseModel):
 
 - **Location**: `{dataset.location.value}`
 - **Path**: `{dataset.path}`
-- **Format**: `{dataset.format}`
 """
             if dataset.description:
                 readme += f"- **Description**: {dataset.description}\n"
@@ -575,7 +621,6 @@ EXAMPLE_SMALL_EXPERIMENT = ExperimentConfig(
         "ground_truth": DatasetReference(
             location=DatasetLocation.GIT,
             path="datasets/ground_truth.csv",
-            format="csv",
             description="10 manually curated test cases"
         )
     },
@@ -605,7 +650,6 @@ EXAMPLE_LARGE_EXPERIMENT = ExperimentConfig(
         "ground_truth": DatasetReference(
             location=DatasetLocation.S3,
             path="s3://rem-prod/experiments/cv-parser-production/datasets/ground_truth.parquet",
-            format="parquet",
             schema_path="datasets/schema.yaml",
             description="10,000 CV/resume pairs with ground truth extractions"
         )

rem/models/core/rem_query.py

@@ -112,7 +112,7 @@ class SearchParameters(BaseModel):
     table_name: str = Field(..., description="Table to search (resources, moments, etc.)")
     limit: int = Field(default=10, gt=0, description="Maximum results")
     min_similarity: float = Field(
-        default=0.7, ge=0.0, le=1.0, description="Minimum similarity score"
+        default=0.3, ge=0.0, le=1.0, description="Minimum similarity score (0.3 recommended for general queries)"
     )
 
 
@@ -198,7 +198,10 @@ class RemQuery(BaseModel):
         | SQLParameters
         | TraverseParameters
     ) = Field(..., description="Query parameters")
-    user_id: str = Field(..., description="User identifier for isolation")
+    user_id: Optional[str] = Field(
+        default=None,
+        description="User identifier (UUID5 hash of email). None = anonymous (shared/public data only)"
+    )
 
 
 class TraverseStage(BaseModel):

rem/models/entities/__init__.py

@@ -5,6 +5,9 @@ Core entity types for the REM system:
 - Resources: Base content units (documents, conversations, artifacts)
 - ImageResources: Image-specific resources with CLIP embeddings
 - Messages: Communication content
+- Sessions: Conversation sessions (normal or evaluation mode)
+- SharedSessions: Session sharing between users for collaboration
+- Feedback: User feedback on messages/sessions with trace integration
 - Users: User entities
 - Files: File metadata and tracking
 - Moments: Temporal narratives (meetings, coding sessions, conversations)
@@ -19,6 +22,8 @@ All entities inherit from CoreModel and support:
 - Natural language labels for conversational queries
 """
 
+from .domain_resource import DomainResource
+from .feedback import Feedback, FeedbackCategory
 from .file import File
 from .image_resource import ImageResource
 from .message import Message
@@ -27,14 +32,34 @@ from .ontology import Ontology
 from .ontology_config import OntologyConfig
 from .resource import Resource
 from .schema import Schema
+from .session import Session, SessionMode
+from .shared_session import (
+    SharedSession,
+    SharedSessionCreate,
+    SharedWithMeResponse,
+    SharedWithMeSummary,
+)
+from .subscriber import Subscriber, SubscriberOrigin, SubscriberStatus
 from .user import User, UserTier
 
 __all__ = [
     "Resource",
+    "DomainResource",
     "ImageResource",
     "Message",
+    "Session",
+    "SessionMode",
+    "SharedSession",
+    "SharedSessionCreate",
+    "SharedWithMeResponse",
+    "SharedWithMeSummary",
+    "Feedback",
+    "FeedbackCategory",
     "User",
     "UserTier",
+    "Subscriber",
+    "SubscriberStatus",
+    "SubscriberOrigin",
     "File",
     "Moment",
     "Schema",

rem/models/entities/domain_resource.py

@@ -0,0 +1,38 @@
+"""
+DomainResource - Curated internal knowledge in REM.
+
+DomainResources are a specialized subclass of Resource for storing curated,
+domain-specific internal knowledge that is not part of general knowledge.
+This includes proprietary information, internal documentation, institutional
+knowledge, and other content that requires more careful curation.
+
+Key Differences from Resource:
+- Intended for curated, internal knowledge (not raw ingested content)
+- Higher quality bar - content is reviewed/vetted before ingestion
+- May contain proprietary or sensitive information
+- Subject to different retention/governance policies
+
+Use Cases:
+- Internal documentation and procedures
+- Proprietary research and analysis
+- Institutional knowledge bases
+- Domain-specific ontologies and taxonomies
+- Curated best practices and guidelines
+"""
+
+from .resource import Resource
+
+
+class DomainResource(Resource):
+    """
+    Curated domain-specific knowledge resource.
+
+    Inherits all fields from Resource but stored in a separate table
+    (domain_resources) to distinguish curated internal knowledge from
+    general ingested content.
+
+    The schema is identical to Resource, allowing seamless migration
+    of content between tables as curation status changes.
+    """
+
+    pass

rem/models/entities/feedback.py

@@ -0,0 +1,123 @@
+"""
+Feedback - User feedback on chat messages and sessions.
+
+Feedback allows users to rate and categorize responses, providing
+data for evaluation and model improvement. Feedback can be attached
+to specific messages or entire sessions.
+
+Trace Integration:
+- Feedback references trace_id/span_id for OTEL/Phoenix integration
+- Can attach annotations to Phoenix spans for unified observability
+
+Predefined Categories (system-defined, extensible):
+- INCOMPLETE: Response lacks expected information
+- INACCURATE: Response contains factual errors
+- POOR_TONE: Inappropriate or unprofessional tone
+- OFF_TOPIC: Response doesn't address the question
+- TOO_VERBOSE: Unnecessarily long response
+- TOO_BRIEF: Insufficiently detailed response
+- HELPFUL: Positive feedback marker
+- EXCELLENT: Exceptionally good response
+"""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import Field
+
+from ..core import CoreModel
+
+
+class FeedbackCategory(str, Enum):
+    """Predefined feedback categories (system-defined)."""
+
+    # Negative categories
+    INCOMPLETE = "incomplete"
+    INACCURATE = "inaccurate"
+    POOR_TONE = "poor_tone"
+    OFF_TOPIC = "off_topic"
+    TOO_VERBOSE = "too_verbose"
+    TOO_BRIEF = "too_brief"
+    CONFUSING = "confusing"
+    UNSAFE = "unsafe"
+
+    # Positive categories
+    HELPFUL = "helpful"
+    EXCELLENT = "excellent"
+    ACCURATE = "accurate"
+    WELL_WRITTEN = "well_written"
+
+    # Neutral/Other
+    OTHER = "other"
+
+
+class Feedback(CoreModel):
+    """
+    User feedback on a message or session.
+
+    Captures structured feedback including:
+    - Rating (1-5 scale or thumbs up/down)
+    - Categories (predefined or custom)
+    - Free-text comment
+    - Trace reference for OTEL/Phoenix integration
+
+    The feedback can be attached to:
+    - A specific message (message_id set)
+    - An entire session (session_id set, message_id null)
+    """
+
+    # Target reference (at least one required)
+    session_id: str = Field(
+        ...,
+        description="Session ID this feedback relates to",
+    )
+    message_id: str | None = Field(
+        default=None,
+        description="Specific message ID (null for session-level feedback)",
+    )
+
+    # Rating (flexible: 1-5, or -1/1 for thumbs)
+    rating: int | None = Field(
+        default=None,
+        ge=-1,
+        le=5,
+        description="Rating: -1 (thumbs down), 1 (thumbs up), or 1-5 scale",
+    )
+
+    # Categories (can select multiple)
+    categories: list[str] = Field(
+        default_factory=list,
+        description="Selected feedback categories (from FeedbackCategory or custom)",
+    )
+
+    # Free-text comment
+    comment: str | None = Field(
+        default=None,
+        description="Optional free-text feedback comment",
+    )
+
+    # Trace reference for OTEL/Phoenix integration
+    trace_id: str | None = Field(
+        default=None,
+        description="OTEL trace ID for linking to observability",
+    )
+    span_id: str | None = Field(
+        default=None,
+        description="OTEL span ID for specific span feedback",
+    )
+
+    # Phoenix annotation status
+    phoenix_synced: bool = Field(
+        default=False,
+        description="Whether feedback has been synced to Phoenix as annotation",
+    )
+    phoenix_annotation_id: str | None = Field(
+        default=None,
+        description="Phoenix annotation ID after sync",
+    )
+
+    # Annotator info
+    annotator_kind: str = Field(
+        default="HUMAN",
+        description="Annotator type: HUMAN, LLM, CODE",
+    )

rem/models/entities/message.py

@@ -6,6 +6,11 @@ that can be grouped into conversations or moments.
 
 Messages are simpler than Resources but share the same graph connectivity
 through CoreModel inheritance.
+
+Trace Integration:
+- trace_id: OTEL trace ID for linking to observability
+- span_id: OTEL span ID for specific span reference
+- These enable feedback to be attached to Phoenix annotations
 """
 
 from pydantic import Field
@@ -19,6 +24,9 @@ class Message(CoreModel):
 
     Represents individual messages in conversations, chats, or other
     communication contexts. Tenant isolation is provided via CoreModel.tenant_id field.
+
+    Trace fields (trace_id, span_id) enable integration with OTEL/Phoenix
+    for observability and feedback annotation.
     """
 
     content: str = Field(
@@ -27,9 +35,30 @@ class Message(CoreModel):
     )
     message_type: str | None = Field(
         default=None,
-        description="Message type e.g role",
+        description="Message type e.g. role: 'user', 'assistant', 'system', 'tool'",
     )
     session_id: str | None = Field(
         default=None,
         description="Session identifier for tracking message context",
     )
+    prompt: str | None = Field(
+        default=None,
+        description="Custom prompt used for this message (if overridden from default)",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Model used for generating this message (provider:model format)",
+    )
+    token_count: int | None = Field(
+        default=None,
+        description="Token count for this message",
+    )
+    # OTEL/Phoenix trace integration
+    trace_id: str | None = Field(
+        default=None,
+        description="OTEL trace ID for observability integration",
+    )
+    span_id: str | None = Field(
+        default=None,
+        description="OTEL span ID for specific span reference",
+    )

rem/models/entities/ontology.py

@@ -129,7 +129,7 @@ class Ontology(CoreModel):
             file_id="file-uuid-456",
             agent_schema_id="contract-parser-v2",
             provider_name="openai",
-            model_name="gpt-4o",
+            model_name="gpt-4.1",
             extracted_data={
                 "contract_type": "supplier_agreement",
                 "parties": [

rem/models/entities/ontology_config.py

@@ -74,7 +74,7 @@ class OntologyConfig(CoreModel):
             priority=200,  # Higher priority = runs first
             enabled=True,
             provider_name="openai",  # Override default provider
-            model_name="gpt-4o",
+            model_name="gpt-4.1",
             tenant_id="acme-corp",
             tags=["legal", "procurement"]
         )

rem/models/entities/session.py

@@ -0,0 +1,83 @@
+"""
+Session - Conversation sessions in REM.
+
+Sessions group related messages together and can have different modes:
+- normal: Standard conversation session
+- evaluation: For LLM evaluation, stores original trace and overridden settings
+
+Sessions allow overriding settings like model, temperature, and custom prompts
+for evaluation and experimentation purposes.
+"""
+
+from enum import Enum
+
+from pydantic import Field
+
+from ..core import CoreModel
+
+
+class SessionMode(str, Enum):
+    """Session mode types."""
+
+    NORMAL = "normal"
+    EVALUATION = "evaluation"
+
+
+class Session(CoreModel):
+    """
+    Conversation session container.
+
+    Groups messages together and supports different modes for normal conversations
+    and evaluation/experimentation scenarios.
+
+    For evaluation sessions, stores:
+    - original_trace_id: Reference to the original session being evaluated
+    - settings_overrides: Model, temperature, prompt overrides
+    - prompt: Custom prompt being tested
+
+    Default sessions are lightweight - just a session_id on messages.
+    Special sessions store additional metadata for experiments.
+    """
+
+    name: str = Field(
+        ...,
+        description="Session name/identifier",
+        json_schema_extra={"entity_key": True},
+    )
+    mode: SessionMode = Field(
+        default=SessionMode.NORMAL,
+        description="Session mode: 'normal' or 'evaluation'",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional session description",
+    )
+    # Evaluation-specific fields
+    original_trace_id: str | None = Field(
+        default=None,
+        description="For evaluation mode: ID of the original session/trace being evaluated",
+    )
+    settings_overrides: dict | None = Field(
+        default=None,
+        description="Settings overrides (model, temperature, max_tokens, system_prompt)",
+    )
+    prompt: str | None = Field(
+        default=None,
+        description="Custom prompt for this session (can override agent prompt)",
+    )
+    # Agent context
+    agent_schema_uri: str | None = Field(
+        default=None,
+        description="Agent schema used for this session",
+    )
+    # Summary stats (updated as session progresses)
+    message_count: int = Field(
+        default=0,
+        description="Number of messages in this session",
+    )
+    total_tokens: int | None = Field(
+        default=None,
+        description="Total tokens used in this session",
+    )
+
+    model_config = {"use_enum_values": True}