Langfuse

The Langfuse connector pulls observations from Langfuse Cloud (EU or US) or a self-hosted instance through the Observations API v2, on a schedule, and turns each trace into one decision record at assurance level observed.

Set-up

1. In Langfuse, create an API key pair. Put the secret key where the Stratl API can read it, for example an environment variable LANGFUSE_SECRET_KEY.
2. In the portal, Sources → Add connector → Langfuse. Base URL (https://cloud.langfuse.com, https://us.cloud.langfuse.com or your own), the public key, the secret reference env:LANGFUSE_SECRET_KEY, and optionally an environment filter.
3. Test, then Save. The first run looks back seven days; afterwards it polls with a ten-minute overlap. Replays are harmless because ingest is idempotent on the decision id, which is derived from the trace id.

The metadata contract

Business facts come from metadata on any observation in the trace, usually the root:

langfuse.trace(name="credit-underwriter", metadata={
  "stratl.subject.type": "applicant", "stratl.subject.id": "72819",
  "stratl.policy.id": "declines_require_second_review", "stratl.policy.version": "5",
  "stratl.policy.result": "human_required",
  "stratl.approval.approver": "r.okafor@lender.ng", "stratl.approval.authority": "credit_officer",
  "stratl.approval.decision": "approved",
  "stratl.action.name": "loan.decline", "stratl.action.target": "applicant/72819",
  "stratl.action.result": "executed",
  "stratl.outcome.adverse": True, "stratl.outcome.category": "credit_decline",
})

stratl.agent overrides the agent id (otherwise the root observation’s name is used). Without stratl.subject.*, records are keyed by trace id and flagged by the packs.

How observations map

Observation type	Event
GENERATION	model_call: provider inferred from the model name or metadata.provider, fingerprints of input, output and model parameters, token usage; content: not_captured when the input is absent; an ERROR level becomes status: error
TOOL	tool_call with fingerprints of input and output
RETRIEVER	retrieval with one fingerprint per output document
Any, with stratl.* metadata	policy_eval, approval, action, outcome events

Content is fingerprinted, never stored. The trace id and the Langfuse environment go into provenance.

Prove it against your account

One command pulls from your project, pulls again from the persisted cursor, and checks every record it produced: valid format, stable hash, fingerprints only, honest provenance. It writes nothing to Stratl and prints no content.

LANGFUSE_PUBLIC_KEY=pk-lf-… LANGFUSE_SECRET_KEY=sk-lf-… make prove-langfuse

Exit status zero is the proof; keep the output with its date. --days 30 widens the window; --out ./records keeps the records as JSON. The connector is replay-tested against recorded responses matching the current API reference; it has not yet been run against a production account by us, which the early-access page says.