cleveragents/cleveragents-core

Fork 3

UAT: `agents diagnostics` missing health checks for text index (tantivy), vector index (faiss), and graph store — spec requires these checks #2127

New issue

Open

opened 2026-04-03 04:18:04 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:18:04 +00:00

Owner

Metadata

Branch: fix/cli-diagnostics-missing-checks
Commit Message: fix(cli): add text index, vector index, and graph store health checks to diagnostics
Milestone: v3.7.0
Parent Epic: #936

Background and Context

The project specification (§agents diagnostics) defines the expected output of the agents diagnostics command, which is the primary tool users rely on to verify their CleverAgents installation is healthy. The spec shows a 10-row diagnostics table that includes checks for the text index (tantivy), vector index (faiss), and graph store — three core infrastructure components of the ACMS (Advanced Context Management System) pipeline.

These checks are absent from the current implementation, meaning users cannot confirm whether these subsystems are properly configured simply by running agents diagnostics.

Current Behavior

The build_diagnostics_data() function in src/cleveragents/cli/commands/system.py currently runs the following checks:

Config file ✓
Data directory ✓
Database ✓
Provider keys (OpenAI, Anthropic, Google, OpenRouter) ✓
Disk space ✓
File permissions ✓
Git ✓
Stale locks ✓ (extra — not in spec)
Async worker health ✓ (extra — not in spec)
Error Pattern DB ✓ (extra — not in spec)

Missing checks:

Text index (tantivy): No check for tantivy availability or version
Vector index (faiss): No check for faiss backend (CPU/GPU)
Graph store: No check for graph store configuration

Steps to reproduce:

agents diagnostics
# Expected: Shows checks for Text index, Vector index, Graph store
# Actual:   No checks for these three components appear in output

Expected Behavior

Per the specification (§agents diagnostics), the diagnostics output should include the following checks (among others):

│ Text index       OK      tantivy 0.22   │   ← MISSING
│ Vector index     OK      faiss (CPU)    │   ← MISSING
│ Graph store      WARN    not configured │   ← MISSING

Specifically:

Text index check: Detect whether the tantivy Python binding is importable and report its version.
Vector index check: Detect whether faiss-cpu (or faiss-gpu) is importable and report the backend variant (CPU/GPU).
Graph store check: Detect whether a graph store is configured (e.g., via the config file or environment) and report its status (OK / WARN not configured).

The faiss-cpu package is already a declared dependency in pyproject.toml, so the faiss check is straightforward to implement.

Acceptance Criteria

agents diagnostics output includes a Text index row showing tantivy availability and version (e.g., OK tantivy 0.22 or WARN not installed)
agents diagnostics output includes a Vector index row showing faiss backend (e.g., OK faiss (CPU), OK faiss (GPU), or WARN not installed)
agents diagnostics output includes a Graph store row showing configuration status (e.g., OK configured or WARN not configured)
All three new checks follow the same display format and severity conventions as existing checks
Existing checks are not broken or removed
BDD scenarios cover each new check (installed/not-installed/not-configured paths)
Integration tests verify the full diagnostics table output includes the new rows
All nox stages pass
Coverage ≥ 97%

Supporting Information

Code location: src/cleveragents/cli/commands/system.py — build_diagnostics_data() function
Spec reference: §agents diagnostics (diagnostics table, 10-check layout)
Dependency note: faiss-cpu is already declared in pyproject.toml; tantivy and graph store configuration detection should follow the same import-probe pattern used for other optional dependencies
Severity: Medium — Users relying on agents diagnostics to verify their installation cannot confirm whether the text search index (tantivy), vector store (faiss), or graph store are properly configured. These are core ACMS infrastructure components.

Subtasks

Implement _check_text_index() in build_diagnostics_data() — probe tantivy import, report version or WARN
Implement _check_vector_index() in build_diagnostics_data() — probe faiss import, detect CPU/GPU backend, report or WARN
Implement _check_graph_store() in build_diagnostics_data() — read config/env for graph store setting, report OK or WARN
Insert the three new check rows into the diagnostics table output in spec-correct order
Tests (Behave): Add BDD scenarios for each new check covering installed, not-installed, and not-configured paths
Tests (Robot): Add integration test asserting all three rows appear in agents diagnostics output
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(cli): add text index, vector index, and graph store health checks to diagnostics), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/cli-diagnostics-missing-checks).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/cli-diagnostics-missing-checks` - **Commit Message**: `fix(cli): add text index, vector index, and graph store health checks to diagnostics` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Background and Context The project specification (§agents diagnostics) defines the expected output of the `agents diagnostics` command, which is the primary tool users rely on to verify their CleverAgents installation is healthy. The spec shows a 10-row diagnostics table that includes checks for the **text index** (tantivy), **vector index** (faiss), and **graph store** — three core infrastructure components of the ACMS (Advanced Context Management System) pipeline. These checks are absent from the current implementation, meaning users cannot confirm whether these subsystems are properly configured simply by running `agents diagnostics`. ## Current Behavior The `build_diagnostics_data()` function in `src/cleveragents/cli/commands/system.py` currently runs the following checks: 1. Config file ✓ 2. Data directory ✓ 3. Database ✓ 4. Provider keys (OpenAI, Anthropic, Google, OpenRouter) ✓ 5. Disk space ✓ 6. File permissions ✓ 7. Git ✓ 8. Stale locks ✓ *(extra — not in spec)* 9. Async worker health ✓ *(extra — not in spec)* 10. Error Pattern DB ✓ *(extra — not in spec)* **Missing checks:** - **Text index** (tantivy): No check for tantivy availability or version - **Vector index** (faiss): No check for faiss backend (CPU/GPU) - **Graph store**: No check for graph store configuration **Steps to reproduce:** ```bash agents diagnostics # Expected: Shows checks for Text index, Vector index, Graph store # Actual: No checks for these three components appear in output ``` ## Expected Behavior Per the specification (§agents diagnostics), the diagnostics output should include the following checks (among others): ``` │ Text index OK tantivy 0.22 │ ← MISSING │ Vector index OK faiss (CPU) │ ← MISSING │ Graph store WARN not configured │ ← MISSING ``` Specifically: - **Text index check**: Detect whether the `tantivy` Python binding is importable and report its version. - **Vector index check**: Detect whether `faiss-cpu` (or `faiss-gpu`) is importable and report the backend variant (CPU/GPU). - **Graph store check**: Detect whether a graph store is configured (e.g., via the config file or environment) and report its status (`OK` / `WARN not configured`). The `faiss-cpu` package is already a declared dependency in `pyproject.toml`, so the faiss check is straightforward to implement. ## Acceptance Criteria - [ ] `agents diagnostics` output includes a **Text index** row showing tantivy availability and version (e.g., `OK tantivy 0.22` or `WARN not installed`) - [ ] `agents diagnostics` output includes a **Vector index** row showing faiss backend (e.g., `OK faiss (CPU)`, `OK faiss (GPU)`, or `WARN not installed`) - [ ] `agents diagnostics` output includes a **Graph store** row showing configuration status (e.g., `OK configured` or `WARN not configured`) - [ ] All three new checks follow the same display format and severity conventions as existing checks - [ ] Existing checks are not broken or removed - [ ] BDD scenarios cover each new check (installed/not-installed/not-configured paths) - [ ] Integration tests verify the full diagnostics table output includes the new rows - [ ] All nox stages pass - [ ] Coverage ≥ 97% ## Supporting Information - **Code location**: `src/cleveragents/cli/commands/system.py` — `build_diagnostics_data()` function - **Spec reference**: §agents diagnostics (diagnostics table, 10-check layout) - **Dependency note**: `faiss-cpu` is already declared in `pyproject.toml`; tantivy and graph store configuration detection should follow the same import-probe pattern used for other optional dependencies - **Severity**: Medium — Users relying on `agents diagnostics` to verify their installation cannot confirm whether the text search index (tantivy), vector store (faiss), or graph store are properly configured. These are core ACMS infrastructure components. ## Subtasks - [ ] Implement `_check_text_index()` in `build_diagnostics_data()` — probe tantivy import, report version or WARN - [ ] Implement `_check_vector_index()` in `build_diagnostics_data()` — probe faiss import, detect CPU/GPU backend, report or WARN - [ ] Implement `_check_graph_store()` in `build_diagnostics_data()` — read config/env for graph store setting, report OK or WARN - [ ] Insert the three new check rows into the diagnostics table output in spec-correct order - [ ] Tests (Behave): Add BDD scenarios for each new check covering installed, not-installed, and not-configured paths - [ ] Tests (Robot): Add integration test asserting all three rows appear in `agents diagnostics` output - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(cli): add text index, vector index, and graph store health checks to diagnostics`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/cli-diagnostics-missing-checks`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 04:18:09 +00:00

freemo added a new dependency

2026-04-03 04:18:32 +00:00

#936 Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework

freemo referenced this issue

2026-04-03 04:20:11 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo referenced this issue

2026-04-03 04:21:53 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:04 +00:00

freemo commented

2026-04-03 18:28:18 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner