cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): extend agents diagnostics example to show all 9 supported providers #5403

Merged
HAL9000 merged 2 commits from spec/fix-diagnostics-providers-example-5320 into master 2026-04-24 04:10:37 +00:00
Conversation 6 Commits 2 Files Changed 3
+230 -111
3 changed files with 230 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+9
View File
@@ -5,6 +5,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [Unreleased]
### Changed
- **Diagnostics spec examples expanded to all 9 providers** (#5320): Updated the
`agents diagnostics` command examples in the specification to show all 9 supported
providers (OpenAI, Anthropic, Google, Gemini, Azure, OpenRouter, Cohere, Groq,
Together), matching the implementation from PR #3469. Rich, plain, JSON, and YAML
example outputs now reflect comprehensive provider coverage with accurate warning
counts and per-provider recommendations.
### Added
- **Architecture Pool Supervisor Milestone Assignment** (#7521): Added a "PR Workflow
docs/specification.md
+208 -98
View File
@@ -868,35 +868,48 @@ None.
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
╭─ Checks ────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────── ────── ──────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #66cc66; font-weight: 600;">OK</span> writable │
│ OPENAI_API_KEY <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Anthropic key <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Disk space <span style="color: #66cc66; font-weight: 600;">OK</span> 2.1 GB free │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #66cc66; font-weight: 600;">OK</span> faiss (CPU) │
│ Graph store <span style="color: yellow; font-weight: 600;">WARN</span> not configured │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰─────────────────────────────────────────╯
╭─ Checks ──────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────────────────── ────── ─────────────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #66cc66; font-weight: 600;">OK</span> writable │
│ OpenAI key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Anthropic key <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Google key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Gemini key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Azure OpenAI key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ OpenRouter key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Cohere key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Groq key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Together key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Disk space <span style="color: #66cc66; font-weight: 600;">OK</span> 2.1 GB free │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #66cc66; font-weight: 600;">OK</span> faiss (CPU) │
│ Graph store <span style="color: yellow; font-weight: 600;">WARN</span> not configured │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰───────────────────────────────────────────────────────────╯
╭─ Summary ─────────╮
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 2 │
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 17 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 9 │
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 0 │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 0.6s │
╰───────────────────╯
╭─ Recommendations ─────────────────────────────────────────────╮
│ - Set OPENAI_API_KEY to enable OpenAI models │
│ - Configure a graph store backend for structural code queries │
│ - Verify provider credentials via config │
╰───────────────────────────────────────────────────────────────╯
╭─ Recommendations ──────────────────────────────────────────────╮
│ - Set OPENAI_API_KEY to enable OpenAI models │
│ - Set GOOGLE_API_KEY to enable Google models │
│ - Set GEMINI_API_KEY to enable Gemini models │
│ - Set AZURE_OPENAI_API_KEY to enable Azure OpenAI models │
│ - Set OPENROUTER_API_KEY to enable OpenRouter models │
│ - Set COHERE_API_KEY to enable Cohere models │
│ - Set GROQ_API_KEY to enable Groq models │
│ - Set TOGETHER_API_KEY to enable Together models │
│ - Configure a graph store backend for structural code queries │
╰────────────────────────────────────────────────────────────────╯
<span style="color: yellow; font-weight: 600;">⚠ WARN</span> 2 warnings require attention
<span style="color: yellow; font-weight: 600;">⚠ WARN</span> 9 warnings require attention
</code></pre></div>
=== "Plain"
@@ -905,31 +918,44 @@ None.
$ agents diagnostics
Checks
Check Status Details
--------------- ------ --------------
Config file OK readable
Database OK writable
OPENAI_API_KEY WARN missing
Anthropic key OK configured
Disk space OK 2.1 GB free
Text index OK tantivy 0.22
Vector index OK faiss (CPU)
Graph store WARN not configured
File permissions OK data dir r/w
Git OK git 2.43.0
Check Status Details
------------------------ ------ --------------
Config file OK readable
Database OK writable
OpenAI key WARN missing
Anthropic key OK configured
Google key WARN missing
Gemini key WARN missing
Azure OpenAI key WARN missing
OpenRouter key WARN missing
Cohere key WARN missing
Groq key WARN missing
Together key WARN missing
Disk space OK 2.1 GB free
Text index OK tantivy 0.22
Vector index OK faiss (CPU)
Graph store WARN not configured
File permissions OK data dir r/w
Git OK git 2.43.0
Summary
Checks: 10 total
Warnings: 2
Checks: 17 total
Warnings: 9
Errors: 0
Duration: 0.6s
Recommendations
- Set OPENAI_API_KEY to enable OpenAI models
- Set GOOGLE_API_KEY to enable Google models
- Set GEMINI_API_KEY to enable Gemini models
- Set AZURE_OPENAI_API_KEY to enable Azure OpenAI models
- Set OPENROUTER_API_KEY to enable OpenRouter models
- Set COHERE_API_KEY to enable Cohere models
- Set GROQ_API_KEY to enable Groq models
- Set TOGETHER_API_KEY to enable Together models
- Configure a graph store backend for structural code queries
- Verify provider credentials via config
[WARN] 2 warnings require attention
[WARN] 9 warnings require attention
```
=== "JSON"
@@ -943,8 +969,15 @@ None.
"checks": [
{ "check": "Config file", "status": "ok", "details": "readable" },
{ "check": "Database", "status": "ok", "details": "writable" },
{ "check": "OPENAI_API_KEY", "status": "warn", "details": "missing" },
{ "check": "OpenAI key", "status": "warn", "details": "missing" },
{ "check": "Anthropic key", "status": "ok", "details": "configured" },
{ "check": "Google key", "status": "warn", "details": "missing" },
{ "check": "Gemini key", "status": "warn", "details": "missing" },
{ "check": "Azure OpenAI key", "status": "warn", "details": "missing" },
{ "check": "OpenRouter key", "status": "warn", "details": "missing" },
{ "check": "Cohere key", "status": "warn", "details": "missing" },
{ "check": "Groq key", "status": "warn", "details": "missing" },
{ "check": "Together key", "status": "warn", "details": "missing" },
{ "check": "Disk space", "status": "ok", "details": "2.1 GB free" },
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
{ "check": "Vector index", "status": "ok", "details": "faiss (CPU)" },
@@ -953,22 +986,28 @@ None.
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
],
"summary": {
"total": 10,
"warnings": 2,
"total": 17,
"warnings": 9,
"errors": 0,
"duration_s": 0.6
},
"recommendations": [
"Set OPENAI_API_KEY to enable OpenAI models",
"Configure a graph store backend for structural code queries",
"Verify provider credentials via config"
"Set GOOGLE_API_KEY to enable Google models",
"Set GEMINI_API_KEY to enable Gemini models",
"Set AZURE_OPENAI_API_KEY to enable Azure OpenAI models",
"Set OPENROUTER_API_KEY to enable OpenRouter models",
"Set COHERE_API_KEY to enable Cohere models",
"Set GROQ_API_KEY to enable Groq models",
"Set TOGETHER_API_KEY to enable Together models",
"Configure a graph store backend for structural code queries"
]
},
"timing": {
"duration_ms": 600
},
"messages": [
{ "level": "warn", "text": "2 warnings require attention" }
{ "level": "warn", "text": "9 warnings require attention" }
]
}
```
@@ -987,12 +1026,33 @@ None.
- check: Database
status: ok
details: writable
- check: OPENAI_API_KEY
- check: OpenAI key
status: warn
details: missing
- check: Anthropic key
status: ok
details: configured
- check: Google key
status: warn
details: missing
- check: Gemini key
status: warn
details: missing
- check: Azure OpenAI key
status: warn
details: missing
- check: OpenRouter key
status: warn
details: missing
- check: Cohere key
status: warn
details: missing
- check: Groq key
status: warn
details: missing
- check: Together key
status: warn
details: missing
- check: Disk space
status: ok
details: 2.1 GB free
@@ -1012,19 +1072,25 @@ None.
status: ok
details: git 2.43.0
summary:
total: 10
warnings: 2
total: 17
warnings: 9
errors: 0
duration_s: 0.6
recommendations:
- Set OPENAI_API_KEY to enable OpenAI models
- Set GOOGLE_API_KEY to enable Google models
- Set GEMINI_API_KEY to enable Gemini models
- Set AZURE_OPENAI_API_KEY to enable Azure OpenAI models
- Set OPENROUTER_API_KEY to enable OpenRouter models
- Set COHERE_API_KEY to enable Cohere models
- Set GROQ_API_KEY to enable Groq models
- Set TOGETHER_API_KEY to enable Together models
- Configure a graph store backend for structural code queries
- Verify provider credentials via config
timing:
duration_ms: 600
messages:
- level: warn
text: 2 warnings require attention
text: 9 warnings require attention
```
When critical checks fail, diagnostics reports errors:
@@ -1034,24 +1100,31 @@ When critical checks fail, diagnostics reports errors:
<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
╭─ Checks ────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────── ─────── ────────────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #ff6666; font-weight: 600;">ERROR</span> locked by another process │
│ OPENAI_API_KEY <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Anthropic key <span style="color: #ff6666; font-weight: 600;">ERROR</span> invalid key format │
│ Disk space <span style="color: yellow; font-weight: 600;">WARN</span> 312 MB free (low) │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #ff6666; font-weight: 600;">ERROR</span> FAISS library not found │
│ Graph store <span style="color: #66cc66; font-weight: 600;">OK</span> neo4j 5.15 │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰─────────────────────────────────────────────────────╯
╭─ Checks ──────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
│ <span style="opacity: 0.7;">─────────────────────────── ─────── ─────────────────────────────</span> │
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
│ Database <span style="color: #ff6666; font-weight: 600;">ERROR</span> locked by another process │
│ OpenAI key <span style="color: #ff6666; font-weight: 600;">ERROR</span> invalid key format │
│ Anthropic key <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
│ Google key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Gemini key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Azure OpenAI key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ OpenRouter key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Cohere key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Groq key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Together key <span style="color: yellow; font-weight: 600;">WARN</span> missing │
│ Disk space <span style="color: yellow; font-weight: 600;">WARN</span> 312 MB free (low) │
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
│ Vector index <span style="color: #ff6666; font-weight: 600;">ERROR</span> FAISS library not found │
│ Graph store <span style="color: #66cc66; font-weight: 600;">OK</span> neo4j 5.15 │
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
╰───────────────────────────────────────────────────────────╯
╭─ Summary ─────────╮
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 1 │
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 17 total │
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 8 │
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 3 │
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 1.2s │
╰───────────────────╯
@@ -1059,8 +1132,8 @@ When critical checks fail, diagnostics reports errors:
╭─ Errors (must fix) ─────────────────────────────────────────────────╮
│ <span style="color: #ff6666; font-weight: 600;">1.</span> Database is locked by PID 12847 — stop the other process or │
│ delete the lock file at ~/.cleveragents/agents.db-lock │
│ <span style="color: #ff6666; font-weight: 600;">2.</span> Anthropic key starts with <span style="color: #66cc66;">"pk-"</span> — expected <span style="color: #66cc66;">"sk-ant-"</span> prefix │
│ Run: agents config set provider.anthropic.api-key <correct-key> │
│ <span style="color: #ff6666; font-weight: 600;">2.</span> OpenAI key starts with <span style="color: #66cc66;">"pk-"</span> — expected <span style="color: #66cc66;">"sk-"</span> prefix │
│ Run: agents config set provider.openai.api-key <correct-key> │
│ <span style="color: #ff6666; font-weight: 600;">3.</span> FAISS library not installed — vector search will not work │
│ Run: pip install faiss-cpu │
╰─────────────────────────────────────────────────────────────────────╯
@@ -1074,30 +1147,37 @@ When critical checks fail, diagnostics reports errors:
$ agents diagnostics
Checks
Check Status Details
--------------- ------- ------------------------
Config file OK readable
Database ERROR locked by another process
OPENAI_API_KEY OK configured
Anthropic key ERROR invalid key format
Disk space WARN 312 MB free (low)
Text index OK tantivy 0.22
Vector index ERROR FAISS library not found
Graph store OK neo4j 5.15
File permissions OK data dir r/w
Git OK git 2.43.0
Check Status Details
------------------------ ------- --------------------------
Config file OK readable
Database ERROR locked by another process
OpenAI key ERROR invalid key format
Anthropic key OK configured
Google key WARN missing
Gemini key WARN missing
Azure OpenAI key WARN missing
OpenRouter key WARN missing
Cohere key WARN missing
Groq key WARN missing
Together key WARN missing
Disk space WARN 312 MB free (low)
Text index OK tantivy 0.22
Vector index ERROR FAISS library not found
Graph store OK neo4j 5.15
File permissions OK data dir r/w
Git OK git 2.43.0
Summary
Checks: 10 total
Warnings: 1
Checks: 17 total
Warnings: 8
Errors: 3
Duration: 1.2s
Errors (must fix)
1. Database is locked by PID 12847 -- stop the other process or
delete the lock file at ~/.cleveragents/agents.db-lock
2. Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
Run: agents config set provider.anthropic.api-key <correct-key>
2. OpenAI key starts with "pk-" -- expected "sk-" prefix
Run: agents config set provider.openai.api-key <correct-key>
3. FAISS library not installed -- vector search will not work
Run: pip install faiss-cpu
@@ -1115,8 +1195,15 @@ When critical checks fail, diagnostics reports errors:
"checks": [
{ "check": "Config file", "status": "ok", "details": "readable" },
{ "check": "Database", "status": "error", "details": "locked by another process" },
{ "check": "OPENAI_API_KEY", "status": "ok", "details": "configured" },
{ "check": "Anthropic key", "status": "error", "details": "invalid key format" },
{ "check": "OpenAI key", "status": "error", "details": "invalid key format" },
{ "check": "Anthropic key", "status": "ok", "details": "configured" },
{ "check": "Google key", "status": "warn", "details": "missing" },
{ "check": "Gemini key", "status": "warn", "details": "missing" },
{ "check": "Azure OpenAI key", "status": "warn", "details": "missing" },
{ "check": "OpenRouter key", "status": "warn", "details": "missing" },
{ "check": "Cohere key", "status": "warn", "details": "missing" },
{ "check": "Groq key", "status": "warn", "details": "missing" },
{ "check": "Together key", "status": "warn", "details": "missing" },
{ "check": "Disk space", "status": "warn", "details": "312 MB free (low)" },
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
{ "check": "Vector index", "status": "error", "details": "FAISS library not found" },
@@ -1125,8 +1212,8 @@ When critical checks fail, diagnostics reports errors:
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
],
"summary": {
"total": 10,
"warnings": 1,
"total": 17,
"warnings": 8,
"errors": 3,
"duration_s": 1.2
},
@@ -1137,8 +1224,8 @@ When critical checks fail, diagnostics reports errors:
},
{
"index": 2,
"message": "Anthropic key starts with \"pk-\" -- expected \"sk-ant-\" prefix",
"fix": "agents config set provider.anthropic.api-key <correct-key>"
"message": "OpenAI key starts with \"pk-\" -- expected \"sk-\" prefix",
"fix": "agents config set provider.openai.api-key <correct-key>"
},
{
"index": 3,
@@ -1170,12 +1257,33 @@ When critical checks fail, diagnostics reports errors:
- check: Database
status: error
details: locked by another process
- check: OPENAI_API_KEY
status: ok
details: configured
- check: Anthropic key
- check: OpenAI key
status: error
details: invalid key format
- check: Anthropic key
status: ok
details: configured
- check: Google key
status: warn
details: missing
- check: Gemini key
status: warn
details: missing
- check: Azure OpenAI key
status: warn
details: missing
- check: OpenRouter key
status: warn
details: missing
- check: Cohere key
status: warn
details: missing
- check: Groq key
status: warn
details: missing
- check: Together key
status: warn
details: missing
- check: Disk space
status: warn
details: 312 MB free (low)
@@ -1195,8 +1303,8 @@ When critical checks fail, diagnostics reports errors:
status: ok
details: git 2.43.0
summary:
total: 10
warnings: 1
total: 17
warnings: 8
errors: 3
duration_s: 1.2
errors:
@@ -1205,10 +1313,12 @@ When critical checks fail, diagnostics reports errors:
Database is locked by PID 12847 -- stop the other process or
delete the lock file at ~/.cleveragents/agents.db-lock
- index: 2
message: Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
fix: agents config set provider.anthropic.api-key <correct-key>
message: >-
OpenAI key starts with "pk-" -- expected "sk-" prefix
fix: agents config set provider.openai.api-key <correct-key>
- index: 3
message: FAISS library not installed -- vector search will not work
message: >-
FAISS library not installed -- vector search will not work
fix: pip install faiss-cpu
timing:
duration_ms: 1200
src/cleveragents/cli/commands/system.py
+13 -13
View File
@@ -253,26 +253,26 @@ def _check_providers() -> list[dict[str, Any]]:
results: list[dict[str, Any]] = []
provider_checks = [
("openai", "OPENAI_API_KEY"),
("anthropic", "ANTHROPIC_API_KEY"),
("google", "GOOGLE_API_KEY"),
("azure", "AZURE_OPENAI_API_KEY"),
("openrouter", "OPENROUTER_API_KEY"),
("gemini", "GEMINI_API_KEY"),
("cohere", "COHERE_API_KEY"),
("groq", "GROQ_API_KEY"),
("together", "TOGETHER_API_KEY"),
("openai", "OpenAI", "OPENAI_API_KEY"),
("anthropic", "Anthropic", "ANTHROPIC_API_KEY"),
("google", "Google", "GOOGLE_API_KEY"),
("gemini", "Gemini", "GEMINI_API_KEY"),
("azure", "Azure OpenAI", "AZURE_OPENAI_API_KEY"),
("openrouter", "OpenRouter", "OPENROUTER_API_KEY"),
("cohere", "Cohere", "COHERE_API_KEY"),
("groq", "Groq", "GROQ_API_KEY"),
("together", "Together", "TOGETHER_API_KEY"),
]
for provider_name, env_var in provider_checks:
configured = settings.has_provider_configured(provider_name)
for provider_slug, display_name, env_var in provider_checks:
configured = settings.has_provider_configured(provider_slug)
results.append(
{
"name": f"{provider_name.capitalize()} key",
"name": f"{display_name} key",
"status": CheckStatus.OK if configured else CheckStatus.WARN,
"details": "configured" if configured else "missing",
"recommendation": (
f"Set {env_var} to enable {provider_name.capitalize()} models"
f"Set {env_var} to enable {display_name} models"
if not configured
else None
),