Add Talos operator CLI commands

[Pro777]

Summary

• add evaluate, status, and explain commands on top of the runtime evaluation contract
• document snapshot-driven CLI usage and persisted Talos state files
• extend CLI coverage for evaluate/status/explain flows

Testing

• . .venv/bin/activate && pytest --cov=talos --cov-report=term-missing --cov-report=xml

Summary by CodeRabbit

• New Features

  • Added evaluate, status, and explain subcommands to the Talos CLI
  • Support for overriding persistence file locations via environment variables

• Documentation

  • Updated CLI usage examples with new snapshot-based workflow
  • Expanded persistence configuration documentation with file structure and environment variable overrides
  • Added CLI smoke-test instructions

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 090c362c-0d02-467e-8b93-1c03f2565269

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This PR extends the Talos CLI beyond a single score subcommand by introducing evaluate, status, and explain commands that operate on snapshot files. The implementation adds snapshot/state loading and persistence logic, a JSON output helper, and corresponding integration tests. Documentation is updated to show the new snapshot-driven workflow and expanded file-based state management.

Changes

Snapshot-based CLI workflow and integration

Layer / File(s)	Summary
CLI command implementation talos/cli.py	New imports add Path, Any, and runtime/state helpers; build_parser() registers evaluate, status, explain subcommands with arguments; _print_json helper formats stable JSON output; main() implements evaluation (snapshot + state/policy → evaluate → persist state/status/history → output), status (load and print status file), and explain (print evaluation reasons) flows.
CLI integration tests tests/test_cli.py	Added Path import and new test cases that mock snapshot JSON files, CLI arguments, and runtime paths, then verify command execution succeeds with expected JSON fields (level), output files are created, and explain includes explanatory text.
Usage documentation and examples README.md, TESTING.md, docs/OVERVIEW.md	README CLI section replaced with snapshot-driven workflow (cat > snapshot.json + talos evaluate/status/explain); API example updated to use TalosSnapshot and evaluate_snapshot; Persistence section expanded to document multiple state files (cycles.json, status.json, history.jsonl, policy.json) and environment-variable overrides; TESTING.md added snapshot smoke-test section; OVERVIEW.md updated scope to include CLI and runtime helpers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Spitfire-Cowboy/talos#5: Both modify talos/cli.py and tests/test_cli.py around CLI command handling, with this PR extending the minimal score command into new snapshot-driven evaluation and state persistence flows.

Poem

🐰 A snapshot springs to life so bright,
Evaluated left and right,
State persists through time's grand flow,
CLI commands steal the show!
Explain what matters, status shines,
Code and tests align just fine. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Talos operator CLI commands' clearly and concisely describes the main change—introducing new evaluate, status, and explain CLI subcommands to the Talos project.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/operator-cli

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Pro777]

Closing for now so these changes can land one at a time and leave room for CodeRabbit review. I’ll reopen this follow-up after the review window.

[Pro777]

@coderabbitai Please review

[coderabbitai]

@Pro777 Sure! I'll kick off a review of the PR now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@talos/cli.py`:
- Around line 70-74: The evaluate command currently always returns 0 even if
persistence fails; modify the evaluate flow (in talos/cli.py, function evaluate)
so that after calling save_state, save_status, and append_history you detect
failure: either catch exceptions from those calls or check their return values
(save_state, save_status, append_history) and if any indicate failure, emit an
error via the existing logger and return a non-zero exit code (e.g., return 1)
instead of 0; ensure _print_json(evaluation.to_dict()) only runs when
persistence succeeded or still allow printing but still return non-zero on
persistence failure.
- Around line 76-78: When handling the "status" command in the args.command
branch, wrap the call to args.status_file.read_text() and json.loads(...) (used
by _print_json) in a try/except that catches FileNotFoundError and
json.JSONDecodeError and routes errors to the CLI parser error path (call
parser.error(...) with a clear message about missing or invalid status file);
reference the "args.command" check, the "_print_json" invocation, and the
"args.status_file.read_text()" / "json.loads" operations and ensure the handler
returns or exits via parser.error so a traceback is not exposed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: eeceff20-dfef-4928-89bc-4f46efe993e3

📥 Commits

Reviewing files that changed from the base of the PR and between 5d1d01b and e4be6ef.

📒 Files selected for processing (5)

• README.md
• TESTING.md
• docs/OVERVIEW.md
• talos/cli.py
• tests/test_cli.py