cleveragents-core/docs/advanced-concepts/index.md

# Advanced Concepts (v3.6.0)

> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
> **Status:** In Progress (~33% complete as of 2026-04-15)
> **Goal:** Advanced capabilities that extend beyond the core MVP without requiring the TUI (M8) or Server (M9).

---

## Overview

v3.6.0 builds on the stable foundation established by v3.0.0–v3.5.0 to introduce advanced
capabilities that were intentionally deferred from the MVP. These features enrich the
CleverAgents platform for power users and production deployments: richer context strategies,
broader LLM provider support, additional resource types, a standardized A2A protocol, container
tool execution, extensible scope chain resolution, cost and safety budgets, end-to-end workflow
tests, and a plugin architecture.

None of these features require the TUI (v3.7.0) or the Server (v3.9.0) — they are fully
usable from the CLI and programmatic API.

**Sub-sections:**

- [Context Strategies & LLM Backends](index.md) — this page
- [Resource Types & A2A Rename](resource-types.md)
- [Container Tools, Scope Chain, Budgets & Safety](container-tools.md)
- [E2E Tests, Code Review Examples & Plugin Architecture](e2e-tests-and-plugins.md)

---

## Advanced Context Strategies

The ACMS (Adaptive Context Management System) introduced in v3.4.0–v3.5.0 provides a
four-stage pipeline: **Gather → Prioritize → Assemble → Deliver**. v3.6.0 extends this
pipeline with advanced strategies for large-scale and multi-project workloads.

### Beyond the Basic ACMS Pipeline

The basic pipeline assembles context from a single project's resources using a fixed priority
order. Advanced strategies add:

| Strategy | Description |
|----------|-------------|
| **Cross-project context merging** | Assembles context from multiple projects simultaneously, respecting per-project budgets and cross-project relevance scores |
| **Incremental context updates** | Sends only the diff of context changes between turns rather than re-assembling the full context on every prompt |
| **Semantic deduplication** | Detects and removes semantically equivalent fragments before assembly, reducing token waste |
| **Adaptive tier promotion** | Automatically promotes frequently-accessed warm/cold fragments to hot tier based on access patterns across a session |
| **Resource-type-aware budgeting** | Allocates context budget by resource type (e.g., 40% source code, 30% tests, 20% docs, 10% config) rather than a flat priority queue |

### Context Request Protocol (CRP) Extensions

The CRP (defined in ADR-014) is extended with new directive types:

- `focus_path` — elevates a specific file path to the highest priority tier, overriding all
  other budget constraints
- `exclude_pattern` — excludes files matching a glob pattern from context assembly
- `max_fragment_size` — caps the size of any single fragment to prevent one large file from
  consuming the entire budget
- `semantic_group` — groups related fragments so they are either all included or all excluded
  (prevents partial inclusion of tightly coupled files)

---

## Additional LLM Backends

v3.6.0 adds first-class support for additional LLM providers beyond the Anthropic and OpenAI
backends available in v3.5.0.

### Supported Providers (v3.6.0 additions)

| Provider | Actor Namespace | Notes |
|----------|----------------|-------|
| **Google Gemini** | `google/gemini-*` | Gemini 1.5 Pro and Flash; supports long-context (1M tokens) |
| **Mistral AI** | `mistral/*` | Mistral Large, Codestral; strong code generation |
| **Ollama (local)** | `ollama/*` | Any model served by a local Ollama instance |
| **LM Studio** | `lmstudio/*` | OpenAI-compatible local inference |
| **Azure OpenAI** | `azure/*` | Azure-hosted OpenAI models with enterprise auth |
| **AWS Bedrock** | `bedrock/*` | Anthropic, Meta, and Mistral models via AWS |
| **Groq** | `groq/*` | Ultra-fast inference for Llama and Mixtral models |

### Provider Configuration

All providers are configured in `~/.config/cleveragents/config.toml` under the `[providers]`
section. Each provider supports a common set of base arguments (`temperature`, `max_tokens`,
`thinking_effort` where applicable) plus provider-specific extensions.

```toml
[providers.google]
api_key = "${GOOGLE_API_KEY}"
default_model = "gemini-1.5-pro"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"
```

### Provider Fallback Chains

A new `provider_fallback` configuration allows defining ordered fallback chains for resilience:

```toml
[actor.default]
provider_fallback = [
  "anthropic/claude-4-sonnet",
  "google/gemini-1.5-pro",
  "ollama/llama3.2",
]
```

When the primary provider fails (rate limit, outage, or cost budget exceeded), the system
automatically retries with the next provider in the chain.

---

*Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope
as of 2026-04-15. Some features may be adjusted as implementation progresses.*

*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*