Module llm 

Shared LLM provider construction from environment variables.

Used by extract and reextract. Providers:

• OXIBRAIN_LLM_PROVIDER=anthropic (+ ANTHROPIC_API_KEY, ANTHROPIC_MODEL)
• OXIBRAIN_LLM_PROVIDER=openai (+ OPENAI_API_KEY, OPENAI_MODEL)
• OXIBRAIN_LLM_PROVIDER=local (GGUF from oxibrain model pull, §8.4)

Resolution order for from_env_for_role, the role-aware entry point (Oxi Foundation v1, Task 3 §3):

1. Explicit OXIBRAIN_LLM_PROVIDER (CLI / automation override).
2. Foundation profile for the requested role whose declared capabilities satisfy the configured extraction mechanism, and whose Keychain secret resolves. A missing/unavailable secret reports why that profile cannot run and falls through to (3). It never silently sends extraction to a different remote provider.
3. Existing ANTHROPIC_* / OPENAI_* compatibility environment.
4. Local GGUF (C2 — no API key required, default).

The legacy from_env / resolve_provider entry points remain in place so the existing extract / reextract callers do not move; they default to role memory.extract. OXIBRAIN_LLM_ROLE overrides the role when present.

OXIBRAIN_MODEL is a fallback for the HTTP model id. The mechanism (tool-call / json-schema / GBNF grammar) follows the provider — Anthropic uses forced tool calls, OpenAI native json_schema structured output, and the local path grammar-constrained decoding (DESIGN §7.4, §9.4).

Structs

ProviderLlm

A resolved LLM provider: the port plus everything ExtractorConfig and Brain need to reflect it (model id, mechanism, weights digest, exact tokenizer when the provider ships one, plus the resolution source for provenance).

Enums

Provider

Which provider from_env resolved. Testable without touching the network or loading model weights.

ResolutionSource

Where the resolved provider came from. Carries enough metadata for callers (and tests) to prove the resolution ladder actually fired the step they expect. Foundation-resolved profiles additionally surface the profile id so Task 5 can plumb it into ExtractorConfig / ExtractorId provenance.

Functions

config

Build a default extractor config from the env-resolved model + mechanism.

from_env

Build an LLM port from the environment using the legacy (role-less) ladder. Preserved for existing extract / reextract callers that have not yet opted into the Foundation-aware entry point.

from_env_for_role

Build an LLM port from the environment for a specific role.

resolve_provider

Decide the provider from the explicit override alone, without consulting Foundation profiles. key_present / openai_key_present are injected so tests stay hermetic. Kept for the legacy callers; new code should prefer from_env_for_role.

resolve_role

Role chosen by OXIBRAIN_LLM_ROLE (or the default). The env var is the only way to override the role today; future revisions can extend OXIBRAIN_LLM_ROLE to comma-separated lists for fan-out consolidation.