Shunya is a Python toolkit for systematic equity research: multi-ticker panels (finTs), JAX-friendly alphas (FinStrat, FinBT), portfolio construction, optional risk and broker helpers, plus a repo-local FastAPI service and React app in ui/ (Alpha Studio, backtests, dashboards).

Home dashboard (macro strip, movers, recent backtests) when the UI is pointed at a running API:

Long-form guides, concepts, HTTP API outline, Timescale, and the generated Python reference are on the documentation site:

kaushikdey647.github.io/shunya

Begin at Quickstart (library-only vs full stack vs Docker Compose).

Install the library from PyPI

pip install "shunya-py[dev]"

Clone: API + Timescale + UI (needs Docker, uv, Node.js 20+)

git clone https://github.com/Kaushikdey647/shunya.git
cd shunya
./scripts/local-dev-all.sh

Clone: full stack in Docker only (Docker only; no host Python/Node required)

git clone https://github.com/Kaushikdey647/shunya.git
cd shunya
cp .env.example .env   # optional: Alpaca, Ollama, SHUNYA_API_*; skip if defaults are enough
docker compose up --build

Open http://localhost:8080 (nginx UI; /api proxies to FastAPI). API directly: http://127.0.0.1:8000/docs. A bootstrap container runs before api: migrate plus optional Yahoo ingest when the DB is empty (see Local Timescale — Docker Compose bootstrap). The api container still runs shunya-timescale migrate on start when RUN_MIGRATIONS=1 (default). Compose loads repo-root .env into api (required: true); DATABASE_URL in Compose overrides .env so the API uses the timescaledb hostname inside Docker. See Quickstart — Path C for details.

Smoke-check the API: curl -sSf http://127.0.0.1:8000/healthz (or curl -sSf http://127.0.0.1:8080/api/healthz through the UI proxy). With local-dev-all.sh, open the URL Vite prints (default http://localhost:5173). Queued backtests run in the same process as uvicorn (api/main.py); you do not need a second “worker” process for normal local use.

After migrate, optional database seeding (example alphas, OHLCV ingest) uses the repo scripts/ helpers; see the docs guide Bootstrap scripts (API + UI + DB) or scripts/README.md. Example: ./scripts/local-dev-all.sh --seed-alphas inserts bundled api_alphas rows for GET /alphas.

Clone: run tests

git clone https://github.com/Kaushikdey647/shunya.git
cd shunya
uv sync --extra dev
uv run pytest

See CONTRIBUTING.md for architecture, extension patterns, and coding guidelines.

Licensed under the MIT License — see LICENSE.