Exceptions

Talu exceptions

Classes

Class Description
TaluError Base exception for all talu errors.
GenerationError Error during text generation.
EmptyPromptError Empty prompt provided to a model without a BOS token.
ModelError Error loading or using a model.
ModelNotFoundError Model path does not exist or is invalid.
TokenizerError Error during tokenization.
TemplateError Base error for template operations.
TemplateSyntaxError Invalid template syntax.
TemplateUndefinedError Undefined variable accessed in strict mode.
TemplateNotFoundError Template file not found.
ConvertError Raised when model conversion fails.
IOError I/O and network errors.
ResourceError System resource exhaustion error.
InteropError DLPack/NumPy interop errors.
StateError Invalid object state error.
StorageError Storage backend operation failed.
ValidationError Invalid parameter value.
StructuredOutputError Base class for all structured output errors.
IncompleteJSONError Generation truncated before JSON was complete.
SchemaValidationError JSON is syntactically valid but fails schema hydration/va...
GrammarError Grammar constraint violation.
StreamingValidationError Streaming JSON validation failed.

class TaluError

TaluError(
    self,
    message: str,
    code: str = 'INTERNAL_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Base exception for all talu errors.

Attributes
message : str

Human-readable error description.

code : str

Stable, string-based error code (e.g., "MODEL_NOT_FOUND"). Use this for programmatic error handling.

details : dict[str, Any]

Structured context (e.g., {"path": "...", "expected": [...]}}).

original_code : int | None

The internal Zig integer code (for debugging/logging).

Example
>>> try:
...     talu.generate("nonexistent/model", "Hello")
... except talu.TaluError as e:
...     print(f"Error code: {e.code}")
...     print(f"Details: {e.details}")
Error code: MODEL_NOT_FOUND
Details: {'path': 'nonexistent/model'}

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class GenerationError

GenerationError(
    self,
    message: str,
    code: str = 'GENERATION_FAILED',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Error during text generation.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class EmptyPromptError

EmptyPromptError(
    self,
    message: str | None = None,
    code: str = 'GENERATION_EMPTY_PROMPT',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Empty prompt provided to a model without a BOS token.

Some models (like Qwen) don't have a beginning-of-sequence (BOS) token, so they require at least one token in the prompt to start generation.

Solutions
  • Provide a non-empty prompt
  • Use chat=True to apply the chat template (adds tokens)
  • Use a model with a BOS token

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class ModelError

ModelError(
    self,
    message: str,
    code: str = 'MODEL_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Error loading or using a model.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class ModelNotFoundError

ModelNotFoundError(
    self,
    message: str,
    code: str = 'MODEL_NOT_FOUND',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Model path does not exist or is invalid.

Raised when the specified model path doesn't exist or the HuggingFace model ID cannot be resolved.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class TokenizerError

TokenizerError(
    self,
    message: str,
    code: str = 'TOKENIZER_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Error during tokenization.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class TemplateError

TemplateError(
    self,
    message: str,
    code: str = 'TEMPLATE_RENDER_FAILED',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Base error for template operations.

This exception (or its subclasses) is raised when template rendering fails.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class TemplateSyntaxError

TemplateSyntaxError(
    self,
    message: str,
    code: str = 'TEMPLATE_SYNTAX_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Invalid template syntax.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class TemplateUndefinedError

TemplateUndefinedError(
    self,
    message: str,
    code: str = 'TEMPLATE_UNDEFINED_VAR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Undefined variable accessed in strict mode.

Raised when a template uses a variable that wasn't provided and strict=True was set. In non-strict mode (default), undefined variables silently render as empty strings.

Solutions
  • Provide the missing variable
  • Use | default(value) filter for optional variables
  • Use strict=False (default) if empty strings are acceptable

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class TemplateNotFoundError

TemplateNotFoundError(
    self,
    message: str,
    code: str = 'TEMPLATE_NOT_FOUND',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Template file not found.

Raised when
  • A model doesn't have a chat_template in tokenizer_config.json
  • No chat_template.jinja file exists in the model directory
  • Template.from_file() is given a non-existent path

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class ConvertError

ConvertError(
    self,
    message: str,
    code: str = 'CONVERT_FAILED',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Raised when model conversion fails.

This exception is raised when the conversion process encounters an error, such as:

The exception message contains details about what went wrong.

Examples
>>> try:
...     talu.convert("nonexistent/model", bits=4)
... except talu.ConvertError as e:
...     print(f"Conversion failed: {e}")
Conversion failed: Model not found

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class IOError

IOError(
    self,
    message: str,
    code: str = 'IO_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

I/O and network errors.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class ResourceError

ResourceError(
    self,
    message: str,
    code: str = 'RESOURCE_EXHAUSTED',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

System resource exhaustion error.

This error is distinct from OutOfMemory in that it may occur during memory-mapped file access when pages cannot be faulted in due to system memory pressure.

Solutions
  • Reduce parallel test workers (pytest -n 2 instead of -n auto)
  • Close unused model/tokenizer instances
  • Use smaller models or reduce batch sizes
  • Increase system memory or swap space
Example
>>> try:
...     # Loading many models in parallel
...     tokenizers = [Tokenizer(model) for model in models]
... except talu.ResourceError as e:
...     print(f"Resource exhaustion: {e}")
...     print("Try reducing parallelism or closing unused instances")

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class InteropError

InteropError(
    self,
    message: str,
    code: str = 'INTEROP_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

DLPack/NumPy interop errors.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class StateError

StateError(
    self,
    message: str,
    code: str = 'STATE_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Invalid object state error.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class StorageError

StorageError(
    self,
    message: str,
    code: str = 'STORAGE_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Storage backend operation failed.

Raised when a storage operation fails during fork/clone operations. The items may still exist in memory, but were not persisted to storage.

This error indicates that
  • The in-memory chat state is valid and usable
  • The storage backend failed to persist the data
  • On restart, unpersisted items will be lost
Common causes
  • Database full or unavailable
  • Network timeout to remote storage
  • Transaction rollback in storage backend
  • Storage backend raised an exception in on_event()

The fork operation succeeded in memory but the storage layer failed. You can continue using the chat, but data is not persisted.

Example
>>> try:
...     forked = chat.fork()
... except talu.StorageError as e:
...     # Fork succeeded in memory, but storage failed
...     print(f"Storage error: {e}")
...     # Option 1: Continue with unpersisted fork
...     # forked = e.details.get("chat")
...     # Option 2: Retry or handle failure

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class ValidationError

ValidationError(
    self,
    message: str,
    code: str = 'INVALID_ARGUMENT',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Invalid parameter value.

Raised when a function receives an argument of the correct type but an inappropriate value (e.g., bits=3 when only 4, 8, 16 are valid).

This exception inherits from both TaluError and ValueError, so both work:

except talu.TaluError:   # catches all talu errors
except ValueError:       # catches validation errors (Pythonic)
Example
>>> talu.convert("model", bits=3)
ValidationError: bits must be 4, 5, 6, 8, or 16, got 3

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class StructuredOutputError

StructuredOutputError(
    self,
    message: str,
    code: str = 'STRUCTURED_OUTPUT_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Base class for all structured output errors.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class IncompleteJSONError

IncompleteJSONError(
    self,
    partial_text: str,
    finish_reason: str,
    code: str = 'INCOMPLETE_JSON',
    original_code: int | None = None
)

Generation truncated before JSON was complete.

Raised when max_tokens is reached mid-generation and the JSON structure is incomplete. The partial output may be recoverable.

Attributes
partial_text

The incomplete JSON string

finish_reason

Why generation stopped ("length")

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class SchemaValidationError

SchemaValidationError(
    self,
    raw_text: str,
    validation_error: Exception,
    code: str = 'SCHEMA_VALIDATION_FAILED',
    original_code: int | None = None
)

JSON is syntactically valid but fails schema hydration/validation.

The grammar enforced structure, but semantic validators failed.

Common causes
  • Dataclass missing required fields
  • Type mismatches in nested fields

This exception enables DATA SALVAGE - the user can access the valid JSON data that was generated, even though hydration failed.

Attributes
raw_text

The generated JSON string

partial_data

Parsed dict (always available for salvage)

validation_error

The underlying hydration/validation error

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class GrammarError

GrammarError(
    self,
    message: str,
    code: str = 'GRAMMAR_ERROR',
    details: dict[str, Any] | None = None,
    original_code: int | None = None
)

Grammar constraint violation.

This indicates a bug in the grammar engine - should never happen in production. If you see this error, please report it.

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.

class StreamingValidationError

StreamingValidationError(
    self,
    position: int,
    invalid_byte: bytes,
    expected: str,
    context: str = '',
    code: str = 'STREAMING_VALIDATION_FAILED',
    original_code: int | None = None
)

Streaming JSON validation failed.

Raised when Validator.feed(chunk, strict=True) encounters invalid data. Provides rich diagnostics including the invalid byte, its position, and what bytes would have been valid at that position.

This exception enables immediate debugging without manual buffer inspection:

Attributes
position : int

Byte offset in the stream where validation failed.

invalid_byte : bytes

The single byte that was rejected.

expected : str

Human-readable description of what was expected (e.g., "digit, quote").

context : str

Surrounding bytes for visual debugging (e.g., '..."age": X...').

Example
>>> validator = Validator(schema)
>>> try:
...     validator.feed('{"age": "five"}', strict=True)
... except StreamingValidationError as e:
...     print(f"Position: {e.position}")
...     print(f"Invalid: {e.invalid_byte!r}")
...     print(f"Expected: {e.expected}")
Position: 8
Invalid: b'"'
Expected: digit, minus sign

Quick Reference

Methods

Method Description
add_note() Add a note to the exception
with_traceback() Set self.traceback to tb and return self.

Methods

def add_note(self, note)

Add a note to the exception

def with_traceback(self, tb)

Set self.__traceback__ to tb and return self.