passepartout: v0.4.2 Structured Output

- json-alist-to-plist: JSON alist-to-keyword-plist converter (core-loop-reason)
- provider-openai-request: accept :tools parameter, build tool definitions
  in request body, parse tool_calls from response (system-model-provider)
- think(): build tools from cognitive-tool-registry, pass to backend cascade,
  handle :tool-calls response via json-alist-to-plist (core-loop-reason)
- backend-cascade-call: accept and propagate :tools parameter
- Diagnostics: remove nc/socat from required binaries — health check passes
- Version: 0.4.0 -> 0.4.2 across handshake, ASDF, README badge

lisp/system-model-provider.lisp

@@ -24,8 +24,9 @@
           (url-env (let ((url (uiop:getenv url-env))) (and url (> (length url) 0))))
           (base-url t))))
 
-(defun provider-openai-request (prompt system-prompt &key model (provider :openrouter))
-  "Executes a request against any OpenAI-compatible API endpoint."
+(defun provider-openai-request (prompt system-prompt &key model (provider :openrouter) tools)
+  "Executes a request against any OpenAI-compatible API endpoint.
+When :tools is provided, includes function-calling tool definitions in the request."
   (let* ((config (provider-config provider))
          (base-url (getf config :base-url))
          (key-env (getf config :key-env))
@@ -47,22 +48,42 @@
                     ,@(when (eq provider :openrouter)
                         `(("HTTP-Referer" . "https://github.com/amrgharbeia/passepartout")
                           ("X-Title" . "Passepartout")))))
-         (body (cl-json:encode-json-to-string
-                `((model . ,model-id)
-                  (messages . (( (role . "system") (content . ,system-prompt) )
-                               ( (role . "user") (content . ,prompt) )))))))
+         (body (let ((base `((model . ,model-id)
+                            (messages . (( (role . "system") (content . ,system-prompt) )
+                                         ( (role . "user") (content . ,prompt) ))))))
+                 (if tools
+                     (append base
+                             `((tools . ,(loop for tool in tools
+                                                collect (list (cons :|type| "function")
+                                                              (cons :|function| (loop for (k v) on tool by #'cddr
+                                                                                      collect (cons (intern (string-upcase (string k)) "KEYWORD") v))))))
+                               (:|tool_choice| . "auto")))
+                     base)))
+         (body-json (cl-json:encode-json-to-string body)))
     (handler-case
-        (let* ((response (dex:post url :headers headers :content body
+        (let* ((response (dex:post url :headers headers :content body-json
                                   :connect-timeout (min 10 timeout)
                                   :read-timeout (max 10 (- timeout 5))))
                (json (cl-json:decode-json-from-string response))
                (choices (cdr (assoc :choices json)))
                (first-choice (car choices))
                (message (cdr (assoc :message first-choice)))
+               (tool-calls (cdr (assoc :|tool_calls| message)))
                (content (cdr (assoc :content message))))
-          (if content
-              (list :status :success :content content)
-              (list :status :error :message (format nil "~a: No content" provider))))
+          (cond
+            (tool-calls
+             (list :status :success
+                   :tool-calls
+                   (loop for tc in tool-calls
+                         for fun = (cdr (assoc :|function| tc))
+                         for args-str = (cdr (assoc :|arguments| fun))
+                         for args = (when args-str (cl-json:decode-json-from-string args-str))
+                         collect (list :name (cdr (assoc :|name| fun))
+                                       :arguments args))))
+            (content
+             (list :status :success :content content))
+            (t
+             (list :status :error :message (format nil "~a: No content" provider)))))
       (error (c)
         (list :status :error :message (format nil "~a Failure: ~a" provider c))))))
 
@@ -73,8 +94,8 @@
       (when (provider-available-p provider)
         (log-message "LLM BACKEND: Registering provider ~a" provider)
         (register-probabilistic-backend provider
-          (lambda (prompt system-prompt &key model)
-            (provider-openai-request prompt system-prompt :model model :provider provider)))))))
+          (lambda (prompt system-prompt &key model tools)
+            (provider-openai-request prompt system-prompt :model model :provider provider :tools tools)))))))
 
 (defun provider-cascade-initialize ()
   "Reads PROVIDER_CASCADE from env and sets *provider-cascade*."
@@ -139,3 +160,8 @@ If API-KEY is nil, reads from environment."
   (let ((config (provider-config :openrouter)))
     (fiveam:is (listp config))
     (fiveam:is (getf config :base-url))))
+
+(fiveam:test test-provider-accepts-tools-parameter
+  "Contract 4: provider-openai-request accepts :tools parameter without error."
+  (let ((result (provider-openai-request "test" "system" :tools (list))))
+    (fiveam:is (member (getf result :status) '(:success :error)))))