From 4a91f40c7be96f2daa62c00909e5a00de120ee86 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Tue, 14 Apr 2026 20:13:01 +0000 Subject: [PATCH] docs(api): add action configuration schema API reference Documents the cleveragents.action configuration schema API including ActionConfigSchema, ActionArgumentSchema, all schema fields, key normalisation, env-var interpolation, validation errors, and worked examples drawn from examples/actions/. Updates mkdocs.yml nav and docs/api/index.md module index. ISSUES CLOSED: #7472 --- docs/api/action.md | 618 +++++++++++++++++++++++++++++++++++++++++++++ docs/api/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 620 insertions(+) create mode 100644 docs/api/action.md diff --git a/docs/api/action.md b/docs/api/action.md new file mode 100644 index 000000000..77e28d81c --- /dev/null +++ b/docs/api/action.md @@ -0,0 +1,618 @@ +# `cleveragents.action` — Action Configuration Schema API + +The `action` package provides the YAML configuration schema, validation +pipeline, and loader for CleverAgents **actions** — reusable plan templates +that define how a task is strategized, executed, reviewed, and completed. + +See [`docs/schema/action.schema.yaml`](../../schema/action.schema.yaml) for +the formal schema definition and +[`docs/reference/action_cli.md`](../reference/action_cli.md) for the +companion CLI reference. + +--- + +## Overview + +Actions are the primary unit of reusable work in CleverAgents. Each action +is defined by a YAML configuration file that specifies: + +- **Identity** — a namespaced name, description, and optional long description. +- **Lifecycle actors** — which actors handle each phase (Strategize, Execute, + Estimate, Review, Apply, Invariant reconciliation). +- **Completion criteria** — a testable definition of done. +- **Behaviour flags** — whether the action is reusable and/or read-only. +- **Arguments** — typed, validated parameters supplied at plan-use time. +- **Invariants** — constraints propagated as plan-level invariants. +- **Automation profile** — default profile for derived plans. +- **Inputs schema** — optional JSON Schema for advanced input validation. + +Actions are created exclusively via YAML files: + +```bash +agents action create --config action.yaml +``` + +--- + +## `ActionConfigSchema` + +```python +from cleveragents.action.schema import ActionConfigSchema +``` + +Pydantic model representing a fully parsed and validated action YAML file. +Instances are created via the factory class methods below — never +instantiated directly. + +### Factory Methods + +#### `ActionConfigSchema.from_yaml(yaml_string)` + +Parse and validate a raw YAML string. + +```python +config = ActionConfigSchema.from_yaml(yaml_string) +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| `yaml_string` | `str` | Raw YAML content. Must be a non-empty mapping. | + +**Returns:** `ActionConfigSchema` + +**Raises:** + +| Exception | Condition | +|-----------|-----------| +| `ValueError` | YAML string is `None`, empty, or not a mapping. | +| `pydantic.ValidationError` | One or more fields fail schema validation. | + +--- + +#### `ActionConfigSchema.from_yaml_file(path)` + +Load and validate an action YAML file from disk. + +```python +config = ActionConfigSchema.from_yaml_file(Path("examples/actions/simple.yaml")) +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| `path` | `str \| Path` | Path to the YAML file. | + +**Returns:** `ActionConfigSchema` + +**Raises:** + +| Exception | Condition | +|-----------|-----------| +| `FileNotFoundError` | File does not exist at the given path. | +| `ValueError` | Path is `None`, points to a directory, or content is invalid. | +| `pydantic.ValidationError` | One or more fields fail schema validation. | + +--- + +### Pre-validation Processing + +Before Pydantic validation runs, the loader applies three normalisation steps +in order: + +1. **camelCase → snake_case key normalisation** — legacy camelCase keys (e.g. + `strategyActor`) are silently converted to their snake_case equivalents and + a `WARNING` is emitted via the `cleveragents.action.schema` logger. +2. **`${ENV_VAR}` interpolation** — any `${VAR}` placeholder in a string value + is replaced with the corresponding environment variable. Missing variables + are left as-is (no error); resolution is deferred to runtime. +3. **Invariant normalisation** — invariant strings are trimmed, blank entries + are dropped, and duplicates are removed (order-preserving). + +--- + +## Schema Reference + +### Identity Fields + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `schema_version` | `str` | No | `"1"` | Schema version for forward compatibility. | +| `name` | `str` | **Yes** | — | Namespaced action name: `namespace/name`. Only lowercase alphanumeric, hyphens, and underscores. | +| `description` | `str` | **Yes** | — | Short, one-line description of the action. | +| `long_description` | `str \| None` | No | `None` | Detailed multi-line description. | + +#### `name` format + +Names must match `^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_-]*$`. + +```yaml +name: local/lint-check # valid +name: myorg/security-audit # valid +name: LintCheck # invalid — missing namespace +name: local/Lint Check # invalid — spaces not allowed +``` + +--- + +### Lifecycle Actor Fields + +All actor references must follow the same `namespace/name` format as `name`. + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `strategy_actor` | `str` | **Yes** | — | Actor for the **Strategize** phase. | +| `execution_actor` | `str` | **Yes** | — | Actor for the **Execute** phase. | +| `estimation_actor` | `str \| None` | No | `None` | Actor for pre-execution cost/risk estimation. | +| `review_actor` | `str \| None` | No | `None` | Actor for reviewing execution results. | +| `apply_actor` | `str \| None` | No | `None` | Actor for the **Apply** phase. | +| `invariant_actor` | `str \| None` | No | `None` | Actor for reconciling conflicting invariants. | + +!!! note "camelCase aliases" + The loader accepts legacy camelCase keys for all actor fields and converts + them automatically. See the [Key Normalisation](#key-normalisation) table. + +--- + +### Completion Criteria + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `definition_of_done` | `str` | **Yes** | — | Testable criteria defining when the action's work is complete. Must be non-empty. | + +--- + +### Behaviour Fields + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `reusable` | `bool` | No | `true` | If `false`, the action is archived after its first use. | +| `read_only` | `bool` | No | `false` | Restricts the action to read-only tool operations. | +| `state` | `str` | No | `"available"` | Lifecycle state: `available` or `archived`. `draft` is an internal-only state and is not valid in YAML configs. | + +--- + +### `arguments` + +An optional list of typed parameters that users supply at plan-use time via +`agents plan use --arg name=value`. + +```yaml +arguments: + - name: target_coverage + type: integer + required: true + description: "Target line coverage percentage" + min_value: 0 + max_value: 100 + - name: report_format + type: string + required: false + default: "text" + validation_pattern: "^(text|json|html)$" +``` + +#### `ActionArgumentSchema` fields + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `name` | `str` | **Yes** | — | Argument name. 1–64 characters. Must be a valid identifier (alphanumeric, hyphens, underscores). Used as the key in `--arg name=value`. | +| `type` | `str` | No | `"string"` | Data type: `string`, `integer`, `float`, `boolean`, or `list`. | +| `required` | `bool` | No | `false` | Whether the argument must be provided. | +| `description` | `str` | No | `""` | Human-readable description shown in help text. Max 500 characters. | +| `default` | `str \| int \| float \| bool \| list[str] \| None` | No | `None` | Default value when the argument is not provided. | +| `validation_pattern` | `str \| None` | No | `None` | Regex pattern for validating `string` arguments. | +| `min_value` | `float \| None` | No | `None` | Minimum value for `integer` or `float` arguments. | +| `max_value` | `float \| None` | No | `None` | Maximum value for `integer` or `float` arguments. | + +Extra fields on an argument object are **forbidden** and will raise a +`ValidationError`. + +--- + +### `automation_profile` + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `automation_profile` | `str \| None` | No | `None` | Default automation profile for plans derived from this action (e.g. `trusted`, `supervised`, `local/cautious`). | + +--- + +### `invariants` + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `invariants` | `list[str]` | No | `[]` | Constraints propagated as plan-level invariants when the action is used. Strings are trimmed, blanks dropped, and duplicates removed. | + +```yaml +invariants: + - "All existing tests must continue to pass" + - "Public API signatures must not change without deprecation" +``` + +--- + +### `inputs_schema` + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `inputs_schema` | `dict[str, Any] \| None` | No | `None` | Optional JSON Schema object for advanced input validation beyond basic argument types. | + +Use `inputs_schema` when argument types alone are insufficient — for example, +to validate nested objects or enforce enumerated values on complex structures. + +```yaml +inputs_schema: + type: object + properties: + stages: + type: array + items: + type: object + required: [name, transform] + properties: + name: + type: string + transform: + type: string + output_format: + type: string + enum: [csv, json, parquet] + required: + - stages +``` + +--- + +### Key Normalisation + +The loader accepts legacy camelCase keys and converts them to snake_case. +A `WARNING` is logged for each converted key. + +| camelCase (deprecated) | snake_case (canonical) | +|------------------------|------------------------| +| `strategyActor` | `strategy_actor` | +| `executionActor` | `execution_actor` | +| `estimationActor` | `estimation_actor` | +| `reviewActor` | `review_actor` | +| `applyActor` | `apply_actor` | +| `invariantActor` | `invariant_actor` | +| `definitionOfDone` | `definition_of_done` | +| `longDescription` | `long_description` | +| `readOnly` | `read_only` | +| `automationProfile` | `automation_profile` | +| `inputsSchema` | `inputs_schema` | +| `validationPattern` | `validation_pattern` | +| `minValue` | `min_value` | +| `maxValue` | `max_value` | +| `schemaVersion` | `schema_version` | + +--- + +## Complete Schema at a Glance + +```yaml +# Required fields only +name: namespace/action-name # required — namespace/name format +description: "Short description" # required +strategy_actor: namespace/actor-name # required — namespace/name format +execution_actor: namespace/actor-name # required — namespace/name format +definition_of_done: | # required — non-empty + Measurable completion criteria. + +# Optional fields (shown with defaults) +schema_version: "1" +long_description: null +estimation_actor: null +review_actor: null +apply_actor: null +invariant_actor: null +reusable: true +read_only: false +state: available +automation_profile: null +arguments: [] +invariants: [] +inputs_schema: null +``` + +Extra top-level keys are **forbidden** and will raise a `ValidationError`. + +--- + +## Examples + +### Minimal Action + +The smallest valid action — only required fields: + +```yaml +# examples/actions/simple.yaml +name: local/lint-check +description: "Run linting checks on the project" + +strategy_actor: local/strategist +execution_actor: local/executor + +definition_of_done: | + All linting checks pass with zero errors. + +reusable: true +read_only: true +``` + +--- + +### Action with Estimation and Review Actors + +Adds optional `estimation_actor` and `review_actor`, typed `arguments`, an +`automation_profile`, and `invariants`: + +```yaml +# examples/actions/estimation-actor.yaml +name: local/large-refactor +description: "Large-scale code refactoring with cost estimation" +long_description: | + Performs a large-scale refactoring of a codebase module. An estimation + actor runs after Strategize to predict cost, risk, and duration before + execution proceeds. + +strategy_actor: local/strategist +execution_actor: local/executor +estimation_actor: local/estimator +review_actor: local/reviewer + +definition_of_done: | + Refactoring complete. All tests pass. No regressions introduced. + Code review approved by the review actor. + +reusable: true +read_only: false + +arguments: + - name: target_module + type: string + required: true + description: "Module path to refactor" + - name: max_files_changed + type: integer + required: false + description: "Maximum number of files to modify" + default: 50 + min_value: 1 + max_value: 500 + +automation_profile: trusted + +invariants: + - "All existing tests must continue to pass" + - "Public API signatures must not change without deprecation" +``` + +--- + +### Read-Only Investigation Action + +Suitable for audits and architecture reviews that must not modify any files: + +```yaml +# examples/actions/read-only.yaml +name: local/architecture-review +description: "Review project architecture and produce a report" +long_description: | + Analyzes the project structure, dependency graph, and code patterns + to produce an architecture review report. Does not modify any files. + +strategy_actor: local/strategist +execution_actor: local/executor + +definition_of_done: | + Architecture review report generated covering: + - Module dependency graph + - Layer boundary compliance + - Circular dependency detection + - Code duplication analysis + +reusable: true +read_only: true +state: available +``` + +--- + +### Action with `inputs_schema` + +Uses `inputs_schema` for complex nested validation beyond basic argument types: + +```yaml +# examples/actions/inputs-schema.yaml +name: local/data-pipeline +description: "Build and validate a data processing pipeline" + +strategy_actor: local/strategist +execution_actor: local/executor + +definition_of_done: | + Pipeline runs end-to-end successfully. All stages produce valid + output. Data quality checks pass on final output. + +arguments: + - name: pipeline_name + type: string + required: true + description: "Name of the pipeline to build" + - name: dry_run + type: boolean + required: false + description: "Run in dry-run mode without writing output" + default: false + +inputs_schema: + type: object + properties: + stages: + type: array + items: + type: object + properties: + name: + type: string + transform: + type: string + required: [name, transform] + output_format: + type: string + enum: [csv, json, parquet] + required: + - stages +``` + +--- + +### Action with Multiple Invariants and `invariant_actor` + +Demonstrates `invariant_actor`, `validation_pattern` on a string argument, +and a rich invariant list: + +```yaml +# examples/actions/invariant-heavy.yaml +name: local/security-audit +description: "Comprehensive security audit of a project" + +strategy_actor: local/security-strategist +execution_actor: local/security-scanner +invariant_actor: local/invariant-resolver + +definition_of_done: | + All critical and high severity findings have been identified. + A complete security report has been generated with severity + classifications and remediation steps for each finding. + +arguments: + - name: severity_threshold + type: string + required: false + description: "Minimum severity to include in report" + default: "low" + validation_pattern: "^(critical|high|medium|low|informational)$" + - name: auto_fix + type: boolean + required: false + description: "Automatically create fix plans for critical findings" + default: false + +automation_profile: supervised + +invariants: + - "Never modify production database schemas during audit" + - "Never execute discovered exploit code against live systems" + - "All findings must include reproducible steps" + - "Secrets found during scanning must be redacted in reports" + - "Remediation fixes must not break existing tests" +``` + +--- + +## Python API Usage + +```python +from pathlib import Path +from cleveragents.action.schema import ActionConfigSchema + +# Load from a file +config = ActionConfigSchema.from_yaml_file(Path("examples/actions/simple.yaml")) + +print(config.name) # "local/lint-check" +print(config.strategy_actor) # "local/strategist" +print(config.read_only) # True +print(config.reusable) # True + +# Load from a YAML string +yaml_str = """ +name: local/my-action +description: My action +strategy_actor: local/strategist +execution_actor: local/executor +definition_of_done: Task is complete. +""" +config = ActionConfigSchema.from_yaml(yaml_str) + +# Access arguments +for arg in config.arguments: + print(arg.name, arg.type, arg.required) +``` + +### Environment Variable Interpolation + +String values may reference environment variables using `${VAR}` syntax. +Unresolved variables are left as-is: + +```yaml +name: local/deploy +description: "Deploy to ${TARGET_ENV}" +strategy_actor: local/strategist +execution_actor: local/executor +definition_of_done: "Deployment to ${TARGET_ENV} complete." +automation_profile: ${DEPLOY_PROFILE} +``` + +```python +import os +os.environ["TARGET_ENV"] = "staging" +os.environ["DEPLOY_PROFILE"] = "supervised" + +config = ActionConfigSchema.from_yaml_file(Path("deploy.yaml")) +# config.description == "Deploy to staging" +# config.automation_profile == "supervised" +``` + +--- + +## CLI Usage + +Actions are managed through the `agents action` command group. See +[Action CLI Reference](../reference/action_cli.md) for full details. + +```bash +# Create an action from a YAML config file +agents action create --config action.yaml + +# List all available actions +agents action list + +# Filter by namespace or state +agents action list --namespace local +agents action list --state available + +# Show full details for an action +agents action show local/lint-check +agents action show local/lint-check --format json + +# Archive (soft-delete) an action +agents action archive local/old-action +``` + +--- + +## Validation Errors + +`ActionConfigSchema` produces clear, actionable error messages. Common +failure modes: + +| Scenario | Error | +|----------|-------| +| `name` missing namespace | `Invalid action name '…'. Names must follow the namespace/name format` | +| `strategy_actor` not namespaced | `Invalid actor name '…'. Actor names must follow the namespace/name format` | +| `state` set to `draft` | `Invalid state 'draft'. Allowed states: archived, available` | +| Unknown argument `type` | `Invalid argument type '…'. Allowed types: boolean, float, integer, list, string` | +| Extra top-level key | `Extra inputs are not permitted` | +| Empty YAML | `YAML string is empty. Provide a valid action YAML configuration.` | +| Non-mapping YAML | `Action YAML must be a mapping (key: value), got …` | + +--- + +## See Also + +- [`docs/schema/action.schema.yaml`](../../schema/action.schema.yaml) — Formal schema definition +- [Action CLI Reference](../reference/action_cli.md) — `agents action` command group +- [`cleveragents.actor`](actor.md) — Actor system (actors referenced by actions) +- [`cleveragents.config`](config.md) — Application configuration +- [ADR-006 Plan Lifecycle](../adr/ADR-006-plan-lifecycle.md) — Design rationale for the plan/action model diff --git a/docs/api/index.md b/docs/api/index.md index 8da0de416..e8fa27e86 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -11,6 +11,7 @@ classes, functions, and exceptions with signatures and usage examples. | [`cleveragents.core`](core.md) | Exception hierarchy, error handling, retry patterns, async cleanup | | [`cleveragents.a2a`](a2a.md) | Agent-to-Agent (A2A) protocol facade, transport, models, and events | | [`cleveragents.actor`](actor.md) | Actor registry, configuration, loader, and compiler | +| [`cleveragents.action`](action.md) | Action configuration schema, validation pipeline, and YAML loader | | [`cleveragents.skills`](skills.md) | Skill framework — schema, protocol, registry, discovery, and inline executor | | [`cleveragents.tool`](tool.md) | Tool runtime, lifecycle, registry, router, and container executor | | [`cleveragents.mcp`](mcp.md) | Model Context Protocol (MCP) adapter, client, registry, and sandbox | diff --git a/mkdocs.yml b/mkdocs.yml index 48a98aa71..9f84ab93c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,7 @@ nav: - Core Utilities: api/core.md - A2A Protocol: api/a2a.md - Actor System: api/actor.md + - Action Schema: api/action.md - Skills: api/skills.md - Tools: api/tool.md - MCP Adapter: api/mcp.md -- 2.52.0