Classifiers

Narrow, typed questions answered with probabilities. See the Classifiers guide for usage.

Classifier

Bases: ABC

Answers typed questions about a state, every one or none (ClassifierError).

It sends the questions' wording as the caller wrote it, and bounds its wait. An implementation says how far its probabilities can be trusted.

classify abstractmethod async

classify(state, questions)

Every question in questions answered, under its name.

close async

close()

Release resources (a client, a model).

YesNoQuestion dataclass

YesNoQuestion(instructions, yes=None, no=None)

Whether something holds: answered with the probability of yes.

instructions instance-attribute

instructions

The question, and what it means.

yes class-attribute instance-attribute

yes = None

What a yes covers, when that needs saying.

no class-attribute instance-attribute

no = None

What a no covers.

ChoiceQuestion dataclass

ChoiceQuestion(instructions, options)

One option among several: answered with every option's probability.

options instance-attribute

options

Each option's name and what it covers; two at least.

ScoreQuestion dataclass

ScoreQuestion(instructions, levels)

A degree on an ordered scale: answered with the expected level.

levels instance-attribute

levels

The levels, lowest first, each described; two at least.

YesNoAnswer dataclass

YesNoAnswer(probability)

probability instance-attribute

probability

Of yes, in [0, 1].

ChoiceAnswer dataclass

ChoiceAnswer(choice, probabilities=dict())

choice instance-attribute

choice

The most probable option.

probabilities class-attribute instance-attribute

probabilities = field(default_factory=dict)

Every option's probability.

ScoreAnswer dataclass

ScoreAnswer(score, probabilities=())

score instance-attribute

score

The expected level: 0 for the first, a fraction between two levels.

probabilities class-attribute instance-attribute

probabilities = ()

Each level's probability, in the levels' order.

Answers

Bases: dict[str, Answer]

The answers by question name, with typed reads.

answers.yes("addressed") is the probability of yes, answers.choice("lang") the chosen option, answers.score("directness") the expected level.

ClassifierError

Bases: Exception

A classifier could not answer: a refused request, an answer it cannot read, or the end of its bounded wait.

check_answers

check_answers(questions, answers)

answers, once every question has its answer of the right type.

JevClassifier

JevClassifier(api_key=None, *, model=None, timeout=3.0, client=None)

Bases: Classifier

Answers on Jev, with calibrated probabilities.

Parameters:

Name	Type	Description	Default
api_key	str | None	The TypeSafe key; the SDK reads TYPESAFE_API_KEY when None.	None
model	str | None	A Jev model id; the SDK's default when None.	None
timeout	float	Seconds the whole call may take, retries included, before ClassifierError.	3.0
client	Any | None	An AsyncTypeSafeClient to use instead of one made here (it is then the caller's to close).	None

OpenAIClassifier

OpenAIClassifier(api_key=None, *, model=DEFAULT_MODEL, timeout=3.0, client=None)

Bases: Classifier

Answers on OpenAI's Decisions API, with probabilities.

Parameters:

Name	Type	Description	Default
api_key	str | None	The OpenAI key; the SDK reads OPENAI_API_KEY when None.	None
model	str	A model the Decisions API takes.	DEFAULT_MODEL
timeout	float	Seconds the whole call may take, retries included, before ClassifierError.	3.0
client	Any | None	An AsyncOpenAI to use instead of one made here (it is then the caller's to close).	None

LLMClassifier

LLMClassifier(provider, *, timeout=10.0, max_tokens=1000)

Bases: Classifier

Answers on provider under a JSON schema; probabilities degenerate (0 or 1).

Parameters:

Name	Type	Description	Default
provider	AIProvider	An AI provider that supports response_schema (RFC §6.7). It stays the caller's: close() leaves it open.	required
timeout	float	Seconds it waits for the answer before raising ClassifierError.	10.0
max_tokens	int	The answer's cap; a reasoning model needs room for its reasoning.	1000

Raises:

Type	Description
ValueError	provider does not support a response schema.

MockClassifier

MockClassifier(answers=None, *, error=None)

Bases: Classifier

Answers from a script, by question name: a float for a yes/no question (the probability of yes), an option for a choice, a level for a score, or an :data:~roomkit.classifiers.base.Answer. A question the script does not name gets no, the first option, or the lowest level. Given a list of scripts, the calls take them in order and the last one repeats. Records every call.