Skip to content

getting-started.md

Latest commit

 

History

History
279 lines (199 loc) · 4.94 KB

getting-started.md

File metadata and controls

279 lines (199 loc) · 4.94 KB

Getting Started with FARP

This guide will help you set up and run FARP (Financial Analytics & Risk Pipeline) on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement Version Purpose
Python 3.11+ Core runtime
Docker Latest PostgreSQL container
Docker Compose Latest Container orchestration
Git Latest Version control

Installation

1. Clone the Repository

git clone <repository-url>
cd farp

2. Create Virtual Environment

Windows:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment

Copy the example environment file and customize as needed:

Windows:

copy .env.example .env

Linux/macOS:

cp .env.example .env

Edit .env to configure:

  • Database credentials
  • API settings
  • Risk parameters

See Configuration Reference for all options.

Database Setup

1. Start PostgreSQL

Using Docker Compose:

docker-compose up -d

This starts:

  • PostgreSQL 15 on port 5432
  • pgAdmin on port 5050 (optional, use --profile tools)

2. Verify Database Connection

docker-compose ps

Ensure the farp_postgres container is running and healthy.

3. Initialize Database Schema

python scripts/init_db.py

This creates all required tables in the database.

4. Seed Demo Data (Optional)

To populate the database with sample data for testing:

python scripts/seed_data.py

This creates:

  • 13 demo instruments (equities, crypto, FX)
  • 30 days of price history
  • 30 days of FX rates
  • ~100 sample trades

Running FARP

Start the API Server

uvicorn src.api.main:app --reload --port 8000

The API will be available at:

Start the Dashboard

In a separate terminal:

streamlit run dashboard/app.py --server.port 8501

The dashboard will be available at: http://localhost:8501

Start the Scheduler (Optional)

For automated background jobs:

python -m src.scheduler.runner

This enables:

  • Price updates every 5 minutes
  • FX rate updates every 15 minutes
  • Position snapshots every 30 minutes
  • End-of-day processing at market close

Verify Installation

1. Check API Health

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "timestamp": "2024-01-15T12:00:00Z"
}

2. Check API Root

curl http://localhost:8000/

Expected response:

{
  "name": "FARP - Financial Analytics & Risk Pipeline",
  "version": "0.1.0",
  "docs": "/docs",
  "health": "/health"
}

3. Submit a Test Trade

curl -X POST http://localhost:8000/api/v1/trades \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "TEST001",
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": 100,
    "price": 185.50,
    "currency": "USD"
  }'

Quick Start Example

Here's a complete Python example to get you started:

import requests

API_BASE = "http://localhost:8000/api/v1"

# 1. Submit a trade
trade = {
    "external_id": "TRADE001",
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": 100,
    "price": 185.50,
    "currency": "USD"
}
response = requests.post(f"{API_BASE}/trades", json=trade)
print("Trade submitted:", response.json())

# 2. Get positions
positions = requests.get(f"{API_BASE}/positions")
print("Current positions:", positions.json())

# 3. Get portfolio summary
summary = requests.get(f"{API_BASE}/positions/summary")
print("Portfolio summary:", summary.json())

# 4. Get PnL
pnl = requests.get(f"{API_BASE}/positions/pnl/summary")
print("PnL summary:", pnl.json())

# 5. Get risk metrics
risk = requests.get(f"{API_BASE}/risk/metrics")
print("Risk metrics:", risk.json())

Troubleshooting

Database Connection Failed

  1. Ensure Docker is running
  2. Check if PostgreSQL container is healthy: docker-compose ps
  3. Verify .env database settings match docker-compose.yml

Port Already in Use

Change the port in your command:

uvicorn src.api.main:app --reload --port 8001
streamlit run dashboard/app.py --server.port 8502

Import Errors

Ensure you're in the project root and virtual environment is activated:

cd farp
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/macOS

Next Steps