Improve Langfuse trace handoff

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: yanpgwang

README.md

@@ -46,16 +46,24 @@ Related work:
 
 ## Install
 
+For agent/CLI use, prefer an isolated executable install:
+
 ```bash
-pip install context-profiler
+pipx install context-profiler
+# or
+uv tool install context-profiler
+context-profiler --version
+which -a context-profiler  # ensure a stale executable is not shadowing pipx/uv
 ```
 
 Or install from source:
 
 ```bash
 git clone https://github.com/Turdot/context-profiler.git
 cd context-profiler
-pip install -e .
+uv tool install -e .
+# for local development in this repo:
+PYTHONPATH=src uv run context-profiler --version
 ```
 
 ## Quick Start
@@ -82,6 +90,14 @@ context-profiler diagnose trace.json --format langfuse --json
 context-profiler analyze trace.json --format langfuse --html report.html
 ```
 
+Analyze a Langfuse trace fetched by Langfuse CLI:
+
+```bash
+npx langfuse-cli api traces get <trace-id> --fields core,io,observations --json \
+  | context-profiler diagnose - --format langfuse --json
+```
+
+
 Generate an interactive report:
 
 ```bash
@@ -105,8 +121,10 @@ context-profiler schema diagnosis --json
 context-profiler validate trace.json --format auto --json
 context-profiler normalize trace.json --from auto --json
 
-# Diagnose for agent consumption
+# Diagnose for agent consumption; '-' reads JSON/JSONL from stdin
 context-profiler diagnose trace.json --format auto --json
+npx langfuse-cli api traces get <trace-id> --fields core,io,observations --json \
+  | context-profiler diagnose - --format langfuse --json
 ```
 
 If validation fails, the JSON response includes `errors[].agent_action` and `next_steps` so the agent can convert the trace into `ContextTrace`.
@@ -115,7 +133,7 @@ If validation fails, the JSON response includes `errors[].agent_action` and `nex
 
 This repository ships an `analyze-agent-context` skill for Cursor, Claude Code, and other Agent Skills / Open Plugins compatible tools.
 
-The skill does not fetch traces. It teaches agents to use `context-profiler` whenever the user asks to analyze a trace, loop, transcript, agent run, context growth, stale context, or tool bloat.
+The skill does not make `context-profiler` fetch traces itself. It teaches agents to use Langfuse tooling to fetch Langfuse trace ids, then route the fetched JSON into `context-profiler` for diagnosis whenever the user asks to analyze a trace, loop, transcript, agent run, context growth, stale context, or tool bloat.
 
 Canonical skill:
 
@@ -181,6 +199,7 @@ The HTML report is self-contained and keeps the existing profiler style:
 }
 ```
 
+
 ## Examples
 
 See [`examples/README.md`](examples/README.md) for runnable fixtures and conversion patterns.

skills/analyze-agent-context/SKILL.md

@@ -9,13 +9,29 @@ Use `context-profiler` as the trace-source agnostic context analysis harness.
 
 ## Core Rule
 
-Do not fetch traces unless the user asks you to. If another tool already fetched trace data, use that local file or recent JSON output. The source can be Langfuse CLI, Claude Code, Cursor, OpenTelemetry, raw OpenAI/Anthropic requests, or an academic trajectory dataset.
+Do not fetch traces unless the user asks you to. If the user provides a Langfuse trace id and asks to inspect, debug, or analyze it, use the Langfuse skill/CLI to fetch that trace, then hand the fetched JSON to `context-profiler`. Do not manually summarize the raw trace before running `context-profiler`.
+
+If another tool already fetched trace data, use that local file or recent JSON output. The source can be Langfuse CLI, Claude Code, Cursor, OpenTelemetry, raw OpenAI/Anthropic requests, or an academic trajectory dataset.
+
+Before analysis, verify the CLI is callable:
+
+```bash
+context-profiler --version
+```
+
+If the command is missing or its entry point is broken, ask the user to install it with `pipx install context-profiler` or `uv tool install context-profiler`.
+If `which -a context-profiler` shows a stale broken executable before the `pipx`/`uv tool` executable, use the working executable path or fix `PATH` before continuing.
 
 ## Workflow
 
 1. Identify the available trace or loop data:
    - File path supplied by user.
    - Recent JSON output from another CLI, such as `langfuse-cli`.
+   - Langfuse trace id supplied by user. Fetch it with Langfuse tooling first:
+     ```bash
+     npx langfuse-cli api traces get <trace-id> --fields core,io,observations --json \
+       | context-profiler diagnose - --format langfuse --json
+     ```
    - Current Cursor transcript under `~/.cursor/projects/**/agent-transcripts/**/*.jsonl`.
    - Current Claude Code transcript under `~/.claude/projects/**/*.jsonl`.
 

src/context_profiler/adapters/langfuse_adapter.py

@@ -1,10 +1,7 @@
 """Adapter for Langfuse trace export format.
 
-Parses a Langfuse trace JSON (exported from UI or API) and extracts all
+Parses a Langfuse trace JSON (exported from UI or API) and extracts analyzable
 GENERATION observations as a Session of APIRequests.
-
-Each GENERATION observation contains an 'input' dict with {tools, messages}
-in OpenAI format, which we delegate to the OpenAI adapter for parsing.
 """
 
 from __future__ import annotations
@@ -29,39 +26,91 @@ def is_langfuse_trace(data: dict[str, Any]) -> bool:
     )
 
 
+def _json_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _normalize_generation_input(inp: Any) -> dict[str, Any] | None:
+    """Convert common Langfuse generation input shapes to OpenAI messages."""
+    if isinstance(inp, dict):
+        messages = inp.get("messages")
+        if isinstance(messages, list) and messages:
+            return dict(inp)
+
+        role = inp.get("role")
+        content = inp.get("content")
+        if isinstance(role, str) and role and content is not None:
+            normalized = {
+                "messages": [
+                    {
+                        "role": role,
+                        "content": _json_text(content),
+                    }
+                ]
+            }
+            if isinstance(inp.get("tools"), list):
+                normalized["tools"] = inp["tools"]
+            if isinstance(inp.get("model"), str):
+                normalized["model"] = inp["model"]
+            return normalized
+
+    if isinstance(inp, str) and inp:
+        return {"messages": [{"role": "user", "content": inp}]}
+
+    return None
+
+
 def parse_langfuse_trace(data: dict[str, Any]) -> Session:
     """Extract all GENERATION observations and build a Session.
 
     Returns a Session with one APIRequest per GENERATION, sorted by startTime.
     """
     observations = data.get("observations", [])
 
-    generations = [
+    generation_observations = [
         obs for obs in observations
         if obs.get("type") == "GENERATION"
-        and isinstance(obs.get("input"), dict)
-        and "messages" in obs["input"]
     ]
-
-    generations.sort(key=lambda x: x.get("startTime", ""))
+    generation_observations.sort(key=lambda x: x.get("startTime", ""))
 
     requests: list[APIRequest] = []
-    for idx, gen in enumerate(generations):
-        inp = gen["input"]
-        req = _openai.parse(inp)
-        req.request_index = idx
-        req.model = gen.get("model", req.model)
+    unsupported_generation_count = 0
+    for gen in generation_observations:
+        normalized_input = _normalize_generation_input(gen.get("input"))
+        if normalized_input is None:
+            unsupported_generation_count += 1
+            continue
+
+        req = _openai.parse(normalized_input)
+        req.request_index = len(requests)
+        req.source_format = "langfuse"
+        req.model = gen.get("model") or req.model
         requests.append(req)
 
+    warnings: list[str] = []
+    if unsupported_generation_count:
+        warnings.append(
+            f"Skipped {unsupported_generation_count} Langfuse GENERATION observations without analyzable input messages."
+        )
+    if generation_observations and not requests:
+        warnings.append("Langfuse trace contains GENERATION observations, but none include analyzable input messages.")
+    if not generation_observations:
+        warnings.append("Langfuse trace contains no GENERATION observations.")
+
     metadata = {
         "trace_id": data.get("id"),
         "trace_name": data.get("name"),
         "project_id": data.get("projectId"),
         "session_id": data.get("sessionId"),
         "timestamp": data.get("timestamp"),
-        "total_generations": len(generations),
+        "total_generations": len(requests),
+        "total_generation_observations": len(generation_observations),
+        "unsupported_generation_observations": unsupported_generation_count,
         "total_observations": len(observations),
         "source_format": "langfuse",
+        "warnings": warnings,
     }
 
     return Session(requests=requests, metadata=metadata)