Skip to main content

​
Overview

ClefClassifier answers classifier questions through Clef, Cloudflare’s decision model on Workers AI. All the questions about one state go to Clef in one request, and an answer typically comes back in a few hundred milliseconds. Clef comes as two models: clef, the default, and clef-flash for faster answers. A ClefClassifier asks through a ClefClient, which holds the HTTP/2 connection, adds the auth header, retries when Workers AI is busy, and counts tokens. Build the classifier with an account ID and API token to give it a client of its own, or pass a ClefClient to share one connection between several classifiers.

​
Installation

​
Prerequisites

A Cloudflare account ID and an API token with Workers AI access, usually set as environment variables:

​
Configuration

​
ClefClassifier

​
str | None
default:"None"
Cloudflare account ID, when the classifier should have a client of its own.
​
str | None
default:"None"
Cloudflare API token, when the classifier should have a client of its own.
​
ClefClient | None
default:"None"
A client to share with other classifiers. Either client, or both account_id and api_key, are required.
​
str
default:"clef"
The Clef model a client of its own asks: clef, or clef-flash for faster answers.
​
float
default:"10.0"
Seconds a client of its own waits for an answer before raising ClassifierError.
​
str | None
default:"None"
Name of the classifier, as it appears in logs and metrics.

​
ClefClient

​
str
required
Cloudflare account ID.
​
str
required
Cloudflare API token with Workers AI access.
​
str
default:"clef"
The Clef model to ask: clef, or clef-flash for faster answers.
​
float
default:"10.0"
Seconds to wait for a reply before raising ClassifierError.
​
int
default:"3"
How many times to retry a request Workers AI refused because it was busy (HTTP 429), with exponential backoff.

​
Usage

​
Basic Usage

Most of the time you don’t call the classifier yourself: you pass it to a component that asks it, such as VoicemailDetector or UIWorker.

​
Sharing a Client

Several classifiers can share one ClefClient, and with it one connection pool and one token count:
A client the classifier created is closed in the classifier’s cleanup(). A shared client is left open, so close it yourself with await client.close() when every classifier using it is done.

​
Opening the Connection Early

setup() opens the connection to Workers AI ahead of the first question, so the first answer does not pay for the TLS handshake. Components that own a classifier, such as VoicemailDetector, call it for you. If the connection cannot be opened at setup, a warning is logged and the first question opens it instead.

​
ClefClassifier Properties

​
ClefClient Reference

​
Properties

​
Methods

​
connect

Opens the connection to Workers AI by asking for the model’s schema, which also checks the token and the model name. It connects once: a client shared by several classifiers is connected by each of them, and only the first call sends anything. Raises ClassifierError if Workers AI could not be reached or refused the request.

​
close

Closes the connection pool.

​
Metrics

After every call, a ClefClassifier reports the time it took as ProcessingMetricsData and the tokens Clef used as LLMUsageMetricsData through its on_metrics event.

​
Notes

  • Limits: a choice question takes at most 255 options, available as CLEF_MAX_CHOICE_OPTIONS in pipecat.classifiers.cloudflare.clef.classifier. A question with more raises ClassifierError before anything is sent.
  • Errors: a rejected request, a busy Workers AI after every retry, an unreachable server, or a reply missing an answer all raise ClassifierError. The message carries the reason Cloudflare gave, such as HTTP 401: Authentication error.
  • Idle connections are kept open for 240 seconds, so a gap between questions does not cost a new TLS handshake.