# Local Development

## Install
Python and web dependencies:

```bash
uv sync --extra dev
npm install
```

Optional local Timescale bootstrap:

```bash
./ops/run-db.sh
export UFORIA_DB_ENABLED=true
export UFORIA_DB_DSN=postgresql://uforia:uforia@127.0.0.1:5432/uforia
uv run uforia-admin db init
```

## Run the full local stack
From the repo root:

```bash
npm run dev
```

That starts:
- the Python API via `uv run uforia-api`
- the Next.js UI via `npm --workspace apps/web run dev`

Default local endpoints:
- UI: `http://localhost:3000`
- API: `http://127.0.0.1:8000`
- WebSocket: `ws://127.0.0.1:8000/api/v1/stream`

Useful DB env vars:
- `UFORIA_DB_ENABLED=true`
- `UFORIA_DB_DSN=postgresql://uforia:uforia@127.0.0.1:5432/uforia`
- `UFORIA_DB_READ_MODE=auto`
- `UFORIA_DB_WRITE_MODE=dual`

## Build data locally
For the current multi-asset vol suite, including the options and perps dashboards:

```bash
for UNDERLYING in BTC ETH; do
  uv run uforia-admin ingest deribit-dvol --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin ingest deribit-funding --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-index --underlying "$UNDERLYING" --source dvol --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build rvvix --underlying "$UNDERLYING" --source dvol --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build qvvix --underlying "$UNDERLYING" --source dvol --ts 2026-03-08T23:00:00Z
  uv run uforia-admin build razor --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-surface --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-carry --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-skew --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-dislocations --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-positioning --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-cone --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build term-structure-momentum --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build gamma-exposure --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build funding-context --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build straddle-breakeven --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build surface-factor-rv --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build ml-carry-toxicity --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build expiry-flow-map --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build adaptive-hedging --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build sessionality-clocks --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build funding-basis-skew --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-signals --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-regime-transitions --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-signals --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-composites --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-transitions --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite-components --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite-transitions --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
done
uv run uforia-admin build options-rv --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
uv run uforia-admin build btc-eth-dispersion --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
```

Or use the umbrella command:

```bash
uv run uforia-admin build alpha-canvas --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z --underlyings BTC,ETH
```

## Build the TCN-Boost microstructure stack locally

Import old history, train the hybrid model stack, and generate paper predictions:

```bash
uv run uforia-admin microstructure import-history --root /Users/mubaris/dev/crypto-microstructure

for ASSET in BTC ETH; do
  uv run uforia-admin microstructure build-features --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin microstructure build-labels --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z --horizons 30s,1m,2m,5m
  uv run uforia-admin microstructure build-regime --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin microstructure train --asset "$ASSET" --horizon 1m
  uv run uforia-admin microstructure evaluate --asset "$ASSET" --horizon 1m
  uv run uforia-admin microstructure generate-signals --asset "$ASSET" --horizon 1m
done
```

To generate the full initial signal set that feeds the dashboard tables, train all default horizons:

```bash
uv run uforia-admin microstructure import-history --root /Users/mubaris/dev/crypto-microstructure

for ASSET in BTC ETH; do
  uv run uforia-admin microstructure build-features --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin microstructure build-labels --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z --horizons 30s,1m,2m,5m
  uv run uforia-admin microstructure build-regime --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  for HORIZON in 1m 2m 5m 30s; do
    uv run uforia-admin microstructure train --asset "$ASSET" --horizon "$HORIZON"
    uv run uforia-admin microstructure evaluate --asset "$ASSET" --horizon "$HORIZON"
    uv run uforia-admin microstructure generate-signals --asset "$ASSET" --horizon "$HORIZON"
  done
done
```

Run live collection plus live inference locally:

```bash
./ops/run-microstructure-live.sh
./ops/run-microstructure-inference.sh
```

Rust engine scaffold checks:

```bash
cargo check
cargo run -p uforia-ms-app -- health
```

Repo-managed service templates are available under `launchd/`, and the helper:

```bash
./ops/install-launchd.sh
```

installs them into `~/Library/LaunchAgents` for local daemon-style testing on macOS.

## Execution layer locally

Execution uses repo-managed accounts config and stays operator-triggered in this phase.

Bootstrap a local execution accounts file:

```bash
cp config/execution_accounts.example.json config/execution_accounts.json
```

Useful execution env vars:
- `UFORIA_EXECUTION_ENABLED=true`
- `UFORIA_EXECUTION_ACCOUNTS_PATH=config/execution_accounts.json`
- `UFORIA_EXECUTION_DEFAULT_MODE=dry_run`
- `UFORIA_EXECUTION_KILL_SWITCH=false`
- `UFORIA_HYPERLIQUID_PRIVATE_KEY=...`
- `UFORIA_LIGHTER_API_PRIVATE_KEY=...`
- `UFORIA_DERIVE_SESSION_KEY=...`
- `UFORIA_DERIVE_PRIVATE_KEY=...`
- `UFORIA_BEBOP_PRIVATE_KEY=...`
- `UFORIA_BEBOP_RPC_URL=...`

Seed execution market/health state, run the Rust execution heartbeat locally, and sync live venue state:

```bash
uv run uforia-admin execution seed-markets --asset BTC
cargo run -p uforia-execution-app -- run --health-path data/execution_live/health/latest.json
uv run uforia-admin execution sync-state --health-path data/execution_live/health/latest.json
uv run uforia-admin execution sync-live-state --venue hyperliquid --account hyperliquid-main --asset BTC
```

Useful dry-run checks:

```bash
uv run uforia-admin execution seed-markets --asset ETH --venue hyperliquid
cargo run -p uforia-execution-app -- dry-run-order --venue hyperliquid --symbol BTC-PERP
cargo run -p uforia-execution-app -- dry-run-order --venue bebop --symbol BTC-USD
```

Useful live operator checks:

```bash
uv run uforia-admin execution sync-live-state --venue derive --account derive-main --asset BTC
uv run uforia-admin execution sync-live-state --venue lighter --account lighter-main --asset BTC
curl http://127.0.0.1:8000/api/v1/execution/markets
curl http://127.0.0.1:8000/api/v1/execution/health
```

Bebop live orders are quote-driven:

1. request a live quote
2. capture the returned `quote_id`
3. submit a live order with that `quote_id`
4. if the quote payload was already written to `execution_quote_snapshot`, `uforia` can hydrate it automatically for self-execution

If you need to repopulate normalized option snapshots from archived raw Deribit payloads after a schema upgrade, run:

```bash
uv run uforia-admin maintenance rebuild-options-from-archive \
  --underlying BTC \
  --start 2026-03-09T00:00:00Z \
  --end 2026-03-09T23:00:00Z
```

## Environment
Useful web env file:

```bash
cp apps/web/.env.local.example apps/web/.env.local
```

For LAN browser access, prefer using the deployed host and let the browser-side client derive:
- API host from the page hostname
- WebSocket host from the page hostname

The default production-facing URLs on the Mac Mini are plain HTTP, not HTTPS:
- `http://192.168.1.69:3000`
- `http://192.168.1.69:8000/api/v1/system/health`

## Verification
Python:

```bash
uv run ruff check src tests
uv run mypy src
uv run pytest
```

Web:

```bash
npm --workspace apps/web run typecheck
npm --workspace apps/web run test -- --run
npm --workspace apps/web run build
```
