# AI Financial Research Agent

An autonomous stock research agent built with **LangGraph**, **LangChain**, and the **ReAct** pattern. It researches any ticker — fundamentals, news sentiment, technical indicators, and analyst consensus — then produces a structured buy/sell investment brief.

Includes a **Streamlit** web UI, **MCP server** for tool exposure, and **session tracking** for the full ReAct loop.

Based on [Building a Financial Research Agent with ReAct, LangGraph, and LangChain](https://pub.towardsai.net/building-a-financial-research-agent-with-react-langgraph-and-langchain-c5d5142d8b29).

## Features

- **ReAct Agent Loop** — Agent decides tool order dynamically (Reason → Act → Observe)
- **4 Research Tools** — Fundamentals, news sentiment, technicals, analyst ratings
- **Streamlit UI** — Live ReAct step tracking + investment brief display
- **Session Tracking** — Persisted JSON logs of every research session
- **MCP Server** — Expose tools to Cursor, Claude Desktop, or any MCP client
- **Ticker Normalization** — Handles mixed case input (`reliance.ns` → `RELIANCE.NS`)

## Project Structure

```
financial-research-agent/
├── app/
│   └── streamlit_app.py      # Streamlit web interface
├── financial_mcp/
│   ├── server.py             # MCP server (stdio transport)
│   └── config.json           # Sample MCP client config
├── src/financial_agent/
│   ├── state.py              # LangGraph agent state
│   ├── tools.py              # Research tools (yfinance, Tavily, pandas-ta)
│   ├── agent.py              # LLM + system prompt
│   ├── graph.py              # LangGraph ReAct graph
│   ├── runner.py             # Streaming runner with tracking
│   ├── utils.py              # Ticker normalization
│   └── tracking/
│       └── session_tracker.py  # ReAct step & session persistence
├── data/sessions/            # Tracked research sessions (JSON)
├── main.py                   # CLI entry point
├── requirements.txt
├── .env.example
└── README.md
```

## Setup

### 1. Clone and install

```bash
cd financial-research-agent
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt
```

### 2. Configure API keys

Copy `.env.example` to `.env` and add your keys:

```env
OPENAI_API_KEY=your_openai_key
TAVILY_API_KEY=your_tavily_key
OPENAI_MODEL=gpt-4o
```

Get a free Tavily key at [tavily.com](https://tavily.com).

### 3. Run

**Streamlit UI (recommended):**

```bash
streamlit run app/streamlit_app.py
```

**CLI:**

```bash
python main.py RELIANCE.NS
python main.py AAPL
```

**MCP Server:**

```bash
python -m financial_mcp.server
```

Add to your MCP client config (see `financial_mcp/config.json`):

```json
{
  "mcpServers": {
    "financial-research-agent": {
      "command": "python",
      "args": ["-m", "financial_mcp.server"],
      "cwd": "/path/to/financial-research-agent",
      "env": { "PYTHONPATH": "/path/to/financial-research-agent/src" }
    }
  }
}
```

## Architecture

```
User: "Research RELIANCE.NS"
        │
        ▼
  ┌─────────────┐     tool_call      ┌─────────────┐
  │  Agent Node │ ─────────────────► │  Tools Node │
  │   (LLM)     │ ◄───────────────── │  (ToolNode) │
  └─────────────┘    observation     └─────────────┘
        │
        ▼ (no more tool calls)
  Final Investment Brief
```

## Session Tracking

Every research run is tracked step-by-step:

| Step Type     | Description                    |
|---------------|--------------------------------|
| `tool_call`   | Agent decides to call a tool   |
| `tool_result` | Tool observation returned      |
| `final_brief` | Structured investment brief    |

Sessions are saved to `data/sessions/{session_id}_{ticker}.json`.

## Supported Tickers

| Market | Format       | Example        |
|--------|--------------|----------------|
| US     | `SYMBOL`     | `AAPL`, `MSFT` |
| NSE    | `SYMBOL.NS`  | `RELIANCE.NS`  |
| BSE    | `SYMBOL.BO`  | `RELIANCE.BO`  |

## License

MIT