passepartout/skills/org-skill-peripheral-vision.org

SKILL: Peripheral Vision (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Package Context
• Phase D: Build (Implementation)
  • Foveal-Peripheral Pruning
• Registration

Overview

The Peripheral Vision skill implements the Foveal-Peripheral Hybrid model for context pruning. It ensures that the LLM receives a semantically relevant and manageable view of the Memory, preventing context window overflow.

Phase A: Demand (PRD)

1. Purpose

Refine the global awareness provided to the LLM by pruning irrelevant branches of the Org DAG while maintaining high-fidelity focus on the current task.

2. User Needs

• Semantic Pruning: Use vector similarity to include only related nodes.
• Structural Integrity: Always include top-level projects and recent tasks.
• Foveal Focus: Provide full-body content for the currently active node.

3. Success Criteria

• Correctly calculate semantic relevance using the Embedding skill.
• Recursively render the Org DAG with depth-based and similarity-based pruning.
• Successfully generate the `GLOBAL MEMEX AWARENESS` block for the probabilistic-gate.

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Move context pruning and rendering logic out of `context.lisp` to allow for more sophisticated, pluggable pruning strategies.

2. Semantic Interfaces

Package Context

(in-package :opencortex)

\n#+begin_src lisp :tangle (expand-file-name "org-skill-peripheral-vision.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills")) (defun context-render-to-org (obj &key depth foveal-id semantic-threshold foveal-vector) "Recursively renders an org-object with foveal-peripheral pruning.")

(defun context-assemble-global-awareness (&optional signal) "Assembles the full context block for a neural request.")

#+end_src

Phase D: Build (Implementation)

Foveal-Peripheral Pruning

(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 (and is-semantically-relevant (> similarity 0))
        (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))

(defun context-assemble-global-awareness (&optional signal)
  "Produces a high-level skeletal outline of the current Memory for the LLM."
  (let* ((payload (when signal (getf signal :payload)))
         (foveal-id (when payload (getf payload :target-id)))
         (foveal-vector (when foveal-id (org-object-vector (lookup-object foveal-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 
                                                           :foveal-vector foveal-vector))))
        (setf output (concatenate 'string output "No active projects found.~%")))
    output))

Registration

(defskill :skill-peripheral-vision
  :priority 90
  :dependencies ("org-skill-embedding")
  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:perceive :context-refresh)))
  :probabilistic nil
  :deterministic (lambda (action ctx)
              (declare (ignore action ctx))
              ;; This skill primarily provides the context-assemble-global-awareness function
              ;; used by the probabilistic-gate, rather than handling specific actions.
              nil))