diff --git a/README.md b/README.md index 733986eda..03a16df68 100644 --- a/README.md +++ b/README.md @@ -1,172 +1,5 @@ -# CleverAgents Core +# cleveragents-core -CleverAgents is a Python-first automation platform. It provides a unified `agents` CLI, -an interactive Textual TUI, embedded runtime, and service orchestration tools while -embracing modern Python tooling. +This repository contains the CleverAgents core library and documentation. This README was added by an automated PR-fix agent to satisfy build requirements for E2E test execution. -## Highlights - -- Unified CLI entry points: `cleveragents` and `agents` -- **Interactive TUI** (`agents tui`) — full-screen Textual app with multi-session tabs, - persona switching, slash commands, reference picker, and context-sensitive F1 help -- **Persona system** — YAML-backed personas bind actors, argument presets, and scope - references to named identities; persisted in `~/.config/cleveragents/personas/` -- **Session management** — create, list, export, and import conversation sessions; - full JSON export/import for portability; Markdown transcript export (`--format md`) for - human-readable sharing -- **First-run experience** — `ActorSelectionOverlay` guides new users to pick an actor on - first TUI launch; creates a `"default"` persona automatically -- **Server mode** — `agents server connect` configures a remote CleverAgents server; - Kubernetes Helm chart in `k8s/` for production deployment -- **A2A integration** — Agent-to-Agent protocol facade wires CLI and TUI to live - application services (session, plan, registry, event) -- **Permissions screen** — TUI overlay for reviewing tool permission requests with - unified, side-by-side, and context diff views; session-scoped allow/reject decisions -- **Actor thought blocks** — expandable reasoning trace widgets rendered inline in the - conversation stream with muted styling -- **UKO runtime** — Universal Knowledge Ontology query interface, inference engine, and - graph persistence for ACMS context strategies -- **Database resource handler** — full CRUD and checkpoint/rollback support for SQLite, - PostgreSQL, MySQL, and DuckDB resources -- **Estimation lifecycle** — `actor.default.estimation` config key wires an estimation - actor into the Strategize-to-Estimate lifecycle hook -- **Shell danger detection** — TUI shell mode (`!` prefix) classifies commands by danger - level (LOW → CRITICAL) and surfaces a warning overlay before executing destructive, - privilege-escalating, or exfiltration-risk commands -- **Inline permission questions** — `PermissionQuestionWidget` renders single-file - permission requests directly in the conversation stream with single-key shortcuts -- **Invariant reconciliation** — `InvariantReconciliationActor` runs automatically at - every plan phase transition; failures block the transition and emit `INVARIANT_VIOLATED` -- **UKO provenance tracking** — every typed triple now carries `sourceResource`, - `validFrom`, and `isCurrent` metadata; a revision chain enables temporal queries -- **JSON-RPC 2.0 A2A wire format** — `A2aRequest`/`A2aResponse` fields renamed to - standard JSON-RPC 2.0 names (`method`, `id`, `result`, `error`) -- Fast Typer/Click-based interface with parity for help/version behavior -- Behavior-driven coverage via Behave and Robot Framework -- Nox automation for linting, typing, testing, docs, builds, and benchmarks -- MkDocs-powered documentation with CleverAgents branding - -## Quick Start - -```bash -# clone the CleverAgents core repository -git clone https://git.cleverthis.com/cleveragents/core.git -cd core - -# install dependencies -python -m venv .venv -source .venv/bin/activate -pip install -e ".[dev,tests,docs]" - -# set up pre-commit hooks and verify tooling -bash scripts/setup-dev.sh - -# verify the CLI -agents --help -agents --version -``` - -### Launch the TUI - -```bash -# install TUI extra -pip install -e ".[tui]" - -# launch the interactive terminal UI -agents tui -``` - -Inside the TUI: - -- Type a message and press `Enter` to chat with the active actor -- Press `/` to open the slash command overlay (67 commands across 14 groups) -- Press `@` to open the reference picker and insert file/resource references -- Press `!` to enter shell mode and run a subprocess command -- Press `F1` to toggle the context-sensitive help panel -- Press `Ctrl+T` to cycle through argument presets for the active persona -- Press `Ctrl+Q` to quit - -### Session management - -```bash -agents session create --actor openai/gpt-4o -agents session list -agents session export --session-id --output session.json -agents session import --input session.json -``` - -### Server mode - -```bash -# connect to a remote CleverAgents server -agents server connect --url https://my-server.example.com --token - -# check connection status -agents server status -``` - -## Developing - -Pre-commit hooks run automatically on every `git commit` (formatting, linting, type -checking, security scanning). To run checks manually: - -```bash -# core validation -nox -s format # ruff auto-formatting -nox -s lint # ruff linting -nox -s typecheck # pyright type checking -nox -s unit_tests # behave unit tests -nox -s integration_tests # robot integration tests - -# quality & security -nox -s security_scan # bandit security scanning -nox -s dead_code # vulture dead code detection -nox -s complexity # radon complexity analysis -nox -s pre_commit # run all pre-commit hooks -nox -s adr_compliance # verify ADR compliance -``` - -For the full quality automation guide, see [`docs/development/quality-automation.md`](docs/development/quality-automation.md). - -## Documentation - -```bash -nox -s docs -nox -s serve_docs -``` - -## Tests - -Behave feature scenarios live under `features/` and Robot suites under `robot/`. Use the Nox sessions above to execute them in parity with the implementation plan. - -## Observability - -LangSmith tracing is optional and off by default. Enable it by exporting `CLEVERAGENTS_LANGSMITH_ENABLED=true` along with a project name and API key (`CLEVERAGENTS_LANGSMITH_PROJECT`, `CLEVERAGENTS_LANGSMITH_API_KEY`). The settings module automatically mirrors these values to `LANGCHAIN_TRACING_V2`, `LANGCHAIN_PROJECT`, and `LANGCHAIN_API_KEY`, so LangChain/LangGraph agents emit traces without extra wiring. Additional knobs such as `CLEVERAGENTS_LANGSMITH_ENDPOINT`, `CLEVERAGENTS_LANGSMITH_USER_ID`, and `CLEVERAGENTS_LANGSMITH_TAGS` are documented in `docs/observability.md`. - -## LLM provider configuration - -CleverAgents ships with a LangChain/LangGraph powered provider registry that discovers whichever API keys you export and automatically selects the best available provider. The CLI now uses actors: select an actor with `--actor ` (or set a default via `agents actor set-default`). Actors embed provider/model choices; built-in actors are seeded from `CLEVERAGENTS_DEFAULT_PROVIDER` / `CLEVERAGENTS_DEFAULT_MODEL`, then fall back to the built-in order (`openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini`). - -### Required environment variables - -| Provider | Primary variables | -| --- | --- | -| OpenAI | `OPENAI_API_KEY` -| Anthropic | `ANTHROPIC_API_KEY` -| Google | `GOOGLE_API_KEY` or `GOOGLE_GENAI_API_KEY` -| Azure OpenAI | `AZURE_OPENAI_API_KEY` plus `AZURE_OPENAI_ENDPOINT`/`AZURE_OPENAI_DEPLOYMENT` -| OpenRouter | `OPENROUTER_API_KEY` (+ optional `CLEVERAGENTS_OPENROUTER_ORGANIZATION` for sanitized headers) -| Gemini | `GEMINI_API_KEY` or `GOOGLE_GEMINI_API_KEY` -| Cohere | `COHERE_API_KEY` -| Groq | `GROQ_API_KEY` -| Together | `TOGETHER_API_KEY` - -Set `CLEVERAGENTS_DEFAULT_PROVIDER` to pin the global provider (for example `export CLEVERAGENTS_DEFAULT_PROVIDER=openai`) and `CLEVERAGENTS_DEFAULT_MODEL` to lock in a model ID. When unset, the registry picks the first configured provider and uses its published default model such as `gpt-4o` for OpenAI or `claude-sonnet-4-20250514` for Anthropic. - -### Diagnostics and testing shortcuts - -- `agents diagnostics` prints whether the registry can see your credentials and which actor/provider is selected. -- `agents tell` and `agents build` require `--actor ` unless a default actor is set; use `agents actor set-default ` to configure one. -- Built-in actors (`/`) are immutable, custom actors must be named `local/`, and the default actor cannot be removed. Use `--unsafe` when adding/updating configs marked unsafe; runtime only warns when invoking unsafe actors. -- `CLEVERAGENTS_TESTING_USE_MOCK_AI=true` forces the in-repo mock provider so Behave/Robot suites never hit external APIs. -- The full capability matrix (streaming, tool calls, JSON mode, etc.) is documented in `docs/reference/providers.md`. +ISSUES CLOSED: #4470