:PROPERTIES:
:ID:       a44d29c6-a686-451e-b4e6-b060c3aa7524
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Anthropic Provider Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :llm:provider:anthropic:claude:psf:

* Overview
The *Anthropic Provider Agent* integrates Anthropic's Claude family of models as a pluggable System 1 (neural) backend. It enables high-intelligence reasoning, drafting, and analysis within the PSF.

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

** 1. Purpose
Define the interface for reliable communication with the Anthropic Messages API.

** 2. User Needs
- *Connectivity:* Reliable I/O with Claude models.
- *Configurability:* Model selection via Environment Configuration.
- *Context Management:* Leverage Claude's large context windows.
- *Safety:* Graceful error handling for API failures or missing keys.

** 3. Success Criteria
*** TODO API Authentication
*** TODO Model Resolution Loop
*** TODO Response Parsing Verification


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

* Phase B: Blueprint (PROTOCOL)

** 1. Architectural Intent

The Anthropic Provider Agent will be designed as a stateless service responsible for managing communication with the Anthropic API.  It will abstract away the complexities of API authentication, model selection, prompt construction, and response parsing, exposing a simple, functional interface to the broader PSF.  The key architectural constraint is reliability and efficient context management.  Error handling and API rate limiting must be gracefully managed to prevent cascading failures.

** 2. Semantic Interfaces (Lisp Signatures)

*** `anthropic-query`

This function is the primary entry point for interacting with the Anthropic models. It constructs the full prompt (system prompt + user query), sends it to the Anthropic API, and returns the model's response.

    :lisp
    (defun anthropic-query (query &key model system-prompt max-tokens temperature top-p stream?)
      "Sends a query to the Anthropic API and returns the response.

      QUERY: The user's question or instruction (string).
      MODEL: (Optional) The Claude model to use (string, default 'claude-v1.3').
      SYSTEM-PROMPT: (Optional) A system prompt to guide the model (string).
      MAX-TOKENS: (Optional) The maximum number of tokens in the response (integer).
      TEMPERATURE: (Optional) Sampling temperature (float, 0.0-1.0).
      TOP-P: (Optional) Top-p sampling (float, 0.0-1.0).
      STREAM?: (Optional) Whether to stream the response (boolean, default nil).

      Returns: A string containing the model's generated response, or nil on error."
      ...)

*** `anthropic-authenticate`

This function handles API key authentication. It retrieves the API key from environment variables or a configuration file.

    :lisp
    (defun anthropic-authenticate ()
      "Authenticates with the Anthropic API, retrieving the API key from the environment or config.

      Returns: The API key (string), or nil on failure."
      ...)

*** `anthropic-model-resolve`

This function resolves a symbolic model name (e.g., 'most-powerful') to a specific Claude model identifier (e.g., 'claude-v1.3-100k').

    :lisp
    (defun anthropic-model-resolve (model-symbol)
      "Resolves a symbolic model name to a specific Anthropic model identifier.

      MODEL-SYMBOL: A symbolic name for the model (symbol).

      Returns: The Anthropic model identifier (string), or nil if resolution fails."
      ...)