cleveragents-core/docs/architecture

CleverAgents Architecture

CleverAgents uses a layered architecture for autonomous code modification. This document provides a high-level overview. For detailed design decisions, see docs/adr/ (48 ADRs) and docs/architecture.md.

Core Layers

Domain Layer

• Pydantic v2 domain models with frozen=True for immutability. All models inherit from cleveragents.domain.DomainBaseModel which provides shared model_config.
• SQLite persistence via SQLAlchemy ORM and Alembic migrations (alembic/versions/). Default database: ~/.cleveragents/cleveragents.db.
• Key entities: Action, Resource, Project, Plan, Actor, Decision, ChangeSet, Session, Invariant, Skill, Tool.
• Repository pattern: Each entity has a corresponding repository class (e.g., cleveragents.domain.ActionRepository) providing CRUD operations.

Actor Layer

• Actor YAML v3 schema (version: "3", type: llm|tool|graph). Defined in cleveragents.actor.config.ActorConfigSchema.
• LangGraph StateGraph compilation: cleveragents.actor.compiler.ActorCompiler translates YAML actor definitions into executable LangGraph StateGraph instances.
• Subgraph resolution, cycle detection, entry/exit validation.
• Actor types:
  • llm — LLM-backed actor with model, system prompt, and tool bindings.
  • tool — Pure tool executor without LLM.
  • graph — Composite actor composed of sub-actors connected by edges.
• Actor registry (cleveragents.actor.registry.ActorRegistry): Persists and resolves actors by namespace/name.

Execution Layer

• Actor-based LLM execution path: cleveragents.plan.executor.PlanExecutor orchestrates the Strategize → Execute → Apply lifecycle.
• Git worktree sandbox (cleveragents.sandbox.GitWorktreeSandbox): Isolated working directory using git worktree add so LLM-generated changes do not affect the original repository until plan apply is called.
• ChangeSet (cleveragents.changeset.ChangeSet): Built from tool invocations (not parsed from LLM output) to ensure structural correctness.
• MCP adapter (cleveragents.mcp.MCPToolAdapter): External tool server connectivity via the Model Context Protocol.

ACMS Layer (Adaptive Context Management System)

• UKO (Universal Knowledge Ontology): Four-layer ontology hierarchy for structured knowledge representation. Defined in docs/ontology/uko.ttl.
• CRP (Context Retrieval Pipeline): Six context strategies for assembling relevant context for LLM execution. Documented in docs/reference/crp.md.
• Context tiers: Hot/warm/cold tier service (cleveragents.acms.ContextTierService) with LRU eviction, staleness enforcement, and actor-scoped views.
• Skeleton compressor (cleveragents.acms.SkeletonCompressor): Reduces large codebases to structural skeletons for context budget management.

Plan Lifecycle

The plan lifecycle follows a state machine with four primary phases:

1. Use (agents plan use) — Create plan record, associate with action, initialize state machine. Defined in cleveragents.cli.plan.use_plan.
2. Execute (agents plan execute <plan_id>) — Invoke actor-based LLM path. Strategize phase builds decision tree; Execute phase produces ChangeSet via tool invocations. Defined in cleveragents.cli.plan.execute_plan.
3. Diff (agents plan diff <plan_id>) — Show pending changes in sandbox without modifying the target repository. Defined in cleveragents.cli.plan.diff_plan.
4. Apply (agents plan apply <plan_id>) — Merge sandbox branch into target repository via git merge with a structured commit. Defined in cleveragents.cli.plan.apply_plan.

Validation Layer

• Validation runner (cleveragents.validation.ValidationRunner): Executes required and informational validations. Required validations block Apply if they fail.
• Fix-then-revalidate loop: Failed required validations trigger a correction cycle before re-running the validation.
• Invariant reconciliation (cleveragents.invariant.InvariantReconciliationActor): Runs automatically at every plan phase transition; failures block the transition and emit INVARIANT_VIOLATED events.

Key Design Decisions

• Changes in sandbox do not affect original until Apply: The git worktree sandbox provides complete isolation. See ADR-015 (docs/adr/ADR-015-sandbox-and-checkpoint.md).
• ChangeSet built from tool invocations: Structural correctness is guaranteed by building ChangeSets from tool call results rather than parsing LLM text output. See ADR-007 (docs/adr/ADR-007-decision-tree-and-correction.md).
• Pydantic v2 with frozen=True: Domain models are immutable to prevent accidental mutation. See ADR-004 (docs/adr/ADR-004-data-validation.md).
• Layered architecture: CLI → Service → Domain → Persistence separation of concerns. See ADR-001 (docs/adr/ADR-001-layered-architecture.md).
• LangGraph for actor compilation: StateGraph provides deterministic execution flow with cycle detection. See ADR-022 (docs/adr/ADR-022-langchain-langgraph-integration.md).

Further Reading

• Architecture Decision Records: docs/adr/ (48 ADRs covering all major design choices)
• Full architecture specification: docs/architecture.md
• Module guides: docs/modules/
• API reference: docs/api/