# dsh-quant-workspace

[English](README.md) | [中文](README.zh.md)

A self-contained **quant research workspace** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
It ships a Python engine inside the package — fetch Yahoo Finance daily data, backtest
rule-based strategies, and generate interactive visual reports, all from chat.

> ⚠️ **Not investment advice.** The workspace surfaces rule state and evidence; decisions are
> always yours. It never places orders and never changes positions.

## Features

- **Data** — Yahoo Finance daily bars (2 years by default), with OHLCV + indicator export.
- **Backtesting** — per-trade table, total return, max drawdown, win rate, average hold, and a
  buy-and-hold baseline.
- **Visual reports** — self-contained interactive HTML charts: candlesticks with bands and
  entry/exit markers, volume, %B, and an equity curve. Zoom (anchored at the cursor), pan,
  crosshair, and a red-up/green-down toggle — no dependencies, open in any browser.
- **Strategy registry** — save strategies you have researched and reuse them by id.
- **Read-only by design** — no orders, no position changes, no market-data keys.

## Requirements

- A DeepSeek Harness installation (`web` profile) with `pnpm`.
- `uv` (runs the bundled Python engine; first use syncs `python/.venv`).
- Internet access for Yahoo Finance data.

## Install

> **Installation status:** not yet published to npm. Until then, install from the git spec
> (`dsh plugin --profile web add github:AllenCX/dsh-quant-workspace`) or use the dev overlay below.

```sh
dsh plugin --profile web add dsh-quant-workspace
```

All configuration is optional. Example user patch (`$DSH_HOME/profiles/web/cordis.patch.yml`):

```yaml
- id: quant-workspace
  config:
    ledgerPath: 'C:\path\to\trade_log.csv'   # optional: track your real positions
    reportsDir: 'C:\path\to\reports'          # optional: where visual reports go
```

| Option | Default | Meaning |
|---|---|---|
| `ledgerPath` | *(none)* | Position ledger CSV (`date,ticker,action,price`; FIFO). Positions are only tracked from this file. |
| `reportsDir` | `$DSH_HOME/dsh-quant-workspace/reports` | Directory for visual report artifacts (HTML charts) and state exports. |
| `registryPath` | `$DSH_HOME/dsh-quant-workspace/strategies.json` | Strategy registry JSON file. |
| `defaultRule` | *(none)* | Default rule family used when a call does not specify one. |
| `timeoutMs` | `180000` | Foreground timeout per tool call. |
| `pythonCommand` | `uv run --project <package>/python dsh-quant` | Override for running the bundled engine CLI (e.g. a pre-built venv). |

### Dev / local overlay

```sh
pnpm dsh web --patch ./dev.patch.yml
```

## Quick start

In a Harness session:

- "Give me today's signal card for TSLA" — `single_ticker`, mode `daily`.
- "Backtest META and generate a chart" — `single_ticker`, mode `backtest`, `chart: true`.
- "Compare the review health check for TSLA" — `single_ticker`, mode `review`.

A call runs exactly one rule: an example `rule` family, a registered `strategy` id, or the
configured `defaultRule` when neither is given. Without any of these, the workspace reports
that no strategy is selected.

## Tools

### `single_ticker`

- `ticker` (required) — symbol, e.g. `TSLA`. Uppercased automatically; only letters, digits, dot and dash.
- `mode` (default `daily`) — `daily` signal card · `backtest` with per-trade table · `review` health check.
- `rule` — an example rule family (currently `bollinger_mean_reversion`).
- `strategy` — id of a strategy in the workspace registry.
- `chart` (default false) — also write an interactive HTML report and the state CSV under `reportsDir`;
  the artifact paths are included in the output.

## Strategy registry

After research, save a strategy and reuse it by id:

```sh
dsh-quant strategy register --id tsla_dip --family bollinger_mean_reversion --bollinger-window 30 --note 'dip strategy after Aug-2026 research'
dsh-quant strategy list
dsh-quant strategy remove --id tsla_dip
```

## Example rule

The bundled engine ships one example rule so the workspace works out of the box: Bollinger
mean-reversion on daily bars — enter when `%B <= 0`, exit when `%B >= 1` (Bollinger 20, 2σ,
same-bar close fills, no transaction costs in v1). Rule parameters are CLI options, and more
rule families (MA cross, Donchian, RSI, trend filters) are on the roadmap.

## CLI reference

```
dsh-quant single-ticker --ticker <T> --mode <daily|backtest|review> (--rule <family> | --strategy <id>) [--ledger <path>] [--chart <dir>] [--export-state <dir>] [--registry <path>] [--data-file <csv>]
dsh-quant strategy register|list|remove [options]
```

- Exit 0 with plain-text report on success; exit 1 when data cannot be loaded; exit 2 for invalid invocation.
- `--data-file` reads a local OHLCV CSV instead of the network (used by the tests).

## Development

```sh
pnpm install && pnpm run typecheck && pnpm run test && pnpm run build   # TS shell
cd python && uv run --project . pytest tests -q                          # bundled engine
```

## License

MIT