memex/notes/org-skill-web-interface.org

SKILL: Web Dashboard Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Server Bootstrap Verification
    • Telemetry Data Rendering
    • Log Tail Exposure
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces (Lisp Signatures)
    • `telemetry-collector (skill-name start-time end-time success-p)`
    • `current-telemetry-data ()`
    • `system-log-tail (n)`
    • `start-web-dashboard (port)`
    • `stop-web-dashboard ()`

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)

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)

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.