:PROPERTIES:
:ID:       f3e3a6b3-8cd8-4e64-a835-5cdf5d13b75b
:CREATED:  [2026-04-07 Tue 13:42]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Token Accountant Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :infrastructure:budget:llm:psf:
#+DEPENDS_ON: skill-router

* Overview
The *Token Accountant* is the governor of the Neural Engine. it manages the cost and reliability of LLM providers on-the-fly.

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Maintain a dynamic, state-aware provider cascade. Detect provider "pain" (errors) and autonomously route around them.

** 2. Semantic Interfaces

*** Dynamic Routing Logic
#+begin_src lisp :tangle ../projects/org-skill-token-accountant/src/accountant-logic.lisp
(in-package :org-agent)

(defvar *provider-pain-table* (make-hash-table :test 'equal))

(defun token-accountant-record-pain (provider)
  "Marks a provider as 'pained' (failed). It will be de-prioritized."
  (setf (gethash provider *provider-pain-table*) (+ (get-universal-time) 600)) ; 10 min penalty
  (kernel-log "ACCOUNTANT - Provider ~a de-prioritized due to failure." provider))

(defun token-accountant-get-cascade (context)
  "Returns a dynamic list of providers, routing around pained ones."
  (let ((all-providers '(:openrouter :groq :gemini))
        (healthy nil)
        (pained nil)
        (now (get-universal-time)))
    (dolist (p all-providers)
      (if (> (or (gethash p *provider-pain-table*) 0) now)
          (push p pained)
          (push p healthy)))
    (append (nreverse healthy) (nreverse pained))))


(defun token-accountant-get-model-for-provider (provider &optional context)
  "Returns the recommended model for the provider."
  (case provider
    (:openrouter "moonshotai/kimi-k2.5")
    (:groq "llama-3.3-70b-versatile")
    (:gemini "gemini-1.5-flash-latest")
    (t nil)))

(defun token-accountant-patch-kernel ()
  "Hot-patches the kernel's cascade and model selector to use our dynamic logic."
  (setf org-agent:*provider-cascade* #'token-accountant-get-cascade)
  (setf org-agent:*model-selector-fn* #'token-accountant-get-model-for-provider))
#+end_src

* Registration
#+begin_src lisp
(progn
  (token-accountant-patch-kernel)
  (defskill :skill-token-accountant
    :priority 100
    :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :tool-error))
    :neuro (lambda (context) nil)
    :symbolic (lambda (action context) 
                (let ((p (getf (getf context :payload) :provider)))
                  (when p (token-accountant-record-pain p))
                  action))))
#+end_src