Metadata-Version: 2.4
Name: the-marketlab-project
Version: 0.1.6
Summary: Python tool to download data of financial market such as price, candales, volume from BINANCE and computing indicators. Long terme project is to build a neural network to spot patterns over a large amount of data and build a AI trading agent with tensortrade.
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 and run locally

Clone the project and create a virtual environment from the repository root:

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

Then start Market Lab with the launcher script:

```bash
python run_marketlab.py
```

This launcher calls the project entry point and opens the application in the same way as the packaged version.

If you prefer to use the project directly without the launcher, you can also run:

```bash
python desktop.py
```

However, `run_marketlab.py` is the recommended start command for a straightforward local launch.

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 |
| --- | --- |
| `run_marketlab.py` | Recommended local launcher for opening the app. |
| `desktop.py` | Interactive terminal user interface and main application 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
```
