#+TITLE: SKILL: Model Explorer Agent (Discovery)
#+ID: skill-model-explorer-agent
#+STARTUP: content

* Overview
The **Model Explorer Agent** provides dynamic introspection of the system's LLM capabilities. It intercepts specific user commands to list and describe all available models across all active providers, presenting them in a structured, human-readable format.

* The Discovery Mandate
1. **Transparency:** The user must always be able to see which models are available and their respective context windows.
2. **Determinism:** This is a meta-data retrieval task; it MUST bypass the neural layer to ensure zero-latency, high-fidelity reporting.
3. **Integration:** Results should be rendered as a native Org-mode table for easy parsing and interaction.

* Symbolic Implementation (The Logic)
Because this skill handles internal telemetry and model lists, it operates entirely within the symbolic layer (System 2).

** Architectural Intent: Command Perception
Monitors the user's buffers for the specific `@agent list models` command, triggering the introspection routine.

#+begin_src lisp
(defun trigger-skill-model-explorer (context)
  (let* ((payload (getf context :payload))
         (sensor (getf payload :sensor))
         (text (or (getf payload :text) "")))
    (and (eq sensor :buffer-update)
         (search "@agent list models" text :test #'string-equal))))
#+end_src

** Architectural Intent: Provider Introspection
This function iterates through the skills registry, identifies provider skills, and dynamically calls their `GET-AVAILABLE-MODELS` functions to build a comprehensive list.

#+begin_src lisp
(defun build-org-table-for-models ()
  "Introspects all skills to find providers and builds an Org-mode table string."
  (let ((table-rows (list "| Provider | Model ID | Context |"
                          "|----------+----------+---------|")))
    ;; Iterate through all loaded skills in the kernel
    (maphash (lambda (name skill)
               (when (uiop:string-prefix-p "SKILL-PROVIDER-" (string-upcase name))
                 ;; Extract the provider name cleanly (e.g., "OPENAI")
                 (let* ((provider-name (subseq (string-upcase name) 15))
                        (pkg-name (intern (format nil "ORG-AGENT.SKILLS.~a" (string-upcase name)) :keyword))
                        (pkg (find-package pkg-name))
                        (fn (when pkg (find-symbol "GET-AVAILABLE-MODELS" pkg))))
                   (when (and fn (fboundp fn))
                     (let ((models (funcall fn)))
                       (dolist (model models)
                         (push (format nil "| ~a | ~a | ~a |" 
                                       provider-name 
                                       (getf model :id) 
                                       (getf model :context)) 
                               table-rows)))))))
             org-agent:*skills-registry*)
    (format nil "~{~a~^~%~}" (nreverse table-rows))))
#+end_src

** Architectural Intent: Actuation Dispatch
Constructs the final actuator command to inject the generated table back into the user's Emacs buffer, including automatic alignment.

#+begin_src lisp
(defun execute-skill-model-explorer (proposed-action context)
  "Constructs the Emacs actuator command to insert the table."
  (declare (ignore proposed-action)) ; We don't use System 1's proposal
  (let* ((table-string (build-org-table-for-models))
         ;; We use Emacs lisp to safely insert the table on the next line and align it.
         (elisp-code (format nil "(progn (end-of-line) (insert \"\\n~a\\n\") (search-backward \"| Provider |\") (org-table-align))" table-string)))
    `(:type :REQUEST 
      :target :emacs 
      :payload (:action :eval :code ,elisp-code))))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-model-explorer
  :priority 85 ; High priority to intercept before the general Router
  :trigger #'trigger-skill-model-explorer
  :neuro (lambda (context) nil) ; Bypass System 1
  :symbolic #'execute-skill-model-explorer)
#+end_src