diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..3daa8175 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,208 @@ +# Gemini Code Assistant Workspace Configuration + +This document provides a comprehensive guide for the Gemini Code Assistant to effectively understand and contribute to the `TradingAgents` project. + +## Project Overview + +`TradingAgents` is a multi-agent LLM framework for financial trading that simulates a real-world trading firm. It leverages a team of specialized LLM-powered agents, including analysts, researchers, and a trader, to collaboratively analyze market conditions and make informed trading decisions. The framework is built on `LangGraph`, which enables a modular and flexible agent-based architecture. + +The core of the project is the `TradingAgentsGraph`, which orchestrates the interactions between the different agents. The agents are organized into teams: + +* **Analyst Team:** Gathers and analyzes different types of data (e.g., fundamentals, news, social media). +* **Researcher Team:** Debates the findings of the analyst team to form an investment plan. +* **Trader Agent:** Makes the final trading decision based on the input from the other teams. +* **Risk Management Team:** Assesses the risk of the proposed trade. + +## Getting Started + +### Installation + +1. Clone the repository: + ```bash + git clone https://github.com/TauricResearch/TradingAgents.git + cd TradingAgents + ``` +2. Create and activate a virtual environment: + ```bash + conda create -n tradingagents python=3.13 + conda activate tradingagents + ``` +3. Install the required dependencies: + ```bash + pip install -r requirements.txt + ``` + +### API Keys + +The project requires the following API keys to be set as environment variables: + +* **FinnHub:** For financial data. + ```bash + export FINNHUB_API_KEY=$YOUR_FINNHUB_API_KEY + ``` +* **OpenAI:** For the LLM agents. + ```bash + export OPENAI_API_KEY=$YOUR_OPENAI_API_KEY + ``` +* **OpenRouter (optional):** If you want to use OpenRouter as your LLM provider. + ```bash + export OPENROUTER_API_KEY=$YOUR_OPENROUTER_API_KEY + ``` + +## Project Structure + +``` +C:\Users\kevin\repo\TradingAgents\ +├───.gitignore +├───.python-version +├───ERROR_HANDLING_GUIDE.md +├───LICENSE +├───main.py +├───openrouter_status.py +├───pyproject.toml +├───README.md +├───requirements.txt +├───setup.py +├───uv.lock +├───.git\... +├───.venv\ +│ ├───include\... +│ ├───Lib\... +│ ├───Scripts\... +│ └───share\... +├───assets\ +│ ├───analyst.png +│ ├───researcher.png +│ ├───risk.png +│ ├───schema.png +│ ├───TauricResearch.png +│ ├───trader.png +│ ├───wechat.png +│ └───cli\ +│ ├───cli_init.png +│ ├───cli_news.png +│ ├───cli_technical.png +│ └───cli_transaction.png +├───cli\ +│ ├───__init__.py +│ ├───main.py +│ ├───models.py +│ ├───utils.py +│ ├───__pycache__\ +│ └───static\ +│ └───welcome.txt +├───results\ +│ ├───AAPL\... +│ └───TSLA\... +└───tradingagents\ + ├───default_config.py + ├───__pycache__\ + ├───agents\ + │ ├───__init__.py + │ ├───__pycache__\ + │ ├───analysts\ + │ │ ├───fundamentals_analyst.py + │ │ ├───market_analyst.py + │ │ ├───news_analyst.py + │ │ ├───social_media_analyst.py + │ │ └───__pycache__\ + │ ├───managers\ + │ │ ├───research_manager.py + │ │ ├───risk_manager.py + │ │ └───__pycache__\ + │ ├───researchers\ + │ │ ├───bear_researcher.py + │ │ ├───bull_researcher.py + │ │ └───__pycache__\ + │ ├───risk_mgmt\ + │ │ ├───aggresive_debator.py + │ │ ├───conservative_debator.py + │ │ ├───neutral_debator.py + │ │ └───__pycache__\ + │ ├───trader\ + │ │ ├───trader.py + │ │ └───__pycache__\ + │ └───utils\ + │ ├───agent_states.py + │ ├───agent_utils.py + │ ├───memory.py + │ └───__pycache__\ + ├───dataflows\ + │ ├───__init__.py + │ ├───config.py + │ ├───finnhub_utils.py + │ ├───googlenews_utils.py + │ ├───interface.py + │ ├───reddit_utils.py + │ ├───stockstats_utils.py + │ ├───utils.py + │ ├───yfin_utils.py + │ ├───__pycache__\ + │ └───data_cache\ + └───graph\ + ├───__init__.py + ├───conditional_logic.py + ├───propagation.py + ├───reflection.py + ├───setup.py + ├───signal_processing.py + ├───trading_graph.py + └───__pycache__\ +``` + +* **`main.py`**: A simple script demonstrating how to use the `TradingAgentsGraph` as a Python package. +* **`cli/main.py`**: The main entry point for the command-line interface. +* **`tradingagents/`**: The core Python package. + * **`agents/`**: Contains the implementation of the different agents. + * **`dataflows/`**: Handles data acquisition from various APIs. + * **`graph/`**: Defines the `LangGraph` graph and the overall orchestration of the agents. + * **`default_config.py`**: The default configuration for the project. +* **`requirements.txt`**: A list of the Python dependencies. +* **`pyproject.toml`**: Project metadata and dependencies. +* **`README.md`**: The main README file for the project. + +## Core Concepts + +### TradingAgentsGraph + +The `TradingAgentsGraph` class in `tradingagents/graph/trading_graph.py` is the central orchestrator of the framework. It initializes the LLMs, tools, and agents, and then constructs a `LangGraph` graph to define the workflow. The `propagate` method executes the graph for a given company and date. + +### Agents + +Agents are defined in the `tradingagents/agents/` directory. Each agent is a "node" in the `LangGraph` graph. The agents are created by functions that take the LLM and other necessary components as input. These functions return a node function that processes the current state of the graph and returns an updated state. + +### Dataflows + +The `tradingagents/dataflows/` directory contains the logic for fetching data from various financial data APIs, such as Finnhub, Yahoo Finance, and Reddit. The `Toolkit` class in `tradingagents/agents/__init__.py` provides a unified interface for the agents to access these data sources. + +## Development Guidelines + +### Adding a New Agent + +1. Create a new Python file in the appropriate subdirectory of `tradingagents/agents/`. +2. Define a `create__agent` function that takes the LLM and any other necessary components as input. +3. Inside this function, define a node function that takes the current state of the graph as input. +4. Prepare a prompt for the LLM and invoke it. +5. Return an updated state dictionary. +6. Add the new agent to the `TradingAgentsGraph` in `tradingagents/graph/trading_graph.py`. + +### Adding a New Tool + +1. Add a new function to the appropriate file in `tradingagents/dataflows/`. +2. Add the new function to the `Toolkit` class in `tradingagents/agents/__init__.py`. +3. Add the new tool to the appropriate `ToolNode` in the `_create_tool_nodes` method of the `TradingAgentsGraph` class. + +### Running Tests + +This project does not currently have a dedicated test suite. When adding new features, it is recommended to add unit tests to ensure the correctness of the code. + +## Key Commands + +* **Run the CLI:** + ```bash + python -m cli.main + ``` +* **Run the package example:** + ```bash + python main.py + ```