feat: adds logic to create new proof docs

[semmet95]

Summary by CodeRabbit

• New Features

  • Added a new CLI tool for ingesting claim-proof links into local YAML files, with automatic deduplication and validation.
  • Enabled automated proof retrieval and storage with web-search capabilities.

• Documentation

  • Updated API schema documentation with example values for proof input parameters.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

Warning

Rate limit exceeded

@semmet95 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 54 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 51d0ca96-58fa-4c88-aa96-5855ccbd7733

📥 Commits

Reviewing files that changed from the base of the PR and between 4b393c4 and 056ee91.

📒 Files selected for processing (2)

• scripts/helper.py
• scripts/ingest_proofs.py

📝 Walkthrough

Walkthrough

This PR adds a proof ingestion system that fetches claims from an API, uses an AI service to generate proofs for each claim, deduplicates results against existing documents, and stores new proofs as YAML files. It also updates the ProofInput schema with an example and adds a helper function to fetch claims from the API.

Changes

Proof Ingestion Pipeline

Layer / File(s)	Summary
ProofInput schema and claims fetching oapi.yaml, scripts/helper.py	ProofInput schema now defines an example object with representative values for claimUriDigest, supportsClaim, reviewedBy, and uri. A new get_claims(api_key, base_url) helper fetches claims from the /api/v1/claims endpoint with API key authentication.
Proof document loading and deduplication scripts/ingest_proofs.py	Script initialization and utilities to recursively load existing proof documents from proofs/ directory, filter empty YAML files, and deduplicate new proofs by matching uri values against already-stored documents.
Proof document creation and ingest orchestration scripts/ingest_proofs.py	Converts deduplicated proofs into YAML documents with normalized structure and sanitized filenames (based on claim name and proof hostname). Main orchestration loop fetches claims, retrieves verification skill markdown, calls OpenRouter with web-search tool, parses and validates results, deduplicates, and writes unique proofs while avoiding overwrites. Exits early on critical failures and continues on recoverable per-claim errors.

Sequence Diagram

sequenceDiagram
  participant CLI as ingest_proofs CLI
  participant APIServer as API Server
  participant FileSystem as Local File System
  participant OpenRouter as OpenRouter AI
  participant WebSearch as Web Search Tool

  CLI->>FileSystem: Load existing proofs from proofs/
  CLI->>APIServer: GET /api/v1/claims (X-API-Key)
  APIServer-->>CLI: [claims list]
  
  loop For each claim
    CLI->>OpenRouter: POST request with claim URI + verification prompt
    OpenRouter->>WebSearch: Execute web search for claim verification
    WebSearch-->>OpenRouter: Search results
    OpenRouter-->>CLI: Proof generation result (JSON)
    CLI->>CLI: Parse and deduplicate proofs
    CLI->>FileSystem: Write unique proofs as YAML to proofs/<claim_name>/
  end
  
  CLI-->>CLI: Exit with status 0 or 1

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Automate PR creation #3: The new ingest_proofs script and get_claims helper implement the "fetch recent claims" and "get proofs" steps of the proof ingestion workflow, directly addressing the objectives of this issue.

Poem

🐰 A proof script hops along the way,
Fetching claims from the API tray,
With OpenRouter's AI sight so keen,
Deduplicates what's been and seen,
Storing proofs in YAML arrays bright! 📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding logic to create new proof documents, which is the primary purpose of the new ingest_proofs.py script and supporting functions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 feat/fetch-claim-proofs

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 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 `@scripts/helper.py`:
- Around line 87-94: The get_claims function currently lets network and JSON
decode exceptions propagate; wrap the requests.get and response.json() calls in
a try/except that catches requests.exceptions.RequestException (for
transport/timeouts) and json.JSONDecodeError or ValueError (for invalid JSON),
log or print a descriptive error including the exception and endpoint (use
api_key/base_url to build context), and return None on any exception; keep the
existing non-200 check and return None there as before so callers can rely on
None for failures.

In `@scripts/ingest_proofs.py`:
- Around line 80-87: The code builds filenames from only hostname (hostname,
filename, helper.clean_filepath, proof["uri"]), causing collisions when multiple
proofs share a domain; change the filename generation to incorporate a unique
component (e.g., urlparse(proof["uri"]).netloc or path and/or a short hash of
the full proof["uri"] or proof["id"]) appended to the cleaned hostname so each
proof yields a distinct filename, apply helper.clean_filepath after composing
the combined string, add the ".yaml" suffix, and make the same change to the
other occurrence mentioned (the block around lines 97-99).
- Line 115: The print statement uses an unnecessary f-string with no
placeholders; replace print(f"Error: failed to fetch all claims",
file=sys.stderr) with a regular string literal print("Error: failed to fetch all
claims", file=sys.stderr) (update the print call in scripts/ingest_proofs.py
where the erroneous f-string is used).
- Around line 126-131: The f-strings in the print statement and req_content
construction are using double quotes around the outer string and again around
claim["uri"], causing a syntax error; update the print and the req_content
f-strings to use single-quoted outer strings (or escape the inner quotes) so
{claim["uri"]} is parsed correctly (e.g., change the print line that references
claim["uri"] and the req_content assignment that concatenates
CLAIM_VERIFICATION_PROMPT to use single-quoted f-strings or string formatting
instead).
- Around line 64-78: The generated proof_doc includes "reviewedBy" set to an
empty string which violates the ProofInput schema's nonempty,nospace rule;
change the construction of proof_doc (in the loop that builds proof_doc from
proofs) to only include the reviewedBy field when the source proof has a
non-empty value (e.g. if proof.get("reviewed_by") is truthy then set
"reviewedBy": proof["reviewed_by"], otherwise omit the key), ensuring produced
docs conform to ProofInput validation.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 59f310a0-1a4c-4c1c-a7e8-1787c86e0f07

📥 Commits

Reviewing files that changed from the base of the PR and between f70c438 and 4b393c4.

📒 Files selected for processing (3)

• oapi.yaml
• scripts/helper.py
• scripts/ingest_proofs.py

[cubic-dev-ai]

6 issues found across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>