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

* Overview
The *Token Accountant* is the governor of the Neural Engine. It manages the cost, reliability, and routing of LLM providers. Its primary mission is to ensure the PSF operates at maximum intelligence with minimum marginal cost by aggressively prioritizing subsidized free models when appropriate.

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

** 1. Purpose
Autonomously manage the provider cascade and model selection to optimize for cost, speed, and reliability.

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

** 1. Architectural Intent
Maintain a state-aware provider cascade that routes around "pain" (failures) and dynamically selects models based on task complexity.

** 2. Semantic Interfaces

*** Routing and Pain Management
#+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, prioritizing free/subsidized models. Updated April 2026."
  (let ((complexity (ignore-errors (uiop:symbol-call :org-agent.skills.org-skill-router :router-classify-complexity context))))
    (case provider
      (:openrouter
       (case complexity
         (:REASONING "meta-llama/llama-3.3-70b-instruct:free") ; High fidelity, zero cost
         (:COGNITION "qwen/qwen3.6-plus:free")               ; Latest interaction, zero cost
         (t "meta-llama/llama-3.2-3b-instruct:free")))       ; Ultra-fast reflex, zero cost
      (:groq
       (case complexity
         (:REASONING "llama-3.3-70b-versatile")
         (t "llama-3.1-8b-instant")))
      (: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) 
               (let ((sensor (getf (getf context :payload) :sensor)))
                 (or (eq sensor :tool-error) (eq sensor :cost-audit))))
    :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