Exceptions

ContextOverflowError means the request input does not fit the model context, so Agent drops the latest turn, summarizes the rest and retries the step once. OutputTokenLimitError means the provider exhausted the configured max_tokens response budget. An output limit failure surfaces without summarization or retry with the unchanged limit. IncompleteResponseError means the provider stopped for some other reason, such as a content filter; it also surfaces without retry. CompactionRequiredError means the provider rejected the request for a limit compaction can fix, too many images (reason="image_count") or too many request bytes (reason="request_size"); Agent drops the latest turn, summarizes the rest and retries the step once.

stirrup.core.exceptions

Custom exceptions for agent framework.

__all__ module-attribute

__all__ = [
    "CompactionReason",
    "CompactionRequiredError",
    "ContextOverflowError",
    "IncompleteResponseError",
    "OutputTokenLimitError",
]

CompactionReason

CompactionReason = Literal['image_count', 'request_size']

CompactionRequiredError

CompactionRequiredError(
    *args: object, reason: CompactionReason
)

Bases: Exception

Raised by an LLMClient when compacting the conversation could fix a rejected request.

For limits other than tokens: too many images ("image_count") or too many request bytes ("request_size"). The agent drops the latest turn, summarizes the rest and retries the step once, as for ContextOverflowError. reason is recorded as the summary's trigger.

Source code in src/stirrup/core/exceptions.py

def __init__(self, *args: object, reason: CompactionReason) -> None:
    super().__init__(*args)
    self.reason = reason

ContextOverflowError

Bases: Exception

Raised when request input exceeds the model's context capacity.

The agent drops the latest turn, summarizes the rest and retries the step once.

IncompleteResponseError

Bases: Exception

Raised when a provider returns an incomplete response Stirrup cannot recover from.

Covers stop reasons other than the context and output-budget cases, such as a content filter. Retrying the same request is not expected to help.

OutputTokenLimitError

OutputTokenLimitError(
    *,
    model_slug: str,
    max_tokens: int,
    provider_reason: str,
)

Bases: Exception

Raised when a provider exhausts the configured response-token budget.

Source code in src/stirrup/core/exceptions.py

def __init__(self, *, model_slug: str, max_tokens: int, provider_reason: str) -> None:
    self.model_slug = model_slug
    self.max_tokens = max_tokens
    self.provider_reason = provider_reason
    super().__init__(
        f"Model '{model_slug}' exhausted its configured output budget "
        f"(max_tokens={max_tokens}; provider reason: {provider_reason}). "
        "Increase max_tokens or ask the model for a shorter response."
    )