From 8f35b08a751fd4a97ac2faae9f1b97abf24f3cd1 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Mon, 13 Apr 2026 08:37:44 +0000 Subject: [PATCH] docs: add troubleshooting guide, FAQ, and config reference [AUTO-DOCS-6] - Create docs/guides/troubleshooting.md: comprehensive troubleshooting guide covering installation, LLM provider, database, plan execution, TUI, and test suite issues with step-by-step remediation - Create docs/guides/faq.md: practical FAQ covering setup, actors, tools/skills, plans, testing, and contributing - Create docs/guides/index.md: guides landing page with navigation table - Expand docs/api/config.md: add complete CLEVERAGENTS_* env var reference, config file TOML format, actor YAML format, and action YAML format - Update mkdocs.yml: add Guides section to site navigation --- docs/api/config.md | 261 +++++++++++ docs/guides/faq.md | 326 ++++++++++++++ docs/guides/index.md | 20 + docs/guides/troubleshooting.md | 776 +++++++++++++++++++++++++++++++++ mkdocs.yml | 4 + 5 files changed, 1387 insertions(+) create mode 100644 docs/guides/faq.md create mode 100644 docs/guides/index.md create mode 100644 docs/guides/troubleshooting.md diff --git a/docs/api/config.md b/docs/api/config.md index 8e7bf59b8..2aa156aad 100644 --- a/docs/api/config.md +++ b/docs/api/config.md @@ -98,3 +98,264 @@ from cleveragents.config.security_scanner import scan_for_secrets issues = scan_for_secrets({"db_url": "postgresql://user:password@host/db"}) # → [SecretIssue(field="db_url", pattern="password_in_url")] ``` + +--- + +## Complete Environment Variable Reference + +All `CLEVERAGENTS_*` environment variables recognised by the settings system. +Variables marked **secret** are redacted from logs and CLI output. + +### Provider and Model Selection + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_DEFAULT_PROVIDER` | `str` | auto-detected | Pin the global LLM provider (`openai`, `anthropic`, `google`, `azure`, `openrouter`, `groq`, `together`, `cohere`, `gemini`) | +| `CLEVERAGENTS_DEFAULT_MODEL` | `str` | provider default | Pin the global model ID | +| `CLEVERAGENTS_FALLBACK_PROVIDERS` | `str` | `""` | Comma-separated ordered list of fallback providers (e.g. `anthropic,openrouter`) | + +### Provider API Keys + +| Environment Variable | Provider | Secret | +|---------------------|----------|--------| +| `OPENAI_API_KEY` | OpenAI | ✓ | +| `ANTHROPIC_API_KEY` | Anthropic | ✓ | +| `GOOGLE_API_KEY` | Google | ✓ | +| `GOOGLE_GENAI_API_KEY` | Google (alias) | ✓ | +| `GEMINI_API_KEY` | Gemini | ✓ | +| `GOOGLE_GEMINI_API_KEY` | Gemini (alias) | ✓ | +| `AZURE_OPENAI_API_KEY` | Azure OpenAI | ✓ | +| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI | — | +| `AZURE_OPENAI_DEPLOYMENT` | Azure OpenAI | — | +| `OPENROUTER_API_KEY` | OpenRouter | ✓ | +| `CLEVERAGENTS_OPENROUTER_ORGANIZATION` | OpenRouter | — | +| `GROQ_API_KEY` | Groq | ✓ | +| `TOGETHER_API_KEY` | Together | ✓ | +| `COHERE_API_KEY` | Cohere | ✓ | +| `HF_TOKEN` | Hugging Face | ✓ | + +### Paths and Storage + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_DATA_DIR` | `path` | `~/.local/share/cleveragents` | Root directory for database, logs, and runtime data | +| `CLEVERAGENTS_CONFIG_PATH` | `path` | `~/.config/cleveragents/config.toml` | Path to the TOML configuration file | +| `CLEVERAGENTS_ACTOR_PATH` | `path` | `~/.config/cleveragents/actors` | Directory scanned for custom actor YAML files | +| `CLEVERAGENTS_DB_URL` | `str` | SQLite in `CLEVERAGENTS_DATA_DIR` | Database URL (SQLite, PostgreSQL, MySQL, or DuckDB) | + +### Budget and Cost Controls + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_BUDGET_PER_PLAN` | `int` | unlimited | Maximum tokens consumed per plan execution | +| `CLEVERAGENTS_BUDGET_PER_DAY` | `int` | unlimited | Maximum tokens consumed per calendar day | + +### Actor Defaults + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_ACTOR__DEFAULT__ESTIMATION` | `str` | `""` | Name of the actor used for cost/effort estimation | +| `CLEVERAGENTS_ACTOR__DEFAULT__INVARIANT` | `str` | `""` | Name of the actor used for invariant reconciliation | + +### Logging and Observability + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_LOG_LEVEL` | `str` | `WARNING` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | +| `CLEVERAGENTS_LOG_FORMAT` | `str` | `text` | Log format: `text` or `json` | +| `CLEVERAGENTS_LANGSMITH_ENABLED` | `bool` | `false` | Enable LangSmith tracing | +| `CLEVERAGENTS_LANGSMITH_PROJECT` | `str` | `""` | LangSmith project name | +| `CLEVERAGENTS_LANGSMITH_API_KEY` | `str` | `""` | LangSmith API key (secret) | +| `CLEVERAGENTS_LANGSMITH_ENDPOINT` | `str` | LangSmith default | LangSmith endpoint URL | +| `CLEVERAGENTS_LANGSMITH_USER_ID` | `str` | `""` | LangSmith user ID for trace attribution | +| `CLEVERAGENTS_LANGSMITH_TAGS` | `str` | `""` | Comma-separated tags added to all LangSmith traces | + +### Testing + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_TESTING_USE_MOCK_AI` | `bool` | `false` | Force the in-repo mock provider; disables all real API calls | + +### TUI + +| Environment Variable | Type | Default | Description | +|---------------------|------|---------|-------------| +| `CLEVERAGENTS_TUI_ANIMATIONS` | `bool` | `true` | Enable/disable TUI animations | + +--- + +## Configuration File + +CleverAgents reads a TOML configuration file from `~/.config/cleveragents/config.toml` +(or the path set by `CLEVERAGENTS_CONFIG_PATH`). Environment variables always take +precedence over file values. + +```toml +# ~/.config/cleveragents/config.toml + +[defaults] +provider = "anthropic" +model = "claude-sonnet-4-20250514" +fallback_providers = ["openrouter", "openai"] + +[budget] +per_plan = 100000 +per_day = 1000000 + +[actor.default] +estimation = "local/my-estimator" +invariant = "local/my-invariant-checker" + +[logging] +level = "INFO" +format = "json" + +[langsmith] +enabled = true +project = "my-project" +``` + +--- + +## Actor Configuration YAML Format + +Custom actors are defined as YAML files placed in `~/.config/cleveragents/actors/` +(or the path set by `CLEVERAGENTS_ACTOR_PATH`). + +### Minimal LLM Actor + +```yaml +name: local/my-assistant # Required — must be namespace/identifier +type: llm # Required — llm | tool | graph +description: My assistant # Required +model: gpt-4o # Required for llm and graph types +version: "1.0" # Optional +``` + +### LLM Actor with Skills + +```yaml +name: local/code-assistant +type: llm +description: Code-focused assistant with file and git tools +model: claude-sonnet-4-20250514 +version: "1.0" + +skills: + - local/file-ops + - local/git-ops +``` + +### Graph Actor (Multi-Node Workflow) + +```yaml +name: local/dev-pipeline +type: graph +description: Multi-step development pipeline +model: gpt-4o +version: "1.0" + +skills: + - local/file-ops + +route: + entry_node: planner + exit_nodes: + - reviewer + + nodes: + - id: planner + type: agent + name: Planner + description: Plans the implementation + config: + model: gpt-4o + prompt: "Analyze requirements and create a plan." + + - id: implementer + type: agent + name: Implementer + description: Implements the plan + config: + model: gpt-4o + prompt: "Implement the changes per the plan." + + - id: gate + type: conditional + name: Quality Gate + description: Routes based on lint result + config: + conditions: + - check: "state.get('lint_ok') == True" + route_to: reviewer + - check: "state.get('lint_ok') == False" + route_to: planner + + - id: reviewer + type: agent + name: Reviewer + description: Reviews the implementation + config: + model: gpt-4o + prompt: "Review the implementation for correctness." + + edges: + - from_node: planner + to_node: implementer + - from_node: implementer + to_node: gate + - from_node: gate + to_node: planner + - from_node: gate + to_node: reviewer +``` + +See [Actor Configuration Reference](../reference/actor_config.md) for the full field listing and validation rules. + +--- + +## Action Configuration YAML Format + +Actions define high-level tasks. They are typically created via the CLI +(`agents action create`) but can also be written as YAML files. + +```yaml +name: local/refactor-auth +description: Refactor the authentication module to use async patterns +version: "1.0" + +# Actor to use for this action +actor: local/dev-pipeline + +# Automation profile (manual | review | supervised | cautious | trusted | autonomous | ci | full-auto) +automation_profile: trusted + +# Resources this action operates on +resources: + - type: git-checkout + path: /path/to/repo + name: main-repo + +# Invariants enforced for every plan spawned from this action +invariants: + - "All API changes must maintain backward compatibility" + - "Test coverage must not decrease" + +# Definition of Done +definition_of_done: + must: + - "All existing tests pass" + - "New tests cover the changed code" + should: + - "Cyclomatic complexity does not increase" +``` + +--- + +## Related Documentation + +- [ADR-024 Configuration System](../adr/ADR-024-configuration-system.md) — design rationale +- [ADR-025 Observability & Logging](../adr/ADR-025-observability-and-logging.md) — LangSmith integration details +- [Actor Configuration Reference](../reference/actor_config.md) — full actor YAML schema +- [Diagnostics Check List](../reference/diagnostics_checks.md) — `agents diagnostics` checks +- [Troubleshooting Guide](../guides/troubleshooting.md) — common configuration problems and fixes diff --git a/docs/guides/faq.md b/docs/guides/faq.md new file mode 100644 index 000000000..34ad50b96 --- /dev/null +++ b/docs/guides/faq.md @@ -0,0 +1,326 @@ +# Frequently Asked Questions + +Quick answers to common questions about CleverAgents. For deeper dives, follow the links to the relevant documentation. + +> **Note:** The existing [Architecture FAQ](../faq.md) covers advanced architectural questions about ACMS, dependency closures, parallel execution, and automation profiles. This guide focuses on practical day-to-day usage questions. + +--- + +## General + +### What is CleverAgents? + +CleverAgents is a Python-first automation platform that lets you build, run, and manage AI agents for software development tasks. It provides: + +- A unified `agents` CLI and interactive Textual TUI +- A structured plan lifecycle (Strategize → Execute → Apply) with a full decision tree +- Multi-provider LLM support (OpenAI, Anthropic, Google, Azure, Groq, and more) +- A git worktree sandbox for safe, isolated plan execution +- SQLite-backed local persistence for sessions, plans, and decisions +- An Actor system for composing reusable agent workflows + +See the [README](../../README.md) for a full feature overview. + +### How does CleverAgents differ from using LangChain/LangGraph directly? + +CleverAgents is built *on top of* LangChain/LangGraph and adds: + +| Feature | LangChain/LangGraph | CleverAgents | +|---------|--------------------|----| +| Provider switching | Manual wiring | Auto-detected from env vars | +| Plan lifecycle | Custom | Built-in Strategize/Execute/Apply | +| Decision tracking | None | Full decision tree with correction | +| Sandbox isolation | None | Git worktree + filesystem overlays | +| Invariant enforcement | None | Multi-scope invariant system | +| CLI/TUI | None | Unified `agents` CLI + Textual TUI | +| Persistence | Custom | SQLite with Alembic migrations | +| Actor system | Chains/Graphs | Named, versioned, YAML-configured actors | + +If you want full control over every LangGraph node and edge, use LangGraph directly. If you want a structured, production-ready agent platform with batteries included, use CleverAgents. + +### Is CleverAgents open source? + +Yes. CleverAgents Core is licensed under the Apache 2.0 License. See [LICENSE](../../LICENSE) and [ATTRIBUTIONS.md](../../ATTRIBUTIONS.md). + +--- + +## Setup and Configuration + +### Can I use CleverAgents without an LLM API key? + +Yes, for **testing and development** purposes. Set the mock provider environment variable: + +```bash +export CLEVERAGENTS_TESTING_USE_MOCK_AI=true +agents tell --actor mock/default "Hello" +``` + +The mock provider returns deterministic responses without hitting any external API. It is used by the full test suite to avoid API costs. + +For production use, you need at least one real provider API key. See [LLM provider configuration](../../README.md#llm-provider-configuration) for the list of supported providers. + +### Where does CleverAgents store its data? + +| Data type | Default location | +|-----------|-----------------| +| Database | `~/.local/share/cleveragents/cleveragents.db` | +| Config file | `~/.config/cleveragents/config.toml` | +| Actors | `~/.config/cleveragents/actors/` | +| Personas | `~/.config/cleveragents/personas/` | +| Logs | `~/.local/share/cleveragents/logs/` | + +Override the data directory: + +```bash +export CLEVERAGENTS_DATA_DIR=/custom/path +``` + +Override the config file: + +```bash +export CLEVERAGENTS_CONFIG_PATH=/custom/config.toml +``` + +### How do I pin a specific LLM provider and model? + +```bash +# Via environment variables +export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic +export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514 + +# Via config file (~/.config/cleveragents/config.toml) +[defaults] +provider = "anthropic" +model = "claude-sonnet-4-20250514" + +# Via actor configuration (most specific) +agents actor set-default anthropic/claude-sonnet-4-20250514 +``` + +### How do I check which provider is being used? + +```bash +agents diagnostics +``` + +This prints the detected provider, model, and API key status for every supported provider. + +--- + +## Actors + +### How do I add a custom actor? + +1. Create a YAML file in `~/.config/cleveragents/actors/`: + +```yaml +# ~/.config/cleveragents/actors/my-assistant.yaml +name: local/my-assistant +type: llm +description: My custom assistant +model: gpt-4o +``` + +2. Verify it is registered: + +```bash +agents actor list +``` + +3. Use it: + +```bash +agents tell --actor local/my-assistant "Hello" +``` + +For graph actors with multiple nodes, see [Actor Configuration Reference](../reference/actor_config.md). + +### What is the difference between built-in and custom actors? + +- **Built-in actors** (`/`, e.g., `openai/gpt-4o`) are immutable and auto-generated from the provider registry. You cannot modify or delete them. +- **Custom actors** must be named `local/` (or another custom namespace). They are stored in YAML files and fully configurable. + +The default actor cannot be removed. Use `--unsafe` when adding or updating actors marked as unsafe. + +### How do I set a default actor? + +```bash +agents actor set-default openai/gpt-4o +``` + +Once set, commands like `agents tell` and `agents build` do not require `--actor`. + +### Can I use an actor with a local LLM (Ollama)? + +Yes. Configure an actor pointing to an OpenAI-compatible endpoint: + +```yaml +name: local/ollama-llama3 +type: llm +description: Local Llama 3 via Ollama +model: llama3 +``` + +Set the base URL to your Ollama instance: + +```bash +export OPENAI_API_BASE=http://localhost:11434/v1 +export OPENAI_API_KEY=ollama # Ollama accepts any non-empty key +``` + +Then use the actor: + +```bash +agents tell --actor local/ollama-llama3 "Hello" +``` + +--- + +## Tools and Skills + +### How do I create a custom tool? + +Tools are Python functions registered with the tool registry. Create a tool definition: + +```python +# my_tools/search.py +from cleveragents.tool import tool + +@tool(name="local/web-search", description="Search the web") +def web_search(query: str) -> str: + """Search the web for the given query.""" + # implementation + return results +``` + +Register it: + +```bash +agents tool add local/web-search --path my_tools/search.py +``` + +See [Tool API Reference](../api/tool.md) for the full tool lifecycle and registry API. + +### What is the difference between a Tool and a Skill? + +- **Tools** are individual callable functions that actors can invoke (like LangChain tools). They perform a single operation. +- **Skills** are collections of related tools bundled together as a reusable unit. An actor declares which skills it uses, and the skill's tools become available to it. + +Example: a `local/git-ops` skill might bundle `git_commit`, `git_push`, `git_diff`, and `git_log` tools. + +--- + +## Plans and Actions + +### What is the difference between an Action and a Plan? + +- An **Action** is a high-level task definition — it describes *what* you want to accomplish, the resources involved, invariants to enforce, and the automation profile to use. +- A **Plan** is a concrete execution instance of an Action. When you run an action, CleverAgents creates a Plan and runs it through the Strategize → Execute → Apply lifecycle. + +Think of Actions as templates and Plans as runs. + +### How does the git worktree sandbox work? + +When a plan executes against a git repository resource, CleverAgents: + +1. Creates a new branch `cleveragents/plan-` from the current HEAD. +2. Creates a temporary git worktree in a system temp directory. +3. The actor writes all changes inside the worktree (not the original repo). +4. On **Apply**: stages and commits all changes in the worktree, then merges the sandbox branch back into the original branch. +5. On **Rollback**: discards the worktree entirely — the original branch is untouched. + +This means you can always safely reject a plan's changes without any manual cleanup. + +See [Git Worktree Sandbox](../modules/git-worktree-sandbox.md) for the full technical reference. + +### What is the A2A protocol? + +A2A (Agent-to-Agent) is a JSON-RPC 2.0 protocol that CleverAgents uses internally to wire the CLI and TUI to live application services (session, plan, registry, event). It follows the standard JSON-RPC 2.0 wire format with `method`, `id`, `result`, and `error` fields. + +See [A2A Protocol Reference](../api/a2a.md) for details. + +### How do I correct a bad decision in a plan? + +Use `agents plan correct`: + +```bash +# View the decision tree +agents plan tree + +# Correct a specific decision +agents plan correct \ + --mode revert \ + --guidance "Use gRPC instead of REST for this service" +``` + +The system marks the original decision as superseded, creates a new decision with your guidance, and recomputes only the affected downstream decisions — preserving all unrelated work. + +--- + +## Testing + +### How do I run tests without hitting real APIs? + +Set the mock AI environment variable: + +```bash +export CLEVERAGENTS_TESTING_USE_MOCK_AI=true + +# Run all tests +nox -s unit_tests +nox -s integration_tests + +# Run a specific feature +nox -s unit_tests -- features/plan_model.feature +``` + +The mock provider is used by the full CI test suite and never hits external APIs. + +### What testing frameworks does CleverAgents use? + +- **Behave** (BDD/Gherkin) for unit-level and scenario tests — feature files live under `features/` +- **Robot Framework** for integration and end-to-end tests — suites live under `robot/` +- **ASV** (airspeed velocity) for performance benchmarks — under `benchmarks/` +- **Coverage**: `coverage.py` with branch coverage, enforced at **≥97%** + +Always run tests through `nox` sessions, never invoke `behave` or `robot` directly. + +See [Testing Guide](../development/testing.md) for full details. + +--- + +## Contributing + +### How do I contribute to CleverAgents? + +1. Read [CONTRIBUTING.md](../../CONTRIBUTING.md) — it covers the full development workflow, coding standards, and review process. +2. Set up your development environment: + ```bash + git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git + cd cleveragents-core + python -m venv .venv && source .venv/bin/activate + pip install -e ".[dev,tests,docs,tui]" + bash scripts/setup-dev.sh + ``` +3. Create a feature branch and make your changes. +4. Ensure all checks pass: + ```bash + nox -s format lint typecheck unit_tests integration_tests coverage_report + ``` +5. Open a pull request against `master`. + +### Where do I report bugs? + +File issues at: [https://git.cleverthis.com/cleveragents/cleveragents-core/issues](https://git.cleverthis.com/cleveragents/cleveragents-core/issues) + +Include: +- Output of `agents diagnostics` +- Output of `agents --version` +- Your Python version (`python --version`) +- Debug logs (`CLEVERAGENTS_LOG_LEVEL=DEBUG agents 2>debug.log`) + +--- + +## Troubleshooting + +For detailed troubleshooting steps, see the [Troubleshooting Guide](troubleshooting.md). diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 000000000..9a326f764 --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,20 @@ +# Guides + +Practical how-to guides for working with CleverAgents. + +## Available Guides + +| Guide | Description | +|-------|-------------| +| [Troubleshooting](troubleshooting.md) | Step-by-step fixes for installation, provider, database, plan execution, TUI, and test suite issues | +| [FAQ](faq.md) | Frequently asked questions about CleverAgents — setup, actors, plans, testing, and contributing | + +## Other Documentation + +- **[API Reference](../api/index.md)** — Python API for `cleveragents` modules +- **[Configuration Reference](../api/config.md)** — All `CLEVERAGENTS_*` environment variables, config file format, actor YAML schema +- **[Reference](../reference/)** — Detailed reference pages for CLI commands, schemas, and subsystems +- **[Modules](../modules/)** — Deep-dive documentation for specific subsystems (git worktree sandbox, UKO, invariant reconciliation, etc.) +- **[Development](../development/)** — Contributor guides: testing, CI/CD, quality automation, ops runbook +- **[Architecture FAQ](../faq.md)** — Advanced architectural questions about ACMS, parallel execution, and automation profiles +- **[ADRs](../adr/index.md)** — Architecture Decision Records explaining *why* key design choices were made diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md new file mode 100644 index 000000000..86fc5bf9a --- /dev/null +++ b/docs/guides/troubleshooting.md @@ -0,0 +1,776 @@ +# Troubleshooting Guide + +This guide covers the most common issues encountered when installing, configuring, and running CleverAgents, along with step-by-step remediation instructions. + +--- + +## Table of Contents + +- [Installation Issues](#installation-issues) +- [LLM Provider Issues](#llm-provider-issues) +- [Database Issues](#database-issues) +- [Plan Execution Issues](#plan-execution-issues) +- [TUI Issues](#tui-issues) +- [Test Suite Issues](#test-suite-issues) +- [Common Error Messages](#common-error-messages) +- [Diagnostic Commands](#diagnostic-commands) +- [Getting Help](#getting-help) + +--- + +## Installation Issues + +### Python version mismatch + +CleverAgents requires **Python 3.11 or later**. Check your version: + +```bash +python --version +# or +python3 --version +``` + +If you see `Python 3.10.x` or earlier, install a supported version. The project ships a `.python-version` file for [pyenv](https://github.com/pyenv/pyenv) users: + +```bash +# Install pyenv (if not already installed) +curl https://pyenv.run | bash + +# Install the required Python version +pyenv install $(cat .python-version) +pyenv local $(cat .python-version) +``` + +### Virtual environment not activated + +Symptoms: `agents: command not found` or `ModuleNotFoundError: No module named 'cleveragents'`. + +```bash +# Create and activate a virtual environment +python -m venv .venv +source .venv/bin/activate # Linux/macOS +.venv\Scripts\activate # Windows + +# Verify activation +which python # should point to .venv/bin/python +``` + +### `pip install` failures + +**Dependency resolution errors:** + +```bash +# Upgrade pip first +pip install --upgrade pip + +# Install with all extras +pip install -e ".[dev,tests,docs,tui]" +``` + +**Build errors for compiled extensions:** + +```bash +# Install build tools (Debian/Ubuntu) +sudo apt-get install build-essential python3-dev + +# Install build tools (macOS) +xcode-select --install +``` + +**Lock file conflicts (uv users):** + +```bash +# Sync from the lock file +uv sync + +# Or regenerate the lock file +uv lock --upgrade +``` + +### Pre-commit hooks failing on first setup + +```bash +# Run the setup script +bash scripts/setup-dev.sh + +# Or install hooks manually +pre-commit install +pre-commit run --all-files +``` + +--- + +## LLM Provider Issues + +### Missing API key + +**Symptom:** `Error [525] CONFIGURATION_ERROR: No LLM provider is configured` + +CleverAgents requires at least one provider API key. Run diagnostics to see which keys are detected: + +```bash +agents diagnostics +``` + +Set the appropriate key for your provider: + +```bash +# OpenAI +export OPENAI_API_KEY="sk-..." + +# Anthropic +export ANTHROPIC_API_KEY="sk-ant-..." + +# Google +export GOOGLE_API_KEY="AIza..." + +# Groq +export GROQ_API_KEY="gsk_..." +``` + +Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist it across sessions. + +### Wrong provider selected + +**Symptom:** The system uses a different provider than expected. + +The provider auto-detection order is: + +``` +openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini +``` + +To pin a specific provider: + +```bash +export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic +export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514 +``` + +Or set it in your config file (`~/.config/cleveragents/config.toml`): + +```toml +[defaults] +provider = "anthropic" +model = "claude-sonnet-4-20250514" +``` + +### Model not found + +**Symptom:** `Error [527] MODEL_UNAVAILABLE: Model 'gpt-5' not found` + +Verify the model name is correct for your provider. Check the capability matrix: + +```bash +# List available actors (which embed provider/model choices) +agents actor list + +# Check provider documentation +# See: docs/reference/providers.md +``` + +Common model identifiers: + +| Provider | Example model IDs | +|----------|------------------| +| OpenAI | `gpt-4o`, `gpt-4o-mini`, `o1-preview` | +| Anthropic | `claude-sonnet-4-20250514`, `claude-3-5-haiku-20241022` | +| Google | `gemini-2.0-flash`, `gemini-1.5-pro` | +| Groq | `llama-3.3-70b-versatile`, `mixtral-8x7b-32768` | + +### Rate limit errors + +**Symptom:** `Error [429] RATE_LIMITED: Too many requests` + +CleverAgents has built-in retry logic with exponential backoff. If you hit persistent rate limits: + +1. **Reduce concurrency** — avoid running multiple parallel plans simultaneously. +2. **Switch to a fallback provider:** + +```bash +export CLEVERAGENTS_FALLBACK_PROVIDERS="anthropic,openrouter" +``` + +3. **Set a budget limit** to prevent runaway token usage: + +```bash +export CLEVERAGENTS_BUDGET_PER_PLAN=50000 # tokens per plan +export CLEVERAGENTS_BUDGET_PER_DAY=500000 # tokens per day +``` + +### Azure OpenAI configuration + +Azure requires additional environment variables beyond the API key: + +```bash +export AZURE_OPENAI_API_KEY="your-key" +export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com" +export AZURE_OPENAI_DEPLOYMENT="your-deployment-name" +export CLEVERAGENTS_DEFAULT_PROVIDER=azure +``` + +### Token limit exceeded + +**Symptom:** `Error [526] TOKEN_LIMIT: Context window exceeded` + +- Switch to a model with a larger context window (e.g., `gpt-4o` supports 128K tokens). +- Break the task into smaller sub-plans. +- Reduce the number of resources included in the plan scope. + +--- + +## Database Issues + +### Migration failures + +**Symptom:** `Error [522] DATABASE_ERROR: alembic migration failed` + +Run migrations manually: + +```bash +# Check current migration state +alembic current + +# Apply pending migrations +alembic upgrade head + +# If migrations are out of sync, check history +alembic history --verbose +``` + +If the database is corrupted, you can reset it (this deletes all local data): + +```bash +# Backup first +cp ~/.local/share/cleveragents/cleveragents.db ~/.local/share/cleveragents/cleveragents.db.bak + +# Remove and let CleverAgents recreate on next run +rm ~/.local/share/cleveragents/cleveragents.db +agents diagnostics +``` + +### Database locked + +**Symptom:** `Error [522] DATABASE_ERROR: database is locked` + +Another process is holding an exclusive lock on the SQLite database. Find and stop it: + +```bash +# Find processes using the database file +lsof ~/.local/share/cleveragents/cleveragents.db + +# Or check for stale lock files +ls ~/.local/share/cleveragents/*.db-wal +ls ~/.local/share/cleveragents/*.db-shm +``` + +If no other process is running, the lock files may be stale: + +```bash +rm -f ~/.local/share/cleveragents/cleveragents.db-wal +rm -f ~/.local/share/cleveragents/cleveragents.db-shm +``` + +### Schema mismatch + +**Symptom:** `Error [522] DATABASE_ERROR: no such column: ...` or `table ... has no column named ...` + +Your database schema is out of date. Run: + +```bash +alembic upgrade head +``` + +If you have a very old database, you may need to stamp it at the base revision first: + +```bash +alembic stamp base +alembic upgrade head +``` + +### Data directory not writable + +**Symptom:** `Error [523] FILESYSTEM_ERROR: Permission denied: '/home/user/.local/share/cleveragents'` + +```bash +# Fix permissions +chmod 755 ~/.local/share/cleveragents +chmod 644 ~/.local/share/cleveragents/cleveragents.db + +# Or use a custom data directory +export CLEVERAGENTS_DATA_DIR=/path/to/writable/dir +``` + +--- + +## Plan Execution Issues + +### Actor not found + +**Symptom:** `Error [404] NOT_FOUND: Actor 'local/my-actor' not found` + +```bash +# List all registered actors +agents actor list + +# Check actor YAML files are in the search path +agents actor list --verbose + +# Verify actor name format (must be namespace/identifier) +# Correct: local/my-actor +# Incorrect: my-actor +``` + +Custom actors must be placed in `~/.config/cleveragents/actors/` or a path configured via `CLEVERAGENTS_ACTOR_PATH`. + +### Actor configuration errors + +**Symptom:** `Schema validation failed for actor.yaml` + +Common actor YAML mistakes and fixes: + +```yaml +# WRONG — missing namespace +name: my-actor + +# CORRECT +name: local/my-actor +``` + +```yaml +# WRONG — llm type without model +name: local/my-actor +type: llm +description: My actor + +# CORRECT +name: local/my-actor +type: llm +description: My actor +model: gpt-4o +``` + +See [Actor Configuration Reference](../reference/actor_config.md) for the full schema. + +### Sandbox creation failure + +**Symptom:** `Error [521] EXECUTION_ERROR: SandboxCreationError: git worktree add failed` + +The git worktree sandbox requires the resource path to be a valid git repository root: + +```bash +# Verify the path is a git repository +git -C /path/to/resource rev-parse --git-dir + +# Ensure git is installed +git --version + +# Check disk space (worktrees need space) +df -h /tmp +``` + +If the repository has an existing worktree with the same name (from a crashed plan): + +```bash +# List existing worktrees +git worktree list + +# Remove stale worktrees +git worktree prune +git worktree remove /tmp/ca-sandbox-plan- --force +``` + +### Git worktree errors + +**Symptom:** `fatal: 'cleveragents/plan-...' is already checked out` + +A previous plan left a stale worktree. Clean it up: + +```bash +# In the repository directory +git worktree prune + +# List and remove specific stale worktrees +git worktree list +git worktree remove --force + +# Delete the stale branch +git branch -D cleveragents/plan- +``` + +### ChangeSet empty + +**Symptom:** Plan completes but no files are changed; `CommitResult` shows empty file lists. + +This usually means the actor did not write any changes to the sandbox path. Possible causes: + +1. **Actor wrote to the wrong path** — ensure the actor uses the sandbox path returned by `get_path()`, not the original resource path. +2. **All changes were identical to existing content** — git does not stage unchanged files. +3. **Actor exited early** — check plan logs for warnings or early termination. + +Debug by inspecting the plan's decision tree: + +```bash +agents plan tree +agents plan errors +``` + +### Plan stuck in Strategize phase + +**Symptom:** Plan does not progress past the Strategize phase. + +```bash +# Check plan status +agents plan status + +# View the decision tree +agents plan tree + +# Check for invariant violations blocking the transition +agents plan errors +``` + +If the automation profile requires human input at phase transitions, you may need to approve the transition: + +```bash +agents plan approve +``` + +### Invariant violation blocking plan + +**Symptom:** `INVARIANT_VIOLATED` event emitted; plan blocked at phase transition. + +```bash +# View active invariants +agents invariant list + +# View the specific violation +agents plan errors + +# Correct the decision that caused the violation +agents plan correct --guidance "..." +``` + +--- + +## TUI Issues + +### TUI fails to launch + +**Symptom:** `Error: No module named 'textual'` or blank screen on launch. + +```bash +# Install the TUI extra +pip install -e ".[tui]" + +# Verify Textual is installed +python -c "import textual; print(textual.__version__)" +``` + +### Terminal compatibility issues + +**Symptom:** Garbled output, missing colors, or broken layout. + +CleverAgents TUI requires a terminal with: +- 256-color or true-color support +- Unicode/UTF-8 support +- Minimum 80×24 terminal size + +```bash +# Check terminal color support +echo $TERM +echo $COLORTERM + +# Force true-color mode +export COLORTERM=truecolor + +# Increase terminal size or use a larger window +``` + +Recommended terminals: iTerm2, Alacritty, kitty, Windows Terminal, GNOME Terminal. + +### Display glitches or rendering artifacts + +```bash +# Force a terminal reset +reset + +# Try disabling animations +export CLEVERAGENTS_TUI_ANIMATIONS=false + +# Run with a specific color depth +TERM=xterm-256color agents tui +``` + +### TUI crashes on startup + +```bash +# Run with verbose logging to diagnose +CLEVERAGENTS_LOG_LEVEL=DEBUG agents tui 2>tui-debug.log +cat tui-debug.log +``` + +### Slash commands not working + +Ensure you are pressing `/` at the beginning of the input field. The slash command overlay lists all 67 available commands across 14 groups. Press `Escape` to dismiss it. + +--- + +## Test Suite Issues + +### Mock AI not working + +**Symptom:** Tests hit real APIs or fail with `No LLM provider configured`. + +Set the mock AI environment variable before running tests: + +```bash +export CLEVERAGENTS_TESTING_USE_MOCK_AI=true +nox -s unit_tests +``` + +Verify the mock is active: + +```bash +python -c " +import os +os.environ['CLEVERAGENTS_TESTING_USE_MOCK_AI'] = 'true' +from cleveragents.config.settings import Settings +s = Settings() +print('Provider:', s.provider) # should show 'mock' +" +``` + +### Coverage below 97% + +**Symptom:** `COVERAGE FAILED: 95.3% < 97% threshold` + +1. **Identify uncovered lines:** + +```bash +nox -s coverage_report -- --show-missing +``` + +2. **Add missing Behave scenarios** for the uncovered code paths. + +3. **Check for excluded files** — some files may be incorrectly excluded from coverage measurement in `pyproject.toml`. + +4. **Run coverage locally before pushing:** + +```bash +nox -s unit_tests +nox -s coverage_report +``` + +### Robot Framework errors + +**Symptom:** `robot: command not found` or `ImportError` in Robot suites. + +```bash +# Install test dependencies +pip install -e ".[tests]" + +# Run Robot tests via nox (never directly) +nox -s integration_tests + +# Run a specific Robot suite +nox -s integration_tests -- robot/suites/actor_cli.robot +``` + +**Symptom:** `FAIL: Setup failed: ...` + +Check that the test environment is clean: + +```bash +# Reset the test database +CLEVERAGENTS_DATA_DIR=/tmp/cleveragents-test agents diagnostics + +# Ensure mock AI is enabled for tests +export CLEVERAGENTS_TESTING_USE_MOCK_AI=true +``` + +### Behave step not found + +**Symptom:** `NotImplementedError: STEP NOT IMPLEMENTED` + +The Behave step definition is missing. Check `features/steps/` for the relevant step file and add the missing step implementation. + +### Pre-commit hook failures + +```bash +# Run all hooks manually +pre-commit run --all-files + +# Run a specific hook +pre-commit run ruff --all-files +pre-commit run pyright --all-files + +# Skip hooks temporarily (not recommended for CI) +git commit --no-verify -m "wip: ..." +``` + +--- + +## Common Error Messages + +### `Error [400] BAD_REQUEST: name must be in 'namespace/name' format` + +Actor, tool, or skill names must include a namespace prefix separated by `/`. + +- ❌ `my-actor` +- ✅ `local/my-actor` + +### `Error [401] UNAUTHORIZED: Invalid API key` + +The API key for the selected provider is invalid or expired. Regenerate it from the provider's dashboard and update your environment variable. + +### `Error [404] NOT_FOUND: Resource '...' not found` + +The referenced resource, actor, skill, or tool does not exist in the registry. Use `agents actor list`, `agents resource list`, or `agents tool list` to see what is registered. + +### `Error [409] CONFLICT: Actor '...' already exists` + +You are trying to register an actor with a name that is already taken. Use `agents actor update` to modify an existing actor, or choose a different name. + +### `Error [422] VALIDATION_FAILED: ...` + +A configuration value or input failed schema validation. The error message includes the field path and the validation rule that failed. See the relevant schema reference for the correct format. + +### `Error [500] INTERNAL: Unexpected error` + +An unhandled exception occurred. Enable debug logging to get the full traceback: + +```bash +CLEVERAGENTS_LOG_LEVEL=DEBUG agents 2>debug.log +cat debug.log +``` + +Report the issue with the log output at the [issue tracker](https://git.cleverthis.com/cleveragents/cleveragents-core/issues). + +### `Error [520] PROVIDER_ERROR: ...` + +The LLM provider returned an error. Common causes: + +- Invalid API key → check `agents diagnostics` +- Model not available in your region → try a different model +- Provider outage → check the provider's status page + +### `Error [521] EXECUTION_ERROR: SandboxCreationError` + +See [Sandbox creation failure](#sandbox-creation-failure) above. + +### `Error [522] DATABASE_ERROR: database is locked` + +See [Database locked](#database-locked) above. + +### `Error [525] CONFIGURATION_ERROR: No LLM provider is configured` + +No API key is set for any supported provider. See [Missing API key](#missing-api-key) above. + +### `Error [527] MODEL_UNAVAILABLE: ...` + +The requested model does not exist or is not accessible with your API key. See [Model not found](#model-not-found) above. + +--- + +## Diagnostic Commands + +### `agents diagnostics` + +Runs a comprehensive health check covering configuration, database, provider API keys, disk space, file permissions, and git availability. + +```bash +# Basic diagnostics (human-readable) +agents diagnostics + +# JSON output (useful for scripting) +agents diagnostics --format json + +# Fail with exit code 1 if any check errors (useful in CI) +agents diagnostics --check +``` + +See [Diagnostics Check List](../reference/diagnostics_checks.md) for the full list of checks and their remediation steps. + +### `agents actor list` + +Lists all registered actors, including built-in and custom actors. + +```bash +agents actor list +agents actor list --verbose # show full configuration +``` + +### `agents resource list` + +Lists all registered resources. + +```bash +agents resource list +agents resource list --type git-checkout +``` + +### `agents plan status ` + +Shows the current status and phase of a plan. + +```bash +agents plan status 01HZ... +``` + +### `agents plan tree ` + +Displays the full decision tree for a plan, showing every decision made during Strategize and Execute phases. + +```bash +agents plan tree 01HZ... +``` + +### `agents plan errors ` + +Lists errors and invariant violations associated with a plan. + +```bash +agents plan errors 01HZ... +``` + +### `agents config list` + +Shows the current effective configuration, including all `CLEVERAGENTS_*` environment variables and config file values. + +```bash +agents config list +agents config list --format json +``` + +--- + +## Getting Help + +### Documentation + +- **Full documentation:** [https://docs.cleverthis.com/cleveragents](https://docs.cleverthis.com/cleveragents) +- **API Reference:** [docs/api/](../api/index.md) +- **Configuration Reference:** [docs/api/config.md](../api/config.md) +- **Actor Configuration:** [docs/reference/actor_config.md](../reference/actor_config.md) +- **Provider Capability Matrix:** [docs/reference/providers.md](../reference/providers.md) +- **Diagnostics Check List:** [docs/reference/diagnostics_checks.md](../reference/diagnostics_checks.md) +- **FAQ:** [docs/guides/faq.md](faq.md) + +### Reporting Issues + +Before filing an issue, please: + +1. Run `agents diagnostics` and include the output. +2. Enable debug logging and include the relevant log lines: + ```bash + CLEVERAGENTS_LOG_LEVEL=DEBUG agents 2>debug.log + ``` +3. Include your Python version (`python --version`) and CleverAgents version (`agents --version`). + +File issues at: [https://git.cleverthis.com/cleveragents/cleveragents-core/issues](https://git.cleverthis.com/cleveragents/cleveragents-core/issues) + +### Community + +- Check existing issues and discussions before opening a new one. +- See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines. diff --git a/mkdocs.yml b/mkdocs.yml index 76940184b..9250e3da9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,10 @@ nav: - Automation Tracking: development/automation-tracking.md - Custom Sandbox Strategy: development/custom_sandbox_strategy.md - Documentation Writer: development/docs-writer.md + - Guides: + - Overview: guides/index.md + - Troubleshooting: guides/troubleshooting.md + - FAQ: guides/faq.md - Implementation Timeline: timeline.md - FAQ: faq.md - Reference: reference/ -- 2.52.0