remdb 0.3.103__py3-none-any.whl → 0.3.141__py3-none-any.whl

rem/models/core/experiment.py

@@ -318,6 +318,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 +419,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 +447,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 +464,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 +535,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 +547,7 @@ class ExperimentConfig(BaseModel):
 ## Evaluator Schema
 
 - **Name**: `{self.evaluator_schema_ref.name}`
+- **File**: `{self.get_evaluator_filename()}`
 - **Type**: `{self.evaluator_schema_ref.type}`
 
 ## Datasets

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/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/shared_session.py

@@ -111,28 +111,20 @@ To permanently delete, an admin can run:
 
 from datetime import datetime
 from typing import Optional
-from uuid import UUID
 
 from pydantic import BaseModel, Field
 
-from ...utils.date_utils import utc_now
+from ..core import CoreModel
 
 
-class SharedSession(BaseModel):
+class SharedSession(CoreModel):
     """
     Session sharing record between users.
 
     Links a session (identified by session_id from Message records) to a
     recipient user, enabling collaborative access to conversation history.
-
-    This is NOT a CoreModel - it's a lightweight linking table without
-    graph edges, metadata, or embeddings.
     """
 
-    id: Optional[UUID] = Field(
-        default=None,
-        description="Unique identifier (auto-generated)",
-    )
     session_id: str = Field(
         ...,
         description="The session being shared (matches Message.session_id)",
@@ -145,24 +137,6 @@ class SharedSession(BaseModel):
         ...,
         description="User ID of the recipient (who can now view the session)",
     )
-    tenant_id: str = Field(
-        default="default",
-        description="Tenant identifier for multi-tenancy isolation",
-    )
-    created_at: datetime = Field(
-        default_factory=utc_now,
-        description="When the share was created",
-    )
-    updated_at: datetime = Field(
-        default_factory=utc_now,
-        description="Last modification timestamp",
-    )
-    deleted_at: Optional[datetime] = Field(
-        default=None,
-        description="Soft delete timestamp (null = active share)",
-    )
-
-    model_config = {"from_attributes": True}
 
 
 class SharedSessionCreate(BaseModel):

rem/registry.py

@@ -123,6 +123,7 @@ class ModelRegistry:
             return
 
         from .models.entities import (
+            Feedback,
             File,
             ImageResource,
             Message,
@@ -131,19 +132,24 @@ class ModelRegistry:
             OntologyConfig,
             Resource,
             Schema,
+            Session,
+            SharedSession,
             User,
         )
 
         core_models = [
-            Resource,
+            Feedback,
+            File,
             ImageResource,
             Message,
-            User,
-            File,
             Moment,
-            Schema,
             Ontology,
             OntologyConfig,
+            Resource,
+            Schema,
+            Session,
+            SharedSession,
+            User,
         ]
 
         for model in core_models:

rem/schemas/agents/examples/contract-analyzer.yaml

@@ -308,7 +308,7 @@ json_schema_extra:
   - provider_name: anthropic
     model_name: claude-sonnet-4-5-20250929
   - provider_name: openai
-    model_name: gpt-4o
+    model_name: gpt-4.1
   embedding_fields:
   - contract_title
   - contract_type

rem/schemas/agents/examples/contract-extractor.yaml

@@ -131,4 +131,4 @@ json_schema_extra:
   - provider_name: anthropic
     model_name: claude-sonnet-4-5-20250929
   - provider_name: openai
-    model_name: gpt-4o
+    model_name: gpt-4.1

rem/schemas/agents/examples/cv-parser.yaml

@@ -255,7 +255,7 @@ json_schema_extra:
     - provider_name: anthropic
       model_name: claude-sonnet-4-5-20250929
     - provider_name: openai
-      model_name: gpt-4o
+      model_name: gpt-4.1
   embedding_fields:
     - candidate_name
     - professional_summary

rem/services/content/service.py

@@ -370,11 +370,32 @@ class ContentService:
         file_size = len(file_content)
         logger.info(f"Read {file_size} bytes from {file_uri} (source: {source_type})")
 
-        # Step 2: Write to internal storage (user-scoped)
+        # Step 1.5: Early schema detection for YAML/JSON files
+        # Skip File entity creation for schemas (agents/evaluators)
+        file_suffix = Path(file_name).suffix.lower()
+        if file_suffix in ['.yaml', '.yml', '.json']:
+            import yaml
+            import json
+            try:
+                content_text = file_content.decode('utf-8') if isinstance(file_content, bytes) else file_content
+                data = yaml.safe_load(content_text) if file_suffix in ['.yaml', '.yml'] else json.loads(content_text)
+                if isinstance(data, dict):
+                    json_schema_extra = data.get('json_schema_extra', {})
+                    kind = json_schema_extra.get('kind', '')
+                    if kind in ['agent', 'evaluator']:
+                        # Route directly to schema processing, skip File entity
+                        logger.info(f"Detected {kind} schema: {file_name}, routing to _process_schema")
+                        result = self.process_uri(file_uri)
+                        return await self._process_schema(result, file_uri, user_id)
+            except Exception as e:
+                logger.debug(f"Early schema detection failed for {file_name}: {e}")
+                # Fall through to standard file processing
+
+        # Step 2: Write to internal storage (public or user-scoped)
         file_id = str(uuid4())
         storage_uri, internal_key, content_type, _ = await fs_service.write_to_internal_storage(
             content=file_content,
-            tenant_id=user_id,  # Using user_id for storage scoping
+            tenant_id=user_id or "public",  # Storage path: public/ or user_id/
             file_name=file_name,
             file_id=file_id,
         )
@@ -383,7 +404,7 @@ class ContentService:
         # Step 3: Create File entity
         file_entity = File(
             id=file_id,
-            tenant_id=user_id,  # Set tenant_id to user_id (application scoped to user)
+            tenant_id=user_id,  # None = public/shared
             user_id=user_id,
             name=file_name,
             uri=storage_uri,
@@ -538,7 +559,7 @@ class ContentService:
             size_bytes=result["metadata"].get("size"),
             mime_type=result["metadata"].get("content_type"),
             processing_status="completed",
-            tenant_id=user_id or "default",  # Required field
+            tenant_id=user_id,  # None = public/shared
             user_id=user_id,
         )
 
@@ -571,7 +592,7 @@ class ContentService:
                 ordinal=i,
                 content=chunk,
                 category="document",
-                tenant_id=user_id or "default",  # Required field
+                tenant_id=user_id,  # None = public/shared
                 user_id=user_id,
             )
             for i, chunk in enumerate(chunks)
@@ -645,9 +666,10 @@ class ContentService:
         # IMPORTANT: category field distinguishes agents from evaluators
         # - kind=agent → category="agent" (AI agents with tools/resources)
         # - kind=evaluator → category="evaluator" (LLM-as-a-Judge evaluators)
+        # Schemas (agents/evaluators) default to system tenant for shared access
         schema_entity = Schema(
-            tenant_id=user_id or "default",
-            user_id=user_id,
+            tenant_id="system",
+            user_id=None,
             name=name,
             spec=schema_data,
             category=kind,  # Maps kind → category for database filtering
@@ -717,7 +739,7 @@ class ContentService:
             processor = EngramProcessor(postgres)
             result = await processor.process_engram(
                 data=data,
-                tenant_id=user_id or "default",
+                tenant_id=user_id,  # None = public/shared
                 user_id=user_id,
             )
             logger.info(f"✅ Engram processed: {result.get('resource_id')} with {len(result.get('moment_ids', []))} moments")

rem/services/embeddings/api.py

@@ -45,7 +45,7 @@ def generate_embedding(
             return [0.0] * DEFAULT_EMBEDDING_DIMS
 
         try:
-            logger.info(f"Generating OpenAI embedding for text using {model}")
+            logger.debug(f"Generating OpenAI embedding for text using {model}")
 
             response = requests.post(
                 "https://api.openai.com/v1/embeddings",
@@ -60,7 +60,7 @@ def generate_embedding(
 
             data = response.json()
             embedding = data["data"][0]["embedding"]
-            logger.info(f"Successfully generated embedding (dimension: {len(embedding)})")
+            logger.debug(f"Successfully generated embedding (dimension: {len(embedding)})")
             return cast(list[float], embedding)
 
         except Exception as e:
@@ -97,7 +97,7 @@ async def generate_embedding_async(
             return [0.0] * DEFAULT_EMBEDDING_DIMS
 
         try:
-            logger.info(f"Generating OpenAI embedding for text using {model}")
+            logger.debug(f"Generating OpenAI embedding for text using {model}")
 
             async with httpx.AsyncClient() as client:
                 response = await client.post(
@@ -113,7 +113,7 @@ async def generate_embedding_async(
 
                 data = response.json()
                 embedding = data["data"][0]["embedding"]
-                logger.info(
+                logger.debug(
                     f"Successfully generated embedding (dimension: {len(embedding)})"
                 )
                 return cast(list[float], embedding)

rem/services/embeddings/worker.py

@@ -69,7 +69,7 @@ def get_global_embedding_worker(postgres_service: Any = None) -> "EmbeddingWorke
         if postgres_service is None:
             raise RuntimeError("Must provide postgres_service on first call to get_global_embedding_worker")
         _global_worker = EmbeddingWorker(postgres_service=postgres_service)
-        logger.info("Created global EmbeddingWorker singleton")
+        logger.debug("Created global EmbeddingWorker singleton")
 
     return _global_worker
 
@@ -117,7 +117,7 @@ class EmbeddingWorker:
                 "No OpenAI API key provided - embeddings will use zero vectors"
             )
 
-        logger.info(
+        logger.debug(
             f"Initialized EmbeddingWorker: {num_workers} workers, "
             f"batch_size={batch_size}, timeout={batch_timeout}s"
         )
@@ -125,17 +125,17 @@ class EmbeddingWorker:
     async def start(self) -> None:
         """Start worker pool."""
         if self.running:
-            logger.warning("EmbeddingWorker already running")
+            logger.debug("EmbeddingWorker already running")
             return
 
         self.running = True
-        logger.info(f"Starting {self.num_workers} embedding workers")
+        logger.debug(f"Starting {self.num_workers} embedding workers")
 
         for i in range(self.num_workers):
             worker = asyncio.create_task(self._worker_loop(i))
             self.workers.append(worker)
 
-        logger.info("EmbeddingWorker started")
+        logger.debug("EmbeddingWorker started")
 
     async def stop(self) -> None:
         """Stop worker pool gracefully - processes remaining queue before stopping."""
@@ -143,7 +143,7 @@ class EmbeddingWorker:
             return
 
         queue_size = self.task_queue.qsize()
-        logger.info(f"Stopping EmbeddingWorker (processing {queue_size} queued tasks first)")
+        logger.debug(f"Stopping EmbeddingWorker (processing {queue_size} queued tasks first)")
 
         # Wait for queue to drain (with timeout)
         max_wait = 30  # 30 seconds max
@@ -171,7 +171,7 @@ class EmbeddingWorker:
         await asyncio.gather(*self.workers, return_exceptions=True)
 
         self.workers.clear()
-        logger.info("EmbeddingWorker stopped")
+        logger.debug("EmbeddingWorker stopped")
 
     async def queue_task(self, task: EmbeddingTask) -> None:
         """
@@ -195,7 +195,7 @@ class EmbeddingWorker:
         Args:
             worker_id: Unique worker identifier
         """
-        logger.info(f"Worker {worker_id} started")
+        logger.debug(f"Worker {worker_id} started")
 
         while self.running:
             try:
@@ -205,7 +205,7 @@ class EmbeddingWorker:
                 if not batch:
                     continue
 
-                logger.info(f"Worker {worker_id} processing batch of {len(batch)} tasks")
+                logger.debug(f"Worker {worker_id} processing batch of {len(batch)} tasks")
 
                 # Generate embeddings for batch
                 await self._process_batch(batch)
@@ -213,14 +213,14 @@ class EmbeddingWorker:
                 logger.debug(f"Worker {worker_id} completed batch")
 
             except asyncio.CancelledError:
-                logger.info(f"Worker {worker_id} cancelled")
+                logger.debug(f"Worker {worker_id} cancelled")
                 break
             except Exception as e:
                 logger.error(f"Worker {worker_id} error: {e}", exc_info=True)
                 # Continue processing (don't crash worker on error)
                 await asyncio.sleep(1)
 
-        logger.info(f"Worker {worker_id} stopped")
+        logger.debug(f"Worker {worker_id} stopped")
 
     async def _collect_batch(self) -> list[EmbeddingTask]:
         """
@@ -284,10 +284,10 @@ class EmbeddingWorker:
             )
 
             # Upsert to database
-            logger.info(f"Upserting {len(embeddings)} embeddings to database...")
+            logger.debug(f"Upserting {len(embeddings)} embeddings to database...")
             await self._upsert_embeddings(batch, embeddings)
 
-            logger.info(
+            logger.debug(
                 f"Successfully generated and stored {len(embeddings)} embeddings "
                 f"(provider={provider}, model={model})"
             )
@@ -315,7 +315,7 @@ class EmbeddingWorker:
         """
         if provider == "openai" and self.openai_api_key:
             try:
-                logger.info(
+                logger.debug(
                     f"Generating OpenAI embeddings for {len(texts)} texts using {model}"
                 )
 
@@ -336,7 +336,7 @@ class EmbeddingWorker:
                     data = response.json()
                     embeddings = [item["embedding"] for item in data["data"]]
 
-                    logger.info(
+                    logger.debug(
                         f"Successfully generated {len(embeddings)} embeddings from OpenAI"
                     )
                     return embeddings
@@ -409,7 +409,7 @@ class EmbeddingWorker:
                     ),
                 )
 
-                logger.info(
+                logger.debug(
                     f"Upserted embedding: {task.table_name}.{task.entity_id}.{task.field_name}"
                 )
 

rem/services/phoenix/client.py

@@ -793,40 +793,72 @@ class PhoenixClient:
         score: float | None = None,
         explanation: str | None = None,
         metadata: dict[str, Any] | None = None,
+        trace_id: str | None = None,
     ) -> str | None:
-        """Add feedback annotation to a span.
+        """Add feedback annotation to a span via Phoenix REST API.
+
+        Uses direct HTTP POST to /v1/span_annotations for reliability
+        (Phoenix Python client API changes frequently).
 
         Args:
-            span_id: Span ID to annotate
+            span_id: Span ID to annotate (hex string)
             annotation_name: Name of the annotation (e.g., "correctness", "user_feedback")
             annotator_kind: Type of annotator ("HUMAN", "LLM", "CODE")
             label: Optional label (e.g., "correct", "incorrect", "helpful")
             score: Optional numeric score (0.0-1.0)
             explanation: Optional explanation text
             metadata: Optional additional metadata dict
+            trace_id: Optional trace ID (used if span lookup needed)
 
         Returns:
             Annotation ID if successful, None otherwise
         """
+        import httpx
+
         try:
-            result = self._client.add_span_annotation(  # type: ignore[attr-defined]
-                span_id=span_id,
-                name=annotation_name,
-                annotator_kind=annotator_kind,
-                label=label,
-                score=score,
-                explanation=explanation,
-                metadata=metadata,
-            )
+            # Build annotation payload for Phoenix REST API
+            annotation_data = {
+                "span_id": span_id,
+                "name": annotation_name,
+                "annotator_kind": annotator_kind,
+                "result": {
+                    "label": label,
+                    "score": score,
+                    "explanation": explanation,
+                },
+                "metadata": metadata or {},
+            }
 
-            annotation_id = getattr(result, "id", None) if result else None
-            logger.info(f"Added {annotator_kind} feedback to span {span_id} -> {annotation_id}")
+            # Add trace_id if provided
+            if trace_id:
+                annotation_data["trace_id"] = trace_id
+
+            # POST to Phoenix REST API
+            annotations_endpoint = f"{self.config.base_url}/v1/span_annotations"
+            headers = {}
+            if self.config.api_key:
+                headers["Authorization"] = f"Bearer {self.config.api_key}"
+
+            with httpx.Client(timeout=5.0) as client:
+                response = client.post(
+                    annotations_endpoint,
+                    json={"data": [annotation_data]},
+                    headers=headers,
+                )
+                response.raise_for_status()
 
-            return annotation_id
+            logger.info(f"Added {annotator_kind} feedback to span {span_id}")
+            return span_id  # Return span_id as annotation reference
 
+        except httpx.HTTPStatusError as e:
+            logger.error(
+                f"Failed to add span feedback (HTTP {e.response.status_code}): "
+                f"{e.response.text if hasattr(e, 'response') else 'N/A'}"
+            )
+            return None
         except Exception as e:
             logger.error(f"Failed to add span feedback: {e}")
-            raise
+            return None
 
     def sync_user_feedback(
         self,
@@ -835,6 +867,7 @@ class PhoenixClient:
         categories: list[str] | None = None,
         comment: str | None = None,
         feedback_id: str | None = None,
+        trace_id: str | None = None,
     ) -> str | None:
         """Sync user feedback to Phoenix as a span annotation.
 
@@ -847,6 +880,7 @@ class PhoenixClient:
             categories: List of feedback categories
             comment: Free-text comment
             feedback_id: Optional REM feedback ID for reference
+            trace_id: Optional trace ID for the span
 
         Returns:
             Phoenix annotation ID if successful
@@ -860,12 +894,18 @@ class PhoenixClient:
             ... )
         """
         # Convert rating to 0-1 score
+        # Rating scheme:
+        #   -1 = thumbs down → score 0.0
+        #    1 = thumbs up   → score 1.0
+        #  2-5 = star rating → normalized to 0-1 range
         score = None
         if rating is not None:
             if rating == -1:
                 score = 0.0
-            elif 1 <= rating <= 5:
-                score = rating / 5.0
+            elif rating == 1:
+                score = 1.0  # Thumbs up
+            elif 2 <= rating <= 5:
+                score = (rating - 1) / 4.0  # 2→0.25, 3→0.5, 4→0.75, 5→1.0
 
         # Use primary category as label
         label = categories[0] if categories else None
@@ -880,7 +920,7 @@ class PhoenixClient:
                 explanation = f"Categories: {cats_str}"
 
         # Build metadata
-        metadata = {
+        metadata: dict[str, Any] = {
             "rating": rating,
             "categories": categories or [],
         }
@@ -895,6 +935,7 @@ class PhoenixClient:
             score=score,
             explanation=explanation,
             metadata=metadata,
+            trace_id=trace_id,
         )
 
     def get_span_annotations(