From 2410208734d9fa7efb63f80558df11cfba5c8630 Mon Sep 17 00:00:00 2001 From: CTO Hermes Date: Mon, 1 Jun 2026 15:49:34 +0700 Subject: [PATCH] =?UTF-8?q?docs:=20update=20for=20v0.1.7=20=E2=80=94=20cac?= =?UTF-8?q?hing,=20LLM=20params,=20custom=20prompts,=20anti-hallucination?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: add feature bullets for deterministic reviews, diff-hash caching, custom prompts, anti-hallucination, configurable LLM params - README: expand .cora.yaml example with llm section (temperature, max_tokens, timeout, cache_ttl), review.system_prompt, review.response_format, scan options - README: add --no-cache CLI flag and CORA_NO_CACHE env var - Website config page: add llm and review sections to config example - Website config page: add CORA_NO_CACHE to env vars table - Website config page: add new sections for caching behavior, custom system prompts, response_format json_object, anti-hallucination - Website homepage: add feature cards for deterministic reviews, smart caching, and custom prompts + anti-hallucination --- README.md | 27 +++++ website/src/routes/+page.svelte | 30 +++++ .../routes/docs/configuration/+page.svelte | 113 +++++++++++++++++- 3 files changed, 166 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8c605b16..6e7f82ed 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,11 @@ - 🔧 **Configurable** — YAML config file with project-level defaults - 🪝 **Git Hooks** — Pre-commit integration for instant feedback - 📊 **Exit Codes** — Non-zero exit on critical findings for pipeline gating +- 🧠 **Deterministic Reviews** — Temperature 0 by default: same diff always produces the same issues +- 💾 **Diff-Hash Caching** — Reviews cached by diff hash in `~/.cache/cora/reviews/` — skip repeat reviews with `--no-cache` +- 🎯 **Custom System Prompts** — Override review/scan prompts via config or file path +- 🛡️ **Anti-Hallucination** — File path injection and post-parse filtering keep LLM output grounded +- 🌡️ **Configurable LLM Params** — Tune temperature, max tokens, timeout, and cache TTL per project ## 📦 Installation @@ -141,6 +146,9 @@ cora review --severity major # Quiet mode (machine-readable) cora review --quiet + +# Skip cached reviews +cora review --no-cache ``` ### `cora scan` @@ -232,6 +240,13 @@ provider: model: gpt-4o-mini base_url: https://api.openai.com/v1 # Override for custom/self-hosted endpoints +# LLM parameters +llm: + temperature: 0 # Default: 0 (deterministic — same diff = same issues) + max_tokens: 4096 # Default: 4096 + timeout: 120 # Default: 120 (seconds) + cache_ttl: 1440 # Default: 1440 (minutes) — diff-hash cache TTL + # Focus areas for review (empty = all) focus: - security @@ -239,6 +254,17 @@ focus: - bugs - best_practice +# Review options +review: + system_prompt: "You are a senior Rust code reviewer." + # system_prompt_file: ./review-prompt.md # Load prompt from file + response_format: json_object # Opt-in structured JSON output + +# Scan options +# scan: +# system_prompt: "Focus on security vulnerabilities." +# system_prompt_file: ./scan-prompt.md + # Custom rules rules: - "no unwrap" @@ -278,6 +304,7 @@ output: | `CORA_CONFIG` | Path to config file | `.cora.yaml` | | `CORA_FORMAT` | Output format (`pretty`, `json`, `compact`, `sarif`) | `pretty` | | `CORA_NO_COLOR` | Disable colored output | — | +| `CORA_NO_CACHE` | Skip diff-hash cache (same as `--no-cache`) | — | ### Authentication diff --git a/website/src/routes/+page.svelte b/website/src/routes/+page.svelte index ccf7876b..c0dfc5b6 100644 --- a/website/src/routes/+page.svelte +++ b/website/src/routes/+page.svelte @@ -317,6 +317,36 @@

Your code stays yours

Runs entirely on your machine. No cloud, no telemetry, no data leaving your network. Perfect for Gitea and air-gapped environments.

+ + +
+
+ +
+

Deterministic Reviews

+

Same diff, same issues

+

Temperature defaults to 0. Identical diffs always produce identical findings — perfect for CI reproducibility.

+
+ + +
+
+ +
+

Smart Caching

+

Never review the same diff twice

+

Reviews are cached by diff hash in ~/.cache/cora/reviews/. Re-reviewing an unchanged diff returns cached results instantly. Use --no-cache to bypass.

+
+ + +
+
+ +
+

Custom Prompts & Anti-Hallucination

+

Control the review, trust the output

+

Override system prompts for review and scan. File path injection and post-parse filtering ensure the LLM only reports issues that exist in your actual diff.

+
diff --git a/website/src/routes/docs/configuration/+page.svelte b/website/src/routes/docs/configuration/+page.svelte index 98fe0961..fee65771 100644 --- a/website/src/routes/docs/configuration/+page.svelte +++ b/website/src/routes/docs/configuration/+page.svelte @@ -74,6 +74,17 @@ model: gpt-4o base_url: https://api.openai.com/v1 +llm: + temperature: 0 + max_tokens: 4096 + timeout: 120 + cache_ttl: 1440 + +review: + system_prompt: "You are a senior code reviewer." + # system_prompt_file: ./review-prompt.md + response_format: json_object + focus: security, performance, bugs hook: @@ -128,10 +139,14 @@ CORA_FORMAT Output format (pretty, json, compact, sarif) - - CORA_NO_COLOR - Disable colored output - + + CORA_NO_COLOR + Disable colored output + + + CORA_NO_CACHE + Skip diff-hash review cache (same as --no-cache) + GITHUB_TOKEN GitHub token for SARIF upload @@ -184,4 +199,94 @@ + + +
+

+ + Diff-Hash Caching +

+

cora caches review results by diff hash in ~/.cache/cora/reviews/. If you re-review the same diff, the cached result is returned instantly.

+
+
+
+
Config
+
+ llm.cache_ttl — TTL in minutes (default: 1440 / 24h) +
+
+
+
CLI / Env
+
+ --no-cache or CORA_NO_CACHE=1 to bypass +
+
+
+
+
+ + +
+

+ + Custom System Prompts +

+

Override the default system prompt for review or scan commands to match your project's coding standards and review criteria.

+
+
+ + + + .cora.yaml +
+
+
review:
+  system_prompt: "Focus on Rust idioms and error handling."
+  # Or load from a file:
+  system_prompt_file: ./prompts/review.md
+
+scan:
+  system_prompt: "Check for OWASP Top 10 vulnerabilities."
+  system_prompt_file: ./prompts/scan.md
+
+
+

If both system_prompt and system_prompt_file are set, the file takes precedence.

+
+ + +
+

+ + Response Format (JSON Mode) +

+

Opt into structured JSON output from the LLM by setting review.response_format to json_object. This instructs the LLM to return valid JSON, enabling machine-readable parsing and pipeline integration.

+
+
+ + + + .cora.yaml +
+
+
review:
+  response_format: json_object
+
+
+

Requires provider support for structured output. Works with OpenAI, Anthropic, and compatible APIs.

+
+ + +
+

+ + Anti-Hallucination +

+

cora uses two mechanisms to prevent the LLM from fabricating findings:

+
+
    +
  • File path injection — Actual file paths are embedded in the prompt, anchoring the LLM to real files in the diff.
    • +
  • Post-parse filtering — After parsing, any reported file paths or line numbers that don't exist in the actual diff are discarded.
    • +
+
+