From 0d8f265b4c12f83c52741af5b2064aba9a942e6f Mon Sep 17 00:00:00 2001 From: CleverThis Date: Mon, 13 Apr 2026 06:25:03 +0000 Subject: [PATCH] docs: add getting-started guide and architecture overview [AUTO-DOCS-3] --- docs/architecture/index.md | 68 +++++ docs/architecture/overview.md | 510 +++++++++++++++++++++++++++++++++ docs/guides/getting-started.md | 371 ++++++++++++++++++++++++ docs/guides/index.md | 41 +++ mkdocs.yml | 6 + 5 files changed, 996 insertions(+) create mode 100644 docs/architecture/index.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/guides/getting-started.md create mode 100644 docs/guides/index.md diff --git a/docs/architecture/index.md b/docs/architecture/index.md new file mode 100644 index 000000000..2caa1915d --- /dev/null +++ b/docs/architecture/index.md @@ -0,0 +1,68 @@ +# Architecture Documentation + +Comprehensive documentation of the CleverAgents platform architecture. + +--- + +## Available Documents + +| Document | Description | +|----------|-------------| +| [Architecture Overview](overview.md) | Six-layer architecture, domain concepts, plan lifecycle state machine, actor system, resource system, A2A protocol facade, data flow diagram, and full ADR table | + +--- + +## Quick Reference + +### The Six Layers + +| Layer | Package(s) | Responsibility | +|-------|-----------|----------------| +| **Entry Points** | `cli`, `tui` | CLI commands, TUI screens | +| **Application** | `application` | DI wiring, service orchestration, A2A facade | +| **Domain** | `domain`, `actor`, `skills`, `tool`, `resource` | Core business logic | +| **Infrastructure** | `infrastructure` | Database, sandbox, events, observability | +| **Integration** | `a2a`, `mcp`, `lsp`, `langgraph`, `acms` | External protocol adapters | +| **Core** | `core`, `shared`, `config` | Cross-cutting utilities | + +### Plan Lifecycle at a Glance + +``` +Action ──► Strategize ──► Execute ──► Apply + │ │ │ │ + │ (estimate) (validate) (diff review) + │ │ + └───────────────────────────┘ + (correction / rollback) +``` + +### Key Standards + +| Standard | Role | +|----------|------| +| **A2A** | Sole client-server communication protocol (JSON-RPC 2.0) | +| **MCP** | External tool discovery and invocation | +| **LSP** | Code intelligence for actors | +| **AgentSkills.io** | Instruction-driven skill packaging | + +--- + +## Related Documentation + +- [Specification](../specification.md) — Authoritative platform specification +- [architecture.md](../architecture.md) — Developer-oriented component map with Mermaid diagrams +- [ADR Index](../adr/index.md) — All Architecture Decision Records +- [Getting Started Guide](../guides/getting-started.md) — Step-by-step installation and first plan +- [API Reference](../api/index.md) — Full CLI and Python API reference + +--- + +## Contributing Architecture Documentation + +To add new architecture documentation: + +1. Create a Markdown file in `docs/architecture/` (e.g., `acms-deep-dive.md`). +2. Add an entry to this index file. +3. Add the document to the `nav` section of `mkdocs.yml` under `Architecture`. +4. Cross-reference the relevant ADRs. +5. Follow the [Documentation Writer](../development/docs-writer.md) standards. diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 000000000..ed1919f5d --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,510 @@ +# Architecture Overview + +CleverAgents is a Python-first AI agent orchestration platform built around a strict +**six-layer architecture**, a rich **domain model**, and open **interoperability standards**. +This document provides a comprehensive but accessible overview of the system design. + +For the authoritative specification see [`docs/specification.md`](../specification.md). +For individual design decisions see the [ADR index](../adr/index.md). +For the developer-oriented component map see [`docs/architecture.md`](../architecture.md). + +--- + +## Six-Layer Architecture + +CleverAgents enforces a strict layered architecture +([ADR-001](../adr/ADR-001-layered-architecture.md)) where **dependencies flow downward +only** — upper layers may import from lower layers but never the reverse. + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ LAYER 1 — ENTRY POINTS │ +│ CLI (agents / cleveragents) │ TUI (agents tui) │ Server │ +├─────────────────────────────────────────────────────────────────┤ +│ LAYER 2 — APPLICATION │ +│ A2A Facade │ DI Container │ Application Services │ +├─────────────────────────────────────────────────────────────────┤ +│ LAYER 3 — DOMAIN │ +│ Plan Lifecycle │ Actor System │ Resource DAG │ +│ Decision Tree │ Skill System │ Tool System │ +├─────────────────────────────────────────────────────────────────┤ +│ LAYER 4 — INFRASTRUCTURE │ +│ Database (SQLAlchemy) │ Sandbox │ Event Bus │ +│ Observability │ Plugin Manager │ +├─────────────────────────────────────────────────────────────────┤ +│ LAYER 5 — INTEGRATION │ +│ LangGraph Bridge │ MCP Adapter │ LSP Client │ +│ ACMS │ UKO Runtime │ +├─────────────────────────────────────────────────────────────────┤ +│ LAYER 6 — CORE │ +│ Shared Utilities │ Configuration │ Cross-cutting Concerns │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| Layer | Package(s) | Responsibility | +|-------|-----------|----------------| +| **Entry Points** | `cli`, `tui` | User-facing interfaces — CLI commands, TUI screens | +| **Application** | `application` | DI wiring, service orchestration, A2A facade | +| **Domain** | `domain`, `actor`, `skills`, `tool`, `resource` | Core business logic and domain model | +| **Infrastructure** | `infrastructure` | Database, sandbox, events, observability, plugins | +| **Integration** | `a2a`, `mcp`, `lsp`, `langgraph`, `acms` | External protocol adapters and runtime bridges | +| **Core** | `core`, `shared`, `config` | Cross-cutting utilities, configuration, logging | + +--- + +## Key Domain Concepts + +### Plan + +A **Plan** is a ULID-identified, hierarchical unit of work instantiated from an Action +template. It progresses through four phases and persists a decision tree at each step. + +- May spawn child plans (hierarchical composition) +- Scoped to one or more projects +- Top-level plans carry a namespaced name (`[[server:]namespace/]name`) +- Child plans are identified solely by their plan ID (ULID) + +### Action + +An **Action** is a YAML-defined, reusable plan template specifying: + +- Description and definition of done +- Strategy and execution actors +- Typed arguments +- Optional invariants + +Actions are project-agnostic until bound to a project via `agents plan use`. + +### Actor + +An **Actor** is a YAML-configured conversational unit — either a single LLM/agent or a +composed LangGraph of actors and tool nodes. + +Specialized actor roles: + +| Role | Description | +|------|-------------| +| **Strategy Actor** | Produces the initial decision tree during Strategize | +| **Execution Actor** | Carries out decisions during Execute | +| **Estimation Actor** | Wired via `actor.default.estimation` config key | +| **Invariant Reconciliation Actor** | Runs automatically at each phase transition | + +### Tool + +A **Tool** is the atomic unit of execution — a namespaced, independently registered +callable operation with: + +- JSON Schema inputs/outputs +- Capability metadata (`read_only`, `writes`, `checkpointable`) +- Four-stage lifecycle: `discover → activate → execute → deactivate` +- Sources: MCP servers, Agent Skills folders, built-ins, or custom Python + +### Skill + +A **Skill** is a composable, namespaced collection of tools. Actors reference skills +by name to acquire capabilities. Skills can: + +- Reference named tools +- Define inline anonymous tools +- Include other skills +- Expose MCP server tools and AgentSkills.io tools + +### Resource + +A **Resource** is a ULID-identified entity registered in the Resource Registry +representing anything readable, writable, or queryable: + +- Git repositories (`git-checkout`) +- Filesystems (`fs-mount`, `fs-directory`) +- Databases (`sqlite`, `postgresql`, `mysql`, `duckdb`) +- Containers (`container.docker`, `container.podman`, `devcontainer-instance`) +- LSP servers (`lsp.*`) +- Cloud infrastructure (`cloud.*`) + +Resources are organized as a **DAG** (Directed Acyclic Graph) with dependency tracking +and support single-inheritance type hierarchies ([ADR-042](../adr/ADR-042-resource-type-inheritance.md)). + +### Project + +A **Project** is a named scope linking resources, context policies, invariants, and +validation attachments. Projects do not own resources — a single resource may be linked +to multiple projects. + +### Decision + +A **Decision** is a persisted choice point in a plan's decision tree, created during +Strategize or Execute. It records: + +- The question and chosen option +- Alternatives considered +- Confidence score and rationale +- Context snapshot +- Downstream dependencies + +Decisions support targeted correction with selective subtree recomputation +([ADR-007](../adr/ADR-007-decision-tree-and-correction.md)). + +--- + +## Plan Lifecycle State Machine + +The plan lifecycle is the central abstraction ([ADR-006](../adr/ADR-006-plan-lifecycle.md)): + +``` + ┌─────────────────────────────────────────┐ + │ │ + ▼ │ + ┌──────────┐ │ + │ ACTION │ User intent captured as a │ + │ (init) │ plan request from an Action │ + └────┬─────┘ template │ + │ │ + ▼ │ + ┌────────────────┐ │ + │ STRATEGIZE │ LLM generates structured plan │ + │ (read-only) │ decision tree; no resource │ + └────────┬───────┘ mutations │ + │ │ + │ [optional: Estimate phase] │ + │ │ + ▼ │ + ┌────────────────┐ │ + │ EXECUTE │ Operations executed against │ + │ (sandbox) │ resources via tools; all │ + └────────┬───────┘ mutations in sandbox │ + │ │ + ▼ │ + ┌────────────────┐ │ + │ APPLY │ Sandbox changeset merged into │ + │ (commit) │ real project resources after │ + └────────┬───────┘ diff review │ + │ │ + ┌─────────┼──────────────┐ │ + ▼ ▼ ▼ │ + [applied] [errored] [constrained] ─────────────────►┘ + (revert to Strategize) +``` + +### Phase Details + +| Phase | Actor | Mutations | Output | +|-------|-------|-----------|--------| +| **Action** | — | None | Plan instantiated from Action template | +| **Strategize** | Strategy Actor | None (read-only) | Decision tree with strategy choices | +| **Execute** | Execution Actor | Sandbox only | Artifacts, tool results, child plans | +| **Apply** | — | Real resources | Merged changeset; terminal state | + +### Phase Transition Gates + +Every phase transition is gated by: + +1. **Invariant Reconciliation** — `InvariantReconciliationActor` runs automatically; + failures block the transition with `ReconciliationBlockedError` +2. **Validation Pipeline** — rule-based checks with severity levels +3. **Definition-of-Done** — explicit criteria evaluated before Apply +4. **Advisory Locking** — prevents concurrent modification of the same plan + +--- + +## Actor System + +Actors are defined in YAML with a LangGraph node graph +([ADR-010](../adr/ADR-010-actor-and-agent-architecture.md), +[ADR-031](../adr/ADR-031-actor-abstraction-definition.md)): + +```yaml +name: local/my-workflow-actor +entry_node: planner +nodes: + planner: + model: gpt-4o + tool_sources: [builtin, mcp://bash-tools] + lsp_bindings: [python] + executor: + model: gpt-4o-mini + tool_sources: [builtin, skill://my-skill] +edges: + - from: planner + to: executor + condition: needs_execution +``` + +### Actor Types + +| Type | Description | +|------|-------------| +| **LLM Actor** | Single LLM node; simplest form | +| **Graph Actor** | Multi-node LangGraph with routing conditions | +| **Tool Actor** | Wraps a tool as an actor for composability | +| **Built-in Actors** | `openai/gpt-4o`, `anthropic/claude-*`, etc. — immutable | +| **Custom Actors** | Must be named `local/` | + +### Actor Compilation + +1. YAML loaded and validated by `ActorLoader` +2. `ActorCompiler` resolves tool sources, LSP bindings, and skill references +3. `CompiledActor` registered in `ActorRegistry` +4. Resolved by name at runtime via the DI container + +--- + +## Resource System + +Resources are managed via the Resource Registry +([ADR-008](../adr/ADR-008-resource-system.md)): + +``` +Resource Registry (DAG) +│ +├── git-checkout: /repos/my-app (physical) +│ └── devcontainer-instance: my-app (auto-discovered, inherits container-instance) +│ +├── fs-directory: /data/docs (physical) +│ +├── postgresql: prod-db (physical) +│ +└── virtual-repo: my-app-identity (virtual — links physical equivalents) +``` + +### Resource Handler Lifecycle + +Each resource type implements a handler with: + +- **CRUD** — read, write, list, delete +- **Checkpoint** — snapshot current state before mutations +- **Rollback** — restore from checkpoint on failure or rejection +- **Sandbox** — isolate mutations during Execute phase + +### Built-in Resource Types + +| Type | Description | +|------|-------------| +| `git-checkout` | Git repository at a specific path/URL | +| `fs-mount` / `fs-directory` | Filesystem mount or directory | +| `sqlite` / `postgresql` / `mysql` / `duckdb` | Database resources | +| `container.docker` / `container.podman` | Container instances | +| `devcontainer-instance` | Dev container (inherits `container-instance`) | +| `lsp.*` | Language server resources | +| `cloud.*` | Cloud infrastructure resources | + +--- + +## A2A Protocol Facade + +All CLI, TUI, and server interactions cross the **A2A (Agent-to-Agent Protocol)** +boundary ([ADR-026](../adr/ADR-026-agent-client-protocol.md), +[ADR-047](../adr/ADR-047-acp-standard-adoption.md)): + +``` +CLI / TUI / IDE Plugin / Third-party Client + │ + │ JSON-RPC 2.0 (A2A) + ▼ + ┌─────────────────────┐ + │ A2A Facade │ + │ │ + │ Local mode: │ + │ A2aLocalFacade │──► Direct Python calls to Application Services + │ (stdio / in-proc) │ + │ │ + │ Server mode: │ + │ A2aHttpTransport │──► HTTP → CleverAgents Server + └─────────────────────┘ +``` + +### Standard A2A Operations + +| Operation | Description | +|-----------|-------------| +| `message/send` | Send a message to an actor | +| `message/stream` | Stream responses via SSE | +| Task lifecycle | Create, update, cancel tasks | +| Agent Card | Capability discovery | + +### CleverAgents Extensions (`_cleveragents/` prefix) + +| Extension Method | Description | +|-----------------|-------------| +| `_cleveragents/plan.*` | Plan lifecycle operations | +| `_cleveragents/registry.*` | Registry CRUD (actors, tools, skills, resources) | +| `_cleveragents/entity.*` | Entity sync | +| `_cleveragents/namespace.*` | Namespace management | +| `_cleveragents/diagnostics` | Platform diagnostics | + +--- + +## Data Flow Diagram + +The following ASCII diagram shows the end-to-end data flow for a typical plan execution: + +``` +User Input (CLI / TUI) + │ + │ agents plan use --project + ▼ + ┌─────────────┐ + │ CLI / TUI │ Entry Point Layer + └──────┬──────┘ + │ A2A JSON-RPC 2.0 + ▼ + ┌─────────────┐ + │ A2A Facade │ Application Layer + └──────┬──────┘ + │ + ▼ + ┌──────────────────┐ + │ PlanService │ Application Services + │ SessionService │ + └──────┬───────────┘ + │ + ▼ + ┌──────────────────────────────────────────┐ + │ Plan Lifecycle (Domain Layer) │ + │ │ + │ Action ──► Strategize ──► Execute ──► Apply + │ │ │ + │ [Decision Tree] [Sandbox] + └──────┬───────────────────────────────────┘ + │ + ├──► ActorRegistry ──► ActorCompiler ──► CompiledActor + │ │ + │ ┌─────────┴──────────┐ + │ │ LangGraph Bridge │ + │ │ (Integration Layer)│ + │ └─────────┬──────────┘ + │ │ + │ ┌───────────────┼───────────────┐ + │ ▼ ▼ ▼ + │ MCP Adapter LSP Client ACMS/UKO + │ (ext tools) (code intel) (context mgmt) + │ + ├──► ResourceRegistry ──► ResourceHandler ──► Checkpoint/Rollback + │ + ├──► ToolRegistry ──► Tool Execution ──► Sandbox + │ + └──► Database (SQLAlchemy) ──► Persistence + │ + └──► Observability (logging, metrics, audit) +``` + +--- + +## Advanced Context Management System (ACMS) + +The ACMS manages what context is assembled and sent to the LLM at each phase +([ADR-014](../adr/ADR-014-context-management-acms.md)): + +``` +Context Assembly Pipeline +│ +├── Tier 1 (Hot) — Always-present system context; per-actor scoped views +├── Tier 2 (Warm) — Phase-specific context (plan, project, actor) +└── Tier 3 (Cold) — Dynamic retrieval via pluggable Context Strategies + │ + ├── Keyword Search Strategy + ├── Semantic Embedding Strategy + ├── Graph Navigation Strategy (UKO) + └── Temporal Archaeology Strategy +``` + +### Universal Knowledge Ontology (UKO) + +The UKO is an RDF-based, inheritance-driven ontology with four layers: + +1. **Universal Foundation** — base concepts applicable to all domains +2. **Domain Specializations** — software, documents, data schemas, infrastructure +3. **Paradigm/Format Specializations** — procedural programming, markdown +4. **Technology-Specific** — Python, PostgreSQL, etc. + +Key UKO capabilities: + +- **Typed triples with provenance** — every triple carries `sourceResource`, + `validFrom`, and `isCurrent` metadata +- **Temporal versioning** — revision chain enables point-in-time queries +- **Implicit inference** — `UKOInferenceEngine` produces implicit relationship triples + with confidence scores + +--- + +## Key Architecture Decision Records (ADRs) + +The following ADRs document the most significant design decisions: + +| ADR | Title | Summary | +|-----|-------|---------| +| [ADR-001](../adr/ADR-001-layered-architecture.md) | Layered Architecture | Strict six-layer boundaries; no upward imports | +| [ADR-002](../adr/ADR-002-namespace-system.md) | Namespace System | `[[server:]namespace/]name` qualified identifiers | +| [ADR-003](../adr/ADR-003-dependency-injection.md) | Dependency Injection | Single DI container; no service locator pattern | +| [ADR-004](../adr/ADR-004-data-validation.md) | Data Validation | Pydantic-based validation at domain boundaries | +| [ADR-005](../adr/ADR-005-technical-stack.md) | Technical Stack | Python 3.13+, LangGraph, SQLAlchemy, Textual | +| [ADR-006](../adr/ADR-006-plan-lifecycle.md) | Plan Lifecycle | Four-phase lifecycle with gating and invariants | +| [ADR-007](../adr/ADR-007-decision-tree-and-correction.md) | Decision Tree & Correction | Persisted decision tree with targeted recomputation | +| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | DAG-organized resources with handler lifecycle | +| [ADR-009](../adr/ADR-009-project-model.md) | Project Model | Projects as resource scopes, not resource owners | +| [ADR-010](../adr/ADR-010-actor-and-agent-architecture.md) | Actor & Agent Architecture | YAML-configured LangGraph actors | +| [ADR-011](../adr/ADR-011-tool-system.md) | Tool System | Atomic, namespaced, four-stage lifecycle tools | +| [ADR-012](../adr/ADR-012-skill-system.md) | Skill System | Composable tool bundles with progressive disclosure | +| [ADR-013](../adr/ADR-013-validation-abstraction.md) | Validation Abstraction | Tool subtype with pass/fail semantics | +| [ADR-014](../adr/ADR-014-context-management-acms.md) | Context Management (ACMS) | Pluggable, tiered context assembly pipeline | +| [ADR-015](../adr/ADR-015-sandbox-and-checkpoint.md) | Sandbox & Checkpoint | Checkpoint/rollback for all resource writes | +| [ADR-016](../adr/ADR-016-invariant-system.md) | Invariant System | Four-scope invariants with precedence resolution | +| [ADR-017](../adr/ADR-017-automation-profiles.md) | Automation Profiles | Confidence-threshold gating for autonomous operation | +| [ADR-018](../adr/ADR-018-semantic-error-prevention.md) | Semantic Error Prevention | Type-safe domain model to prevent logic errors | +| [ADR-019](../adr/ADR-019-storage-and-persistence.md) | Storage & Persistence | SQLAlchemy + Alembic; ULID primary keys | +| [ADR-020](../adr/ADR-020-session-model.md) | Session Model | Persistent conversation threads tied to actors | +| [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) | CLI & Output Rendering | Typer/Click CLI with Rich output rendering | +| [ADR-022](../adr/ADR-022-langchain-langgraph-integration.md) | LangGraph Integration | LangGraph as graph execution engine | +| [ADR-023](../adr/ADR-023-server-mode.md) | Server Mode | Multi-user shared backend with namespace resolution | +| [ADR-024](../adr/ADR-024-configuration-system.md) | Configuration System | Layered config: defaults → file → env → CLI flags | +| [ADR-025](../adr/ADR-025-observability-and-logging.md) | Observability & Logging | Structured logging, metrics, audit trail | +| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | A2A Protocol | JSON-RPC 2.0 as sole client-server protocol | +| [ADR-027](../adr/ADR-027-language-server-protocol.md) | LSP Integration | LSP servers as code intelligence tools for actors | +| [ADR-028](../adr/ADR-028-agent-skills-standard.md) | Agent Skills Standard | AgentSkills.io SKILL.md packaging | +| [ADR-029](../adr/ADR-029-model-context-protocol.md) | MCP Adoption | MCP servers bridged into Tool Registry | +| [ADR-030](../adr/ADR-030-skill-abstraction-definition.md) | Skill Abstraction | Formal skill definition and registry contract | +| [ADR-031](../adr/ADR-031-actor-abstraction-definition.md) | Actor Abstraction | Formal actor definition and compilation contract | +| [ADR-032](../adr/ADR-032-jinja2-yaml-template-preprocessing.md) | Jinja2 YAML Templates | Sandboxed Jinja2 with allowlist for YAML configs | +| [ADR-033](../adr/ADR-033-decision-recording-protocol.md) | Decision Recording | Protocol for persisting decisions during plan phases | +| [ADR-034](../adr/ADR-034-decision-tree-versioning-and-history.md) | Decision Tree Versioning | Immutable history with version pointers | +| [ADR-035](../adr/ADR-035-decision-tree-rollback-and-replay.md) | Decision Tree Rollback | Rollback to prior version; selective subtree replay | +| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Semantics | DAG traversal, dependency resolution, cycle detection | +| [ADR-037](../adr/ADR-037-tool-reachability-and-access-projection.md) | Tool Reachability | Access projection for tool visibility per actor node | +| [ADR-038](../adr/ADR-038-cross-mechanism-sandbox-coordination.md) | Sandbox Coordination | Coordinating git, container, and DB sandboxes | +| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Docker/Podman container resource type hierarchy | +| [ADR-040](../adr/ADR-040-lsp-resource-types.md) | LSP Resource Types | LSP server resource type and registry | +| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles as composable sub-models | +| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Single-inheritance type hierarchy with field merging | +| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Auto-discovered dev containers as resource types | +| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture | Textual-based full-screen TUI with persona system | +| [ADR-045](../adr/ADR-045-tui-persona-system.md) | TUI Persona System | YAML-backed personas with actor/preset binding | +| [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference & Commands | Slash commands and reference picker system | +| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | Adopting the external A2A protocol standard | +| [ADR-048](../adr/ADR-048-server-application-architecture.md) | Server Application Architecture | ASGI server with Kubernetes Helm deployment | + +--- + +## Standards Alignment + +CleverAgents deliberately adopts open, versioned protocols for interoperability: + +| Standard | Role | Key Benefit | +|----------|------|-------------| +| **A2A** (Agent-to-Agent Protocol) | Sole client-server communication protocol | Interchangeable clients; Agent Card discovery | +| **MCP** (Model Context Protocol) | External tool discovery and invocation | Plug-and-play tool ecosystem | +| **LSP** (Language Server Protocol) | Code intelligence for actors | Semantic understanding from mature LSP ecosystem | +| **AgentSkills.io** | Instruction-driven skill packaging | Teaches agents *how* to accomplish complex tasks | + +--- + +## Further Reading + +| Document | Description | +|----------|-------------| +| [Specification](../specification.md) | Authoritative platform specification with full glossary | +| [architecture.md](../architecture.md) | Developer-oriented component map with Mermaid diagrams | +| [ADR Index](../adr/index.md) | All Architecture Decision Records | +| [Getting Started Guide](../guides/getting-started.md) | Step-by-step installation and first plan | +| [CLI Reference](../api/index.md) | Full command reference | +| [Python API](../api/core.md) | Programmatic access to CleverAgents services | +| [A2A Protocol](../api/a2a.md) | A2A protocol implementation details | +| [Development Guide](../development/quality-automation.md) | Nox sessions, linting, testing | diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md new file mode 100644 index 000000000..1e19ef053 --- /dev/null +++ b/docs/guides/getting-started.md @@ -0,0 +1,371 @@ +# Getting Started with CleverAgents + +Welcome to **CleverAgents** — a unified platform for orchestrating complex AI agent tasks. +This guide walks you through installation, first-run verification, LLM provider setup, and +running your first plan end-to-end. + +--- + +## Prerequisites + +| Requirement | Minimum Version | Notes | +|-------------|----------------|-------| +| **Python** | 3.13+ | Required for all runtime features | +| **Git** | 2.38+ | Required for git-checkout resources and sandbox | +| **pip** | 23+ | Bundled with Python 3.13 | +| **bash** | any | Used by `setup-dev.sh` | + +!!! tip "Check your Python version" + ```bash + python --version # should print Python 3.13.x or later + git --version + ``` + +--- + +## Installation + +### 1. Clone the Repository + +```bash +git clone https://git.cleverthis.com/cleveragents/core.git +cd core +``` + +### 2. Create a Virtual Environment + +```bash +python -m venv .venv +source .venv/bin/activate # Linux / macOS +# .venv\Scripts\activate # Windows PowerShell +``` + +### 3. Install the Package + +Install the core package plus the optional extras you need: + +```bash +# Core + development tools + tests + docs +pip install -e ".[dev,tests,docs]" + +# Add the TUI (Textual-based interactive terminal UI) +pip install -e ".[tui]" +``` + +!!! note "Extras at a glance" + | Extra | Contents | + |-------|----------| + | `dev` | Nox, Ruff, Pyright, pre-commit | + | `tests` | Behave, Robot Framework, pytest | + | `docs` | MkDocs, mkdocstrings, kroki | + | `tui` | Textual and TUI dependencies | + +### 4. Run the Developer Setup Script + +```bash +bash scripts/setup-dev.sh +``` + +This installs pre-commit hooks (formatting, linting, type-checking, security scanning) +and verifies that all required tooling is available. + +--- + +## First Run + +### Verify the CLI + +```bash +agents --version +agents --help +``` + +Both `agents` and `cleveragents` are equivalent entry points. + +### Run Diagnostics + +```bash +agents diagnostics +``` + +`diagnostics` prints: + +- Whether the registry can see your credentials +- Which actor/provider is selected +- Data directory and configuration paths +- Any missing dependencies or misconfigurations + +--- + +## Setting Up an LLM Provider + +CleverAgents auto-discovers API keys from environment variables and selects the best +available provider. Export at least one of the following: + +| Provider | Environment Variable(s) | +|----------|------------------------| +| **OpenAI** | `OPENAI_API_KEY` | +| **Anthropic** | `ANTHROPIC_API_KEY` | +| **Google** | `GOOGLE_API_KEY` or `GOOGLE_GENAI_API_KEY` | +| **Azure OpenAI** | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_DEPLOYMENT` | +| **OpenRouter** | `OPENROUTER_API_KEY` | +| **Gemini** | `GEMINI_API_KEY` or `GOOGLE_GEMINI_API_KEY` | +| **Cohere** | `COHERE_API_KEY` | +| **Groq** | `GROQ_API_KEY` | +| **Together** | `TOGETHER_API_KEY` | + +### Quick Example — OpenAI + +```bash +export OPENAI_API_KEY="sk-..." +agents diagnostics # should now show openai/gpt-4o as the selected actor +``` + +### Pin a Specific Provider and Model + +```bash +export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic +export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514 +``` + +### Set a Default Actor + +```bash +agents actor set-default openai/gpt-4o +``` + +!!! tip "Testing without an API key" + Set `CLEVERAGENTS_TESTING_USE_MOCK_AI=true` to force the built-in mock provider. + This is how the Behave/Robot test suites run without hitting external APIs. + +--- + +## Creating Your First Action + +An **Action** is a reusable YAML template that describes a task — the plan's "what". +Actions are project-agnostic until bound to a project. + +```bash +agents action create my-first-action \ + --description "Summarise the README of a repository" \ + --strategy-actor openai/gpt-4o \ + --execution-actor openai/gpt-4o +``` + +List available actions: + +```bash +agents action list +agents action show my-first-action +``` + +--- + +## Creating a Project and Linking a Resource + +A **Project** groups resources (git repos, databases, filesystems) and provides the +context in which plans execute. + +### 1. Register a Git Resource + +```bash +agents resource add git-checkout \ + --url https://github.com/example/my-repo.git \ + --path /tmp/my-repo \ + my-repo +``` + +### 2. Create a Project + +```bash +agents project create my-project \ + --description "My first CleverAgents project" +``` + +### 3. Link the Resource to the Project + +```bash +agents project link-resource my-project my-repo +``` + +Verify the project: + +```bash +agents project show my-project +``` + +--- + +## Running Your First Plan + +A **Plan** is a live instance of an Action bound to a project. It progresses through +four phases: **Action → Strategize → Execute → Apply**. + +### 1. Instantiate a Plan + +```bash +agents plan use my-first-action --project my-project +``` + +This prints the new plan ID (a ULID, e.g. `01HZ...`). Export it for convenience: + +```bash +export PLAN_ID=01HZ... +``` + +### 2. Run the Strategize Phase + +The strategy actor reads the action template and project context, then produces a +structured decision tree — without modifying any resources. + +```bash +agents plan execute --phase strategize $PLAN_ID +``` + +Review the generated strategy: + +```bash +agents plan show $PLAN_ID +agents plan decisions $PLAN_ID +``` + +### 3. Run the Execute Phase + +The execution actor carries out the decisions from Strategize — invoking tools, +producing artifacts, and writing to the sandbox. + +```bash +agents plan execute --phase execute $PLAN_ID +``` + +### 4. Review the Diff + +Before committing changes, inspect what the plan proposes to change: + +```bash +agents plan diff $PLAN_ID +``` + +This shows a unified diff of all sandbox changes against the current resource state. + +### 5. Apply the Changes + +If the diff looks correct, apply the changes to the real resources: + +```bash +agents plan apply $PLAN_ID +``` + +!!! warning "Apply is irreversible by default" + Once applied, changes are merged into the real resource. Use `--dry-run` to + preview the apply operation without committing. + +### Full Plan Lifecycle at a Glance + +``` +agents plan use --project # Action phase — instantiate +agents plan execute --phase strategize # Strategize — plan the work +agents plan execute --phase execute # Execute — do the work (sandbox) +agents plan diff # Review proposed changes +agents plan apply # Apply — commit to real resources +``` + +--- + +## Using the TUI + +The **TUI** (Terminal User Interface) provides a full-screen, interactive experience +for working with CleverAgents — ideal for exploratory sessions and multi-plan workflows. + +### Launch + +```bash +agents tui +``` + +On first launch, the **Actor Selection Overlay** guides you to pick an actor and +automatically creates a `"default"` persona. + +### Key Bindings + +| Key | Action | +|-----|--------| +| `Enter` | Send message to the active actor | +| `/` | Open slash command overlay (67 commands across 14 groups) | +| `@` | Open reference picker — insert file/resource references | +| `!` | Enter shell mode — run a subprocess command | +| `F1` | Toggle context-sensitive help panel | +| `Ctrl+T` | Cycle through argument presets for the active persona | +| `Ctrl+Q` | Quit | + +### Slash Commands (Examples) + +``` +/plan use my-first-action --project my-project +/plan execute +/plan diff +/plan apply +/session create --actor openai/gpt-4o +/actor set-default anthropic/claude-sonnet-4-20250514 +``` + +### Shell Mode + +Prefix a command with `!` to run it as a subprocess: + +``` +! git status +! ls -la +``` + +!!! warning "Shell Danger Detection" + The TUI classifies shell commands by danger level (LOW → CRITICAL) and shows a + warning overlay before executing destructive, privilege-escalating, or + exfiltration-risk commands. + +--- + +## Session Management + +Sessions are persistent conversation threads tied to an actor. + +```bash +# Create a new session +agents session create --actor openai/gpt-4o + +# List all sessions +agents session list + +# Export a session (JSON or Markdown) +agents session export --session-id --output session.json +agents session export --session-id --format md --output session.md + +# Import a session +agents session import --input session.json +``` + +--- + +## Next Steps + +Now that you have CleverAgents running, explore these resources: + +| Resource | Description | +|----------|-------------| +| [Architecture Overview](../architecture/overview.md) | Six-layer architecture, domain concepts, data flow | +| [CLI Reference](../api/index.md) | Full command reference with all flags | +| [Python API](../api/core.md) | Programmatic access to CleverAgents services | +| [A2A Protocol](../api/a2a.md) | Agent-to-Agent protocol details | +| [Specification](../specification.md) | Authoritative platform specification | +| [ADR Index](../adr/index.md) | Architecture Decision Records | +| [Development Guide](../development/quality-automation.md) | Nox sessions, linting, testing | +| [FAQ](../faq.md) | Frequently asked questions | + +### Common Workflows + +- **Multi-actor pipelines** — compose actors in a LangGraph YAML to chain strategy and execution roles +- **Custom tools** — register tools with `agents tool add --config tool.yaml` +- **Custom skills** — bundle tools into skills with `agents skill add --config skill.yaml` +- **Invariants** — add constraints to projects with `agents project create --invariant "..."` +- **Server mode** — connect to a shared backend with `agents server connect --url --token ` +- **Observability** — enable LangSmith tracing with `CLEVERAGENTS_LANGSMITH_ENABLED=true` diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 000000000..0699c8887 --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,41 @@ +# Guides + +Practical, task-oriented guides for working with CleverAgents. + +--- + +## Available Guides + +| Guide | Description | +|-------|-------------| +| [Getting Started](getting-started.md) | Install CleverAgents, configure an LLM provider, and run your first plan end-to-end | + +--- + +## What's in a Guide? + +Guides are **task-oriented** — they walk you through accomplishing a specific goal +step by step. They assume you want to *do* something rather than *understand* something. + +For conceptual background, see: + +- [Architecture Overview](../architecture/overview.md) — how CleverAgents is structured +- [Specification](../specification.md) — the authoritative platform specification +- [ADR Index](../adr/index.md) — the reasoning behind key design decisions + +For reference material, see: + +- [CLI Reference](../api/index.md) — every command and flag +- [Python API](../api/core.md) — programmatic access to CleverAgents services + +--- + +## Contributing a Guide + +To add a new guide: + +1. Create a Markdown file in `docs/guides/` following the naming convention + `.md` (e.g., `custom-actors.md`). +2. Add an entry to this index file. +3. Add the guide to the `nav` section of `mkdocs.yml` under `Guides`. +4. Follow the [Documentation Writer](../development/docs-writer.md) standards. diff --git a/mkdocs.yml b/mkdocs.yml index 76940184b..1da904251 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,12 @@ site_dir: build/site nav: - Specification: specification.md - Architecture: architecture.md + - Guides: + - Overview: guides/index.md + - Getting Started: guides/getting-started.md + - Architecture Deep Dive: + - Overview: architecture/index.md + - Architecture Overview: architecture/overview.md - API Reference: - Overview: api/index.md - Core Utilities: api/core.md -- 2.52.0