#+TITLE: SKILL: OpenAI Provider Agent (Universal Literate Note)
#+ID: skill-provider-openai
#+STARTUP: content
#+FILETAGS: :llm:provider:openai:gpt:psf:

* Overview
The *OpenAI Provider Agent* integrates OpenAI's GPT models as a pluggable System 1 (neural) backend. It provides industry-standard processing capabilities for reasoning and content generation.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define the interface for reliable communication with the OpenAI Chat Completions API.

** 2. User Needs
- *Compatibility:* Full implementation of the Chat Completions protocol.
- *Reliability:* Secure management of `$OPENAI_API_KEY`.
- *Optimized Inference:* Configurable temperature and model selection (GPT-4o, etc.).
- *Resilience:* Graceful handling of timeouts and errors.

** 3. Success Criteria
*** TODO API Authentication via Bearer Token
*** TODO Chat Payload Construction
*** TODO Choice Extraction Verification


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:

** 1. Architectural Intent
The OpenAI Provider Agent will act as a translator and executor for requests targeting OpenAI's Chat Completions API.  It will abstract away the complexities of API authentication, payload construction, and response parsing, providing a clean and consistent interface for System 1 agents within the Lisp Machine. It prioritizes secure API key management using environment variables and offers configurable parameters for inference.  The architecture focuses on resilience, managing potential API errors (timeouts, rate limits) through robust error handling.

** 2. Semantic Interfaces (Lisp Signatures)

*** `openai-chat-completion`

    - *Purpose:*  Primary function to interact with the OpenAI Chat Completions API.
    - *Signature:* `(openai-chat-completion messages &key model temperature api-key)`
    - *Arguments:*
        - `messages`:  A list of message objects, conforming to the OpenAI Chat Completions API format (e.g., `((:role :system :content "You are a helpful assistant") (:role :user :content "Hello!"))`). Each message is a plist of roles and content keys.
        - `model`: (optional, keyword)  The OpenAI model to use (e.g., `:gpt-4o`, `:gpt-3.5-turbo`). Defaults to a configurable default model.
        - `temperature`: (optional, keyword) The sampling temperature (0.0 - 2.0). Defaults to a configurable default temperature.
        - `api-key`: (optional, keyword) The OpenAI API key. If not provided, defaults to the value of the `$OPENAI_API_KEY` environment variable.
    - *Return Value:* A plist representing the API response.  Crucially, will contain an ` :choices` key, whose value is a list of choices.

*** `construct-chat-payload`

    - *Purpose:*  Constructs the JSON payload for the Chat Completions API from a list of message objects.
    - *Signature:* `(construct-chat-payload messages model temperature)`
    - *Arguments:*
        - `messages`: A list of message objects as described above.
        - `model`: The OpenAI model string.
        - `temperature`: String representation of sampling temperature.
    - *Return Value:*  A JSON string representing the complete payload.

*** `extract-choices`

   - *Purpose:* Extracts the list of choices from the API response.
   - *Signature:* `(extract-choices response)`
   - *Arguments:*
        - `response`:  The API response plist from `openai-chat-completion`.
   - *Return Value:* A list of choice objects (plists).  Typically, the relevant choice contains a `:message` with `:role` and `:content`.

*** `get-openai-api-key`

    - *Purpose:* Retrieves the OpenAI API key.
    - *Signature:* `(get-openai-api-key &optional key-override)`
    - *Arguments:*
        - `key-override:` (optional) The actual API key value, if provided, skip looking for the default $OPENAI_API_KEY environment variable.
    - *Return Value:*  A string representing the API key.  If the environment variable is not found or the `key-override` argument is missing raises an error.  (Security consideration:  API Key should be redacted from logs).

*** `handle-openai-error`

    - *Purpose:*  Handles errors returned by the OpenAI API (e.g., timeouts, rate limiting).
    - *Signature:*  `(handle-openai-error error)`
    - *Arguments:*
        - `error`:  The error object returned by the underlying HTTP client.
    - *Return Value:* Signals an appropriate error condition within the Lisp Machine, potentially including retry logic. (TBD)