Buckets:

download
raw
15 kB
"""
Top-level error types for the effGen framework.
These are raised at runtime when a required system dependency or backend
is unavailable, so callers can catch them specifically and display helpful
messages rather than cryptic import errors.
Also holds the two helpers every error message in the framework composes
itself with: :func:`quote_for_message`, applied to text quoted from somewhere
else so it is redacted and cut to a bounded length, and
:func:`with_next_step`, which joins what happened to what to do about it.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from effgen.core.agent_response import AgentResponse, PartialResult
#: How much of a value produced elsewhere an error message quotes. A provider
#: echoes the rejected request back in its error body, a parser reports the
#: input it choked on, and an SDK wraps both — so an unbounded quote buries the
#: reason for the failure under kilobytes of payload in a terminal panel, a log
#: line, or an API envelope. Long enough to carry a provider's own sentence,
#: short enough to stay readable.
MESSAGE_ECHO_LIMIT = 240
def abbreviate_for_message(value: object, limit: int = MESSAGE_ECHO_LIMIT) -> str:
"""Return *value* as text, cut to *limit* characters and marked if cut.
Every error message that quotes text it did not produce — a provider error
body, a parser complaint, a rejected input — passes it through here first,
so no single message can grow without bound.
Args:
value: The value to quote. Anything not already a string is rendered
with ``str()``.
limit: How many characters to keep before cutting.
Returns:
The text unchanged when it fits, otherwise the first *limit*
characters followed by an ellipsis and the full length.
"""
text = str(value)
if len(text) <= limit:
return text
return f"{text[:limit]}… ({len(text)} characters)"
def redact_for_message(value: object) -> str:
"""Return *value* as text with any credential in it replaced by a marker.
Upstream error bodies echo parts of the request back, and some include the
submitted credential. Text that reaches an error message goes through here
so a key cannot travel into a log, a terminal panel or an API envelope.
Redaction never replaces the failure: if the redactor cannot be loaded, the
original text is returned rather than an error about redacting it.
Args:
value: The value to redact. Anything not already a string is rendered
with ``str()``.
Returns:
The text with every recognized credential replaced by a marker.
"""
text = str(value)
if not text:
return text
try:
# Imported here so the error types stay importable before the
# observability stack is built.
from effgen.observability.redact import get_redactor
return get_redactor().scrub(text)
except Exception: # noqa: BLE001 - redaction must not replace the error
return text
def quote_for_message(value: object, limit: int = MESSAGE_ECHO_LIMIT) -> str:
"""Return *value* ready to quote in an error message: redacted, then bound.
The single call every error message makes on text it did not produce. The
order matters — redacting first means a credential near the cut point is
replaced rather than half-printed.
Args:
value: The value to quote.
limit: How many characters to keep before cutting.
Returns:
The redacted text, cut to *limit* characters and marked if cut.
"""
return abbreviate_for_message(redact_for_message(value), limit)
#: Terminators that already end a sentence, so no period is added after them.
_SENTENCE_END = ".!?…"
def with_next_step(statement: object, next_step: str) -> str:
"""Join what happened to what to do about it, as two sentences.
The statement half is usually text from somewhere else — a provider error
body, a parser complaint — which may or may not punctuate itself. Joining
by hand produces either ``"...no.. Check"`` or ``"...no Check"`` depending
on the upstream, so every message that carries guidance joins here instead.
Args:
statement: What happened. Rendered with ``str()`` and stripped of
trailing whitespace and any separator left dangling at the end.
next_step: What the reader can do about it, already a sentence.
Returns:
The two joined by a single space, with exactly one terminator between
them. When *statement* is empty, *next_step* alone.
"""
head = str(statement).rstrip()
while head and head[-1] in ",;:":
head = head[:-1].rstrip()
if not head:
return next_step
if head[-1] not in _SENTENCE_END:
head += "."
return f"{head} {next_step}"
class EffGenError(Exception):
"""Base class for all effGen-specific errors."""
class MissingSystemDependency(EffGenError):
"""Raised when a required system-level binary is not found on PATH.
Attributes:
dependency: Name of the missing binary (e.g. "tesseract").
install_instructions: Per-OS install guidance.
"""
_DEFAULT_HINT = (
"Install it with the system package manager (apt, brew, choco or "
"conda), then re-run."
)
def __init__(self, dependency: str, install_instructions: str = "") -> None:
self.dependency = dependency
self.install_instructions = install_instructions
msg = f"System dependency '{dependency}' is not installed or not on PATH."
if install_instructions:
msg += f"\n\n{quote_for_message(install_instructions)}"
msg += f"\n\n{self._DEFAULT_HINT}"
super().__init__(msg)
class OCRBackendUnavailable(EffGenError):
"""Raised when no OCR backend (Tesseract or OCR.space) is available.
Attributes:
tried_backends: List of backend names that were checked.
"""
_DEFAULT_INSTALL = (
"Install Tesseract:\n"
" Ubuntu/Debian : sudo apt install tesseract-ocr\n"
" macOS : brew install tesseract\n"
" Windows : choco install tesseract\n"
" conda : conda install -c conda-forge tesseract\n\n"
"Or set OCR_SPACE_API_KEY to use the OCR.space cloud fallback."
)
def __init__(
self,
tried_backends: list[str] | None = None,
extra: str = "",
) -> None:
self.tried_backends = tried_backends or []
msg = "No OCR backend is available."
if self.tried_backends:
msg += f" Tried: {', '.join(self.tried_backends)}."
if extra:
msg += f"\n\n{quote_for_message(extra)}"
msg += f"\n\n{self._DEFAULT_INSTALL}"
super().__init__(msg)
class NoVisionProviderAvailable(EffGenError):
"""Raised when ImageCaptionTool cannot find a vision-capable provider.
Attributes:
tried_providers: List of provider names that were checked.
"""
_DEFAULT_HINT = (
"Configure a vision-capable provider:\n"
" OpenAI : set OPENAI_API_KEY (gpt-4o supports vision)\n"
" Google : set GOOGLE_API_KEY (gemini-2.5-flash-lite supports vision)\n"
" Replicate: set REPLICATE_API_TOKEN\n\n"
"Then pass the provider when creating ImageCaptionTool or use "
"the model router with Capability.vision."
)
def __init__(
self,
tried_providers: list[str] | None = None,
extra: str = "",
) -> None:
self.tried_providers = tried_providers or []
msg = "No vision-capable provider is configured."
if self.tried_providers:
msg += f" Tried: {', '.join(self.tried_providers)}."
if extra:
msg += f"\n\n{quote_for_message(extra)}"
msg += f"\n\n{self._DEFAULT_HINT}"
super().__init__(msg)
class CorruptDocumentError(EffGenError):
"""Raised when a document file is malformed or cannot be parsed.
Attributes:
doc_type: The document type that failed (e.g. 'pdf', 'docx', 'xlsx').
detail: Additional detail from the underlying parser.
"""
def __init__(self, doc_type: str, detail: str = "") -> None:
self.doc_type = doc_type
self.detail = detail
msg = f"Cannot parse {doc_type.upper()} document - file may be corrupt or invalid."
if detail:
msg += f"\nDetail: {quote_for_message(detail)}"
msg += (
"\n\nOpen the file in a reader to confirm it is intact, re-export "
"it, or pass a different document."
)
super().__init__(msg)
class CorruptStateError(EffGenError):
"""Raised when a persisted session or checkpoint file cannot be read.
The file is named explicitly so a user can find and fix (or delete) it
instead of seeing a raw ``JSONDecodeError`` stack trace.
Attributes:
kind: What was being loaded (e.g. 'session', 'checkpoint').
path: The file path that failed to parse.
detail: Underlying parser detail.
"""
def __init__(self, kind: str, path: str, detail: str = "") -> None:
self.kind = kind
self.path = path
self.detail = detail
msg = f"Cannot read {kind} file '{path}' - it is corrupt, truncated, or not valid JSON."
if detail:
msg += f"\nDetail: {quote_for_message(detail)}"
msg += "\n\nFix: inspect the file, restore a backup, or delete it to start fresh."
super().__init__(msg)
class MissingCredentialsError(EffGenError):
"""Raised when required credentials (env vars) are absent for a tool.
Attributes:
tool_name: The tool that needs credentials.
missing_vars: List of env var names that are missing.
"""
_DEFAULT_HINT = (
"Set {names} in the environment or in the project .env file, then "
"re-run."
)
def __init__(self, tool_name: str, missing_vars: list[str], hint: str = "") -> None:
self.tool_name = tool_name
self.missing_vars = missing_vars
names = ", ".join(missing_vars)
msg = (
f"{tool_name} requires credentials that are not configured: "
f"{names}."
)
if hint:
msg += f"\n\n{quote_for_message(hint)}"
msg += f"\n\n{self._DEFAULT_HINT.format(names=names)}"
super().__init__(msg)
class CapabilityNotSupportedError(EffGenError):
"""Raised when an adapter cannot handle a requested capability (e.g. vision, audio).
Attributes:
capability: The Capability enum value that is not supported.
provider: Name of the provider/adapter that raised this.
hint: Optional guidance on which provider to use instead.
"""
_DEFAULT_HINT = (
"Choose a model that declares this capability — run "
"`effgen models list --capability <name>` to see which do."
)
def __init__(self, capability: object, provider: str = "", hint: str = "") -> None:
capability_name = getattr(capability, "value", str(capability))
self.capability = capability_name
self.provider = provider
msg = f"Capability '{capability_name}' is not supported"
if provider:
msg += f" by provider '{provider}'"
msg += "."
if hint:
msg += f"\n\n{quote_for_message(hint)}"
msg += f"\n\n{self._DEFAULT_HINT}"
super().__init__(msg)
class InvalidMultimodalContent(EffGenError):
"""Raised when multimodal content (image, audio, video) fails validation.
Attributes:
part_type: The part type that failed (e.g. 'image', 'audio', 'video_frames').
reason: Description of the validation failure.
"""
def __init__(self, part_type: str, reason: str = "") -> None:
self.part_type = part_type
self.reason = reason
msg = f"Invalid {part_type} content"
if reason:
msg += f": {quote_for_message(reason)}"
super().__init__(
with_next_step(
msg,
f"Check that the {part_type} source is reachable and in a "
"supported format.",
)
)
class AudioBackendUnavailable(EffGenError):
"""Raised when no audio transcription backend is available.
Attributes:
tried_backends: List of backend names that were checked.
"""
_DEFAULT_INSTALL = (
"Install local transcription support:\n"
" pip install 'effgen[audio]'\n"
" Ubuntu/Debian : sudo apt install ffmpeg\n"
" macOS : brew install ffmpeg\n"
" Windows : choco install ffmpeg\n"
" conda : conda install -c conda-forge ffmpeg\n\n"
"Or set HF_TOKEN to use the HuggingFace Inference fallback."
)
def __init__(
self,
tried_backends: list[str] | None = None,
extra: str = "",
) -> None:
self.tried_backends = tried_backends or []
msg = "No audio transcription backend is available."
if self.tried_backends:
msg += f" Tried: {', '.join(self.tried_backends)}."
if extra:
msg += f"\n\n{quote_for_message(extra)}"
msg += f"\n\n{self._DEFAULT_INSTALL}"
super().__init__(msg)
class RunStoppedError(RuntimeError):
"""The loop stopped a run before the model wrote an answer.
Raised by ``Agent.run()`` under the default ``raise_on_error=True`` when a
run ends with ``outcome == "stopped"`` — the iteration cap, a repeated tool
call, a tool that reproduced its own result, or an empty final answer after
tools ran. The run made progress but never produced an answer, so there is
nothing to return in its place.
It subclasses :class:`RuntimeError`, which is what the iteration cap has
always raised, so ``except RuntimeError`` keeps catching it. What is new is
that the run comes with it: :attr:`response` is the full response and
:attr:`partial` is what the run had reached, so reading the progress is one
``except`` clause rather than a configuration change.
::
try:
print(agent.run(task).output)
except RunStoppedError as exc:
print(exc.stop_reason, exc.partial.text if exc.partial else "")
Attributes:
response: The :class:`~effgen.core.agent_response.AgentResponse` the run
produced, with ``success=False``.
stop_reason: What stopped the run, copied from the response.
partial: What the run had reached, or ``None`` when it had reached
nothing.
"""
def __init__(self, response: "AgentResponse") -> None:
super().__init__(response.output)
self.response = response
self.stop_reason: str | None = response.stop_reason
self.partial: "PartialResult | None" = response.partial

Xet Storage Details

Size:
15 kB
·
Xet hash:
c1d52b068e484cb2aa68127d52d8424028a34ff2259d63d031cab823a16c765f

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.