Files · Vertex AI Code Sandbox for QuickBooks Financial Modeling

# Vertex AI Code Sandbox for QuickBooks Financial Modeling
 
> Ask conversational questions about your QuickBooks data and get safe, sandboxed code execution that generates answers with spend controls.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to combine Vertex AI with an e2b sandbox and the `@reaatech/*` package family for secure, conversational financial analysis.
 
## How it works
 
1. **User asks a question** about their QuickBooks data (e.g., "What was our net income last month?")
2. **Vertex AI** generates Python code to answer the question, using function calling with an `execute_code` declaration
3. **Tool-use firewall** (`@reaatech/tool-use-firewall-core`) evaluates the code against policy — length limits, allowlists, and risk patterns
4. **Slack approval** (`@reaatech/tool-use-firewall-approvals`) triggers a human-in-the-loop check for high-risk operations
5. **e2b sandbox** executes the approved code in a secure, isolated microVM
6. **QuickBooks data** is queried via the node-quickbooks client (Python/Node.js scripts inside the sandbox)
7. **Output repair** (`@reaatech/structured-repair-core`) validates and fixes malformed responses
8. **Cost telemetry** (`@reaatech/llm-cost-telemetry`) tracks per-request spend and enforces monthly budget caps
 
## Architecture
 
```
User → POST /api/chat → SessionManager (context) → Vertex AI (code gen)
  → Firewall (policy check) → e2b Sandbox (execution)
  → OutputRepair (validation) → Vertex AI (synthesis) → Response
```
 
## Prerequisites
 
- Node.js >= 22
- pnpm >= 10
- Google Cloud Project with Vertex AI API enabled
- E2B account and API key
- QuickBooks Online account with OAuth 2.0 credentials
- Slack workspace with a bot token
 
## Setup
 
1. Clone the repository and install dependencies:
   ```bash
   pnpm install
   ```
 
2. Copy `.env.example` to `.env` and fill in your credentials:
   ```bash
   cp .env.example .env
   ```
 
3. Run the development server:
   ```bash
   pnpm dev
   ```
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `GOOGLE_CLOUD_PROJECT` | GCP project ID for Vertex AI |
| `GOOGLE_CLOUD_LOCATION` | GCP region (default: us-central1) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |
| `E2B_API_KEY` | E2B sandbox API key |
| `QUICKBOOKS_CONSUMER_KEY` | QuickBooks OAuth consumer key |
| `QUICKBOOKS_CONSUMER_SECRET` | QuickBooks OAuth consumer secret |
| `QUICKBOOKS_OAUTH_TOKEN` | QuickBooks OAuth access token |
| `QUICKBOOKS_REALM_ID` | QuickBooks company ID |
| `QUICKBOOKS_REFRESH_TOKEN` | QuickBooks OAuth refresh token |
| `SLACK_TOKEN` | Slack bot token for approval notifications |
| `SLACK_APPROVAL_CHANNEL` | Slack channel ID for approvals |
| `MONTHLY_LLM_BUDGET_USD` | Monthly LLM spend cap |
| `SESSION_MAX_TOKENS` | Max tokens per conversation session |
| `APPROVAL_API_KEY` | API key for approval callback endpoint |
 
## API Endpoints
 
### POST /api/chat
 
Send a financial question to the chat endpoint.
 
**Request:**
```json
{ "message": "What is our current cash flow?", "sessionId": "optional-existing-session" }
```
 
**Response (no code execution needed):**
```json
{ "reply": "Your cash flow is...", "sessionId": "abc-123" }
```
 
**Response (approval required):**
```json
{ "reply": "Code execution requires approval", "sessionId": "abc-123", "approvalRequired": true, "approvalId": "appr_xyz" }
```
 
### GET /api/approvals/:approvalId
 
Check the status of an approval request. Requires `x-api-key` header.
 
### POST /api/approvals/:approvalId
 
Approve or deny a pending code execution request. Requires `x-api-key` header.
 
**Request:**
```json
{ "action": "approve" }
```
 
## Running Tests
 
```bash
pnpm test
pnpm typecheck
pnpm lint
```
 
Tests mock all external services (Vertex AI, e2b, Slack, QuickBooks) via `vi.mock`. No live API keys are needed.
 
## Project Layout
 
```
app/api/chat/route.ts              Chat API endpoint
app/api/approvals/[id]/route.ts    Approval callback endpoint
app/page.tsx                       Chat UI
src/types/index.ts                 Shared TypeScript types
src/services/vertex-client.ts      Vertex AI integration
src/services/session-manager.ts    Conversation session management
src/services/quickbooks-client.ts  QuickBooks API client
src/services/code-executor.ts      e2b sandbox executor
src/services/tool-firewall.ts      Code execution policy engine
src/services/approval-workflow.ts  Slack-based approval workflow
src/services/cost-telemetry.ts     LLM cost tracking
src/services/output-repair.ts      Structured output repair
tests/                             Vitest test suite
packages/                          API references for every dependency
```
 
## Dependencies
 
- `@reaatech/session-continuity` — Session lifecycle and context management
- `@reaatech/tool-use-firewall-core` — Firewall types and policy engine
- `@reaatech/tool-use-firewall-approvals` — Human-in-the-loop approval workflows
- `@reaatech/llm-cost-telemetry` — LLM cost tracking and budget enforcement
- `@reaatech/structured-repair-core` — Malformed output repair
- `@google-cloud/vertexai` — Vertex AI Gemini API
- `e2b` — Secure sandboxed code execution
- `node-quickbooks` — QuickBooks Online API client
- `@slack/web-api` — Slack messaging
- `zod` — Runtime schema validation
 
## License
 
MIT — see [LICENSE](./LICENSE).