osrforge.providers.clef_local
The local Clef backend: a decision model on a System One server on this machine, such as Ollama.
It fills the tracing stage's decision role
(DecisionProvider), as the
hosted adapter in osrforge.providers.clef does, and costs nothing, so it
keeps no ledger. A setting chooses between the two backends
(clef_from_env).
Each request is one HTTP POST to <base_url>/v1/systemone with a JSON body.
The body is the hosted body of
request_body with two
differences that Ollama's System One endpoint needs: model is the server's
name for the model, and images is a list of plain base64 strings rather
than {content_type, base64} objects. The image goes as PNG, or as JPEG
when the hosted body would be too large, by the same rule as
encode_request, so both
backends see the same pixels. The server answers with
{"model", "answers": {<tag>: {"probabilities": {...}, ...}}, "usage":
{"input_tokens", ...}} at the top level, with no envelope.
A response's model_id is local: followed by the model the server says
answered, so a recording shows which backend made it. Recordings from the
two backends belong in different directories, because the recording key
names the model and not the backend.
No vendor SDK: the transport is a function the constructor takes, so tests give it a fake.
BACKEND_ENV
module-attribute
hosted (the default when unset or empty) or local.
LOCAL_MODEL_ENV
module-attribute
The server's name for Clef-flash. The default is clef-flash, Ollama's.
LOCAL_URL_ENV
module-attribute
The local server's API root. The default is http://localhost:11434, Ollama's.
LocalClefProvider
LocalClefProvider(
settings: LocalClefSettings, transport: Transport | None = None, sleep: Callable[[float], None] | None = None
)
Clef on a local System One server.
The constructor performs no I/O. Transport policy: at most three attempts per request. A connection failure and a 5xx are retried with a short backoff, and any other status that isn't 200 raises at once. An error names the server's URL, the status or the connection failure, and the server's message, so a server that isn't running says so plainly.
Bind to a server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
settings
|
LocalClefSettings
|
The settings. |
required |
transport
|
Transport | None
|
The function that sends one POST, injectable for tests. When omitted, the provider uses the standard library's HTTP client with the settings' timeout. |
None
|
sleep
|
Callable[[float], None] | None
|
The backoff sleeper, injectable for tests. When omitted,
|
None
|
decide
decide(request: DecisionRequest) -> DecisionResponse
Send one question and return its probabilities.
The image goes as PNG unless
encode_request would
send the hosted body as JPEG. The POST goes to <base_url>/v1/systemone
with a JSON content type and no authorization. The answer's
probabilities must cover exactly the request's options. The response's
model_id is local: and the model the server names, input_tokens
is the usage's, format is how the image went, and body_sha256 is
the sha256 of the body sent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
DecisionRequest
|
The question. |
required |
Returns:
| Type | Description |
|---|---|
DecisionResponse
|
The answer. |
Raises:
| Type | Description |
|---|---|
ProviderError
|
If the request names a model the settings don't map, the server can't be reached or keeps failing, it answers with another status, or its answer can't be read. |
LocalClefSettings
Bases: BaseModel
Where the local server is and what it calls each model.
Examples:
from osrforge.providers.clef_local import LocalClefProvider, LocalClefSettings
provider = LocalClefProvider(LocalClefSettings())
base_url
class-attribute
instance-attribute
base_url: str = _DEFAULT_URL
The server's API root, with no trailing slash. The provider appends /v1/systemone.
models
class-attribute
instance-attribute
The server's name for each model a request may name. A request for a model not in this map is refused before anything is sent.
timeout_seconds
class-attribute
instance-attribute
How long one attempt may take. The first request after the server loads the model can take seconds.
from_env
classmethod
from_env() -> LocalClefSettings
Build settings from OSRFORGE_CLEF_LOCAL_URL and OSRFORGE_CLEF_LOCAL_MODEL, each optional.
Returns:
| Type | Description |
|---|---|
LocalClefSettings
|
The settings, with a trailing slash stripped from the URL. When |
LocalClefSettings
|
names the server's model for |
clef_from_env
clef_from_env() -> ClefProvider | LocalClefProvider
Build the decision provider the environment chooses.
OSRFORGE_CLEF_BACKEND chooses the backend: hosted, the default when
it's unset or empty, gives a ClefProvider
from ClefSettings.from_env,
and local gives a
LocalClefProvider
from LocalClefSettings.from_env,
which needs no account, token, or ledger.
Returns:
| Type | Description |
|---|---|
ClefProvider | LocalClefProvider
|
The provider. |
Raises:
| Type | Description |
|---|---|
ProviderError
|
If the backend is another word, or the hosted backend's settings are missing. |
local_request_body
local_request_body(request: DecisionRequest, image_format: ImageFormat, server_model: str) -> bytes
Build the exact body for the local server.
The body is the canonical JSON (sorted keys, compact separators, UTF-8)
of {"model": server_model, "images": [<base64 of the image>], "state":
request.state, "questions": {request.tag: {"type": "choice",
"instructions": request.question, "criteria": {option id:
description}}}}. The image is the request's PNG, or for "jpeg" the
PNG's pixels saved as the hosted body saves them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
DecisionRequest
|
The request. |
required |
image_format
|
ImageFormat
|
How to send the image. |
required |
server_model
|
str
|
The server's name for the request's model. |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
The body bytes. |