# PHAEDRA AI ASSISTANT [ rev. 1.3 ]
# 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 configuration via "Model Setup" (sidebar button), enter the key, and click "Save". It will be stored in PHAEDRA.INI.

Note:
Leave the Base 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 # 3. 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-4-argon - Latest model. Expensive. It is a flash 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.

Works for Gemini v3.x. Ignored by gemini-4-argon (the AI decides the temperature on its own).


##### Thinking level:
- Off (Default): Disables the reasoning phase. Recommended for standard Flash models or when conserving tokens and maximizing speed.

- Low: For easy tasks, smaller translations, or corrections (fast response).

- Medium: For medium complexity, e.g., REXX development (medium response time).

- High: For high complexity like algorithm design. Combine 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.


### 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
- UI Activation:

Explicit caching requires the "Explicit Cache" checkbox to be enabled in the AI Assistant sidebar.

- Threshold Activation:

Explicit caching 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.

- 1-Hour Rolling Lifetime (TTL): 

When created, a cache is assigned a 1-hour Time-to-Live. Whenever you submit a prompt within that 1-hour window, Phaedra automatically refreshes the expiration time back to a full 1 hour. Unused caches automatically expire on the server after 1 hour of inactivity.

- Delete Cache:

The [Del Cache] button scans all configured models in PHAEDRA.INI for active explicit caches and prompts for confirmation to delete each one from the server and local configuration.

- 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 1h server cache (25987 bytes)...
  [CACHE] Server cache ready: cachedContents/xxxxxxxxxxxxxxxxxxxx

- Reused Session:

  [CACHE] Active server cache reused (TTL refreshed to 1h).
  [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 3.x Models:

This feature requires a native Google Gemini 3.x model (e.g., gemini-3.8-flash) without a custom Base URL configured. Gemini 4.x models do not support explicit caching and rely on automatic implicit caching instead.

- 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 Files API & Implicit Caching
-------------------------------------------------------------------------------
##### Overview
As an alternative to Explicit Caching, Phaedra supports the Google Gemini Files API. This mode allows instruction files and large document contexts to be uploaded to Google servers as independent file resources instead of transmitting their entire text content inside the request payload.


##### How it works
- UI Activation:

Enable the "Files API" checkbox in the AI Assistant sidebar. Enabling "Files API" automatically unchecks "Explicit Cache", and vice versa (the two modes are mutually exclusive).

- Independent File Uploads:

Each selected instruction file is checked individually against the server cache. New or modified files are converted to UTF-8 and uploaded via Google's resumable raw upload endpoint. If "send tab content" is active, document context can also be transferred via the Files API.

- 48-Hour Lifetime (TTL):

Files uploaded to Google Gemini remain valid on the server for 48 hours. Phaedra tracks uploaded file URIs, file hashes, and timestamps in PHAEDRA.INI under [AI_FILES_CACHE] with an internal 47-hour safety limit. As long as a file has not been modified locally and has not expired, Phaedra reuses the existing file URI immediately without any data transfer.

- Automatic Replacement:

If you modify an instruction file locally, Phaedra detects the change via its file size and timestamp fingerprint, deletes the outdated file from the Google server, and uploads the revised version.

- Profit from Implicit Caching:

A decisive technical advantage of using the Files API for instruction files is Google's Implicit Caching:
1. Phaedra sorts all selected instruction files in strict alphabetical order.
2. In the JSON request, these file references are inserted at the very beginning of the contents array before any dynamic document or user prompt data.
3. Because the prefix of file URIs remains 100% deterministic and identical between requests, Google Gemini's server-side Implicit Prefix Caching automatically kicks in.
4. Unlike Explicit Caching, this implicit cache hit occurs automatically without requiring the strict 20 KB minimum threshold and without requiring manual cache creation calls.

- Diagnostics:

File reuse, uploads, and deletions are logged in the sidebar MLE:
  [FILES] Reusing active file: instructions.txt (files/xxxxxxxxxxxx)
  [FILES] Uploaded: files/yyyyyyyyyyyy


### 1.5 When to use what? (Inline vs. Explicit Cache vs. Files API)
-------------------------------------------------------------------------------

##### Inline Transmission (Both checkboxes unchecked):
- Best for: Small instruction sets (< 20 KB), simple one-off queries, or changing instructions frequently.
- Behavior: Instructions are embedded directly in every request payload. No server resources are retained.

##### Explicit Cache (Checkbox "Explicit Cache" checked):
- Best for: Large, fixed prompt engineering guidelines and documentation dumps exceeding 20 KB that remain static during an extended work session with Gemini 3.x models.
- Behavior: A dedicated 1-hour cache resource is managed on the server. Requires >= 20 KB total size.

##### Files API (Checkbox "Files API" checked):
- Best for: Modular instruction setups of any size (even under 20 KB), large project files, and multi-day projects where files should persist across sessions without re-uploading (up to 48 hours).
- Behavior: Files are stored independently on the server. Leverages Google's automatic Implicit Caching via deterministic file ordering while keeping local request payloads minimal.


### 1.6 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 required wait time does not exceed 15s.

##### 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. Anthropic Claude Integration (Experimental / Untested)
-------------------------------------------------------------------------------

Phaedra contains native protocol support for the Anthropic Claude REST API (Messages API format).

IMPORTANT NOTICE:
This integration has been implemented according to Anthropic's official API specifications, but it is currently NOT YET TESTED under live OS/2 conditions. Regard this feature as experimental.


### 2.1 Configuration & Model Setup
-------------------------------------------------------------------------------

Open "Configure AI" (sidebar button):

- AI Model:
  Select or enter a Claude model name containing "claude" (e.g. claude-sonnet-5.5).

- Base URL:
  Leave the Base URL field COMPLETELY EMPTY. An empty Base URL signals Phaedra to use native Anthropic Messages API handling (https://api.anthropic.com/v1/messages).

- API Key:
  Enter your personal Anthropic API key (starts with sk-ant-...). Phaedra transmits this key via the "x-api-key" header alongside the required "anthropic-version: 2023-06-01" header.


### 2.2 Thinking, Temperature & Caching
-------------------------------------------------------------------------------

- Thinking Mode:
  When a Thinking Level ("Low", "Medium", "High") is configured, Phaedra activates Anthropic extended thinking with dedicated token budgets (2,048 to 16,384 tokens). Anthropic requires temperature to be omitted when thinking is enabled; Phaedra handles this automatically.

- 1-Hour Ephemeral Prompt Caching:
  When the "Explicit Cache" checkbox is active, Phaedra automatically appends the 1-hour ephemeral cache control block ("type": "ephemeral", "ttl": "1h") to system instructions and document context blocks, using the prompt-caching beta header.

- Anthropic Files API:
  When the "Files API" checkbox is active, instruction files are uploaded to Anthropic's /v1/files endpoint as multipart text/plain documents and tracked in PHAEDRA.INI under [AI_ANTHROPIC_FILES_CACHE]. Requests reference them as document content blocks.


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

### 3.1 Configuration
-------------------------------------------------------------------------------

Open "Configure AI" (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.


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


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


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


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


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

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


# 4. 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 "Configure AI" button in the sidebar, and enter there:
- AI Model Name: openrouter/free
- Base URL: https://openrouter.ai/api/v1
- API Key: [Your OpenRouter API key]

3. Save settings via [Save].

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 content" mode must be selected so that the current conversation history is always sent along.

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

# 5. Example: Using Phaedras CBlock Feature
-------------------------------------------------------------------------------

To structure AI responses and take full advantage of Phaedra's CBlock search and selection features, you can instruct the AI (either in your prompt or within system instruction files) to format generated source code using dedicated block markers:

------------------
- CRITICAL FORMATTING RULE FOR ALL CODE BLOCKS:
Whenever you output source code in *any* programming language, you must NOT use standard markdown code blocks (such as ```python, ```rexx, ```json, etc.). 
Instead, you must enclose the entire code block strictly between these exact custom markers:
Starting marker on a new line (with the respective language identifier):
 [language_name]
Ending marker on a new line:

------------------

This enables Phaedra to instantly navigate between code segments using dedicated menu options and shortcuts (such as "Select next AI code block"), allowing you to cleanly isolate, copy, or process source code without tedious manual selection.

For further information on the CBlock feature, please refer to the file README_CBLOCK.TXT (CBlock help).