wiki/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

```python
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

```python
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

```python
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

```python
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**:
```python
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

```python
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**:
```python
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

```python
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()
```python
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
```python
await self.services.ai.callAiDocuments(
    prompt=prompt,
    documents=None,
    options=options,
    outputFormat="json"
)
```

### Pattern 3: Specialized Operation Types
Used by: MethodOutlook.sendEmail(), ServiceWeb methods
```python
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()
```python
await self.services.ai.callAiDocuments(
    prompt=promptJson,  # JSON string
    documents=None,
    options=options,
    outputFormat="base64"  # Special format for images
)
```

---

## All Routes End Up In:

```python
# 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.