LangfuseLangfuse Python SDK 4.15.4 · Python 3.10+
Dashboard
0%

The prompt cache, and a fallback

The SDK caches prompts in memory, so only the first get_prompt waits for the network. With no cache and no server, get_prompt raises, unless you give it a fallback.

Lesson 20 mentioned a cache that delays a label change in other programs. The same cache is why fetching a prompt on every request is fine, and why an application keeps working through a short Langfuse outage.

Examplecache.py, after the setup lines
langfuse.create_prompt(name="desk-system", prompt="Answer in one short sentence.", labels=["production"])

for _ in range(3):
    langfuse.get_prompt("desk-system")
print(local_langfuse.REQUESTS)
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
cache.py
from langfuse import Langfuse

import local_langfuse

url = local_langfuse.start()
langfuse = Langfuse(public_key="pk-lf-local", secret_key="sk-lf-local", base_url=url)

langfuse.create_prompt(name="desk-system", prompt="Answer in one short sentence.", labels=["production"])

for _ in range(3):
    langfuse.get_prompt("desk-system")
print(local_langfuse.REQUESTS)
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)
Example
python cache.py

Three calls, one request. The first fetched the prompt; the other two came from memory. After the 60 second lifetime, the next call still returns the cached prompt at once and fetches a new copy in the background. cache_ttl_seconds changes the lifetime, and 0 turns caching off, which the documentation suggests only outside production.

When Langfuse cannot be reached

A cache only helps once it has something in it. A freshly started process has an empty cache. Port 9 on your machine, where nothing listens, stands in for a Langfuse that is down.

Exampledown.py
from langfuse import Langfuse

langfuse = Langfuse(public_key="pk-lf-local", secret_key="sk-lf-local", base_url="http://127.0.0.1:9")

try:
    prompt = langfuse.get_prompt("desk-system")
except Exception as error:
    print("no prompt:", type(error).__name__)
Example
python down.py

With nothing cached and no answer after its retries, get_prompt raised. Uncaught, that error would stop the desk from answering anyone, which is a worse outage than Langfuse's.

Exampledown.py, fixed
from langfuse import Langfuse

langfuse = Langfuse(public_key="pk-lf-local", secret_key="sk-lf-local", base_url="http://127.0.0.1:9")

prompt = langfuse.get_prompt("desk-system", fallback="Answer in one short sentence.")
print(prompt.is_fallback, "|", prompt.compile())
Example
python down.py

With fallback, the SDK logs the failure and returns a prompt built from the text you gave it, marked is_fallback. Keep the fallback close to the production prompt. The other option in the documentation is to fetch every prompt when the application starts and refuse to start without them, so a new instance never serves without its prompt.

Where a prompt comes from, and what happens when it cannot be fetched
in Langfusein your processversion 1one short sentenceversion 2plus a thank-youversion 3a candidateproductionwhat the desk asks forlatestalways the newestthe SDK cache60 seconds, then refreshedyour applicationget_prompt('desk-system')fallbackno cache and no server
Hover or tap a piece to see what it is and which lesson built it.
Ask for the prompt

Pick one to watch it run, step by step.

Versions and labels live in Langfuse; the cache and the fallback live in your process. Between them, a prompt change reaches the desk within a minute, and a Langfuse outage does not reach customers at all.

Try it yourself
  • Give a chat prompt a fallback: a list of messages, with type="chat".
  • Set cache_ttl_seconds=0 in cache.py and count the requests.
  • Print prompt.version for the fallback prompt.

Little by little, you're building something great.