freemo
e9c96c3d0c
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
4.2 KiB
cleveragents.core — Core Utilities
The core package provides the exception hierarchy, error classification,
retry patterns, circuit breaker, and async resource cleanup used throughout
the entire CleverAgents platform.
Exception Hierarchy
All exceptions inherit from CleverAgentsError. Catch the most specific
type you can handle; let everything else propagate.
CleverAgentsError
├── DomainError
│ ├── ValidationError
│ ├── BusinessRuleViolation
│ │ ├── LockConflictError
│ │ └── DecisionPhaseViolationError
│ ├── ResourceNotFoundError (alias: NotFoundError)
│ ├── ResourceConflictError
│ ├── LockExpiredError
│ └── PlanError
├── InfrastructureError
│ ├── DatabaseError
│ │ └── MigrationNotApprovedError
│ ├── NetworkError
│ └── ExternalServiceError
├── ProviderError
│ ├── RateLimitError
│ ├── ModelNotAvailableError
│ └── TokenLimitExceededError
├── AuthenticationError
├── AuthorizationError
├── ConfigurationError
│ └── MissingConfigurationError
├── FileSystemError
├── ExecutionError
├── StreamRoutingError
└── UnsafeConfigurationError
CleverAgentsError
class CleverAgentsError(Exception):
message: str
details: dict[str, Any]
Base class for all platform exceptions. Always carries a human-readable
message and an optional details dict for structured context.
ResourceNotFoundError
class ResourceNotFoundError(DomainError):
resource_type: str | None
resource_id: str | None
Raised when a requested entity does not exist. If resource_type and
resource_id are provided the message is auto-generated.
from cleveragents.core.exceptions import ResourceNotFoundError
raise ResourceNotFoundError(resource_type="plan", resource_id="plan-42")
# → "Plan 'plan-42' not found"
LockConflictError
class LockConflictError(BusinessRuleViolation):
resource_type: str
resource_id: str
owner_id: str
Raised when an advisory lock cannot be acquired because another owner holds it.
RateLimitError
class RateLimitError(ProviderError):
retry_after: int | None # seconds to wait before retrying
DecisionPhaseViolationError
class DecisionPhaseViolationError(BusinessRuleViolation):
decision_type: str
plan_phase: str
allowed_types: frozenset[str]
Raised when a decision type is incompatible with the plan's current phase.
Error Handling Utilities
Module: cleveragents.core.error_handling
ErrorCode
IntEnum mapping exception categories to HTTP-like numeric codes used for
consistent CLI and API output.
classify_error(exc) → ErrorCode
Returns the ErrorCode for any exception, falling back to
ErrorCode.INTERNAL for unknown types.
redact_error_details(details) → dict
Strips sensitive keys (tokens, passwords, secrets) from an error details dict before logging.
wrap_unexpected(exc, *, context=None) → CleverAgentsError
Wraps an unexpected exception in a CleverAgentsError with a safe
user-facing message that hides internal stack details.
from cleveragents.core.error_handling import wrap_unexpected
try:
risky_operation()
except Exception as exc:
safe = wrap_unexpected(exc, context={"plan_id": plan_id})
raise safe from exc
Retry Patterns
Module: cleveragents.core.retry_patterns
Provides decorators and helpers for exponential-backoff retry with jitter, configurable per exception type.
Async Cleanup
Module: cleveragents.core.async_cleanup
AsyncResourceTracker — unified async resource lifecycle with
timeout-bounded cleanup, leak detection via finalizer, and async context
manager support.
async with AsyncResourceTracker() as tracker:
conn = await tracker.register(open_connection())
# conn is automatically closed on exit, even on error
Circuit Breaker
Module: cleveragents.core.circuit_breaker
Implements the circuit-breaker pattern to prevent cascading failures when calling external services.