Quickstart

Requires Python 3.12+ on macOS or Linux.

pip install signalquarry
sqy init my-lab --demo        # synthetic data: no credentials needed
cd my-lab
sqy check                     # contract, determinism and look-ahead checks
sqy backtest --strategy sma-trend
sqy spec freeze --strategy sma-trend
sqy evaluate --strategy sma-trend
sqy report --strategy sma-trend
sqy paper dry-run --alias demo

On the demo, sqy evaluate is expected to exit with status 2 (blocked, GATE_FAILED): a trend filter on random synthetic prices should fail the walk-forward and stress gates, and it does. That is the framework working, not an error.

sqy prints a one-line summary in a terminal and the full JSON envelope when piped or with --json. Read status, reason_codes, evidence and next_actions; sqy explain <CODE> explains any reason code.

Synthetic data proves nothing about markets; the demo's claim level stays none. For real data, create a project without --demo, add your Alpaca keys (see Data) and run sqy data fetch --strategy <id> before backtesting.

Factor research offline

Create a demo project with sqy init factor-demo --demo --kind factor, then run these commands inside factor-demo:

sqy factor ls
sqy check --factor-id volume-shock
sqy factor evaluate --factor volume-shock --synthetic

Synthetic results diagnose the factor code path; they are not evidence about real markets and record no trial or holdout access.

Using a coding agent

Open the project in your agent (Claude Code, Codex, …). It reads AGENTS.md (CLAUDE.md points to it), which explains the golden path, the claim ladder and the stop conditions. Ask it for a hypothesis, not a result: "Test whether holding SPY only above its 150-day average reduces drawdowns." See Working with agents.