# PHAEDRA AI ASSISTENT
# 1. 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.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 "Model Setup" (sidebar), enter the key, and click "Save". It will be stored in PHAEDRA.INI.
Note:
Leave the API Url field empty if you want to use Phaedra's native Gemini handling. 
Enter a Base URL if you want to use Gemini via an OpenAI-compatible API. Both are possible. For details refer to chapter # OpenAI-Compatible API.

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.


### 1.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.6-flash - Free tier model with limitations.
- 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, 0.0 to 0.2 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.
- Off: to disable the reasoning phase. 
"Off" is the recommended setting when:
- Using Standard Models: The selected model does not support the reasoning API (e.g., standard Flash models). Using "Low/Medium/High" on these models will result in an API error.
- Speed is Priority: You need the fastest possible response with minimal latency.
- Simple Tasks: You are doing straightforward tasks like translation, text formatting, or basic code completion that do not require deep logical analysis.
- Conserving Tokens: You want to save your API token quota, as hidden "thinking tokens" consume your total output budget.

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


### 1.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.


# 2. OpenAI-Compatible API
-------------------------------------------------------------------------------

Phaedra also supports AI providers that expose an OpenAI-compatible REST API.
This allows users to connect Phaedra to a wide range of AI providers without requiring provider-specific integration.

The OpenAI-compatible interface is configured by specifying the provider's Base URL, API key, and model ID.

### 2.1 Configuration
-------------------------------------------------------------------------------

Open "Model Setup" (sidebar) to configure an OpenAI-compatible provider.

- AI Model
  The model ID expected by the selected provider.
  Example:
  openai/gpt-oss-120b

- Base URL
  The base URL of the OpenAI-compatible API.
  Example for the official OpenAI API:
  https://api.openai.com/v1

  Other providers may use different Base URLs, for example:
  https://api.groq.com/openai/v1
  https://openrouter.ai/api/v1

- API Key
  The API key provided by the selected AI provider.
  Phaedra sends the key using HTTP Bearer authentication.


The model configuration is stored in PHAEDRA.INI.

Users can configure their own provider and model as long as the provider supports the required OpenAI-compatible API interface.

### 2.2 Example: Groq / OpenAI GPT-OSS
-------------------------------------------------------------------------------

The following configuration can be used as an example for the Groq API:

- Model:
  openai/gpt-oss-120b

- Base URL:
  https://api.groq.com/openai/v1

- API Key:
  Your Groq API key.
  Create an account or log in at:
  https://console.groq.com/keys
  Then click "Create API Key".

Note on API Conditions:
Availability, rate limits and pricing depend on the selected provider and account type.
For example, the free tier of the example model is limited to 8,000 tokens per minute.
This may make it unsuitable for large prompts, source or instrcution files.


### 2.3 OpenAI-Compatible API Requirements
-------------------------------------------------------------------------------

Phaedra expects the provider to support the following interface:

- HTTP POST request to:
  <Base URL>/chat/completions

- Authentication:
  Authorization: Bearer <API-Key>

- Content type:
  Content-Type: application/json

- Request data:
  model
  messages
  temperature
  reasoning_effort

The exact availability of individual parameters depends on the selected model and provider.
If a model does not support reasoning_effort, select "Off" as the Thinking level.

### 2.4 AI Models
-------------------------------------------------------------------------------

Unlike the native Gemini integration, Phaedra does not maintain a fixed model list for OpenAI-compatible providers.

Users may configure any compatible model offered by their provider.

Examples include:
- OpenAI models
- Groq models
- OpenRouter models
- Other providers offering an OpenAI-compatible API

For models using provider-specific model IDs, enter the exact model ID supplied by the provider.

### 2.5 AI Instructions, Answer Modes and Logging
-------------------------------------------------------------------------------

The same AI Instructions, AI Answer insertion modes and diagnostic logging described above are also available for OpenAI-compatible providers.

AI Instructions are transmitted as system instructions where supported by the selected API.

The available Thinking levels depend on the capabilities of the selected model.
Phaedra passes the selected reasoning level to OpenAI-compatible APIs using the reasoning_effort parameter when enabled.


### 2.6 Network, Rate Limits & OS/2 Buffers
-------------------------------------------------------------------------------

The same OS/2-specific limitations described in the Gemini section also apply to OpenAI-compatible providers.
