Trading Research Assistant

LLM-powered trading research assistant for technical and fundamental analysis

---

Features

Technical Analysis • Fundamental Analysis • LLM-Powered Insights • Trade Journal • Automated Reports

---

About

Trading Research Assistant is a production-ready automated financial market analysis system that uses Large Language Models (LLM) to generate trading recommendations based on technical and fundamental analysis. Built with clean architecture principles and designed for extensibility.

⚠️ Demo Only: This system is for research and analysis purposes only. All recommendations require manual execution. Not financial advice.

Key Features

• 📊 Technical Analysis - Automatic indicator calculation and chart analysis via LLM
• 📰 Fundamental Analysis - News aggregation and analysis from various sources (GDELT, NewsAPI)
• 🤖 LLM Agents - Use of local or remote LLM models (Ollama) for analysis
• 💾 Trade Journal - Track trading results and statistics
• 📈 Reports - Generate trading operation statistics
• 🔄 Fallback Providers - Automatic switching between data sources (OANDA, Twelve Data)
• 🏗️ Clean Architecture - Domain-driven design with ports & adapters pattern
• 🧪 Testable - Each layer can be tested independently

---

Quick Start

Requirements

• Python 3.11 or higher
• uv (recommended) or pip
• Ollama installed and running (for LLM features)
• API keys for data providers (OANDA, Twelve Data)

Installation

Using uv (recommended)

1. Create virtual environment with Python 3.11:

   Windows (PowerShell):

   uv venv --python 3.11
   .venv\Scripts\Activate.ps1

   Linux/macOS:

   uv venv --python 3.11
   source .venv/bin/activate

2. Install dependencies:

   # Base dependencies (required)
   uv sync
   
   # With dev dependencies (testing, linting)
   uv sync --extra dev

Using pip

# Base dependencies
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

Setup

1. Create and activate virtual environment:

   Windows (PowerShell):

   uv venv --python 3.11
   .venv\Scripts\Activate.ps1

   Linux/macOS:

   uv venv --python 3.11
   source .venv/bin/activate

2. Install dependencies:

   uv sync --extra dev

3. Configure environment variables: Copy .env.example to .env and fill in your API keys:

   Windows (PowerShell):

   Copy-Item .env.example .env

   Linux/macOS:

   cp .env.example .env

   Then edit .env and replace placeholder values with your actual API keys.

4. Initialize database:

   python src/app/main.py init-db

5. Run analysis:

   python src/app/main.py analyze --symbol EURUSD --timeframe 1h

6. View latest recommendation:

   python src/app/main.py show-latest

---

Usage

Commands

• init-db - Initialize database and run migrations
• analyze --symbol SYMBOL [--timeframe TIMEFRAME] [--verbose] - Run full analysis pipeline
  • Example: analyze --symbol EURUSD --timeframe 1h
  • Supported timeframes: 1m, 5m, 15m, 1h, 1d
  • Use --verbose to show detailed analysis output during execution
• show-latest [--details] - Display the latest recommendation with color-coded action and confidence
  • Use --details to show full rationales (technical analysis, news context, synthesis)
• journal - Interactive command for logging trading decisions
• report - View trading statistics and reports

---

Dependency Groups

• Base (required): pydantic, pydantic-settings, httpx, tenacity, numpy, pandas, ta, ollama, rich
• dev (optional): pytest, ruff, mypy - for development and testing

---

Documentation

Comprehensive documentation is available in the docs/ directory:

English:

• 📖 Overview - Project overview and key features
• 🏗️ Architecture - Project structure and design patterns
• 📚 Usage Guide - Installation and usage instructions
• ⚙️ Environment Configuration - Complete description of all .env variables
• 🤖 LLM Task Routing - LLM routing by tasks and branches
• 🔧 Troubleshooting - Common issues and solutions
• 🔒 Safety Policy - Safety policy and risk management
• 📋 Import Rules - Import rules and dependency graph

Русский:

• 📖 Обзор - Обзор проекта и основные возможности
• 🏗️ Архитектура - Структура проекта и паттерны проектирования
• 📚 Руководство по использованию - Инструкции по установке и использованию
• ⚙️ Конфигурация переменных окружения - Полное описание всех переменных .env
• 🤖 LLM Task Routing - Маршрутизация LLM по задачам и веткам
• 🔧 Устранение неполадок - Распространенные проблемы и решения
• 🔒 Политика безопасности - Политика безопасности и управление рисками
• 📋 Правила импортов - Правила импортов и граф зависимостей

---

Tech Stack

Category	Technology
Language	Python 3.11+
Package Manager	uv
Data Validation	Pydantic 2.0+
HTTP Client	httpx 0.25+
Retry Logic	tenacity 8.2+
Data Processing	pandas 2.0+, numpy 1.24+
Technical Analysis	ta 0.11+
LLM Provider	Ollama (local or remote)
CLI Interface	Rich 13.0+
Database	SQLite 3
Testing	pytest 7.4+
Linting	ruff 0.1+
Type Checking	mypy 1.5+

---

Project Structure

Trading-research-assistant/
├── src/
│   ├── core/              # Domain logic (models, ports, services, policies)
│   ├── data_providers/    # Market data adapters (OANDA, Twelve Data)
│   ├── news_providers/    # News adapters (GDELT, NewsAPI)
│   ├── features/          # Technical indicators, volatility, regime detection
│   ├── agents/            # LLM agents for analysis
│   ├── llm/               # LLM providers (Ollama)
│   ├── storage/           # SQLite repositories and artifact store
│   ├── runtime/           # Orchestration and jobs
│   ├── ui/                # CLI interface (Rich)
│   ├── app/               # Entry point and settings
│   ├── broker_journal/    # Trade journal management
│   └── utils/             # Utilities (logging, retry, time)
├── tests/                 # Unit and integration tests
├── docs/                  # Documentation (en/ru)
│   ├── en/               # English documentation
│   └── ru/               # Russian documentation
├── scripts/              # Utility scripts
├── db/                   # SQLite database directory
└── pyproject.toml        # Project configuration

For detailed structure, see Architecture Documentation.

---

Architecture

The project is built on Clean Architecture principles using the Ports & Adapters pattern. The system core (core) is completely isolated from external dependencies and only knows about business logic.

Key Rule: core does not know about external integrations. External modules implement interfaces from core/ports.

Dependency Graph:

app → runtime → (features, agents, storage, providers, llm) → core

For detailed architecture documentation, see:

• Architecture (English)
• Architecture (Русский)
• Import Rules (English)
• Import Rules (Русский)

---

Supported Providers

Market Data

• OANDA — primary provider for Forex
• Twelve Data — fallback provider

News

• GDELT — global news database
• NewsAPI — news aggregator

LLM

• Multi-provider routing — Support for Ollama (local/server) and DeepSeek API
• Task-based routing — Configure different models for different tasks (tech analysis, news analysis, synthesis, verification)
• Automatic fallback — Falls back to available providers if primary fails
• Health checks — Provider availability checking with caching
• Verification stage — Optional LLM-based verification of agent outputs
• Legacy support — Backward compatible with OLLAMA_BASE_URL and OLLAMA_MODEL during transition

---

Safety Policy

The system includes a safety policy that validates recommendations before issuing them. See Safety Policy Documentation for details.

⚠️ Important: Trading Research Assistant is a research and analysis tool, not an automated trading system. The system does not guarantee recommendation profitability. All trading decisions are made by the user independently.

---

Acknowledgments

• Ollama for local LLM capabilities
• Rich for beautiful CLI interface
• Pydantic for data validation
• uv for fast Python package management
• OANDA and Twelve Data for market data APIs
• GDELT for news data

---

Made with ❤️ using Python, Clean Architecture, and LLM

📖 Documentation • 🏗️ Architecture • 📚 Usage Guide