Files · Vertex AI Sandboxed Data Analysis with Budget Guardrails for SMBs

# Vertex AI Sandboxed Data Analysis with Budget Guardrails for SMBs
 
> Run AI-generated code safely inside a sandbox with per‑analysis spend limits and automatic output repair.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Problem
 
SMB analysts want to use AI to generate and execute data analysis code, but raw LLM outputs are often malformed, execution can run away, and costs spiral without per‑job budgeting.
 
## Architecture
 
```
POST /api/analysis { sessionId, prompt }
  → session loaded via @reaatech/session-continuity
  → budget checked via @reaatech/agent-budget-engine (hard $1/session cap)
  → model selected via @reaatech/llm-router-engine (cheapest capable Vertex AI model)
  → code generated via Vertex AI (gemini-1.5-flash or gemini-1.5-pro)
  → code executed in @e2b/code-interpreter sandbox (isolated, timed)
  → output repaired via @reaatech/structured-repair-core (Zod schema)
  → spend recorded back to budget engine
  → result returned as AnalysisResponse
```
 
## Prerequisites
 
- Node.js >=22
- pnpm 10.x
- E2B API key (get one at https://e2b.dev/dashboard)
- GCP project with Vertex AI enabled
 
## Environment Variables
 
| Variable | Required | Description |
|---|---|---|
| `E2B_API_KEY` | Yes | E2B Code Interpreter API key |
| `GOOGLE_CLOUD_PROJECT` | Yes | GCP project ID |
| `GOOGLE_CLOUD_LOCATION` | Yes | Vertex AI region (default: us-central1) |
| `ANALYSIS_BUDGET_LIMIT` | No | Per-analysis USD spend cap (default: 1.00) |
| `VERTEX_MODEL_ID` | No | Fallback Vertex model ID (default: gemini-1.5-flash) |
| `E2B_SANDBOX_TIMEOUT_MS` | No | Sandbox execution timeout ms (default: 30000) |
 
## Quick Start
 
```bash
pnpm install
pnpm dev
```
 
Create a session:
```bash
curl -X POST http://localhost:3000/api/analysis/session \
  -H 'Content-Type: application/json' \
  -d '{}'
```
 
Run an analysis:
```bash
curl -X POST http://localhost:3000/api/analysis \
  -H 'Content-Type: application/json' \
  -d '{"sessionId":"<session-id>","prompt":"analyze sales data trends"}'
```
 
## API Reference
 
### `POST /api/analysis`
 
Request: `{ "sessionId": string, "prompt": string }`
 
Response (200): `{ "success": true, "data": { "summary": string, "insights": string[], "code"?: string }, "sessionId": string, "budgetSpent": number, "budgetRemaining": number }`
 
Response (400): `{ "error": "Missing sessionId or prompt" }`
 
Response (500): `{ "error": "...", "success": false, "sessionId": string, "budgetSpent": number, "budgetRemaining": number }`
 
### `GET /api/analysis`
 
Health check: `{ "status": "ok", "service": "vertex-ai-analysis" }`
 
### `POST /api/analysis/session`
 
Create session: `{ "userId"?: string }` → `{ "id": string, "status": "active" }`
 
## Project Structure
 
| File | Responsibility |
|---|---|
| `src/lib/types.ts` | Shared types (AnalysisRequest, AnalysisResponse, BudgetScope) |
| `src/lib/spend-store.ts` | In-memory spend tracker adapter for BudgetController |
| `src/lib/memory-storage.ts` | In-memory IStorageAdapter + SimpleTokenCounter for SessionManager |
| `src/lib/budget-check.ts` | Budget enforcement wrapper around @reaatech/agent-budget-engine |
| `src/lib/vertex-client.ts` | Vertex AI SDK wrapper for content generation |
| `src/lib/session-store.ts` | Session lifecycle wrappers around @reaatech/session-continuity |
| `src/lib/router-config.ts` | LLM router setup with Vertex AI model definitions |
| `src/lib/sandbox-executor.ts` | E2B code interpreter sandbox with concurrency limit |
| `src/lib/output-repair.ts` | Zod-schema-driven output repair via @reaatech/structured-repair-core |
| `src/lib/analytics-agent.ts` | Main orchestration agent wiring all components |
| `app/api/analysis/route.ts` | HTTP handler for analysis requests |
| `app/api/analysis/session/route.ts` | HTTP handler for session lifecycle |
 
## Testing
 
```bash
pnpm test        # vitest run --coverage
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint .
```
 
## Packages Used
 
- `@reaatech/agent-budget-engine` — budget enforcement with pre-flight checks and spend recording
- `@reaatech/llm-router-engine` — config-driven model selection with cost optimization
- `@reaatech/session-continuity` — session lifecycle management with context compression
- `@reaatech/structured-repair-core` — Zod-schema-driven LLM output repair
- `@e2b/code-interpreter` — sandboxed code execution
- `@google-cloud/vertexai` — Vertex AI Gemini API
- `p-limit` — concurrent sandbox limit
- `zod` — runtime schema validation
 
## License
 
MIT — see [LICENSE](./LICENSE).