Evidence Ledger

Turn source links into a decision-ready, verifiable research brief — without turning search snippets into facts.

Evidence Ledger is a local-first Python tool and agent skill for organizing research evidence from public web and social sources. It accepts a local JSON bundle, preserves each source's original URL, deduplicates only with a separate canonical URL, and generates Markdown that keeps three categories apart:

• Verified facts — a primary or authoritative source was actually opened.
• Reported experiences — a person describes what they experienced; useful, but not universal fact.
• Inferences and verification gaps — hypotheses, snippets, conflicting claims, or material that still needs source review.

The project was shaped by travel research, especially the need to turn scattered social-post evidence into an auditable decision brief. It is deliberately platform-neutral: Xiaohongshu is a supported record type, not a built-in scraper or network reader.

What it does

• Preserves original_url for revisiting the exact source.
• Generates canonical_url separately for deduplication.
• Treats verified as invalid unless source_opened_at is recorded.
• Merges duplicate observations without losing alternate links or provenance.
• Reports route failures, empty results, truncation, and login-state use instead of silently claiming coverage.
• Renders a Markdown evidence brief from local JSON only.

What it does not do

Evidence Ledger does not log into sites, scrape pages, read platform content over the network, bypass challenges, export private favorites, download media, post content, or call a network API. The public core accepts local records only: user-provided links, user-provided excerpts, or data from a provider that is independently authorized to supply it. A future network adapter would require an official platform API or documented written permission.

Quick start

Requires Python 3.10+ and has no runtime dependencies.

cd evidence-ledger
PYTHONPATH=src python3 -m evidence_ledger \
  --input examples/illustrative-evidence.json \
  --output /tmp/evidence-ledger-example.md

Then open /tmp/evidence-ledger-example.md.

Run the test suite:

PYTHONPATH=src python3 -m unittest discover -s tests -v

Input shape

{
  "title": "Decision title",
  "routes": [
    {
      "platform": "xiaohongshu",
      "backend": "visible_page",
      "status": "success",
      "result_count": 2,
      "login_state_used": false,
      "truncated": false
    }
  ],
  "records": [
    {
      "source_id": "xhs-001",
      "platform": "xiaohongshu",
      "original_url": "https://…",
      "retrieved_at": "2026-01-01T00:00:00Z",
      "source_opened_at": "2026-01-01T00:00:01Z",
      "verification_status": "verified",
      "evidence_kind": "reported_experience",
      "claims": [
        {
          "text": "The author reports a quiet weekday visit.",
          "claim_kind": "reported_experience"
        }
      ]
    }
  ]
}

See docs/input-schema.md for field rules and docs/xiaohongshu-adapter.md for public-safe source-adapter boundaries.

Xiaohongshu and other social sources

A social post can be useful evidence, but it is not automatically a verified fact. The public project ships no Xiaohongshu network adapter. For the Chinese Xiaohongshu service, the current user agreement (updated 2026-03-23) restricts, without written permission, reading/copying/adopting/statistically processing platform content and using non-authorized third-party software to log in or use the platform. Verify the agreement applicable to the user's region before any future integration.

Accordingly, this project accepts only user-supplied links or excerpts today. Any future provider must use an official API or documented written permission, operate under the user's current explicit authorization, stop at login/CAPTCHA/account-warning/payment/verification UI, and never export browser state or media by default. Personal narratives remain reported_experience, never universal facts.

For Xiaohongshu links, query parameters such as xsec_token may be necessary to revisit a page. Keep them only in the private original_url; strip them only from canonical_url for deduplication. Do not publish raw evidence bundles without reviewing their links and metadata.

Contributing

Please read CONTRIBUTING.md. The central rule is simple: a green test or search snippet is evidence of a narrow behavior, not a license to make a broader claim.

License

MIT — see LICENSE.