Metadata-Version: 2.5
Name: yuclaw
Version: 8.0.1
Summary: Evidence-first financial research — every signal traced to its SEC filings and verifiable against a public, git-anchored ledger. CLI + REST + MCP + LangChain/LlamaIndex. Research / education only — not investment advice.
Project-URL: Homepage, https://github.com/YuClawLab/yuclaw-brain
Project-URL: Documentation, https://github.com/YuClawLab/yuclaw-brain/tree/main/docs
Project-URL: Ledger, https://github.com/YuClawLab/yuclaw-trust
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai,evidence,finance,mcp,quant,research,sec-filings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Requires-Dist: feedparser>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: tenacity>=8.0
Provides-Extra: agents
Requires-Dist: langchain-core>=1.0; extra == 'agents'
Requires-Dist: llama-index-core>=0.11; extra == 'agents'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: uvicorn>=0.20; extra == 'api'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

<p align="center"><b>Research &amp; education only. Not investment advice.</b></p>

<!-- MISSION-VISION-CANONICAL:BEGIN -->
<h1 align="center">YUCLAW</h1>

<p align="center">
<b>Evidence-First Financial AI</b><br>
The Science Trust Layer for Financial AI.
</p>

<h2 align="center">Evidence before answers.</h2>

> Financial AI normally gives you an answer.
>
> **YUCLAW gives you the evidence** — what was known, when it was known, what it can support, what it cannot, and whether the conclusion survived.

### Mission

**Make financial AI accountable to evidence.**

- **Trace every claim** to the filing it came from.
- **Lock every method** before the data arrives.
- **State every conclusion’s limits.**
- **Keep every result** — including the ones we wished had come out differently.

A public, hash-linked record, built to be recomputed by anyone.

### Vision

**Become the Science Trust Layer for Financial AI.**

The evidence infrastructure that AI systems, researchers, and institutions use to decide what deserves to be believed.

### How we work

| Principle | Practice |
| :--- | :--- |
| **We don’t ask you to trust us.** | We give you the hash. |
| **We don’t predict.** | We register, compute once, and disclose. |
| **We don’t hide the days we were wrong.** | We chain them. |

### What you get

| For | What you get |
| :--- | :--- |
| **Analysts** | The evidence behind every label, and the label’s limits. |
| **Builders** | Machine-readable receipts — passports, endpoints, and a registry you can walk line by line. |
| **Institutions** | A record that can be audited without asking us. |

---

> *Statistics is one instrument. Evidence is the foundation. Science is the discipline.*
>
> *AI is the market. Trust is the product. Accountability is the mission.*

<p align="center">🍁 <b>Built in Canada</b></p>
<!-- MISSION-VISION-CANONICAL:END -->

<div align="center">

<!-- REPLICATION-SENTENCE-CANONICAL BEGIN -->
Designed for reproduction from published artifacts. One affiliated external-machine reproduction recorded; unaffiliated replications: 0.
<!-- REPLICATION-SENTENCE-CANONICAL END -->

![PyPI](https://img.shields.io/pypi/v/yuclaw)
![License Apache--2.0](https://img.shields.io/badge/License-Apache--2.0-green)
![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)
![Ledger git-anchored](https://img.shields.io/badge/Ledger-git--anchored-blue)

</div>

**First touch — install, ask for help, check a claim, reproduce the Lab** (expected exit code in the comment):

```bash
pip install yuclaw                                              # installs the CLI
yuclaw --help                                                   # command list with one-line descriptions · exit 0
yuclaw check-claim --text "NVDA reported an insider sale in May 2026"   # Evidence Passport JSON · exit 0
yuclaw check-claim --ticker NVDA --accession 0001045810-26-000019       # passport for one cited filing · exit 0
yuclaw check-claim --accession 0001045810-26-000019            # accession alone: unique → same passport · exit 0
                                                               # (ambiguous accession → exit 2 with the candidate tickers)
yuclaw replay-lab                                              # rebuilds every published Lab statistic · exit 0 = reproduced
```

Exit-code contract for every command: 0 = success · 1 = ran, negative result (e.g. a
replay mismatch) · 2 = usage or validation error · 3 = environment unsupported. The
transcript below is generated from the release-candidate wheel and regenerated every release:

<!-- CLI-TRANSCRIPT BEGIN -->
Transcript produced from the release-candidate wheel `yuclaw-8.0.1-py3-none-any.whl` (yuclaw 8.0.1, Python 3.12) by `tools/cli_transcript.py`; the `replay-lab` run uses the documented local-bundle path. Every command ran with `YUCLAW_CORPUS=snapshot`: `check-claim` answers from the corpus snapshot bundled in the wheel and never looks for a research node (without that setting, a host that reaches a research node answers from it and its passport has no `corpus` block). No date: release verification compares this block byte-for-byte with a fresh transcript of the final artifact, made the same way.

```text
$ yuclaw --version
yuclaw 8.0.1
[exit 0]
```
```text
$ yuclaw --help
yuclaw 8.0.1 — evidence-first financial research CLI (research and education only; not investment advice)

usage: yuclaw <command> [args]   ·   yuclaw <command> --help

commands:
  brief          evidence brief (legacy v3 helper)
  cascade        supply-chain cascade view for a ticker (deterministic, evidence-backed)
  challenge      structured challenge bound to an exact artifact + claim id; dispositions keep the original finding (v7)
  check-claim    Evidence Passport — deterministic claim check (--text, --ticker/--type/--date-range, --accession)
  decision       document-use receipt bound to an exact packet manifest digest; export needs permission (v7)
  demo           3-minute guided offline journey — zero config, no backend
  events         accepted-events export (derived data only)
  evidencebench  score EvidenceBench predictions against a supplied item set (--items; rubric v1 exact, v2 candidate; stdlib-only) (7.0.1)
  export         lens events export (--format csv|json; --page builds the evidence packet)
... (17 more lines)
[exit 0]
```
```text
$ yuclaw check-claim --text "NVDA reported an insider sale in May 2026"
{
 "status": "SOURCE_MATCHED",
 "claim_as_parsed": {
  "ticker": "NVDA",
  "type": "INSIDER_SELL",
  "accession": null,
  "date_range": null
 },
 "misses": [],
 "matched_evidence": "<5 object(s)>",
 "corpus": {
  "mode": "offline_snapshot",
  "snapshot_generated": "2026-08-06T01:06:08.732897+00:00"
 },
 "...": "<10 fields total; not_advice line present: True>"
}
[exit 0]
```
```text
$ yuclaw check-claim --ticker NVDA --accession 0001045810-26-000019
{
 "status": "SOURCE_MATCHED",
 "claim_as_parsed": {
  "ticker": "NVDA",
  "type": null,
  "accession": "0001045810-26-000019",
  "date_range": null
 },
 "misses": [],
 "matched_evidence": "<1 object(s)>",
 "corpus": {
  "mode": "offline_snapshot",
  "snapshot_generated": "2026-08-06T01:06:08.732897+00:00"
 },
 "...": "<10 fields total; not_advice line present: True>"
}
[exit 0]
```
```text
$ yuclaw check-claim --accession 0001045810-26-000019
{
 "status": "SOURCE_MATCHED",
 "claim_as_parsed": {
  "ticker": "NVDA",
  "type": null,
  "accession": "0001045810-26-000019",
  "date_range": null
 },
 "misses": [],
 "matched_evidence": "<1 object(s)>",
 "corpus": {
  "mode": "offline_snapshot",
  "snapshot_generated": "2026-08-06T01:06:08.732897+00:00"
 },
 "...": "<10 fields total; not_advice line present: True>"
}
[exit 0]
```
```text
$ yuclaw replay-lab docs/replay/lab_replay_bundle.json
Replay bundle built 2026-09-21 23:02 UTC from source commit 46832138a830
Ledger repo: https://github.com/YuClawLab/yuclaw-trust @ f30042a24acb

[forward] 83 rebalance periods, window ['2026-05-20', '2026-09-21']
  spread top_minus_bottom   mean/period -0.00222  t=-0.73 p=0.467  n=83  CI95=(-0.00821,+0.00371)
  spread top_minus_universe mean/period -0.00159  t=-0.94 p=0.351  n=83  CI95=(-0.00487,+0.00170)
  IC  1d  mean -0.0003  NW-t=-0.01 (lag 0) p=0.992  T=88 dates
  IC  5d  mean -0.0316  NW-t=-0.81 (lag 4) p=0.420  T=84 dates
  IC 20d  mean -0.0442  NW-t=-1.30 (lag 19) p=0.198  T=68 dates
  market-model vs_universe  alpha/period -0.00172 beta +1.12  t(alpha)=-1.00 p=0.320  R2=0.258  n=83
  market-model vs_spy       alpha/period -0.00113 beta +1.00  t(alpha)=-0.65 p=0.521  R2=0.210  n=83

[in_sample] 13 rebalance periods, window ['2026-02-18', '2026-05-18']
  spread top_minus_bottom   mean/period +0.00553  t=+0.41 p=0.686  n=13  CI95=(-0.01937,+0.03079)
... (11 more lines)
[exit 0]
```
<!-- CLI-TRANSCRIPT END -->

Protocol chain (statistics locked BEFORE computation, tamper-evident):
`curl -sO https://raw.githubusercontent.com/YuClawLab/yuclaw-brain/main/registry/protocols.jsonl` ·
full clean-environment replication: `make replicate`.

**[How we compare →](COMPARISON.md)** · **[Take the 5-minute tour →](https://yuclaw.ca/tour.html)**

**What you'll find inside:** the baseline test our own composite lost at current
sample sizes — published under the pre-registered protocol · a label-calibration
panel that says "directional meaning not yet demonstrated" · retired hypotheses
preserved with their grounds · 500+ filings shown to be 3 evidence stories ·
robustness grids that print where results break.

**Research and education only — not investment advice.** Signal labels are
research classifications, not buy/sell recommendations.

<div align="center">

[Live site (yuclaw.ca)](https://yuclaw.ca) ·
[Validation Lab](https://yuclaw.ca/validation_lab.html) ·
[SMH Evidence Lens](https://yuclaw.ca/etf_evidence.html) ·
[XLK Evidence Lens](https://yuclaw.ca/xlk_evidence.html) ·
[Canada Resources](https://yuclaw.ca/canada_resources.html) ·
[Forward Tracking](https://yuclaw.ca/validation.html) ·
[📖 Current guide (v8)](https://github.com/YuClawLab/yuclaw-brain/blob/main/v8/workbench/resources/OPERATOR_GUIDE.md) ·
[Earlier PDF guide (version 5 era, historical)](https://yuclaw.ca/YUCLAW_User_Guide.pdf) ·
[Guide PDF antérieur (FR, historique)](https://yuclaw.ca/YUCLAW_Guide_Utilisateur_FR.pdf) ·
[Weekly Note](https://yuclaw.ca/weekly_note.html) ·
[For AI agents → llms.txt](https://yuclaw.ca/llms.txt) ·
[**⚠️ Disclaimer**](#%EF%B8%8F-disclaimer) ·
[PyPI](https://pypi.org/project/yuclaw)

</div>

> [!IMPORTANT]
> **Research and education only — not investment advice.** Signal labels are research
> classifications, not buy/sell recommendations. Hypothetical research; past results do
> not predict future performance.

---

## v8 — the local workbench and its four modules

`yuclaw.ca` is the **research-content site**. The v8 **workbench** is a different thing: an application that runs **on your own
computer** — it binds `127.0.0.1` only, your data stays in the workspace folder you name, there is no hosted service and no account.
It traces one financial commitment from an exact source passage through a **typed, frozen claim**, its revisions, exact calculation,
history and review to an **export that a fresh workspace re-verifies**. Four modules work on the same records:

| Module | In plain words |
|---|---|
| **SHD** — Distillation Shield | Protected evidence intake: a bundle is admitted only with another administrator's signed approval for its exact bytes, and it is parsed inside a restricted worker. |
| **EVO** — Evolution Evidence Audit | Records what changed in an AI system (model, code, tools, memory, data, runtime, grader, evaluation data) and decides which earlier evidence still applies. |
| **COM** — Research Commons Guard | A fair, bounded review queue: one task per duplicate group, admission limits, review budgets, disputes kept. |
| **PRC** — Independent Practice | Attempt first, then compare: one preserved attempt before the comparison opens; assistance and exposure are declared, not hidden. |

```bash
pip install yuclaw
yuclaw workbench selftest                                  # checks this installation in a temporary fictional workspace (no test tools needed)
yuclaw workbench principals init --workspace ~/yuclaw-ws   # optional: roles for the four modules; prints the first administrator's credential once
yuclaw workbench serve --workspace ~/yuclaw-ws             # then open http://127.0.0.1:8765   (Ctrl-C stops it)
yuclaw workbench guide                                     # the full guide, from the package (the same text as the link below)
```

In the browser: load a fictional example on the Workspace page, follow its seven steps, build the export, then verify it in a second,
fresh workspace ([current guide](https://github.com/YuClawLab/yuclaw-brain/blob/main/v8/workbench/resources/OPERATOR_GUIDE.md)). `python -m v8.workbench …` is the same program.

**Status: experimental, local, owner-operated.** Including the modules activates nothing — no role, approval, budget or study exists
until you set one up. Protected SHD admission needs **Linux with Landlock**; on macOS, Windows or a kernel without it that one route
stays closed and everything else works. No independent security review has been performed, and there has been no user study: human
benefit is PENDING. What has and has not been demonstrated is on the [evidence scoreboard](https://yuclaw.ca/evidence_scoreboard.html),
under its own as-of time.

## v7 — check → reproduce → challenge → document use (outsider verification, offline)

Everything below runs without an account or a hosted service. The outputs below were recorded on the 7.0.0 candidate checkout (operator runs; **not** outsider receipts); the commands are unchanged since, and the manifest digest is different for every later tree.

```
$ yuclaw packet build ./yuclaw-packet --source <checkout>
[packet] built ./yuclaw-packet: 10 files, source <sha>; verify with: yuclaw packet verify ./yuclaw-packet
$ yuclaw packet verify ./yuclaw-packet
[packet] SUCCESS — manifest b89617e9735ecd5d…; exact bytes verified and published Lab statistics/ledger roots reproduced from the frozen bundle; not an outsider receipt, not a research interpretation
$ # after one byte of an artifact is changed:
[packet] MISMATCH — manifest b89617e9735ecd5d…; first discrepancy: byte mismatch at docs/capabilities.json: expected 96beff4fa51b4f91…/3341 B, observed 4c2a56369d42a623…/3341 B
```

- `yuclaw check-claim …` now returns `support_limits` — source match, temporal eligibility, replay status and `research_interpretation: NONE` — plus an explicit unsupported-conclusion sentence ("a coverage statement, not a finding that the claim is false").
- `yuclaw challenge --store <private> create …` records a challenge bound to an exact artifact (type, sha256, byte length) and a claim id; a `RESOLVED` disposition must name a tested **revised** artifact and never erases the original finding.
- `yuclaw decision --store <private> record …` records a research decision (investigate further / discard / request evidence) bound to a packet manifest digest; export needs explicit permission.
- `yuclaw receipts --store <private> …` imports an attempt, verifies artifact bytes, records a designated review and derives counts. Primary counts are **qualified attempts** (failed and inconclusive retained); successful attempts are reported separately; package evidence (wheel, sdist) is separate from site checks; program-wide exact-artifact evidence is separate from a release's exact-target evidence (bound to an independently supplied target manifest, UNBOUND until then). A submission can describe an outcome; it cannot award itself qualification. `yuclaw receipts --store <private> explain <receipt id>` answers "why did this count / not count?" with reason codes; `yuclaw receipts --store <private> history a.json b.json` compares two published scoreboard snapshots (additions, supersessions rendered CORRECTED in their original window, disposition changes, per-window and absolute movement).
- The **Evidence Scoreboard** (`evidence_scoreboard.html`, `/receipts/scoreboard.json`, REST `/v1/receipts/scoreboard`, MCP `get_evidence_scoreboard`) shows witnesses, pilots, replications, audits, refusals, packet uses and challenges with their counting definitions. Zero and pending are real states; no trust score is computed. Registration of the receipt program is pending (owner decision), so counts are unwindowed.

## Why this is different

- **Statistics are registered before they are computed.** Every published
  statistic names its protocol in a hash-chained, append-only registry
  ([registry/protocols.jsonl](registry/protocols.jsonl)); estimator changes
  are supersessions, never edits. Check the chain yourself:

  ```bash
  python3 - <<'EOF'
  import sys; sys.path.insert(0, 'tools')
  from yuclaw_protocol_registry import Registry
  Registry('registry/protocols.jsonl').verify_chain(); print('chain OK')
  EOF
  ```

- **Self-audits publish as measured.** A pre-registered champion-challenger
  test found a persistence baseline ahead of our own composite at the primary
  horizon — that table is on the [Lab page](https://yuclaw.ca/validation_lab.html),
  not in a drawer. The label-calibration panel prints where labels carry no
  demonstrated directional meaning.
- **Lenses pass a published admission standard or they don't ship.** The XLK
  lens is live because it passed the same admission standard the SMH lens
  registered; verdicts and their reasons print on each page.
- **The evidence layer is machine-readable.** [llms.txt](https://yuclaw.ca/llms.txt)
  and [evidence_index.json](https://yuclaw.ca/evidence_index.json) give AI
  agents stable URLs for every page, packet, and protocol.

---

## What YUCLAW does

- **Every signal traces to a filing.** Each composite score decomposes into nine
  components, and every evidence event links to the SEC document it was
  extracted from — checked against the source text before any signal sees it.
- **Every snapshot is hashed to a public, tamper-evident ledger — git-anchored,
  never edited.** Daily signal sets are content-hashed and committed to
  [yuclaw-trust](https://github.com/YuClawLab/yuclaw-trust) before pages
  publish. Outages are disclosed, never backfilled.
- **Every Lab chart is reproducible bit-for-bit.** `yuclaw replay-lab` (or a
  standalone stdlib script) rebuilds the cohorts, recomputes every statistic,
  and re-derives every ledger hash root from published derived data.

---

## Sixty seconds

```bash
pip install yuclaw
yuclaw demo                        # 3-minute guided journey — works offline, zero config
yuclaw why AMD --as-of 2026-05-20  # bundled offline signal, no backend needed
```

Live signals for **all** tickers need the local backend
([docs/v4/backend_setup.md](docs/v4/backend_setup.md)); the published-data
commands work anywhere with no backend. The most recent recorded external-machine
replication (see the [Replication Log](https://yuclaw.ca/replication.html)) ran
`replay-lab` from a fresh venv with nothing but `pip install yuclaw` and reproduced
**74 daily ledger roots exactly plus one anchored-subset day (6,165 leaf hashes
recomputed)** and every published statistic, exit 0. It exits non-zero on any
mismatch.

---

## What is in 6.0.x

Current package version: `8.0.1` — the release notes, the frozen wheel and sdist
SHA-256 hashes, and the shipped-object list live on the
[GitHub Release for this version](https://github.com/YuClawLab/yuclaw-brain/releases/tag/v8.0.1)
([all releases](https://github.com/YuClawLab/yuclaw-brain/releases) ·
[CHANGELOG](CHANGELOG.md)). 7.0.0 adds the receipt engine, the offline verification packet, structured claim-support limits, local challenges and document-use receipts, and the Evidence Scoreboard. Scientific states are unchanged: Gate #15 stays MANUAL_REVIEW, Phase 6 N_eff stays PENDING, C6 stays DESCRIPTIVE, U350 stays shadow-only. Zero outsider receipts exist at release; the scoreboard shows that as a real zero.

### Command surface

```bash
yuclaw --help                      # Command list with one-line descriptions (also -h, help)
yuclaw why TICKER                  # Composite signal + ranked evidence w/ SEC source URLs
yuclaw check-claim --text "..."    # Evidence Passport — deterministic claim check (also --ticker/--type/--date-range/--accession)
yuclaw replay TICKER --date DATE   # Point-in-time signal at end of date
yuclaw replay-lab                  # Reproduce the Validation Lab from the public bundle
yuclaw validation                  # In-sample event validation + forward tracking ledger
yuclaw events --ticker SU --since 2026-05-01   # Accepted-events export (derived data only)
yuclaw lens canada --lens XEG      # Lens summary-card data as JSON (same numbers the page renders)
yuclaw export --lens GDX --format csv          # Lens events export; --page builds the evidence packet
yuclaw memo --ticker SU --days 30  # Evidence memo — grounded, citation-verified, linted (docs/usage.md)
yuclaw verify TICKER --date DATE   # Verified Research Ledger integrity check
```

Worked examples with real output: [docs/usage.md](docs/usage.md).

**Public signal vocabulary:** `STRONG_BULLISH`, `BULLISH`, `NEUTRAL`, `WATCH`,
`WEAKENING`, `NEGATIVE_EVENT`, `BEARISH_WATCH`, `RISK_ALERT`.
There is no `SELL` or `SHORT` label — these are research classifications, not trade directions.

---

## How it works

```
SEC EDGAR (Form 4 / 8-K / 10-Q / 10-K / 6-K / 20-F / 40-F)
  │
  ▼ systemd poller (always-on, 5-min sweep)
  ├──▶ Form 4 → deterministic XML parser (no LLM, zero GPU) → events table
  ▼ prose-first text acquisition (exhibit / MD&A prose; XBRL cover fallback)
  ▼ Llama 3.1 70B extraction + SourceLock Guard (checked against source text)
  ▼ events table — the evidence layer
  ▼ Layer-1 specialist swarm (10 specialists; risk channel kept SEPARATE from direction)
  ▼ 9-component composite (C1..C9)
  ▼ signal_snapshots (content-hashed)
  ├──▶ Verified Research Ledger (git-anchored, public)
  ├──▶ Forward Tracking Ledger (outcomes vs SPY at 1 / 5 / 20 days)
  ├──▶ Live landing + Validation Lab pages (regenerated daily)
  └──▶ SDK / REST / MCP server
```

**132-name coverage:** a 79-name scoring universe (equities + sector ETFs +
broad ETFs + macro instruments) plus a 53-filer evidence tier (49 Canada Resources
issuers + 4 SMH-lens foreign filers: ASML, NXPI, STM, TSM) — ingested and
dashboarded, never scored; the boundary is machine-enforced.

Deep dives: [system architecture, operations, hardware](docs/architecture.md) ·
[OpenClaw / MCP integration](docs/openclaw.md) ·
[methodology](docs/methodology/backfill.md).

---

## Signal Validation Lab

A decile-cohort event study of whether YUCLAW's composite score carries forward
information — methodology reviewed by two senior finance/methodology academics, plus a structured multi-AI critique loop:

- **Regenerated daily** after U.S. market close, freshness-stamped, with a
  staleness alarm in the health monitor.
- **Statistical rigor panel:** bootstrap confidence intervals, Newey–West and
  clustered inference, market-model alpha, and a statistical power meter that
  quantifies what the current n can and cannot detect.
- **Statistics computed per-regime** (in-sample vs forward) and never blended
  across the boundary.
- **Reproduce this page:** `yuclaw replay-lab` or the standalone stdlib script.

In the Lab's own words: *"No forward alpha has been statistically proven yet."*

🔬 **Live:** [Signal Validation Lab](https://yuclaw.ca/validation_lab.html)
· [Today's Evidence Digest](https://yuclaw.ca/todays_evidence.html)
· [Independent Replication Log](https://yuclaw.ca/replication.html)
· **Methodology:** [docs/methodology/validation_lab.md](docs/methodology/validation_lab.md)

*Hypothetical research illustration — not investment advice, not performance advertising.*

---

## Methodology & honest limitations

Full methodology lives in [docs/methodology/backfill.md](docs/methodology/backfill.md).
The honest limits, stated up front:

- **The forward record is young.** Forward tracking began 2026-05-20; roughly
  50 trading days of look-ahead-free history exist as of early August 2026 —
  enough to display, not enough for statistical significance; the Lab's power
  meter quantifies this.
- **In-sample is replay reconstruction, not a live backtest.** The in-sample
  panel was materialized after the fact by the replay engine; the canonical
  look-ahead statement below says exactly what the extraction model could and
  could not have seen, and why in-sample results stay systematically optimistic.
- **C6 risk channel is partially confirmed.** Rareness confirmed OOS; the sign
  question remains open — the first read under the registered v2 protocol
  printed INCONCLUSIVE (2026-07-30) and accrual continues. The sign
  confirmation is the gate for Layers 2–10, and it has not been met.
- **C4 macro regime is temporarily frozen as of 2026-05-18** with a staleness
  disclosure, pending macro-engine restoration. C1/C3/C5/C7 read live
  `price_history`; C6/C8/C9 remain point-in-time exact.
- **Jun 26 – Jul 3, 2026 outage — disclosed, not patched.** A network outage
  froze price-derived inputs at Jun 25 closes while snapshots continued
  point-in-time on-box. No snapshot or ledger row was retroactively edited.
- **No table of headline % returns appears in this README.** Hit rates are
  reported alongside their *n* on the
  [live validation page](https://yuclaw.ca/validation.html); small-*n* panels
  are tagged.

**Look-ahead statement** — canonical text, byte-identical on every surface
(README, methodology, Validation Lab page; checked by the copy-consistency gate):

<!-- LOOKAHEAD-CANONICAL BEGIN -->
In-sample look-ahead statement. The in-sample replay rows (signal dates 2026-02-18
to 2026-05-13, evidence window 2026-02-18 to 2026-05-17) were built from evidence
events extracted by one language model, Meta Llama 3.1 70B Instruct (served
locally as yuclaw-llm-70b), whose published pretraining cutoff is December 2023
(Meta model card). Form 4 events in the window come from a deterministic XML
parser with no language model. The earliest in-sample date is about 26 months
after that cutoff, so no filing text in the window could have been seen in
training: there is no parametric look-ahead from the filings themselves, and the
model's general market knowledge also ends before the window begins. The replay
engine flags any as-of date before 2024-07-01 as inside the model's training
window; no in-sample date triggers it. In-sample results nonetheless remain a
replay reconstruction, not a live record: the scoring design was finalized in May
2026, after the window it is replayed over, market-layer components read
approximated inputs, and no in-sample signal was exposed to external challenge in
real time. In-sample results are therefore treated as systematically optimistic
and educational only; the forward record (signal dates from 2026-05-20) is the
look-ahead-free record.
<!-- LOOKAHEAD-CANONICAL END -->

---

## Community

| | |
|---|---|
| **Live site** | [yuclaw.ca](https://yuclaw.ca) |
| **Validation Lab** | [validation_lab.html](https://yuclaw.ca/validation_lab.html) |
| **SMH Evidence Lens** | [etf_evidence.html](https://yuclaw.ca/etf_evidence.html) |
| **XLK Evidence Lens** | [xlk_evidence.html](https://yuclaw.ca/xlk_evidence.html) |
| **📖 Guides** | [Current guide (v8, English)](https://github.com/YuClawLab/yuclaw-brain/blob/main/v8/workbench/resources/OPERATOR_GUIDE.md) — also `yuclaw workbench guide` · earlier PDF guides (written for the version 5 command line, 12 pages, historical, not updated for v8): [EN](https://yuclaw.ca/YUCLAW_User_Guide.pdf) · [FR](https://yuclaw.ca/YUCLAW_Guide_Utilisateur_FR.pdf) |
| **Twitter** | [@Vincenzhang2026](https://twitter.com/Vincenzhang2026) |
| **GitHub** | [YuClawLab](https://github.com/YuClawLab) |
| **PyPI** | [pypi.org/project/yuclaw](https://pypi.org/project/yuclaw) |
| **Methodology** | [docs/methodology/backfill.md](docs/methodology/backfill.md) |

---

## ⚠️ Disclaimer

YUCLAW is open-source research and educational software. It is **NOT financial advice,
investment advice, or a recommendation to buy, sell, or hold any security.** All signals,
scores, and analyses are generated by automated AI models and may contain errors.

Past performance does not guarantee future results. Trading involves substantial risk of loss.
You are solely responsible for your own investment decisions. Consult a licensed financial
advisor before making any investment.

YuClawLab, its contributors, and affiliates accept no liability for any losses arising from use
of this software.

For educational and research purposes only. See
[docs/methodology/backfill.md](docs/methodology/backfill.md) and
[DISCLAIMER.md](DISCLAIMER.md) for the long-form versions.

---

## For AI agents & researchers

The open evidence layer for financial AI.

Agents citing YUCLAW inherit accession-verified, point-in-time, hash-anchored
evidence. Start at [capabilities.json](https://yuclaw.ca/capabilities.json) — one URL discovers
the why-JSON API, the Evidence Passport, the schemas, EvidenceBench, and the MCP tools
([full pitch](https://yuclaw.ca/for_ai_builders.html)).

- **Start here**: [`llms.txt`](https://yuclaw.ca/llms.txt) and the
  machine-readable [`evidence_index.json`](https://yuclaw.ca/evidence_index.json)
  (every page, packet, and protocol with stable URLs and data-through dates).
- **Objects**: the five frozen v1 JSON Schemas — SignalSnapshot, EvidenceEvent,
  ResearchProtocol, RobustnessCell, ResearchMemo — at [/schemas/](https://yuclaw.ca/schemas/SignalSnapshot.v1.json);
  today's real outputs validate against them in the daily gate suite.
- **Consume**: evidence packets (derived statistics, event CSVs, engine run
  JSONs, metadata + citation snippets) from `/packets/`; the MCP server
  exposes `why / memo / events / lens / universe / validation / verify` as
  tools with friendly no-backend behavior.
- **Cite**: use the `CITATION.txt` inside any packet; event-level citations
  use event IDs resolvable in the packet CSVs.
- **Verify**: `pip install yuclaw && yuclaw replay-lab` recomputes the
  published Lab statistics from the public bundle; the protocol registry
  ([registry/protocols.jsonl](registry/protocols.jsonl)) is hash-chained and
  append-only.
- **Rules**: derived statistics only; preserve the disclaimers and the
  frozen implication line when quoting inference; nothing here is advice
  or a recommendation.
<div align="center">

**Released under the Apache License 2.0 — free for everyone.**

`pip install yuclaw`

</div>
