PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-function-calling.org

@@ -26,50 +26,60 @@ Define a high-reliability bridge for LLM-native "Tool Use."
 *** TODO Multi-provider schema formatting (Gemini vs OpenAI)
 *** TODO Response parsing from tool_call to symbolic action
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: DRAFT
+:END:
+
 ** 1. Architectural Intent
-Interfaces for schema translation and response normalization. Source of truth is the Lisp signatures in the `PROTOCOL.org` blocks.
 
-** 2. Semantic Interfaces
-#+begin_src lisp
-(defun lisp-signature-to-schema (fn-name params docstring)
-  "Transforms a Lisp function definition into a JSON Schema tool object.")
+The core intent is to create a robust, bi-directional translation layer. This layer guarantees type safety and schema adherence between the LLM's Tool Calling mechanism and the Lisp environment.  The design emphasizes clear separation of concerns: schema generation, response parsing, and provider-specific formatting.  We should aim for a modular architecture that allows for easier extension to new LLM providers and new data types. The validation process must be explicit and easily auditable.  Error handling is critical; parsing failures should yield informative error messages, enabling rapid debugging.
 
-(defun normalize-tool-call (raw-response)
-  "Parses the LLM response and returns a standard :REQUEST action plist.")
-#+end_src
+** 2. Semantic Interfaces (Lisp Signatures)
 
-* Phase D: Build (Implementation)
+*** `defun json-schema-from-defun (function-name)`
+     - *Purpose:* Generates a JSON Schema representation from a Lisp function definition.
+     - *Args:*
+       - `function-name`: A symbol representing the name of the Lisp function.
+     - *Returns:*  A Lisp plist representing the JSON Schema. Keys should correspond to standard JSON Schema fields (e.g., `:type`, `:properties`, `:required`).
+     - *Side Effects:* None.  Pure function.
 
-** Schema Generator
-#+begin_src lisp :tangle projects/org-skill-function-calling/src/calling-logic.lisp
-(defun lisp-signature-to-schema (fn-name params docstring)
-  "Simplified schema generator for the refactor."
-  (let ((schema `((:name . ,(string-downcase (string fn-name)))
-                  (:description . ,docstring)
-                  (:parameters . ((:type . "object")
-                                  (:properties . ,(loop for p in params 
-                                                       collect (cons p '((:type . "string"))))))))))
-    schema))
-#+end_src
+*** `defun parse-tool-call-arguments (function-name arguments tool-provider)`
+     - *Purpose:* Parses the arguments returned by an LLM tool call into a Lisp plist. Validates the arguments against the schema generated by `json-schema-from-defun`.
+     - *Args:*
+       - `function-name`: A symbol representing the name of the Lisp function being called.
+       - `arguments`: A string containing the JSON arguments returned by the LLM's `tool_calls` field.
+       - `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider.
+     - *Returns:* A Lisp plist representing the parsed arguments, or `nil` if parsing fails.  On failure, appropriate error messages should be logged.
+     - *Side Effects:* May signal errors.
 
-** Kernel Integration
-#+begin_src lisp :tangle projects/org-skill-function-calling/src/calling-logic.lisp
-(defun get-available-tools ()
-  "Gathers all registered Lisp interfaces and returns them as a JSON Schema array."
-  ;; Logic to scan skills-registry and collect function signatures
-  nil)
-#+end_src
+*** `defun format-json-schema-for-provider (json-schema tool-provider)`
+     - *Purpose:*  Formats the automatically generated JSON schema to the specific format required by each LLM provider.
+     - *Args:*
+       - `json-schema`: A Lisp plist containing the generic JSON schema (output of `json-schema-from-defun`).
+       - `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider.
+     - *Returns:* A Lisp plist representing the provider-specific JSON schema.
+     - *Side Effects:* None. Pure function.
+
+*** `defun validate-arguments (function-name arguments)`
+     - *Purpose:*  Validates that the parsed arguments conform to the expected schema.
+     - *Args:*
+       - `function-name`:  A symbol identifying the function being called. Used to retrieve the function definition and associated JSON schema.
+       - `arguments`: A Lisp plist containing the parsed arguments.
+     - *Returns:* `T` if validation succeeds, `NIL` if it fails.
+     - *Side Effects:* May signal errors if validation fails. Logs validation errors.
+
+** 3. Data Structures
+
+*** JSON Schema (Lisp Representation)
+     A Lisp plist mimicking the structure of a JSON Schema.  Keys will generally be keywords mirroring JSON Schema vocabulary (e.g., `:type`, `:properties`, `:required`, `:description`). Values will be Lisp datatypes corresponding to the schema datatypes (e.g., symbols, strings, booleans, numbers, lists of symbols/strings/numbers).
+
+*** Tool Call Response
+     The expected format of an LLM's `tool_calls` response will be parsed using a dedicated JSON parsing library. `parse-tool-call-arguments` will handle the conversion to lisp datatypes based upon the `json-schema`
 
-* Registration
-#+begin_src lisp
-(defskill :skill-function-calling
-  :priority 100 ; Foundational bridge
-  :trigger (lambda (context) nil)
-  :neuro (lambda (context) nil)
-  :symbolic (lambda (action context) action))
-#+end_src