# Langfuse agent and tool tracing fixture

This artifact reproduces the trace-shape checks behind FutureCraft's article on
multi-step agent tracing. It contains a deterministic Python workflow, a Langfuse v4
adapter, tests, one minimized integration export, and a diagram generated from that
export.

No live model, customer data, prompt, raw trace response, or credential is included.

## Verified environment

The remote evidence run completed on 26 August 2026 with:

| Component | Version |
| --- | --- |
| Langfuse Python SDK | `4.14.5` |
| Self-hosted Langfuse server | `3.205.0` |
| Python | `3.13.9` |
| Fixture release | `6401879` |

The result covers this version pair and one deterministic workflow. It is not a
Langfuse performance benchmark or a claim about every SDK release.

## Files

- `workflow.py` — deterministic support workflow and exporter isolation;
- `langfuse_adapter.py` — explicit Langfuse v4 parentage and level mapping;
- `test_workflow.py` — workflow, retry, redaction, and failure-isolation tests;
- `test_langfuse_adapter.py` — adapter contract tests;
- `run_integration.py` — real-server runner that retains no raw trace file;
- `test_sanitized_evidence.py` — checks for trace shape and unsafe values;
- `sanitized-trace-shapes-2026-08-26.json` — minimized evidence from three scenarios;
- `render_trace_diagram.py` — deterministic SVG renderer;
- `sanitized-trace-shape-2026-08-26.svg` — reviewed diagram;
- `evidence-run-2026-08-26.md` — assertions, defects found, commands, and limits.

## Run without Langfuse

Download the files into one directory, change into it, then run:

```bash
python3 -m unittest discover -s . -p 'test_*.py' -v
```

The suite uses only the Python standard library. It verifies one root, explicit child
parentage, separate retry attempts, terminal child errors, source-side redaction,
exporter isolation, and the stored sanitized evidence.

Rebuild the diagram from the reviewed JSON:

```bash
python3 render_trace_diagram.py
```

## Run against a Langfuse project

Use a dedicated project credential and keep it in environment variables. Never paste a
real secret into this directory or a command argument.

```bash
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://your-langfuse.example"

uv run --isolated --with langfuse==4.14.5 python \
  run_integration.py \
  --output /tmp/futurecraft-langfuse-evidence.json
```

The runner keeps the authenticated response in memory, builds a new object from an
allowlist, rejects synthetic identifiers and credentials, and writes only the minimized
trace shape. Review the output before publishing it. Do not assume the two fixture
regexes cover the data formats in your application.

## Expected assertions

- each scenario has exactly one root observation;
- every child points to that root;
- a timeout and its successful retry are separate `TOOL` observations;
- the terminal tool failure is `ERROR`, the root is `WARNING`, and successful siblings
  remain non-error;
- input and output payloads are absent;
- synthetic email and account values are redacted before export;
- an unreachable exporter does not change the fixture result.

## Licenses

Python code and tests are licensed under MIT. The evidence report, sanitized JSON, and
SVG diagram are licensed under CC BY 4.0. See `LICENSE-MIT.txt` and
`LICENSE-CC-BY-4.0.md`.