Skip to content

Getting Started

This tutorial will guide you through setting up the 2Sigma Backend from scratch and making your first API request.

What You'll Learn

By the end of this tutorial, you will:

  1. Set up a local PostgreSQL database
  2. Install and configure the backend
  3. Run database migrations
  4. Start the development server
  5. Create a user and authenticate
  6. Make your first API request

Prerequisites

Before starting, ensure you have:

  • Python 3.11 or 3.12 installed
  • PostgreSQL 14+ installed and running
  • Git installed
  • A text editor or IDE
  • Basic understanding of REST APIs

Estimated Time

This tutorial takes approximately 30 minutes to complete.

Step 1: Clone the Repository

git clone <your-repo-url>
cd ai-tutor-backend

Step 2: Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

python -m venv venv
venv\Scripts\activate

You should see (venv) in your terminal prompt.

Step 3: Install Dependencies

pip install -r requirements.txt

This installs FastAPI, SQLAlchemy, Alembic, and all other dependencies.

Step 4: Set Up PostgreSQL Database

Create the Database

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE ai_tutor_dev;
CREATE USER ai_tutor_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE ai_tutor_dev TO ai_tutor_user;
\q

Configure Environment Variables

Create a .env file in the ai-tutor-backend directory:

# Application
APP_NAME="2Sigma Backend"
DEBUG=true
ENVIRONMENT=development

# Database
DATABASE_URL=postgresql+asyncpg://ai_tutor_user:your_password@localhost:5432/ai_tutor_dev

# Security
SECRET_KEY=your-super-secret-key-change-this-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=10080
REFRESH_TOKEN_EXPIRE_DAYS=30

# CORS
BACKEND_CORS_ORIGINS=["http://localhost:3000", "http://localhost:8000"]

# LLM Configuration
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

Security

  • Generate a strong SECRET_KEY for production (use openssl rand -hex 32)
  • Never commit .env files to version control
  • The example tokens expire in 7 days (10080 minutes) for development convenience

Step 5: Run Database Migrations

Apply all database migrations to create the schema:

alembic upgrade head

You should see output indicating migrations are being applied:

INFO  [alembic.runtime.migration] Running upgrade  -> abc123, initial
INFO  [alembic.runtime.migration] Running upgrade abc123 -> def456, add chat system
...

Step 6: Start the Development Server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Server Running

Your API is now running at http://localhost:8000

Step 7: Explore the API Documentation

Open your browser and navigate to:

These provide interactive API documentation generated from your code.

Step 8: Register a User

Let's create your first user using the API.

Using curl

curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123",
    "full_name": "John Doe"
  }'

Using the Swagger UI

  1. Go to http://localhost:8000/docs
  2. Expand POST /api/v1/auth/register
  3. Click "Try it out"
  4. Enter the request body:
{
  "email": "user@example.com",
  "password": "SecurePassword123",
  "full_name": "John Doe"
}
  1. Click "Execute"

Expected Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Save Your Tokens

Copy the access_token - you'll need it for authenticated requests.

Step 9: Make an Authenticated Request

Now let's fetch your user profile using the access token.

Using curl

curl -X GET "http://localhost:8000/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with the token from Step 8.

Using Swagger UI

  1. At the top of the Swagger UI, click the Authorize button
  2. Enter: Bearer YOUR_ACCESS_TOKEN
  3. Click "Authorize" then "Close"
  4. Expand GET /api/v1/users/me
  5. Click "Try it out" then "Execute"

Expected Response

{
  "id": 1,
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "locale": "en",
  "time_zone": "UTC",
  "created_at": "2026-01-20T10:30:00Z",
  "current_streak_days": 0
}

Step 10: Create Sample Data (Optional)

To explore the full system, you may want to create universities, courses, and content. Here's a quick example:

Create a University

curl -X POST "http://localhost:8000/api/v1/universities/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example University",
    "short_code": "EXUNI",
    "country_id": 1,
    "time_zone": "America/New_York"
  }'

Country IDs

You'll need to populate the Country table first, or adjust the schema to make it optional during development.

Troubleshooting

Database Connection Errors

If you see connection refused errors:

  • Verify PostgreSQL is running: pg_isready
  • Check your DATABASE_URL in .env
  • Ensure the database exists: psql -l

Migration Errors

If migrations fail:

  • Check database permissions
  • Verify the database is empty (or use alembic downgrade base to reset)
  • Review error messages for specific issues

Import Errors

If you get ModuleNotFoundError:

  • Ensure your virtual environment is activated
  • Reinstall dependencies: pip install -r requirements.txt

Next Steps

Congratulations! You now have a working 2Sigma Backend.

Here's what to explore next:

Common Workflows

Daily Development

# Activate environment
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Start server
uvicorn app.main:app --reload --port 8000

After Pulling Changes

# Update dependencies
pip install -r requirements.txt

# Run new migrations
alembic upgrade head

Running Tests

pytest -v

Need help? Check the How-To Guides or review the Architecture docs.