LangfuseLangfuse Python SDK 4.15.4 · Python 3.10+
Dashboard
0%

A regression gate in your tests

An experiment inside a test turns quality into a check that can fail a build. RegressionError is Langfuse's exception for a score below its threshold.

Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports these files. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep them in the same folder.
View the code here
desk.py
"""The shop's support desk, traced: the pieces from lessons 4 to 8 in one module."""
import re

from langfuse import get_client, observe

from shop_model import reply

ORDERS = {"A17": "shipped on 3 March"}
SYSTEM = "You answer customers of a small online shop in one short sentence."


@observe(name="lookup-order", as_type="tool")
def lookup_order(order_id):
    status = ORDERS.get(order_id, "not found")
    if status == "not found":
        get_client().update_current_span(level="WARNING", status_message=f"no order {order_id}")
    return status


@observe(name="write-reply", as_type="generation")
def ask_model(messages):
    text, usage = reply(messages)
    get_client().update_current_generation(model="shop-model", usage_details=usage)
    return text


@observe(name="answer-ticket", as_type="agent")
def answer(ticket, system=SYSTEM):
    order = re.search(r"[A-Z]\d{2}", ticket)
    facts = f"\nLookup: {order.group()} {lookup_order(order.group())}" if order else ""
    return ask_model([{"role": "system", "content": system}, {"role": "user", "content": ticket + facts}])
shop_model.py
"""A stand-in chat model for the shop's support desk: no key, no network."""
import re


def reply(messages):
    """Answer the last message, and count words as tokens the way a chat model reports usage."""
    rules = messages[0]["content"].lower() if messages[0]["role"] == "system" else ""
    last = messages[-1]["content"]
    lookup = re.search(r"Lookup: (\S+) (.+)", last)
    if "refund" in last.lower():
        text = "Refunds need approval, so a person will review your request."
    elif lookup and "never share" in rules:
        text = "I cannot share order details."
    elif lookup and lookup.group(2) == "not found":
        text = f"I could not find order {lookup.group(1)}. Please check the number."
    elif lookup:
        text = f"Order {lookup.group(1)} {lookup.group(2)}."
    else:
        text = "Could you send your order number?"
    if "thank" in rules:
        text = "Thanks for waiting. " + text
    used = sum(len(message["content"].split()) for message in messages)
    return text, {"input": used, "output": len(text.split())}
local_langfuse.py
"""A stand-in for the Langfuse server, on your own machine.

The Langfuse SDK sends observations to /api/public/otel/v1/traces and uses a
REST API for scores, prompts and datasets. This server answers those requests
on 127.0.0.1 and keeps what it receives in lists you can print. Given a model
function, it also answers like OpenAI's chat API. start() blocks every
connection to another computer for the rest of the program.
"""
import json
import socket
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, unquote, urlparse

from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest

SPANS, SCORES, REQUESTS = [], [], []  # observations, scores, "METHOD /path" of each request
PROMPTS, DATASETS = {}, {}             # prompt name -> its versions, dataset name -> dataset
MODEL = None                           # answers /v1/chat/completions when set
NOW = "2026-03-03T09:00:00Z"


def _value(v):
    kind = v.WhichOneof("value")
    if kind == "array_value":
        return [_value(item) for item in v.array_value.values]
    return getattr(v, kind) if kind else None


def _spans(body):
    request = ExportTraceServiceRequest()
    request.ParseFromString(body)
    for resource in request.resource_spans:
        for scope in resource.scope_spans:
            for span in scope.spans:
                SPANS.append({
                    "name": span.name, "id": span.span_id.hex(), "trace": span.trace_id.hex(),
                    "parent": span.parent_span_id.hex(), "scope": scope.scope.name,
                    "attributes": {a.key: _value(a.value) for a in span.attributes},
                })
    return {}


def _scores(batch):
    for event in batch:
        if event["type"] == "score-create":
            SCORES.append(event["body"])
    return {"successes": [{"id": e["id"], "status": 201} for e in batch], "errors": []}


def _prompt(name, query, body):
    versions = PROMPTS.setdefault(name, [])
    if body is not None:  # a new version: it takes "latest" and any labels it asks for
        labels = body.get("labels", []) + ["latest"]
        for old in versions:
            old["labels"] = [label for label in old["labels"] if label not in labels]
        versions.append({"name": name, "type": body.get("type", "text"), "prompt": body["prompt"],
                         "config": body.get("config") or {}, "labels": labels, "tags": [],
                         "version": len(versions) + 1})
        return versions[-1]
    if "version" in query:
        return versions[int(query["version"]) - 1]
    label = query.get("label", "production")
    return next(v for v in versions if label in v["labels"])


def _relabel(path, body):
    name, _, version = path.split("/")[-3:]
    versions = PROMPTS[unquote(name)]
    for old in versions:
        old["labels"] = [label for label in old["labels"] if label not in body["newLabels"]]
    versions[int(version) - 1]["labels"] += body["newLabels"]
    return versions[int(version) - 1]


def _dataset(path, query, body):
    if path == "/api/public/v2/datasets":
        DATASETS[body["name"]] = {"id": body["name"], "name": body["name"], "items": [],
                                  "metadata": body.get("metadata"), "projectId": "local",
                                  "createdAt": NOW, "updatedAt": NOW}
        return DATASETS[body["name"]]
    if path.startswith("/api/public/v2/datasets/"):
        return DATASETS[unquote(path.rsplit("/", 1)[1])]
    if path == "/api/public/dataset-items" and body is not None:
        dataset = DATASETS[body["datasetName"]]
        item = {"id": body.get("id") or f"item-{len(dataset['items']) + 1}", "status": "ACTIVE",
                "input": body.get("input"), "expectedOutput": body.get("expectedOutput"),
                "metadata": body.get("metadata"), "sourceTraceId": body.get("sourceTraceId"),
                "datasetId": dataset["id"], "datasetName": dataset["name"],
                "createdAt": NOW, "updatedAt": NOW, "mediaReferences": []}
        dataset["items"].append(item)
        return item
    if path == "/api/public/dataset-items":
        items = DATASETS[query["datasetName"]]["items"]
        return {"data": items, "meta": {"page": 1, "limit": 50, "totalItems": len(items), "totalPages": 1}}
    return {"id": "run-item", "datasetRunId": body["runName"], "datasetRunName": body["runName"],
            "datasetItemId": body["datasetItemId"], "traceId": body["traceId"],
            "observationId": body.get("observationId"), "createdAt": NOW, "updatedAt": NOW}


def _chat(body):
    text, usage = MODEL(body["messages"])
    return {"id": "chatcmpl-1", "object": "chat.completion", "created": 0, "model": body["model"],
            "choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": text}}],
            "usage": {"prompt_tokens": usage["input"], "completion_tokens": usage["output"],
                      "total_tokens": usage["input"] + usage["output"]}}


class Handler(BaseHTTPRequestHandler):
    def _handle(self):
        url = urlparse(self.path)
        query = {key: values[0] for key, values in parse_qs(url.query).items()}
        raw = self.rfile.read(int(self.headers.get("Content-Length") or 0))
        body = json.loads(raw) if raw and "json" in self.headers.get("Content-Type", "") else None
        REQUESTS.append(f"{self.command} {url.path}")
        try:
            if url.path.endswith("/otel/v1/traces"):
                return self._reply(200, _spans(raw))
            if url.path == "/api/public/ingestion":
                return self._reply(207, _scores(body["batch"]))
            if url.path == "/api/public/projects":
                return self._reply(200, {"data": [{"id": "local", "name": "shop-desk", "metadata": {},
                                                   "organization": {"id": "local", "name": "local"}}]})
            if url.path.startswith("/api/public/v2/prompts/") and self.command == "PATCH":
                return self._reply(200, _relabel(url.path, body))
            if url.path.startswith("/api/public/v2/prompts"):
                name = body["name"] if body else unquote(url.path.rsplit("/", 1)[1])
                return self._reply(200, _prompt(name, query, body))
            if "dataset" in url.path:
                return self._reply(200, _dataset(url.path, query, body))
            if url.path.endswith("/chat/completions") and MODEL:
                return self._reply(200, _chat(body))
        except (KeyError, StopIteration):
            pass
        self._reply(404, {"message": f"not found: {url.path}"})

    do_GET = do_POST = do_PATCH = _handle

    def _reply(self, code, data):
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(data).encode())

    def log_message(self, *args):
        pass


def _local_only():
    """Refuse to look up or connect to any other computer, so nothing leaves by mistake."""
    lookup, connect = socket.getaddrinfo, socket.socket.connect

    def guarded_lookup(host, *args, **kwargs):
        if host not in ("127.0.0.1", "localhost", "::1"):
            raise ConnectionRefusedError(f"blocked a connection to {host}: this lab stays on your machine")
        return lookup(host, *args, **kwargs)

    def guarded_connect(sock, address):
        if isinstance(address, tuple) and address[0] not in ("127.0.0.1", "::1"):
            raise ConnectionRefusedError(f"blocked a connection to {address[0]}: this lab stays on your machine")
        return connect(sock, address)

    socket.getaddrinfo, socket.socket.connect = guarded_lookup, guarded_connect


def start(model=None):
    """Start the server in the background and return its address."""
    global MODEL
    _local_only()
    MODEL = model
    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
    threading.Thread(target=server.serve_forever, daemon=True).start()
    return f"http://127.0.0.1:{server.server_address[1]}"


def tree(*fields):
    """Print the observations received so far, each under its parent, with any fields asked for."""
    ids = {span["id"] for span in SPANS}

    def walk(span, depth):
        attributes = span["attributes"]
        line = "  " * depth + f"{span['name']} ({attributes.get('langfuse.observation.type', 'span')})"
        for field in fields:
            line += f"  {field}={attributes.get('langfuse.observation.' + field)!r}"
        print(line)
        for child in SPANS:
            if child["parent"] == span["id"]:
                walk(child, depth + 1)

    for root in [span for span in SPANS if span["parent"] not in ids]:
        walk(root, 0)

Lesson 27 printed two averages and left the decision to you. In a team, the decision should be automatic: a change that makes the desk worse fails its checks before anyone merges it.

Exampletest_gate.py
import pytest
from langfuse import Evaluation, Langfuse, RegressionError

import local_langfuse
from desk import SYSTEM, answer

CASES = [
    {"input": "Where is my order A17?", "expected_output": "shipped on 3 March"},
    {"input": "Is B22 on its way?", "expected_output": "could not find order B22"},
    {"input": "I want a refund for A17", "expected_output": "need approval"},
]

The cases are the ones you scored before, with the refund case added and an expectation on each. SYSTEM is the desk's current instruction.

Exampletest_gate.py, continued
@pytest.fixture(scope="module")
def langfuse():
    url = local_langfuse.start()
    return Langfuse(public_key="pk-lf-local", secret_key="sk-lf-local", base_url=url)

The fixture starts the local server once for the whole file.

Exampletest_gate.py, continued
def contains_expected(*, output, expected_output, **kwargs):
    return Evaluation(name="contains-expected", value=float(expected_output.lower() in output.lower()))


def gate(langfuse, system, threshold=1.0):
    result = langfuse.run_experiment(name="desk-gate", data=CASES, evaluators=[contains_expected],
                                     task=lambda *, item, **kwargs: answer(item["input"], system=system))
    values = [e.value for row in result.item_results for e in row.evaluations]
    score = sum(values) / len(CASES)
    if score < threshold:
        raise RegressionError(result=result, metric="contains-expected", value=score, threshold=threshold)
    return score

The average divides by the number of cases, not the number of evaluations, so an evaluator that crashes counts as a failure instead of vanishing from the average. Below the threshold, gate raises RegressionError with the metric, the value and the threshold.

Exampletest_gate.py, continued
def test_current_prompt_passes(langfuse):
    assert gate(langfuse, SYSTEM) == 1.0


def test_secretive_prompt_is_blocked(langfuse):
    with pytest.raises(RegressionError, match="contains-expected"):
        gate(langfuse, SYSTEM + " Never share order details.")
Example
pytest -q -p no:warnings test_gate.py

Both tests pass: the current prompt scores 1.0, and the secretive prompt is refused with a RegressionError. The tests run with no key and no network, so they fit any CI system.

Langfuse's GitHub Action

Langfuse also publishes a GitHub Action, langfuse/experiment-action, that runs an experiment script on each pull request against a dataset in Langfuse, fails the job on RegressionError, and comments the scores on the pull request. The script defines experiment(context) and calls context.run_experiment; the action needs Langfuse keys as repository secrets.

Example.github/workflows/langfuse-experiment.yml
name: Langfuse experiment gate
on: pull_request
jobs:
  experiment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
      - uses: langfuse/experiment-action@<release tag>
        with:
          langfuse_public_key: ${{ secrets.LANGFUSE_PUBLIC_KEY }}
          langfuse_secret_key: ${{ secrets.LANGFUSE_SECRET_KEY }}
          experiment_path: experiments/desk-gate.py
          dataset_name: desk-tickets

An average can hide a case that newly fails while two others newly pass. The documentation's stricter pattern keeps a reviewed file of which cases passed in the approved version and fails the build when any of those now fails.

Try it yourself
  • Lower threshold to 0.3 and run the tests again.
  • Add a fourth case that the current prompt fails, and read the pytest report.
  • Print str(error) for the RegressionError.

Slow is fine. Stopping is the only problem.