sentienceapi 0.90.16__py3-none-any.whl → 0.98.0__py3-none-any.whl

sentience/trace_indexing/index_schema.py

@@ -13,6 +13,7 @@ class TraceFileInfo:
     path: str
     size_bytes: int
     sha256: str
+    line_count: int | None = None  # Number of lines in the trace file
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -28,6 +29,12 @@ class TraceSummary:
     step_count: int
     error_count: int
     final_url: str | None
+    status: Literal["success", "failure", "partial", "unknown"] | None = None
+    agent_name: str | None = None  # Agent name from run_start event
+    duration_ms: int | None = None  # Calculated duration in milliseconds
+    counters: dict[str, int] | None = (
+        None  # Aggregated counters (snapshot_count, action_count, error_count)
+    )
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -78,17 +85,18 @@ class StepIndex:
     step_index: int
     step_id: str
     goal: str | None
-    status: Literal["ok", "error", "partial"]
+    status: Literal["success", "failure", "partial", "unknown"]
     ts_start: str
     ts_end: str
     offset_start: int
     offset_end: int
-    url_before: str | None
-    url_after: str | None
-    snapshot_before: SnapshotInfo
-    snapshot_after: SnapshotInfo
-    action: ActionInfo
-    counters: StepCounters
+    line_number: int | None = None  # Line number for byte-range fetching
+    url_before: str | None = None
+    url_after: str | None = None
+    snapshot_before: SnapshotInfo = field(default_factory=SnapshotInfo)
+    snapshot_after: SnapshotInfo = field(default_factory=SnapshotInfo)
+    action: ActionInfo = field(default_factory=ActionInfo)
+    counters: StepCounters = field(default_factory=StepCounters)
 
     def to_dict(self) -> dict:
         result = asdict(self)
@@ -109,3 +117,83 @@ class TraceIndex:
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
         return asdict(self)
+
+    def to_sentience_studio_dict(self) -> dict:
+        """
+        Convert to SS-compatible format.
+
+        Maps SDK field names to frontend expectations:
+        - created_at -> generated_at
+        - first_ts -> start_time
+        - last_ts -> end_time
+        - step_index (0-based) -> step (1-based)
+        - ts_start -> timestamp
+        - Filters out "unknown" status
+        """
+        from datetime import datetime
+
+        # Calculate duration if not already set
+        duration_ms = self.summary.duration_ms
+        if duration_ms is None and self.summary.first_ts and self.summary.last_ts:
+            try:
+                start = datetime.fromisoformat(self.summary.first_ts.replace("Z", "+00:00"))
+                end = datetime.fromisoformat(self.summary.last_ts.replace("Z", "+00:00"))
+                duration_ms = int((end - start).total_seconds() * 1000)
+            except (ValueError, AttributeError):
+                duration_ms = None
+
+        # Aggregate counters if not already set
+        counters = self.summary.counters
+        if counters is None:
+            snapshot_count = sum(step.counters.snapshots for step in self.steps)
+            action_count = sum(step.counters.actions for step in self.steps)
+            counters = {
+                "snapshot_count": snapshot_count,
+                "action_count": action_count,
+                "error_count": self.summary.error_count,
+            }
+
+        return {
+            "version": self.version,
+            "run_id": self.run_id,
+            "generated_at": self.created_at,  # Renamed from created_at
+            "trace_file": {
+                "path": self.trace_file.path,
+                "size_bytes": self.trace_file.size_bytes,
+                "line_count": self.trace_file.line_count,  # Added
+            },
+            "summary": {
+                "agent_name": self.summary.agent_name,  # Added
+                "total_steps": self.summary.step_count,  # Renamed from step_count
+                "status": (
+                    self.summary.status if self.summary.status != "unknown" else None
+                ),  # Filter out unknown
+                "start_time": self.summary.first_ts,  # Renamed from first_ts
+                "end_time": self.summary.last_ts,  # Renamed from last_ts
+                "duration_ms": duration_ms,  # Added
+                "counters": counters,  # Added
+            },
+            "steps": [
+                {
+                    "step": s.step_index + 1,  # Convert 0-based to 1-based
+                    "byte_offset": s.offset_start,
+                    "line_number": s.line_number,  # Added
+                    "timestamp": s.ts_start,  # Use start time
+                    "action": {
+                        "type": s.action.type or "",
+                        "goal": s.goal,  # Move goal into action
+                        "digest": s.action.args_digest,
+                    },
+                    "snapshot": (
+                        {
+                            "url": s.snapshot_after.url,
+                            "digest": s.snapshot_after.digest,
+                        }
+                        if s.snapshot_after.url
+                        else None
+                    ),
+                    "status": s.status if s.status != "unknown" else None,  # Filter out unknown
+                }
+                for s in self.steps
+            ],
+        }

sentience/trace_indexing/indexer.py

@@ -7,8 +7,9 @@ import json
 import os
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Optional
 
+from ..canonicalization import canonicalize_element
 from .index_schema import (
     ActionInfo,
     SnapshotInfo,
@@ -20,30 +21,6 @@ from .index_schema import (
 )
 
 
-def _normalize_text(text: str | None, max_len: int = 80) -> str:
-    """Normalize text for digest: trim, collapse whitespace, lowercase, cap length."""
-    if not text:
-        return ""
-    # Trim and collapse whitespace
-    normalized = " ".join(text.split())
-    # Lowercase
-    normalized = normalized.lower()
-    # Cap length
-    if len(normalized) > max_len:
-        normalized = normalized[:max_len]
-    return normalized
-
-
-def _round_bbox(bbox: dict[str, float], precision: int = 2) -> dict[str, int]:
-    """Round bbox coordinates to reduce noise (default: 2px precision)."""
-    return {
-        "x": round(bbox.get("x", 0) / precision) * precision,
-        "y": round(bbox.get("y", 0) / precision) * precision,
-        "width": round(bbox.get("width", 0) / precision) * precision,
-        "height": round(bbox.get("height", 0) / precision) * precision,
-    }
-
-
 def _compute_snapshot_digest(snapshot_data: dict[str, Any]) -> str:
     """
     Compute stable digest of snapshot for diffing.
@@ -55,18 +32,8 @@ def _compute_snapshot_digest(snapshot_data: dict[str, Any]) -> str:
     viewport = snapshot_data.get("viewport", {})
     elements = snapshot_data.get("elements", [])
 
-    # Canonicalize elements
-    canonical_elements = []
-    for elem in elements:
-        canonical_elem = {
-            "id": elem.get("id"),
-            "role": elem.get("role", ""),
-            "text_norm": _normalize_text(elem.get("text")),
-            "bbox": _round_bbox(elem.get("bbox", {"x": 0, "y": 0, "width": 0, "height": 0})),
-            "is_primary": elem.get("is_primary", False),
-            "is_clickable": elem.get("is_clickable", False),
-        }
-        canonical_elements.append(canonical_elem)
+    # Canonicalize elements using shared helper
+    canonical_elements = [canonicalize_element(elem) for elem in elements]
 
     # Sort by element id for determinism
     canonical_elements.sort(key=lambda e: e.get("id", 0))
@@ -149,15 +116,21 @@ def build_trace_index(trace_path: str) -> TraceIndex:
     event_count = 0
     error_count = 0
     final_url = None
+    run_end_status = None  # Track status from run_end event
+    agent_name = None  # Extract from run_start event
+    line_count = 0  # Track total line count
 
     steps_by_id: dict[str, StepIndex] = {}
     step_order: list[str] = []  # Track order of first appearance
 
-    # Stream through file, tracking byte offsets
+    # Stream through file, tracking byte offsets and line numbers
     with open(trace_path, "rb") as f:
         byte_offset = 0
+        line_number = 0  # Track line number for each event
 
         for line_bytes in f:
+            line_number += 1
+            line_count += 1
             line_len = len(line_bytes)
 
             try:
@@ -182,6 +155,10 @@ def build_trace_index(trace_path: str) -> TraceIndex:
             if event_type == "error":
                 error_count += 1
 
+            # Extract agent_name from run_start event
+            if event_type == "run_start":
+                agent_name = data.get("agent")
+
             # Initialize step if first time seeing this step_id
             if step_id not in steps_by_id:
                 step_order.append(step_id)
@@ -189,11 +166,12 @@ def build_trace_index(trace_path: str) -> TraceIndex:
                     step_index=len(step_order),
                     step_id=step_id,
                     goal=None,
-                    status="partial",
+                    status="failure",  # Default to failure (will be updated by step_end event)
                     ts_start=ts,
                     ts_end=ts,
                     offset_start=byte_offset,
                     offset_end=byte_offset + line_len,
+                    line_number=line_number,  # Track line number
                     url_before=None,
                     url_after=None,
                     snapshot_before=SnapshotInfo(),
@@ -207,6 +185,7 @@ def build_trace_index(trace_path: str) -> TraceIndex:
             # Update step metadata
             step.ts_end = ts
             step.offset_end = byte_offset + line_len
+            step.line_number = line_number  # Update line number on each event
             step.counters.events += 1
 
             # Handle specific event types
@@ -214,7 +193,8 @@ def build_trace_index(trace_path: str) -> TraceIndex:
                 step.goal = data.get("goal")
                 step.url_before = data.get("pre_url")
 
-            elif event_type == "snapshot":
+            elif event_type == "snapshot" or event_type == "snapshot_taken":
+                # Handle both "snapshot" (current) and "snapshot_taken" (schema) for backward compatibility
                 snapshot_id = data.get("snapshot_id")
                 url = data.get("url")
                 digest = _compute_snapshot_digest(data)
@@ -231,7 +211,8 @@ def build_trace_index(trace_path: str) -> TraceIndex:
                 step.counters.snapshots += 1
                 final_url = url
 
-            elif event_type == "action":
+            elif event_type == "action" or event_type == "action_executed":
+                # Handle both "action" (current) and "action_executed" (schema) for backward compatibility
                 step.action = ActionInfo(
                     type=data.get("type"),
                     target_element_id=data.get("target_element_id"),
@@ -240,18 +221,83 @@ def build_trace_index(trace_path: str) -> TraceIndex:
                 )
                 step.counters.actions += 1
 
-            elif event_type == "llm_response":
+            elif event_type == "llm_response" or event_type == "llm_called":
+                # Handle both "llm_response" (current) and "llm_called" (schema) for backward compatibility
                 step.counters.llm_calls += 1
 
             elif event_type == "error":
-                step.status = "error"
+                step.status = "failure"
 
             elif event_type == "step_end":
-                if step.status != "error":
-                    step.status = "ok"
+                # Determine status from step_end event data
+                # Frontend expects: success, failure, or partial
+                # Logic: success = exec.success && verify.passed
+                #        partial = exec.success && !verify.passed
+                #        failure = !exec.success
+                exec_data = data.get("exec", {})
+                verify_data = data.get("verify", {})
+
+                exec_success = exec_data.get("success", False)
+                verify_passed = verify_data.get("passed", False)
+
+                if exec_success and verify_passed:
+                    step.status = "success"
+                elif exec_success and not verify_passed:
+                    step.status = "partial"
+                elif not exec_success:
+                    step.status = "failure"
+                else:
+                    # Fallback: if step_end exists but no exec/verify data, default to failure
+                    step.status = "failure"
+
+            elif event_type == "run_end":
+                # Extract status from run_end event
+                run_end_status = data.get("status")
+                # Validate status value
+                if run_end_status not in ["success", "failure", "partial", "unknown"]:
+                    run_end_status = None
 
             byte_offset += line_len
 
+    # Use run_end status if available, otherwise infer from step statuses
+    if run_end_status is None:
+        step_statuses = [step.status for step in steps_by_id.values()]
+        if step_statuses:
+            # Infer overall status from step statuses
+            if all(s == "success" for s in step_statuses):
+                run_end_status = "success"
+            elif any(s == "failure" for s in step_statuses):
+                # If any failure and no successes, it's failure; otherwise partial
+                if any(s == "success" for s in step_statuses):
+                    run_end_status = "partial"
+                else:
+                    run_end_status = "failure"
+            elif any(s == "partial" for s in step_statuses):
+                run_end_status = "partial"
+            else:
+                run_end_status = "failure"  # Default to failure instead of unknown
+        else:
+            run_end_status = "failure"  # Default to failure instead of unknown
+
+    # Calculate duration
+    duration_ms = None
+    if first_ts and last_ts:
+        try:
+            start = datetime.fromisoformat(first_ts.replace("Z", "+00:00"))
+            end = datetime.fromisoformat(last_ts.replace("Z", "+00:00"))
+            duration_ms = int((end - start).total_seconds() * 1000)
+        except (ValueError, AttributeError):
+            duration_ms = None
+
+    # Aggregate counters
+    snapshot_count = sum(step.counters.snapshots for step in steps_by_id.values())
+    action_count = sum(step.counters.actions for step in steps_by_id.values())
+    counters = {
+        "snapshot_count": snapshot_count,
+        "action_count": action_count,
+        "error_count": error_count,
+    }
+
     # Build summary
     summary = TraceSummary(
         first_ts=first_ts,
@@ -260,6 +306,10 @@ def build_trace_index(trace_path: str) -> TraceIndex:
         step_count=len(steps_by_id),
         error_count=error_count,
         final_url=final_url,
+        status=run_end_status,
+        agent_name=agent_name,
+        duration_ms=duration_ms,
+        counters=counters,
     )
 
     # Build steps list in order
@@ -270,6 +320,7 @@ def build_trace_index(trace_path: str) -> TraceIndex:
         path=str(trace_path),
         size_bytes=os.path.getsize(trace_path),
         sha256=_compute_file_sha256(str(trace_path)),
+        line_count=line_count,
     )
 
     # Build final index
@@ -285,13 +336,16 @@ def build_trace_index(trace_path: str) -> TraceIndex:
     return index
 
 
-def write_trace_index(trace_path: str, index_path: str | None = None) -> str:
+def write_trace_index(
+    trace_path: str, index_path: str | None = None, frontend_format: bool = False
+) -> str:
     """
     Build index and write to file.
 
     Args:
         trace_path: Path to trace JSONL file
         index_path: Optional custom path for index file (default: trace_path with .index.json)
+        frontend_format: If True, write in frontend-compatible format (default: False)
 
     Returns:
         Path to written index file
@@ -301,8 +355,11 @@ def write_trace_index(trace_path: str, index_path: str | None = None) -> str:
 
     index = build_trace_index(trace_path)
 
-    with open(index_path, "w") as f:
-        json.dump(index.to_dict(), f, indent=2)
+    with open(index_path, "w", encoding="utf-8") as f:
+        if frontend_format:
+            json.dump(index.to_sentience_studio_dict(), f, indent=2)
+        else:
+            json.dump(index.to_dict(), f, indent=2)
 
     return index_path
 

sentience/tracer_factory.py

@@ -7,16 +7,16 @@ Provides convenient factory function for creating tracers with cloud upload supp
 import gzip
 import os
 import uuid
+from collections.abc import Callable
 from pathlib import Path
+from typing import Any, Optional
 
 import requests
 
 from sentience.cloud_tracing import CloudTraceSink, SentienceLogger
+from sentience.constants import SENTIENCE_API_URL
 from sentience.tracing import JsonlTraceSink, Tracer
 
-# Sentience API base URL (constant)
-SENTIENCE_API_URL = "https://api.sentienceapi.com"
-
 
 def create_tracer(
     api_key: str | None = None,
@@ -24,6 +24,11 @@ def create_tracer(
     api_url: str | None = None,
     logger: SentienceLogger | None = None,
     upload_trace: bool = False,
+    goal: str | None = None,
+    agent_type: str | None = None,
+    llm_model: str | None = None,
+    start_url: str | None = None,
+    screenshot_processor: Callable[[str], str] | None = None,
 ) -> Tracer:
     """
     Create tracer with automatic tier detection.
@@ -42,15 +47,42 @@ def create_tracer(
         upload_trace: Enable cloud trace upload (default: False). When True and api_key
                       is provided, traces will be uploaded to cloud. When False, traces
                       are saved locally only.
+        goal: User's goal/objective for this trace run. This will be displayed as the
+              trace name in the frontend. Should be descriptive and action-oriented.
+              Example: "Add wireless headphones to cart on Amazon"
+        agent_type: Type of agent running (e.g., "SentienceAgent", "CustomAgent")
+        llm_model: LLM model used (e.g., "gpt-4-turbo", "claude-3-5-sonnet")
+        start_url: Starting URL of the agent run (e.g., "https://amazon.com")
+        screenshot_processor: Optional function to process screenshots before upload.
+                            Takes base64 string, returns processed base64 string.
+                            Useful for PII redaction or custom image processing.
 
     Returns:
         Tracer configured with appropriate sink
 
     Example:
-        >>> # Pro tier user
-        >>> tracer = create_tracer(api_key="sk_pro_xyz", run_id="demo")
+        >>> # Pro tier user with goal
+        >>> tracer = create_tracer(
+        ...     api_key="sk_pro_xyz",
+        ...     run_id="demo",
+        ...     goal="Add headphones to cart",
+        ...     agent_type="SentienceAgent",
+        ...     llm_model="gpt-4-turbo",
+        ...     start_url="https://amazon.com"
+        ... )
         >>> # Returns: Tracer with CloudTraceSink
         >>>
+        >>> # With screenshot processor for PII redaction
+        >>> def redact_pii(screenshot_base64: str) -> str:
+        ...     # Your custom redaction logic
+        ...     return redacted_screenshot
+        >>>
+        >>> tracer = create_tracer(
+        ...     api_key="sk_pro_xyz",
+        ...     screenshot_processor=redact_pii
+        ... )
+        >>> # Screenshots will be processed before upload
+        >>>
         >>> # Free tier user
         >>> tracer = create_tracer(run_id="demo")
         >>> # Returns: Tracer with JsonlTraceSink (local-only)
@@ -73,11 +105,28 @@ def create_tracer(
     # 1. Try to initialize Cloud Sink (Pro/Enterprise tier) if upload enabled
     if api_key and upload_trace:
         try:
+            # Build metadata object for trace initialization
+            # Only include non-empty fields to avoid sending empty strings
+            metadata: dict[str, str] = {}
+            if goal and goal.strip():
+                metadata["goal"] = goal.strip()
+            if agent_type and agent_type.strip():
+                metadata["agent_type"] = agent_type.strip()
+            if llm_model and llm_model.strip():
+                metadata["llm_model"] = llm_model.strip()
+            if start_url and start_url.strip():
+                metadata["start_url"] = start_url.strip()
+
+            # Build request payload
+            payload: dict[str, Any] = {"run_id": run_id}
+            if metadata:
+                payload["metadata"] = metadata
+
             # Request pre-signed upload URL from backend
             response = requests.post(
                 f"{api_url}/v1/traces/init",
                 headers={"Authorization": f"Bearer {api_key}"},
-                json={"run_id": run_id},
+                json=payload,
                 timeout=10,
             )
 
@@ -96,16 +145,46 @@ def create_tracer(
                             api_url=api_url,
                             logger=logger,
                         ),
+                        screenshot_processor=screenshot_processor,
                     )
                 else:
                     print("⚠️  [Sentience] Cloud init response missing upload_url")
+                    print(f"   Response data: {data}")
                     print("   Falling back to local-only tracing")
 
             elif response.status_code == 403:
                 print("⚠️  [Sentience] Cloud tracing requires Pro tier")
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error") or error_data.get("message", "")
+                    if error_msg:
+                        print(f"   API Error: {error_msg}")
+                except Exception:
+                    pass
+                print("   Falling back to local-only tracing")
+            elif response.status_code == 401:
+                print("⚠️  [Sentience] Cloud init failed: HTTP 401 Unauthorized")
+                print("   API key is invalid or expired")
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error") or error_data.get("message", "")
+                    if error_msg:
+                        print(f"   API Error: {error_msg}")
+                except Exception:
+                    pass
                 print("   Falling back to local-only tracing")
             else:
                 print(f"⚠️  [Sentience] Cloud init failed: HTTP {response.status_code}")
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error") or error_data.get(
+                        "message", "Unknown error"
+                    )
+                    print(f"   Error: {error_msg}")
+                    if "tier" in error_msg.lower() or "subscription" in error_msg.lower():
+                        print(f"   💡 This may be a tier/subscription issue")
+                except Exception:
+                    print(f"   Response: {response.text[:200]}")
                 print("   Falling back to local-only tracing")
 
         except requests.exceptions.Timeout:
@@ -125,7 +204,11 @@ def create_tracer(
     local_path = traces_dir / f"{run_id}.jsonl"
     print(f"💾 [Sentience] Local tracing: {local_path}")
 
-    return Tracer(run_id=run_id, sink=JsonlTraceSink(str(local_path)))
+    return Tracer(
+        run_id=run_id,
+        sink=JsonlTraceSink(str(local_path)),
+        screenshot_processor=screenshot_processor,
+    )
 
 
 def _recover_orphaned_traces(api_key: str, api_url: str = SENTIENCE_API_URL) -> None:
@@ -149,10 +232,23 @@ def _recover_orphaned_traces(api_key: str, api_url: str = SENTIENCE_API_URL) ->
     if not orphaned:
         return
 
-    print(f"⚠️  [Sentience] Found {len(orphaned)} un-uploaded trace(s) from previous runs")
+    # Filter out test files (run_ids that start with "test-" or are clearly test data)
+    # These are likely from local testing and shouldn't be uploaded
+    test_patterns = ["test-", "test_", "test."]
+    valid_orphaned = [
+        f
+        for f in orphaned
+        if not any(f.stem.startswith(pattern) for pattern in test_patterns)
+        and not f.stem.startswith("test")
+    ]
+
+    if not valid_orphaned:
+        return
+
+    print(f"⚠️  [Sentience] Found {len(valid_orphaned)} un-uploaded trace(s) from previous runs")
     print("   Attempting to upload now...")
 
-    for trace_file in orphaned:
+    for trace_file in valid_orphaned:
         try:
             # Extract run_id from filename (format: {run_id}.jsonl)
             run_id = trace_file.stem
@@ -166,6 +262,21 @@ def _recover_orphaned_traces(api_key: str, api_url: str = SENTIENCE_API_URL) ->
             )
 
             if response.status_code != 200:
+                # HTTP 409 means trace already exists (already uploaded)
+                # Treat as success and delete local file
+                if response.status_code == 409:
+                    print(f"✅ Trace {run_id} already exists in cloud (skipping re-upload)")
+                    # Delete local file since it's already in cloud
+                    try:
+                        os.remove(trace_file)
+                    except Exception:
+                        pass  # Ignore cleanup errors
+                    continue
+                # HTTP 422 typically means invalid run_id (e.g., test files)
+                # Skip silently for 422, but log other errors
+                if response.status_code == 422:
+                    # Likely a test file or invalid run_id, skip silently
+                    continue
                 print(f"❌ Failed to get upload URL for {run_id}: HTTP {response.status_code}")
                 continue