Shared type definitions, protocols, and error hierarchy for AgentiCraft packages.

The type foundation behind AgentiCraft -- an enterprise-grade platform for building production-ready AI agents and multi-agent systems.

Pydantic v2 models · Protocol classes · Exception hierarchy · Configuration schemas · Zero business logic

---

Install

With uv (recommended):

uv add agenticraft-types

Or with pip:

pip install agenticraft-types

Quick Start

from agenticraft_types import (
    CompletionRequest,
    CompletionResponse,
    ProviderName,
    ProviderError,
    RateLimitError,
    RetryConfig,
)

# Build a typed request
request = CompletionRequest(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=100,
)

# Use enums for provider selection
provider = ProviderName.OPENAI

# Catch typed exceptions
try:
    response = await some_provider.complete(request)
except RateLimitError as e:
    print(f"Rate limited by {e.provider}, retry after {e.retry_after}s")
except ProviderError as e:
    print(f"Provider {e.provider} failed: {e}")

Protocol-Based Typing

from agenticraft_types import Provider, Router, CircuitBreakerLike

# Structural typing -- implement the protocol, no inheritance needed
class MyProvider:
    async def complete(self, messages, **kwargs) -> CompletionResponse: ...
    async def stream(self, messages, **kwargs): ...

def route(provider: Provider) -> None:
    # Type-safe without coupling to a base class
    ...

What's Inside

• models -- Pydantic v2 request/response models (CompletionRequest, CompletionResponse, StreamChunk, Usage, Message)
• enums -- Shared enumerations (ProviderName, FailureType, RoutingStrategy, MessageRole, CircuitBreakerState)
• errors -- Exception hierarchy (AgentiCraftError, ProviderError, RateLimitError, AuthenticationError, etc.)
• protocols -- typing.Protocol classes for structural typing (Provider, Router, CircuitBreakerLike, KeyPoolLike)
• config -- Configuration schemas (RetryConfig, CircuitBreakerConfig, RateLimitConfig)

Design Rules

• Under 1,000 LOC total
• Zero business logic
• Only dependency: pydantic>=2.0
• Apache 2.0 license

Development

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=agenticraft_types --cov-report=html

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run pyright src/

# Pre-commit hooks
uv run pre-commit install

See CONTRIBUTING.md for full guidelines.

License

Apache 2.0

Part of the AgentiCraft platform.