core.model

Model modules: Ollama Python client wrapper, model download/setup UX, and model availability checking.

Model Backend

core.model.model_backend

ModelBackend implementations — real Ollama backend and factory.

Provides a concrete ModelBackend implementation wrapping the Ollama Python client, plus a factory function for selecting backends by name.

Design goals

1. All Ollama-specific calls are contained in this module.
2. The rest of the codebase depends only on ModelBackend Protocol.
3. Alternative backends (llama.cpp, remote API) can be added by implementing the Protocol and registering a factory name.

Components

• OllamaModelBackend — wraps the ollama Python client
• OllamaEmbedder — standalone embedding helper for Ollama
• create_model_backend() — factory function

OllamaModelBackend

Real ModelBackend wrapping the Ollama Python client.

Reads OLLAMA_HOST from the environment (default http://127.0.0.1:11434). Set it via os.environ or main.py before constructing.

Parameters

default_model : Model name used when model is not specified per-call. keep_alive : Model keep-alive duration in seconds (-1 = forever).

cancel() -> None

Signal in-flight generation to stop.

chat(*, model: str = '', messages: list[dict[str, str]] | None = None, system_prompt: list[str] | str | None = None, temperature: float = 1.0, top_p: float = 0.95, top_k: int = 64, num_ctx: int = 8192, tools: list[dict[str, Any]] | None = None, think: bool | str | None = None, seed: int | None = None, **kwargs: Any) -> dict[str, Any] async

Return the full response (non-streaming) from Ollama.

chat_stream(*, model: str = '', messages: list[dict[str, str]] | None = None, system_prompt: list[str] | str | None = None, temperature: float = 1.0, top_p: float = 0.95, top_k: int = 64, num_ctx: int = 8192, tools: list[dict[str, Any]] | None = None, think: bool | str | None = None, seed: int | None = None, **kwargs: Any) -> AsyncIterator[str] async

Yield raw token strings from Ollama chat stream.

chat_stream_structured(*, model: str = '', messages: list[dict[str, str]] | None = None, system_prompt: list[str] | str | None = None, temperature: float = 1.0, top_p: float = 0.95, top_k: int = 64, num_ctx: int = 8192, tools: list[dict[str, Any]] | None = None, think: bool | str | None = None, seed: int | None = None, **kwargs: Any) -> AsyncIterator[ChatStreamChunk] async

Yield structured :class:ChatStreamChunks from Ollama.

Wraps the raw Ollama stream response, extracting content, thinking/reasoning, and tool-calls into typed chunks.

chat_stream_structured_sync(*, model: str = '', messages: list[dict[str, str]] | None = None, system_prompt: list[str] | str | None = None, temperature: float = 1.0, top_p: float = 0.95, top_k: int = 64, num_ctx: int = 8192, tools: list[dict[str, Any]] | None = None, think: bool | str | None = None, seed: int | None = None, **kwargs: Any) -> Iterator[ChatStreamChunk]

Sync generator version of :meth:chat_stream_structured.

Designed for loop.run_in_executor() calls where an async generator cannot be used directly (e.g. agent_classes.py's executor offload path).

embed(*, model: str = '', texts: list[str]) -> list[list[float]] async

Return embeddings for each text via Ollama.

health_check() -> dict[str, Any] async

Return a health status dict ({"healthy": True, "status": "ok"}).

list_models() -> list[str] async

List available models on the Ollama server.

OllamaEmbedder

Standalone embedding helper for Ollama.

Thin wrapper around ollama.embed() used by core/embedding.py and other modules that only need vector embeddings (not chat).

Reads OLLAMA_HOST from the environment (set by main.py).

Parameters

default_model : Default embedding model name. keep_alive : Model keep-alive duration in seconds.

embed(texts: list[str], *, model: str = '', options: dict[str, Any] | None = None) -> list[list[float]] async

Embed one or more texts.

embed_single(text: str, *, model: str = '', options: dict[str, Any] | None = None) -> list[float] async

Embed a single text and return the vector.

create_model_backend(backend: str = 'ollama', **kwargs: Any) -> ModelBackend

Create a ModelBackend implementation by name.

Parameters

backend : Backend name ("ollama" is built-in). Use register_backend() to add custom implementations. **kwargs : Passed through to the backend constructor.

Returns

ModelBackend

Raises

ValueError If backend is not registered.

Model Manager

core.model.model_manager

Model download and setup manager.

Provides a cohesive API for model availability detection, health checks, recommendations, disk-space validation, and optional downloads. Bridges the gap between ModelBackend (runtime inference), ProvenanceStore (checksums/consent), and OnboardingManager (first-run flow).

Components

• ModelInfo — metadata about a single available/recommended model
• OllamaStatus — detection status of the Ollama service
• ModelRecommendation — a suggested model with rationale
• DiskSpaceWarning — disk space advisory
• ModelManager — high-level manager coordinating detection, health, recommendations, downloads, and verification

DiskSpaceWarning dataclass

Disk space advisory.

Parameters

path : The path checked (e.g. model cache directory). total_bytes : Total disk space on the partition. free_bytes : Free disk space remaining. required_bytes : Estimated space required for pending operations. is_sufficient : Whether free space meets the requirement. message : Human-readable warning message.

check(path: str | Path, required_bytes: int = 0) -> DiskSpaceWarning classmethod

Check disk space for a path.

ModelAvailability

Bases: StrEnum

Whether a required model is available locally.

ModelInfo dataclass

Metadata about a single model (available or recommended).

Parameters

name : Full model name (e.g. "gemma4:26b"). availability : Whether the model is available locally. size_bytes : Approximate size on disk (0 if unknown). purpose : Human-readable description of what this model is used for. backend : Backend name (e.g. "ollama"). priority : 0 = required, 1 = recommended, 2 = optional. metadata : Arbitrary additional context (quantization, family, sha256).

ModelManager dataclass

High-level model lifecycle manager.

Coordinates Ollama detection, health checks, model recommendations, disk-space validation, and optional downloads.

Parameters

backend : Optional pre-built ModelBackend (e.g. OllamaModelBackend). provenance_store : Optional pre-built ProvenanceStore. required_models : List of required model names (from config). recommended_models : List of recommended model names (from config). embed_model : Embedding model name (from config). stt_model : Speech-to-text model name (from config). vision_model : Vision model name (from config).

check_disk_space(path: str | Path | None = None) -> DiskSpaceWarning async

Check disk space for model storage.

Parameters

path : Path to check (default: user's home directory).

check_healthy() -> dict[str, Any] async

Run a health check on the backend.

Returns

dict Health status dictionary (from backend.health_check()).

check_ollama() -> OllamaStatus async

Check if Ollama is available and healthy.

Returns

OllamaStatus Detection status (NOT_FOUND, RUNNING, HEALTHY, VERSION_MISMATCH).

list_local_models() -> list[ModelInfo] async

List models available locally via the backend.

list_required_models() -> list[ModelInfo] async

List all required models and their availability.

pull_model(model_name: str, *, timeout: float = 3600.0, on_progress: Callable[[str], Awaitable[None]] | None = None) -> bool async

Pull a model via ollama pull.

Parameters

model_name : Full model name (e.g. "gemma4:26b"). timeout : Maximum seconds to wait for the pull. on_progress : Optional callback for progress updates.

Returns

bool True if the pull completed successfully.

recommend_models() -> list[ModelRecommendation] async

Generate model recommendations based on config and availability.

Returns models that are missing but needed for full functionality.

record_consent(model_name: str) -> bool

Record user consent for a model. Returns True if recorded.

run_setup_check() -> dict[str, Any] async

Run a comprehensive setup check.

Returns a dictionary with: - ollama_status: OllamaStatus - local_models: list[ModelInfo] - missing_models: list[ModelInfo] - recommendations: list[ModelRecommendation] - disk_space: DiskSpaceWarning - warnings: list[str] - loaded_models: list[str] -- models currently loaded in Ollama memory - configured_models: list[str] -- all models referenced by config

verify_model(model_name: str) -> list[str] async

Verify a model's provenance. Returns a list of warnings.

ModelRecommendation dataclass

A suggested model with rationale and urgency.

Parameters

model_name : Full model name to recommend. rationale : Human-readable explanation of why this model is recommended. urgency : How critical this model is (critical, important, optional). estimated_size_bytes : Approximate download size. pull_command : Shell command to pull the model (for display in UI). metadata : Arbitrary additional context.

OllamaStatus

Bases: StrEnum

Detection status of the Ollama service.

create_model_manager(*, required_models: list[str] | None = None, recommended_models: list[str] | None = None, embed_model: str = 'qwen3-embedding:0.6b', stt_model: str = '', vision_model: str = '', backend: ModelBackend | None = None, provenance_store: ProvenanceStore | None = None) -> ModelManager

Create a ModelManager from config values.

Parameters

required_models : List of required model names. recommended_models : List of recommended (non-required) model names. embed_model : Embedding model name. stt_model : Speech-to-text model name. vision_model : Vision model name. backend : Optional pre-built ModelBackend. provenance_store : Optional pre-built ProvenanceStore.

Returns

ModelManager Configured model manager.

set_model_backend(backend) -> None

Set an optional ModelBackend for the ModelManager.