Financial Market Research Assistant

An agentic AI assistant for financial market research. It accepts natural language queries, searches the web for real-time data, and returns cited, LLM-generated analysis via a streaming REST API.

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• API keys for your chosen LLM and search providers

Setup

1. Clone and install dependencies

git clone <repo-url>
cd financial-market-research-assist

# With uv (recommended)
uv sync

# Or with pip
pip install -e .

2. Configure environment variables

cp .env.example .env

Edit .env and fill in your API keys:

Variable	Required	Description
OPENAI_API_KEY	If using OpenAI	OpenAI API key
GEMINI_API_KEY	If using Gemini	Google Gemini API key
TAVILY_API_KEY	Yes	Tavily web search API key
LANGCHAIN_API_KEY	Optional	LangSmith observability — omit to disable tracing silently

3. Configure the app (optional)

Edit config/settings.yaml to choose your LLM provider and model:

llm:
  llm_provider: openai        # openai or gemini
  model: gpt-4o-mini          # gpt-4o, gpt-4o-mini, gemini-3.5-flash, gemini-3.5-pro
  temperature: 0.7

search:
  search_provider: tavily     # tavily (only supported provider)
  max_results: 5              # number of search results per query
  cache_ttl: 300              # cache time-to-live in seconds
  cache_entries_to_keep: 100  # maximum cached entries

api:
  host: 0.0.0.0
  port: 8080

Running

With uv (no activation needed):

uv run python -m api.main

Or activate the virtual environment first, then run:

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

python -m api.main

The server starts at http://localhost:8080 or the one mentioned in settings.yaml

• Interactive API docs: http://localhost:8080/docs
• Health check: http://localhost:8080/api/v1/health

Usage

Send a financial research query:

curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the current outlook for NVIDIA stock?",
    "thread_id": "my-session-1"
  }'

Responses are streamed via Server-Sent Events (SSE). Use the same thread_id across requests to maintain a multi-turn conversation.

API Reference

See docs/api.md for full endpoint documentation.