From c46c4d4fd72195b7e63cbb0f2443b7247ab4dda2 Mon Sep 17 00:00:00 2001 From: Amr Gharbeia Date: Sun, 12 Apr 2026 14:09:47 -0400 Subject: [PATCH] docs: Rename cognitive architecture to Associative/Deliberate and Foreground/Background --- README.org | 6 +- literate/core.org | 20 ++-- literate/neurosymbolic.org | 53 ++++++----- literate/protocol.org | 4 +- literate/system-definition.org | 3 + skills/org-skill-agent.org | 10 +- skills/org-skill-chaos.org | 64 +++++++++---- skills/org-skill-chat.org | 28 +++++- skills/org-skill-embedding.org | 118 +++++++++++++++++++++++ skills/org-skill-oacp-validator.org | 91 ++++++++++++++++++ skills/org-skill-peripheral-vision.org | 127 +++++++++++++++++++++++++ 11 files changed, 459 insertions(+), 65 deletions(-) create mode 100644 skills/org-skill-embedding.org create mode 100644 skills/org-skill-oacp-validator.org create mode 100644 skills/org-skill-peripheral-vision.org diff --git a/README.org b/README.org index 010e360..e93d11d 100644 --- a/README.org +++ b/README.org @@ -22,8 +22,8 @@ The design of `org-agent` represents a radical departure from mainstream, fragme ** Homoiconic Memory (The Org Mandate) Most frameworks break the human-machine interface by forcing humans to read Markdown while machines read JSON. `org-agent` mandates that **Org-mode is the native Abstract Syntax Tree (AST) for both.** The code is the data, and the data is the interface. This ensures the agent's memory is perfectly aligned with the user's, preventing "black box" logic. -** The Neurosymbolic Split (System 1 vs. System 2) -Relying entirely on LLMs is fragile. `org-agent` assigns the LLM strictly to **System 1** (intuition). Common Lisp acts as **System 2** (logic and safety gating). The system is imaginative but bound by mathematical rigor. It is safe by design. +** The Neurosymbolic Split (Associative vs. Deliberate) +Relying entirely on LLMs is fragile. `org-agent` assigns the LLM strictly to **Associative** (intuition). Common Lisp acts as **Deliberate** (logic and safety gating). The system is imaginative but bound by mathematical rigor. It is safe by design. ** The Sovereign Boundary To guarantee a high MTBF (Mean Time Between Failures), the core microkernel manages only the cognitive loop, the Object-Store, and the protocol. Everything else—LLM routing, embeddings, and business logic—is pushed across the **Sovereign Boundary** into user-space Skills. @@ -45,5 +45,5 @@ The microkernel is divided into core subsystems, each documented as a standalone - **[[./literate/core.org][The Cognitive Loop (OODA)]]**: Asynchronous recursion and the perception engine. - **[[./literate/skills.org][The Skill Engine]]**: Hot-reloadable jailing and topological dependency sorting. - **[[./literate/context.org][Peripheral Vision]]**: Sparse trees, context assembly, and semantic embeddings. -- **[[./literate/neurosymbolic.org][The Neurosymbolic Bridge]]**: System 1 (LLM) intuition gated by System 2 (Lisp) physics. +- **[[./literate/neurosymbolic.org][The Neurosymbolic Bridge]]**: Associative (LLM) intuition gated by Deliberate (Lisp) physics. - **[[./literate/evolution.org][Evolutionary Roadmap]]**: The Reactive Signal Pipeline and beyond. diff --git a/literate/core.org b/literate/core.org index 65043a4..5648d29 100644 --- a/literate/core.org +++ b/literate/core.org @@ -16,9 +16,9 @@ The original `cognitive-loop` used asynchronous recursion to handle stimuli. Whi graph TD S1[Signal: User Message] --> P[Perceive Gate] S2[Signal: Heartbeat] --> P - P --> N[Neuro Gate: Multi-Backend] + P --> N[Associative Gate: Multi-Backend] N --> C[Consensus Gate] - C --> V[Validation Gate: System 2] + C --> V[Validation Gate: Deliberate] V --> D[Dispatch Gate: Actuators] D -- Feedback Signal --> S1 #+end_src @@ -162,15 +162,15 @@ Normalizes raw stimuli and updates the Object Store knowledge graph. signal)) #+end_src -*** Neuro Gate -Invokes the neural System 1 engine to generate intuition-based proposals. If parallel consensus is enabled, this gate returns a list of proposals. +*** Associative Gate +Invokes the Associative engine to generate intuition-based proposals. If parallel consensus is enabled, this gate returns a list of proposals. #+begin_src lisp :tangle ../src/core.lisp (defun neuro-gate (signal) - "System 1: Intuition and proposed actions." + "Associative: Intuition and proposed actions." (unless (eq (getf signal :type) :EVENT) (return-from neuro-gate signal)) - (kernel-log "GATE [Neuro]: Consulting System 1...") + (kernel-log "GATE [Associative]: Consulting System 1...") (let ((thoughts (think signal))) (setf (getf signal :proposals) (if (and (listp thoughts) (listp (car thoughts))) thoughts @@ -214,19 +214,19 @@ Compares multiple proposals (from parallel backends) and selects the most consis #+end_src *** Decide Gate -The System 2 safety gate. Validates the candidate action against formal rules and PSF invariants. +The Deliberate safety gate. Validates the candidate action against formal rules and PSF invariants. **** Phase A: Demand -- *Need:* Ensure that malformed candidates (e.g., raw strings from System 1) do not crash the `decide` or `safety-harness` logic, which expect property lists. +- *Need:* Ensure that malformed candidates (e.g., raw strings from Associative) do not crash the `decide` or `safety-harness` logic, which expect property lists. - *Success:* Coerce non-list candidates into valid `:RESPONSE` property lists before validation. **** Phase B: Blueprint -Before passing the candidate to `decide`, the gate checks its type. If it's a string, it wraps it in `(:type :RESPONSE :payload (:text ))`. +Before passing the candidate to `decide`, the gate checks its type. If it's a string, it wraps it in `(:type :RESPONSE :payload (list :text ))`. **** Phase D: Build #+begin_src lisp :tangle ../src/core.lisp (defun decide-gate (signal) - "System 2: Safety and validation." + "Deliberate: Safety and validation." (let ((candidate (getf signal :candidate))) (if candidate (let* ((normalized-candidate (if (listp candidate) candidate (list :type :RESPONSE :payload (list :text candidate)))) diff --git a/literate/neurosymbolic.org b/literate/neurosymbolic.org index 8c8765a..f6c9edc 100644 --- a/literate/neurosymbolic.org +++ b/literate/neurosymbolic.org @@ -5,11 +5,11 @@ * The Neurosymbolic Bridge (neuro.lisp & symbolic.lisp) ** Deep Reasoning: Imagination Checked by Physics -System 1 (LLM) is creative but hallucination-prone. System 2 (Lisp) is rigid but 100% accurate. -- **The Safety Gate:** We never allow the LLM to talk to the actuators directly. It must propose a Lisp form. System 2 intercepts this form and validates it against mathematical rules and PSF invariants. +Associative (LLM) is creative but hallucination-prone. Deliberate (Lisp) is rigid but 100% accurate. +- **The Safety Gate:** We never allow the LLM to talk to the actuators directly. It must propose a Lisp form. Deliberate intercepts this form and validates it against mathematical rules and PSF invariants. - **Sovereign Decoupling:** By moving the physical API logic into skills, the core remains a neutral "Thinking Engine" that doesn't care if the imagination comes from Google, Anthropic, or a local Llama instance. -* Neural Engine (neuro.lisp) +* Associative Engine (neuro.lisp) This module handles the interaction with Large Language Models, providing a unified interface for multiple backends. ** Package Context @@ -60,7 +60,7 @@ Retrieves authentication credentials for a provider, falling back to environment (list :api-key legacy))))))))) #+end_src -** Neuro Backends Registry +** Associative Backends Registry Tracks the actual implementation functions for each LLM provider. #+begin_src lisp :tangle ../src/neuro.lisp @@ -74,7 +74,7 @@ The ordered list of backends to attempt for neural reasoning. (defvar *provider-cascade* '(:openrouter :gemini)) #+end_src -** Register Neuro Backend +** Register Associative Backend Maps a keyword identifier to a backend implementation function. #+begin_src lisp :tangle ../src/neuro.lisp @@ -88,13 +88,13 @@ A hook for dynamic model selection based on the current context. (defvar *model-selector-fn* nil "A function called with (provider context) to return a model ID.") #+end_src -** Neural Dispatch (ask-neuro) -The primary entry point for System 1. It handles the retry logic and backend selection. It supports a parallel consensus mode where all backends are queried simultaneously. +** Associative Dispatch (ask-neuro) +The primary entry point for Associative. It handles the retry logic and backend selection. It supports a parallel consensus mode where all backends are queried simultaneously. #+begin_src lisp :tangle ../src/neuro.lisp (defvar *consensus-enabled-p* t "If T, ask-neuro queries all backends in parallel.") -(defun ask-neuro (prompt &key (system-prompt "You are the System 1 engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil)) +(defun ask-neuro (prompt &key (system-prompt "You are the Associative engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil)) "Dispatches a neural request through the provider cascade or parallel consensus." (let ((backends (cond ((and cascade (listp cascade)) cascade) @@ -110,7 +110,7 @@ The primary entry point for System 1. It handles the retry logic and backend sel (when backend-fn (push (bt:make-thread (lambda () - (kernel-log "SYSTEM 1 [Consensus]: Querying backend ~a..." backend) + (kernel-log "ASSOCIATIVE [Consensus]: Querying backend ~a..." backend) (let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context))) (result (ignore-errors (if model @@ -134,7 +134,7 @@ The primary entry point for System 1. It handles the retry logic and backend sel (or (dolist (backend backends) (let ((backend-fn (gethash backend *neuro-backends*))) (when backend-fn - (kernel-log "SYSTEM 1: Attempting backend ~a..." backend) + (kernel-log "ASSOCIATIVE: Attempting backend ~a..." backend) (let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context))) (result (if model (funcall backend-fn prompt system-prompt :model model) @@ -154,19 +154,19 @@ Standard functions that can be overridden by specific skills to provide enhanced '(:openrouter :gemini)) #+end_src -** Neural Reasoning (think) -Invokes the System 1 engine to generate a proposed Lisp action. It automatically injects the tool documentation and global context into the prompt. +** Associative Reasoning (think) +Invokes the Associative engine to generate a proposed Lisp action. It automatically injects the tool documentation and global context into the prompt. #+begin_src lisp :tangle ../src/neuro.lisp (defun think (context) - "Invokes the neural System 1 engine to propose a Lisp action based on context. + "Invokes the neural Associative engine to propose a Lisp action based on context. If consensus is enabled, it returns a list of proposals from different backends." (let ((active-skill (find-triggered-skill context)) (tool-belt (generate-tool-belt-prompt)) (global-context (context-assemble-global-awareness))) (if active-skill (progn - (kernel-log "SYSTEM 1: Engaging skill '~a'~%" (skill-name active-skill)) + (kernel-log "ASSOCIATIVE: Engaging skill '~a'~%" (skill-name active-skill)) (let* ((prompt-generator (skill-neuro-prompt active-skill)) (raw-prompt (when prompt-generator (funcall prompt-generator context))) (full-system-prompt (concatenate 'string @@ -194,7 +194,7 @@ To call a tool, you MUST use: (raw-thoughts (cl-ppcre:split (cl-ppcre:quote-meta-chars "|CONSENSUS-SEP|") thought)) (suggestions nil)) (dolist (raw-thought raw-thoughts) - (kernel-log "SYSTEM 1 RAW: ~a~%" raw-thought) + (kernel-log "ASSOCIATIVE RAW: ~a~%" raw-thought) (let* ((cleaned-thought (let ((match (cl-ppcre:scan-to-strings "(?s)```(?:lisp)?\\n?(.*?)\\n?```" raw-thought))) (if match @@ -208,7 +208,7 @@ To call a tool, you MUST use: (list :sensor :syntax-error :code cleaned-thought :error (format nil "~a" c))))))) - (kernel-log "SYSTEM 1 Suggestion: ~a~%" cleaned-thought) + (kernel-log "ASSOCIATIVE Suggestion: ~a~%" cleaned-thought) (when (and suggestion (listp suggestion)) (push suggestion suggestions)))) (if (and *consensus-enabled-p* suggestions) @@ -227,7 +227,7 @@ Allows the agent to self-optimize its own prompts. (ask-neuro (format nil "PROMPT: ~a~%RESULT: ~a" full-prompt successful-output) :system-prompt system-instr))) #+end_src -* Symbolic Logic (symbolic.lisp) +* Deliberate Logic (symbolic.lisp) The deterministic gatekeeper that ensures all proposed actions are safe and logically valid. ** Package Context @@ -255,7 +255,7 @@ Enforces high-integrity semantic rules for task management (e.g. blocking closin #+end_src ** Authorization Gate (Bouncer) -The Bouncer intercepts high-risk or complex actions and requires manual Sovereign approval. +The Bouncer intercepts high-risk or complex actions and requires manual Foreground approval. #+begin_src lisp :tangle ../src/symbolic.lisp (defun bouncer-check (action) @@ -274,20 +274,20 @@ The Bouncer intercepts high-risk or complex actions and requires manual Sovereig #+end_src ** Validation Gate (decide) -The "System 2" supervisor. It intercepts every action proposed by System 1 and runs it through the task integrity check, the bouncer, the skill's symbolic gate, and the global safety harness. +The "Deliberate" supervisor. It intercepts every action proposed by Associative and runs it through the task integrity check, the bouncer, the skill's symbolic gate, and the global safety harness. #+begin_src lisp :tangle ../src/symbolic.lisp (defun decide (proposed-action context) - "The System 2 Safety Gate: validates or rejects proposed neural actions." + "The Deliberate Safety Gate: validates or rejects proposed neural actions." ;; 1. Task Integrity Check (GTD Semantics) (let ((integrity-error (task-integrity-check proposed-action))) (when integrity-error - (kernel-log "SYSTEM 2 [INTEGRITY]: ~a~%" integrity-error) + (kernel-log "DELIBERATE [INTEGRITY]: ~a~%" integrity-error) (return-from decide (list :type :LOG :payload (list :text integrity-error))))) ;; 2. Bouncer Check (Authorization Gate) (when (bouncer-check proposed-action) - (kernel-log "SYSTEM 2 [BOUNCER]: Action requires manual approval.~%") + (kernel-log "DELIBERATE [BOUNCER]: Action requires manual approval.~%") (return-from decide (list :type :EVENT :payload (list :sensor :approval-required :action proposed-action)))) @@ -305,18 +305,19 @@ The "System 2" supervisor. It intercepts every action proposed by System 1 and r (let ((harness-pkg (find-package :org-agent.skills.org-skill-safety-harness))) (when (and code harness-pkg) (unless (ignore-errors (uiop:symbol-call :org-agent.skills.org-skill-safety-harness :safety-harness-validate code)) - (kernel-log "SYSTEM 2 [GLOBAL]: Security violation blocked.~%") + (kernel-log "DELIBERATE [GLOBAL]: Security violation blocked.~%") (return-from decide '(:type :LOG :payload (:text "Blocked by Global Safety Harness"))))))) ;; Skill-specific verification (if symbolic-gate (let ((decision (funcall symbolic-gate proposed-action context))) (if decision - (progn (kernel-log "SYSTEM 2: Verified by skill '~a'.~%" (skill-name active-skill)) decision) - (progn (kernel-log "SYSTEM 2: REJECTED by skill '~a'.~%" (skill-name active-skill)) + (progn (kernel-log "DELIBERATE: Verified by skill '~a'.~%" (skill-name active-skill)) decision) + (progn (kernel-log "DELIBERATE: REJECTED by skill '~a'.~%" (skill-name active-skill)) '(:type :LOG :payload (:text "Action rejected by skill heuristics"))))) - (progn (kernel-log "SYSTEM 2: Verified (Implicitly safe for skill '~a').~%" (skill-name active-skill)) proposed-action))) + (progn (kernel-log "DELIBERATE: Verified (Implicitly safe for skill '~a').~%" (skill-name active-skill)) proposed-action))) proposed-action))) #+end_src +#+end_src ** Store Filtering (list-objects-with-attribute) A symbolic helper function to find nodes with specific attributes. diff --git a/literate/protocol.org b/literate/protocol.org index a825d28..42dcfab 100644 --- a/literate/protocol.org +++ b/literate/protocol.org @@ -92,7 +92,9 @@ Parsing is the inverse of framing. This function performs three critical safety ;; SECURITY: Prevent Reader Macro Injection (e.g. #. ) during deserialization (let ((*read-eval* nil)) - (read-from-string actual-msg))))) + (let ((msg (read-from-string actual-msg))) + (validate-oacp-schema msg) + msg))))) #+end_src ** Handshaking (make-hello-message) diff --git a/literate/system-definition.org b/literate/system-definition.org index 979b1a3..19dc7de 100644 --- a/literate/system-definition.org +++ b/literate/system-definition.org @@ -15,9 +15,12 @@ :serial t :components ((:file "src/package") (:file "src/protocol") + (:file "src/protocol-validator") (:file "src/object-store") (:file "src/embedding") + (:file "src/embedding-logic") (:file "src/context") + (:file "src/context-logic") (:file "src/skills") (:file "src/neuro") (:file "src/credentials-vault") diff --git a/skills/org-skill-agent.org b/skills/org-skill-agent.org index 1822be7..bd05bf5 100644 --- a/skills/org-skill-agent.org +++ b/skills/org-skill-agent.org @@ -48,7 +48,7 @@ Define the core functional and security requirements for the neurosymbolic daemo ** 2. User Needs - *Homoiconic Memory:* Use Org-mode AST as the primary data structure for both human and machine. - *Deterministic Reasoning:* Common Lisp (SBCL) for high-performance, threaded symbolic logic. -- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (System 1) -> Decide (System 2) -> Act. +- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (Associative) -> Decide (Deliberate) -> Act. - *Minimalist Core:* The kernel handles only the loop, object-store, and communication; all else is a skill. - *Security by Default:* Reader safety (*read-eval* disabled) and package-based skill jailing. @@ -56,7 +56,7 @@ Define the core functional and security requirements for the neurosymbolic daemo *** TODO Core Lisp microkernel stability (Heartbeat consistency) *** TODO OACP Swank/Socket communication reliability *** TODO Org AST-to-Lisp conversion fidelity -*** TODO System 2 Safety Gating (The Harness) enforcement +*** TODO Deliberate Safety Gating (The Harness) enforcement * Phase B: Blueprint (PROTOCOL) :PROPERTIES: @@ -72,10 +72,10 @@ The kernel is transport-agnostic and business-logic-agnostic. It communicates wi "Injects an event into the global object store.") (defun kernel-think (context) - "Queries System 1 (LLM) for an intuitive proposal.") + "Queries Associative (LLM) for an intuitive proposal.") (defun kernel-decide (proposal context) - "Invokes System 2 (Symbolic Skills) to verify or overrule the proposal.") + "Invokes Deliberate (Symbolic Skills) to verify or overrule the proposal.") (defun kernel-act (action) "Dispatches verified commands to the registered actuators.") @@ -139,7 +139,7 @@ Follow the Core Invariants: (let ((payload (getf action :payload))) (if (and payload (search "proprietary" (format nil "~s" payload))) (progn - (org-agent:kernel-log "SYSTEM 2 [Agent]: Sovereignty violation suspected. Blocking action.") + (org-agent:kernel-log "DELIBERATE [Agent]: Sovereignty violation suspected. Blocking action.") nil) action)))) #+end_src diff --git a/skills/org-skill-chaos.org b/skills/org-skill-chaos.org index 1bf728a..12863f1 100644 --- a/skills/org-skill-chaos.org +++ b/skills/org-skill-chaos.org @@ -26,30 +26,55 @@ Verify the system's stability and error-handling capabilities under stress. - *Recovery Verification:* Ensure the kernel can recover from a "skip-event" restart. * Phase D: Build (Implementation) +:PROPERTIES: +:STATUS: SIGNED +:END: ** Chaos Injection Logic #+begin_src lisp :tangle ../src/chaos-logic.lisp +(in-package :org-agent) + (defun chaos-inject-error (sensor-type) "Injects a synthetic error into a specific sensor pipeline." - (org-agent:kernel-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type) - (org-agent:inject-stimulus + (unless *chaos-enabled-p* + (kernel-log "CHAOS ERROR - Injection blocked. Production gate is ACTIVE.") + (return-from chaos-inject-error nil)) + (kernel-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type) + (inject-stimulus `(:type :EVENT :payload (:sensor ,sensor-type :error "SYNTHETIC_CHAOS_ERROR")))) (defun chaos-stress-test (action context) "Executes a randomized stress test by injecting failures into the system." (declare (ignore context)) + (unless *chaos-enabled-p* + (kernel-log "CHAOS ERROR - Stress test blocked. Production gate is ACTIVE.") + (return-from chaos-stress-test "FAILURE - Production gate active.")) (let* ((payload (getf action :payload)) (mode (or (getf payload :mode) :random)) (intensity (or (getf payload :intensity) 3))) - (org-agent:kernel-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity) + (kernel-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity) + (snapshot-object-store) (case mode (:random (dotimes (i intensity) (let ((failure-type (nth (random 3) '(:test-failure :shell-timeout :llm-error)))) - (org-agent:inject-stimulus + (inject-stimulus `(:type :EVENT :payload (:sensor :chaos-injection :type ,failure-type)))))) - (:shell (org-agent:inject-stimulus + (:shell (inject-stimulus `(:type :EVENT :payload (:sensor :shell-response :cmd "git push" :exit-code 128 :stderr "fatal: network unreachable"))))) + (snapshot-object-store) (format nil "SUCCESS - Chaos stress test initiated."))) + +(defun chaos-enable () + "Disables the production gate and allows chaos injection." + (setf *chaos-enabled-p* t) + (kernel-log "CHAOS - Production gate DISABLED. Chaos injection is now ALLOWED.") + t) + +(defun chaos-disable () + "Enables the production gate and blocks chaos injection." + (setf *chaos-enabled-p* nil) + (kernel-log "CHAOS - Production gate ENABLED. Chaos injection is now BLOCKED.") + t) #+end_src @@ -58,23 +83,26 @@ Verify the system's stability and error-handling capabilities under stress. :STATUS: SIGNED :END: -* Phase B: Blueprint (PROTOCOL) - :PROPERTIES: - :STATUS: IN_PROGRESS - :END: +** 1. Architectural Intent +The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. It is protected by a **Production Gate** (`*chaos-enabled-p*`) to prevent accidental disruptions during real work. - ** 1. Architectural Intent - The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. The skill aims to provide a controlled environment for inducing and observing failures. Key intents: +- *Controlled Chaos:* Failures must be injected in a precise and controllable manner. +- *Merkle Integrity:* Every stress test triggers a Merkle snapshot before and after to allow for full-system rollback. +- *Observability:* The system's response to failures must be easily observable through logging. - - *Controlled Chaos:* Failures must be injected in a precise and controllable manner (specific sensor, specific error type). - - *Observability:* The system's response to failures must be easily observable through logging and system state. - - *Minimal Impact:* The skill should avoid causing permanent damage or corruption to the system or its data. - - *Testability*: Easy to run, configure, and verify success/failure. Reports failures through the regular error reporting mechanisms. Logs activity with 'CHAOS' tag. -- *Recoverability*: Emphasis on testing kernel's recovery from errors, by deliberately triggering skip-event type restarts. +** 2. Semantic Interfaces - ** 2. Semantic Interfaces +*** A. Gate Control - *** A. Triggering Chaos +#+begin_src lisp +(defun chaos-enable () + "Disables the production gate and allows chaos injection.") + +(defun chaos-disable () + "Enables the production gate and blocks chaos injection.") +#+end_src + +*** B. Triggering Chaos *`chaos-trigger` Sensor:* Events of type `:EVENT` with a `:payload` containing `(:sensor :chaos-trigger)` trigger the skill. The payload can contain a `:mode` key to specify the type of chaos to inject (e.g., `:random`, `:shell`), and an `:intensity` to control the number of failures injected. diff --git a/skills/org-skill-chat.org b/skills/org-skill-chat.org index 7a1f223..f3064da 100644 --- a/skills/org-skill-chat.org +++ b/skills/org-skill-chat.org @@ -50,10 +50,29 @@ Interfaces for conversational event handling and UI integration. Source of truth ** Event Perception #+begin_src lisp :tangle ../src/chat-logic.lisp +(in-package :org-agent) + +(defun chat-archive-message (text &key (role :user) channel chat-id) + "Archives a chat message into the persistent Object Store and triggers a snapshot." + (let* ((msg-id (org-id-new)) + (obj (make-org-object + :id msg-id + :type :CHAT-MESSAGE + :attributes `(:role ,role :channel ,channel :chat-id ,chat-id :timestamp ,(get-universal-time)) + :content text + :version (get-universal-time)))) + (setf (gethash msg-id *object-store*) obj) + (kernel-log "CHAT - Message archived: ~a (~a)" msg-id role) + (snapshot-object-store) + msg-id)) + (defun trigger-skill-chat (context) (let* ((payload (getf context :payload)) (sensor (getf payload :sensor))) - (eq sensor :chat-message))) + (when (eq sensor :chat-message) + ;; Archive inbound message + (chat-archive-message (getf payload :text) :role :user :channel (getf payload :channel) :chat-id (getf payload :chat-id)) + t))) #+end_src ** Symbolic Verification @@ -76,7 +95,12 @@ Interfaces for conversational event handling and UI integration. Source of truth (or (getf payload :cmd) (getf proposed-action :cmd))) (member target '(:tool :TOOL)))) (member (getf proposed-action :type) '(:response :RESPONSE :log :LOG)))) - proposed-action + (progn + ;; Archive outbound response + (when (and (member (getf proposed-action :type) '(:request :REQUEST)) + (not (eq target :tool))) + (chat-archive-message (getf payload :text) :role :agent :channel target :chat-id (or (getf payload :chat-id) (getf payload :room-id)))) + proposed-action) (let ((err-text (format nil "\n\n*System Error:* Chat agent returned invalid action: ~s" proposed-action))) `(:type :request :target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text ,err-text)))))) #+end_src diff --git a/skills/org-skill-embedding.org b/skills/org-skill-embedding.org new file mode 100644 index 0000000..62d0e30 --- /dev/null +++ b/skills/org-skill-embedding.org @@ -0,0 +1,118 @@ +:PROPERTIES: +:ID: org-skill-embedding +:CREATED: [2026-04-12 Sun 14:00] +:END: +#+TITLE: SKILL: Vector Embedding (Universal Literate Note) +#+STARTUP: content +#+FILETAGS: :embedding:vector-search:semantic:psf: + +* Overview +The *Vector Embedding* skill provides semantic search and vectorization capabilities to the org-agent. It decouples the specific embedding algorithms and provider-specific API calls from the core kernel. + +* Phase A: Demand (PRD) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Purpose +Provide a standardized interface for converting text into vector representations and performing similarity searches. + +** 2. User Needs +- *Text Vectorization:* Convert Org-mode content into high-dimensional vectors. +- *Similarity Search:* Find semantically related nodes in the Object Store. +- *Provider Agnosticism:* Support multiple embedding models (Gemini, OpenAI, etc.). + +** 3. Success Criteria +- [ ] Successfully retrieve embeddings from a configured provider. +- [ ] Perform cosine similarity calculations between vectors. +- [ ] Register as a hot-reloadable skill. + +* Phase B: Blueprint (PROTOCOL) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Architectural Intent +Move heavy neural and mathematical logic out of `core.lisp` and `neuro.lisp` into a dedicated skill. + +** 2. Semantic Interfaces + +#+begin_src lisp +(defun get-embedding (text) + "Retrieves a vector representation of text via the configured neural provider.") + +(defun cosine-similarity (v1 v2) + "Calculates the semantic distance between two vectors.") + +(defun find-most-similar (query-vector top-k) + "Identifies the top-k most semantically related objects in the store.") +#+end_src + +* Phase D: Build (Implementation) + +** Vector Operations +#+begin_src lisp :tangle ../src/embedding-logic.lisp +(in-package :org-agent) + +(defun get-embedding (text) + "Retrieves a vector representation of text via the configured neural provider." + (let* ((auth (get-provider-auth :gemini)) + (api-key (getf auth :api-key)) + (endpoint "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent")) + (unless api-key + (kernel-log "EMBEDDING ERROR: No API key for :gemini") + (return-from get-embedding nil)) + (let* ((url (format nil "~a?key=~a" endpoint api-key)) + (headers `(("Content-Type" . "application/json"))) + (body (cl-json:encode-json-to-string + `((model . "models/text-embedding-004") + (content . ((parts . ((text . ,text))))))))) + (handler-case + (let* ((response (dex:post url :headers headers :content body)) + (json (cl-json:decode-json-from-string response)) + (embedding (getf (getf json :embedding) :values))) + embedding) + (error (c) + (kernel-log "EMBEDDING FAILURE: ~a" c) + nil))))) + +(defun dot-product (v1 v2) + "Calculates the dot product of two numerical vectors." + (reduce #'+ (mapcar #'* v1 v2))) + +(defun magnitude (v) + "Calculates the Euclidean magnitude of a numerical vector." + (sqrt (reduce #'+ (mapcar (lambda (x) (* x x)) v)))) + +(defun cosine-similarity (v1 v2) + "Calculates the semantic distance between two vectors." + (let ((m1 (magnitude v1)) + (m2 (magnitude v2))) + (if (or (zerop m1) (zerop m2)) 0 (/ (dot-product v1 v2) (* m1 m2))))) + +(defun find-most-similar (query-vector top-k) + "Identifies the top-k most semantically related objects in the store." + (let ((similarities nil)) + (maphash (lambda (id obj) + (declare (ignore id)) + (let ((vec (org-object-vector obj))) + (when vec + (push (cons (cosine-similarity query-vector vec) obj) similarities)))) + *object-store*) + (let ((sorted (sort similarities #'> :key #'car))) + (subseq sorted 0 (min top-k (length sorted)))))) +#+end_src + +* Registration +#+begin_src lisp :tangle ../src/embedding-logic.lisp +(defskill :skill-embedding + :priority 50 + :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :embedding-request)) + :neuro nil + :symbolic (lambda (action ctx) + (declare (ignore ctx)) + (case (getf action :action) + (:get-embedding (get-embedding (getf action :text))) + (:similarity (cosine-similarity (getf action :v1) (getf action :v2))) + (t action)))) +#+end_src diff --git a/skills/org-skill-oacp-validator.org b/skills/org-skill-oacp-validator.org new file mode 100644 index 0000000..789bd35 --- /dev/null +++ b/skills/org-skill-oacp-validator.org @@ -0,0 +1,91 @@ +:PROPERTIES: +:ID: org-skill-oacp-validator +:CREATED: [2026-04-12 Sun 14:35] +:END: +#+TITLE: SKILL: OACP Schema Validator (Universal Literate Note) +#+STARTUP: content +#+FILETAGS: :protocol:oacp:security:validation:psf: + +* Overview +The *OACP Schema Validator* skill provides deep structural validation for all messages entering the org-agent kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing kernel-level errors. + +* Phase A: Demand (PRD) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Purpose +Enforce a formal grammar for the Org-Agent Control Protocol (OACP). + +** 2. User Needs +- *Type Safety:* Ensure mandatory keys (e.g., `:type`, `:payload`) are present. +- *Range Validation:* Check that enum values (e.g., `:REQUEST`, `:EVENT`) are valid. +- *Structural Integrity:* Validate nested payloads based on the message type. + +** 3. Success Criteria +- [ ] Block any message that does not contain a valid `:type`. +- [ ] Block `:REQUEST` messages that lack a `:target`. +- [ ] Block `:EVENT` messages that lack a `:payload` with an `:action` or `:sensor`. + +* Phase B: Blueprint (PROTOCOL) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Architectural Intent +Decouple protocol parsing (framing/unframing) from semantic validation. + +** 2. Semantic Interfaces + +#+begin_src lisp +(defun validate-oacp-schema (msg) + "Returns T if the message is valid, NIL (and signals error) otherwise.") +#+end_src + +* Phase D: Build (Implementation) + +** Schema Enforcement +#+begin_src lisp :tangle ../src/protocol-validator.lisp +(in-package :org-agent) + +(defun validate-oacp-schema (msg) + "Strict structural validation for incoming OACP messages." + (unless (listp msg) + (error "OACP Schema Error: Message must be a property list (got ~s)" (type-of msg))) + + (let ((type (getf msg :type))) + (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG)) + (error "OACP Schema Error: Invalid message type '~a'" type)) + + (case type + (:REQUEST + (unless (getf msg :target) + (error "OACP Schema Error: REQUEST missing mandatory :target")) + (unless (getf msg :payload) + (error "OACP Schema Error: REQUEST missing mandatory :payload"))) + + (:EVENT + (let ((payload (getf msg :payload))) + (unless (and payload (listp payload)) + (error "OACP Schema Error: EVENT missing or invalid :payload")) + (unless (or (getf payload :action) (getf payload :sensor)) + (error "OACP Schema Error: EVENT payload must contain :action or :sensor")))) + + (:RESPONSE + (unless (getf msg :payload) + (error "OACP Schema Error: RESPONSE missing mandatory :payload")))) + + t)) +#+end_src + +* Registration +#+begin_src lisp :tangle ../src/protocol-validator.lisp +(defskill :skill-oacp-validator + :priority 95 + :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received))) + :neuro nil + :symbolic (lambda (action ctx) + (declare (ignore ctx)) + (validate-oacp-schema action) + action)) +#+end_src diff --git a/skills/org-skill-peripheral-vision.org b/skills/org-skill-peripheral-vision.org new file mode 100644 index 0000000..311426c --- /dev/null +++ b/skills/org-skill-peripheral-vision.org @@ -0,0 +1,127 @@ +:PROPERTIES: +:ID: org-skill-peripheral-vision +:CREATED: [2026-04-12 Sun 14:15] +:END: +#+TITLE: SKILL: Peripheral Vision (Universal Literate Note) +#+STARTUP: content +#+FILETAGS: :context:foveal:peripheral:pruning:psf: + +* 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 Object Store, preventing context window overflow. + +* Phase A: Demand (PRD) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 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 neuro-gate. + +* Phase B: Blueprint (PROTOCOL) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Architectural Intent +Move context pruning and rendering logic out of `context.lisp` to allow for more sophisticated, pluggable pruning strategies. + +** 2. Semantic Interfaces + +#+begin_src lisp +(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 +#+begin_src lisp :tangle ../src/context-logic.lisp +(in-package :org-agent) + +(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 Object Store 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)) +#+end_src + +* Registration +#+begin_src lisp :tangle ../src/context-logic.lisp +(defskill :skill-peripheral-vision + :priority 90 + :dependencies ("org-skill-embedding") + :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:perceive :context-refresh))) + :neuro nil + :symbolic (lambda (action ctx) + (declare (ignore action ctx)) + ;; This skill primarily provides the context-assemble-global-awareness function + ;; used by the neuro-gate, rather than handling specific actions. + nil)) +#+end_src