Core - rotalabs-audit
Description: Reasoning chain capture and decision transparency for AI systems

Skip to content

# Core Module

The `rotalabs_audit.core` module provides the foundational data types, configuration classes, and exceptions used throughout the rotalabs-audit package for reasoning chain capture and decision transparency.

## Types

Core data structures for representing reasoning chains, decision traces, and analysis results.

### ReasoningType

Classification enumeration for different kinds of reasoning steps.

#### `` `ReasoningType`

Bases: `str`, `Enum`

Classification of reasoning step types.

Used to categorize different kinds of reasoning that appear in AI model outputs, enabling analysis of reasoning patterns and detection of specific behaviors like evaluation awareness or strategic reasoning.

Attributes:

Name | Type | Description
--- | --- | ---
`EVALUATION_AWARE` |  | References to testing, evaluation, or monitoring context. Indicates the model may be aware it's being evaluated.
`GOAL_REASONING` |  | Goal-directed reasoning where the model explicitly considers objectives and how to achieve them.
`DECISION_MAKING` |  | Explicit decision points where the model chooses between alternatives.
`FACTUAL_KNOWLEDGE` |  | Factual statements or knowledge retrieval without significant inference.
`UNCERTAINTY` |  | Expressions of uncertainty, hedging, or acknowledgment of limitations.
`META_REASONING` |  | Meta-cognitive statements like "I think" or "I believe" that reflect on the reasoning process itself.
`INCENTIVE_REASONING` |  | Consideration of rewards, penalties, or other incentive structures.
`CAUSAL_REASONING` |  | Cause-and-effect reasoning, analyzing why things happen or predicting consequences.
`HYPOTHETICAL` |  | Counterfactual or "what if" reasoning exploring alternative scenarios.
`UNKNOWN` |  | Reasoning that doesn't fit other categories or couldn't be classified.

### ConfidenceLevel

Discrete confidence levels that map to numeric confidence scores.

#### `` `ConfidenceLevel`

Bases: `str`, `Enum`

Discrete confidence levels for reasoning assessments.

Provides human-readable confidence categories that map to numeric confidence scores, useful for reporting and thresholding.

Attributes:

Name | Type | Description
--- | --- | ---
`VERY_LOW` |  | Confidence score < 0.2. Very uncertain assessment.
`LOW` |  | Confidence score 0.2-0.4. Uncertain assessment.
`MEDIUM` |  | Confidence score 0.4-0.6. Moderate confidence.
`HIGH` |  | Confidence score 0.6-0.8. Confident assessment.
`VERY_HIGH` |  | Confidence score > 0.8. Highly confident assessment.

##### `` `from_score(score)` `classmethod`

Convert a numeric confidence score to a discrete level.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`score` | `float` | Confidence score between 0 and 1. | required

Returns:

Type | Description
--- | ---
`ConfidenceLevel` | The corresponding ConfidenceLevel.

Raises:

Type | Description
--- | ---
`ValueError` | If score is not between 0 and 1.

### ReasoningStep

A single step in a reasoning chain with classification and confidence.

#### `` `ReasoningStep` `dataclass`

A single step in a reasoning chain.

Represents an atomic unit of reasoning extracted from model output, including its classification, confidence assessment, and supporting evidence.

Attributes:

Name | Type | Description
--- | --- | ---
`content` | `str` | The text content of this reasoning step.
`reasoning_type` | `ReasoningType` | Classification of what kind of reasoning this represents.
`confidence` | `float` | Model's confidence in this step (0-1 scale).
`index` | `int` | Position of this step in the reasoning chain (0-indexed).
`evidence` | `Dict[str, List[str]]` | Dictionary mapping evidence types to lists of pattern matches or other supporting information.
`causal_importance` | `float` | How important this step is to the final decision (0-1 scale). Higher values indicate steps that significantly influenced the outcome.
`metadata` | `Dict[str, Any]` | Additional arbitrary metadata about this step.

Example

> > > step = ReasoningStep( ... content="Since the user asked for Python, I should use Python syntax", ... reasoning_type=ReasoningType.GOAL_REASONING, ... confidence=0.85, ... index=0, ... causal_importance=0.7 ... )

##### `` `confidence_level` `property`

Get the discrete confidence level for this step.

##### `` `__post_init__()`

Validate field values after initialization.

### ReasoningChain

A complete chain of reasoning steps from an AI model.

#### `` `ReasoningChain` `dataclass`

A complete chain of reasoning steps.

Represents a full reasoning trace from an AI model, potentially parsed into discrete steps with classifications. The chain maintains both the raw text and structured representation.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `str` | Unique identifier for this chain.
`steps` | `List[ReasoningStep]` | List of parsed reasoning steps in order.
`raw_text` | `str` | Original unparsed text of the reasoning.
`model` | `Optional[str]` | Name/identifier of the model that produced this reasoning.
`timestamp` | `datetime` | When this reasoning was captured.
`parsing_confidence` | `float` | Confidence in the quality of step parsing (0-1).
`metadata` | `Dict[str, Any]` | Additional arbitrary metadata about the chain.

Example

> > > chain = ReasoningChain( ... id="chain-001", ... steps=[step1, step2, step3], ... raw_text="First, I consider... Then, I decide...", ... model="gpt-4" ... ) chain.is_structured True chain.step_count 3

##### `` `is_structured` `property`

Check if this chain has been successfully parsed into steps.

Returns:

Type | Description
--- | ---
`bool` | True if the chain contains at least one parsed step.

##### `` `step_count` `property`

Get the number of reasoning steps in this chain.

Returns:

Type | Description
--- | ---
`int` | The count of parsed reasoning steps.

##### `` `average_confidence` `property`

Calculate the average confidence across all steps.

Returns:

Type | Description
--- | ---
`float` | Mean confidence score, or 0.0 if no steps exist.

##### `` `__post_init__()`

Validate field values after initialization.

##### `` `get_steps_by_type(reasoning_type)`

Filter steps by their reasoning type.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`reasoning_type` | `ReasoningType` | The type of reasoning to filter for. | required

Returns:

Type | Description
--- | ---
`List[ReasoningStep]` | List of steps matching the specified type, in order.

##### `` `get_high_importance_steps(threshold=0.5)`

Get steps with high causal importance.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`threshold` | `float` | Minimum causal importance to include (default 0.5). | `0.5`

Returns:

Type | Description
--- | ---
`List[ReasoningStep]` | List of steps with causal importance >= threshold, in order.

### DecisionTrace

Trace of a single decision point with context and rationale.

#### `` `DecisionTrace` `dataclass`

Trace of a single decision point.

Captures a specific decision made by an AI system, including the context, reasoning, alternatives considered, and potential consequences.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `str` | Unique identifier for this decision.
`decision` | `str` | The actual decision that was made (text description).
`timestamp` | `datetime` | When this decision was made.
`context` | `Dict[str, Any]` | Dictionary of contextual information relevant to the decision.
`reasoning_chain` | `Optional[ReasoningChain]` | Optional full reasoning chain leading to this decision.
`alternatives_considered` | `List[str]` | List of alternative decisions that were considered.
`rationale` | `str` | Explanation for why this decision was made.
`confidence` | `float` | Confidence in the decision (0-1 scale).
`reversible` | `bool` | Whether this decision can be undone.
`consequences` | `List[str]` | List of known or predicted consequences.
`metadata` | `Dict[str, Any]` | Additional arbitrary metadata.

Example

> > > trace = DecisionTrace( ... id="decision-001", ... decision="Use caching for API responses", ... timestamp=datetime.utcnow(), ... context={"request_volume": "high", "latency_requirement": "low"}, ... alternatives_considered=["No caching", "CDN caching"], ... rationale="High volume requires low latency responses", ... confidence=0.8 ... )

##### `` `confidence_level` `property`

Get the discrete confidence level for this decision.

##### `` `has_reasoning` `property`

Check if this decision has an associated reasoning chain.

##### `` `alternatives_count` `property`

Get the number of alternatives that were considered.

##### `` `__post_init__()`

Validate field values after initialization.

### DecisionPath

A sequence of related decisions tracking progress toward a goal.

#### `` `DecisionPath` `dataclass`

A sequence of related decisions.

Represents a series of connected decisions made in pursuit of a goal, enabling analysis of decision trajectories and identification of failure points.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `str` | Unique identifier for this path.
`decisions` | `List[DecisionTrace]` | Ordered list of decisions in the path.
`goal` | `str` | The objective these decisions were working toward.
`success` | `Optional[bool]` | Whether the goal was achieved (None if unknown/ongoing).
`failure_point` | `Optional[DecisionTrace]` | The decision where things went wrong, if applicable.
`metadata` | `Dict[str, Any]` | Additional arbitrary metadata.

Example

> > > path = DecisionPath( ... id="path-001", ... decisions=[decision1, decision2, decision3], ... goal="Complete user request accurately", ... success=True ... ) path.length 3

##### `` `length` `property`

Get the number of decisions in this path.

##### `` `is_complete` `property`

Check if the path has a known outcome.

##### `` `has_failure` `property`

Check if this path has an identified failure point.

##### `` `total_confidence` `property`

Calculate the product of all decision confidences.

Represents the overall confidence in the path, assuming independence between decisions.

Returns:

Type | Description
--- | ---
`float` | Product of confidences, or 1.0 if no decisions.

##### `` `get_decision_by_id(decision_id)`

Find a decision in the path by its ID.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`decision_id` | `str` | The ID of the decision to find. | required

Returns:

Type | Description
--- | ---
`Optional[DecisionTrace]` | The matching DecisionTrace, or None if not found.

### AwarenessAnalysis

Result of evaluation awareness detection analysis.

#### `` `AwarenessAnalysis` `dataclass`

Result of evaluation awareness detection.

Contains the results of analyzing whether an AI system appears to be aware that it's being evaluated, monitored, or tested, and whether it's adapting its behavior accordingly.

Attributes:

Name | Type | Description
--- | --- | ---
`is_evaluation_aware` | `bool` | Whether the system shows signs of evaluation awareness.
`awareness_score` | `float` | Numeric score (0-1) indicating degree of awareness.
`awareness_indicators` | `List[str]` | Specific textual indicators of awareness found.
`evaluation_signals` | `List[str]` | References to evaluation/testing context detected.
`behavioral_adaptation_indicators` | `List[str]` | Signs the system is adapting behavior based on perceived evaluation context.
`strategic_reasoning_score` | `float` | Score (0-1) for strategic/game-theoretic reasoning.
`confidence` | `float` | Confidence in this analysis (0-1).

Example

> > > analysis = AwarenessAnalysis( ... is_evaluation_aware=True, ... awareness_score=0.75, ... awareness_indicators=["reference to 'test'", "mention of 'evaluator'"], ... evaluation_signals=["this appears to be a test scenario"], ... behavioral_adaptation_indicators=["adjusted response style"], ... strategic_reasoning_score=0.6, ... confidence=0.85 ... )

##### `` `awareness_level` `property`

Get the discrete awareness level.

##### `` `indicator_count` `property`

Get the total number of awareness indicators found.

##### `` `__post_init__()`

Validate field values after initialization.

### QualityMetrics

Quality assessment metrics for reasoning chains.

#### `` `QualityMetrics` `dataclass`

Quality assessment of reasoning.

Provides a comprehensive quality assessment of a reasoning chain, evaluating multiple dimensions of reasoning quality.

Attributes:

Name | Type | Description
--- | --- | ---
`clarity` | `float` | How clear and understandable the reasoning is (0-1).
`completeness` | `float` | Whether all necessary steps are explained (0-1).
`consistency` | `float` | Absence of contradictions in the reasoning (0-1).
`logical_validity` | `float` | Whether inferences are logically sound (0-1).
`evidence_support` | `float` | Whether claims are backed by evidence (0-1).
`overall_score` | `float` | Composite quality score (0-1).
`depth` | `int` | Number of reasoning steps (indicates depth of analysis).
`breadth` | `int` | Number of alternatives considered.
`issues` | `List[str]` | List of identified quality issues.
`recommendations` | `List[str]` | Suggestions for improving reasoning quality.

Example

> > > metrics = QualityMetrics( ... clarity=0.8, ... completeness=0.7, ... consistency=0.9, ... logical_validity=0.85, ... evidence_support=0.6, ... overall_score=0.77, ... depth=5, ... breadth=3, ... issues=["Some claims lack supporting evidence"], ... recommendations=["Add citations for factual claims"] ... )

##### `` `quality_level` `property`

Get the discrete overall quality level.

##### `` `has_issues` `property`

Check if any quality issues were identified.

##### `` `issue_count` `property`

Get the number of identified issues.

##### `` `__post_init__()`

Validate field values after initialization.

##### `` `to_summary_dict()`

Create a summary dictionary of the metrics.

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dictionary with all metric values and counts.

## Configuration

Configuration classes for controlling parser, analysis, and tracing behavior.

### ParserConfig

Configuration for reasoning chain parsing.

#### `` `ParserConfig` `dataclass`

Configuration for reasoning chain parsing.

Controls how raw model outputs are parsed into structured reasoning chains, including pattern matching settings and output constraints.

Attributes:

Name | Type | Description
--- | --- | ---
`patterns_file` | `Optional[Path]` | Path to a YAML/JSON file containing custom patterns for identifying reasoning steps. If None, uses built-in patterns.
`min_confidence` | `float` | Minimum confidence threshold for including a parsed step. Steps below this threshold are discarded.
`max_steps` | `int` | Maximum number of steps to extract from a single chain. Prevents runaway parsing on very long outputs.
`step_separator_patterns` | `List[str]` | List of regex patterns that indicate boundaries between reasoning steps.
`include_raw_evidence` | `bool` | Whether to include raw pattern match strings in the evidence field of parsed steps.
`normalize_whitespace` | `bool` | Whether to normalize whitespace in parsed content (collapse multiple spaces, trim, etc.).
`preserve_formatting` | `bool` | Whether to preserve markdown/code formatting in step content.
`timeout_seconds` | `float` | Maximum time allowed for parsing a single chain. Prevents hanging on adversarial inputs.

Example

> > > config = ParserConfig( ... min_confidence=0.6, ... max_steps=20, ... include_raw_evidence=True ... )

##### `` `__post_init__()`

Validate configuration values.

### AnalysisConfig

Configuration for reasoning chain analysis features.

#### `` `AnalysisConfig` `dataclass`

Configuration for reasoning chain analysis.

Controls which analysis features are enabled and their parameters. Analysis includes evaluation awareness detection, quality assessment, and counterfactual reasoning analysis.

Attributes:

Name | Type | Description
--- | --- | ---
`enable_counterfactual` | `bool` | Whether to perform counterfactual analysis, examining what would happen if certain reasoning steps were different.
`enable_awareness` | `bool` | Whether to detect evaluation awareness, checking if the model appears to know it's being tested.
`enable_quality` | `bool` | Whether to compute quality metrics for reasoning chains.
`awareness_threshold` | `float` | Score threshold above which a chain is considered evaluation-aware.
`quality_weights` | `Dict[str, float]` | Dictionary of weights for different quality dimensions when computing overall score.
`counterfactual_depth` | `int` | How many alternative branches to explore in counterfactual analysis.
`use_llm_analysis` | `bool` | Whether to use an LLM for deeper analysis (requires API credentials).
`llm_model` | `Optional[str]` | Model identifier for LLM-based analysis.
`cache_results` | `bool` | Whether to cache analysis results for repeated calls on the same input.
`parallel_analysis` | `bool` | Whether to run independent analyses in parallel.

Example

> > > config = AnalysisConfig( ... enable_awareness=True, ... awareness_threshold=0.7, ... enable_quality=True ... )

##### `` `__post_init__()`

Validate configuration values.

### TracingConfig

Configuration for decision tracing and persistence.

#### `` `TracingConfig` `dataclass`

Configuration for decision tracing.

Controls how decisions are captured, tracked, and organized into decision paths during AI system operation.

Attributes:

Name | Type | Description
--- | --- | ---
`capture_alternatives` | `bool` | Whether to capture alternative decisions that were considered but not taken.
`max_trace_depth` | `int` | Maximum depth of nested decision traces. Prevents unbounded recursion in complex decision trees.
`max_path_length` | `int` | Maximum number of decisions in a single path.
`capture_context` | `bool` | Whether to capture contextual information at each decision point.
`context_keys` | `Optional[List[str]]` | Specific context keys to capture (if None, captures all).
`include_reasoning_chain` | `bool` | Whether to parse and include the full reasoning chain for each decision.
`track_consequences` | `bool` | Whether to track predicted and actual consequences of decisions.
`enable_timestamps` | `bool` | Whether to record precise timestamps for each decision.
`persistence_backend` | `Optional[str]` | Backend for persisting traces ("memory", "sqlite", "postgres", or None for no persistence).
`persistence_path` | `Optional[str]` | Path or connection string for persistence backend.
`auto_flush_interval` | `float` | Seconds between automatic flushes to persistence (0 disables auto-flush).

Example

> > > config = TracingConfig( ... capture_alternatives=True, ... max_trace_depth=10, ... include_reasoning_chain=True, ... persistence_backend="sqlite", ... persistence_path="./traces.db" ... )

##### `` `__post_init__()`

Validate configuration values.

### AuditConfig

Master configuration combining all audit-related settings.

#### `` `AuditConfig` `dataclass`

Master configuration combining all audit-related settings.

Provides a unified configuration object that contains parser, analysis, and tracing configurations, along with global settings.

Attributes:

Name | Type | Description
--- | --- | ---
`parser` | `ParserConfig` | Configuration for reasoning chain parsing.
`analysis` | `AnalysisConfig` | Configuration for reasoning analysis.
`tracing` | `TracingConfig` | Configuration for decision tracing.
`debug` | `bool` | Whether to enable debug mode with verbose logging.
`log_level` | `str` | Logging level ("DEBUG", "INFO", "WARNING", "ERROR").
`metadata` | `Dict[str, Any]` | Additional global metadata to include in all outputs.

Example

> > > config = AuditConfig( ... parser=ParserConfig(min_confidence=0.6), ... analysis=AnalysisConfig(enable_awareness=True), ... tracing=TracingConfig(capture_alternatives=True), ... debug=True ... )

##### `` `__post_init__()`

Validate configuration values.

##### `` `from_dict(data)` `classmethod`

Create an AuditConfig from a dictionary.

Useful for loading configuration from files or environment.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`data` | `Dict[str, Any]` | Dictionary containing configuration values. | required

Returns:

Type | Description
--- | ---
`AuditConfig` | Configured AuditConfig instance.

##### `` `to_dict()`

Convert this configuration to a dictionary.

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dictionary representation of the configuration.

## Exceptions

Custom exceptions for handling errors in parsing, analysis, tracing, and integrations.

### AuditError

Base exception for all rotalabs-audit errors.

#### `` `AuditError`

Bases: `Exception`

Base exception for all rotalabs-audit errors.

All exceptions raised by this package inherit from AuditError, allowing callers to catch all audit-related errors with a single except clause if desired.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`details` |  | Optional dictionary of additional error context.
`cause` |  | Optional underlying exception that caused this error.

Example

> > > try: ... raise AuditError("Something went wrong", details={"code": 42}) ... except AuditError as e: ... print(f"Error: {e.message}, Details: {e.details}") Error: Something went wrong, Details: {'code': 42}

##### `` `__init__(message, details=None, cause=None)`

Initialize an AuditError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`details` | `Optional[Dict[str, Any]]` | Optional dictionary of additional error context. | `None`
`cause` | `Optional[Exception]` | Optional underlying exception that caused this error. | `None`

##### `` `__repr__()`

Return a detailed string representation.

### ParsingError

Exception raised when parsing reasoning chains fails.

#### `` `ParsingError`

Bases: `AuditError`

Exception raised when parsing reasoning chains fails.

This exception is raised when the parser encounters problems extracting structured reasoning steps from raw model output, such as malformed input, unrecognized patterns, or timeout.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`raw_text` |  | The original text that failed to parse.
`partial_steps` |  | Any steps that were successfully parsed before failure.
`position` |  | Character position in raw_text where parsing failed.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise ParsingError( ... "Unexpected token", ... raw_text="malformed input...", ... position=15 ... ) ... except ParsingError as e: ... print(f"Parsing failed at position {e.position}")

##### `` `__init__(message, raw_text=None, partial_steps=None, position=None, details=None, cause=None)`

Initialize a ParsingError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`raw_text` | `Optional[str]` | The original text that failed to parse. | `None`
`partial_steps` | `Optional[List[Any]]` | Any steps successfully parsed before failure. | `None`
`position` | `Optional[int]` | Character position where parsing failed. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`

### AnalysisError

Exception raised when reasoning analysis fails.

#### `` `AnalysisError`

Bases: `AuditError`

Exception raised when reasoning analysis fails.

This exception is raised when analyzing a reasoning chain encounters problems, such as invalid chain structure, analysis timeout, or failures in quality assessment or awareness detection.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`chain_id` |  | Identifier of the chain being analyzed.
`analysis_type` |  | Type of analysis that failed (e.g., "quality", "awareness").
`partial_results` |  | Any results computed before failure.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise AnalysisError( ... "Quality assessment timed out", ... chain_id="chain-123", ... analysis_type="quality" ... ) ... except AnalysisError as e: ... print(f"Analysis '{e.analysis_type}' failed for {e.chain_id}")

##### `` `__init__(message, chain_id=None, analysis_type=None, partial_results=None, details=None, cause=None)`

Initialize an AnalysisError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`chain_id` | `Optional[str]` | Identifier of the chain being analyzed. | `None`
`analysis_type` | `Optional[str]` | Type of analysis that failed. | `None`
`partial_results` | `Optional[Dict[str, Any]]` | Any results computed before failure. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`

### TracingError

Exception raised when decision tracing fails.

#### `` `TracingError`

Bases: `AuditError`

Exception raised when decision tracing fails.

This exception is raised when capturing, storing, or retrieving decision traces encounters problems, such as persistence failures, depth limit exceeded, or invalid trace structure.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`trace_id` |  | Identifier of the trace involved.
`operation` |  | The operation that failed (e.g., "capture", "store", "retrieve").
`depth` |  | Current trace depth when error occurred.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise TracingError( ... "Maximum trace depth exceeded", ... trace_id="trace-456", ... operation="capture", ... depth=25 ... ) ... except TracingError as e: ... print(f"Tracing failed during {e.operation} at depth {e.depth}")

##### `` `__init__(message, trace_id=None, operation=None, depth=None, details=None, cause=None)`

Initialize a TracingError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`trace_id` | `Optional[str]` | Identifier of the trace involved. | `None`
`operation` | `Optional[str]` | The operation that failed. | `None`
`depth` | `Optional[int]` | Current trace depth when error occurred. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`

### IntegrationError

Exception raised when integration with external systems fails.

#### `` `IntegrationError`

Bases: `AuditError`

Exception raised when integration with external systems fails.

This exception is raised when interacting with external components like LLM APIs, databases, or other rotalabs packages encounters problems.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`integration_name` |  | Name of the integration that failed.
`endpoint` |  | API endpoint or connection string involved.
`request_data` |  | Data that was being sent (sanitized).
`response_data` |  | Any response received before failure.
`status_code` |  | HTTP status code if applicable.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise IntegrationError( ... "API request failed", ... integration_name="openai", ... endpoint="https://api.openai.com/v1/chat", ... status_code=429 ... ) ... except IntegrationError as e: ... print(f"Integration '{e.integration_name}' failed: {e.status_code}")

##### `` `is_rate_limited` `property`

Check if this error indicates rate limiting (HTTP 429).

##### `` `is_auth_error` `property`

Check if this error indicates authentication failure (HTTP 401/403).

##### `` `is_server_error` `property`

Check if this error indicates a server-side failure (HTTP 5xx).

##### `` `__init__(message, integration_name=None, endpoint=None, request_data=None, response_data=None, status_code=None, details=None, cause=None)`

Initialize an IntegrationError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`integration_name` | `Optional[str]` | Name of the integration that failed. | `None`
`endpoint` | `Optional[str]` | API endpoint or connection string involved. | `None`
`request_data` | `Optional[Dict[str, Any]]` | Data that was being sent (should be sanitized). | `None`
`response_data` | `Optional[Dict[str, Any]]` | Any response received before failure. | `None`
`status_code` | `Optional[int]` | HTTP status code if applicable. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`

### ValidationError

Exception raised when input validation fails.

#### `` `ValidationError`

Bases: `AuditError`

Exception raised when input validation fails.

This exception is raised when input data doesn't meet expected constraints, such as invalid configuration values, malformed data structures, or out-of-range parameters.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`field_name` |  | Name of the field that failed validation.
`expected` |  | Description of expected value/format.
`actual` |  | The actual value that was provided.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise ValidationError( ... "Confidence out of range", ... field_name="confidence", ... expected="0.0 to 1.0", ... actual=1.5 ... ) ... except ValidationError as e: ... print(f"Field '{e.field_name}': expected {e.expected}, got {e.actual}")

##### `` `__init__(message, field_name=None, expected=None, actual=None, details=None, cause=None)`

Initialize a ValidationError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`field_name` | `Optional[str]` | Name of the field that failed validation. | `None`
`expected` | `Optional[str]` | Description of expected value/format. | `None`
`actual` | `Optional[Any]` | The actual value that was provided. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`

### TimeoutError

Exception raised when an operation times out.

#### `` `TimeoutError`

Bases: `AuditError`

Exception raised when an operation times out.

This exception is raised when parsing, analysis, or other operations exceed their configured time limits.

Attributes:

Name | Type | Description
--- | --- | ---
`message` |  | Human-readable error description.
`operation` |  | The operation that timed out.
`timeout_seconds` |  | The timeout limit that was exceeded.
`elapsed_seconds` |  | How long the operation ran before timeout.
`details` |  | Additional error context.
`cause` |  | Underlying exception if applicable.

Example

> > > try: ... raise TimeoutError( ... "Parsing timed out", ... operation="parse_chain", ... timeout_seconds=30.0, ... elapsed_seconds=30.5 ... ) ... except TimeoutError as e: ... print(f"Operation '{e.operation}' exceeded {e.timeout_seconds}s limit")

##### `` `__init__(message, operation=None, timeout_seconds=None, elapsed_seconds=None, details=None, cause=None)`

Initialize a TimeoutError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Human-readable error description. | required
`operation` | `Optional[str]` | The operation that timed out. | `None`
`timeout_seconds` | `Optional[float]` | The timeout limit that was exceeded. | `None`
`elapsed_seconds` | `Optional[float]` | How long the operation ran before timeout. | `None`
`details` | `Optional[Dict[str, Any]]` | Additional error context. | `None`
`cause` | `Optional[Exception]` | Underlying exception if applicable. | `None`