wiki/z-archive/appdoc/doc_system_call_sites_callAiDocuments.md

All Call Sites for callAiDocuments() → subCoreAi.callAiDocuments()

This document lists all places in the codebase where callAiDocuments() is called, which ultimately routes through mainServiceAi.callAiDocuments() to subCoreAi.callAiDocuments().

---

Call Chain

Call Site → services.ai.callAiDocuments() 
           → mainServiceAi.callAiDocuments() 
           → subCoreAi.callAiDocuments()

---

1. MethodAi.process() - First Call Site

File: gateway/modules/workflows/methods/methodAi.py
Line: 114-119

Context: General AI processing method for workflow actions

result = await self.services.ai.callAiDocuments(
    prompt=aiPrompt,
    documents=chatDocuments if chatDocuments else None,
    options=options,
    outputFormat=output_format
)

Purpose:

• Processes user prompts with optional documents
• Returns formatted output in specified format
• Used for general AI document generation tasks

Parameters:

• prompt: AI prompt (from aiPrompt)
• documents: Optional list of chat documents
• options: AI call options
• outputFormat: Desired output format

---

2. MethodAi.generateImage() - Second Call Site

File: gateway/modules/workflows/methods/methodAi.py
Line: 282-287

Context: Image generation workflow action

result = await self.services.ai.callAiDocuments(
    prompt=promptJson,
    documents=None,
    options=options,
    outputFormat="base64"
)

Purpose:

• Generates images using AI
• Passes prompt as JSON string
• Returns base64 encoded image data

Parameters:

• prompt: JSON string containing image generation prompt
• documents: None (no documents for image generation)
• options: AI call options with image generation settings
• outputFormat: "base64" (returns image as base64 string)

Note: Uses outputFormat="base64" to get image data, not document structure.

---

3. MethodOutlook.sendEmail() - Third Call Site

File: gateway/modules/workflows/methods/methodOutlook.py
Line: 1187-1201

Context: Email composition and sending workflow action

ai_response = await self.services.ai.callAiDocuments(
    prompt=ai_prompt,
    documents=chatDocuments,
    options=AiCallOptions(
        operationType="email_composition",
        priority="normal",
        compressPrompt=False,
        compressContext=True,
        processDocumentsIndividually=False,
        processingMode="detailed",
        resultFormat="json",
        maxCost=0.50,
        maxProcessingTime=30
    )
)

Purpose:

• Generates email content using AI
• Composes email with subject, body, and attachment references
• Processes all documents together for email context

Parameters:

• prompt: AI prompt for email composition
• documents: Chat documents to include in email context
• options: Specialized options for email composition
• outputFormat: Not specified (defaults to text/JSON)

Special Options:

• operationType="email_composition": Specific operation type
• processDocumentsIndividually=False: Process all docs together
• processingMode="detailed": Detailed processing for email quality
• resultFormat="json": Expects JSON response

---

4. ServiceWeb.search() - Fourth Call Site

File: gateway/modules/services/serviceWeb/mainServiceWeb.py
Line: 216-221

Context: Web search service method

searchResult = await self.services.ai.callAiDocuments(
    prompt=searchPrompt,
    documents=None,
    options=searchOptions,
    outputFormat="json"
)

Purpose:

• Performs web search using AI
• Returns search results as JSON with URLs
• Used for finding relevant web content

Parameters:

• prompt: Web search prompt
• documents: None (no documents for search)
• options: AiCallOptions with operationType=WEB_SEARCH
• outputFormat: "json" (expects JSON with URLs)

Options Used:

searchOptions = AiCallOptions(
    operationType=OperationTypeEnum.WEB_SEARCH,
    resultFormat="json"
)

---

5. ServiceWeb.crawl() - Fifth Call Site

File: gateway/modules/services/serviceWeb/mainServiceWeb.py
Line: 275-280

Context: Web crawling service method

crawlResult = await self.services.ai.callAiDocuments(
    prompt=crawlPrompt,
    documents=None,
    options=crawlOptions,
    outputFormat="json"
)

Purpose:

• Crawls web pages using AI
• Extracts and structures web content
• Returns crawled data as JSON

Parameters:

• prompt: Web crawling prompt with URL
• documents: None (no documents for crawling)
• options: AiCallOptions with operationType=WEB_CRAWL
• outputFormat: "json" (expects JSON with crawled content)

Options Used:

crawlOptions = AiCallOptions(
    operationType=OperationTypeEnum.WEB_CRAWL,
    resultFormat="json"
)

---

6. test3_ai_behavior.py - Sixth Call Site (Test)

File: gateway/test3_ai_behavior.py
Line: 83-88

Context: Test script for AI behavior testing

response = await self.services.ai.callAiDocuments(
    prompt=prompt,  # Use the raw user prompt directly
    documents=None,
    outputFormat="json",
    title="Prime Numbers Test"
)

Purpose:

• Testing AI behavior with various prompts
• Specifically tested with "Generate 9000 prime numbers"
• Validates the continuation and looping mechanism

Parameters:

• prompt: Raw user prompt (e.g., "Generate 9000 prime numbers")
• documents: None
• outputFormat: "json" (expects JSON document structure)
• title: Test title ("Prime Numbers Test")

Note: This is a test file, not production code.

---

Summary Table

#	Location	File	Line	Purpose	outputFormat	Has Documents
1	MethodAi.process()	methodAi.py	114	General AI processing	Variable	Optional
2	MethodAi.generateImage()	methodAi.py	282	Image generation	"base64"	No
3	MethodOutlook.sendEmail()	methodOutlook.py	1187	Email composition	Not specified	Yes
4	ServiceWeb.search()	mainServiceWeb.py	216	Web search	"json"	No
5	ServiceWeb.crawl()	mainServiceWeb.py	275	Web crawling	"json"	No
6	AIBehaviorTester.test()	test3_ai_behavior.py	83	Testing	"json"	No

---

Common Patterns

Pattern 1: Document Generation with Format

Used by: MethodAi.process()

await self.services.ai.callAiDocuments(
    prompt=aiPrompt,
    documents=chatDocuments,
    options=options,
    outputFormat=output_format  # html, pdf, docx, txt, etc.
)

Pattern 2: JSON Response

Used by: ServiceWeb.search(), ServiceWeb.crawl(), Test

await self.services.ai.callAiDocuments(
    prompt=prompt,
    documents=None,
    options=options,
    outputFormat="json"
)

Pattern 3: Specialized Operation Types

Used by: MethodOutlook.sendEmail(), ServiceWeb methods

options = AiCallOptions(
    operationType=OperationTypeEnum.EMAIL_COMPOSITION,  # or WEB_SEARCH, WEB_CRAWL
    ...
)
await self.services.ai.callAiDocuments(
    prompt=prompt,
    documents=documents,
    options=options,
    outputFormat=...
)

Pattern 4: Image Generation

Used by: MethodAi.generateImage()

await self.services.ai.callAiDocuments(
    prompt=promptJson,  # JSON string
    documents=None,
    options=options,
    outputFormat="base64"  # Special format for images
)

---

All Routes End Up In:

# mainServiceAi.py (line 142)
return await self.coreAi.callAiDocuments(prompt, documents, options, outputFormat, title)

# subCoreAi.py (line 423)
async def callAiDocuments(...) -> Union[str, Dict[str, Any]]:
    # Builds prompt using buildGenerationPrompt()
    # Calls _callAiWithLooping() for iteration management
    # Handles continuation and completion detection

---

Notes

1. All calls go through the same path: Every callAiDocuments() call routes through mainServiceAi → subCoreAi, which means they all benefit from:

   • The new generic prompt building logic
   • Continuation and looping mechanism
   • JSON repair and section extraction
   • Completion detection

2. Different Use Cases:

   • Document generation (MethodAi, with outputFormat)
   • Image generation (MethodAi, with base64)
   • Email composition (MethodOutlook, with specialized options)
   • Web search/crawling (ServiceWeb, with operation types)
   • Testing (test files)

3. All Use Cases Work: Since subCoreAi.callAiDocuments() uses buildGenerationPrompt(), which is generic and works for any user prompt, all these call sites will work correctly regardless of their specific use case.