Skip to content

models

models

Data models for error classification.

Contains the dataclass models used throughout the error handling system.

This module provides: - ParsedCliError: Structured error from CLI JSON output - ErrorInfo: Machine-readable error metadata (Google AIP-193 inspired) - ClassifiedError: Single error with classification and metadata - ErrorChain: Error chain from symptom to root cause - ClassificationResult: Multi-error result with root cause identification

Classes

ClassificationInput dataclass 

ClassificationInput(stdout='', stderr='', exit_code=None, exit_signal=None, exit_reason=None, exception=None, output_format=None)

Bundled inputs for ErrorClassifier.classify_execution().

Groups the execution result fields that the classifier needs, reducing the method's parameter count from 8 to 2 (self + input). Callers can still pass individual keyword arguments for backward compatibility.

ParsedCliError dataclass 

ParsedCliError(error_type, message, tool_name=None, metadata=dict())

A single error extracted from CLI JSON output.

Claude CLI returns structured JSON with an errors[] array: 

{
  "result": "...",
  "errors": [
    {"type": "system", "message": "Rate limit exceeded"},
    {"type": "user", "message": "spawn claude ENOENT"}
  ],
  "cost_usd": 0.05
}

This dataclass represents one item from that array.

Attributes:

Name Type Description
error_type Literal['system', 'user', 'tool']

Error type from CLI: "system", "user", "tool".
message str

Human-readable error message.
tool_name str | None

For tool errors, the name of the failed tool.
metadata dict[str, Any]

Additional structured metadata from the error.
Attributes
error_type instance-attribute 
error_type

Error type from CLI: "system", "user", "tool".

message instance-attribute 
message

Human-readable error message.

tool_name class-attribute instance-attribute 
tool_name = None

For tool errors, the name of the failed tool.

metadata class-attribute instance-attribute 
metadata = field(default_factory=dict)

Additional structured metadata.

ErrorInfo dataclass 

ErrorInfo(reason, domain, metadata=dict())

Machine-readable error identification (Google AIP-193 inspired).

Provides structured metadata for programmatic error handling.

Example: 

error_info = ErrorInfo(
    reason="BINARY_NOT_FOUND",
    domain="marianne.backend.claude_cli",
    metadata={
        "expected_binary": "claude",
        "search_path": "/usr/bin:/usr/local/bin",
        "suggestion": "Ensure claude CLI is installed and in PATH",
    }
)

Attributes:

Name Type Description
reason str

UPPER_SNAKE_CASE identifier for the specific error reason.
domain str

Service/component identifier (e.g., "marianne.backend.claude_cli").
metadata dict[str, str]

Dynamic contextual information as key-value pairs.
Attributes
reason instance-attribute 
reason

UPPER_SNAKE_CASE identifier for the specific error reason. Example: "RATE_LIMIT_EXCEEDED", "BINARY_NOT_FOUND"

domain instance-attribute 
domain

Service/component identifier. Example: "marianne.backend.claude_cli", "marianne.execution"

metadata class-attribute instance-attribute 
metadata = field(default_factory=dict)

Dynamic contextual information. Example: {"binary_path": "/usr/bin/claude", "exit_code": "127"}

ClassifiedError dataclass 

ClassifiedError(category, message, error_code=UNKNOWN, original_error=None, exit_code=None, exit_signal=None, exit_reason=None, retriable=True, suggested_wait_seconds=None, error_info=None)

An error with its classification and metadata.

ClassifiedError combines high-level category (for retry logic) with specific error codes (for diagnostics and logging). The error_code provides stable identifiers for programmatic handling while category determines retry behavior.

Attributes
error_info class-attribute instance-attribute 
error_info = None

Optional structured metadata for this error.

is_signal_kill property 
is_signal_kill

True if process was killed by a signal.

signal_name property 
signal_name

Human-readable signal name if killed by signal.

code property 
code

Get the error code string value (e.g., 'E001').

severity property 
severity

Get the severity level for this error.

ErrorChain dataclass 

ErrorChain(errors, root_cause, symptoms=list(), confidence=1.0)

Represents a chain of errors from symptom to root cause.

When multiple errors occur, this class helps identify the actual root cause vs symptoms. For example, if ENOENT and rate limit both appear, ENOENT is likely the root cause (missing binary prevents any operation).

Attributes:

Name Type Description
errors list[ClassifiedError]

All errors in order of detection (first = earliest).
root_cause ClassifiedError

The error identified as the most fundamental cause.
symptoms list[ClassifiedError]

Errors that are likely consequences of the root cause.
confidence float

0.0-1.0 confidence in root cause identification.
Attributes
errors instance-attribute 
errors

All errors in order of detection (first = earliest).

root_cause instance-attribute 
root_cause

The error identified as the most fundamental cause.

symptoms class-attribute instance-attribute 
symptoms = field(default_factory=list)

Errors that are likely consequences of the root cause.

confidence class-attribute instance-attribute 
confidence = 1.0

0.0-1.0 confidence in root cause identification.

ClassificationResult dataclass 

ClassificationResult(primary, secondary=list(), raw_errors=list(), confidence=1.0, classification_method='structured')

Complete classification result with root cause and context.

This is the new result type from the classifier, providing access to all detected errors while maintaining backward compatibility through the primary attribute.

Example: 

# New code - returns ClassificationResult
classification = classifier.classify(stdout, stderr, exit_code)
result = classification.primary  # Backward compatible

# Access all errors
for error in classification.all_errors:
    log.info(f"Error: {error.error_code.value} - {error.message}")

Attributes:

Name Type Description
primary ClassifiedError

The identified root cause error.
secondary list[ClassifiedError]

Secondary/symptom errors for debugging.
raw_errors list[ParsedCliError]

Original parsed errors from CLI JSON.
confidence float

0.0-1.0 confidence in root cause identification.
classification_method str

How classification was done.
Attributes
primary instance-attribute 
primary

The identified root cause error.

secondary class-attribute instance-attribute 
secondary = field(default_factory=list)

Secondary/symptom errors for debugging.

raw_errors class-attribute instance-attribute 
raw_errors = field(default_factory=list)

Original parsed errors from CLI JSON.

confidence class-attribute instance-attribute 
confidence = 1.0

0.0-1.0 confidence in root cause identification.

classification_method class-attribute instance-attribute 
classification_method = 'structured'

How classification was done: "structured", "exit_code", "regex_fallback".

all_errors property 
all_errors

All errors including primary and secondary.

error_codes property 
error_codes

All error codes for logging/metrics.

category property 
category

Category of the primary error (backward compatibility).

message property 
message

Message of the primary error (backward compatibility).

error_code property 
error_code

Error code of the primary error (backward compatibility).

retriable property 
retriable

Whether the primary error is retriable (backward compatibility).

should_retry property 
should_retry

Whether to retry based on primary error (backward compatibility).

Functions
to_error_chain 
to_error_chain()

Convert to ErrorChain for detailed analysis.

Source code in src/marianne/core/errors/models.py 
301
302
303
304
305
306
307
308
def to_error_chain(self) -> ErrorChain:
    """Convert to ErrorChain for detailed analysis."""
    return ErrorChain(
        errors=self.all_errors,
        root_cause=self.primary,
        symptoms=self.secondary,
        confidence=self.confidence,
    )