Prefer Langfuse public API trace exports

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

Author: yanpgwang

CLAUDE.md

@@ -51,7 +51,7 @@ PYTHONPATH=src uv run context-profiler analyze tests/fixtures/cursor_transcript.
 
 ## Product Boundaries
 
-Do not add provider-specific fetch clients to core. Agents can use Langfuse CLI, SDKs, Hugging Face tooling, or local transcript discovery to obtain data, then pass files or stdin to `context-profiler`.
+Do not add provider-specific fetch clients to core. Agents can use Langfuse public API exports via `curl`, SDKs, Hugging Face tooling, or local transcript discovery to obtain data, then pass files or stdin to `context-profiler`. Prefer direct Langfuse public API exports over `langfuse-cli` for trace analysis because the CLI can omit fields needed for nested observations and generations.
 
 Do not make Toolathlon a first-class multi-turn demo. Prefer genuinely multi-turn datasets such as `pagarsky/agent-trace`, `cx-cmu/agent_trajectories`, and SWE-agent trajectories for future research examples.
 

README.md

@@ -90,11 +90,25 @@ 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:
+Fetch a Langfuse trace through the public API, then analyze it:
 
 ```bash
-npx langfuse-cli api traces get <trace-id> --fields core,io,observations --json \
-  | context-profiler diagnose - --format langfuse --json
+TRACE_ID="<trace-id>"
+HOST="${LANGFUSE_HOST%/}"
+OUT="/tmp/langfuse-trace-${TRACE_ID}"
+mkdir -p "$OUT"
+
+curl -fsS \
+  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
+  "$HOST/api/public/traces/$TRACE_ID" \
+  -o "$OUT/trace.json"
+
+curl -fsS \
+  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
+  "$HOST/api/public/observations?traceId=$TRACE_ID&limit=100&page=1" \
+  -o "$OUT/observations-page-1.json"
+
+context-profiler diagnose "$OUT/trace.json" --format langfuse --json
 ```
 
 Analyze a public academic agent trajectory:
@@ -129,8 +143,6 @@ context-profiler normalize trace.json --from auto --json
 
 # 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`.
@@ -139,7 +151,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 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.
+The skill does not make `context-profiler` fetch traces itself. It teaches agents to fetch Langfuse trace ids with the Langfuse public API via `curl`, 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. It intentionally avoids `langfuse-cli` for trace fetching because the CLI may omit fields needed for complete analysis.
 
 Canonical skill:
 

docs/design/cli-harness.md

@@ -13,7 +13,7 @@ The CLI is designed for two users at once:
 
 Good upstream sources include:
 
-- Langfuse CLI or API exports
+- Langfuse public API exports
 - OpenTelemetry / OpenInference span exports
 - raw OpenAI or Anthropic request logs
 - Cursor or Claude Code local transcripts
@@ -41,7 +41,7 @@ context-profiler analyze <file|-> --format auto --html report.html
 
 The style is inspired by mature agent-friendly CLIs:
 
-- Langfuse CLI: schema-driven API access
+- Langfuse API: observability trace access
 - kubectl: resource discovery and explainability
 - Terraform: validate/plan-style machine output
 - GitHub CLI: human commands plus machine-readable JSON

examples/README.md

@@ -73,7 +73,7 @@ context-profiler diagnose trace.json --format langfuse --json
 context-profiler analyze trace.json --format langfuse --html /tmp/context-profiler-langfuse.html
 ```
 
-`context-profiler` does not fetch Langfuse data. Use Langfuse's own CLI/API or any other tool to obtain the trace first.
+`context-profiler` does not fetch Langfuse data. Use the Langfuse public API via `curl` or another external tool to obtain the trace first. Prefer the public API for complete trace analysis because CLI output can omit fields needed to inspect nested observations and generations.
 
 ## Academic AgentTrace
 

skills/analyze-agent-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze-agent-context
-description: Analyze LLM agent traces, loops, transcripts, Langfuse exports, OpenTelemetry spans, or raw provider requests with context-profiler. Use when the user asks to analyze/debug/explain a trace, agent run, context growth, stale context, tool bloat, or a recently fetched trace from another CLI.
+description: Analyze LLM agent traces, loops, transcripts, Langfuse exports, OpenTelemetry spans, or raw provider requests with context-profiler. Use when the user asks to analyze/debug/explain a trace, agent run, context growth, stale context, tool bloat, or recently fetched trace JSON.
 ---
 
 # Analyze Agent Context

src/context_profiler/formats.py

@@ -69,14 +69,14 @@ def to_dict(self) -> dict[str, Any]:
             "observations[]",
             "GENERATION observations with input.messages, input {role, content}, or string input",
         ],
-        common_sources=["Langfuse UI export", "Langfuse API", "langfuse-cli"],
+        common_sources=["Langfuse UI export", "Langfuse public API"],
         analysis_scope=[
             "Per-generation context growth",
             "Visible generation input messages",
             "Tool input/output if captured in generation inputs",
         ],
         limitations=["Only GENERATION observations with analyzable input content are profiled in the current adapter."],
-        agent_conversion_guidance="Use langfuse-cli or API to fetch traces/observations, then pass the exported trace JSON directly.",
+        agent_conversion_guidance="Use the Langfuse public API via curl to fetch traces/observations, then pass the exported trace JSON directly. Avoid langfuse-cli for trace analysis because it may omit nested observation or generation fields.",
         notes=["Current adapter extracts generation inputs and delegates to OpenAI parsing."],
     ),
     "cursor-jsonl": FormatSpec(