feat: add evidence-backed log explanations

[CoreyLeath-code]

Summary

Adds an opt-in, evidence-backed explanation layer to LogSight's existing deterministic analysis. The CLI can now render why a finding was raised while preserving existing output and behavior when --explain is not supplied.

Architecture Changes

• Retains the local parser → statistical detector → Rich CLI architecture.
• Records detection evidence alongside the existing anomaly list: parsed error level and/or message-length z-score.
• Represents each complete error-rate spike with its observed count, rate, threshold, and entry range.
• Adds a pure explanation module that converts these recorded facts into direct or statistical statements. It explicitly does not infer incident root causes, invoke an LLM, transmit logs, or emit a model-confidence score.

Files Changed

• logsight/analyzer.py — adds backwards-compatible evidence and spike-detail models while preserving error_rate_spike()'s return contract.
• logsight/reasoning.py — adds deterministic, evidence-only explanation rendering data.
• logsight/cli.py — adds opt-in --explain to analyze and stdin; escapes displayed log content.
• tests/test_analyzer.py — verifies recorded error, outlier, and spike evidence.
• tests/test_reasoning.py — verifies direct/statistical explanations and no-finding behavior.
• tests/test_cli.py — verifies the CLI explanation output uses detector evidence across terminal line wrapping.
• README.md — documents scope, constraints, and reproducible commands for the feature.

Validation Performed

GitHub Actions run CI #100 and CodeQL #37 completed successfully on the PR merge commit.

Check	Result	Evidence
Ruff format	Passed	All files formatted.
Ruff lint	Passed	All checks passed!
mypy	Passed	Success: no issues found in 5 source files
pytest	Passed	57 passed in 2.19s
Coverage	Passed	94.88% total; configured 90% gate reached
Package build, Docker build, and container health	Passed	package-and-container completed successfully
Security	Passed	Bandit, pip-audit, Gitleaks, SBOM, and license report completed in security
Benchmark job	Passed	benchmark completed successfully
CodeQL	Passed	CodeQL run #37 completed successfully

Commands and Real Output

ruff format --check .
All files formatted.

ruff check .
All checks passed!

mypy
Success: no issues found in 5 source files

pytest
57 passed in 2.19s
Required test coverage of 90% reached. Total coverage: 94.88%

Risks

• Explanation output intentionally exposes only detector inputs/thresholds, so it may yield more than one finding for an entry that satisfies multiple independent rules.
• Existing default CLI output remains unchanged; the new output is only enabled by --explain.

Follow-up Recommendations

• Evaluate explanation usefulness against a labeled incident corpus before making any quality or accuracy claim.
• Keep root-cause analysis as a separately designed capability with explicit data, evaluation, and safety boundaries.

NEEDS HUMAN DECISION

None.

Summary by CodeRabbit

• New Features

  • Added an optional --explain flag for file and standard-input analysis.
  • Anomaly results now include evidence such as error-level findings, message-length outliers, and error-rate spike details.
  • Explanations distinguish direct evidence from statistical indicators and avoid inferring root causes.

• Bug Fixes

  • Log messages are safely escaped before display, preventing formatting issues in terminal output.

• Documentation

  • Added usage examples and limitations for evidence-backed explanations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0cd525c2-2d98-45f8-a76e-cf16659417f4

📥 Commits

Reviewing files that changed from the base of the PR and between f9dea4a and e8fd8fa.

📒 Files selected for processing (7)

• README.md
• logsight/analyzer.py
• logsight/cli.py
• logsight/reasoning.py
• tests/test_analyzer.py
• tests/test_cli.py
• tests/test_reasoning.py

---

📝 Walkthrough

Walkthrough

The analyzer now records evidence for detected anomalies and detailed error-rate spikes. A new reasoning module generates non-causal explanations. The CLI exposes these explanations through --explain for file and stdin analysis.

Changes

Evidence-backed explanations

Layer / File(s)	Summary
Analyzer evidence and spike details logsight/analyzer.py, tests/test_analyzer.py	The analyzer records error-level and message-length z-score evidence. It also returns complete spike-window metrics through error_rate_spike_details().
Evidence explanation engine logsight/reasoning.py, tests/test_reasoning.py	The new module generates direct, statistical, and error-rate-spike explanations without inferring root causes.
CLI explanation flow logsight/cli.py, tests/test_cli.py, README.md	The CLI adds --explain to file and stdin commands, escapes Rich-rendered messages, displays evidence details, and documents the option.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Analyzer
  participant Reasoning
  CLI->>Analyzer: Analyze log entries
  Analyzer-->>CLI: Return anomaly report and spike details
  CLI->>Reasoning: Generate explanations
  Reasoning-->>CLI: Return evidence explanations
  CLI-->>CLI: Render explanations when --explain is enabled

Loading

Possibly related PRs

• CoreyLeath-code/LogSight-AI#5: Overlaps in the analyzer and CLI anomaly-detection and spike functions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/evidence-backed-reasoning

---

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.}