1What YUCLAW is (and is not)

YUCLAW ingests SEC filings (Form 4, 8-K, 10-Q, 10-K, 6-K, 40-F), extracts typed evidence events with a locally hosted LLM, checks every extraction against the source text with a deterministic verifier, and combines the evidence with market context into a nine-component composite research signal. Every day’s signal set is content-hashed and committed to a public git repository (yuclaw-trust) before pages publish — so the record is tamper-evident and independently checkable.

Three design commitments define the project:

• Every signal traces to a filing. Each composite decomposes into its components, and every evidence event links to the SEC document it came from.
• Every snapshot is hashed to a public ledger. Git-anchored, never edited. Outages are disclosed, never backfilled.
• Every published chart is reproducible. yuclaw replay-lab rebuilds the cohorts and recomputes every statistic and ledger hash from published derived data, and exits non-zero on any mismatch.

What YUCLAW is not: it is not a trading system, does not connect to any broker, does not manage money, and does not produce buy/sell recommendations. The ingestion and extraction pipeline runs on the project’s own hardware (a single NVIDIA DGX-class node); as a user you consume the published, hash-anchored outputs through the CLI, SDK, REST API, MCP server, and dashboards.

2Install and your first signal

Requirements: Python 3.10 or newer, pip, and an internet connection. No GPU is needed to use published signals or reproduce the Validation Lab.

Live signals for all tickers need the local backend (docs/v4/backend_setup.md); the published-data commands — replay-lab, verify, validation — work anywhere with no backend. With the backend running, yuclaw why NVDA produces output shaped like this (backend-mode output, abbreviated):

Three things to notice: the label (NEUTRAL) is a research classification of the composite score; each component’s contribution is shown with its weight; and every contributing event carries a link to the SEC document it was extracted from. If you take one habit from this guide, take this one: follow the source links. The engine is built to show its work — make it.

3Reading a signal

The nine components

The composite is a confidence-weighted sum of nine components. C6 (event impact) carries the highest single weight by design: evidence is meant to correct price-only signals, not echo them.

* C2 (volume confirm) currently contributes no signal — confidence-gated to zero since v3.0 pending volume-feed wiring; live composite weights effectively renormalize across the remaining eight components. Repair-vs-deprecation decision scheduled for v5.2.

Signal labels

The public vocabulary is fixed: STRONG_BULLISH · BULLISH · NEUTRAL · WATCH · WEAKENING · NEGATIVE_EVENT · BEARISH_WATCH · RISK_ALERT. These bucket the composite score and risk state; exact thresholds are documented in docs/methodology/backfill.md. Two facts worth knowing: extreme labels (STRONG_BULLISH, BEARISH_WATCH) are rare by construction — they require broad component agreement plus at least one material non-insider event — and there is deliberately no SELL or SHORT label: these are research classifications, not trade directions.

The universe

Signals cover a 79-name scoring universe (equities, sector ETFs, broad ETFs, macro instruments). Separately, a 49-filer Canada Resources evidence tier (XEG / ZEO / GDX / URNM constituents) is ingested and dashboarded but never scored — the boundary is machine-enforced and regression-tested. See Section 6.

4Command reference

* Ships in v5.1; run from a main checkout meanwhile (see the version note in Section 2). Worked examples with real output: docs/usage.md.

5Verify everything yourself

YUCLAW’s central claim is not that its signals are good — that is for the data to prove or disprove in public. The claim is that nothing is unverifiable. Three tools back it:

5.1  Reproduce the Validation Lab

This runs from a brand-new environment with nothing but the pip install. At the v5.0.0 release it reproduced every published daily ledger root and statistic exactly from a fresh venv. A standalone stdlib script (tools/replay_lab.py) does the same with no dependencies at all.

5.2  Check a specific signal against the public ledger

Recomputes the signal’s hash and checks it against the git-anchored ledger in yuclaw-trust — independent confirmation that the record hasn’t been edited since publication. For any other ticker/date, clone github.com/YuClawLab/yuclaw-trust next to your working directory (the full public ledger) or connect the local backend.

5.3  Replay any signal as of a past date

Point-in-time filtering (available_as_of ≤ as_of) guarantees the replay uses only information that existed on that date. The same capability is exposed over REST (/replay) and MCP (yuclaw_replay).

5.4  Publish your replication

If you run a reproduction, the project wants your result — pass or fail. Open a GitHub issue using the replication template (it asks for OS, Python version, command, output hash, and result). Accepted reports appear on the public Independent Replication Log. A failed reproduction is a bug report of the highest value: the verifier exiting non-zero is exactly the alarm it exists to raise.

6Dashboards and daily surfaces

Every page carries a freshness stamp. If the pipeline has an outage, the gap is disclosed on the page and never backfilled — a visible gap is the honest state of the record.

7Evidence memos and data exports

Evidence memos

yuclaw memo --ticker SU --days 30 produces a short research memo in which every sentence cites an event ID that resolves to a filing excerpt. Generation uses the local LLM; verification does not: a deterministic verifier checks each citation against source text, and a linter enforces a restricted conclusion vocabulary plus the research-only footer. Memos require a full local deployment (events database + local models) — pip-only users can read the approved demo at docs/examples/evidence_memo_su.md to see the exact output shape.

Evidence packets and exports

yuclaw export --lens GDX --page builds an evidence packet: a zip of typed events, verified excerpts, and replay data, each carrying citation metadata (data_through, build_date, source_commit, ledger_root, methodology_version, scope_note, known_limitations) so anything you quote downstream stays traceable.

8Programmatic access: SDK, REST, MCP

• Python SDK — pip install yuclaw; the same signal, replay, and verify surfaces as the CLI, importable.
• REST API — FastAPI server (v3/api/) including the /replay endpoint for point-in-time queries.
• MCP server — FastMCP stdio server exposing 7 tools (including yuclaw_replay), for use from MCP-capable AI clients.
• OpenClaw skill — install via yuclaw/openclaw/install.sh, or run python3 yuclaw/openclaw/mcp_server.py (port 8002).

All inference in the pipeline is local to the project’s node (Llama 3.1 70B + Gemma via one Ollama daemon) — there are no cloud LLM calls anywhere, and SEC EDGAR is the evidence layer’s only external data source.

9Honest limitations

These are stated up front on the site and repeated here because a user guide that hides them would defeat the project’s point. Full detail: docs/methodology/backfill.md.

• The forward record is young. Look-ahead-free forward tracking began 2026-05-20. In the Lab’s own words: “No forward alpha has been statistically proven yet.” The on-page power meter quantifies what the current sample can and cannot detect.
• In-sample results are optimistic by construction. The In-Sample Event Validation panel was reconstructed after the fact by the replay engine, and the extraction model’s training window overlaps it — treat in-sample numbers as an upper bound, not a promise.
• C6 risk channel is partially confirmed. C6 risk channel: rare-by-construction confirmed OOS (22% fire rate, n=9 held-out); sign positive at n=2 elevated — accruing. Deeper architecture layers are gated on that confirmation.
• C4 macro regime is temporarily frozen (as of 2026-05-18, with an on-page staleness disclosure) pending macro-engine restoration.
• Small samples are labeled. Panels with too few observations for inference say so on the page; no headline return tables appear without their n.

10Troubleshooting, support, and disclaimer

YUCLAW User Guide · written for the v5.0 series · the repository README and docs/ are authoritative where this guide and newer releases differ.

AAppendix — quick reference card

Print this page and keep it near the terminal.