memex/notes/org-skill-provider-openrouter.org

SKILL: OpenRouter Provider Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Tiered Model Resolution
  • Request Execution
• Registration

Overview

The OpenRouter Provider Agent acts as a unified gateway to hundreds of LLMs. It provides flexibility by dynamically switching between models based on intelligence tiers while maintaining architectural alignment.

Phase A: Demand (PRD)

1. Purpose

Define the interface for unified communication with the OpenRouter API.

2. User Needs

• Abstraction: OpenAI-compatible interface for all OpenRouter models.
• Dynamic Routing: Support for intelligence tiers (:POWERFUL, :FAST, :FREE).
• Resilience: Leverage auto-routing fallbacks.
• Transparency: Proper identification via Referer and Title headers.

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Interfaces for executing neural completion requests via the unified OpenRouter gateway.

2. Semantic Interfaces

(defun execute-openrouter-request (prompt system-prompt)
  "Executes a completion request via the OpenRouter API.")

(defun get-openrouter-tiered-model (tier)
  "Returns the preferred model ID for a given tier.")

Phase D: Build (Implementation)

Tiered Model Resolution

(defun get-openrouter-tiered-model (tier)
  (case tier
    (:powerful "anthropic/claude-3.5-sonnet")
    (:fast "google/gemini-2.0-flash-001")
    (:free "openrouter/auto")
    (t "openrouter/auto")))

Request Execution

(defun execute-openrouter-request (prompt system-prompt)
  (let ((api-key (uiop:getenv "OPENROUTER_API_KEY"))
        (endpoint "https://openrouter.ai/api/v1/chat/completions"))
    
    (unless api-key 
      (return-from execute-openrouter-request 
        "(:type :LOG :payload (:text \"OpenRouter API Key missing in environment\"))"))
    
    (let* ((model (get-openrouter-tiered-model :fast))
           (headers `(("Content-Type" . "application/json")
                      ("Authorization" . ,(format nil "Bearer ~a" api-key))
                      ("HTTP-Referer" . "https://github.com/amr/org-agent")
                      ("X-Title" . "org-agent Sovereign Kernel")))
           (body (cl-json:encode-json-to-string
                  `((model . ,model)
                    (messages . (( (role . "system") (content . ,system-prompt) )
                                 ( (role . "user") (content . ,prompt) )))))))
      
      (handler-case
          (let* ((response (dex:post endpoint :headers headers :content body))
                 (json (cl-json:decode-json-from-string response)))
            ;; Extract content from OpenAI-style response: choices[0].message.content
            (cdr (assoc :content (cdr (assoc :message (car (cdr (assoc :choices json))))))))
        (error (c)
          (format nil "(:type :LOG :payload (:text \"OpenRouter Error: ~a\"))" c))))))

Registration

;; Register the backend with the kernel at load-time
(org-agent:register-neuro-backend :openrouter #'execute-openrouter-request)

;; Update the cascade to prefer OpenRouter
(setf org-agent:*provider-cascade* '(:openrouter :gemini))

(defskill :skill-provider-openrouter
  :priority 100
  :trigger (lambda (context) nil) ; Provider skills don't trigger OODA loops
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) action))