Metadata-Version: 2.4
Name: wavedesk
Version: 0.1.2
Summary: WaveDesk — multi-agent market analysis desk: 7 indicators, Monte Carlo, risk-managed trade plans.
Author-email: Utkarsh Sharma <utkarshkviim@gmail.com>
License: MIT
License-File: LICENSE
Keywords: elliott-wave,monte-carlo,technical-analysis,trading,volatility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: fastapi>=0.110
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: yfinance>=0.2.40
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Description-Content-Type: text/markdown

# WaveDesk

Market-analysis desk for **stocks, oil, gold**, and other assets. Seven analysis
agents (Elliott Wave, EMA, Fibonacci, VWAP, ADX, Price Action/S&R, monthly RSI)
run in parallel and feed a **chief-analyst** synthesizer, on top of a forward
**volatility forecast**, a **Monte Carlo** outcome simulation, **risk-managed
position sizing**, **portfolio context**, and a walk-forward **backtest**.

The math is deterministic and reproducible; **Claude** provides the judgement
calls, anchored to the numbers the engine hands it.

**Contents** — [Requirements](#requirements) · [Quick start](#quick-start) ·
[Commands](#commands) · [How it works](#how-it-works) ·
[Web UI](#web-ui) · [Decision-support layer](#decision-support-layer) ·
[Disclaimer](#disclaimer)

---

## Requirements

| | |
| --- | --- |
| **Python** | 3.10 or newer |
| **Claude** | **Required** — a Claude Code subscription *or* an Anthropic API key |
| **Platform** | macOS · Linux · Windows |

WaveDesk runs entirely on your own machine — no server, no shared account, no
telemetry. Claude is not optional: every forecast is produced by the seven-agent
ensemble, and WaveDesk refuses to start without it rather than fall back to a
lower-quality non-AI analysis.

---

## Quick start

### 1 · Install

```bash
pipx install wavedesk
```

<details>
<summary>Other install options</summary>

```bash
pip install wavedesk                 # into the current environment
pip install "wavedesk[plot]"         # + matplotlib, for the CLI --plot chart
```

`pipx` is recommended: it installs WaveDesk into its own isolated environment
and puts the `wavedesk` command on your PATH, so its dependencies (pandas,
numpy, FastAPI, …) can't collide with your other projects.

</details>

### 2 · Connect Claude

Pick **one** — WaveDesk detects it automatically.

| Option | How | Billing |
| --- | --- | --- |
| **Claude Code subscription** | Install the [`claude` CLI](https://claude.com/claude-code) and log in | Your existing plan — no API credits |
| **Anthropic API key** | `export ANTHROPIC_API_KEY=sk-ant-...` | Pay-as-you-go credits ([console](https://console.anthropic.com)) |

A `.env` file in the directory you launch from is also read.

> If neither is present, the CLI exits with setup instructions and the web UI
> shows a **"WaveDesk needs Claude"** screen instead of the desk.

### 3 · Run

```bash
wavedesk
```

This starts the desk and opens your browser at `http://127.0.0.1:8000`.

---

## Commands

| Command | What it does |
| --- | --- |
| `wavedesk` | Start the desk and open the browser |
| `wavedesk serve --port 9000 --no-open` | Web server only, on a chosen port |
| `wavedesk analyze gold --json` | One-shot CLI forecast |
| `wavedesk backtest gold --period 5y` | Walk-forward track record |

Run any command with `--help` for its full options. `--help` works even before
Claude is set up.

---

## How it works

```
Price history ─► Structure ─► Levels ─► Seven agents ─► Verdict
```

**Noise becomes structure.** Raw candles collapse into the swing highs and lows
that actually define the move.

**Structure becomes evidence.** The wave count is tested against Elliott's three
hard rules. A count that breaks them is rejected, not rationalised.

**Evidence becomes levels.** Fibonacci projections turn the surviving structure
into a concrete target and the price that would prove it wrong.

**Levels become a verdict.** Seven specialists each read a single indicator in
their own lens; a chief analyst reconciles the disagreement into one call —
direction, target, invalidation, confidence, horizon, and the reasoning.

> The arithmetic is reproducible. The judgement is Claude's. Take the judgement
> away and WaveDesk doesn't run — see [Quick start](#quick-start).

---

## Configuration

Set these in your environment or a `.env` file next to where you run WaveDesk.

| Variable | Default | Effect |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | — | Use the Anthropic API backend |
| `WAVEDESK_LLM_BACKEND` | `auto` | Force `cli` or `api` instead of auto-detecting |
| `WAVEDESK_ANALYST_CONCURRENCY` | `6` | How many analyst calls run in parallel |

`auto` prefers the API when a key is set, otherwise the `claude` CLI
subscription. The result card's **Engine** footnote shows which one answered.

> Driving an app from the `claude` CLI counts against your Claude Code usage
> limits. Keep it to personal/light use.

---

## Web UI

A warm "commodity desk" web interface: pick an asset, choose the lens, and read
the waves. FastAPI serves both the UI and the JSON API.

```bash
wavedesk                                # → http://127.0.0.1:8000, opens your browser
wavedesk serve --port 9000 --no-open    # pick a port, don't open the browser
```

Open the URL, click **Gold** (or Oil, Bitcoin, S&P 500, …) or type any ticker,
tune the history/candle/swing controls, and hit **Read the waves**. You get a
verdict badge, target & invalidation levels, a hand-drawn chart with the ZigZag
pivots overlaid, the impulse-rule check, and the model's rationale.

## Command line

```bash
# Friendly names: gold, oil, btc, silver, sp500, nasdaq ... or any ticker
wavedesk analyze gold
wavedesk analyze oil  --period 2y --interval 1wk --plot
wavedesk analyze AAPL --threshold 0.04 --json
```

### Options

| Flag          | Default          | Description                                   |
| ------------- | ---------------- | --------------------------------------------- |
| `--period`    | `1y`             | History window (`6mo`, `1y`, `2y`, `5y`, ...) |
| `--interval`  | `1d`             | Candle size (`1d`, `1wk`, `1h`, ...)          |
| `--threshold` | `0.05`           | ZigZag swing size as a fraction (5%)          |
| `--model`     | `claude-opus-4-8`| Claude model id                               |
| `--plot`      | off              | Save a PNG chart with pivots overlaid         |
| `--json`      | off              | Emit raw analysis + forecast JSON             |

## Decision-support layer

A direction is not a decision. Three deterministic modules close that gap —
none of them consult the LLM, so every number reproduces exactly.

### Track record

> The signal is only ever shown what was knowable on the day.

Walk-forward and free of look-ahead, scored on independent windows: hit rate,
expectancy, performance against simply buying and holding, how often reality
landed inside the predicted range, and which indicators earned their place.

It grades the reproducible core, **not** Claude's judgement — a floor beneath
the tool, not a forecast of it. Costs and slippage are excluded.

### Position sizing

> The stop is the analyst's own invalidation level, so the worst case is
> bounded before the position is sized.

Conservative, moderate, and aggressive profiles each fix how much capital one
idea may risk, how large a single position may grow, and the least reward worth
accepting for that risk. Anything below the bar is flagged **skip** rather than
sized.

### Portfolio context

> A good idea in isolation can still be a bad idea in your book.

Correlation against what you already hold surfaces concentration you may not
have noticed — and shrinks the suggested position as that overlap rises.

See the [disclaimer](#disclaimer) on what these numbers are and aren't.

---

## ☕ Support

WaveDesk is free, runs entirely on your own machine, and takes no cut of
anything. If it earned you a better decision — or just saved you an afternoon —
you can say thanks:

☕ **[Buy me a coffee](https://buymeacoffee.com/codeWithUtkarsh)**

---

## Disclaimer

> ⚠️ **WaveDesk is a decision-support and research tool — not investment
> advice, and not a licensed adviser.**
>
> Markets are not predictable. Every signal, target, and probability it
> produces requires independent validation and your own risk management.
> Providing personalized advice for compensation requires registration with
> the relevant regulator (e.g. SEBI RIA/RA in India, SEC or state RIA in the
> US); WaveDesk holds no such registration and none of its output constitutes
> a recommendation.
>
> Backtest figures exclude costs and slippage, score only the deterministic
> layer, and are not a promise of future performance.

## License

MIT — see [LICENSE](LICENSE).
