{"owner":"Helicone","repo":"helicone","hasSkills":true,"totalSkillsCount":23,"totalTokensCount":15499,"categories":["root-instruction","claude-rule","plugin-manifest","anthropic-skill","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md","packages/README.md","packages/tsconfig.json",".cursor/rules/ai-gateway-docs.mdc",".cursor/rules/docs-guide.mdc",".cursor/rules/helicone-style-guidelines.mdc",".cursor/rules/helicone-system-overview.mdc",".cursor/rules/supabase.mdc",".cursor/rules/jawn.mdc","packages/common/package.json","packages/cost/FLOWS.md","packages/cost/README.md","packages/cost/package.json","packages/filters/package.json","packages/llm-mapper/README.md","packages/llm-mapper/package.json","packages/pricing/package.json","packages/prompts/package.json","packages/secrets/package.json","examples/tools/python/README.md","packages/cost/models/AUTHORS_DATA_POPULATION.md","packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md"],"skills":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n  - valhalla/jawn/src/tsoa-build/\n  - web/lib/clients/jawnTypes/\n  - bifrost/lib/clients/jawnTypes/\n  - worker/supabase/database.types.ts\n  - web/db/database.types.ts\n  - helicone-cron/src/db/database.types.ts\n  - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put <NAME>`.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace <name> <cmd>`; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth          # With better-auth\ncd web && yarn dev:local               # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n<div className=\"flex flex-col gap-4\">\n<div className=\"flex items-center gap-2\">\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/                   # Next.js frontend\n/valhalla/jawn/        # Express.js backend\n/worker/               # Cloudflare Workers\n/aigateway/            # Rust LLM proxy\n/bifrost/              # Marketing site\n/packages/             # Shared packages\n  ├── cost/            # Cost calculations\n  ├── llm-mapper/      # Provider mappings\n  └── prompts/         # Prompt management\n/supabase/             # Database migrations\n/clickhouse/           # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n   ```bash\n   grep -r \"thinkingLevel\" packages/  # Find all usages of similar type\n   ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n\n| Component | Size                                 | Line Height       | Weight    | Usage              |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1        | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold  | Main page titles   |\n| H1Large   | text-5xl (48px)                      | leading-10 (40px) | extrabold | Hero sections      |\n| H2        | text-3xl (30px)                      | leading-9 (36px)  | semibold  | Section headers    |\n| H3        | text-2xl (24px)                      | leading-8 (32px)  | semibold  | Subsection headers |\n| H4        | text-xl (20px)                       | leading-7 (28px)  | semibold  | Card titles        |\n| Lead      | text-xl (20px)                       | leading-7 (28px)  | normal    | Introduction text  |\n| P         | text-base (16px)                     | leading-7 (28px)  | normal    | Body text          |\n| Small     | text-sm (14px)                       | leading-4 (16px)  | medium    | Helper text        |\n| Muted     | text-sm (14px)                       | leading-none      | normal    | Secondary text     |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>Monitor and analyze your LLM usage</Lead>\n\n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n\n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map((feature) => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">Last 30 days</Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```\n","packages/README.md":"# Common issues\n\nIf you are using OpenAI you might need to include stream usage options: https://docs.helicone.ai/faq/enable-stream-usage\n\n\n\n# Helicone Packages\n\nThis directory contains shared packages used across the Helicone ecosystem.\n\n## Packages\n\n### 🏷️ Cost Package\n**Add pricing support for LLM models and providers**\n\nThe cost package handles pricing calculations for all supported AI/ML providers in Helicone.\n\n**[📖 Click here to add cost support for new models →](./cost/README.md)**\n\nCommon tasks:\n- Add pricing for new models (GPT-5, Claude 4, etc.)\n- Add support for new providers \n- Update existing model pricing\n- Add cost types (images, audio, per-call fees)\n\n### 🗺️ LLM Mapper\nRequest/response mapping and transformation for different LLM providers.\n\n### 🔍 Filters  \nFiltering definitions and utilities for request/response data.\n\n### 💬 Prompts\nPrompt templates and management utilities.\n\n## Contributing\n\nEach package contains its own documentation. See individual README files for contribution guidelines.\n\n### Quick Links\n- **[Cost Package Documentation](./cost/README.md)** - Add model pricing support\n- **Test Directory** - Package tests in `__tests__/`\n\n## Development\n\n### Running Tests\n\nTests are located in `__tests__/` directory and use Jest:\n\n```bash\n# Run all package tests\nnpx jest\n\n# Run specific test file\nnpx jest __tests__/cost/registrySnapshots.test.ts\n\n# Update snapshots after intentional changes\nnpx jest -u\n\n# Run tests without cache (useful for debugging)\nnpx jest --no-cache\n```\n\n#### Key Test Files\n- `__tests__/cost/ensureOnlyOne.test.ts` - Validates no duplicate models and cost calculations\n- `__tests__/cost/registrySnapshots.test.ts` - Snapshot tests for model registry (pricing, coverage, configs)\n- `__tests__/llm-mapper/` - Tests for request/response mapping\n\n### Building\n\n```bash\n# Build packages\nnpm run build\n```\n","packages/tsconfig.json":"{\n  \"compilerOptions\": {\n    \"target\": \"es5\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": true,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"node\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [\n      {\n        \"name\": \"next\"\n      }\n    ],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\n    \"next-env.d.ts\",\n    \"**/*.ts\",\n    \"**/*.tsx\",\n    \".next/types/**/*.ts\",\n    \"../valhalla/jawn/src/utils/tryGetSize.ts\"\n  ],\n  \"exclude\": [\"node_modules\", \"codegen.ts\"]\n}\n",".cursor/rules/ai-gateway-docs.mdc":"---\ndescription: \nglobs: docs/ai-gateway/*\nalwaysApply: false\n---\n# AI Gateway Documentation Rules\n\nCritical rules to ensure documentation accuracy based on configuration changes.\n\n## Configuration Structure (BREAKING CHANGES)\n\n### 1. Cache Store Configuration\n\n```yaml\n# ✅ CORRECT - cache-store at top level\ncache-store:\n  type: \"in-memory\"\n\nrouters:\n  my-router:\n    cache:\n      directive: \"max-age=3600\"\n\n# ❌ WRONG - old structure\nrouters:\n  my-router:\n    cache:\n      store: in-memory\n      enabled: true\n```\n\n### 2. Helicone Configuration\n\n```yaml\n# ✅ CORRECT - separate fields\nhelicone:\n  authentication: true\n  observability: true\n\n# ❌ WRONG - old structure\nhelicone-observability:\n  enable-auth: true\n```\n\n## Required Dependencies\n\n### 3. Authentication Requirements\n\n- **Rate limiting requires authentication** (works per-API-key)\n- **Observability requires authentication** to function\n- Always add warning and link to `/ai-gateway/authentication`\n\n### 4. Model Names\n\n```yaml\n# ✅ CORRECT - provider prefix\n\"model\": \"openai/gpt-4o-mini\"\n\n# ❌ WRONG - no prefix\n\"model\": \"gpt-4o-mini\"\n```\n\n## Examples That Actually Work\n\n### 5. Code Examples\n\n- **Always include:** TypeScript, Python, cURL (no Node.js)\n- **Router URLs:** `http://localhost:8080/router/{name}/v1/chat/completions`\n- **API Keys:** Use `sk-placeholder` for local, real keys for public deployments\n\n### 6. Deprecated Patterns to Never Use\n\n- ❌ `cache.enabled: true/false`\n- ❌ `cache.store: in-memory`\n- ❌ `helicone-observability.enable-auth`\n- ❌ Model names without provider prefixes\n",".cursor/rules/docs-guide.mdc":"---\nglobs: docs/*\nalwaysApply: false\n---\n\n# Helicone Documentation Guide\n\nA streamlined guide for creating consistent, high-quality feature documentation.\n\n## Template Structure\n\nAll feature documentation must follow this exact structure:\n\n````markdown\n---\ntitle: \"[Feature Name]\"\nsidebarTitle: \"[Feature Name]\"\n---\n\nWhen [developer context/situation], [common pattern]. [Feature name] [solves this by doing X].\n\n## Why use [Feature Name]\n\n- **[Benefit 1]**: Specific, actionable benefit\n- **[Benefit 2]**: Another key advantage\n- **[Benefit 3]**: Third compelling reason\n\n## Quick Start\n\n<Steps>\n<Step title=\"[Action 1]\">\nDescription with code example.\n```language\n// Working code\n````\n\n</Step>\n</Steps>\n\n## Configuration Options\n\n### Basic Settings\n\n| Setting | Type     | Description  | Default     | Example     |\n| ------- | -------- | ------------ | ----------- | ----------- |\n| `name`  | `string` | What it does | `\"default\"` | `\"example\"` |\n\n### Advanced Settings\n\n| Setting    | Type     | Description    | Default | Example            |\n| ---------- | -------- | -------------- | ------- | ------------------ |\n| `advanced` | `object` | Complex config | `{}`    | `{\"key\": \"value\"}` |\n\n## Use Cases\n\n<Tabs>\n<Tab title=\"[Use Case 1]\">\nReal-world scenario description.\n\n<CodeGroup>\n```typescript Node.js\n// Complete working example\n```\n```python Python  \n# Same example in Python\n```\n</CodeGroup>\n</Tab>\n</Tabs>\n\n## Understanding [Feature Name]\n\n### [Core Concept]\n\nDeep explanation of key concepts developers need to understand.\n\n```typescript\n// ✅ Good example\n// Correct usage\n\n// ❌ Bad example\n// What not to do\n```\n\n## Related Features\n\n<CardGroup cols={2}>\n<Card title=\"[Feature]\" icon=\"icon-name\" href=\"/path\">\nHow they work together\n</Card>\n</CardGroup>\n```\n\n## Component Usage\n\n### Required Components\n\n**Steps** - For procedures:\n\n```markdown\n<Steps>\n  <Step title=\"Action\">Content and code</Step>\n</Steps>\n```\n\n**Tabs** - For use cases:\n\n```markdown\n<Tabs>\n  <Tab title=\"Scenario\">Content</Tab>\n</Tabs>\n```\n\n**CodeGroup** - Multiple languages:\n\n````markdown\n<CodeGroup>\n```typescript Node.js\n// Code\n````\n\n```python Python\n# Code\n```\n\n</CodeGroup>\n```\n\n**CardGroup** - Related features:\n\n```markdown\n<CardGroup cols={2}>\n  <Card title=\"Feature\" icon=\"icon\" href=\"/path\">Description</Card>\n</CardGroup>\n```\n\n## Content Standards\n\n### Writing Rules\n\n1. **Start with developer context**: \"When building X, you need Y\"\n2. **No generic introductions**: Avoid \"This page explains...\"\n3. **Exactly 3 benefits**: Specific and actionable\n4. **3-5 Quick Start steps**: Immediately actionable\n5. **Complete code examples**: Include imports and setup\n6. **Real-world use cases**: Focus on developer problems\n7. **Good vs bad examples**: Use ✅/❌ format\n\n### Code Requirements\n\n- **All examples must be tested** with real API calls\n- **Include necessary imports** and setup code\n- **Show error handling** for production use\n- **Use current syntax** and dependencies\n- **Provide complete context** - no partial snippets\n\n### Content Guidelines\n\n- **Remove UI-only sections** that don't add developer value\n- **Focus on implementation** not product features\n- **Use consistent terminology** throughout\n- **Include alt text** for all images\n- **Link related features** appropriately\n\n## Workflow\n\n### 1. Apply Template\n\n- Follow the structure exactly\n- Use required components properly\n- Focus on developer-first content\n- Remove unnecessary UI descriptions\n\n### 2. Validate Against Code\n\n- Verify all API endpoints exist\n- Check authentication requirements\n- Confirm configuration options and defaults\n- Find any undocumented features\n\n### 3. Test Examples\n\n- Create test scripts for all code examples\n- Use real API keys to verify functionality\n- Test error conditions and edge cases\n- Confirm dashboard integration works\n\n## Quality Checklist\n\nBefore publishing:\n\n- [ ] Follows template structure exactly\n- [ ] All code examples tested and working\n- [ ] API details verified against codebase\n- [ ] Uses proper Mintlify components\n- [ ] Includes complete, working examples\n- [ ] Focuses on developer use cases\n- [ ] Related features properly linked\n- [ ] No UI-only content without value\n\n## Common Mistakes\n\n**Avoid:**\n\n- Generic introductions (\"This feature allows...\")\n- Incomplete code examples missing imports\n- Untested code snippets\n- UI descriptions without developer value\n- Missing error handling\n- Outdated syntax or dependencies\n\n**Instead:**\n\n- Start with developer context\n- Provide complete, tested examples\n- Focus on implementation details\n- Show practical use cases\n- Include proper error handling\n- Keep examples current\n",".cursor/rules/helicone-style-guidelines.mdc":"---\ndescription: Helicone Style Guidelines\nglobs: \nalwaysApply: true\n---\n# Helicone Design System Guidelines\n\n## Core Principles\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n| Component | Size | Line Height | Weight | Usage |\n|-----|---|----|---|----|\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n```tsx\n/* Text Colors */\ntext-foreground              // Primary text\ntext-muted-foreground        // Secondary text\ntext-accent-foreground       // Accent text\n\n/* Background Colors */\nbg-background                // Page background\nbg-card                      // Card background\nbg-muted                     // Muted background\n\n/* Border Colors */\nborder-border                // Default borders\nborder-input                 // Form inputs\nring-ring                    // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n```tsx\n/* Light Mode */\nbg-primary                   // #0EA5E9 (sky-500)\ntext-primary-foreground      // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg-primary                   // #0284C7 (sky-600)\ntext-primary-foreground      // #083344 (sky-950)\n```\n\n### Background Colors\n```tsx\n/* Light Mode */\nbg-background                // #FFFFFF (white)\ntext-foreground              // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-background                // #020617 (slate-950)\ntext-foreground              // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n```tsx\n/* Light Mode */\nbg-accent                    // #F1F5F9 (slate-100)\ntext-accent-foreground       // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-accent                    // #1E293B (slate-800)\ntext-accent-foreground       // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n```tsx\n/* Light Mode */\nbg-card                      // #FFFFFF (white)\ntext-card-foreground         // #020617 (slate-950)\nbg-popover                   // #FFFFFF (white)\ntext-popover-foreground      // #020617 (slate-950)\nborder-border                // #E2E8F0 (slate-200)\nborder-input                 // #E2E8F0 (slate-200)\nring-ring                    // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-card                      // #020617 (slate-950)\ntext-card-foreground         // #F8FAFC (slate-50)\nbg-popover                   // #020617 (slate-950)\ntext-popover-foreground      // #F8FAFC (slate-50)\nborder-border                // #1E293B (slate-800)\nborder-input                 // #1E293B (slate-800)\nring-ring                    // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n```tsx\n/* Light Mode */\nbg-muted                     // #F1F5F9 (slate-100)\ntext-muted-foreground        // #64748B (slate-500)\nbg-secondary                 // #F1F5F9 (slate-100)\ntext-secondary-foreground    // #0F172A (slate-900)\nbg-destructive               // #DC2626 (red-600)\ntext-destructive-foreground  // #450A0A (red-950)\nbg-confirmative              // #16A34A (green-600)\ntext-confirmative-foreground // #052E16 (green-950)\n\n/* Dark Mode */\nbg-muted                     // #1E293B (slate-800)\ntext-muted-foreground        // #94A3B8 (slate-400)\nbg-secondary                 // #1E293B (slate-800)\ntext-secondary-foreground    // #F8FAFC (slate-50)\nbg-destructive               // #7F1D1D (red-900)\ntext-destructive-foreground  // #FEF2F2 (red-50)\nbg-confirmative              // #14532D (green-900)\ntext-confirmative-foreground // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n```tsx\n/* Light Mode */\nbg-sidebar-background        // #F8FAFC (slate-50)\ntext-sidebar-foreground      // #334155 (slate-700)\nborder-sidebar-border        // #E2E8F0 (slate-200)\nbg-sidebar-primary           // #0C4A6E (sky-900)\ntext-sidebar-primary-foreground // #F0F9FF (sky-50)\nbg-sidebar-accent            // #F1F5F9 (slate-100)\ntext-sidebar-accent-foreground // #0F172A (slate-900)\nring-sidebar-ring            // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg-sidebar-background        // #0F172A (slate-900)\ntext-sidebar-foreground      // #F1F5F9 (slate-100)\nborder-sidebar-border        // #1E293B (slate-800)\nbg-sidebar-primary           // #0369A1 (sky-700)\ntext-sidebar-primary-foreground // #FFFFFF (white)\nbg-sidebar-accent            // #1E293B (slate-800)\ntext-sidebar-accent-foreground // #F1F5F9 (slate-100)\nring-sidebar-ring            // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n```tsx\n/* Light Mode */\nbg-chart-1                   // #2A9D90\nbg-chart-2                   // #E76E50\nbg-chart-3                   // #274754\nbg-chart-4                   // #E8C468\nbg-chart-5                   // #F4A462\n\n/* Dark Mode */\nbg-chart-1                   // #2662D9\nbg-chart-2                   // #E23670\nbg-chart-3                   // #E88C30\nbg-chart-4                   // #AF57DB\nbg-chart-5                   // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>\n    Monitor and analyze your LLM usage\n  </Lead>\n  \n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n    \n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map(feature => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">\n      Last 30 days\n    </Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```",".cursor/rules/helicone-system-overview.mdc":"---\ndescription: \nglobs: \nalwaysApply: true\n---\n# Helicone System Architecture\n\n## Core Components\n\n1. **Frontend (Web)** - Next.js application\n   - Dashboard UI for visualization and management\n   - Located in `/web` directory\n\n2. **Proxy Workers** - Cloudflare Workers\n   - Intercept and process API calls to LLM providers\n   - Located in `/worker` directory\n   - Separate workers for OpenAI, Anthropic, and general API\n\n3. **Jawn Server** - Express.js + Tsoa backend\n   - Core business logic and data processing\n   - Located in `/valhalla/jawn` directory\n   - Handles authentication, logging, and analytics\n\n4. **Bifrost** - Landing page and blog application\n   - Marketing website and documentation\n   - Located in `/bifrost` directory\n\n5. **Databases**\n   - **PostgreSQL** (via Supabase): User data, organizations, API keys\n   - **ClickHouse**: High-performance analytics storage for request logs\n\n6. **Object Storage** - Minio/S3 compatible\n   - Stores large request/response payloads\n   - Enables efficient retrieval of historical data\n\n7. **Upstash** - Redis-compatible message queue\n   - Buffers requests between proxy and backend\n   - Ensures reliable delivery of logging data\n\n## Directory Structure\n\n```\n/helicone\n├── /web                 # Next.js frontend dashboard\n├── /worker              # Cloudflare Workers proxy\n│   ├── /src/routers     # API provider-specific routers\n│   └── /src/lib         # Shared utilities\n├── /valhalla\n│   └── /jawn            # Express.js backend server\n├── /bifrost             # Landing page and blog\n├── /sdk                 # Client SDKs\n│   ├── /typescript      # TypeScript SDK\n│   └── /python          # Python SDK\n```\n\n## Data Flow\n\n1. **Request Interception**:\n   - Client request → Helicone Proxy → LLM Provider\n   - Proxy adds tracking headers and applies features\n\n2. **Response Processing**:\n   - LLM Provider → Helicone Proxy → Client\n   - Proxy sends log data to Upstash queue\n\n3. **Log Processing**:\n   - Upstash queue → Jawn server\n   - Jawn processes and stores logs in databases\n\n4. **Data Storage**:\n   - Request metadata → PostgreSQL\n   - Analytics data → ClickHouse\n   - Large payloads → Object Storage\n\n5. **Analytics Processing**:\n   - Jawn server processes logs for insights\n   - Aggregates metrics for dashboard visualization\n\n## System Interactions\n\n- **Frontend ↔ Jawn**: REST API for dashboard data\n- **Proxy ↔ Upstash**: Asynchronous message queuing\n- **Upstash ↔ Jawn**: Reliable message delivery\n- **Jawn ↔ Databases**: Data storage and retrieval\n\n## Technical Implementation\n\n- **Frontend**: React, Next.js, Tailwind CSS\n- **Proxy**: Cloudflare Workers, TypeScript\n- **Backend**: Express.js, Tsoa, TypeScript\n- **Bifrost**: Next.js, React, TypeScript\n- **Databases**: PostgreSQL, ClickHouse\n- **Queue**: Upstash Redis\n\n## Key Files for Development\n\n- `/worker/src/index.ts`: Entry point for proxy workers\n- `/worker/src/routers/`: Provider-specific routing logic\n- `/valhalla/jawn/src/index.ts`: Backend server entry point\n- `/web/pages/`: Frontend dashboard components\n- `/bifrost/pages/`: Landing page and blog components",".cursor/rules/supabase.mdc":"---\ndescription: Supabase\nglobs: *.ts, *sql\nalwaysApply: false\n---\nDo not use the Supabase Client, instead use the Jawn Client and put all new endpoints in controllers.\nDon't use RLS policies, instead enable RLS for new tables and revoke privledges. Example:\n\n```\nalter table \"public\".\"org_rate_limits\" enable row level security;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom authenticated;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom anon;\n```",".cursor/rules/jawn.mdc":"---\ndescription: \nglobs: *.ts\nalwaysApply: false\n---\n# Helicone Jawn Controller and TanStack Query Integration\n\n## Controller Pattern\n- Jawn controllers (`valhalla/jawn/src/controllers/`) follow a RESTful design with standard HTTP methods\n- Controllers use decorators like `@Route`, `@Get`, `@Post`, etc. from TSOA\n- Controllers accept `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Required parameters should come before optional parameters in controller methods\n\n## Manager Pattern\n- Each controller has a corresponding manager (`valhalla/jawn/src/managers/`)\n- Managers extend `BaseManager` and handle database operations\n- Managers receive `authParams` from the controller request\n- Use `dbExecute` for database operations and wrap results in `Result<T, string>`\n\n## Frontend Hooks with TanStack Query\n- Use `useJawnClient()` to interact with Jawn controllers\n- Implement custom hooks with TanStack Query for data fetching and mutations\n- For GET requests:\n  ```typescript\n  const query = useQuery({\n    queryKey: ['resource', id],\n    queryFn: async () => {\n      const response = await jawn.GET('/v1/resource/{id}', {\n        params: { path: { id } }\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    }\n  });\n  ```\n\n- For mutations:\n  ```typescript\n  const mutation = useMutation({\n    mutationFn: async (input) => {\n      const response = await jawn.POST('/v1/resource', {\n        body: input\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    },\n    onSuccess: (data) => {\n      // Invalidate queries\n      queryClient.invalidateQueries({ queryKey: ['resource'] });\n    }\n  });\n  ```\n\n## Type Definitions\n- Define request and response interfaces in the controller file\n- Use proper typing with TanStack Query\n- Handle Jawn response structure properly with error checking\n\n## URL State Management\n- Use URL parameters for persisting filter state between pages\n- Update URL when filter changes with `useSearchParams` from Next.js\n\n## Database Schema\n- Tables follow snake_case naming\n- Use proper indexes for performance\n- Implement proper RLS policies for security\n- Create functions for specialized operations (e.g., incrementing versions)\n\n## Enhanced Filters Specifics\n- Filters support both simple queries and complex logical expressions\n- Filters can be persisted, shared, and reused\n- Support both legacy and enhanced filter systems for backward compatibility\n","packages/common/package.json":"{\n  \"name\": \"@helicone-package/common\",\n  \"types\": \"./\",\n  \"version\": \"1.0.0\"\n}\n","packages/cost/FLOWS.md":"# Cost Skill\n\nPath: `packages/cost/FLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/FLOWS.md)","packages/cost/README.md":"# cost Documentation\n\nPath: `packages/cost/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/README.md)","packages/cost/package.json":"# Cost Skill\n\nPath: `packages/cost/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/package.json)","packages/filters/package.json":"# Filters Skill\n\nPath: `packages/filters/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/filters/package.json)","packages/llm-mapper/README.md":"# llm-mapper Documentation\n\nPath: `packages/llm-mapper/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/README.md)","packages/llm-mapper/package.json":"# Llm-mapper Skill\n\nPath: `packages/llm-mapper/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/package.json)","packages/pricing/package.json":"# Pricing Skill\n\nPath: `packages/pricing/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/pricing/package.json)","packages/prompts/package.json":"# Prompts Skill\n\nPath: `packages/prompts/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/prompts/package.json)","packages/secrets/package.json":"# Secrets Skill\n\nPath: `packages/secrets/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/secrets/package.json)","examples/tools/python/README.md":"# python Documentation\n\nPath: `examples/tools/python/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/examples/tools/python/README.md)","packages/cost/models/AUTHORS_DATA_POPULATION.md":"# Models Skill\n\nPath: `packages/cost/models/AUTHORS_DATA_POPULATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/AUTHORS_DATA_POPULATION.md)","packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md":"# Authors Skill\n\nPath: `packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md)"},"files":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n  - valhalla/jawn/src/tsoa-build/\n  - web/lib/clients/jawnTypes/\n  - bifrost/lib/clients/jawnTypes/\n  - worker/supabase/database.types.ts\n  - web/db/database.types.ts\n  - helicone-cron/src/db/database.types.ts\n  - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put <NAME>`.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace <name> <cmd>`; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth          # With better-auth\ncd web && yarn dev:local               # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n<div className=\"flex flex-col gap-4\">\n<div className=\"flex items-center gap-2\">\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/                   # Next.js frontend\n/valhalla/jawn/        # Express.js backend\n/worker/               # Cloudflare Workers\n/aigateway/            # Rust LLM proxy\n/bifrost/              # Marketing site\n/packages/             # Shared packages\n  ├── cost/            # Cost calculations\n  ├── llm-mapper/      # Provider mappings\n  └── prompts/         # Prompt management\n/supabase/             # Database migrations\n/clickhouse/           # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n   ```bash\n   grep -r \"thinkingLevel\" packages/  # Find all usages of similar type\n   ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n\n| Component | Size                                 | Line Height       | Weight    | Usage              |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1        | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold  | Main page titles   |\n| H1Large   | text-5xl (48px)                      | leading-10 (40px) | extrabold | Hero sections      |\n| H2        | text-3xl (30px)                      | leading-9 (36px)  | semibold  | Section headers    |\n| H3        | text-2xl (24px)                      | leading-8 (32px)  | semibold  | Subsection headers |\n| H4        | text-xl (20px)                       | leading-7 (28px)  | semibold  | Card titles        |\n| Lead      | text-xl (20px)                       | leading-7 (28px)  | normal    | Introduction text  |\n| P         | text-base (16px)                     | leading-7 (28px)  | normal    | Body text          |\n| Small     | text-sm (14px)                       | leading-4 (16px)  | medium    | Helper text        |\n| Muted     | text-sm (14px)                       | leading-none      | normal    | Secondary text     |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>Monitor and analyze your LLM usage</Lead>\n\n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n\n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map((feature) => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">Last 30 days</Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```\n","packages/README.md":"# Common issues\n\nIf you are using OpenAI you might need to include stream usage options: https://docs.helicone.ai/faq/enable-stream-usage\n\n\n\n# Helicone Packages\n\nThis directory contains shared packages used across the Helicone ecosystem.\n\n## Packages\n\n### 🏷️ Cost Package\n**Add pricing support for LLM models and providers**\n\nThe cost package handles pricing calculations for all supported AI/ML providers in Helicone.\n\n**[📖 Click here to add cost support for new models →](./cost/README.md)**\n\nCommon tasks:\n- Add pricing for new models (GPT-5, Claude 4, etc.)\n- Add support for new providers \n- Update existing model pricing\n- Add cost types (images, audio, per-call fees)\n\n### 🗺️ LLM Mapper\nRequest/response mapping and transformation for different LLM providers.\n\n### 🔍 Filters  \nFiltering definitions and utilities for request/response data.\n\n### 💬 Prompts\nPrompt templates and management utilities.\n\n## Contributing\n\nEach package contains its own documentation. See individual README files for contribution guidelines.\n\n### Quick Links\n- **[Cost Package Documentation](./cost/README.md)** - Add model pricing support\n- **Test Directory** - Package tests in `__tests__/`\n\n## Development\n\n### Running Tests\n\nTests are located in `__tests__/` directory and use Jest:\n\n```bash\n# Run all package tests\nnpx jest\n\n# Run specific test file\nnpx jest __tests__/cost/registrySnapshots.test.ts\n\n# Update snapshots after intentional changes\nnpx jest -u\n\n# Run tests without cache (useful for debugging)\nnpx jest --no-cache\n```\n\n#### Key Test Files\n- `__tests__/cost/ensureOnlyOne.test.ts` - Validates no duplicate models and cost calculations\n- `__tests__/cost/registrySnapshots.test.ts` - Snapshot tests for model registry (pricing, coverage, configs)\n- `__tests__/llm-mapper/` - Tests for request/response mapping\n\n### Building\n\n```bash\n# Build packages\nnpm run build\n```\n","packages/tsconfig.json":"{\n  \"compilerOptions\": {\n    \"target\": \"es5\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": true,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"node\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [\n      {\n        \"name\": \"next\"\n      }\n    ],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\n    \"next-env.d.ts\",\n    \"**/*.ts\",\n    \"**/*.tsx\",\n    \".next/types/**/*.ts\",\n    \"../valhalla/jawn/src/utils/tryGetSize.ts\"\n  ],\n  \"exclude\": [\"node_modules\", \"codegen.ts\"]\n}\n",".cursor/rules/ai-gateway-docs.mdc":"---\ndescription: \nglobs: docs/ai-gateway/*\nalwaysApply: false\n---\n# AI Gateway Documentation Rules\n\nCritical rules to ensure documentation accuracy based on configuration changes.\n\n## Configuration Structure (BREAKING CHANGES)\n\n### 1. Cache Store Configuration\n\n```yaml\n# ✅ CORRECT - cache-store at top level\ncache-store:\n  type: \"in-memory\"\n\nrouters:\n  my-router:\n    cache:\n      directive: \"max-age=3600\"\n\n# ❌ WRONG - old structure\nrouters:\n  my-router:\n    cache:\n      store: in-memory\n      enabled: true\n```\n\n### 2. Helicone Configuration\n\n```yaml\n# ✅ CORRECT - separate fields\nhelicone:\n  authentication: true\n  observability: true\n\n# ❌ WRONG - old structure\nhelicone-observability:\n  enable-auth: true\n```\n\n## Required Dependencies\n\n### 3. Authentication Requirements\n\n- **Rate limiting requires authentication** (works per-API-key)\n- **Observability requires authentication** to function\n- Always add warning and link to `/ai-gateway/authentication`\n\n### 4. Model Names\n\n```yaml\n# ✅ CORRECT - provider prefix\n\"model\": \"openai/gpt-4o-mini\"\n\n# ❌ WRONG - no prefix\n\"model\": \"gpt-4o-mini\"\n```\n\n## Examples That Actually Work\n\n### 5. Code Examples\n\n- **Always include:** TypeScript, Python, cURL (no Node.js)\n- **Router URLs:** `http://localhost:8080/router/{name}/v1/chat/completions`\n- **API Keys:** Use `sk-placeholder` for local, real keys for public deployments\n\n### 6. Deprecated Patterns to Never Use\n\n- ❌ `cache.enabled: true/false`\n- ❌ `cache.store: in-memory`\n- ❌ `helicone-observability.enable-auth`\n- ❌ Model names without provider prefixes\n",".cursor/rules/docs-guide.mdc":"---\nglobs: docs/*\nalwaysApply: false\n---\n\n# Helicone Documentation Guide\n\nA streamlined guide for creating consistent, high-quality feature documentation.\n\n## Template Structure\n\nAll feature documentation must follow this exact structure:\n\n````markdown\n---\ntitle: \"[Feature Name]\"\nsidebarTitle: \"[Feature Name]\"\n---\n\nWhen [developer context/situation], [common pattern]. [Feature name] [solves this by doing X].\n\n## Why use [Feature Name]\n\n- **[Benefit 1]**: Specific, actionable benefit\n- **[Benefit 2]**: Another key advantage\n- **[Benefit 3]**: Third compelling reason\n\n## Quick Start\n\n<Steps>\n<Step title=\"[Action 1]\">\nDescription with code example.\n```language\n// Working code\n````\n\n</Step>\n</Steps>\n\n## Configuration Options\n\n### Basic Settings\n\n| Setting | Type     | Description  | Default     | Example     |\n| ------- | -------- | ------------ | ----------- | ----------- |\n| `name`  | `string` | What it does | `\"default\"` | `\"example\"` |\n\n### Advanced Settings\n\n| Setting    | Type     | Description    | Default | Example            |\n| ---------- | -------- | -------------- | ------- | ------------------ |\n| `advanced` | `object` | Complex config | `{}`    | `{\"key\": \"value\"}` |\n\n## Use Cases\n\n<Tabs>\n<Tab title=\"[Use Case 1]\">\nReal-world scenario description.\n\n<CodeGroup>\n```typescript Node.js\n// Complete working example\n```\n```python Python  \n# Same example in Python\n```\n</CodeGroup>\n</Tab>\n</Tabs>\n\n## Understanding [Feature Name]\n\n### [Core Concept]\n\nDeep explanation of key concepts developers need to understand.\n\n```typescript\n// ✅ Good example\n// Correct usage\n\n// ❌ Bad example\n// What not to do\n```\n\n## Related Features\n\n<CardGroup cols={2}>\n<Card title=\"[Feature]\" icon=\"icon-name\" href=\"/path\">\nHow they work together\n</Card>\n</CardGroup>\n```\n\n## Component Usage\n\n### Required Components\n\n**Steps** - For procedures:\n\n```markdown\n<Steps>\n  <Step title=\"Action\">Content and code</Step>\n</Steps>\n```\n\n**Tabs** - For use cases:\n\n```markdown\n<Tabs>\n  <Tab title=\"Scenario\">Content</Tab>\n</Tabs>\n```\n\n**CodeGroup** - Multiple languages:\n\n````markdown\n<CodeGroup>\n```typescript Node.js\n// Code\n````\n\n```python Python\n# Code\n```\n\n</CodeGroup>\n```\n\n**CardGroup** - Related features:\n\n```markdown\n<CardGroup cols={2}>\n  <Card title=\"Feature\" icon=\"icon\" href=\"/path\">Description</Card>\n</CardGroup>\n```\n\n## Content Standards\n\n### Writing Rules\n\n1. **Start with developer context**: \"When building X, you need Y\"\n2. **No generic introductions**: Avoid \"This page explains...\"\n3. **Exactly 3 benefits**: Specific and actionable\n4. **3-5 Quick Start steps**: Immediately actionable\n5. **Complete code examples**: Include imports and setup\n6. **Real-world use cases**: Focus on developer problems\n7. **Good vs bad examples**: Use ✅/❌ format\n\n### Code Requirements\n\n- **All examples must be tested** with real API calls\n- **Include necessary imports** and setup code\n- **Show error handling** for production use\n- **Use current syntax** and dependencies\n- **Provide complete context** - no partial snippets\n\n### Content Guidelines\n\n- **Remove UI-only sections** that don't add developer value\n- **Focus on implementation** not product features\n- **Use consistent terminology** throughout\n- **Include alt text** for all images\n- **Link related features** appropriately\n\n## Workflow\n\n### 1. Apply Template\n\n- Follow the structure exactly\n- Use required components properly\n- Focus on developer-first content\n- Remove unnecessary UI descriptions\n\n### 2. Validate Against Code\n\n- Verify all API endpoints exist\n- Check authentication requirements\n- Confirm configuration options and defaults\n- Find any undocumented features\n\n### 3. Test Examples\n\n- Create test scripts for all code examples\n- Use real API keys to verify functionality\n- Test error conditions and edge cases\n- Confirm dashboard integration works\n\n## Quality Checklist\n\nBefore publishing:\n\n- [ ] Follows template structure exactly\n- [ ] All code examples tested and working\n- [ ] API details verified against codebase\n- [ ] Uses proper Mintlify components\n- [ ] Includes complete, working examples\n- [ ] Focuses on developer use cases\n- [ ] Related features properly linked\n- [ ] No UI-only content without value\n\n## Common Mistakes\n\n**Avoid:**\n\n- Generic introductions (\"This feature allows...\")\n- Incomplete code examples missing imports\n- Untested code snippets\n- UI descriptions without developer value\n- Missing error handling\n- Outdated syntax or dependencies\n\n**Instead:**\n\n- Start with developer context\n- Provide complete, tested examples\n- Focus on implementation details\n- Show practical use cases\n- Include proper error handling\n- Keep examples current\n",".cursor/rules/helicone-style-guidelines.mdc":"---\ndescription: Helicone Style Guidelines\nglobs: \nalwaysApply: true\n---\n# Helicone Design System Guidelines\n\n## Core Principles\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n| Component | Size | Line Height | Weight | Usage |\n|-----|---|----|---|----|\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n```tsx\n/* Text Colors */\ntext-foreground              // Primary text\ntext-muted-foreground        // Secondary text\ntext-accent-foreground       // Accent text\n\n/* Background Colors */\nbg-background                // Page background\nbg-card                      // Card background\nbg-muted                     // Muted background\n\n/* Border Colors */\nborder-border                // Default borders\nborder-input                 // Form inputs\nring-ring                    // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n```tsx\n/* Light Mode */\nbg-primary                   // #0EA5E9 (sky-500)\ntext-primary-foreground      // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg-primary                   // #0284C7 (sky-600)\ntext-primary-foreground      // #083344 (sky-950)\n```\n\n### Background Colors\n```tsx\n/* Light Mode */\nbg-background                // #FFFFFF (white)\ntext-foreground              // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-background                // #020617 (slate-950)\ntext-foreground              // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n```tsx\n/* Light Mode */\nbg-accent                    // #F1F5F9 (slate-100)\ntext-accent-foreground       // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-accent                    // #1E293B (slate-800)\ntext-accent-foreground       // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n```tsx\n/* Light Mode */\nbg-card                      // #FFFFFF (white)\ntext-card-foreground         // #020617 (slate-950)\nbg-popover                   // #FFFFFF (white)\ntext-popover-foreground      // #020617 (slate-950)\nborder-border                // #E2E8F0 (slate-200)\nborder-input                 // #E2E8F0 (slate-200)\nring-ring                    // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-card                      // #020617 (slate-950)\ntext-card-foreground         // #F8FAFC (slate-50)\nbg-popover                   // #020617 (slate-950)\ntext-popover-foreground      // #F8FAFC (slate-50)\nborder-border                // #1E293B (slate-800)\nborder-input                 // #1E293B (slate-800)\nring-ring                    // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n```tsx\n/* Light Mode */\nbg-muted                     // #F1F5F9 (slate-100)\ntext-muted-foreground        // #64748B (slate-500)\nbg-secondary                 // #F1F5F9 (slate-100)\ntext-secondary-foreground    // #0F172A (slate-900)\nbg-destructive               // #DC2626 (red-600)\ntext-destructive-foreground  // #450A0A (red-950)\nbg-confirmative              // #16A34A (green-600)\ntext-confirmative-foreground // #052E16 (green-950)\n\n/* Dark Mode */\nbg-muted                     // #1E293B (slate-800)\ntext-muted-foreground        // #94A3B8 (slate-400)\nbg-secondary                 // #1E293B (slate-800)\ntext-secondary-foreground    // #F8FAFC (slate-50)\nbg-destructive               // #7F1D1D (red-900)\ntext-destructive-foreground  // #FEF2F2 (red-50)\nbg-confirmative              // #14532D (green-900)\ntext-confirmative-foreground // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n```tsx\n/* Light Mode */\nbg-sidebar-background        // #F8FAFC (slate-50)\ntext-sidebar-foreground      // #334155 (slate-700)\nborder-sidebar-border        // #E2E8F0 (slate-200)\nbg-sidebar-primary           // #0C4A6E (sky-900)\ntext-sidebar-primary-foreground // #F0F9FF (sky-50)\nbg-sidebar-accent            // #F1F5F9 (slate-100)\ntext-sidebar-accent-foreground // #0F172A (slate-900)\nring-sidebar-ring            // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg-sidebar-background        // #0F172A (slate-900)\ntext-sidebar-foreground      // #F1F5F9 (slate-100)\nborder-sidebar-border        // #1E293B (slate-800)\nbg-sidebar-primary           // #0369A1 (sky-700)\ntext-sidebar-primary-foreground // #FFFFFF (white)\nbg-sidebar-accent            // #1E293B (slate-800)\ntext-sidebar-accent-foreground // #F1F5F9 (slate-100)\nring-sidebar-ring            // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n```tsx\n/* Light Mode */\nbg-chart-1                   // #2A9D90\nbg-chart-2                   // #E76E50\nbg-chart-3                   // #274754\nbg-chart-4                   // #E8C468\nbg-chart-5                   // #F4A462\n\n/* Dark Mode */\nbg-chart-1                   // #2662D9\nbg-chart-2                   // #E23670\nbg-chart-3                   // #E88C30\nbg-chart-4                   // #AF57DB\nbg-chart-5                   // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>\n    Monitor and analyze your LLM usage\n  </Lead>\n  \n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n    \n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map(feature => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">\n      Last 30 days\n    </Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```",".cursor/rules/helicone-system-overview.mdc":"---\ndescription: \nglobs: \nalwaysApply: true\n---\n# Helicone System Architecture\n\n## Core Components\n\n1. **Frontend (Web)** - Next.js application\n   - Dashboard UI for visualization and management\n   - Located in `/web` directory\n\n2. **Proxy Workers** - Cloudflare Workers\n   - Intercept and process API calls to LLM providers\n   - Located in `/worker` directory\n   - Separate workers for OpenAI, Anthropic, and general API\n\n3. **Jawn Server** - Express.js + Tsoa backend\n   - Core business logic and data processing\n   - Located in `/valhalla/jawn` directory\n   - Handles authentication, logging, and analytics\n\n4. **Bifrost** - Landing page and blog application\n   - Marketing website and documentation\n   - Located in `/bifrost` directory\n\n5. **Databases**\n   - **PostgreSQL** (via Supabase): User data, organizations, API keys\n   - **ClickHouse**: High-performance analytics storage for request logs\n\n6. **Object Storage** - Minio/S3 compatible\n   - Stores large request/response payloads\n   - Enables efficient retrieval of historical data\n\n7. **Upstash** - Redis-compatible message queue\n   - Buffers requests between proxy and backend\n   - Ensures reliable delivery of logging data\n\n## Directory Structure\n\n```\n/helicone\n├── /web                 # Next.js frontend dashboard\n├── /worker              # Cloudflare Workers proxy\n│   ├── /src/routers     # API provider-specific routers\n│   └── /src/lib         # Shared utilities\n├── /valhalla\n│   └── /jawn            # Express.js backend server\n├── /bifrost             # Landing page and blog\n├── /sdk                 # Client SDKs\n│   ├── /typescript      # TypeScript SDK\n│   └── /python          # Python SDK\n```\n\n## Data Flow\n\n1. **Request Interception**:\n   - Client request → Helicone Proxy → LLM Provider\n   - Proxy adds tracking headers and applies features\n\n2. **Response Processing**:\n   - LLM Provider → Helicone Proxy → Client\n   - Proxy sends log data to Upstash queue\n\n3. **Log Processing**:\n   - Upstash queue → Jawn server\n   - Jawn processes and stores logs in databases\n\n4. **Data Storage**:\n   - Request metadata → PostgreSQL\n   - Analytics data → ClickHouse\n   - Large payloads → Object Storage\n\n5. **Analytics Processing**:\n   - Jawn server processes logs for insights\n   - Aggregates metrics for dashboard visualization\n\n## System Interactions\n\n- **Frontend ↔ Jawn**: REST API for dashboard data\n- **Proxy ↔ Upstash**: Asynchronous message queuing\n- **Upstash ↔ Jawn**: Reliable message delivery\n- **Jawn ↔ Databases**: Data storage and retrieval\n\n## Technical Implementation\n\n- **Frontend**: React, Next.js, Tailwind CSS\n- **Proxy**: Cloudflare Workers, TypeScript\n- **Backend**: Express.js, Tsoa, TypeScript\n- **Bifrost**: Next.js, React, TypeScript\n- **Databases**: PostgreSQL, ClickHouse\n- **Queue**: Upstash Redis\n\n## Key Files for Development\n\n- `/worker/src/index.ts`: Entry point for proxy workers\n- `/worker/src/routers/`: Provider-specific routing logic\n- `/valhalla/jawn/src/index.ts`: Backend server entry point\n- `/web/pages/`: Frontend dashboard components\n- `/bifrost/pages/`: Landing page and blog components",".cursor/rules/supabase.mdc":"---\ndescription: Supabase\nglobs: *.ts, *sql\nalwaysApply: false\n---\nDo not use the Supabase Client, instead use the Jawn Client and put all new endpoints in controllers.\nDon't use RLS policies, instead enable RLS for new tables and revoke privledges. Example:\n\n```\nalter table \"public\".\"org_rate_limits\" enable row level security;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom authenticated;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom anon;\n```",".cursor/rules/jawn.mdc":"---\ndescription: \nglobs: *.ts\nalwaysApply: false\n---\n# Helicone Jawn Controller and TanStack Query Integration\n\n## Controller Pattern\n- Jawn controllers (`valhalla/jawn/src/controllers/`) follow a RESTful design with standard HTTP methods\n- Controllers use decorators like `@Route`, `@Get`, `@Post`, etc. from TSOA\n- Controllers accept `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Required parameters should come before optional parameters in controller methods\n\n## Manager Pattern\n- Each controller has a corresponding manager (`valhalla/jawn/src/managers/`)\n- Managers extend `BaseManager` and handle database operations\n- Managers receive `authParams` from the controller request\n- Use `dbExecute` for database operations and wrap results in `Result<T, string>`\n\n## Frontend Hooks with TanStack Query\n- Use `useJawnClient()` to interact with Jawn controllers\n- Implement custom hooks with TanStack Query for data fetching and mutations\n- For GET requests:\n  ```typescript\n  const query = useQuery({\n    queryKey: ['resource', id],\n    queryFn: async () => {\n      const response = await jawn.GET('/v1/resource/{id}', {\n        params: { path: { id } }\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    }\n  });\n  ```\n\n- For mutations:\n  ```typescript\n  const mutation = useMutation({\n    mutationFn: async (input) => {\n      const response = await jawn.POST('/v1/resource', {\n        body: input\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    },\n    onSuccess: (data) => {\n      // Invalidate queries\n      queryClient.invalidateQueries({ queryKey: ['resource'] });\n    }\n  });\n  ```\n\n## Type Definitions\n- Define request and response interfaces in the controller file\n- Use proper typing with TanStack Query\n- Handle Jawn response structure properly with error checking\n\n## URL State Management\n- Use URL parameters for persisting filter state between pages\n- Update URL when filter changes with `useSearchParams` from Next.js\n\n## Database Schema\n- Tables follow snake_case naming\n- Use proper indexes for performance\n- Implement proper RLS policies for security\n- Create functions for specialized operations (e.g., incrementing versions)\n\n## Enhanced Filters Specifics\n- Filters support both simple queries and complex logical expressions\n- Filters can be persisted, shared, and reused\n- Support both legacy and enhanced filter systems for backward compatibility\n","packages/common/package.json":"{\n  \"name\": \"@helicone-package/common\",\n  \"types\": \"./\",\n  \"version\": \"1.0.0\"\n}\n","packages/cost/FLOWS.md":"# Cost Skill\n\nPath: `packages/cost/FLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/FLOWS.md)","packages/cost/README.md":"# cost Documentation\n\nPath: `packages/cost/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/README.md)","packages/cost/package.json":"# Cost Skill\n\nPath: `packages/cost/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/package.json)","packages/filters/package.json":"# Filters Skill\n\nPath: `packages/filters/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/filters/package.json)","packages/llm-mapper/README.md":"# llm-mapper Documentation\n\nPath: `packages/llm-mapper/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/README.md)","packages/llm-mapper/package.json":"# Llm-mapper Skill\n\nPath: `packages/llm-mapper/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/package.json)","packages/pricing/package.json":"# Pricing Skill\n\nPath: `packages/pricing/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/pricing/package.json)","packages/prompts/package.json":"# Prompts Skill\n\nPath: `packages/prompts/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/prompts/package.json)","packages/secrets/package.json":"# Secrets Skill\n\nPath: `packages/secrets/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/secrets/package.json)","examples/tools/python/README.md":"# python Documentation\n\nPath: `examples/tools/python/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/examples/tools/python/README.md)","packages/cost/models/AUTHORS_DATA_POPULATION.md":"# Models Skill\n\nPath: `packages/cost/models/AUTHORS_DATA_POPULATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/AUTHORS_DATA_POPULATION.md)","packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md":"# Authors Skill\n\nPath: `packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n  - valhalla/jawn/src/tsoa-build/\n  - web/lib/clients/jawnTypes/\n  - bifrost/lib/clients/jawnTypes/\n  - worker/supabase/database.types.ts\n  - web/db/database.types.ts\n  - helicone-cron/src/db/database.types.ts\n  - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put <NAME>`.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace <name> <cmd>`; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","isInternal":false,"tokens":798,"sizeBytes":2927},{"name":"package.json","path":"packages/common/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/common/package.json","title":"@helicone-package/common","category":"anthropic-skill","format":"json","content":"{\n  \"name\": \"@helicone-package/common\",\n  \"types\": \"./\",\n  \"version\": \"1.0.0\"\n}\n","frontmatter":{"name":"@helicone-package/common","types":"./","version":"1.0.0"},"isInternal":false,"tokens":29,"sizeBytes":80},{"name":"FLOWS.md","path":"packages/cost/FLOWS.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/FLOWS.md","title":"Cost Skill","category":"anthropic-skill","format":"markdown","content":"# Cost Skill\n\nPath: `packages/cost/FLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/FLOWS.md)","tokens":300,"sizeBytes":155},{"name":"AUTHORS_DATA_POPULATION.md","path":"packages/cost/models/AUTHORS_DATA_POPULATION.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/AUTHORS_DATA_POPULATION.md","title":"Models Skill","category":"anthropic-skill","format":"markdown","content":"# Models Skill\n\nPath: `packages/cost/models/AUTHORS_DATA_POPULATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/AUTHORS_DATA_POPULATION.md)","tokens":300,"sizeBytes":207},{"name":"OPENROUTER_ENDPOINT_GUIDE.md","path":"packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md","title":"Authors Skill","category":"anthropic-skill","format":"markdown","content":"# Authors Skill\n\nPath: `packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md)","tokens":300,"sizeBytes":228},{"name":"package.json","path":"packages/cost/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/package.json","title":"Cost Skill","category":"anthropic-skill","format":"json","content":"# Cost Skill\n\nPath: `packages/cost/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/package.json)","tokens":300,"sizeBytes":163},{"name":"package.json","path":"packages/filters/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/filters/package.json","title":"Filters Skill","category":"anthropic-skill","format":"json","content":"# Filters Skill\n\nPath: `packages/filters/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/filters/package.json)","tokens":300,"sizeBytes":172},{"name":"package.json","path":"packages/llm-mapper/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/package.json","title":"Llm-mapper Skill","category":"anthropic-skill","format":"json","content":"# Llm-mapper Skill\n\nPath: `packages/llm-mapper/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/package.json)","tokens":300,"sizeBytes":181},{"name":"package.json","path":"packages/pricing/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/pricing/package.json","title":"Pricing Skill","category":"anthropic-skill","format":"json","content":"# Pricing Skill\n\nPath: `packages/pricing/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/pricing/package.json)","tokens":300,"sizeBytes":172},{"name":"package.json","path":"packages/prompts/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/prompts/package.json","title":"Prompts Skill","category":"anthropic-skill","format":"json","content":"# Prompts Skill\n\nPath: `packages/prompts/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/prompts/package.json)","tokens":300,"sizeBytes":172},{"name":"package.json","path":"packages/secrets/package.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/secrets/package.json","title":"Secrets Skill","category":"anthropic-skill","format":"json","content":"# Secrets Skill\n\nPath: `packages/secrets/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/secrets/package.json)","tokens":300,"sizeBytes":172},{"name":"tsconfig.json","path":"packages/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/tsconfig.json","title":"Packages Skill","category":"anthropic-skill","format":"json","content":"{\n  \"compilerOptions\": {\n    \"target\": \"es5\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": true,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"node\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [\n      {\n        \"name\": \"next\"\n      }\n    ],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\n    \"next-env.d.ts\",\n    \"**/*.ts\",\n    \"**/*.tsx\",\n    \".next/types/**/*.ts\",\n    \"../valhalla/jawn/src/utils/tryGetSize.ts\"\n  ],\n  \"exclude\": [\"node_modules\", \"codegen.ts\"]\n}\n","frontmatter":{"compilerOptions":{"target":"es5","lib":["dom","dom.iterable","esnext"],"allowJs":true,"skipLibCheck":true,"strict":true,"forceConsistentCasingInFileNames":true,"noEmit":true,"esModuleInterop":true,"module":"esnext","moduleResolution":"node","resolveJsonModule":true,"isolatedModules":true,"jsx":"preserve","incremental":true,"plugins":[{"name":"next"}],"baseUrl":".","paths":{"@/*":["./*"]}},"include":["next-env.d.ts","**/*.ts","**/*.tsx",".next/types/**/*.ts","../valhalla/jawn/src/utils/tryGetSize.ts"],"exclude":["node_modules","codegen.ts"]},"isInternal":false,"tokens":225,"sizeBytes":740},{"name":"ai-gateway-docs.mdc","path":".cursor/rules/ai-gateway-docs.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/ai-gateway-docs.mdc","title":"Cursor Rule: ai-gateway-docs","category":"cursor-rule","format":"mdc","content":"---\ndescription: \nglobs: docs/ai-gateway/*\nalwaysApply: false\n---\n# AI Gateway Documentation Rules\n\nCritical rules to ensure documentation accuracy based on configuration changes.\n\n## Configuration Structure (BREAKING CHANGES)\n\n### 1. Cache Store Configuration\n\n```yaml\n# ✅ CORRECT - cache-store at top level\ncache-store:\n  type: \"in-memory\"\n\nrouters:\n  my-router:\n    cache:\n      directive: \"max-age=3600\"\n\n# ❌ WRONG - old structure\nrouters:\n  my-router:\n    cache:\n      store: in-memory\n      enabled: true\n```\n\n### 2. Helicone Configuration\n\n```yaml\n# ✅ CORRECT - separate fields\nhelicone:\n  authentication: true\n  observability: true\n\n# ❌ WRONG - old structure\nhelicone-observability:\n  enable-auth: true\n```\n\n## Required Dependencies\n\n### 3. Authentication Requirements\n\n- **Rate limiting requires authentication** (works per-API-key)\n- **Observability requires authentication** to function\n- Always add warning and link to `/ai-gateway/authentication`\n\n### 4. Model Names\n\n```yaml\n# ✅ CORRECT - provider prefix\n\"model\": \"openai/gpt-4o-mini\"\n\n# ❌ WRONG - no prefix\n\"model\": \"gpt-4o-mini\"\n```\n\n## Examples That Actually Work\n\n### 5. Code Examples\n\n- **Always include:** TypeScript, Python, cURL (no Node.js)\n- **Router URLs:** `http://localhost:8080/router/{name}/v1/chat/completions`\n- **API Keys:** Use `sk-placeholder` for local, real keys for public deployments\n\n### 6. Deprecated Patterns to Never Use\n\n- ❌ `cache.enabled: true/false`\n- ❌ `cache.store: in-memory`\n- ❌ `helicone-observability.enable-auth`\n- ❌ Model names without provider prefixes\n","frontmatter":{"description":null,"globs":"docs/ai-gateway/*","alwaysApply":false},"isInternal":false,"tokens":407,"sizeBytes":1578},{"name":"docs-guide.mdc","path":".cursor/rules/docs-guide.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/docs-guide.mdc","title":"Cursor Rule: docs-guide","category":"cursor-rule","format":"mdc","content":"---\nglobs: docs/*\nalwaysApply: false\n---\n\n# Helicone Documentation Guide\n\nA streamlined guide for creating consistent, high-quality feature documentation.\n\n## Template Structure\n\nAll feature documentation must follow this exact structure:\n\n````markdown\n---\ntitle: \"[Feature Name]\"\nsidebarTitle: \"[Feature Name]\"\n---\n\nWhen [developer context/situation], [common pattern]. [Feature name] [solves this by doing X].\n\n## Why use [Feature Name]\n\n- **[Benefit 1]**: Specific, actionable benefit\n- **[Benefit 2]**: Another key advantage\n- **[Benefit 3]**: Third compelling reason\n\n## Quick Start\n\n<Steps>\n<Step title=\"[Action 1]\">\nDescription with code example.\n```language\n// Working code\n````\n\n</Step>\n</Steps>\n\n## Configuration Options\n\n### Basic Settings\n\n| Setting | Type     | Description  | Default     | Example     |\n| ------- | -------- | ------------ | ----------- | ----------- |\n| `name`  | `string` | What it does | `\"default\"` | `\"example\"` |\n\n### Advanced Settings\n\n| Setting    | Type     | Description    | Default | Example            |\n| ---------- | -------- | -------------- | ------- | ------------------ |\n| `advanced` | `object` | Complex config | `{}`    | `{\"key\": \"value\"}` |\n\n## Use Cases\n\n<Tabs>\n<Tab title=\"[Use Case 1]\">\nReal-world scenario description.\n\n<CodeGroup>\n```typescript Node.js\n// Complete working example\n```\n```python Python  \n# Same example in Python\n```\n</CodeGroup>\n</Tab>\n</Tabs>\n\n## Understanding [Feature Name]\n\n### [Core Concept]\n\nDeep explanation of key concepts developers need to understand.\n\n```typescript\n// ✅ Good example\n// Correct usage\n\n// ❌ Bad example\n// What not to do\n```\n\n## Related Features\n\n<CardGroup cols={2}>\n<Card title=\"[Feature]\" icon=\"icon-name\" href=\"/path\">\nHow they work together\n</Card>\n</CardGroup>\n```\n\n## Component Usage\n\n### Required Components\n\n**Steps** - For procedures:\n\n```markdown\n<Steps>\n  <Step title=\"Action\">Content and code</Step>\n</Steps>\n```\n\n**Tabs** - For use cases:\n\n```markdown\n<Tabs>\n  <Tab title=\"Scenario\">Content</Tab>\n</Tabs>\n```\n\n**CodeGroup** - Multiple languages:\n\n````markdown\n<CodeGroup>\n```typescript Node.js\n// Code\n````\n\n```python Python\n# Code\n```\n\n</CodeGroup>\n```\n\n**CardGroup** - Related features:\n\n```markdown\n<CardGroup cols={2}>\n  <Card title=\"Feature\" icon=\"icon\" href=\"/path\">Description</Card>\n</CardGroup>\n```\n\n## Content Standards\n\n### Writing Rules\n\n1. **Start with developer context**: \"When building X, you need Y\"\n2. **No generic introductions**: Avoid \"This page explains...\"\n3. **Exactly 3 benefits**: Specific and actionable\n4. **3-5 Quick Start steps**: Immediately actionable\n5. **Complete code examples**: Include imports and setup\n6. **Real-world use cases**: Focus on developer problems\n7. **Good vs bad examples**: Use ✅/❌ format\n\n### Code Requirements\n\n- **All examples must be tested** with real API calls\n- **Include necessary imports** and setup code\n- **Show error handling** for production use\n- **Use current syntax** and dependencies\n- **Provide complete context** - no partial snippets\n\n### Content Guidelines\n\n- **Remove UI-only sections** that don't add developer value\n- **Focus on implementation** not product features\n- **Use consistent terminology** throughout\n- **Include alt text** for all images\n- **Link related features** appropriately\n\n## Workflow\n\n### 1. Apply Template\n\n- Follow the structure exactly\n- Use required components properly\n- Focus on developer-first content\n- Remove unnecessary UI descriptions\n\n### 2. Validate Against Code\n\n- Verify all API endpoints exist\n- Check authentication requirements\n- Confirm configuration options and defaults\n- Find any undocumented features\n\n### 3. Test Examples\n\n- Create test scripts for all code examples\n- Use real API keys to verify functionality\n- Test error conditions and edge cases\n- Confirm dashboard integration works\n\n## Quality Checklist\n\nBefore publishing:\n\n- [ ] Follows template structure exactly\n- [ ] All code examples tested and working\n- [ ] API details verified against codebase\n- [ ] Uses proper Mintlify components\n- [ ] Includes complete, working examples\n- [ ] Focuses on developer use cases\n- [ ] Related features properly linked\n- [ ] No UI-only content without value\n\n## Common Mistakes\n\n**Avoid:**\n\n- Generic introductions (\"This feature allows...\")\n- Incomplete code examples missing imports\n- Untested code snippets\n- UI descriptions without developer value\n- Missing error handling\n- Outdated syntax or dependencies\n\n**Instead:**\n\n- Start with developer context\n- Provide complete, tested examples\n- Focus on implementation details\n- Show practical use cases\n- Include proper error handling\n- Keep examples current\n","frontmatter":{"globs":"docs/*","alwaysApply":false},"isInternal":false,"tokens":1078,"sizeBytes":4653},{"name":"helicone-style-guidelines.mdc","path":".cursor/rules/helicone-style-guidelines.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/helicone-style-guidelines.mdc","title":"Cursor Rule: helicone-style-guidelines","category":"cursor-rule","format":"mdc","content":"---\ndescription: Helicone Style Guidelines\nglobs: \nalwaysApply: true\n---\n# Helicone Design System Guidelines\n\n## Core Principles\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n| Component | Size | Line Height | Weight | Usage |\n|-----|---|----|---|----|\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n```tsx\n/* Text Colors */\ntext-foreground              // Primary text\ntext-muted-foreground        // Secondary text\ntext-accent-foreground       // Accent text\n\n/* Background Colors */\nbg-background                // Page background\nbg-card                      // Card background\nbg-muted                     // Muted background\n\n/* Border Colors */\nborder-border                // Default borders\nborder-input                 // Form inputs\nring-ring                    // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n```tsx\n/* Light Mode */\nbg-primary                   // #0EA5E9 (sky-500)\ntext-primary-foreground      // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg-primary                   // #0284C7 (sky-600)\ntext-primary-foreground      // #083344 (sky-950)\n```\n\n### Background Colors\n```tsx\n/* Light Mode */\nbg-background                // #FFFFFF (white)\ntext-foreground              // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-background                // #020617 (slate-950)\ntext-foreground              // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n```tsx\n/* Light Mode */\nbg-accent                    // #F1F5F9 (slate-100)\ntext-accent-foreground       // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-accent                    // #1E293B (slate-800)\ntext-accent-foreground       // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n```tsx\n/* Light Mode */\nbg-card                      // #FFFFFF (white)\ntext-card-foreground         // #020617 (slate-950)\nbg-popover                   // #FFFFFF (white)\ntext-popover-foreground      // #020617 (slate-950)\nborder-border                // #E2E8F0 (slate-200)\nborder-input                 // #E2E8F0 (slate-200)\nring-ring                    // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-card                      // #020617 (slate-950)\ntext-card-foreground         // #F8FAFC (slate-50)\nbg-popover                   // #020617 (slate-950)\ntext-popover-foreground      // #F8FAFC (slate-50)\nborder-border                // #1E293B (slate-800)\nborder-input                 // #1E293B (slate-800)\nring-ring                    // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n```tsx\n/* Light Mode */\nbg-muted                     // #F1F5F9 (slate-100)\ntext-muted-foreground        // #64748B (slate-500)\nbg-secondary                 // #F1F5F9 (slate-100)\ntext-secondary-foreground    // #0F172A (slate-900)\nbg-destructive               // #DC2626 (red-600)\ntext-destructive-foreground  // #450A0A (red-950)\nbg-confirmative              // #16A34A (green-600)\ntext-confirmative-foreground // #052E16 (green-950)\n\n/* Dark Mode */\nbg-muted                     // #1E293B (slate-800)\ntext-muted-foreground        // #94A3B8 (slate-400)\nbg-secondary                 // #1E293B (slate-800)\ntext-secondary-foreground    // #F8FAFC (slate-50)\nbg-destructive               // #7F1D1D (red-900)\ntext-destructive-foreground  // #FEF2F2 (red-50)\nbg-confirmative              // #14532D (green-900)\ntext-confirmative-foreground // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n```tsx\n/* Light Mode */\nbg-sidebar-background        // #F8FAFC (slate-50)\ntext-sidebar-foreground      // #334155 (slate-700)\nborder-sidebar-border        // #E2E8F0 (slate-200)\nbg-sidebar-primary           // #0C4A6E (sky-900)\ntext-sidebar-primary-foreground // #F0F9FF (sky-50)\nbg-sidebar-accent            // #F1F5F9 (slate-100)\ntext-sidebar-accent-foreground // #0F172A (slate-900)\nring-sidebar-ring            // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg-sidebar-background        // #0F172A (slate-900)\ntext-sidebar-foreground      // #F1F5F9 (slate-100)\nborder-sidebar-border        // #1E293B (slate-800)\nbg-sidebar-primary           // #0369A1 (sky-700)\ntext-sidebar-primary-foreground // #FFFFFF (white)\nbg-sidebar-accent            // #1E293B (slate-800)\ntext-sidebar-accent-foreground // #F1F5F9 (slate-100)\nring-sidebar-ring            // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n```tsx\n/* Light Mode */\nbg-chart-1                   // #2A9D90\nbg-chart-2                   // #E76E50\nbg-chart-3                   // #274754\nbg-chart-4                   // #E8C468\nbg-chart-5                   // #F4A462\n\n/* Dark Mode */\nbg-chart-1                   // #2662D9\nbg-chart-2                   // #E23670\nbg-chart-3                   // #E88C30\nbg-chart-4                   // #AF57DB\nbg-chart-5                   // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>\n    Monitor and analyze your LLM usage\n  </Lead>\n  \n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n    \n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map(feature => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">\n      Last 30 days\n    </Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```","frontmatter":{"description":"Helicone Style Guidelines","globs":null,"alwaysApply":true},"isInternal":false,"tokens":3018,"sizeBytes":10460},{"name":"helicone-system-overview.mdc","path":".cursor/rules/helicone-system-overview.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/helicone-system-overview.mdc","title":"Cursor Rule: helicone-system-overview","category":"cursor-rule","format":"mdc","content":"---\ndescription: \nglobs: \nalwaysApply: true\n---\n# Helicone System Architecture\n\n## Core Components\n\n1. **Frontend (Web)** - Next.js application\n   - Dashboard UI for visualization and management\n   - Located in `/web` directory\n\n2. **Proxy Workers** - Cloudflare Workers\n   - Intercept and process API calls to LLM providers\n   - Located in `/worker` directory\n   - Separate workers for OpenAI, Anthropic, and general API\n\n3. **Jawn Server** - Express.js + Tsoa backend\n   - Core business logic and data processing\n   - Located in `/valhalla/jawn` directory\n   - Handles authentication, logging, and analytics\n\n4. **Bifrost** - Landing page and blog application\n   - Marketing website and documentation\n   - Located in `/bifrost` directory\n\n5. **Databases**\n   - **PostgreSQL** (via Supabase): User data, organizations, API keys\n   - **ClickHouse**: High-performance analytics storage for request logs\n\n6. **Object Storage** - Minio/S3 compatible\n   - Stores large request/response payloads\n   - Enables efficient retrieval of historical data\n\n7. **Upstash** - Redis-compatible message queue\n   - Buffers requests between proxy and backend\n   - Ensures reliable delivery of logging data\n\n## Directory Structure\n\n```\n/helicone\n├── /web                 # Next.js frontend dashboard\n├── /worker              # Cloudflare Workers proxy\n│   ├── /src/routers     # API provider-specific routers\n│   └── /src/lib         # Shared utilities\n├── /valhalla\n│   └── /jawn            # Express.js backend server\n├── /bifrost             # Landing page and blog\n├── /sdk                 # Client SDKs\n│   ├── /typescript      # TypeScript SDK\n│   └── /python          # Python SDK\n```\n\n## Data Flow\n\n1. **Request Interception**:\n   - Client request → Helicone Proxy → LLM Provider\n   - Proxy adds tracking headers and applies features\n\n2. **Response Processing**:\n   - LLM Provider → Helicone Proxy → Client\n   - Proxy sends log data to Upstash queue\n\n3. **Log Processing**:\n   - Upstash queue → Jawn server\n   - Jawn processes and stores logs in databases\n\n4. **Data Storage**:\n   - Request metadata → PostgreSQL\n   - Analytics data → ClickHouse\n   - Large payloads → Object Storage\n\n5. **Analytics Processing**:\n   - Jawn server processes logs for insights\n   - Aggregates metrics for dashboard visualization\n\n## System Interactions\n\n- **Frontend ↔ Jawn**: REST API for dashboard data\n- **Proxy ↔ Upstash**: Asynchronous message queuing\n- **Upstash ↔ Jawn**: Reliable message delivery\n- **Jawn ↔ Databases**: Data storage and retrieval\n\n## Technical Implementation\n\n- **Frontend**: React, Next.js, Tailwind CSS\n- **Proxy**: Cloudflare Workers, TypeScript\n- **Backend**: Express.js, Tsoa, TypeScript\n- **Bifrost**: Next.js, React, TypeScript\n- **Databases**: PostgreSQL, ClickHouse\n- **Queue**: Upstash Redis\n\n## Key Files for Development\n\n- `/worker/src/index.ts`: Entry point for proxy workers\n- `/worker/src/routers/`: Provider-specific routing logic\n- `/valhalla/jawn/src/index.ts`: Backend server entry point\n- `/web/pages/`: Frontend dashboard components\n- `/bifrost/pages/`: Landing page and blog components","frontmatter":{"description":null,"globs":null,"alwaysApply":true},"isInternal":false,"tokens":768,"sizeBytes":3196},{"name":"jawn.mdc","path":".cursor/rules/jawn.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/jawn.mdc","title":"Cursor Rule: jawn","category":"cursor-rule","format":"mdc","content":"---\ndescription: \nglobs: *.ts\nalwaysApply: false\n---\n# Helicone Jawn Controller and TanStack Query Integration\n\n## Controller Pattern\n- Jawn controllers (`valhalla/jawn/src/controllers/`) follow a RESTful design with standard HTTP methods\n- Controllers use decorators like `@Route`, `@Get`, `@Post`, etc. from TSOA\n- Controllers accept `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Required parameters should come before optional parameters in controller methods\n\n## Manager Pattern\n- Each controller has a corresponding manager (`valhalla/jawn/src/managers/`)\n- Managers extend `BaseManager` and handle database operations\n- Managers receive `authParams` from the controller request\n- Use `dbExecute` for database operations and wrap results in `Result<T, string>`\n\n## Frontend Hooks with TanStack Query\n- Use `useJawnClient()` to interact with Jawn controllers\n- Implement custom hooks with TanStack Query for data fetching and mutations\n- For GET requests:\n  ```typescript\n  const query = useQuery({\n    queryKey: ['resource', id],\n    queryFn: async () => {\n      const response = await jawn.GET('/v1/resource/{id}', {\n        params: { path: { id } }\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    }\n  });\n  ```\n\n- For mutations:\n  ```typescript\n  const mutation = useMutation({\n    mutationFn: async (input) => {\n      const response = await jawn.POST('/v1/resource', {\n        body: input\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    },\n    onSuccess: (data) => {\n      // Invalidate queries\n      queryClient.invalidateQueries({ queryKey: ['resource'] });\n    }\n  });\n  ```\n\n## Type Definitions\n- Define request and response interfaces in the controller file\n- Use proper typing with TanStack Query\n- Handle Jawn response structure properly with error checking\n\n## URL State Management\n- Use URL parameters for persisting filter state between pages\n- Update URL when filter changes with `useSearchParams` from Next.js\n\n## Database Schema\n- Tables follow snake_case naming\n- Use proper indexes for performance\n- Implement proper RLS policies for security\n- Create functions for specialized operations (e.g., incrementing versions)\n\n## Enhanced Filters Specifics\n- Filters support both simple queries and complex logical expressions\n- Filters can be persisted, shared, and reused\n- Support both legacy and enhanced filter systems for backward compatibility\n","isInternal":false,"tokens":540,"sizeBytes":2465},{"name":"supabase.mdc","path":".cursor/rules/supabase.mdc","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/.cursor/rules/supabase.mdc","title":"Cursor Rule: supabase","category":"cursor-rule","format":"mdc","content":"---\ndescription: Supabase\nglobs: *.ts, *sql\nalwaysApply: false\n---\nDo not use the Supabase Client, instead use the Jawn Client and put all new endpoints in controllers.\nDon't use RLS policies, instead enable RLS for new tables and revoke privledges. Example:\n\n```\nalter table \"public\".\"org_rate_limits\" enable row level security;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom authenticated;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom anon;\n```","isInternal":false,"tokens":118,"sizeBytes":468},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth          # With better-auth\ncd web && yarn dev:local               # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n<div className=\"flex flex-col gap-4\">\n<div className=\"flex items-center gap-2\">\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/                   # Next.js frontend\n/valhalla/jawn/        # Express.js backend\n/worker/               # Cloudflare Workers\n/aigateway/            # Rust LLM proxy\n/bifrost/              # Marketing site\n/packages/             # Shared packages\n  ├── cost/            # Cost calculations\n  ├── llm-mapper/      # Provider mappings\n  └── prompts/         # Prompt management\n/supabase/             # Database migrations\n/clickhouse/           # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n   ```bash\n   grep -r \"thinkingLevel\" packages/  # Find all usages of similar type\n   ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n\n| Component | Size                                 | Line Height       | Weight    | Usage              |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1        | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold  | Main page titles   |\n| H1Large   | text-5xl (48px)                      | leading-10 (40px) | extrabold | Hero sections      |\n| H2        | text-3xl (30px)                      | leading-9 (36px)  | semibold  | Section headers    |\n| H3        | text-2xl (24px)                      | leading-8 (32px)  | semibold  | Subsection headers |\n| H4        | text-xl (20px)                       | leading-7 (28px)  | semibold  | Card titles        |\n| Lead      | text-xl (20px)                       | leading-7 (28px)  | normal    | Introduction text  |\n| P         | text-base (16px)                     | leading-7 (28px)  | normal    | Body text          |\n| Small     | text-sm (14px)                       | leading-4 (16px)  | medium    | Helper text        |\n| Muted     | text-sm (14px)                       | leading-none      | normal    | Secondary text     |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>Monitor and analyze your LLM usage</Lead>\n\n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n\n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map((feature) => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">Last 30 days</Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```\n","isInternal":false,"tokens":4481,"sizeBytes":15737},{"name":"README.md","path":"examples/tools/python/README.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/examples/tools/python/README.md","title":"python Documentation","category":"plugin-manifest","format":"markdown","content":"# python Documentation\n\nPath: `examples/tools/python/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/examples/tools/python/README.md)","tokens":300,"sizeBytes":183},{"name":"README.md","path":"packages/cost/README.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/README.md","title":"cost Documentation","category":"plugin-manifest","format":"markdown","content":"# cost Documentation\n\nPath: `packages/cost/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/README.md)","tokens":300,"sizeBytes":165},{"name":"README.md","path":"packages/llm-mapper/README.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/README.md","title":"llm-mapper Documentation","category":"plugin-manifest","format":"markdown","content":"# llm-mapper Documentation\n\nPath: `packages/llm-mapper/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/README.md)","tokens":300,"sizeBytes":183},{"name":"README.md","path":"packages/README.md","rawUrl":"https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/README.md","title":"packages Documentation","category":"plugin-manifest","format":"markdown","content":"# Common issues\n\nIf you are using OpenAI you might need to include stream usage options: https://docs.helicone.ai/faq/enable-stream-usage\n\n\n\n# Helicone Packages\n\nThis directory contains shared packages used across the Helicone ecosystem.\n\n## Packages\n\n### 🏷️ Cost Package\n**Add pricing support for LLM models and providers**\n\nThe cost package handles pricing calculations for all supported AI/ML providers in Helicone.\n\n**[📖 Click here to add cost support for new models →](./cost/README.md)**\n\nCommon tasks:\n- Add pricing for new models (GPT-5, Claude 4, etc.)\n- Add support for new providers \n- Update existing model pricing\n- Add cost types (images, audio, per-call fees)\n\n### 🗺️ LLM Mapper\nRequest/response mapping and transformation for different LLM providers.\n\n### 🔍 Filters  \nFiltering definitions and utilities for request/response data.\n\n### 💬 Prompts\nPrompt templates and management utilities.\n\n## Contributing\n\nEach package contains its own documentation. See individual README files for contribution guidelines.\n\n### Quick Links\n- **[Cost Package Documentation](./cost/README.md)** - Add model pricing support\n- **Test Directory** - Package tests in `__tests__/`\n\n## Development\n\n### Running Tests\n\nTests are located in `__tests__/` directory and use Jest:\n\n```bash\n# Run all package tests\nnpx jest\n\n# Run specific test file\nnpx jest __tests__/cost/registrySnapshots.test.ts\n\n# Update snapshots after intentional changes\nnpx jest -u\n\n# Run tests without cache (useful for debugging)\nnpx jest --no-cache\n```\n\n#### Key Test Files\n- `__tests__/cost/ensureOnlyOne.test.ts` - Validates no duplicate models and cost calculations\n- `__tests__/cost/registrySnapshots.test.ts` - Snapshot tests for model registry (pricing, coverage, configs)\n- `__tests__/llm-mapper/` - Tests for request/response mapping\n\n### Building\n\n```bash\n# Build packages\nnpm run build\n```\n","isInternal":false,"tokens":437,"sizeBytes":1888}],"systemPromptSnippet":"<yakaai_skills repo=\"Helicone/helicone\">\n<!-- File: AGENTS.md (Tokens: ~798 | Category: root-instruction) -->\n# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n  - valhalla/jawn/src/tsoa-build/\n  - web/lib/clients/jawnTypes/\n  - bifrost/lib/clients/jawnTypes/\n  - worker/supabase/database.types.ts\n  - web/db/database.types.ts\n  - helicone-cron/src/db/database.types.ts\n  - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put <NAME>`.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace <name> <cmd>`; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n\n<!-- File: packages/common/package.json (Tokens: ~29 | Category: anthropic-skill) -->\n{\n  \"name\": \"@helicone-package/common\",\n  \"types\": \"./\",\n  \"version\": \"1.0.0\"\n}\n\n<!-- File: packages/cost/FLOWS.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Cost Skill\n\nPath: `packages/cost/FLOWS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/FLOWS.md)\n\n<!-- File: packages/cost/models/AUTHORS_DATA_POPULATION.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Models Skill\n\nPath: `packages/cost/models/AUTHORS_DATA_POPULATION.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/AUTHORS_DATA_POPULATION.md)\n\n<!-- File: packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Authors Skill\n\nPath: `packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/models/authors/OPENROUTER_ENDPOINT_GUIDE.md)\n\n<!-- File: packages/cost/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Cost Skill\n\nPath: `packages/cost/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/package.json)\n\n<!-- File: packages/filters/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Filters Skill\n\nPath: `packages/filters/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/filters/package.json)\n\n<!-- File: packages/llm-mapper/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Llm-mapper Skill\n\nPath: `packages/llm-mapper/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/package.json)\n\n<!-- File: packages/pricing/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Pricing Skill\n\nPath: `packages/pricing/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/pricing/package.json)\n\n<!-- File: packages/prompts/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Prompts Skill\n\nPath: `packages/prompts/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/prompts/package.json)\n\n<!-- File: packages/secrets/package.json (Tokens: ~300 | Category: anthropic-skill) -->\n# Secrets Skill\n\nPath: `packages/secrets/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/secrets/package.json)\n\n<!-- File: packages/tsconfig.json (Tokens: ~225 | Category: anthropic-skill) -->\n{\n  \"compilerOptions\": {\n    \"target\": \"es5\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": true,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"node\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [\n      {\n        \"name\": \"next\"\n      }\n    ],\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\n    \"next-env.d.ts\",\n    \"**/*.ts\",\n    \"**/*.tsx\",\n    \".next/types/**/*.ts\",\n    \"../valhalla/jawn/src/utils/tryGetSize.ts\"\n  ],\n  \"exclude\": [\"node_modules\", \"codegen.ts\"]\n}\n\n<!-- File: .cursor/rules/ai-gateway-docs.mdc (Tokens: ~407 | Category: cursor-rule) -->\n---\ndescription: \nglobs: docs/ai-gateway/*\nalwaysApply: false\n---\n# AI Gateway Documentation Rules\n\nCritical rules to ensure documentation accuracy based on configuration changes.\n\n## Configuration Structure (BREAKING CHANGES)\n\n### 1. Cache Store Configuration\n\n```yaml\n# ✅ CORRECT - cache-store at top level\ncache-store:\n  type: \"in-memory\"\n\nrouters:\n  my-router:\n    cache:\n      directive: \"max-age=3600\"\n\n# ❌ WRONG - old structure\nrouters:\n  my-router:\n    cache:\n      store: in-memory\n      enabled: true\n```\n\n### 2. Helicone Configuration\n\n```yaml\n# ✅ CORRECT - separate fields\nhelicone:\n  authentication: true\n  observability: true\n\n# ❌ WRONG - old structure\nhelicone-observability:\n  enable-auth: true\n```\n\n## Required Dependencies\n\n### 3. Authentication Requirements\n\n- **Rate limiting requires authentication** (works per-API-key)\n- **Observability requires authentication** to function\n- Always add warning and link to `/ai-gateway/authentication`\n\n### 4. Model Names\n\n```yaml\n# ✅ CORRECT - provider prefix\n\"model\": \"openai/gpt-4o-mini\"\n\n# ❌ WRONG - no prefix\n\"model\": \"gpt-4o-mini\"\n```\n\n## Examples That Actually Work\n\n### 5. Code Examples\n\n- **Always include:** TypeScript, Python, cURL (no Node.js)\n- **Router URLs:** `http://localhost:8080/router/{name}/v1/chat/completions`\n- **API Keys:** Use `sk-placeholder` for local, real keys for public deployments\n\n### 6. Deprecated Patterns to Never Use\n\n- ❌ `cache.enabled: true/false`\n- ❌ `cache.store: in-memory`\n- ❌ `helicone-observability.enable-auth`\n- ❌ Model names without provider prefixes\n\n<!-- File: .cursor/rules/docs-guide.mdc (Tokens: ~1078 | Category: cursor-rule) -->\n---\nglobs: docs/*\nalwaysApply: false\n---\n\n# Helicone Documentation Guide\n\nA streamlined guide for creating consistent, high-quality feature documentation.\n\n## Template Structure\n\nAll feature documentation must follow this exact structure:\n\n````markdown\n---\ntitle: \"[Feature Name]\"\nsidebarTitle: \"[Feature Name]\"\n---\n\nWhen [developer context/situation], [common pattern]. [Feature name] [solves this by doing X].\n\n## Why use [Feature Name]\n\n- **[Benefit 1]**: Specific, actionable benefit\n- **[Benefit 2]**: Another key advantage\n- **[Benefit 3]**: Third compelling reason\n\n## Quick Start\n\n<Steps>\n<Step title=\"[Action 1]\">\nDescription with code example.\n```language\n// Working code\n````\n\n</Step>\n</Steps>\n\n## Configuration Options\n\n### Basic Settings\n\n| Setting | Type     | Description  | Default     | Example     |\n| ------- | -------- | ------------ | ----------- | ----------- |\n| `name`  | `string` | What it does | `\"default\"` | `\"example\"` |\n\n### Advanced Settings\n\n| Setting    | Type     | Description    | Default | Example            |\n| ---------- | -------- | -------------- | ------- | ------------------ |\n| `advanced` | `object` | Complex config | `{}`    | `{\"key\": \"value\"}` |\n\n## Use Cases\n\n<Tabs>\n<Tab title=\"[Use Case 1]\">\nReal-world scenario description.\n\n<CodeGroup>\n```typescript Node.js\n// Complete working example\n```\n```python Python  \n# Same example in Python\n```\n</CodeGroup>\n</Tab>\n</Tabs>\n\n## Understanding [Feature Name]\n\n### [Core Concept]\n\nDeep explanation of key concepts developers need to understand.\n\n```typescript\n// ✅ Good example\n// Correct usage\n\n// ❌ Bad example\n// What not to do\n```\n\n## Related Features\n\n<CardGroup cols={2}>\n<Card title=\"[Feature]\" icon=\"icon-name\" href=\"/path\">\nHow they work together\n</Card>\n</CardGroup>\n```\n\n## Component Usage\n\n### Required Components\n\n**Steps** - For procedures:\n\n```markdown\n<Steps>\n  <Step title=\"Action\">Content and code</Step>\n</Steps>\n```\n\n**Tabs** - For use cases:\n\n```markdown\n<Tabs>\n  <Tab title=\"Scenario\">Content</Tab>\n</Tabs>\n```\n\n**CodeGroup** - Multiple languages:\n\n````markdown\n<CodeGroup>\n```typescript Node.js\n// Code\n````\n\n```python Python\n# Code\n```\n\n</CodeGroup>\n```\n\n**CardGroup** - Related features:\n\n```markdown\n<CardGroup cols={2}>\n  <Card title=\"Feature\" icon=\"icon\" href=\"/path\">Description</Card>\n</CardGroup>\n```\n\n## Content Standards\n\n### Writing Rules\n\n1. **Start with developer context**: \"When building X, you need Y\"\n2. **No generic introductions**: Avoid \"This page explains...\"\n3. **Exactly 3 benefits**: Specific and actionable\n4. **3-5 Quick Start steps**: Immediately actionable\n5. **Complete code examples**: Include imports and setup\n6. **Real-world use cases**: Focus on developer problems\n7. **Good vs bad examples**: Use ✅/❌ format\n\n### Code Requirements\n\n- **All examples must be tested** with real API calls\n- **Include necessary imports** and setup code\n- **Show error handling** for production use\n- **Use current syntax** and dependencies\n- **Provide complete context** - no partial snippets\n\n### Content Guidelines\n\n- **Remove UI-only sections** that don't add developer value\n- **Focus on implementation** not product features\n- **Use consistent terminology** throughout\n- **Include alt text** for all images\n- **Link related features** appropriately\n\n## Workflow\n\n### 1. Apply Template\n\n- Follow the structure exactly\n- Use required components properly\n- Focus on developer-first content\n- Remove unnecessary UI descriptions\n\n### 2. Validate Against Code\n\n- Verify all API endpoints exist\n- Check authentication requirements\n- Confirm configuration options and defaults\n- Find any undocumented features\n\n### 3. Test Examples\n\n- Create test scripts for all code examples\n- Use real API keys to verify functionality\n- Test error conditions and edge cases\n- Confirm dashboard integration works\n\n## Quality Checklist\n\nBefore publishing:\n\n- [ ] Follows template structure exactly\n- [ ] All code examples tested and working\n- [ ] API details verified against codebase\n- [ ] Uses proper Mintlify components\n- [ ] Includes complete, working examples\n- [ ] Focuses on developer use cases\n- [ ] Related features properly linked\n- [ ] No UI-only content without value\n\n## Common Mistakes\n\n**Avoid:**\n\n- Generic introductions (\"This feature allows...\")\n- Incomplete code examples missing imports\n- Untested code snippets\n- UI descriptions without developer value\n- Missing error handling\n- Outdated syntax or dependencies\n\n**Instead:**\n\n- Start with developer context\n- Provide complete, tested examples\n- Focus on implementation details\n- Show practical use cases\n- Include proper error handling\n- Keep examples current\n\n<!-- File: .cursor/rules/helicone-style-guidelines.mdc (Tokens: ~3018 | Category: cursor-rule) -->\n---\ndescription: Helicone Style Guidelines\nglobs: \nalwaysApply: true\n---\n# Helicone Design System Guidelines\n\n## Core Principles\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n| Component | Size | Line Height | Weight | Usage |\n|-----|---|----|---|----|\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n```tsx\n/* Text Colors */\ntext-foreground              // Primary text\ntext-muted-foreground        // Secondary text\ntext-accent-foreground       // Accent text\n\n/* Background Colors */\nbg-background                // Page background\nbg-card                      // Card background\nbg-muted                     // Muted background\n\n/* Border Colors */\nborder-border                // Default borders\nborder-input                 // Form inputs\nring-ring                    // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n```tsx\n/* Light Mode */\nbg-primary                   // #0EA5E9 (sky-500)\ntext-primary-foreground      // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg-primary                   // #0284C7 (sky-600)\ntext-primary-foreground      // #083344 (sky-950)\n```\n\n### Background Colors\n```tsx\n/* Light Mode */\nbg-background                // #FFFFFF (white)\ntext-foreground              // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-background                // #020617 (slate-950)\ntext-foreground              // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n```tsx\n/* Light Mode */\nbg-accent                    // #F1F5F9 (slate-100)\ntext-accent-foreground       // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-accent                    // #1E293B (slate-800)\ntext-accent-foreground       // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n```tsx\n/* Light Mode */\nbg-card                      // #FFFFFF (white)\ntext-card-foreground         // #020617 (slate-950)\nbg-popover                   // #FFFFFF (white)\ntext-popover-foreground      // #020617 (slate-950)\nborder-border                // #E2E8F0 (slate-200)\nborder-input                 // #E2E8F0 (slate-200)\nring-ring                    // #0F172A (slate-900)\n\n/* Dark Mode */\nbg-card                      // #020617 (slate-950)\ntext-card-foreground         // #F8FAFC (slate-50)\nbg-popover                   // #020617 (slate-950)\ntext-popover-foreground      // #F8FAFC (slate-50)\nborder-border                // #1E293B (slate-800)\nborder-input                 // #1E293B (slate-800)\nring-ring                    // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n```tsx\n/* Light Mode */\nbg-muted                     // #F1F5F9 (slate-100)\ntext-muted-foreground        // #64748B (slate-500)\nbg-secondary                 // #F1F5F9 (slate-100)\ntext-secondary-foreground    // #0F172A (slate-900)\nbg-destructive               // #DC2626 (red-600)\ntext-destructive-foreground  // #450A0A (red-950)\nbg-confirmative              // #16A34A (green-600)\ntext-confirmative-foreground // #052E16 (green-950)\n\n/* Dark Mode */\nbg-muted                     // #1E293B (slate-800)\ntext-muted-foreground        // #94A3B8 (slate-400)\nbg-secondary                 // #1E293B (slate-800)\ntext-secondary-foreground    // #F8FAFC (slate-50)\nbg-destructive               // #7F1D1D (red-900)\ntext-destructive-foreground  // #FEF2F2 (red-50)\nbg-confirmative              // #14532D (green-900)\ntext-confirmative-foreground // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n```tsx\n/* Light Mode */\nbg-sidebar-background        // #F8FAFC (slate-50)\ntext-sidebar-foreground      // #334155 (slate-700)\nborder-sidebar-border        // #E2E8F0 (slate-200)\nbg-sidebar-primary           // #0C4A6E (sky-900)\ntext-sidebar-primary-foreground // #F0F9FF (sky-50)\nbg-sidebar-accent            // #F1F5F9 (slate-100)\ntext-sidebar-accent-foreground // #0F172A (slate-900)\nring-sidebar-ring            // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg-sidebar-background        // #0F172A (slate-900)\ntext-sidebar-foreground      // #F1F5F9 (slate-100)\nborder-sidebar-border        // #1E293B (slate-800)\nbg-sidebar-primary           // #0369A1 (sky-700)\ntext-sidebar-primary-foreground // #FFFFFF (white)\nbg-sidebar-accent            // #1E293B (slate-800)\ntext-sidebar-accent-foreground // #F1F5F9 (slate-100)\nring-sidebar-ring            // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n```tsx\n/* Light Mode */\nbg-chart-1                   // #2A9D90\nbg-chart-2                   // #E76E50\nbg-chart-3                   // #274754\nbg-chart-4                   // #E8C468\nbg-chart-5                   // #F4A462\n\n/* Dark Mode */\nbg-chart-1                   // #2662D9\nbg-chart-2                   // #E23670\nbg-chart-3                   // #E88C30\nbg-chart-4                   // #AF57DB\nbg-chart-5                   // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>\n    Monitor and analyze your LLM usage\n  </Lead>\n  \n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n    \n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map(feature => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">\n      Last 30 days\n    </Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```\n\n<!-- File: .cursor/rules/helicone-system-overview.mdc (Tokens: ~768 | Category: cursor-rule) -->\n---\ndescription: \nglobs: \nalwaysApply: true\n---\n# Helicone System Architecture\n\n## Core Components\n\n1. **Frontend (Web)** - Next.js application\n   - Dashboard UI for visualization and management\n   - Located in `/web` directory\n\n2. **Proxy Workers** - Cloudflare Workers\n   - Intercept and process API calls to LLM providers\n   - Located in `/worker` directory\n   - Separate workers for OpenAI, Anthropic, and general API\n\n3. **Jawn Server** - Express.js + Tsoa backend\n   - Core business logic and data processing\n   - Located in `/valhalla/jawn` directory\n   - Handles authentication, logging, and analytics\n\n4. **Bifrost** - Landing page and blog application\n   - Marketing website and documentation\n   - Located in `/bifrost` directory\n\n5. **Databases**\n   - **PostgreSQL** (via Supabase): User data, organizations, API keys\n   - **ClickHouse**: High-performance analytics storage for request logs\n\n6. **Object Storage** - Minio/S3 compatible\n   - Stores large request/response payloads\n   - Enables efficient retrieval of historical data\n\n7. **Upstash** - Redis-compatible message queue\n   - Buffers requests between proxy and backend\n   - Ensures reliable delivery of logging data\n\n## Directory Structure\n\n```\n/helicone\n├── /web                 # Next.js frontend dashboard\n├── /worker              # Cloudflare Workers proxy\n│   ├── /src/routers     # API provider-specific routers\n│   └── /src/lib         # Shared utilities\n├── /valhalla\n│   └── /jawn            # Express.js backend server\n├── /bifrost             # Landing page and blog\n├── /sdk                 # Client SDKs\n│   ├── /typescript      # TypeScript SDK\n│   └── /python          # Python SDK\n```\n\n## Data Flow\n\n1. **Request Interception**:\n   - Client request → Helicone Proxy → LLM Provider\n   - Proxy adds tracking headers and applies features\n\n2. **Response Processing**:\n   - LLM Provider → Helicone Proxy → Client\n   - Proxy sends log data to Upstash queue\n\n3. **Log Processing**:\n   - Upstash queue → Jawn server\n   - Jawn processes and stores logs in databases\n\n4. **Data Storage**:\n   - Request metadata → PostgreSQL\n   - Analytics data → ClickHouse\n   - Large payloads → Object Storage\n\n5. **Analytics Processing**:\n   - Jawn server processes logs for insights\n   - Aggregates metrics for dashboard visualization\n\n## System Interactions\n\n- **Frontend ↔ Jawn**: REST API for dashboard data\n- **Proxy ↔ Upstash**: Asynchronous message queuing\n- **Upstash ↔ Jawn**: Reliable message delivery\n- **Jawn ↔ Databases**: Data storage and retrieval\n\n## Technical Implementation\n\n- **Frontend**: React, Next.js, Tailwind CSS\n- **Proxy**: Cloudflare Workers, TypeScript\n- **Backend**: Express.js, Tsoa, TypeScript\n- **Bifrost**: Next.js, React, TypeScript\n- **Databases**: PostgreSQL, ClickHouse\n- **Queue**: Upstash Redis\n\n## Key Files for Development\n\n- `/worker/src/index.ts`: Entry point for proxy workers\n- `/worker/src/routers/`: Provider-specific routing logic\n- `/valhalla/jawn/src/index.ts`: Backend server entry point\n- `/web/pages/`: Frontend dashboard components\n- `/bifrost/pages/`: Landing page and blog components\n\n<!-- File: .cursor/rules/jawn.mdc (Tokens: ~540 | Category: cursor-rule) -->\n---\ndescription: \nglobs: *.ts\nalwaysApply: false\n---\n# Helicone Jawn Controller and TanStack Query Integration\n\n## Controller Pattern\n- Jawn controllers (`valhalla/jawn/src/controllers/`) follow a RESTful design with standard HTTP methods\n- Controllers use decorators like `@Route`, `@Get`, `@Post`, etc. from TSOA\n- Controllers accept `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Required parameters should come before optional parameters in controller methods\n\n## Manager Pattern\n- Each controller has a corresponding manager (`valhalla/jawn/src/managers/`)\n- Managers extend `BaseManager` and handle database operations\n- Managers receive `authParams` from the controller request\n- Use `dbExecute` for database operations and wrap results in `Result<T, string>`\n\n## Frontend Hooks with TanStack Query\n- Use `useJawnClient()` to interact with Jawn controllers\n- Implement custom hooks with TanStack Query for data fetching and mutations\n- For GET requests:\n  ```typescript\n  const query = useQuery({\n    queryKey: ['resource', id],\n    queryFn: async () => {\n      const response = await jawn.GET('/v1/resource/{id}', {\n        params: { path: { id } }\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    }\n  });\n  ```\n\n- For mutations:\n  ```typescript\n  const mutation = useMutation({\n    mutationFn: async (input) => {\n      const response = await jawn.POST('/v1/resource', {\n        body: input\n      });\n      if (response.error) throw response.error;\n      return response.data;\n    },\n    onSuccess: (data) => {\n      // Invalidate queries\n      queryClient.invalidateQueries({ queryKey: ['resource'] });\n    }\n  });\n  ```\n\n## Type Definitions\n- Define request and response interfaces in the controller file\n- Use proper typing with TanStack Query\n- Handle Jawn response structure properly with error checking\n\n## URL State Management\n- Use URL parameters for persisting filter state between pages\n- Update URL when filter changes with `useSearchParams` from Next.js\n\n## Database Schema\n- Tables follow snake_case naming\n- Use proper indexes for performance\n- Implement proper RLS policies for security\n- Create functions for specialized operations (e.g., incrementing versions)\n\n## Enhanced Filters Specifics\n- Filters support both simple queries and complex logical expressions\n- Filters can be persisted, shared, and reused\n- Support both legacy and enhanced filter systems for backward compatibility\n\n<!-- File: .cursor/rules/supabase.mdc (Tokens: ~118 | Category: cursor-rule) -->\n---\ndescription: Supabase\nglobs: *.ts, *sql\nalwaysApply: false\n---\nDo not use the Supabase Client, instead use the Jawn Client and put all new endpoints in controllers.\nDon't use RLS policies, instead enable RLS for new tables and revoke privledges. Example:\n\n```\nalter table \"public\".\"org_rate_limits\" enable row level security;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom authenticated;\nREVOKE all PRIVILEGES on \"public\".\"org_rate_limits\"\nfrom anon;\n```\n\n<!-- File: CLAUDE.md (Tokens: ~4481 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth          # With better-auth\ncd web && yarn dev:local               # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n<div className=\"flex flex-col gap-4\">\n<div className=\"flex items-center gap-2\">\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result<T, string>`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/                   # Next.js frontend\n/valhalla/jawn/        # Express.js backend\n/worker/               # Cloudflare Workers\n/aigateway/            # Rust LLM proxy\n/bifrost/              # Marketing site\n/packages/             # Shared packages\n  ├── cost/            # Cost calculations\n  ├── llm-mapper/      # Provider mappings\n  └── prompts/         # Prompt management\n/supabase/             # Database migrations\n/clickhouse/           # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n   ```bash\n   grep -r \"thinkingLevel\" packages/  # Find all usages of similar type\n   ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n<H1>Page Title</H1>\n<P>Regular paragraph</P>\n<Small>Helper text</Small>\n<Muted>Secondary text</Muted>\n\n// ❌ Don't do this\n<h1 className=\"text-4xl font-bold\">Raw Styles</h1>\n<H1 className=\"text-3xl\">Overriding Typography</H1>\n<P className=\"text-sm\">Wrong Size</P>\n```\n\n### Available Components\n\n```tsx\n// Headings\n<H1>              // Main page titles\n<H1Large>         // Hero sections\n<H2>              // Section headers\n<H3>              // Subsection headers\n<H4>              // Card titles\n\n// Body Text\n<P>               // Regular paragraphs\n<Lead>            // Introduction text\n<Large>           // Emphasized body text\n<Small>           // Helper text\n<Muted>           // Secondary text\n\n// Special Elements\n<Blockquote>      // Quotations\n<Code>            // Inline code\n<List>            // Unordered lists\n\n// Table Elements\n<TableHead>       // Table headers\n<TableCell>       // Table cells\n```\n\n### Typography Scale\n\n| Component | Size                                 | Line Height       | Weight    | Usage              |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1        | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold  | Main page titles   |\n| H1Large   | text-5xl (48px)                      | leading-10 (40px) | extrabold | Hero sections      |\n| H2        | text-3xl (30px)                      | leading-9 (36px)  | semibold  | Section headers    |\n| H3        | text-2xl (24px)                      | leading-8 (32px)  | semibold  | Subsection headers |\n| H4        | text-xl (20px)                       | leading-7 (28px)  | semibold  | Card titles        |\n| Lead      | text-xl (20px)                       | leading-7 (28px)  | normal    | Introduction text  |\n| P         | text-base (16px)                     | leading-7 (28px)  | normal    | Body text          |\n| Small     | text-sm (14px)                       | leading-4 (16px)  | medium    | Helper text        |\n| Muted     | text-sm (14px)                       | leading-none      | normal    | Secondary text     |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅ <div className=\"flex flex-col gap-2\">  // Related items (0.5rem)\n✅ <div className=\"flex flex-col gap-4\">  // Content blocks (1rem)\n✅ <div className=\"flex flex-col gap-6\">  // Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex items-center gap-2\">\n\n// ❌ Don't use space-y or margins for spacing\n❌ <div className=\"space-y-4\">\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"p-[5px]\">\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅ <div className=\"flex gap-4\">\n✅ <div className=\"flex flex-col gap-6\">\n\n// 2. Use grid + gap\n✅ <div className=\"grid grid-cols-3 gap-4\">\n\n// ❌ Don't use margins for spacing\n❌ <div className=\"flex [&>*+*]:ml-4\">\n❌ <div className=\"space-y-4\">\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅ <div className=\"mx-auto max-w-7xl px-4 sm:px-6 lg:px-8\">\n\n// Card Container\n✅ <div className=\"rounded-lg border border-border bg-card text-card-foreground\">\n\n// Form Groups\n✅ <div className=\"flex flex-col gap-4\">\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ <Info size={16} />  // Default size\n✅ <Settings size={20} />  // Large size\n✅ <ChevronRight size={14} />  // Small size\n\n// ❌ Don't use className for sizing\n❌ <Info className=\"h-4 w-4\" />  // Use size prop instead\n❌ <Settings className=\"w-[18px] h-[18px]\" />  // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ <Button variant=\"action\">Create Organization</Button>\n✅ <Button variant=\"outline\" size=\"sm\">Cancel</Button>\n\n// ❌ Don't wrap components unnecessarily\n❌ <div className=\"w-full\">\n    <Button>Create Organization</Button>\n  </div>\n❌ <div className=\"text-white\">\n    <Button>Create Organization</Button>\n  </div>\n\n// 2. Use size variants for consistent sizing\n✅ <Button size=\"sm\">Small Button</Button>\n✅ <Button size=\"default\">Default Button</Button>\n✅ <Button size=\"lg\">Large Button</Button>\n\n// 3. Use asPill for rounded buttons\n✅ <Button asPill>Rounded Button</Button>\n\n// 4. Combine variants appropriately\n✅ <Button variant=\"action\" size=\"lg\" asPill>Create Account</Button>\n```\n\n### Page Layout\n\n```tsx\n<article className=\"flex flex-col gap-6\">\n  <H1>Welcome to Helicone</H1>\n  <Lead>Monitor and analyze your LLM usage</Lead>\n\n  <section className=\"flex flex-col gap-4\">\n    <H2>Features</H2>\n    <P>Detailed explanation of features...</P>\n\n    <div className=\"grid grid-cols-3 gap-6\">\n      {features.map((feature) => (\n        <div key={feature.id} className=\"flex flex-col gap-2\">\n          <H3>{feature.title}</H3>\n          <Muted>{feature.description}</Muted>\n        </div>\n      ))}\n    </div>\n  </section>\n</article>\n```\n\n### Card Pattern\n\n```tsx\n<Card>\n  <CardHeader>\n    <H4>Usage Statistics</H4>\n    <Small className=\"text-muted-foreground\">Last 30 days</Small>\n  </CardHeader>\n  <CardContent>\n    <P>Card content...</P>\n  </CardContent>\n</Card>\n```\n\n<!-- File: examples/tools/python/README.md (Tokens: ~300 | Category: plugin-manifest) -->\n# python Documentation\n\nPath: `examples/tools/python/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/examples/tools/python/README.md)\n\n<!-- File: packages/cost/README.md (Tokens: ~300 | Category: plugin-manifest) -->\n# cost Documentation\n\nPath: `packages/cost/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/cost/README.md)\n\n<!-- File: packages/llm-mapper/README.md (Tokens: ~300 | Category: plugin-manifest) -->\n# llm-mapper Documentation\n\nPath: `packages/llm-mapper/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/Helicone/helicone/HEAD/packages/llm-mapper/README.md)\n\n<!-- File: packages/README.md (Tokens: ~437 | Category: plugin-manifest) -->\n# Common issues\n\nIf you are using OpenAI you might need to include stream usage options: https://docs.helicone.ai/faq/enable-stream-usage\n\n\n\n# Helicone Packages\n\nThis directory contains shared packages used across the Helicone ecosystem.\n\n## Packages\n\n### 🏷️ Cost Package\n**Add pricing support for LLM models and providers**\n\nThe cost package handles pricing calculations for all supported AI/ML providers in Helicone.\n\n**[📖 Click here to add cost support for new models →](./cost/README.md)**\n\nCommon tasks:\n- Add pricing for new models (GPT-5, Claude 4, etc.)\n- Add support for new providers \n- Update existing model pricing\n- Add cost types (images, audio, per-call fees)\n\n### 🗺️ LLM Mapper\nRequest/response mapping and transformation for different LLM providers.\n\n### 🔍 Filters  \nFiltering definitions and utilities for request/response data.\n\n### 💬 Prompts\nPrompt templates and management utilities.\n\n## Contributing\n\nEach package contains its own documentation. See individual README files for contribution guidelines.\n\n### Quick Links\n- **[Cost Package Documentation](./cost/README.md)** - Add model pricing support\n- **Test Directory** - Package tests in `__tests__/`\n\n## Development\n\n### Running Tests\n\nTests are located in `__tests__/` directory and use Jest:\n\n```bash\n# Run all package tests\nnpx jest\n\n# Run specific test file\nnpx jest __tests__/cost/registrySnapshots.test.ts\n\n# Update snapshots after intentional changes\nnpx jest -u\n\n# Run tests without cache (useful for debugging)\nnpx jest --no-cache\n```\n\n#### Key Test Files\n- `__tests__/cost/ensureOnlyOne.test.ts` - Validates no duplicate models and cost calculations\n- `__tests__/cost/registrySnapshots.test.ts` - Snapshot tests for model registry (pricing, coverage, configs)\n- `__tests__/llm-mapper/` - Tests for request/response mapping\n\n### Building\n\n```bash\n# Build packages\nnpm run build\n```\n</yakaai_skills>"}