# `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`

```python
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`

```python
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.

```python
from cleveragents.core.exceptions import ResourceNotFoundError

raise ResourceNotFoundError(resource_type="plan", resource_id="plan-42")
# → "Plan 'plan-42' not found"
```

---

### `LockConflictError`

```python
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`

```python
class RateLimitError(ProviderError):
    retry_after: int | None   # seconds to wait before retrying
```

---

### `DecisionPhaseViolationError`

```python
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.

```python
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.

```python
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.