253 lines
14 KiB
Org Mode
253 lines
14 KiB
Org Mode
#+TITLE: Peripheral Vision (context.lisp)
|
|
#+AUTHOR: Amr
|
|
#+FILETAGS: :harness:context:
|
|
#+STARTUP: content
|
|
|
|
* Peripheral Vision (context.lisp)
|
|
** Architectural Intent: Context Optimization & The Foveal-Peripheral Hybrid
|
|
|
|
A common failure mode for Large Language Models (LLMs) is the "Lost in the Middle" phenomenon, where the model's reasoning accuracy degrades as its context window becomes saturated with irrelevant data. Naive approaches to context management—such as simple character-count truncation or sliding windows—often sever the structural relationships that define an Org-mode Memex.
|
|
|
|
The ~org-agent~ harness implements a deterministic, tree-aware solution: the **Foveal-Peripheral Hybrid Model**.
|
|
|
|
*** 1. The Foveal Focus (High Resolution)
|
|
When the harness prepares a prompt for the Probabilistic Engine, it identifies a "Foveal Focus"—typically the specific Org headline or task the user is currently interacting with. This node, along with its immediate children and semantically relevant neighbors, is rendered at "High Resolution," meaning its full body text, properties, and metadata are included in the prompt.
|
|
|
|
*** 2. The Peripheral Vision (Low Resolution)
|
|
To maintain global awareness without bloating the context window, the rest of the Memex is rendered at "Low Resolution." The harness recursively walks the Object Store and generates a skeletal outline consisting only of titles and IDs. This gives the LLM a "mental map" of the entire system, allowing it to reference other projects or skills without needing to see their full content until they are explicitly brought into focus.
|
|
|
|
*** 3. Deterministic Tree-Walking
|
|
By leveraging Common Lisp's strengths in recursive tree manipulation, the harness can surgically prune the AST before it ever reaches the LLM. This ensures that the structural hierarchy of the Memex is preserved perfectly, even when the content is compressed.
|
|
|
|
** The Context Pipeline
|
|
#+begin_src mermaid
|
|
flowchart TD
|
|
Store[(Object Store)] --> Filter[Context Query Filter]
|
|
Filter --> Identification{Identify Foveal ID}
|
|
Identification --> Foveal[Render Focus: Full Content]
|
|
Identification --> Peripheral[Render Outline: Titles Only]
|
|
Foveal --> Assembly[Assemble Global Awareness String]
|
|
Peripheral --> Assembly
|
|
Assembly --> LLM[Probabilistic Engine Proposal]
|
|
#+end_src
|
|
|
|
* Context Assembly (context.lisp)
|
|
The ~context.lisp~ module provides the deterministic functional layer for querying the Object Store and transforming its internal pointers into the precise context strings required for neural reasoning.
|
|
|
|
** Package Context
|
|
We begin by ensuring we are executing within the correct isolated package namespace.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(in-package :org-agent)
|
|
#+end_src
|
|
|
|
** Querying the Store (context-query-store)
|
|
A generalized filter for the Object Store. This function allows skills to perform high-level semantic sweeps of the Memex based on tags, TODO states, or Org element types. It returns a list of ~org-object~ structures.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-query-store (&key tag todo-state type)
|
|
"Filters the Object Store based on tags, todo states, or types."
|
|
(let ((results nil))
|
|
(maphash (lambda (id obj)
|
|
(declare (ignore id))
|
|
(let* ((attrs (org-object-attributes obj)) (state (getf attrs :TODO-STATE)) (match t))
|
|
(when (and type (not (eq (org-object-type obj) type))) (setf match nil))
|
|
(when tag (unless (search tag (format nil "~a" (getf attrs :TAGS)) :test #'string-equal) (setf match nil)))
|
|
(when (and todo-state (not (equal state todo-state))) (setf match nil))
|
|
(when match (push obj results))))
|
|
*object-store*)
|
|
results))
|
|
#+end_src
|
|
|
|
** Active Projects (context-get-active-projects)
|
|
Identifies headlines tagged with ~project~ that have not yet reached a terminal ~DONE~ state. This provides the primary high-level structure for the agent's global awareness.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-get-active-projects ()
|
|
"Returns headlines tagged as 'project' that are not yet marked DONE."
|
|
(remove-if (lambda (obj) (equal (getf (org-object-attributes obj) :TODO-STATE) "DONE"))
|
|
(context-query-store :tag "project" :type :HEADLINE)))
|
|
#+end_src
|
|
|
|
** Completed Tasks (context-get-recent-completed-tasks)
|
|
Retrieves a list of tasks that have reached the terminal ~DONE~ state. This is useful for providing the agent with historical context or for generating summaries of recent work.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-get-recent-completed-tasks ()
|
|
"Retrieves recently finished tasks from the store."
|
|
(context-query-store :todo-state "DONE" :type :HEADLINE))
|
|
#+end_src
|
|
|
|
** Capability Discovery (context-list-all-skills)
|
|
Provides a sorted list of all currently loaded skills. In a "Self-Writing" environment, the agent must be able to discover and understand its own capabilities. This function provides the metadata necessary for the agent to decide which skill to trigger or how to resolve dependencies.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-list-all-skills ()
|
|
"Provides a sorted overview of currently loaded system capabilities."
|
|
(let ((results nil))
|
|
(maphash (lambda (name skill)
|
|
(declare (ignore name))
|
|
(push (list :name (skill-name skill) :priority (skill-priority skill) :dependencies (skill-dependencies skill)) results))
|
|
*skills-registry*)
|
|
(sort results #'> :key (lambda (x) (getf x :priority)))))
|
|
#+end_src
|
|
|
|
** Skill Inspection (context-get-skill-source)
|
|
Reads the raw literate Org source of a specific skill. This is a foundational capability for an agent expected to eventually "self-write" or perform its own maintenance. By reading the literate source, the agent can understand the *intent* behind a skill's logic before proposing a modification.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-get-skill-source (skill-name)
|
|
"Reads the raw literate source of a specific skill for inspection."
|
|
(let* ((filename (format nil "~a.org" skill-name))
|
|
(skills-dir (merge-pathnames "skills/" (asdf:system-source-directory :org-agent)))
|
|
(full-path (merge-pathnames filename skills-dir)))
|
|
(if (uiop:file-exists-p full-path) (uiop:read-file-string full-path) nil)))
|
|
#+end_src
|
|
|
|
** Harness Logs (context-get-system-logs)
|
|
Retrieves the most recent entries from the harness's internal circular log buffer. This allows the Probabilistic Engine to see recent errors or successful dispatches, enabling it to course-correct or explain failures to the user.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-get-system-logs (&optional (limit 20))
|
|
"Retrieves the most recent lines from the harness's internal log."
|
|
(bt:with-lock-held (*logs-lock*)
|
|
(let ((count (min limit (length *system-logs*)))) (subseq *system-logs* 0 count))))
|
|
#+end_src
|
|
|
|
** Telemetry (context-get-skill-telemetry)
|
|
Provides execution statistics for a specific skill, including total execution time and failure counts. This enables the harness to monitor for performance regressions or malfunctioning skills.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-get-skill-telemetry (skill-name)
|
|
"Returns performance and execution data for a specific skill."
|
|
(bt:with-lock-held (*telemetry-lock*) (gethash (string-downcase skill-name) *skill-telemetry*)))
|
|
#+end_src
|
|
|
|
** AST to Org Rendering (context-render-to-org)
|
|
This is the core engine of the Foveal-Peripheral model. It recursively transforms the internal ~org-object~ graph back into an Org-mode string.
|
|
|
|
It implements the following deterministic logic:
|
|
1. **Depth 1 & 2:** Always rendered (High-level mental map).
|
|
2. **Foveal Node:** Rendered with full body content.
|
|
3. **Semantic Neighbors:** Rendered with full content if their similarity score exceeds the threshold.
|
|
4. **Peripheral Nodes:** Rendered as skeletal headlines (titles and IDs only).
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-render-to-org (obj &key (depth 1) (foveal-id nil) (semantic-threshold 0.75) (foveal-vector nil))
|
|
"Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
|
|
(let* ((id (org-object-id obj))
|
|
(is-foveal (equal id foveal-id))
|
|
(title (or (getf (org-object-attributes obj) :TITLE) "Untitled"))
|
|
(content (org-object-content obj))
|
|
(children (org-object-children obj))
|
|
(stars (make-string depth :initial-element #\*))
|
|
(obj-vector (org-object-vector obj))
|
|
(similarity (if (and foveal-vector obj-vector (not is-foveal))
|
|
(cosine-similarity foveal-vector obj-vector)
|
|
0.0))
|
|
(is-semantically-relevant (>= similarity semantic-threshold))
|
|
;; We always render depth 1 and 2 (Projects and main tasks).
|
|
;; We always render the foveal node and its immediate children.
|
|
;; We render deeper nodes ONLY if they are semantically relevant.
|
|
(should-render (or (<= depth 2) is-foveal is-semantically-relevant))
|
|
(output ""))
|
|
|
|
(when should-render
|
|
(setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
|
|
(when is-semantically-relevant
|
|
(setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
|
|
(setf output (concatenate 'string output (format nil ":END:~%")))
|
|
|
|
;; Only include full body content if this is the Foveal focus or highly relevant
|
|
(when (and content (or is-foveal is-semantically-relevant))
|
|
(setf output (concatenate 'string output content (string #\Newline))))
|
|
|
|
;; Recursively render children
|
|
(dolist (child-id children)
|
|
(let ((child-obj (lookup-object child-id)))
|
|
(when child-obj
|
|
;; If the current node is Foveal, its children should be rendered (depth effectively resets)
|
|
(let ((next-foveal (if is-foveal child-id foveal-id)))
|
|
(setf output (concatenate 'string output
|
|
(context-render-to-org child-obj
|
|
:depth (1+ depth)
|
|
:foveal-id next-foveal
|
|
:semantic-threshold semantic-threshold
|
|
:foveal-vector foveal-vector))))))))
|
|
output))
|
|
#+end_src
|
|
|
|
** Path Resolution (context-resolve-path)
|
|
A utility function that expands environment variables (like ~$HOME~ or ~$MEMEX_ROOT~) within path strings. This ensures that the agent can interact with files across different machine configurations without hardcoding absolute paths.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-resolve-path (path-string)
|
|
"Expands environment variables within path strings (e.g. $HOME/...)."
|
|
(if (and (stringp path-string) (uiop:string-prefix-p "$" path-string))
|
|
(let* ((parts (uiop:split-string path-string :separator '(#\/)))
|
|
(var-name (subseq (car parts) 1)) (var-val (uiop:getenv var-name))
|
|
(remaining (cl:reduce (lambda (a b) (format nil "~a/~a" a b)) (cdr parts))))
|
|
(if var-val (let ((clean-val (string-trim '(#\" #\Space) var-val)))
|
|
(format nil "~a/~a" (string-right-trim "/" clean-val) remaining))
|
|
path-string))
|
|
path-string))
|
|
#+end_src
|
|
|
|
** Global Awareness (context-assemble-global-awareness)
|
|
The primary entry point for context generation. This function identifies active projects and the current user focus, then invokes the recursive renderer to assemble the pruned Org-mode skeletal outline sent to the LLM.
|
|
|
|
#+begin_src lisp :tangle ../src/context.lisp
|
|
(defun context-assemble-global-awareness (&optional signal)
|
|
"Produces a high-level skeletal outline of the current Object Store for the LLM."
|
|
(let* ((payload (when signal (getf signal :payload)))
|
|
(foveal-id (when payload (getf payload :target-id)))
|
|
(projects (context-get-active-projects))
|
|
(output "GLOBAL MEMEX AWARENESS (Peripheral Vision):
|
|
"))
|
|
(if projects
|
|
(dolist (project projects)
|
|
(setf output (concatenate 'string output
|
|
(context-render-to-org project :foveal-id foveal-id))))
|
|
(setf output (concatenate 'string output "No active projects found.~%")))
|
|
output))
|
|
#+end_src
|
|
|
|
* Phase E: Chaos (Verification)
|
|
Following the Engineering Standards, the peripheral vision extraction and rendering logic must be empirically verified. The following test suite ensures that the Foveal-Peripheral model correctly suppresses content for peripheral nodes while preserving focus on the target task.
|
|
|
|
#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
|
|
(defpackage :org-agent-peripheral-vision-tests
|
|
(:use :cl :fiveam :org-agent)
|
|
(:export #:vision-suite))
|
|
(in-package :org-agent-peripheral-vision-tests)
|
|
|
|
(def-suite vision-suite
|
|
:description "Verification of Foveal-Peripheral context model.")
|
|
(in-suite vision-suite)
|
|
|
|
(test test-foveal-rendering
|
|
"Verify that the foveal target is rendered with content, while siblings are skeletal."
|
|
(clrhash org-agent::*object-store*)
|
|
(let* ((ast '(:type :HEADLINE :properties (:ID "proj-root" :TITLE "Project" :TAGS "project")
|
|
:contents ((:type :HEADLINE :properties (:ID "node-foveal" :TITLE "Foveal Node")
|
|
:raw-content "FOVEAL CONTENT" :contents nil)
|
|
(:type :HEADLINE :properties (:ID "node-peripheral" :TITLE "Peripheral Node")
|
|
:raw-content "PERIPHERAL CONTENT" :contents nil)))))
|
|
(ingest-ast ast)
|
|
(let ((output (context-assemble-global-awareness (list :payload (list :target-id "node-foveal")))))
|
|
;; Foveal node should have its content
|
|
(is (search "FOVEAL CONTENT" output))
|
|
;; Peripheral node should be skeletal (only title/ID)
|
|
(is (search "* Peripheral Node" output))
|
|
(is (not (search "PERIPHERAL CONTENT" output))))))
|
|
|
|
(test test-awareness-budget
|
|
"Verify that context-assemble-global-awareness handles multiple projects."
|
|
(clrhash org-agent::*object-store*)
|
|
(ingest-ast '(:type :HEADLINE :properties (:ID "p1" :TITLE "Project 1" :TAGS "project") :contents nil))
|
|
(ingest-ast '(:type :HEADLINE :properties (:ID "p2" :TITLE "Project 2" :TAGS "project") :contents nil))
|
|
(let ((output (context-assemble-global-awareness)))
|
|
(is (search "Project 1" output))
|
|
(is (search "Project 2" output))))
|
|
#+end_src
|