Metadata-Version: 2.4
Name: the-marketlab-project
Version: 0.1.3
Summary: Add your description here
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy<3,>=1.26.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy<2,>=1.11.0
Requires-Dist: websocket-client>=1.8.0

# Market Lab

Market Lab is an interactive Python application for exploring Binance spot-candle data. It stores downloaded OHLCV data in SQLite, calculates technical indicators, marks events, plots series, and produces simple quantile-based statistics. It is intended for research and experimentation; it does not place orders or provide trading advice.

## What it does

- Creates a SQLite database for a Binance `USDT` market and timeframe.
- Downloads historical candles from Binance's public REST API and updates an existing database.
- Calculates built-in or user-defined indicators and stores them as columns in `candles`.
- Calculates events and stores their status values as columns in `status`.
- Plots one or more series, with positive and negative event markers when selected.
- Produces one- and two-variable quantile statistics.

The built-in indicator catalogue includes moving averages, VWEMA, correlation, ATR, relative changes, returns, RSI, Bollinger bands, Savitzky-Golay filtering, and other formulas. The event catalogue includes crossings, extrema, over/under comparisons, and peak detection.

## Requirements

- Python 3.11 or newer
- Internet access to Binance for downloads and updates
- A desktop environment capable of displaying Matplotlib windows

Runtime dependencies are declared in `pyproject.toml`: `matplotlib`, `numpy`, `questionary`, `requests`, `rich`, `scipy`, and `websocket-client`.

## Install

From the repository root, either use `uv`:

```bash
uv sync
```

or create a virtual environment and install the dependencies with pip:

```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install matplotlib numpy questionary requests rich scipy websocket-client
```

## Run Market Lab

Start the interactive application from the repository root:

```bash
python desktop.py
```

The console entry point in the current package configuration is only a placeholder, so use `python desktop.py` for the full application.

At launch, choose **Create a database** or **Open a database**. When creating one, enter a base symbol such as `BTC` (Market Lab appends `USDT`) and choose a supported Binance timeframe. Then use the main menu:

1. **Download Data** — retrieve all available history or a selected date range.
2. **Calculate Indicators** — choose a formula, its input columns, arguments, and window.
3. **Calculate Events** — choose a rule and the columns it should inspect.
4. **Plot** or **Calculate Statistics** — explore saved data.
5. **Update Data** — download newer candles and attempt to extend saved calculations.

Download data before calculating an indicator or event. A window must contain no more candles than are available.

## Data model

Each database has these main tables:

| Table | Purpose |
| --- | --- |
| `candles` | Binance OHLCV fields plus calculated indicator columns, keyed by `open_time`. |
| `status` | Event-status columns, keyed by `open_time`. Positive and negative values are used by plots and statistics. |
| `indicators_metadata` | Formula name, parameters, window, arguments, and a calculation hash for each indicator. |
| `events_metadata` | Equivalent metadata for each event. |
| `database_metadata` | Symbol, timeframe, and registered custom-module information. |

The downloaded candle fields are `open_time`, `open`, `high`, `low`, `close`, `volume`, `close_time`, `quote_asset_vol`, `number_of_trades`, `taker_buy_base_asset_volume`, and `taker_buy_quote_asset_volume`.

Indicator output begins at the final candle of its first window; earlier rows are left empty. Calculating a column with the same name can replace the existing column, so use clear, unique names when preserving experiments matters.

## Custom indicators and events

Market Lab can import Python modules that define `indicator_dict` and/or `event_dict`. Custom Python is executed during import, so only load code you have reviewed and trust.

Use **Settings → Manage Custom Indicators and Events → Create custom_indicators.py** to generate a starter module, edit it, then use **Register custom module** to validate, register, and load it. The complete, code-aligned extension contract and working examples are in [How to create your own indicators and events](how_to_create_your_own_indicators_and_events.md).

## Project layout

| File | Role |
| --- | --- |
| `desktop.py` | Interactive terminal user interface and main entry point. |
| `commands.py` | Menu workflows for download, calculations, plotting, statistics, and custom-module management. |
| `database.py` | SQLite schema, metadata, and data-access helpers. |
| `data_extraction_service.py` | Binance candle downloader. |
| `math_formula.py` | Built-in indicator functions and their registry. |
| `event.py` | Built-in event functions and their registry. |
| `indicators_service.py` / `events_service.py` | Rolling-window calculation engines. |
| `custom_indicators.py` | Example custom module. |

## Notes and limitations

- Market data comes from Binance's public API. Availability, symbols, and historical coverage are controlled by Binance.
- The application is interactive rather than a stable programmatic API.
- SQLite files and generated custom modules are created next to the project files. Back up databases before replacing columns or registering untrusted changes.
- This project is for analysis, not a recommendation to buy or sell any asset.

## Verification

The repository includes a lightweight custom-module smoke test:

```bash
python test_smoke.py
```
