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

sentience/trace_indexing/indexer.py

@@ -7,7 +7,7 @@ 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 .index_schema import (
     ActionInfo,
@@ -58,13 +58,26 @@ def _compute_snapshot_digest(snapshot_data: dict[str, Any]) -> str:
     # Canonicalize elements
     canonical_elements = []
     for elem in elements:
+        # Extract is_primary and is_clickable from visual_cues if present
+        visual_cues = elem.get("visual_cues", {})
+        is_primary = (
+            visual_cues.get("is_primary", False)
+            if isinstance(visual_cues, dict)
+            else elem.get("is_primary", False)
+        )
+        is_clickable = (
+            visual_cues.get("is_clickable", False)
+            if isinstance(visual_cues, dict)
+            else elem.get("is_clickable", False)
+        )
+
         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),
+            "is_primary": is_primary,
+            "is_clickable": is_clickable,
         }
         canonical_elements.append(canonical_elem)
 
@@ -149,15 +162,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 +201,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 +212,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 +231,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 +239,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 +257,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 +267,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 +352,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 +366,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 +382,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 +401,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,7 +7,9 @@ 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
 
@@ -24,6 +26,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 +49,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 +107,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 +147,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 +206,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 +234,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 +264,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