206 lines
6.3 KiB
Org Mode
206 lines
6.3 KiB
Org Mode
#+TITLE: System Interface (package.lisp)
|
|
#+AUTHOR: Amr
|
|
#+FILETAGS: :harness:interface:
|
|
#+STARTUP: content
|
|
|
|
* System Interface (package.lisp)
|
|
The ~package.lisp~ file defines the public API of the ~opencortex~ harness. It serves as the primary membrane between the deterministic core modules and the dynamic world of skills and actuators.
|
|
|
|
** Architectural Intent: The Package Membrane
|
|
By strictly defining the public interface, we ensure that skills remain decoupled from the harness implementation details. This allows for autonomous replacement of any component (e.g., swapping the Memory or the Probabilistic Engine) without breaking existing skills.
|
|
|
|
#+begin_src mermaid
|
|
flowchart TD
|
|
External[Actuators / Clients] -- communication protocol --> Package[Package Membrane: API]
|
|
Skills[Dynamic Skills] -- API Calls --> Package
|
|
Package --> Internal[Harness Internal Modules]
|
|
style Package fill:#f9f,stroke:#333,stroke-width:4px
|
|
#+end_src
|
|
|
|
** Public API Export
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defpackage :opencortex
|
|
(:use :cl)
|
|
(:export
|
|
;; --- communication protocol ---
|
|
#:frame-message
|
|
#:parse-message
|
|
#:make-hello-message
|
|
#:validate-communication-protocol-schema
|
|
|
|
;; --- Daemon Lifecycle ---
|
|
#:start-daemon
|
|
#:stop-daemon
|
|
#:harness-log
|
|
#:main
|
|
|
|
;; --- Memory (CLOSOS) ---
|
|
#:ingest-ast
|
|
#:lookup-object
|
|
#:list-objects-by-type
|
|
#:*memory*
|
|
#:*history-store*
|
|
#:org-object
|
|
#:make-org-object
|
|
#:org-object-id
|
|
#:org-object-type
|
|
#:org-object-attributes
|
|
#:org-object-parent-id
|
|
#:org-object-children
|
|
#:org-object-version
|
|
#:org-object-last-sync
|
|
#:org-object-vector
|
|
#:org-object-content
|
|
#:org-object-hash
|
|
#:snapshot-memory
|
|
#:rollback-memory
|
|
|
|
;; --- Context API (Peripheral Vision) ---
|
|
#:context-query-store
|
|
#:context-get-active-projects
|
|
#:context-get-recent-completed-tasks
|
|
#:context-list-all-skills
|
|
#:context-get-skill-source
|
|
#:context-get-system-logs
|
|
#:context-resolve-path
|
|
#:context-get-skill-telemetry
|
|
#:harness-track-telemetry
|
|
#:context-assemble-global-awareness
|
|
|
|
;; --- Reactive Signal Pipeline ---
|
|
#:process-signal
|
|
#:perceive-gate
|
|
#:probabilistic-gate
|
|
#:consensus-gate
|
|
#:decide-gate
|
|
#:dispatch-gate
|
|
#:inject-stimulus
|
|
#:initialize-actuators
|
|
#:dispatch-action
|
|
#:register-actuator
|
|
|
|
;; --- Skill Engine ---
|
|
#:load-skill-from-org
|
|
#:initialize-all-skills
|
|
#:load-skill-with-timeout
|
|
#:topological-sort-skills
|
|
#:validate-lisp-syntax
|
|
#:defskill
|
|
#:*skills-registry*
|
|
#:skill
|
|
#:skill-name
|
|
#:skill-priority
|
|
#:skill-dependencies
|
|
#:skill-trigger-fn
|
|
#:skill-probabilistic-prompt
|
|
#:skill-deterministic-fn
|
|
|
|
;; --- Tool Registry ---
|
|
#:def-cognitive-tool
|
|
#:*cognitive-tools*
|
|
#:cognitive-tool
|
|
#:cognitive-tool-name
|
|
#:cognitive-tool-description
|
|
#:cognitive-tool-parameters
|
|
#:cognitive-tool-guard
|
|
#:cognitive-tool-body
|
|
|
|
;; --- Emacs Client Registry ---
|
|
#:*emacs-clients*
|
|
#:*clients-lock*
|
|
#:register-emacs-client
|
|
#:unregister-emacs-client
|
|
|
|
;; --- Probabilistic Engine ---
|
|
#:ask-probabilistic
|
|
#:register-probabilistic-backend
|
|
#:distill-prompt
|
|
#:*provider-cascade*
|
|
|
|
;; --- Deterministic Logic ---
|
|
#:list-objects-with-attribute
|
|
#:decide
|
|
|
|
;; --- AST Helpers ---
|
|
#:find-headline-missing-id))
|
|
#+end_src
|
|
|
|
** Package Implementation
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(in-package :opencortex)
|
|
#+end_src
|
|
|
|
** Harness Logging State
|
|
The harness maintains a thread-safe circular log buffer to provide context for debugging and neural reasoning.
|
|
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defvar *system-logs* nil)
|
|
(defvar *logs-lock* (bt:make-lock "harness-logs-lock"))
|
|
(defvar *max-log-history* 100)
|
|
#+end_src
|
|
|
|
** Skills Registry
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defvar *skills-registry* (make-hash-table :test 'equal)
|
|
"Global registry of all loaded skills.")
|
|
#+end_src
|
|
|
|
** Skill Telemetry State
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defvar *skill-telemetry* (make-hash-table :test 'equal))
|
|
(defvar *telemetry-lock* (bt:make-lock "harness-telemetry-lock"))
|
|
#+end_src
|
|
|
|
** Telemetry Implementation
|
|
The system tracks the performance and reliability of individual skills. This logic is currently preserved in the package layer for future expansion into a dedicated telemetry skill.
|
|
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defun harness-track-telemetry (skill-name duration status)
|
|
"Updates performance metrics for a specific skill. Status should be :success or :rejected."
|
|
(when skill-name
|
|
(bt:with-lock-held (*telemetry-lock*)
|
|
(let ((entry (or (gethash skill-name *skill-telemetry*) (list :executions 0 :total-time 0 :failures 0))))
|
|
(incf (getf entry :executions))
|
|
(incf (getf entry :total-time) duration)
|
|
(when (eq status :rejected) (incf (getf entry :failures)))
|
|
(setf (gethash skill-name *skill-telemetry*) entry)))))
|
|
#+end_src
|
|
|
|
** Cognitive Tool Registry
|
|
The Tool Registry allows the agent to interact with the physical world. Every tool must define a guard (for security) and a body (for execution).
|
|
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defvar *cognitive-tools* (make-hash-table :test 'equal))
|
|
|
|
(defstruct cognitive-tool
|
|
name
|
|
description
|
|
parameters
|
|
guard
|
|
body)
|
|
|
|
(defmacro def-cognitive-tool (name description parameters &key guard body)
|
|
"Registers a new cognitive tool into the global registry. Parameters must be a list of property lists."
|
|
`(setf (gethash (string-downcase (string ',name)) *cognitive-tools*)
|
|
(make-cognitive-tool :name (string-downcase (string ',name))
|
|
:description ,description
|
|
:parameters ',parameters
|
|
:guard ,guard
|
|
:body ,body)))
|
|
#+end_src
|
|
|
|
** Harness Logging Implementation
|
|
Centralized logging function. It simultaneously writes to standard output and the in-memory circular buffer.
|
|
|
|
#+begin_src lisp :tangle ../src/package.lisp
|
|
(defun harness-log (msg &rest args)
|
|
"Centralized logging for the harness."
|
|
(let ((formatted-msg (apply #'format nil msg args)))
|
|
(bt:with-lock-held (*logs-lock*)
|
|
(push formatted-msg *system-logs*)
|
|
(when (> (length *system-logs*) *max-log-history*)
|
|
(setq *system-logs* (subseq *system-logs* 0 *max-log-history*))))
|
|
(format t "~a~%" formatted-msg)
|
|
(finish-output)))
|
|
#+end_src
|