Skip to main content

Getting Started with Sable

This guide will help you set up your development environment and understand the Sable codebase.

Prerequisites​

  • Python 3.11+
  • Node.js 20+
  • PostgreSQL client (psql)
  • Access to Supabase project

Repository Structure​

sable-data/
├── dbt/                    # dbt project
│   ├── models/
│   │   ├── bronze/        # Raw data models
│   │   ├── silver/        # Typed/cleaned models
│   │   └── gold/          # Enriched analytics models
│   ├── macros/            # Reusable SQL macros
│   └── tests/             # Data quality tests
├── app/                    # FastAPI backend
│   ├── routes/            # API endpoints
│   ├── pipelines/         # ETL pipelines
│   └── worker.py          # Background job processor
└── web/                    # Next.js frontend

Local Development​

1. Clone and Install​

git clone git@github.com:aic-holdings/sable-data.git
cd sable-data

# Backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Frontend
cd web
npm install

2. Environment Setup​

Create .env file:

# Database
SUPABASE_DB_PASSWORD=<from infisical>
DATABASE_URL=postgresql://postgres:${SUPABASE_DB_PASSWORD}@db.xxx.supabase.co:5432/postgres

# API
SABLE_API_KEY=<your user API key>

3. Run dbt​

cd dbt
source ../.venv/bin/activate

# Test connection
dbt debug

# Run all models
dbt run

# Run specific model
dbt run --select gold.pnl_daily_dbt

# Run tests
dbt test

4. Run API Server​

cd app
uvicorn main:app --reload --port 8000

5. Run Frontend​

cd web
npm run dev

Key Concepts​

Medallion Architecture​

LayerSchemaPurpose
Bronzebronze.*Raw data exactly as uploaded
Silversilver_intermediate.*Typed, deduplicated, validated
Goldgold.*Enriched, joined, analytics-ready

Entity Hierarchy​

Organization (org_id)
└── Entity (fund/account)
    └── Position (security holding)
        └── Daily P&L records

API Authentication​

All API calls require the x-api-key header:

curl -H "x-api-key: sk_xxx" https://sable-data.jettaintelligence.com/api/health

Common Tasks​

Upload a File​

  1. Go to Sable dashboard → Admin → File Bucket
  2. Upload CSV file
  3. Watch for detection and processing status

Query Returns​

curl "https://sable-data.jettaintelligence.com/api/returns/comparison?limit=10" \
  -H "x-api-key: $SABLE_API_KEY"

Run Observability Tests​

cd dbt
dbt test --select tag:observability

Next Steps​