#+TITLE: SKILL: Native Function Calling (Universal Literate Note)
#+ID: skill-function-calling
#+STARTUP: content
#+FILETAGS: :llm:tools:json-schema:reliability:psf:
#+DEPENDS_ON: org-skill-org-json-bridge

* Overview
The *Native Function Calling* skill provides the translation layer between the system's deterministic Lisp interfaces and the LLM's neural tool-calling capabilities. It ensures that System 1 (the LLM) interacts with the world via structured, validated schemas rather than raw text plists, virtually eliminating "formatting hallucinations."

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define a high-reliability bridge for LLM-native "Tool Use."

** 2. User Needs
- *Schema Generation:* Automatically convert Lisp `defun` signatures into JSON Schema tool definitions.
- *Reliable Ingress:* Parse the LLM's structured `tool_calls` response back into a valid Lisp plist.
- *Provider Agnostic:* Support schema formats for Gemini, OpenAI, and Anthropic.
- *Validation:* Ensure arguments match the required types before reaching System 2.

** 3. Success Criteria
*** TODO Lisp-to-JSON Schema conversion logic verification
*** 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:

** 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.")

(defun normalize-tool-call (raw-response)
  "Parses the LLM response and returns a standard :REQUEST action plist.")
#+end_src

* Phase D: Build (Implementation)

** 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

** 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

* 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