Openwright Langfuse Digest

Langfuse telemetry integration for OpenWright. Co-ingests traces, backlinks verdicts, and pulls evals-as-evidence.

🚀 Quick Start

• Install: Available via PyPI for Python >=3.10, <3.15.
• Init Forwarder: Use the dynamic loader to mount the connector.
• Backlink Verdicts: Push openwright:<control> scores onto Langfuse traces.

from openwright.connectors import load
 
# 1. Mount the Langfuse forwarder
fwd = load("openwright.forwarders", "langfuse")
 
# 2. Define API configuration
cfg = {
    "host": "https://cloud.langfuse.com",
    "public_key": "pk-...",
    "secret_key": "sk-...",
    "trace_id": trace_id # Contextual trace reference
}
 
# 3. Push OpenWright verdicts back to Langfuse trace
deep_link = fwd.backlink(report, config=cfg)

🔧 Configuration & Core Actions

• forward: Co-ingests a telemetry batch to Langfuse completely unchanged. Enforces Basic auth + x-langfuse-ingestion-version: 4.
• backlink: Pushes verdicts to the Langfuse trace. Automatically attaches the reason as a trace comment and returns a UI deep-link.
• pull: Reads Langfuse scores back as OpenWright ComplianceEvents. Treats external evals as actionable compliance evidence.

💡 Best Practices & Patterns

• Evals-as-Evidence Pattern: Treat Langfuse evaluations as authoritative compliance artifacts. Use pull to ingest them directly as ComplianceEvents.
• Trace Backlinking Pattern: Always append OpenWright control reasons as comments when submitting scores. This guarantees full context within the Langfuse UI.
• Dynamic Connector Loading: Rely on openwright.connectors.load("openwright.forwarders", "langfuse"). Do not hard-import the forwarder to maintain loosely-coupled plugin architecture.
• Unchanged Telemetry (Co-ingestion): Pass OpenWright telemetry batches natively into the forward function. Never mutate the payloads beforehand.

🚨 Gotchas / Warnings (Anti-patterns)

• Version Mismatch: The forwarder strictly uses Langfuse HTTP API with x-langfuse-ingestion-version: 4. Overriding headers or using obsolete API specifications will silently drop traces.
• Reimplementing Crypto: Never reinvent encryption or token generation. The package strictly relies on Langfuse’s public HTTP API and Basic Auth.
• Python Bounds: Only supports Python >=3.10 and <3.15. Environments outside this strict constraint will fail.

🔍 Research / References

• PyPI: openwright-langfuse
• OpenWright Core Repo: allthingsN/openwright
• License: Apache-2.0