93 lines
3.7 KiB
Org Mode
93 lines
3.7 KiB
Org Mode
:PROPERTIES:
|
|
:ID: ce3bef2a-ff93-49a5-ae5e-acde1de19000
|
|
:CREATED: [2026-03-30 Mon 21:16]
|
|
:EDITED: [2026-04-07 Tue 13:42]
|
|
:END:
|
|
#+TITLE: SKILL: Web Dashboard Agent (Universal Literate Note)
|
|
#+STARTUP: content
|
|
#+FILETAGS: :web:dashboard:telemetry:psf:
|
|
|
|
* Overview
|
|
The *Web Dashboard Agent* provides a lightweight telemetry window into the Neurosymbolic Kernel. It exposes the active skill graph and system logs via a local HTML dashboard.
|
|
|
|
* Phase A: Demand (PRD)
|
|
:PROPERTIES:
|
|
:STATUS: FROZEN
|
|
:END:
|
|
|
|
** 1. Purpose
|
|
Define the interfaces for system observability and telemetry serving.
|
|
|
|
** 2. User Needs
|
|
- *Transparency:* Overview of skill performance (executions, time, failures).
|
|
- *Accessibility:* Served over a local HTTP port.
|
|
- *Observability:* Tail of system logs for debugging.
|
|
- *Low Overhead:* Background execution.
|
|
|
|
** 3. Success Criteria
|
|
*** TODO Server Bootstrap Verification
|
|
*** TODO Telemetry Data Rendering
|
|
*** TODO Log Tail Exposure
|
|
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
:PROPERTIES:
|
|
:STATUS: SIGNED
|
|
:END:
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
|
|
** 1. Architectural Intent
|
|
|
|
The Web Dashboard Agent will function as a lightweight HTTP server exposing key aspects of the Neurosymbolic Kernel's state and logs. It will leverage a simple, efficient rendering mechanism (likely string-based initially) to minimize overhead. Key components include:
|
|
|
|
- *Telemetry Collection:* A mechanism to passively receive skill execution telemetry data from the kernel. This could involve a message queue, shared memory, or direct function calls.
|
|
- *Data Model:* An in-memory representation of the collected telemetry data, optimized for fast rendering.
|
|
- *HTTP Server:* A lightweight HTTP server (e.g., Hunchentoot, embeddable Jetty) to serve the dashboard.
|
|
- *Rendering Engine:* A template-based renderer to generate HTML from the data model. Consider a simple string-based solution for initial implementation.
|
|
- *Log Tail Reader:* A mechanism to efficiently read and expose the tail of the system log file(s).
|
|
|
|
** 2. Semantic Interfaces (Lisp Signatures)
|
|
|
|
*** `telemetry-collector (skill-name start-time end-time success-p)`
|
|
|
|
- *Purpose:* Receives telemetry data from the Neurosymbolic Kernel.
|
|
- *Args:*
|
|
- `skill-name`: Symbol representing the skill (e.g., `'parse-address`).
|
|
- `start-time`: Timestamp (integer or float) of skill execution start.
|
|
- `end-time`: Timestamp (integer or float) of skill execution end.
|
|
- `success-p`: Boolean indicating successful execution (`T` or `NIL`).
|
|
- *Returns:* `T` (acknowledgment).
|
|
- *Side Effects:* Updates the in-memory data model.
|
|
|
|
*** `current-telemetry-data ()`
|
|
|
|
- *Purpose:* Returns the current telemetry data for rendering.
|
|
- *Args:* None.
|
|
- *Returns:* A data structure, likely an alist or plist, containing aggregated telemetry information suitable for rendering. Example:
|
|
```lisp
|
|
(list :total-executions 1234 :successful-executions 1200 :failure-rate 0.027 :last-execution-times (list 1678886400 1678886460 1678886520))
|
|
```
|
|
|
|
*** `system-log-tail (n)`
|
|
|
|
- *Purpose:* Returns the last `n` lines of the system log.
|
|
- *Args:*
|
|
- `n`: Integer representing the number of lines to return.
|
|
- *Returns:* A list of strings, each string representing a line from the log file.
|
|
|
|
*** `start-web-dashboard (port)`
|
|
|
|
- *Purpose:* Starts the HTTP server on the given port.
|
|
- *Args:*
|
|
- `port`: Integer representing the port number.
|
|
- *Returns:* `T` on success, `NIL` on failure.
|
|
- *Side Effects:* Starts the HTTP server in its own thread.
|
|
|
|
*** `stop-web-dashboard ()`
|
|
|
|
- *Purpose:* Stops the HTTP server.
|
|
- *Args:* None.
|
|
- *Returns:* `T` on success, `NIL` on failure.
|
|
- *Side Effects:* Stops the HTTP server.
|