dpsyAPI

# DSPy API — The Arbitrage Factory

A serverless platform for building and deploying optimized AI agents. Define your schema, generate training data, optimize with DSPy's MIPROv2, and deploy behind an API — achieving 10–30x cost reduction vs. raw GPT-4o prompting.

**Production:** https://dpsyapi-frontend.vercel.app
**API:** https://dpsyapi-backend.up.railway.app

---

## Features

- **Schema Builder** — Define input/output fields; the platform infers DSPy signatures
- **Synthetic Data Generation** — GPT-4o generates labeled training examples from your schema
- **MIPROv2 Optimization** — Finds optimal prompts for a cheaper student model (gpt-4o-mini)
- **Regatta Report** — Cost/accuracy comparison between baseline and optimized agent
- **Inference API** — Deploy optimized agents as REST endpoints with API key auth
- **Cloud Tasks Queue** — Async job execution with stuck-job recovery
- **Structured Logging** — JSON logs compatible with Google Cloud Logging

---

## Architecture

```
Frontend (Next.js + Clerk)  →  Backend (FastAPI + DSPy)  →  GCP (Cloud Run + Firestore + GCS + Cloud Tasks)
```

- **Auth:** Clerk (JWT verification) for user-facing endpoints; API key for inference
- **Database:** Firestore (projects, jobs metadata)
- **Storage:** GCS (training datasets, compiled programs)
- **Jobs:** Cloud Tasks queue with BackgroundTasks fallback for local dev

---

## Local Development

### Backend

```bash
cd backend
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Copy and edit env vars
cp .env.example .env
# Set OPENAI_API_KEY, keep MOCK_AUTH_MODE=true for local dev

# Run
uvicorn backend.main:app --reload --port 8000
```

### Frontend

```bash
cd frontend
npm install

# Copy and set Clerk publishable key
cp .env.example .env.local
# Set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

npm run dev  # Starts on http://localhost:3000
```

The frontend proxies `/api/*` to `http://localhost:8000` via Next.js rewrites.

---

## Environment Variables

See `.env.example` for the full list. Key variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes | Used for data generation and optimization |
| `GCP_PROJECT_ID` | Yes | Google Cloud project ID |
| `GCS_BUCKET_NAME` | Yes | Bucket for datasets and compiled programs |
| `ENVIRONMENT` | Yes | `development` or `production` |
| `MOCK_AUTH_MODE` | Dev only | Skip Clerk JWT verification |
| `CLERK_PEM_PUBLIC_KEY` | Prod | Clerk JWT public key for verification |
| `CLOUD_TASKS_QUEUE` | Optional | Enables Cloud Tasks (falls back to BackgroundTasks) |

---

## Testing

```bash
# Run all tests (requires python3.11 with dspy installed)
python3.11 -m pytest tests/ -v

# Backend only (faster)
python3.11 -m pytest tests/backend/ -v
```

**146/146 tests passing** as of Feb 2026.

---

## Deployment

### Backend (Cloud Run)

```bash
# Build and push
docker build -t us-central1-docker.pkg.dev/YOUR_PROJECT/dspyapi/backend:latest .
docker push us-central1-docker.pkg.dev/YOUR_PROJECT/dspyapi/backend:latest

# Deploy
gcloud run services replace service.yaml --region=us-central1

# Set secrets
gcloud run services update dspyapi-backend --region=us-central1 \
  --set-env-vars="OPENAI_API_KEY=sk-..." \
  --set-env-vars="CLERK_PEM_PUBLIC_KEY=..." \
  --set-env-vars="GCS_BUCKET_NAME=..."
```

The `service.yaml` configures 2Gi RAM, 2 vCPU, concurrency 10, with liveness/readiness probes.

### Frontend (Vercel)

1. Connect GitHub repo to Vercel
2. Set root directory: `frontend/`
3. Add environment variables:
   - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
   - `API_URL` (your Cloud Run URL)
4. Deploy

### CI/CD

GitHub Actions workflows in `.github/workflows/`:
- `test.yml` — Runs test suite on PRs
- `deploy.yml` — Builds and deploys to Cloud Run on push to `master` (requires Workload Identity Federation setup)

---

## Documentation

- [API Reference](docs/api-reference.md)
- [Quickstart](docs/quickstart.md)
- [Implementation Plan](docs/Plan.md)

---

## Cost Estimate

**Monthly (GCP, modest traffic):**
- Cloud Run: ~$30 (2Gi/2CPU)
- Firestore: ~$10
- GCS: ~$5 (with 90-day lifecycle)
- Cloud Tasks: ~$0 (first 1M ops free)

**Total: ~$45/month**