freemo
e9c96c3d0c
CI / build (push) Successful in 17s
CI / lint (push) Failing after 19s
CI / helm (push) Successful in 34s
CI / security (push) Failing after 42s
CI / quality (push) Has been cancelled
CI / unit_tests (push) Has been cancelled
CI / e2e_tests (push) Has been cancelled
CI / integration_tests (push) Has been cancelled
CI / typecheck (push) Has been cancelled
CI / benchmark-publish (push) Has been cancelled
CI / coverage (push) Has been cancelled
CI / benchmark-regression (push) Has been cancelled
CI / docker (push) Has been cancelled
CI / status-check (push) Has been cancelled
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
180 lines
4.2 KiB
Markdown
180 lines
4.2 KiB
Markdown
# `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.
|