ALwrity/docs/Billing_Subscription/COST_ESTIMATION_INTEGRATION_GUIDE.md

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:

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:

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

Usage Example

Basic Integration

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

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

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