Files · Perplexity Code Sandbox for SMB Data Reporting

# Perplexity Code Sandbox for SMB Data Reporting
 
Run AI-generated analytics code in a safe, budget-controlled sandbox with real-time data hooks.
 
SMB analysts can ask natural-language questions and get Python or SQL code generated by Perplexity AI, safely executed in a Daytona sandbox behind circuit-breaker and budget controls.
 
## Architecture
 
```
Natural Language Query
        │
        ▼
  Confidence Router ──CLARIFY──▶ Clarification Prompt
        │ FALLBACK
        ▼
  Perplexity API (code generation)
        │
        ▼
  Structured Output Repair
        │
        ▼
  Code Validation (Python/SQL safety)
        │
        ▼
  Budget Controller (spend check)
        │
        ▼
  Circuit Breaker ──▶ Daytona Sandbox ──▶ Execution
        │
        ▼
  Budget Controller (spend recording)
        │
        ▼
  LLM Cache (result storage)
        │
        ▼
  Response to user
```
 
## Prerequisites
 
- Node.js >= 22
- pnpm 10.x
- API keys for: Perplexity, Daytona, OpenAI (for embeddings), Langfuse (optional)
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Edit .env with your API keys
pnpm dev
```
 
## Environment Variables
 
| Variable | Description | Default |
|----------|-------------|---------|
| `PERPLEXITY_API_KEY` | Perplexity AI API key | required |
| `DAYTONA_API_KEY` | Daytona sandbox API key | required |
| `OPENAI_API_KEY` | OpenAI key for cache embeddings | required |
| `LANGFUSE_PUBLIC_KEY` | Langfuse tracing public key | optional |
| `LANGFUSE_SECRET_KEY` | Langfuse tracing secret key | optional |
| `LANGFUSE_HOST` | Langfuse host URL | `https://cloud.langfuse.com` |
| `BUDGET_DEFAULT_LIMIT` | Default budget limit per scope | `5.00` |
| `CACHE_DEFAULT_TTL` | Cache TTL in seconds | `3600` |
| `SEMANTIC_CACHE_THRESHOLD` | Cosine similarity threshold | `0.8` |
| `CIRCUIT_BREAKER_FAILURE_THRESHOLD` | Failures before circuit opens | `5` |
| `CIRCUIT_BREAKER_RECOVERY_TIMEOUT_MS` | Circuit recovery timeout | `30000` |
| `CONFIDENCE_ROUTE_THRESHOLD` | Minimum confidence to route | `0.8` |
| `CONFIDENCE_FALLBACK_THRESHOLD` | Max confidence for fallback | `0.3` |
 
## API
 
### POST /api/generate
 
Accepts a natural-language query and returns generated + executed code results.
 
**Request body:**
```json
{ "query": "show me last month's sales by region", "useCase": "code-sandbox" }
```
 
**Response:**
```json
{ "id": "...", "response": "...", "code": "...", "executionResult": {...}, "routingDecision": "ROUTE", "cached": false, "cost": 0.05, "tokens": { "input": 100, "output": 50 } }
```
 
### GET/POST /api/budgets
 
Manage budget definitions per scope.
 
### GET/DELETE /api/cache
 
Check cache health or invalidate by model version.
 
## Testing
 
```bash
pnpm test
```
 
Runs vitest with 90% coverage thresholds on runtime code.