# 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  Explicit Context Caching
-------------------------------------------------------------------------------
##### Overview
When using native Google Gemini models, Phaedra supports server-side Explicit Context Caching for system instruction files. 

Instead of re-uploading large sets of system instructions with every single request, Phaedra automatically compiles them into a cached context object directly on the Google API servers.


##### How it works
- Threshold Activation:
Explicit caching automatically engages when the combined size of all selected instruction files reaches or exceeds 20 KB (approx. 5,000+ tokens).
Instructions below 20 KB are passed inline without overhead.

- Model-Bound Cache:
Caches are tied to the specific AI model currently selected (e.g., gemini-3.8-flash). Switching models automatically references or creates a dedicated cache for the target model.

- 48-Hour Rolling Lifetime (TTL): 
When created, a cache is assigned a 48-hour Time-to-Live. Whenever you submit a prompt within that 48-hour window, Phaedra automatically refreshes the expiration time back to a full 48 hours. Unused caches automatically expire on the server after 48 hours of inactivity.

- Automatic Invalidation:
If you edit an instruction file, select/deselect files in the list, or change file contents, Phaedra detects the change via a file fingerprint check and replaces the server cache on the next request.


##### Benefits
- Cost Reduction:
Cached input tokens are billed at a significantly reduced rate (up to 75-90%  discount compared to standard input token pricing).

- Reduced Latency:
Local request payloads shrink from tens of kilobytes down to a few hundred bytes, speeding up network transfers over slow connections and reducing Time-To-First-Token (TTFT) processing time on the server.


##### Diagnostics & Logging
You can monitor the status of the cache in the AI Assistant sidebar log:

- Initial Creation:
  [CACHE] Creating new 48h server cache (25987 bytes)...
  [CACHE] Server cache ready: cachedContents/xxxxxxxxxxxxxxxxxxxx

- Reused Session:
  [CACHE] Active server cache reused (TTL refreshed to 48h).
  [INFO] Sizes - Instr: (CACHED) | ...
  [INFO] Tokens - Input: 7663 (Cached: 7645) | Output: 11 | Total: 7674

The "(Cached: >0)" counter confirms that the server successfully read the tokens directly from the persistent KV-cache.


##### Requirements & Limitations
- Native Gemini API:
This feature requires a Google Gemini model without a custom OpenAI-compatible Base URL configured.

- OpenAI-Compatible Endpoints:
Third-party providers and standard OpenAI endpoints do not support explicit cache endpoints; they utilize automatic implicit prefix caching instead.


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


# 3. Example: Using Free AIs via OpenRouter with Phaedra
-------------------------------------------------------------------------------

Since Phaedra supports the OpenRouter interface for AIs, you can use a service from OpenRouter that connects you to a free AI service with every request.

1. Create an account at OpenRouter and generate an API key:
https://openrouter.ai/

2. In Phaedra, call up the AI Setup via the "Model Setup" button in the sidebar, and enter there
- AI Model Name: openrouter/free
- API URL: https://openrouter.ai/api/v1
- API Key: [Your OpenRouter API key]

3. Save settings [Save]. Voila.

Now OpenRouter decides with every request which free AI is sensible for the request and forwards everything.

Notes:
OpenRouter is like other AIs "stateless", meaning the AI does not remember the chat history. Every request is independent for the AI, it does not remember previous questions. This is like with an assistant who starts from zero in every conversation. To conduct a longer chat, the "Dialog" function under AI Answer can be selected. Phaedra then posts the AI answers at the end of the current editor tab.

Also, the "Send Tab" mode must be selected in the footer so that the current conversation history is always sent along.

By the way, other AI assistants do exactly the same, only sometimes invisibly "under the hood".

Practical tip: for longer chats, occasionally let the AI give you a summary of the content, copy this, and start a new fresh tab/chat with it.

