passepartout/docs/PROTOCOL_model_discovery.org

PROTOCOL: Model Discovery

• Overview
• 1. The Provider Export Interface
• 2. The Model Explorer Skill (`skill-model-explorer.org`)
  • Dynamic Introspection
  • Org-Table Formatting
• 3. Emacs Actuator Command

Overview

This protocol defines the interfaces allowing the `org-agent` to dynamically introspect available models from any loaded provider skill, outputting the result to Emacs as an Org table.

1. The Provider Export Interface

Every skill acting as a Neural Provider MUST export a function named `GET-AVAILABLE-MODELS`.

;; Signature
(get-available-models) -> list-of-plists

;; Return Format Example
'((:id "gpt-4-turbo" :context "128k")
  (:id "gpt-4o"      :context "128k"))

2. The Model Explorer Skill (`skill-model-explorer.org`)

Dynamic Introspection

The explorer uses the kernel's `(org-agent:context-list-all-skills)` API to find all skills whose name starts with `skill-provider-`.

For each matching skill, it looks up the package:

(let* ((pkg (find-package (intern (string-upcase (format nil "ORG-AGENT.SKILLS.~a" skill-name)) :keyword)))
       (fn (when pkg (find-symbol "GET-AVAILABLE-MODELS" pkg))))
  (when (and fn (fboundp fn))
    (funcall fn)))

Org-Table Formatting

The explorer aggregates the plists and formats them into an Org table string:

| Provider | Model ID | Context |
|----------+----------+---------|
| OpenAI   | gpt-4o   | 128k    |

3. Emacs Actuator Command

The explorer generates a System 2 `approved-action` that instructs the `:emacs` actuator to insert this text.

'(:type :REQUEST 
  :target :emacs 
  :payload (:action :insert-text 
            :text "| Provider | Model ID | Context |\n..."
            :position :after-trigger))