Skip to content

API_SPECIFICATION.md

Latest commit

 

History

History
497 lines (336 loc) · 15.9 KB

API_SPECIFICATION.md

File metadata and controls

497 lines (336 loc) · 15.9 KB

Exceptions - API Specification

Introduction

This document specifies the Application Programming Interface (API) for the Exceptions module. This module provides a comprehensive, hierarchical error handling system for the entire Codomyrmex ecosystem. All exceptions inherit from a single root class (CodomyrmexError) and are organized into domain-specific categories across 12 source files.

Endpoints / Functions / Interfaces

Class: CodomyrmexError

  • Description: The root exception class for all Codomyrmex-related errors. Provides a consistent interface with structured context information, error codes, and serialization support. All other project exceptions inherit from this class.
  • Module: codomyrmex.exceptions.base
  • Inherits: Exception
  • Parameters/Arguments (constructor):
    • message (str): The error message
    • context (dict[str, Any] | None, optional): Additional context information about the error. Defaults to {}
    • error_code (str | None, optional): A unique error code. Defaults to the class name
    • **kwargs (Any): Additional keyword arguments merged into context
  • Attributes:
    • message (str): The error message
    • context (dict[str, Any]): Structured context dictionary
    • error_code (str): Error code identifier (defaults to class name)
  • Methods:
    • __str__() -> str: Returns formatted string [error_code] message (Context: key=value, ...).
    • to_dict() -> dict[str, Any]: Serializes the exception to a dictionary with keys error_type, error_code, message, and context.

Function: format_exception_chain(exception: Exception) -> str

  • Description: Formats an exception chain for display, walking the __cause__ and __context__ chain and returning a newline-separated string of formatted error messages.
  • Module: codomyrmex.exceptions.base
  • Parameters/Arguments:
    • exception (Exception): The exception to format
  • Returns/Response: str - A formatted string representation of the full exception chain.

Function: create_error_context(**kwargs: Any) -> dict[str, Any]

  • Description: Utility function to create a context dictionary for exception handling. Filters out None values automatically.
  • Module: codomyrmex.exceptions.base
  • Parameters/Arguments:
    • **kwargs (Any): Key-value pairs to include in the context
  • Returns/Response: dict[str, Any] - A dictionary with all non-None values.

Exception Categories

Configuration and Setup (config.py)

ConfigurationError

  • Inherits: CodomyrmexError
  • Description: Raised when there is an issue with configuration settings.
  • Additional Parameters:
    • config_key (str | None, optional): The configuration key that caused the error
    • config_file (str | Path | None, optional): Path to the configuration file

EnvironmentError

  • Inherits: CodomyrmexError
  • Description: Raised when the environment is not properly set up.

DependencyError

  • Inherits: CodomyrmexError
  • Description: Raised when a required dependency is missing or incompatible.

File and I/O (io.py)

FileOperationError

  • Inherits: CodomyrmexError
  • Description: Raised when file operations fail.
  • Additional Parameters:
    • file_path (str | Path | None, optional): Path to the file that caused the error

DirectoryError

  • Inherits: CodomyrmexError
  • Description: Raised when directory operations fail.

AI and Code Generation (ai.py)

AIProviderError

  • Inherits: CodomyrmexError
  • Description: Raised when AI provider operations fail.

CodeGenerationError

  • Inherits: CodomyrmexError
  • Description: Raised when code generation fails.

CodeEditingError

  • Inherits: CodomyrmexError
  • Description: Raised when code editing operations fail.

ModelContextError

  • Inherits: CodomyrmexError
  • Description: Raised when model context protocol operations fail.

Analysis (analysis.py)

StaticAnalysisError

  • Inherits: CodomyrmexError
  • Description: Raised when static analysis operations fail.

PatternMatchingError

  • Inherits: CodomyrmexError
  • Description: Raised when pattern matching operations fail.

SecurityAuditError

  • Inherits: CodomyrmexError
  • Description: Raised when security audit operations fail.

Execution and Build (execution.py)

CodeExecutionError

  • Inherits: CodomyrmexError
  • Description: Raised when code execution fails.
  • Additional Parameters:
    • exit_code (int | None, optional): Process exit code
    • stdout (str | None, optional): Captured standard output
    • stderr (str | None, optional): Captured standard error

SandboxError

  • Inherits: CodomyrmexError
  • Description: Raised when sandbox operations fail.

ContainerError

  • Inherits: CodomyrmexError
  • Description: Raised when container operations fail.

BuildError

  • Inherits: CodomyrmexError
  • Description: Raised when build operations fail.

SynthesisError

  • Inherits: CodomyrmexError
  • Description: Raised when code synthesis operations fail.

Git and Version Control (git.py)

GitOperationError

  • Inherits: CodomyrmexError
  • Description: Raised when git operations fail.
  • Additional Parameters:
    • git_command (str | None, optional): The git command that failed
    • repository_path (str | Path | None, optional): Path to the repository

RepositoryError

  • Inherits: CodomyrmexError
  • Description: Raised when repository operations fail.

Visualization and Documentation (viz.py)

VisualizationError

  • Inherits: CodomyrmexError
  • Description: Raised when data visualization operations fail.

PlottingError

  • Inherits: CodomyrmexError
  • Description: Raised when plotting operations fail.

DocumentationError

  • Inherits: CodomyrmexError
  • Description: Raised when documentation operations fail.

APIDocumentationError

  • Inherits: CodomyrmexError
  • Description: Raised when API documentation generation fails.

Orchestration (orchestration.py)

OrchestrationError

  • Inherits: CodomyrmexError
  • Description: Raised when orchestration operations fail.

WorkflowError

  • Inherits: CodomyrmexError
  • Description: Raised when workflow execution fails.

ProjectManagementError

  • Inherits: CodomyrmexError
  • Description: Raised when project management operations fail.

TaskExecutionError

  • Inherits: CodomyrmexError
  • Description: Raised when task execution fails.

Network, API, and Validation (network.py)

NetworkError

  • Inherits: CodomyrmexError
  • Description: Raised when network operations fail.
  • Additional Parameters:
    • url (str | None, optional): The URL that caused the error
    • status_code (int | None, optional): HTTP status code

APIError

  • Inherits: CodomyrmexError
  • Description: Raised when API operations fail.

ValidationError

  • Inherits: CodomyrmexError
  • Description: Raised when data validation fails.
  • Additional Parameters:
    • field_name (str | None, optional): The field that failed validation
    • validation_rule (str | None, optional): The rule that was violated

SchemaError

  • Inherits: CodomyrmexError
  • Description: Raised when schema validation fails.

TimeoutError

  • Inherits: CodomyrmexError
  • Description: Raised when operations timeout.
  • Additional Parameters:
    • timeout_seconds (float | None, optional): The timeout duration that was exceeded

CEREBRUM (cerebrum.py)

CerebrumError

  • Inherits: CodomyrmexError
  • Description: Base exception class for all CEREBRUM cognitive system errors.

CaseError

  • Inherits: CerebrumError
  • Description: Exception raised for case-related errors.

CaseNotFoundError

  • Inherits: CaseError
  • Description: Exception raised when a case is not found.

InvalidCaseError

  • Inherits: CaseError
  • Description: Exception raised when a case is invalid.

BayesianInferenceError

  • Inherits: CerebrumError
  • Description: Exception raised for Bayesian inference errors.

InferenceError

  • Inherits: BayesianInferenceError
  • Description: Exception raised when inference fails.

NetworkStructureError

  • Inherits: BayesianInferenceError
  • Description: Exception raised when Bayesian network structure is invalid.

ActiveInferenceError

  • Inherits: CerebrumError
  • Description: Exception raised for active inference errors.

ModelError

  • Inherits: CerebrumError
  • Description: Exception raised for model-related errors.

TransformationError

  • Inherits: CerebrumError
  • Description: Exception raised for model transformation errors.

Specialized Domain Exceptions (specialized.py)

Performance and Monitoring

  • PerformanceError (inherits CodomyrmexError): Raised when performance monitoring operations fail.
  • LoggingError (inherits CodomyrmexError): Raised when logging operations fail.

System Discovery

  • SystemDiscoveryError (inherits CodomyrmexError): Raised when system discovery operations fail.
  • CapabilityScanError (inherits CodomyrmexError): Raised when capability scanning fails.

3D Modeling and Physical Management

  • Modeling3DError (inherits CodomyrmexError): Raised when 3D modeling operations fail.
  • PhysicalManagementError (inherits CodomyrmexError): Raised when physical management operations fail.
  • SimulationError (inherits CodomyrmexError): Raised when simulation operations fail.

Terminal and Interface

  • TerminalError (inherits CodomyrmexError): Raised when terminal interface operations fail.
  • InteractiveShellError (inherits CodomyrmexError): Raised when interactive shell operations fail.

Database

  • DatabaseError (inherits CodomyrmexError): Raised when database operations fail.

CI/CD and Deployment

  • CICDError (inherits CodomyrmexError): Raised when CI/CD operations fail.
  • DeploymentError (inherits CodomyrmexError): Raised when deployment operations fail.

Resources and Memory

  • ResourceError (inherits CodomyrmexError): Raised when resource operations fail.
  • MemoryError (inherits CodomyrmexError): Raised when memory-related errors occur.

Spatial and Events

  • SpatialError (inherits CodomyrmexError): Raised when spatial operations fail.
  • EventError (inherits CodomyrmexError): Raised when event processing fails.

Skills and Templates

  • SkillError (inherits CodomyrmexError): Raised when skill execution fails.
  • TemplateError (inherits CodomyrmexError): Raised when template operations fail.

Plugins

  • PluginError (inherits CodomyrmexError): Raised when plugin operations fail.
  • Additional Parameters:
    • plugin_name (str | None, optional): Name of the plugin
    • plugin_version (str | None, optional): Version of the plugin

Authentication

  • AuthenticationError (inherits CodomyrmexError): Raised when authentication fails.

Circuit Breaker / Bulkhead

  • CircuitOpenError (inherits Exception): Raised when the circuit breaker is open. Note: does NOT inherit from CodomyrmexError.
  • BulkheadFullError (inherits Exception): Raised when the bulkhead semaphore is exhausted. Note: does NOT inherit from CodomyrmexError.

Compression and Encryption

  • CompressionError (inherits CodomyrmexError): Raised when compression operations fail.
  • EncryptionError (inherits CodomyrmexError): Raised when encryption operations fail.

IDE

  • IDEError (inherits CodomyrmexError): Base exception for IDE-related errors.
  • IDEConnectionError (inherits IDEError): Raised when IDE connection fails.
  • CommandExecutionError (inherits IDEError): Raised when an IDE command fails to execute.
  • SessionError (inherits IDEError): Raised when there is a session-related error.
  • ArtifactError (inherits IDEError): Raised when artifact operations fail.

Cache

  • CacheError (inherits CodomyrmexError): Raised when cache operations fail.
  • Additional Parameters:
    • cache_key (str | None, optional): The cache key that caused the error
    • backend (str | None, optional): The cache backend in use

Serialization

  • SerializationError (inherits CodomyrmexError): Raised when serialization/deserialization operations fail.
  • Additional Parameters:
    • format_type (str | None, optional): The serialization format (e.g., "json", "yaml")
    • data_type (str | None, optional): The type of data being serialized

Data Models

All exceptions support serialization via the to_dict() method inherited from CodomyrmexError:

{
    "error_type": "FileOperationError",
    "error_code": "FileOperationError",
    "message": "Cannot read file",
    "context": {"file_path": "/path/to/file.txt"}
}

Inheritance Hierarchy

Exception
  +-- CodomyrmexError (base.py)
  |     +-- ConfigurationError (config.py)
  |     +-- EnvironmentError (config.py)
  |     +-- DependencyError (config.py)
  |     +-- FileOperationError (io.py)
  |     +-- DirectoryError (io.py)
  |     +-- AIProviderError (ai.py)
  |     +-- CodeGenerationError (ai.py)
  |     +-- CodeEditingError (ai.py)
  |     +-- ModelContextError (ai.py)
  |     +-- StaticAnalysisError (analysis.py)
  |     +-- PatternMatchingError (analysis.py)
  |     +-- SecurityAuditError (analysis.py)
  |     +-- CodeExecutionError (execution.py)
  |     +-- SandboxError (execution.py)
  |     +-- ContainerError (execution.py)
  |     +-- BuildError (execution.py)
  |     +-- SynthesisError (execution.py)
  |     +-- GitOperationError (git.py)
  |     +-- RepositoryError (git.py)
  |     +-- VisualizationError (viz.py)
  |     +-- PlottingError (viz.py)
  |     +-- DocumentationError (viz.py)
  |     +-- APIDocumentationError (viz.py)
  |     +-- OrchestrationError (orchestration.py)
  |     +-- WorkflowError (orchestration.py)
  |     +-- ProjectManagementError (orchestration.py)
  |     +-- TaskExecutionError (orchestration.py)
  |     +-- NetworkError (network.py)
  |     +-- APIError (network.py)
  |     +-- ValidationError (network.py)
  |     +-- SchemaError (network.py)
  |     +-- TimeoutError (network.py)
  |     +-- CerebrumError (cerebrum.py)
  |     |     +-- CaseError
  |     |     |     +-- CaseNotFoundError
  |     |     |     +-- InvalidCaseError
  |     |     +-- BayesianInferenceError
  |     |     |     +-- InferenceError
  |     |     |     +-- NetworkStructureError
  |     |     +-- ActiveInferenceError
  |     |     +-- ModelError
  |     |     +-- TransformationError
  |     +-- PerformanceError (specialized.py)
  |     +-- LoggingError (specialized.py)
  |     +-- SystemDiscoveryError (specialized.py)
  |     +-- ... (30+ more specialized exceptions)
  |     +-- IDEError (specialized.py)
  |           +-- IDEConnectionError
  |           +-- CommandExecutionError
  |           +-- SessionError
  |           +-- ArtifactError
  +-- CircuitOpenError (specialized.py)
  +-- BulkheadFullError (specialized.py)

Authentication & Authorization

Not applicable for this internal exception module.

Rate Limiting

Not applicable for this internal exception module.

Versioning

This module follows the general versioning strategy of the Codomyrmex project. API stability is aimed for, with changes documented in the CHANGELOG.md.

Navigation Links