Model context windows

Call gateway.get_model_context_window(model) to ask what the provider advertises. The result is a ModelContextWindow with positive max_context_tokens, a source field, and optional Ollama model_num_ctx. None means not advertised or unsupported. Discovery never applies metadata to later completion requests.

from mojentic.llm import CompletionConfig, effective_context_window
from mojentic.llm.gateways.ollama import OllamaGateway

gateway = OllamaGateway(host="http://localhost:11434")
window = gateway.get_model_context_window("qwen3:8b")
config = CompletionConfig(num_ctx=8192)
upper_bound = effective_context_window(window, config)

Ollama sends POST /api/show with exactly {"model": model} and the configured headers. Any architecture's *.context_length supplies the advertised window. The model's parameters text may supply model_num_ctx; this does not replace the advertised window. oMLX uses its configured host and API key for GET /v1/models, matches the exact model ID, and reads max_model_len. OpenAI uses only exact entries in its local model registry, with field="registry", and sends no request. Unknown OpenAI models return None even if completion's existing pattern fallback recognizes their names. Other gateways return None.

HTTP discovery raises httpx.TransportError when the server cannot be reached, httpx.HTTPStatusError for non-success status (including unknown-model 404), and ValueError for malformed JSON or metadata. A missing window is distinct from an invalid advertised value; booleans, strings, zero and negative windows fail validation. Discovery does not retry or change completion recovery behavior.

effective_context_window(window, config) is a pure helper. Caller num_ctx takes precedence over model_num_ctx, and the selected size is clamped to the advertised maximum. Without either setting it returns the advertised maximum; without metadata it returns None, even when the caller supplied num_ctx. Ollama server environment settings remain unknown, so the result is an upper bound. It does not change ChatSession.max_context, configure a request, or measure first-token timing.

Python verifies the unchanged context-window-v1 JSON contract in src/mojentic/llm/contracts/context_window_v1.json through loopback HTTP and contract-derived gateway doubles. Run:

uv run pytest src/mojentic/llm/gateways/context_window_spec.py
sha256sum --check src/mojentic/llm/contracts/context_window_v1.manifest.sha256

These checks also run in the normal pytest gate. External server and cross-repository consumer verification remain unfinished; see CONFORMANCE-3.0.0.md. The coordinated publication hold remains in force.

mojentic.llm.model_context_window.ModelContextWindow

Bases: BaseModel

An advertised positive window, its source field and optional model default.

Parameters:

Name	Type	Description	Default
max_context_tokens	int		required
field	str		required
model_num_ctx	Annotated[int, Strict] | None		None

Source code in src/mojentic/llm/model_context_window.py

class ModelContextWindow(BaseModel):
    """An advertised positive window, its source field and optional model default."""

    model_config = ConfigDict(frozen=True)

    max_context_tokens: StrictInt = Field(gt=0)
    field: str
    model_num_ctx: StrictInt | None = Field(default=None, gt=0)

mojentic.llm.model_context_window.effective_context_window(window_result, config=None)

Return the advertised upper bound clamped by caller or model context size.

Parameters:

Name	Type	Description	Default
window_result	ModelContextWindow | None	Discovered metadata. Unknown metadata always yields None.	required
config	CompletionConfig | None	Explicit num_ctx takes precedence over the model's default.	None

Returns:

Type	Description
int | None	Effective upper bound; server environment defaults remain unknown.

Source code in src/mojentic/llm/model_context_window.py

def effective_context_window(
    window_result: ModelContextWindow | None, config: CompletionConfig | None = None
) -> int | None:
    """Return the advertised upper bound clamped by caller or model context size.

    Parameters
    ----------
    window_result : ModelContextWindow | None
        Discovered metadata. Unknown metadata always yields None.
    config : CompletionConfig | None
        Explicit num_ctx takes precedence over the model's default.

    Returns
    -------
    int | None
        Effective upper bound; server environment defaults remain unknown.
    """
    if window_result is None:
        return None
    requested = config.num_ctx if config is not None else None
    selected = requested if requested is not None else window_result.model_num_ctx
    return (
        min(window_result.max_context_tokens, selected)
        if selected is not None
        else window_result.max_context_tokens
    )