mixle.task.llm module

Provider-agnostic LLM adapters for task teachers and local model calls.

mixle has no LLM client of its own; this is the minimal adapter. An LLM is anything with complete(prompt) -> str. CallableLLM wraps a local function (a llama.cpp/transformers call, or a test double); OpenAICompatLLM posts to any OpenAI-compatible /v1/chat/completions endpoint (Ollama, vLLM, TGI, llama.cpp server, a hosted API) using only the standard library – no openai/requests dependency.

llm_labeler() turns an LLM into the teacher the rest of mixle.task distills from. teacher = llm_labeler(OpenAICompatLLM(...), ["spam", "ham"]) plugs a hosted or local model into mixle.task.distill.distill() / mixle.task.active.active_distill(): the LLM labels selected examples and the calibrated local student serves requests that it can answer. The same adapter lets an LLM propose a model specification (mixle.task.design).

exception LLMResponseError[source]

Bases: ValueError

Raised when an LLM response cannot satisfy the requested typed contract.

exception LLMParseError[source]

Bases: LLMResponseError

Raised when a required label or JSON value cannot be parsed unambiguously.

class LLM(*args, **kwargs)[source]

Bases: Protocol

Anything that can turn a prompt into text. The whole contract the rest of the package depends on.

complete(prompt, *, system=None, **kwargs)[source]

Return model text for a prompt and optional system instruction.

Parameters:

  • prompt (str)

  • system (str | None)

  • kwargs (Any)

Return type:

str

class CallableLLM(fn)[source]

Bases: object

Wrap a plain fn(prompt) -> str (or fn(prompt, system)) as an LLM – local models and tests.

Parameters:

fn (Callable[..., str])

complete(prompt, *, system=None, **kwargs)[source]

Call the wrapped Python function and return its text output.

Parameters:

  • prompt (str)

  • system (str | None)

  • kwargs (Any)

Return type:

str

validated_endpoint_url(url)[source]

Return url unchanged if it names an http/https endpoint; raise ValueError otherwise.

Every request this module makes goes through this check first (see _ALLOWED_ENDPOINT_SCHEMES for why): the scheme is validated against an allowlist before a request object is built, so a file:/ftp:/data: “endpoint” is rejected rather than opened.

Parameters:

url (str)

Return type:

str

class OpenAICompatLLM(base_url, model, *, api_key=None, temperature=0.0, max_tokens=512, timeout=60.0)[source]

Bases: object

An LLM backed by any OpenAI-compatible /v1/chat/completions endpoint (stdlib HTTP only).

Parameters:
complete(prompt, *, system=None, **kwargs)[source]

Call an OpenAI-compatible chat-completions endpoint and return message text.

Parameters:

  • prompt (str)

  • system (str | None)

  • kwargs (Any)

Return type:

str

pick_label(text, labels)[source]

Map a reply to exactly one declared label, or raise LLMParseError.

Parameters:
Return type:

str

llm_labeler(llm, labels, *, instruction=None, system=None)[source]

Turn an LLM into a label-constrained teacher texts -> [label] for distillation / active labeling.

Each item is classified into labels by a constrained prompt; the reply is mapped back with pick_label(). The returned callable has the batched-teacher shape the rest of mixle.task expects.

Parameters:
Return type:

Callable[[list[str]], list[str]]

extract_json_object(text)[source]

Decode the first valid JSON object in arbitrary surrounding text.

JSONDecoder.raw_decode provides real JSON string/escape semantics, so braces inside strings do not corrupt the scan. A malformed earlier candidate does not hide a later valid object.

Parameters:

text (str)

Return type:

dict[str, Any]

llm_extractor(llm, fields, *, instruction=None, system=None)[source]

Turn an LLM into a field-extraction teacher texts -> [{field: value}] for mixle.task.extract.distill_extractor().

Each text is extracted into a JSON object over fields (values must be verbatim substrings so they align to token spans during distillation). The returned callable has the batched-teacher shape the extractor expects.

Parameters:
Return type:

Callable[[list[str]], list[dict[str, str]]]