Files · OpenAI Cost Control for ServiceTitan Small Business Agent Spend

# OpenAI Cost Control for ServiceTitan Small Business Agent Spend
 
Cap and monitor OpenAI tokens per ServiceTitan tenant so field-service AI automation never blows the monthly budget.
 
## Overview
 
SMBs deploying AI-driven scheduling and dispatch agents on ServiceTitan risk runaway costs if one tenant floods the system with requests. This cost-control layer enforces per-tenant token budgets, auto-downgrades to cheaper models near caps, trips circuit breakers on repeated failures, and streams observability data to Helicone.
 
## Architecture
 
```
ServiceTitan API ──► ServiceTitan Client ──► Budget Enforcement ──► OpenAI API
      │                                              │                    │
      │                                              ▼                    │
      │                                        Cost Telemetry              │
      │                                     (Postgres + Aggregator)        │
      │                                              │                    │
      └──── Hono API ◄──── Router / Circuit Breaker ◄─────────────────────┘
                                                │
                                          Helicone Proxy
```
 
## Prerequisites
 
- Node.js 22+
- pnpm 10+
- A ServiceTitan developer account with OAuth2 credentials
- An OpenAI API key
- A Postgres database (for cost span storage)
- A Helicone account (for observability, optional)
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Edit .env with your credentials
pnpm dev
```
 
## API Reference
 
| Method | Path | Description |
|--------|------|-------------|
| GET | /api/health | Liveness check |
| GET | /api/cost/budget/:tenantId | Get budget state for a tenant |
| POST | /api/cost/check | Pre-flight budget check |
| POST | /api/cost/record | Record spend after a call |
| GET | /api/cost/summary/:tenantId | Aggregated cost summary |
| POST | /api/chat | End-to-end chat with budget enforcement |
 
## Environment variables
 
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `OPENAI_API_KEY` | OpenAI API key | Yes | — |
| `DATABASE_URL` | Postgres connection string | Yes | — |
| `SERVICETITAN_CLIENT_ID` | ServiceTitan OAuth2 client ID | Yes | — |
| `SERVICETITAN_CLIENT_SECRET` | ServiceTitan OAuth2 client secret | Yes | — |
| `SERVICETITAN_TENANT_ID` | ServiceTitan tenant identifier | Yes | — |
| `SERVICETITAN_BASE_URL` | ServiceTitan API base URL | No | `https://api.servicetitan.com` |
| `HELICONE_API_KEY` | Helicone observability API key | No | — |
| `DEFAULT_DAILY_BUDGET` | Default daily budget per tenant in USD | No | `100` |
| `DEFAULT_MONTHLY_BUDGET` | Default monthly budget per tenant in USD | No | `2000` |
| `BUDGET_SOFT_CAP` | Utilization fraction triggering auto-downgrade (0–1) | No | `0.8` |
| `CHEAPER_MODEL` | Fallback model ID when budget tightens | No | `gpt-4o-mini` |
 
## Testing
 
```bash
pnpm test
```
 
## License
 
MIT