cleveragents-core/docs/api/domain.md

cleveragents.domain — Domain Layer

The domain package contains the core business logic, domain models, and domain services for CleverAgents. It is the heart of the layered architecture (ADR-001) and must not import from infrastructure or application layers.

---

cleveragents.domain.models.base — Shared Base Model

DomainBaseModel

from cleveragents.domain.models.base import DomainBaseModel

Base class for all standard domain-layer Pydantic models. Centralises the shared model_config that was previously duplicated across 14+ domain model files.

from cleveragents.domain.models.base import DomainBaseModel
from pydantic import Field

class MyDomainModel(DomainBaseModel):
    name: str
    value: int = Field(default=0)

Shared model_config settings:

Setting	Value	Effect
str_strip_whitespace	True	Leading/trailing whitespace stripped from all str fields on assignment and validation
validate_assignment	True	Field assignments after construction are validated like constructor arguments
arbitrary_types_allowed	False	All field types must be Pydantic-compatible; keeps the domain layer clean
populate_by_name	True	Models can be constructed using either the Python field name or the JSON alias
use_enum_values	True	Enum fields stored and serialised as their underlying primitive values

Note: This is a pure structural base class with no behavioural logic. It exists solely to ensure the shared configuration is defined in exactly one place and automatically propagated to every consumer.

---

cleveragents.domain.models.core — Core Domain Models

The core sub-package contains the primary domain models used throughout the system. All models inherit from DomainBaseModel.

Key Models

Model	Module	Description
Plan	core.plan	Plan lifecycle model (Strategize → Execute → Apply)
Session	core.session	Conversation session with message history
Actor	core.actor	Actor configuration and capabilities
Action	core.action	User intent captured as a plan request
Decision	core.decision	Decision record with versioning and rollback
AutomationProfile	core.automation_profile	Automation threshold configuration
SafetyProfile	core.safety_profile	Safety controls for plan execution
InlinePermissionQuestion	core.inline_permission_question	Single-file permission request model
ThoughtBlock	thought.thought_block	Actor reasoning trace with expand/collapse

Session.as_export_markdown() → str

Renders a human-readable Markdown transcript of the session. The output is lossy (for sharing/documentation) and cannot be re-imported.

from cleveragents.domain.models.core.session import Session

session: Session = ...
md = session.as_export_markdown()
# Returns Markdown with:
# - Header: session ID, actor, created_at, message count
# - Message history: role | timestamp | content
# - Linked plan references

ThoughtBlock

from cleveragents.domain.models.thought.thought_block import ThoughtBlock

block = ThoughtBlock(content="...", max_lines=10)
block.is_expanded        # bool
block.truncated_content  # str — first max_lines lines
block.full_content       # str — complete content
block.toggle()           # flip expanded/collapsed state

---

cleveragents.domain.models.acms — ACMS Context Models

Models for the Advanced Context Management System.

Model	Description
ContextFragment	A single context fragment with tier, size, and token metadata
ContextView	Budget constraints for context assembly
BudgetViolation	Structured violation report from budget enforcement
BudgetEnforcementResult	Result of applying size budget to a fragment list
UKOProvenance	Provenance metadata (sourceResource, validFrom, isCurrent) on UKO triples

---

cleveragents.domain.providers — AI Provider Interface

AIProviderInterface

Protocol defining the interface all AI provider implementations must satisfy.

from cleveragents.domain.providers.ai_provider import AIProviderInterface

class MyProvider(AIProviderInterface):
    async def generate(self, messages: list[dict], **kwargs) -> str: ...
    async def stream(self, messages: list[dict], **kwargs) -> AsyncIterator[str]: ...

See cleveragents.providers for the concrete registry and provider implementations.