# Phaedra AI Assistant (Google Gemini Integration)
-------------------------------------------------------------------------------

Phaedra features a direct connection to the Google Gemini REST API.
The integration runs completely natively under OS/2 via Classic REXX and cURL.


### 1. Prerequisites & Installation
-------------------------------------------------------------------------------

- cURL (Package: curl)
  Required for HTTPS communication with the Google REST API.
  Installation via YUM:
  yum install curl

- iconv (Package: libiconv / libiconv-utils)
  Mandatory for conversion between OS/2 CP850 and UTF-8.
  Installation via YUM:
  yum install libiconv-utils

- Google Gemini API Key
  A personal API key is required for access.
  - Create one at https://aistudio.google.com/ (Google account required).
  - Setup in Phaedra: Open menu "Tools" -> "AI Setup", enter the key, and click "Save". It will be stored in PHAEDRA.INI.

Note on API Conditions:
Free Google accounts (Free Tier) are subject to strict rate limits (HTTP 429).
For reliable work, a project with billing enabled (Pay-as-you-go) is recommended; monthly costs can be strictly capped using budget limits.

Attention: Phaedra currently only supports paid models.


### 2. Opening & Using the AI Assistant
-------------------------------------

#### 1. Basic Console:
Menu "Tools" -> "AI console" reveals the prompt input field below the editor area.
   
- [Send]: Sends the current prompt. Controls are temporarily locked during transmission to prevent PM freezes.
   
- [send tab content]: 
The Gemini API is stateless. If active, Phaedra includes context from the current document:
 - If text is SELECTED in the editor, ONLY this selected section is sent to the AI as context.
 - If NO text is selected, the complete content of the current tab is sent along as background information.

- [Cancel]: Closes the AI console and restores full editor height.

#### 2. Extended Sidebar (Button ">>"):
   Clicking ">>" opens the detailed control panel:

##### AI Model:
- gemini-3.8-flash       - Default. High speed and quality.
- gemini-3.5-flash-lite  - Maximum throughput, minimal latency.
- gemini-3.1-pro-preview - Highest accuracy for complex tasks and programming.

##### Temperature:
Controls the level of creativity (0.0 to 2.0, in 0.1 steps).
- 0.0 (Strict): Deterministic, recommended for source code and REXX.
- 0.7 (Default): Balanced ratio for general tasks.
- 1.0+: High creativity for text formulations.

##### Thinking level
- Low: for easy tasks, smaller translations or corrections (fast response)
- Medium (Default): for medium complexity, good e.g. for REXX development (medium response time)
- High: for high complexity like algorithms. Combine it with pro-models.

##### AI Answer (Insertion modes into the editor):
- Append : Appends the answer at the end of the document.
- Insert : Inserts the answer at the current text mark (cursor).
- Replace: Replaces the entire content of the current tab.
- Dialog : Appends prompt (prefixed with '>') and answer structured by divider lines at the end of the document. Ideal in combination with "send tab content" for ongoing chats.

##### AI Instructions (System Prompts):
Defines fixed behavioral rules for the model.
- Folder: Place simple text files in the "\aiinstructions\" directory located below your Phaedra directory.
- Selection: Select the desired rule files in the container. 
Phaedra combines all selected instructions in the request.

#####  Log:
Logs timestamps, HTTP status codes, cURL errors, and event messages for diagnostics.


### 3. Network, Rate Limits & OS/2 Buffers
-------------------------------------------------------------------------------

##### HTTP 429 (Rate Limit): 
If requests are throttled server-side, Phaedra performs up to 3 automatic retries with backoff, provided the wait time is under 3s.

##### 32 KB Line Limit: 
The OS/2 Presentation Manager MLE has a hard line limit of 32 KB. Phaedra automatically scans incoming API responses and wraps overly long lines to prevent crashes of the PM component.

##### Document Size: 
Very large documents increase data volume and can temporarily halt the synchronous UI during cURL transmission. For large source code files, prefer using targeted text selection.




