canswim

Developer toolkit for CANSLIM investment style practitioners

NOT FINANCIAL OR INVESTMENT ADVICE. USE AT YOUR OWN RISK.

For a brief introduction read this blog post.

Here is also a video recording of a CANSWIM presentation for the Python Austin Meetup.

Documentation

Published site: https://ivelin.github.io/canswim/ (built from main / docs/ via GitHub Actions — not the legacy website branch).

Flags: python -m canswim -h is the source of truth. Local site preview: pip install mkdocs-material && mkdocs serve.

Setup

pip install canswim
# pin a release: pip install canswim==0.0.20260722

# dev checkout
pip install -e ".[dev]"

# recommended for this repo
conda activate canswim

CPU and GPU: forecasts run on CPU by default. If the active environment has a working CUDA build of PyTorch, GPU is used automatically — no canswim-specific device flag. Install torch from pytorch.org for your OS/GPU when you want acceleration (RTX 30/40-class, data-center GPUs, etc.). The same source tree and PyPI package are meant to work on contributor laptops and production hosts without host-specific code paths.

See CHANGELOG.md for release notes. Docs: https://ivelin.github.io/canswim/.

Local-first market data

By default gatherdata does not download or upload the full Hugging Face dataset. That HF snapshot step is slow and was a common reason the CLI “hung”. Instead:

1. Use local parquet under data/data-3rd-party/ (created/updated by gather).
2. Refresh from FMP / yfinance APIs as needed.
3. Resolve ticker universes from checked-in symbol_lists/*.csv.

# full-universe local gather (no HF dataset sync)
hfhub_sync=False python -m canswim gatherdata

# scoped list via --tickers (same pipeline as Dashboard Run + MCP gather_tickers)
hfhub_sync=False python -m canswim gatherdata --tickers "AAPL, MSFT"

Train/forecast skip tickers without complete ground-truth OHLCV (no synthetic price fill). Details: docs/data_store.md, docs/cli.md.

Get market data & run forecasts (CLI · GUI · MCP)

Two separate steps, same backend (canswim.run_triggers). Details: docs/run_triggers.md.

*MCP write tools need MCP_ALLOW_RUNS=1. Full MCP guide: docs/mcp.md.

Scoped get-market-data uses ~3 years of history (lookback + catch-up), fundamentals (unless --no_covariates), and skips downloads when local files are already complete. Forecasts stop if data is incomplete (no invented prices).

python -m canswim gatherdata --tickers "AAPL, MSFT"
python -m canswim resolve_start --forecast_start_date 2026-03-05
python -m canswim forecast --tickers AAPL --forecast_start_date 2026-03-05 --dry_run
python -m canswim dashboard --same_data True

Full recipes: docs/cli.md.

Production host (systemd sketch)

For a user-level long-running install:

Basics above; full unit templates, env, Funnel/Caddy apikey matrix, and data population: docs/deploy_service.md. MCP flags: docs/mcp.md.

Dashboard (GUI)

python -m canswim dashboard --same_data True

Sample screenshots

(If images are missing in a fork, open the dashboard locally and refresh captures under docs/images/ — same PR as any UI change.)

Historical example chart:

Command line (quick)

python -m canswim -h

Main tasks: dashboard, gatherdata, forecast, resolve_start, mcp, train, modelsearch, downloaddata, uploaddata.

→ docs/cli.md

MCP server (quick)

Read-only by default. Write tools need MCP_ALLOW_RUNS=1.

python -m canswim mcp
MCP_ALLOW_RUNS=1 python -m canswim mcp

→ docs/mcp.md for tools, client config, and prerequisites.