Improve PostHog tracking coverage and reliability

- Track validation errors (empty key, no file, bad schema) as
"validation_error" events
- Add duration_s to agent_map_completed and agent_map_failed events
- Enrich agent_map_started with field type breakdown (field_types,
has_category)
- Register atexit handler to flush remaining PostHog events on shutdown
- Move css/head params from gr.Blocks() to demo.launch() for Gradio 6
compatibility
- Note frontend/backend identity mismatch as a known limitation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app.py

@@ -1,8 +1,10 @@
 import ast
+import atexit
 import hashlib
 import json
 import os
 import tempfile
+import time
 import uuid
 from typing import Literal
 
@@ -18,7 +20,12 @@ _POSTHOG_ENABLED = bool(_POSTHOG_KEY and _POSTHOG_HOST)
 posthog.api_key = _POSTHOG_KEY
 posthog.project_api_key = _POSTHOG_KEY
 posthog.host = _POSTHOG_HOST
+if _POSTHOG_ENABLED:
+    atexit.register(posthog.shutdown)
 
+# NOTE: Frontend JS uses an anonymous distinct_id while server-side uses a hashed
+# API key. PostHog won't auto-link these identities. To link them, the frontend
+# would need to call posthog.identify() with the hashed key after the user submits.
 POSTHOG_HEAD = f"""
 <script>
   !function(t,e){{var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){{function g(t,e){{var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){{t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){{var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}},u.people.toString=function(){{return u.toString(1)+".people (stub)"}},o="init capture register register_once unregister opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing identify alias people.set people.set_once set_config reset opt_in_capturing".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])}},e.__SV=1)}}(document,window.posthog||[]);
@@ -130,18 +137,50 @@ def _posthog_distinct_id(api_key: str) -> str:
     return hashlib.sha256(api_key.encode()).hexdigest()[:16]
 
 
+def _track_validation_error(api_key, session_id, error_msg):
+    """Track validation errors in PostHog when we have an API key."""
+    if _POSTHOG_ENABLED and api_key:
+        posthog.capture(
+            distinct_id=_posthog_distinct_id(api_key),
+            event="validation_error",
+            properties={
+                "$session_id": session_id,
+                "error": error_msg,
+                "app": "everyrow-research-space",
+            },
+        )
+
+
+def _schema_properties(fields_list):
+    """Summarize the output schema for PostHog events."""
+    if not fields_list:
+        return {"field_count": 0}
+    type_counts = {}
+    for f in fields_list:
+        t = f.get("type", "str")
+        type_counts[t] = type_counts.get(t, 0) + 1
+    return {
+        "field_count": len(fields_list),
+        "field_types": type_counts,
+        "has_category": "category" in type_counts,
+    }
+
+
 async def run_agent_map(api_key, file, query, effort_label, fields_list, session_id):
     if not api_key:
         raise gr.Error("Please enter your everyrow API key.")
     if file is None:
+        _track_validation_error(api_key, session_id, "No file uploaded")
         raise gr.Error("Please upload a CSV file.")
     if not query.strip():
+        _track_validation_error(api_key, session_id, "Empty query")
         raise gr.Error("Please enter a research query.")
 
     os.environ["EVERYROW_API_KEY"] = api_key
 
     df = pd.read_csv(file)
     if df.empty:
+        _track_validation_error(api_key, session_id, "Empty CSV")
         raise gr.Error("The uploaded CSV is empty.")
 
     effort_level = EFFORT_LEVELS[effort_label]
@@ -150,6 +189,7 @@ async def run_agent_map(api_key, file, query, effort_label, fields_list, session
     try:
         response_model = build_response_model(fields_list)
     except ValueError as e:
+        _track_validation_error(api_key, session_id, str(e))
         raise gr.Error(str(e))
 
     kwargs = dict(task=query, input=df, effort_level=effort_level)
@@ -165,19 +205,26 @@ async def run_agent_map(api_key, file, query, effort_label, fields_list, session
                 "effort_level": effort_label,
                 "row_count": len(df),
                 "column_count": len(df.columns),
-                "field_count": len(fields_list) if fields_list else 0,
+                **_schema_properties(fields_list),
                 "app": "everyrow-research-space",
             },
         )
 
+    t0 = time.time()
     result = await agent_map(**kwargs)
+    duration_s = round(time.time() - t0, 2)
 
     if result.error:
         if _POSTHOG_ENABLED:
             posthog.capture(
                 distinct_id=distinct_id,
                 event="agent_map_failed",
-                properties={"$session_id": session_id, "error": str(result.error), "app": "everyrow-research-space"},
+                properties={
+                    "$session_id": session_id,
+                    "error": str(result.error),
+                    "duration_s": duration_s,
+                    "app": "everyrow-research-space",
+                },
             )
         raise gr.Error(f"agent_map failed: {result.error}")
 
@@ -189,6 +236,7 @@ async def run_agent_map(api_key, file, query, effort_label, fields_list, session
                 "$session_id": session_id,
                 "output_rows": len(result.data),
                 "output_columns": len(result.data.columns),
+                "duration_s": duration_s,
                 "app": "everyrow-research-space",
             },
         )
@@ -246,10 +294,10 @@ def expand_research(df: pd.DataFrame) -> pd.DataFrame:
     return result
 
 
+_CSS = ".error-box { background: #fee; border: 1px solid #c00; border-radius: 8px; padding: 12px; color: #900; }"
+
 with gr.Blocks(
     title="everyrow annotate – AI Data Annotation & Web Research",
-    head=POSTHOG_HEAD,
-    css=".error-box { background: #fee; border: 1px solid #c00; border-radius: 8px; padding: 12px; color: #900; }",
 ) as demo:
     gr.Markdown(
         """
@@ -530,4 +578,4 @@ with gr.Blocks(
     )
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch(css=_CSS, head=POSTHOG_HEAD)