112 lines
5.6 KiB
Org Mode
112 lines
5.6 KiB
Org Mode
:PROPERTIES:
|
|
:ID: f6c16640-1875-4d34-8b7a-cbad1c4ce036
|
|
:CREATED: [2026-03-30 Mon 21:16]
|
|
:EDITED: [2026-04-07 Tue 13:42]
|
|
:END:
|
|
#+TITLE: SKILL: Brain Mapper Agent (Universal Literate Note)
|
|
#+STARTUP: content
|
|
#+FILETAGS: :meta-cognition:telemetry:psf:
|
|
|
|
* Overview
|
|
The *Brain Mapper Agent* provides the system with meta-cognitive capabilities. It enables visualization and optimization of the internal "Skill Graph" through real-time telemetry analysis.
|
|
|
|
* Phase A: Demand (PRD)
|
|
:PROPERTIES:
|
|
:STATUS: FROZEN
|
|
:END:
|
|
|
|
** 1. Purpose
|
|
Define the interfaces for self-introspection and skill hierarchy optimization.
|
|
|
|
** 2. User Needs
|
|
- *Transparency:* Explain cognitive hierarchy and decision priorities.
|
|
- *Self-Optimization:* Proactive priority adjustment suggestions.
|
|
- *Introspection:* Identify bottleneck or failing skills.
|
|
|
|
** 3. Success Criteria
|
|
*** TODO Introspective Trigger Verification
|
|
*** TODO Telemetry Synthesis Accuracy
|
|
*** TODO Optimization Command Generation
|
|
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
|
|
** 1. Architectural Intent
|
|
|
|
The Brain Mapper Agent will leverage two primary functional components: a *Telemetry Collector* and an *Optimizer*. The *Telemetry Collector* aggregates real-time data from the Skill Graph, providing a comprehensive view of skill performance and resource utilization. The *Optimizer* analyzes this telemetry, identifies areas for improvement, and generates commands to adjust skill priorities or restructure the Skill Graph. The architecture prioritizes modularity and extensibility, allowing for the integration of new telemetry sources and optimization strategies. The agent shall also expose data in common knowledge representation formats such as the Semantic Web and RDF.
|
|
|
|
** 2. Semantic Interfaces
|
|
|
|
*** 2.1 Telemetry Collector
|
|
|
|
The Telemetry Collector provides functions for registering telemetry sources and retrieving aggregated data.
|
|
|
|
**** register-telemetry-source
|
|
:description Registers a new source of telemetry data.
|
|
:signature `(register-telemetry-source source-name telemetry-function &key interval description)`
|
|
:parameters
|
|
- `source-name`: A symbol representing the unique identifier of the telemetry source (e.g., 'inference-engine-latency).
|
|
- `telemetry-function`: A function that, when called, returns the current telemetry value.
|
|
- `interval`: (Optional) The frequency, in seconds, at which the telemetry function should be called. Defaults to 60 seconds.
|
|
- `description`: (Optional) A string describing the telemetry source.
|
|
:returns `T` if the telemetry source was successfully registered; `NIL` otherwise.
|
|
:example `(register-telemetry-source 'skill-activation-count (lambda () (get-skill-activation-count 'reasoning-skill)) :interval 10 :description "Number of times the reasoning skill was activated per 10 seconds.")`
|
|
|
|
**** get-telemetry-data
|
|
:description Retrieves aggregated telemetry data for a specified source or all sources.
|
|
:signature `(get-telemetry-data &optional source-name)`
|
|
:parameters
|
|
- `source-name`: (Optional) A symbol representing the name of the telemetry source. If omitted, data for all registered sources is returned.
|
|
:returns A list of telemetry data entries. Each entry is an association list containing the 'timestamp and 'value. Or an error if source-name is not registered.
|
|
:example `(get-telemetry-data 'inference-engine-latency)`
|
|
|
|
*** 2.2 Optimizer
|
|
|
|
The Optimizer provides functions for analyzing telemetry data and generating optimization commands.
|
|
|
|
**** analyze-telemetry
|
|
:description Analyzes telemetry data to identify areas for improvement.
|
|
:signature `(analyze-telemetry)`
|
|
:parameters None
|
|
:returns A list of optimization suggestions. Each suggestion is an association list containing at least the 'skill, 'metric, and 'recommendation keys.
|
|
:example `(analyze-telemetry)`
|
|
|
|
**** generate-optimization-command
|
|
:description Generates an optimization command based on a given suggestion.
|
|
:signature `(generate-optimization-command suggestion)`
|
|
:parameters
|
|
- `suggestion`: An association list representing an optimization suggestion, as returned by `analyze-telemetry`.
|
|
:returns A Lisp form representing the optimization command. This command is NOT automatically executed.
|
|
:example `(generate-optimization-command (first (analyze-telemetry)))`
|
|
|
|
**** execute-optimization-command
|
|
:description Executes a given optimization command.
|
|
:signature `(execute-optimization-command command)`
|
|
:parameters
|
|
- `command`: A Lisp form representing the optimization command, as returned by `generate-optimization-command`.
|
|
:returns `T` if the command was successfully executed; `NIL` otherwise.
|
|
:example `(let ((suggestion (first (analyze-telemetry)))) (execute-optimization-command (generate-optimization-command suggestion)))`
|
|
|
|
*** 2.3 Introspection Functions (For Transparency)
|
|
|
|
**** describe-skill-hierarchy
|
|
:description Returns a human-readable description of the current skill hierarchy.
|
|
:signature `(describe-skill-hierarchy)`
|
|
:parameters None
|
|
:returns A string representing the skill hierarchy.
|
|
:example `(describe-skill-hierarchy)`
|
|
|
|
**** explain-decision-priority
|
|
:description Explains the decision priority for a given skill or decision point.
|
|
:signature `(explain-decision-priority skill-name)`
|
|
:parameters
|
|
- `skill-name`: A symbol representing the name of the skill or decision point.
|
|
:returns A string explaining the decision priority, including the factors that influenced it.
|
|
:example `(explain-decision-priority 'reasoning-skill)`
|
|
|