# CleverAgents Core

CleverAgents is a Python-first automation platform. It provides a unified `agents` CLI, embedded runtime, and service orchestration tools while embracing modern Python tooling.

## Highlights

- Unified CLI entry points: `cleveragents` and `agents`
- 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
```

## 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 <name>` (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 <name>` unless a default actor is set; use `agents actor set-default <name>` to configure one.
- Built-in actors (`<provider>/<model>`) are immutable, custom actors must be named `local/<id>`, 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`.