Alphard

Alphard is an experimental, hybrid trading system that bridges the gap between opaque numerical models and human intuition. By converting market data into high-fidelity visual charts, Alphard leverages the spatial reasoning capabilities of Vision-Language Models (VLMs) to analyze market sentiment, structure, and price action "first-hand," rather than relying on lagging numerical indicators.

Developed for the WEEX AI Hackathon.

NOTE: This project is under development, and there are a lot of unused code. To be cleaned later

The Philosophy

Named after the brightest star in the Hydra constellation (the Water Snake), Alphard employs a "multi-headed" intelligence.

• Alpha: In finance, "Alpha" represents the ability to generate excess returns beyond the market benchmark. It is the signal amidst the noise.

• Hydra: The market is often likened to a untamable beast—serpentine, volatile, and multi-faceted.

The Vision: Just as the star Alphard shines clearly within the complex coils of the Hydra constellation, this project aims to isolate pure trading signal ("Alpha") from the chaotic volatility of the crypto markets. By using a Visual Reasoning Engine, we treat the market not as a stream of numbers, but as a visual landscape, allowing the AI to perceive structural patterns (breakouts, rejections, clusters) that traditional numerical models often miss.

⚡ Core Concepts

• Visual-First Reasoning: Unlike traditional bots that ingest raw arrays, Alphard generates high-DPI candlesticks charts with dynamically overlaid support/resistance levels. The AI "looks" at the chart to make decisions.

• Hybrid Architecture: Combines the creative spatial reasoning of Gemini VLMs with a Deterministic Execution Engine. The AI suggests the trade; the code enforces the risk.

• Price Action Strategy: Rejects lagging indicators (RSI, MACD) in favor of raw price action concepts: Breakouts, Rejections, and S/R Flips.

• Hallucination Control: Implements a strict protocol where the AI estimates allocation and targets, but the deterministic layer handles limit orders, pullbacks, and stop-losses.

🏗 System Architecture

The system operates on an asynchronous Python micro-architecture. The data flow is defined by three stages:

1. State Representation (Visual Synthesis):

• The Feature Engineer aggregates OHLCV data into a rolling window (48-72h).
• Uses mplfinance to render "human-view" charts, algorithmically resolving label overlaps so the VLM can read price levels without optical ambiguity.

2. Reasoning Engine (The "Brain"):

• A composite input (PNG chart + textual summary) is sent to the VLM (Gemini).
• Guided by the levels_strategy policy, the model identifies "Horizontal Level Interactions" and outputs a structured decision (BUY/SELL/HOLD).

3. Deterministic Execution (The "Guardrails"):

• Risk Protocols: Enforces 2-position limits and calculates position sizing based on AI confidence and volatility.
• Pullback Logic: Avoids market orders. Places limit orders at a calculated pullback price (e.g., 30-60% retracement) to optimize Risk/Reward.

📂 Project Structure

alphard/
├── core/               # Core loop (TBot) and Ledger management for thread safety [cite: 103]
├── data/               # Data storage and handling
├── docs/               # Project documentation and reports
├── middleware/         # Connectors and API handling
├── notebooks/          # Analysis and backtesting notebooks (e.g., test runs)
├── scripts/            # Utility scripts for maintenance or data fetching
├── templates/          # Jinja2 prompts for the AI (e.g., levels_strategy.j2) [cite: 69]
├── utilities/          # Helper modules, including image generation (imagegenv2.py) [cite: 61]
├── .env.copy           # Environment variable template
├── app.py              # Main entry point for the trading application
├── downloader.py       # Script for fetching historical OHLCV data
├── generate_dataset.py # Tool to create visual datasets for training/testing
├── requirements.txt    # Python dependencies
└── runner.py           # Execution runner for live/simulated environments

Installation and Deployment

Quick start

1. Clone the repository

git clone https://github.com/akaliutau/alphard.git
cd alphard

2. Create and activate a Conda environment

conda create -n alphard python=3.12 -y
conda activate alphard

3. Install dependencies

pip install -r requirements.txt

4. Download historical data

python downloader.py --symbol BTCUSDT --years 4
python merge_script.py -i "./spot/monthly/klines/BTCUSDT/1h" -o "./data/BTC_USDT_1h_4years.csv"

5. Install Google CLI

sudo snap install google-cloud-cli --classic
gcloud --version

6. Auth your gcloud:

gcloud auth login

7. Set env vars:

source scripts/set_env.sh

GCP Cloud deployment

Required pre-requisites: the latest version of gcloud installed.

Create a new project at GCP and modify the scripts/set_env.sh script with your value of PROJECT_ID.

gcloud --version
bq version
gcloud auth login

source scripts/set_env.sh 
source scripts/deploy_infra.sh

Note the name of secret key dev-trader-sa-key.json - it has to be used on each machine which will run python scripts.

Oracle Cloud deployment

License

Source Available / Non-Commercial Use Only

This project is licensed under the PolyForm Noncommercial License 1.0.0

✅ Allowed: You may read, run, modify, and use this code for personal research, education, or hobbyist projects.

❌ Forbidden: You may not use this code for any commercial purpose. This includes selling the software, using it to manage third-party funds for a fee, or using it as part of a paid/for-profit projects.