Files · Azure AI Code Sandbox for SMB Analytics

# Azure AI Code Sandbox for SMB Analytics
 
> Secure, budget‑enforced code execution for small business data analysis, powered by Azure AI and REAA safety controls.
 
SMBs need to run custom analytics scripts against their operational data, but giving an AI agent raw code execution risks runaway costs, infinite loops, or broken outputs without guardrails. This project wraps an E2B sandbox in a safety layer built from REAA packages: `@reaatech/agent-budget-engine` caps per‑analysis spending, `@reaatech/circuit-breaker-agents` isolates failing scripts and prevents cascading failures, and `zod` plus the AI SDK enforces structured inputs and outputs. A Next.js dashboard lets business users submit queries, monitor spend, and view results.
 
## Architecture
 
```
Next.js App Router (app/)
  ├── app/page.tsx              — Dashboard UI (query input, budget bar, results)
  ├── app/api/execute/route.ts  — POST /api/execute (analysis request handler)
  └── app/api/metrics/route.ts  — GET /api/metrics (budget telemetry)
 
src/
  ├── lib/
  │   ├── schemas.ts            — Zod schemas (AnalysisRequest, AnalysisResult, MetricsResponse)
  │   ├── pricing-provider.ts   — Azure OpenAI rate card for BudgetController
  │   ├── supabase.ts           — Supabase client for persisting results
  │   └── langfuse.ts           — Langfuse observability client
  ├── services/
  │   ├── budget-service.ts     — BudgetController + SpendStore singleton
  │   ├── circuit-breaker-service.ts — CircuitBreaker with InMemoryAdapter
  │   ├── sandbox-service.ts    — E2B sandbox wrapper with p-retry + timeout
  │   └── analysis-service.ts   — Orchestrator (budget → AI code gen → sandbox → record)
  └── instrumentation.ts        — Next.js register() for startup hooks
```
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key (read by `@ai-sdk/azure`) |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
| `AZURE_OPENAI_DEPLOYMENT_NAME` | Deployment name (passed to `azure(name)`) |
| `E2B_API_KEY` | E2B sandbox API key |
| `SUPABASE_URL` | Supabase project URL |
| `SUPABASE_ANON_KEY` | Supabase anonymous key |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_BASE_URL` | Langfuse host URL |
| `MAX_BUDGET_PER_ANALYSIS` | Per-analysis budget cap (default: 5.0) |
| `DEFAULT_BUDGET_LIMIT` | Default user budget limit (default: 10.0) |
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env   # fill in your API keys
pnpm test              # vitest run with coverage
pnpm dev               # next dev server at http://localhost:3000
```
 
## API Reference
 
### POST /api/execute
 
Submit an analysis query:
 
```bash
curl -X POST http://localhost:3000/api/execute \
  -H 'Content-Type: application/json' \
  -H 'x-budget-scope-key: user-abc' \
  -d '{"query": "Show total sales by month"}'
```
 
**Success (201):**
```json
{
  "id": "uuid",
  "output": "sales data...",
  "executionTimeMs": 1234,
  "cost": 0.05,
  "tokensUsed": { "input": 50, "output": 200 },
  "status": "success"
}
```
 
**Error (402):** Budget exceeded — `{ "error": "Budget exceeded", "remaining": 0 }`
 
**Error (503):** Circuit open — `{ "error": "Service temporarily unavailable", "fallback": {...} }`
 
### GET /api/metrics
 
Get budget state for a scope:
 
```bash
curl http://localhost:3000/api/metrics \
  -H 'x-budget-scope-key: user-abc'
```
 
**Success (200):** `{ "remaining": 4.95, "spent": 0.05, "limit": 5.0, "state": "active" }`
 
## Budget Configuration
 
The `BudgetController` from `@reaatech/agent-budget-engine` manages a per-scope state machine:
 
```
Active → Warned (soft cap at 80%) → Degraded → Stopped (hard cap at 100%)
```
 
Auto-downgrade and tool filtering activate when budgets tighten. Events are traced via Langfuse.
 
## Circuit Breaker
 
The `CircuitBreaker` from `@reaatech/circuit-breaker-agents` wraps sandbox execution with:
 
- **Error threshold**: 3 consecutive failures trips the circuit OPEN
- **Recovery timeout**: 30 seconds before testing HALF_OPEN
- **Fallback**: When open, returns a structured circuit_open error instead of crashing
 
State transitions are logged via Langfuse for observability.
 
## Packages
 
### REAA
- `@reaatech/agent-budget-engine` — Budget enforcement with pre-flight checks, spend recording, auto-downgrade
- `@reaatech/agent-budget-middleware` — BudgetInterceptor for programmatic budget gating
- `@reaatech/circuit-breaker-agents` — Circuit breaker state machine with InMemoryAdapter persistence
 
### Third-party
- `e2b` — Cloud sandbox for secure code execution
- `@supabase/supabase-js` — Database persistence for analysis results
- `zod` — Runtime schema validation
- `p-retry` — Retry with backoff for sandbox creation
- `langfuse` — LLM observability and tracing
- `ai` + `@ai-sdk/azure` — Vercel AI SDK with Azure OpenAI provider
 
## License
 
MIT — see [LICENSE](./LICENSE).