# AtlasBurn — Full Technical Specification for LLM Consumption

> Version: 1.0.0
> Last updated: 2026-04-09
> Contact: contact@atlasburn.com

---

## 1. Product Overview

AtlasBurn is an AI Capital Risk Engine. It provides forensic burn modeling and stochastic survival forecasting for AI workloads. The platform consists of:

- **@atlasburn/sdk** — A TypeScript/JavaScript SDK that intercepts AI API calls at the fetch level.
- **AtlasBurn Cloud** — A hosted backend for storing forensic data, running Monte Carlo simulations, and enforcing budget guardrails.
- **AtlasBurn Dashboard** — A web application at app.atlasburn.com for visualizing spend, configuring policies, and reviewing audit trails.

---

## 2. SDK Architecture

### 2.1 Installation

```bash
npm install @atlasburn/sdk
# or
yarn add @atlasburn/sdk
# or
pnpm add @atlasburn/sdk
```

### 2.2 Initialization Modes

#### Auto-Detection (Recommended)
```typescript
import { initAtlasBurnAuto } from "@atlasburn/sdk";

initAtlasBurnAuto({
  apiKey: process.env.ATLASBURN_KEY,
  debug: false,           // Enable console logging
  flushIntervalMs: 5000,  // Telemetry flush interval
  maxBatchSize: 50,       // Max events per flush
});
```

Auto-detection works by monkey-patching `globalThis.fetch`. It pattern-matches request URLs against known AI provider endpoints and intercepts responses to extract token usage metadata.

#### Manual Wrapper
```typescript
import { wrapFetch } from "@atlasburn/sdk";

const trackedFetch = wrapFetch(globalThis.fetch, {
  apiKey: process.env.ATLASBURN_KEY,
});
```

### 2.3 Verification
```typescript
import { verifyAtlasBurn } from "@atlasburn/sdk";

await verifyAtlasBurn({
  apiKey: process.env.ATLASBURN_KEY,
  debug: true,
});
```

### 2.4 SDK Safety Laws (Fail-Silent Design)

1. **Never throw** — SDK errors are swallowed; your application is never blocked.
2. **Never mutate** — Request/response payloads are read-only; SDK never alters API behavior.
3. **Never delay** — Telemetry is async and non-blocking; zero latency added to AI calls.
4. **Never leak** — No prompts, completions, or PII are stored. Only token counts and metadata.

---

## 3. Telemetry Architecture

### 3.1 Event Pipeline

1. **Intercept** — Fetch calls to AI provider endpoints are detected.
2. **Extract** — Token counts (prompt_tokens, completion_tokens, total_tokens) and model identifiers are parsed from responses.
3. **Normalize** — Events are tagged with provider, model, timestamp, and cost estimate.
4. **Buffer** — Events accumulate in an in-memory ring buffer.
5. **Flush** — Batches are sent to AtlasBurn Cloud via HTTPS POST at configurable intervals.

### 3.2 Provider Endpoint Detection

| Provider | URL Pattern | Detection |
|----------|-------------|-----------|
| OpenAI | `api.openai.com/v1/*` | Auto |
| Anthropic | `api.anthropic.com/v1/*` | Auto |
| Google Gemini | `generativelanguage.googleapis.com/*` | Auto |
| Meta Llama | Custom endpoints | Manual wrapper |

### 3.3 Data Schema (per event)

```typescript
interface AtlasBurnEvent {
  id: string;              // UUID v4
  timestamp: string;       // ISO 8601
  provider: string;        // "openai" | "anthropic" | "gemini" | "meta"
  model: string;           // e.g. "gpt-4o", "claude-3-opus"
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  estimatedCostUsd: number;
  costSource: "PROVIDER_REGISTRY" | "FALLBACK_ECONOMICS";
  latencyMs: number;
  statusCode: number;
  projectId: string;
  environment: string;     // "production" | "staging" | "development"
}
```

---

## 4. Cost Engine

### 4.1 Pricing Strategy

The Cost Engine uses a two-tier pricing resolution:

1. **PROVIDER_REGISTRY** — Exact per-token pricing sourced from official provider pricing pages. Updated weekly. Used when the model is recognized.
2. **FALLBACK_ECONOMICS** — Conservative cost estimates based on model family heuristics. Applied when a model is unrecognized or newly released.

### 4.2 Confidence Rating

- **94.2%** audited confidence against actual provider invoices (based on internal testing across 10,000+ API calls).
- Discrepancies typically arise from: cached/batched responses, promotional pricing tiers, and enterprise-negotiated rates.

### 4.3 Pricing Formula

```
cost = (prompt_tokens × input_price_per_token) + (completion_tokens × output_price_per_token)
```

Where prices are looked up from PROVIDER_REGISTRY by (provider, model) tuple.

---

## 5. Auto Kill Protocol

### 5.1 Overview

Deterministic budget enforcement. When cumulative spend reaches a configured threshold, all subsequent AI API calls are blocked at the SDK level.

### 5.2 Configuration

```typescript
initAtlasBurnAuto({
  apiKey: process.env.ATLASBURN_KEY,
  budget: {
    dailyLimitUsd: 100,
    monthlyLimitUsd: 2500,
    action: "block",       // "block" | "warn" | "log"
  },
});
```

### 5.3 Behavior

- **block** — Returns a synthetic 429 response; no API call is made.
- **warn** — Allows the call but emits a warning event to the Forensic Ledger.
- **log** — Silently logs the budget breach without intervention.

---

## 6. Monte Carlo Forecasting

Stochastic burn rate projections based on historical usage patterns.

- **P50** — Median expected spend over the forecast period.
- **P95** — 95th percentile; spend unlikely to exceed this under normal usage.
- **P99** — 99th percentile; worst-case scenario excluding extreme outliers.

Simulations run 10,000 iterations using historical call frequency, token distribution, and model mix as inputs.

---

## 7. Security

- **HMAC-SHA-256** key verification for all API keys.
- **No raw key storage** — Keys are hashed before persistence.
- **No PII, prompts, or completions stored** — Only token counts, costs, and metadata.
- **Firestore-level isolation** — Each project's data is isolated at the database level.
- **TLS 1.3** for all data in transit.

---

## 8. Integration Guides

### 8.1 Next.js (App Router)

Initialize in a Server Component or API route:
```typescript
// app/layout.tsx or middleware.ts
import { initAtlasBurnAuto } from "@atlasburn/sdk";
initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
```

### 8.2 Express / Node.js

```typescript
// server.ts
import { initAtlasBurnAuto } from "@atlasburn/sdk";
initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
// ... rest of server setup
```

### 8.3 Genkit / LangChain

Use manual wrapper mode if the framework manages its own HTTP client:
```typescript
import { wrapFetch } from "@atlasburn/sdk";
// Pass wrapped fetch to your framework's HTTP configuration
```

---

## 9. Troubleshooting

### Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| No events in ledger | SDK not initialized before first AI call | Move `initAtlasBurnAuto()` to app entry point |
| Cost shows $0 | Model not in PROVIDER_REGISTRY | Will use FALLBACK_ECONOMICS; check model name |
| Auto Kill not triggering | Budget not configured | Add `budget` config to init options |
| Debug logs not showing | `debug: false` (default) | Set `debug: true` in init options |

---

## 10. API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `POST /v1/events` | POST | Ingest telemetry events (SDK internal) |
| `GET /v1/ledger` | GET | Retrieve Forensic Ledger entries |
| `GET /v1/forecast` | GET | Get Monte Carlo burn forecast |
| `GET /v1/budget` | GET | Current budget status and remaining |
| `PUT /v1/budget` | PUT | Update budget configuration |
| `GET /v1/health` | GET | Service health check |

---

## 11. Links

- Main site: https://atlasburn.com
- Documentation: https://docs.atlasburn.com
- Dashboard: https://app.atlasburn.com
- LLM summary: https://atlasburn.com/llms.txt
- Contact: contact@atlasburn.com