# Cost Estimation Integration Guide

## Overview

The cost estimation feature allows users to see estimated costs before executing operations. This helps users make informed decisions and avoid unexpected charges.

## Components

### 1. `CostEstimationModal` Component

A reusable modal component that displays cost estimates for operations.

**Location**: `frontend/src/components/billing/CostEstimationModal.tsx`

**Props**:
```typescript
interface CostEstimationModalProps {
  open: boolean;
  onClose: () => void;
  onConfirm: () => void;
  operations: PreflightOperation[];
  userId?: string;
}
```

### 2. `useCostEstimation` Hook

A React hook that manages cost estimation state.

**Location**: `frontend/src/hooks/useCostEstimation.ts`

**Returns**:
```typescript
{
  showEstimation: (operations: PreflightOperation[]) => void;
  estimationOperations: PreflightOperation[];
  isEstimationOpen: boolean;
  closeEstimation: () => void;
}
```

## Usage Example

### Basic Integration

```typescript
import React from 'react';
import { useCostEstimation } from '../../hooks/useCostEstimation';
import CostEstimationModal from '../billing/CostEstimationModal';
import { PreflightOperation } from '../../services/billingService';

const MyComponent: React.FC = () => {
  const { 
    showEstimation, 
    estimationOperations, 
    isEstimationOpen, 
    closeEstimation 
  } = useCostEstimation();

  const handleGenerate = () => {
    // Define operations that will be performed
    const operations: PreflightOperation[] = [
      {
        provider: 'gemini',
        model: 'gemini-2.5-flash',
        operation_type: 'text_generation',
        tokens_requested: 2000
      }
    ];

    // Show cost estimation modal
    showEstimation(operations);
  };

  const performActualOperation = async () => {
    // Your actual operation logic here
    console.log('Performing operation...');
  };

  return (
    <>
      <button onClick={handleGenerate}>
        Generate Content
      </button>

      <CostEstimationModal
        open={isEstimationOpen}
        onClose={closeEstimation}
        onConfirm={performActualOperation}
        operations={estimationOperations}
      />
    </>
  );
};
```

### Advanced Example: Blog Writer

```typescript
import React, { useState } from 'react';
import { useCostEstimation } from '../../hooks/useCostEstimation';
import CostEstimationModal from '../billing/CostEstimationModal';
import { PreflightOperation } from '../../services/billingService';

const BlogWriter: React.FC = () => {
  const [keywords, setKeywords] = useState('');
  const { 
    showEstimation, 
    estimationOperations, 
    isEstimationOpen, 
    closeEstimation 
  } = useCostEstimation();

  const handleGenerateBlog = () => {
    // Estimate costs for blog generation workflow
    // Typically involves: research (1 call) + outline (1 call) + content (1-3 calls)
    const operations: PreflightOperation[] = [
      {
        provider: 'gemini',
        model: 'gemini-2.5-flash',
        operation_type: 'research',
        tokens_requested: 1500
      },
      {
        provider: 'gemini',
        model: 'gemini-2.5-flash',
        operation_type: 'outline_generation',
        tokens_requested: 1000
      },
      {
        provider: 'gemini',
        model: 'gemini-2.5-flash',
        operation_type: 'content_generation',
        tokens_requested: 3000
      }
    ];

    showEstimation(operations);
  };

  const performBlogGeneration = async () => {
    // Actual blog generation logic
    // This will only be called if user confirms in the modal
    console.log('Generating blog...');
  };

  return (
    <>
      <div>
        <input 
          value={keywords} 
          onChange={(e) => setKeywords(e.target.value)}
          placeholder="Enter blog topic..."
        />
        <button onClick={handleGenerateBlog}>
          Generate Blog
        </button>
      </div>

      <CostEstimationModal
        open={isEstimationOpen}
        onClose={closeEstimation}
        onConfirm={performBlogGeneration}
        operations={estimationOperations}
      />
    </>
  );
};
```

### Example: Image Generation

```typescript
const ImageStudio: React.FC = () => {
  const { showEstimation, estimationOperations, isEstimationOpen, closeEstimation } = useCostEstimation();

  const handleGenerateImage = () => {
    const operations: PreflightOperation[] = [
      {
        provider: 'stability',
        operation_type: 'image_generation',
        // tokens_requested not needed for image generation
      }
    ];

    showEstimation(operations);
  };

  return (
    <>
      <button onClick={handleGenerateImage}>
        Generate Image
      </button>

      <CostEstimationModal
        open={isEstimationOpen}
        onClose={closeEstimation}
        onConfirm={() => generateImage()}
        operations={estimationOperations}
      />
    </>
  );
};
```

## Operation Types

Common operation types you can use:

### LLM Operations
- `text_generation` - General LLM text generation
- `research` - Research operations (typically includes search + LLM analysis)
- `outline_generation` - Content outline generation
- `content_generation` - Full content generation
- `seo_analysis` - SEO analysis and optimization
- `content_optimization` - Content refinement and optimization
- `title_generation` - Title/headline generation
- `summary_generation` - Content summarization

### Media Generation Operations
- `image_generation` - Image generation (text-to-image)
- `image_editing` - Image editing operations (inpaint, outpaint, recolor, etc.)
- `image_upscaling` - Image upscaling operations
- `face_swap` - Face swap operations
- `video_generation` - Video generation (text-to-video, image-to-video)
- `video_editing` - Video editing operations
- `audio_generation` - Audio/TTS generation
- `audio_editing` - Audio editing operations

### Search & Research Operations
- `search` - Generic search API operations
- `exa_search` - Exa neural search
- `tavily_search` - Tavily AI search
- `serper_search` - Serper Google search
- `metaphor_search` - Metaphor search
- `firecrawl_extract` - Firecrawl web page extraction

### Specialized Operations
- `character_image_generation` - Character-consistent image generation
- `product_image_generation` - Product-focused image generation
- `avatar_generation` - Avatar/talking head generation
- `scene_generation` - Scene-based video/image generation
- `batch_operation` - Batch processing operations

## Providers

Supported providers:

### LLM Providers
- `gemini` - Google Gemini (default: gemini-2.5-flash)
- `openai` - OpenAI GPT models (default: gpt-4o-mini)
- `anthropic` - Anthropic Claude (default: claude-3.5-sonnet)
- `mistral` - Mistral AI / HuggingFace (default: gpt-oss-120b)

### Search Providers
- `tavily` - Tavily AI Search ($0.001 per search)
- `serper` - Serper Google Search ($0.001 per search)
- `metaphor` - Metaphor Search ($0.003 per search)
- `exa` - Exa Neural Search ($0.005 per search)
- `firecrawl` - Firecrawl Web Extraction ($0.002 per page)

### Media Providers
- `stability` - Stability AI (images: $0.04/image, includes OSS models)
  - OSS Models: `qwen-image` ($0.03), `ideogram-v3-turbo` ($0.05)
- `wavespeed` - WaveSpeed AI (OSS models via Stability provider)
  - Image: `qwen-image`, `ideogram-v3-turbo`
  - Image Edit: `qwen-edit` ($0.02), `flux-kontext-pro` ($0.04)
  - Video: `wan-2.5` ($0.25), `seedance-1.5-pro` ($0.40)
  - Audio: `minimax-speech-02-hd` ($0.05 per 1K chars)
- `video` - Video generation (default: wan-2.5 OSS $0.25)
- `image_edit` - Image editing (default: qwen-edit OSS $0.02)
- `audio` - Audio generation (default: minimax-speech-02-hd OSS)

## Best Practices

1. **Always show estimation before expensive operations** - Operations that cost > $0.01 should show estimation
2. **Group related operations** - If a workflow involves multiple API calls, include all of them in the estimation
3. **Provide accurate token estimates** - More accurate token estimates lead to better cost predictions
4. **Handle errors gracefully** - If estimation fails, allow users to proceed with a warning
5. **Cache estimations** - The API returns a `cached` flag - consider caching for better UX

## Integration Checklist

- [ ] Import `useCostEstimation` hook
- [ ] Import `CostEstimationModal` component
- [ ] Define operations array with `PreflightOperation[]`
- [ ] Call `showEstimation(operations)` before operation
- [ ] Render `CostEstimationModal` with proper props
- [ ] Move actual operation logic to `onConfirm` callback
- [ ] Test with various operation types
- [ ] Handle error states gracefully

## Testing

Test the cost estimation with:

1. **Single operation** - Simple text generation
2. **Multiple operations** - Blog generation workflow
3. **Different providers** - Gemini, OpenAI, etc.
4. **Limit exceeded** - Test when limits are reached
5. **Error handling** - Network errors, API failures

## Notes

- The modal automatically fetches cost estimates when opened
- Users can proceed only if `can_proceed` is `true`
- The modal shows detailed breakdown per operation
- Usage limits are displayed if available
- Actual costs may vary slightly from estimates