:PROPERTIES:
:ID:       db56b985-776c-4845-9f38-cc7e9b6af9f1
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: OpenRouter Provider Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :llm:provider:openrouter:unified:psf:

* 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)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 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)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Interfaces for executing neural completion requests via the unified OpenRouter gateway.

** 2. Semantic Interfaces

*** `execute-openrouter-request`
:signature `(execute-openrouter-request prompt system-prompt &key model) :string`
:description "Routes the request through the OpenRouter gateway."

*** `openrouter-get-available-models`
:signature `(openrouter-get-available-models) :list`
:description "Fetches available models from the OpenRouter API."

* Phase D: Build (Implementation)

** Tiered Model Resolution
#+begin_src lisp :tangle ../projects/org-skill-provider-openrouter/src/provider-logic.lisp
(in-package :org-agent)

(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")))
#+end_src

** Request Execution
#+begin_src lisp :tangle ../projects/org-skill-provider-openrouter/src/provider-logic.lisp
(defun execute-openrouter-request (prompt system-prompt &key model)
  (let ((api-key (uiop:getenv "OPENROUTER_API_KEY"))
        (endpoint "https://openrouter.ai/api/v1/chat/completions")
        (model-id (or model (get-openrouter-tiered-model :fast))))
    
    (unless api-key 
      (return-from execute-openrouter-request 
        "(:type :LOG :payload (:text \"OpenRouter API Key missing in environment\"))"))
    
    (let* ((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-ppcre:regex-replace-all "\\\\/" 
                                             (cl-json:encode-json-to-string
                                              `((model . ,model-id)
                                                (messages . (( (role . "system") (content . ,system-prompt) )
                                                             ( (role . "user") (content . ,prompt) )))))
                                             "/")))
      
      (handler-case
          (let* ((response (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30))
                 (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))))))

(defun openrouter-get-available-models ()
  "Fetches available models from OpenRouter."
  (let ((api-key (uiop:getenv "OPENROUTER_API_KEY")))
    (unless api-key (return-from openrouter-get-available-models nil))
    (let ((headers `(("Authorization" . ,(format nil "Bearer ~a" api-key)))))
      (handler-case
          (let* ((response (dex:get "https://openrouter.ai/api/v1/models" 
                                   :headers headers 
                                   :connect-timeout 60 
                                   :read-timeout 60))
                 (json (cl-json:decode-json-from-string response))
                 (data (cdr (assoc :data json)))
                 (results nil))
            (dolist (item data)
              (let ((id (cdr (assoc :id item)))
                    (context-len (cdr (assoc :context--length item))))
                (when id
                  (push (list :id id :context (format nil "~a" (or context-len "unknown"))) results))))
            (nreverse results))
        (error (c) 
          (kernel-log "Model Discovery Error: ~a" c)
          nil)))))
#+end_src

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

;; Export discovery if needed
(setf (fdefinition 'org-agent:openrouter-get-available-models) #'openrouter-get-available-models)

(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))
#+end_src