Quickstart

Prerequisites

• Python 3.12+
• Docker & Docker Compose (for Postgres 16 + Redis 7)
• An OpenAI admin API key (starts with sk-admin-) or Anthropic admin key for integration testing
• AWS credentials with Secrets Manager access (or LocalStack for local dev)
• Stripe test-mode API keys
• Clerk development instance with JWKS endpoint

Local Development Setup

# Clone and enter
cd ai-workloads-api

# Start infrastructure
docker compose up -d postgres redis

# Install dependencies
uv sync

# Copy environment config
cp env.example .env
# Edit .env with your credentials

# Run migrations
uv run alembic upgrade head

# Seed carbon factors
uv run python -m app.scripts.seed_factors

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

# Start ARQ worker (separate terminal)
uv run arq app.jobs.worker.WorkerSettings

Smoke Tests

Test 1: Health Check

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "checks": {
    "database": { "status": "ok", "latency_ms": 2 },
    "redis": { "status": "ok", "latency_ms": 1 },
    "last_poll": {
      "status": "ok",
      "last_poll_at": null,
      "minutes_ago": null
    }
  },
  "version": "1.0.0"
}

---

Test 2: Connect Provider

Verifies US1 acceptance scenario 1.

curl -X POST http://localhost:8000/api/v1/connections \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "api_key": "sk-admin-..."}'

Expected: 201 Created with connection ID, status "active", secrets_manager_arn populated, api_key not in response.

---

Test 3: Trigger Manual Sync

Verifies US1 acceptance scenario 2.

curl -X POST http://localhost:8000/api/v1/connections/{id}/sync \
  -H "Authorization: Bearer $CLERK_JWT"

Expected: 202 Accepted. After the worker processes the job, telemetry events appear.

---

Test 4: View Dashboard Data

Verifies US1 acceptance scenario 3.

curl http://localhost:8000/api/v1/telemetry/summary \
  -H "Authorization: Bearer $CLERK_JWT"

Expected: JSON with total_co2_kg, per_model breakdown, daily_chart data points, cached_vs_uncached split.

---

Test 5: Upgrade to Paid

Verifies US2 acceptance scenario 1.

curl -X POST http://localhost:8000/api/v1/billing/upgrade \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{"plan": "starter"}'

Expected: 200 OK with Stripe checkout session URL. After completing Stripe test checkout, org plan_tier updates to "starter".

---

Test 6: Verify Receipt

Verifies US2 acceptance scenario 3.

# After a billing period closes (use test helper to fast-forward)
curl http://localhost:8000/public/receipts/verify/CL-202603-00001

Expected: JSON with receipt metadata, signature, public_key. Signature verifies against payload_hash using any Ed25519 library.

---

Test 7: Create Project

Verifies US3 acceptance scenario 1.

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production App"}'

Expected: 201 Created with project ID. Then map a connection:

curl -X PUT http://localhost:8000/api/v1/connections/{id}/project \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "{project_id}"}'

Expected: 200 OK. Future telemetry routes to the new project. Historical events stay in the Default project.

Automated Test Suite

# Unit tests (fast, no external deps)
uv run pytest tests/unit/ -v

# Integration tests (requires docker compose services)
uv run pytest tests/integration/ -v

# Contract tests (validates API response shapes)
uv run pytest tests/contract/ -v

# All tests with coverage
uv run pytest --cov=app --cov-report=term-missing

Key Verification Points

User Story	What to verify	How
US1	Provider key validated and encrypted	Check Secrets Manager for secret; verify DB has ARN not key
US1	Telemetry deduplication	Poll twice; verify no duplicate events (same idempotency_hash)
US1	Emissions calculated	Check CarbonCalculation table has entries with co2_kg > 0
US2	Receipt signature valid	Use PyNaCl to verify signature against payload_hash and public_key
US2	PDF downloads	GET receipt PDF URL; verify PDF opens and contains correct data
US2	Prior period adjustment	Insert late event after period close; verify PriorPeriodAdjustment entry
US3	Project isolation	Query telemetry by project; verify no cross-project leakage
US4	Audit pack contents	Download zip; verify manifest matches contained files