Skip to main content

​
Prerequisites

Before setting up Finance Agent locally, ensure you have the following installed:
  • Python 3.9+ - Required for the backend and agent system
  • PostgreSQL 12+ - Database with pgvector extension for embeddings
  • Node.js 16+ - For the React + TypeScript frontend
  • Git - For cloning the repository
Finance Agent uses PostgreSQL with the pgvector extension for hybrid vector + keyword search. Make sure your PostgreSQL installation supports extensions.

​
Installation Steps

1

Clone the repository

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

Set up Python environment

Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
3

Install Python dependencies

pip install -r requirements.txt
This installs all required packages including:
  • FastAPI + Uvicorn for the web server
  • PostgreSQL drivers (asyncpg, psycopg2-binary)
  • AI/ML libraries (OpenAI, Cerebras, LangChain, sentence-transformers)
  • Authentication (PyJWT for Clerk integration)
  • Redis for caching (optional)
4

Configure environment variables

Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your API keys and database credentials. See Environment Variables for details.
Never commit your .env file to version control! It contains sensitive API keys and credentials.
5

Set up the database

Initialize PostgreSQL with the pgvector extension and create required tables.See Database Setup for detailed instructions.
6

Configure application settings

Update these critical settings in your .env:
# Server configuration
BASE_URL=http://localhost:8000
PORT=8000
HOST=0.0.0.0
ENVIRONMENT=development

# Debug mode (optional)
RAG_DEBUG_MODE=true

# Auth bypass for local development (optional)
AUTH_DISABLED=true
7

(Optional) Ingest sample data

To test the RAG system, ingest sample financial data:
# Download earnings transcripts
python agent/rag/data_ingestion/download_transcripts.py

# Ingest transcripts for a specific company and date range
python agent/rag/data_ingestion/ingest_with_structure.py \
  --ticker AAPL \
  --year-start 2020 \
  --year-end 2025
Data ingestion is optional for development. The application will work without data, but RAG queries will return no results.
8

Start the development server

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
The --reload flag enables auto-reload on code changes.
9

Verify the installation

Open your browser and navigate to:
By default, API documentation is disabled in production. Enable it by setting ENABLE_DOCS=true in .env.

​
Frontend Setup (Optional)

If you’re developing the React frontend:
1

Navigate to frontend directory

cd frontend
2

Install Node dependencies

npm install
3

Configure frontend environment

The frontend reads environment variables from the root .env file via envDir: '../' in vite.config.ts.Required variables:
# Clerk authentication (same as backend)
VITE_CLERK_PUBLISHABLE_KEY=pk_test_your-clerk-publishable-key

# API base URL (optional - defaults to same-origin)
VITE_API_BASE_URL=
Leave VITE_API_BASE_URL empty for same-origin requests. Only set it if the backend is on a separate domain.
4

Start the development server

npm run dev
The frontend will run on http://localhost:5173 (Vite default port).

​
Verification

​
Test the API

Test the health endpoint: 
curl http://localhost:8000/health
Expected response: 
{
  "status": "healthy",
  "version": "5.0.0",
  "database": "connected"
}

​
Test the RAG Agent

Test the chat endpoint with a streaming query: 
curl -X POST http://localhost:8000/message/stream-v2 \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were Apple's Q1 2025 earnings?",
    "comprehensive_search": true
  }'
This requires data to be ingested first. If no data is available, you’ll receive a response indicating no results found.

​
Common Issues

​
Database Connection Failed

If you see database connection errors:
  1. Verify PostgreSQL is running: pg_isready
  2. Check your DATABASE_URL in .env
  3. Ensure the database exists: createdb stratalens
  4. Verify pgvector extension is installed (see Database Setup)

​
Import Errors

If you see Python import errors:
  1. Ensure your virtual environment is activated
  2. Reinstall dependencies: pip install -r requirements.txt
  3. Check Python version: python --version (must be 3.9+)

​
API Key Errors

If you see API key errors:
  1. Verify all required API keys are set in .env
  2. Check for typos in environment variable names
  3. Ensure .env is in the project root directory

​
Next Steps

​
Development Tips

Enable Debug Mode: Set RAG_DEBUG_MODE=true to see detailed logs including EXPLAIN ANALYZE output for database queries.
Disable Authentication: Set AUTH_DISABLED=true for local development to bypass Clerk authentication.
Use Hot Reload: The --reload flag in uvicorn automatically restarts the server when code changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us