PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/z-archive/implementation/implementation_centralized_ai_calls.md

15 KiB
Raw Blame History

Centralized AI Calls Specification

Overview

This document specifies the centralized AI call system for PowerOn, replacing the current distributed AI call patterns with a unified approach that provides better optimization, consistency, and maintainability.

Current State Analysis

Existing AI Call Patterns

The current codebase uses multiple AI call patterns across different modules:

  1. ServiceCenter - Basic/Advanced text and image processing
  2. HandlingTasks - Task planning, action planning, result validation
  3. MethodOutlook - Email composition with document context
  4. MethodAi - General AI processing with document context
  5. MethodDocument - HTML report generation and document conversion

Current Implementation Issues

  • Inconsistent Model Selection: Different modules use different AI models without optimization
  • Redundant Document Processing: Each module implements its own document extraction logic
  • No Centralized Optimization: No unified approach to content compression or failover
  • Maintenance Overhead: Changes to AI logic require updates across multiple modules

Centralized AI Call System

Core Interface

async def callAi(
    prompt: str,
    documents: List[ChatDocument] = None,
    options: Dict[str, Any] = None
) -> CentralizedAiResponse

Options Specification

options = {
    "process_type": "text" | "image",                    # Content type to process
    "operation_type": "generate_plan" | "summarize_data" | "extract_content" | "analyse_content" | "generate_content" | "email_composition" | "report_generation" | "task_planning" | "result_validation",
    "priority": "speed" | "quality" | "cost" | "balanced",  # Model selection priority
    "compress_prompt": bool,                             # Allow prompt compression
    "compress_documents": bool,                          # Allow document compression
    "process_documents_individually": bool,              # Process documents separately
    "max_cost": float,                                   # Maximum cost limit
    "max_processing_time": int,                          # Max processing time in seconds
    "max_size_bytes": int,                              # Maximum result size
    "result_format_requested": str,                      # Desired output format
    "include_metadata": bool,                           # Include document metadata
    "processing_mode": "basic" | "advanced" | "detailed" # Processing depth
}

Response Format

The centralized AI call returns a standardized CentralizedAiResponse object:

class CentralizedAiResponse(BaseModel):
    aiResults: List[AiResult] = Field(default_factory=list)
    success: bool = Field(description="Whether the AI call was successful")
    error: Optional[str] = Field(None, description="Error message if the call failed")

class AiResult(BaseModel):
    filename: str = Field(description="Name of the result document")
    mimetype: str = Field(description="MIME type of the result document")
    content: str = Field(description="Content of the result document")

Current AI Calls Mapping

1. ServiceCenter AI Calls

Functions to DELETE from ServiceCenter

# DELETE these functions from ServiceCenter:
async def callAiTextBasic(self, prompt: str, context: str = None) -> str
async def callAiTextAdvanced(self, prompt: str, context: str = None) -> str  
async def callAiImageBasic(self, prompt: str, imageData: str, mimeType: str) -> str
async def callAiImageAdvanced(self, prompt: str, imageData: str, mimeType: str) -> str
async def extractContentFromDocument(self, prompt: str, document: ChatDocument) -> ExtractedContent

Direct Centralized Replacement - All calls go directly to interfaceAiCalls

# Basic text processing - Direct call with speed priority
response = await self.service.interfaceAiCalls.callAi(
    prompt=prompt,
    documents=None,
    options={
        "process_type": "text",
        "operation_type": "generate_content",
        "priority": "speed",
        "compress_prompt": True,
        "compress_documents": False,
        "max_cost": 0.01
    }
)
# Access result: response.aiResults, response.success, response.error

# Advanced text processing - Direct call with quality priority
response = await self.service.interfaceAiCalls.callAi(
    prompt=prompt,
    documents=None,
    options={
        "process_type": "text", 
        "operation_type": "generate_content",
        "priority": "quality",
        "compress_prompt": False,
        "compress_documents": False,
        "max_cost": 0.05
    }
)
# Access result: response.aiResults, response.success, response.error

# Image processing - Direct call with image documents
image_doc = ChatDocument(fileData=imageData, fileName="image", mimeType=mimeType)
response = await self.service.interfaceAiCalls.callAi(
    prompt=prompt,
    documents=[image_doc],
    options={
        "process_type": "image",
        "operation_type": "analyse_content",
        "priority": "balanced",
        "compress_documents": True,
        "max_cost": 0.03
    }
)
# Access result: response.aiResults, response.success, response.error

2. HandlingTasks AI Calls

Current Implementation (TO BE REMOVED)

# Task planning
prompt = await self.service.callAiTextAdvanced(task_planning_prompt)

# Action planning
prompt = await self.service.callAiTextAdvanced(action_prompt)

# Result validation
response = await self.service.callAiTextAdvanced(prompt)

Direct Centralized Replacement

# Task planning - Direct call with detailed processing
response = await self.service.interfaceAiCalls.callAi(
    prompt=task_planning_prompt,
    documents=None,
    options={
        "process_type": "text",
        "operation_type": "generate_plan",
        "priority": "quality",
        "compress_prompt": False,
        "compress_documents": False,
        "processing_mode": "detailed",
        "max_cost": 0.10,
        "max_processing_time": 60
    }
)
# Access result: response.aiResults[0].content for the plan text

# Action planning - Direct call with detailed processing
response = await self.service.interfaceAiCalls.callAi(
    prompt=action_prompt,
    documents=None,
    options={
        "process_type": "text",
        "operation_type": "generate_plan", 
        "priority": "quality",
        "compress_prompt": False,
        "compress_documents": False,
        "processing_mode": "detailed",
        "max_cost": 0.10,
        "max_processing_time": 60
    }
)
# Access result: response.aiResults[0].content for the action plan

# Result validation - Direct call with analysis focus
response = await self.service.interfaceAiCalls.callAi(
    prompt=prompt,
    documents=None,
    options={
        "process_type": "text",
        "operation_type": "analyse_content",
        "priority": "balanced",
        "compress_prompt": True,
        "compress_documents": False,
        "processing_mode": "advanced",
        "max_cost": 0.05,
        "max_processing_time": 30
    }
)
# Access result: response.aiResults[0].content for the validation result

3. MethodOutlook AI Calls

Current Implementation (TO BE REMOVED)

# Document extraction
extracted_content = await self.service.extractContentFromDocument(
    prompt="Extract readable text content for email composition",
    document=doc
)

# Email composition
composed_email = await self.service.callAiTextAdvanced(ai_prompt)

Direct Centralized Replacement

# Email composition with document context - Direct call
response = await self.service.interfaceAiCalls.callAi(
    prompt=ai_prompt,
    documents=documents,
    options={
        "process_type": "text",
        "operation_type": "email_composition",
        "priority": "speed",
        "compress_prompt": True,
        "compress_documents": True,
        "process_documents_individually": False,
        "result_format_requested": "email",
        "include_metadata": True,
        "max_cost": 0.02,
        "max_processing_time": 15
    }
)
# Access result: response.aiResults[0].content for the email content
# response.aiResults[0].mimetype will contain the MIME type of the delivered content

4. MethodAi AI Calls

Current Implementation (TO BE REMOVED)

# Document extraction
extracted_content = await self.service.extractContentFromDocument(
    prompt=extraction_prompt,
    document=doc
)

# AI processing
if processingMode in ["advanced", "detailed"]:
    result = await self.service.callAiTextAdvanced(enhanced_prompt, context)
else:
    result = await self.service.callAiTextBasic(enhanced_prompt, context)

Direct Centralized Replacement

# AI processing with document context - Direct call
response = await self.service.interfaceAiCalls.callAi(
    prompt=enhanced_prompt,
    documents=documents,
    options={
        "process_type": "text",
        "operation_type": "generate_content",
        "priority": "quality" if processingMode in ["advanced", "detailed"] else "speed",
        "compress_prompt": processingMode != "detailed",
        "compress_documents": True,
        "process_documents_individually": True,
        "processing_mode": processingMode,
        "result_format_requested": output_format,
        "include_metadata": includeMetadata,
        "max_cost": 0.05 if processingMode in ["advanced", "detailed"] else 0.02,
        "max_processing_time": 45 if processingMode in ["advanced", "detailed"] else 20
    }
)
# Access result: response.aiResults for all generated documents
# Each aiResult.mimetype will contain the MIME type of the delivered content

5. MethodDocument AI Calls

Current Implementation (TO BE REMOVED)

# Document extraction for HTML report
extracted_content = await self.service.extractContentFromDocument(
    prompt="Extract readable text content for HTML report generation",
    document=doc
)

# HTML report generation
aiReport = await self.service.callAiTextBasic(aiPrompt, combinedContent)

Direct Centralized Replacement

# HTML report generation with document context - Direct call
response = await self.service.interfaceAiCalls.callAi(
    prompt=aiPrompt,
    documents=documents,
    options={
        "process_type": "text",
        "operation_type": "report_generation",
        "priority": "quality",
        "compress_prompt": False,
        "compress_documents": True,
        "process_documents_individually": True,
        "result_format_requested": "html",
        "include_metadata": includeMetadata,
        "processing_mode": "detailed",
        "max_cost": 0.08,
        "max_processing_time": 90
    }
)
# Access result: response.aiResults[0].content for the HTML report
# response.aiResults[0].mimetype will contain the MIME type of the delivered content

Document Processing Integration

Centralized Document Extraction

The centralized system integrates with DocumentExtraction.processFileData() for all document processing:

# Document extraction is handled automatically by the centralized callAi method
# No need for manual extractContentFromDocument calls

Document Processing Options

  • Individual Processing: Each document processed separately with its own context
  • Batch Processing: All documents processed together for comprehensive analysis
  • Metadata Inclusion: Optional inclusion of file metadata (size, type, etc.)
  • Content Compression: Automatic compression for large documents

Technical Benefits

  • Unified Model Selection: Automatic selection based on content size, operation type, and priority
  • Consistent Document Processing: Single point of document extraction logic
  • Content Compression: Automatic compression for large prompts and documents
  • Centralized Error Handling: Consistent error handling and logging across all AI operations

Migration Strategy

Phase 1: Direct Call Implementation

  • Replace all callAiTextBasic/Advanced calls with direct interfaceAiCalls.callAi() calls
  • Remove intermediate wrapper functions
  • Each AI call gets specific options tailored to its needs

Phase 2: DELETE Legacy Methods from ServiceCenter

  • DELETE callAiTextBasic, callAiTextAdvanced, callAiImageBasic, callAiImageAdvanced methods from ServiceCenter
  • DELETE extractContentFromDocument method from ServiceCenter (handled automatically by centralized system)
  • Update all modules to use direct self.service.interfaceAiCalls.callAi() calls

Phase 3: Optimize and Test

  • Fine-tune options for each specific use case
  • Add comprehensive testing for all AI call scenarios
  • Monitor performance and cost optimization

Phase 4: Documentation and Cleanup

  • Update all documentation to reflect direct call approach
  • Remove any remaining legacy code references
  • Finalize centralized AI call patterns

Configuration Examples

High-Quality Document Analysis

options = {
    "process_type": "text",
    "operation_type": "analyse_content", 
    "priority": "quality",
    "compress_prompt": False,
    "compress_documents": False,
    "process_documents_individually": True,
    "include_metadata": True,
    "processing_mode": "detailed"
}
# Response: response.aiResults[0].content contains analysis

Fast Email Composition

options = {
    "process_type": "text",
    "operation_type": "email_composition",
    "priority": "speed", 
    "compress_prompt": True,
    "compress_documents": True,
    "result_format_requested": "email",
    "max_cost": 0.10
}
# Response: response.aiResults[0].content contains email
# response.aiResults[0].mimetype shows the MIME type of delivered content

Cost-Optimized Report Generation

options = {
    "process_type": "text",
    "operation_type": "report_generation",
    "priority": "cost",
    "compress_prompt": True,
    "compress_documents": True,
    "result_format_requested": "html",
    "max_cost": 0.05,
    "max_processing_time": 30
}
# Response: response.aiResults[0].content contains HTML report
# response.aiResults[0].mimetype shows the MIME type of delivered content

Implementation Requirements

Direct Interface Usage

All AI calls must use:

await self.service.interfaceAiCalls.callAi(prompt, documents, options)

Functions to Remove

  • self.service.callAiTextBasic()
  • self.service.callAiTextAdvanced()
  • self.service.callAiImageBasic()
  • self.service.callAiImageAdvanced()
  • self.service.extractContentFromDocument()

Configuration per Use Case

  • Task Planning: Quality priority, detailed processing, 60s timeout
  • Email Composition: Speed priority, compressed content, 15s timeout
  • Report Generation: Quality priority, detailed processing, 90s timeout
  • Image Analysis: Balanced priority, compressed documents