Skip to main content

​
Quickstart guide

This guide will help you set up Finance Agent and run your first query in minutes.

​
Prerequisites

Before starting, ensure you have:
  • Python 3.9 or higher installed
  • PostgreSQL 12+ with the pgvector extension
  • Git for cloning the repository
  • API keys for OpenAI and Cerebras (see Getting API keys)
If you don’t have PostgreSQL with pgvector, see the Installation guide for detailed setup instructions.

​
Quick setup

1

Clone the repository

git clone https://github.com/kamathhrishi/stratalensai.git
cd finance_agent
2

Install dependencies

pip install -r requirements.txt
This installs all required packages including:
  • FastAPI and uvicorn for the web server
  • PostgreSQL drivers (asyncpg, psycopg2-binary)
  • AI/ML libraries (OpenAI, Cerebras, LangChain, sentence-transformers)
  • Vector search and caching (pgvector, Redis)
3

Configure environment variables

Copy the example environment file and add your API keys:
cp .env.example .env
Edit .env with your configuration:
# Required: AI model API keys
OPENAI_API_KEY=sk-your-openai-api-key-here
CEREBRAS_API_KEY=your-cerebras-api-key-here
API_NINJAS_KEY=your-api-ninjas-key-here

# Required: Database connection
DATABASE_URL=postgresql://username:password@localhost:5432/stratalens

# Optional: Real-time news
TAVILY_API_KEY=your-tavily-api-key-here

# Server configuration
BASE_URL=http://localhost:8000
ENVIRONMENT=development
AUTH_DISABLED=true  # Disable auth for local testing
Never commit your .env file to version control! It contains sensitive API keys.
4

Start the server

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
You should see output like:
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
5

Access the application

Open your browser to:
  • Frontend: http://localhost:8000
  • API docs: http://localhost:8000/docs
  • Alternative docs: http://localhost:8000/redoc

​
Your first query

Now that the server is running, let’s try asking a question!

​
Option 1: Web interface

  1. Navigate to http://localhost:8000
  2. Type a question in the chat interface: 
    What was Apple's revenue in Q4 2024?
  3. Watch the agent’s reasoning in real-time:
    • Question analysis and data source routing
    • Research planning statement
    • Retrieved transcript chunks with citations
    • Final answer with sources

​
Option 2: API endpoint

Use curl or any HTTP client: 
curl -X POST "http://localhost:8000/message/stream-v2" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What was Apple's revenue in Q4 2024?",
    "user_id": "test-user"
  }'

​
Option 3: Python client

import asyncio
from agent import create_agent

async def ask_question():
    agent = create_agent()
    
    async for event in agent.execute_rag_flow(
        question="What was Apple's revenue in Q4 2024?",
        stream=True
    ):
        if event['type'] == 'reasoning':
            print(f"Planning: {event['message']}")
        elif event['type'] == 'result':
            print(f"Answer: {event['data']['answer']}")

asyncio.run(ask_question())

​
Understanding the response

Finance Agent streams multiple event types: 
{
  "type": "analysis",
  "message": "Analyzing question...",
  "data": {
    "tickers": ["AAPL"],
    "data_source": "earnings_transcripts",
    "time_period": "Q4 2024"
  }
}

{
  "type": "reasoning",
  "message": "The user is asking about Apple's Q4 2024 revenue. I need to find total revenue figures from the earnings call transcript, including any segment breakdowns and year-over-year comparisons."
}

{
  "type": "iteration_start",
  "data": {
    "iteration": 1,
    "max_iterations": 3
  }
}

{
  "type": "result",
  "data": {
    "answer": "Apple's Q4 2024 revenue was $94.9 billion, up 6% year-over-year [T1]. iPhone revenue was $46.2 billion [T2]...",
    "citations": [
      {
        "id": "T1",
        "text": "Our September quarter revenue was $94.9 billion...",
        "source": "AAPL Q4 2024 Earnings Call"
      }
    ],
    "confidence": 0.92
  }
}

​
Example queries by type

​
Earnings transcript queries

These automatically route to earnings call transcripts: 
"What did Apple say about iPhone sales in Q4 2024?"
"Compare Microsoft and Google cloud revenue last quarter"
"Show me Tesla's guidance for 2025"
"What questions did analysts ask about NVIDIA's data center business?"

​
SEC 10-K queries

These route to the specialized 10-K retrieval agent: 
"What is Tim Cook's compensation?"
"Show me Microsoft's balance sheet"
"What are Amazon's risk factors?"
"Compare Apple and Samsung's total assets"
Executive compensation data is only available in 10-K filings, not earnings transcripts. The semantic router automatically detects this.

​
Real-time news queries

These use Tavily for current events: 
"What's the latest news on Tesla?"
"Recent developments for NVIDIA stock"
"Latest AI announcements from Microsoft"

​
Multi-source hybrid queries

"Compare Apple's official 10-K risk factors with recent news"
"Show me historical revenue trends and latest earnings commentary"

​
Configuration options

​
Choose your LLM provider

Finance Agent supports multiple LLM providers: 
# Use Cerebras (default - fast and cost-effective)
RAG_LLM_PROVIDER=cerebras

# Use OpenAI
RAG_LLM_PROVIDER=openai

# Auto-select (Cerebras if key available, else OpenAI)
RAG_LLM_PROVIDER=auto

​
Adjust answer quality vs. speed

The agent automatically selects answer modes, but you can understand the tradeoffs:
  • Direct mode: 2 iterations, 70% confidence - Quick factual lookups (~5 sec)
  • Standard mode: 3 iterations, 80% confidence - Balanced analysis (~10 sec)
  • Detailed mode: 4 iterations, 90% confidence - Comprehensive research (~15 sec)

​
Enable debug mode

RAG_DEBUG_MODE=true  # See detailed reasoning and search plans
LOG_LEVEL=DEBUG      # Verbose logging

​
Next steps

Now that you have Finance Agent running:

Installation guide

Complete setup with data ingestion and production deployment

Agent system

Understand semantic routing and iterative improvement

SEC agent

Deep dive into 10-K retrieval architecture

API reference

Explore all endpoints and integration options

​
Getting API keys

​
OpenAI API key (required)

  1. Visit platform.openai.com
  2. Sign up or log in
  3. Navigate to API keys section
  4. Create a new secret key
  5. Copy to .env as OPENAI_API_KEY
  1. Visit cerebras.ai
  2. Request API access
  3. Copy key to .env as CEREBRAS_API_KEY
Cerebras provides faster inference (Qwen-3-235B) and is the default provider. OpenAI is used as fallback.

​
API Ninjas key (required for transcripts)

  1. Visit api-ninjas.com
  2. Sign up for free tier
  3. Copy key to .env as API_NINJAS_KEY

​
Tavily API key (optional for news)

  1. Visit tavily.com
  2. Sign up for free tier
  3. Copy key to .env as TAVILY_API_KEY

​
Troubleshooting

Ensure Python 3.9+ and all dependencies are installed:
python --version  # Should be 3.9 or higher
pip install -r requirements.txt
Verify PostgreSQL is running and connection string is correct:
# Test connection
psql "postgresql://username:password@localhost:5432/stratalens"

# Ensure pgvector extension is installed
CREATE EXTENSION IF NOT EXISTS vector;
You need to ingest data first. See the Installation guide for data ingestion steps, or use the live platform at stratalens.ai.
Check that all required keys are set in .env:
# Verify keys are loaded
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('OpenAI:', bool(os.getenv('OPENAI_API_KEY')))"
If you encounter rate limits or quota errors, check your API provider dashboards for usage limits.

Build docs developers (and LLMs) love

Get started for freeTalk to us