conceptkernel 1.0.0__py3-none-any.whl

cklib/ledger.py

@@ -0,0 +1,216 @@
+"""Kernel-wide action ledger — append-only JSONL action log.
+
+Extracted from LOCAL.ClaudeCode's ``log_action()`` pattern
+(ref-tg-cli/concepts/LOCAL.ClaudeCode/tool/processor.py lines 79-134).
+
+Each kernel invocation writes one JSONL entry to a daily file under
+``storage/ledger/actions-{YYYY-MM-DD}.jsonl``.  Files are never rewritten —
+entries are always appended.
+
+Usage:
+    from cklib.ledger import log_action, read_ledger
+
+    log_action(
+        ck_dir="concepts/MyKernel",
+        action_name="task.create",
+        status="completed",
+        task_id="T001",
+        goal_id="G001",
+        detail={"items": 3},
+    )
+
+    entries = read_ledger("concepts/MyKernel", limit=20)
+"""
+
+import json
+import os
+import threading
+import time as _time
+from datetime import datetime, timezone
+from glob import glob
+
+import yaml
+
+__all__ = ["log_action", "read_ledger"]
+
+# ---------------------------------------------------------------------------
+# Internal: resolve kernel identity from conceptkernel.yaml
+# ---------------------------------------------------------------------------
+
+# File-level lock — one per process, protects the open-write-flush sequence.
+_write_lock = threading.Lock()
+
+
+def _resolve_kernel(ck_dir: str) -> tuple[str, str, str]:
+    """Return (kernel_name, kernel_urn, kernel_version) from conceptkernel.yaml.
+
+    Falls back to the directory basename if the YAML is absent or malformed.
+    """
+    ck_yaml = os.path.join(ck_dir, "conceptkernel.yaml")
+    if os.path.isfile(ck_yaml):
+        try:
+            with open(ck_yaml) as f:
+                data = yaml.safe_load(f)
+            meta = data.get("metadata", {})
+            name = meta.get("name", os.path.basename(os.path.abspath(ck_dir)))
+            urn = meta.get("urn", "")
+            version = meta.get("version", "v1.0")
+            if not urn:
+                urn = "ckp://Kernel#%s:%s" % (name, version)
+            return name, urn, version
+        except Exception:
+            pass
+
+    # Fallback
+    name = os.path.basename(os.path.abspath(ck_dir))
+    return name, "ckp://Kernel#%s:v1.0" % name, "v1.0"
+
+
+# ---------------------------------------------------------------------------
+# log_action — append one JSONL entry
+# ---------------------------------------------------------------------------
+
+def log_action(
+    ck_dir: str,
+    action_name: str,
+    *,
+    status: str = "started",
+    target_kernel: str = "",
+    task_id: str = "",
+    goal_id: str = "",
+    instance_id: str = "",
+    persona: str = "",
+    detail: dict | None = None,
+) -> dict:
+    """Append one action entry to the daily ledger file.
+
+    Args:
+        ck_dir:         Root directory of the Concept Kernel.
+        action_name:    Dotted action name (e.g. ``task.create``).
+        status:         One of ``started``, ``completed``, ``failed``,
+                        ``timeout``, ``error``.
+        target_kernel:  Optional target kernel name for cross-kernel actions.
+        task_id:        Optional task identifier (``T001``).
+        goal_id:        Optional goal identifier (``G001``).
+        instance_id:    Optional instance identifier.
+        persona:        Optional persona label.
+        detail:         Optional dict of extra payload.
+
+    Returns:
+        The entry dict that was written.
+    """
+    kernel_name, kernel_urn, _version = _resolve_kernel(ck_dir)
+
+    now = datetime.now(timezone.utc)
+    ts_iso = now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+    ts_ms = int(now.timestamp() * 1000)
+    date_str = now.strftime("%Y-%m-%d")
+
+    # Build Action URN: ckp://Action#{KernelName}/{action}-{ts_ms}
+    action_urn = "ckp://Action#%s/%s-%d" % (kernel_name, action_name, ts_ms)
+
+    entry: dict = {
+        "action_urn": action_urn,
+        "action": action_name,
+        "target_kernel": target_kernel,
+        "task_id": task_id,
+        "goal_id": goal_id,
+        "instance_id": instance_id,
+        "persona": persona,
+        "status": status,
+        "timestamp": ts_iso,
+        "timestamp_ms": ts_ms,
+        "prov:wasAssociatedWith": kernel_urn,
+    }
+
+    # Conditional PROV-O fields
+    if task_id:
+        entry["prov:wasStartedBy"] = "ckp://Task#%s" % task_id
+    if goal_id:
+        entry["prov:wasInfluencedBy"] = "ckp://Goal#%s" % goal_id
+
+    # Optional detail payload
+    if detail is not None:
+        entry["detail"] = detail
+
+    # Ensure ledger directory exists
+    ledger_dir = os.path.join(ck_dir, "storage", "ledger")
+    os.makedirs(ledger_dir, exist_ok=True)
+
+    ledger_file = os.path.join(ledger_dir, "actions-%s.jsonl" % date_str)
+    line = json.dumps(entry, separators=(",", ":")) + "\n"
+
+    # Thread-safe append — hold lock across open+write+flush
+    with _write_lock:
+        with open(ledger_file, "a") as f:
+            f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
+
+    return entry
+
+
+# ---------------------------------------------------------------------------
+# read_ledger — read recent entries across daily files
+# ---------------------------------------------------------------------------
+
+def read_ledger(ck_dir: str, limit: int = 50) -> list[dict]:
+    """Read recent ledger entries in reverse chronological order.
+
+    Scans daily ``actions-*.jsonl`` files in ``storage/ledger/``, starting
+    from the most recent file and working backwards.  Stops once *limit*
+    entries have been collected.
+
+    Args:
+        ck_dir: Root directory of the Concept Kernel.
+        limit:  Maximum number of entries to return.  Pass ``0`` for
+                unlimited (reads every file).
+
+    Returns:
+        List of entry dicts, newest first.
+    """
+    ledger_dir = os.path.join(ck_dir, "storage", "ledger")
+    if not os.path.isdir(ledger_dir):
+        return []
+
+    # Collect daily files and sort descending by filename (date)
+    pattern = os.path.join(ledger_dir, "actions-*.jsonl")
+    files = sorted(glob(pattern), reverse=True)
+
+    entries: list[dict] = []
+    for fpath in files:
+        if limit > 0 and len(entries) >= limit:
+            break
+
+        file_entries = _read_jsonl_file(fpath)
+        # Reverse so newest entries in this file come first
+        file_entries.reverse()
+
+        if limit > 0:
+            remaining = limit - len(entries)
+            entries.extend(file_entries[:remaining])
+        else:
+            entries.extend(file_entries)
+
+    return entries
+
+
+def _read_jsonl_file(path: str) -> list[dict]:
+    """Read all valid JSON lines from a file.
+
+    Silently skips blank or malformed lines.
+    """
+    entries = []
+    try:
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+    return entries

cklib/processor.py

@@ -0,0 +1,237 @@
+"""KernelProcessor — base class for all CK processors.
+
+Provides: identity loading, handle_message dispatch via @on decorator,
+status, listen, and CLI argument handling.
+
+Usage:
+    from cklib import KernelProcessor, on
+
+    class MyKernel(KernelProcessor):
+        @on("my.action")
+        def do_something(self, data):
+            return {"result": "done"}
+
+    if __name__ == "__main__":
+        MyKernel.run()
+"""
+import argparse
+import asyncio
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+import yaml
+
+
+class KernelProcessor:
+    """Base processor for all Concept Kernels."""
+
+    # Subclass registry of @on handlers
+    _handlers = None
+
+    def __init__(self, ck_dir=None):
+        if ck_dir is None:
+            # Default: assume tool/processor.py → CK is parent
+            frame = sys._getframe(1)
+            caller_file = frame.f_globals.get("__file__", "")
+            if caller_file:
+                ck_dir = os.path.abspath(os.path.join(os.path.dirname(caller_file), ".."))
+            else:
+                ck_dir = os.getcwd()
+
+        self.ck_dir = os.path.abspath(ck_dir)
+        self.project_root = os.path.abspath(os.path.join(self.ck_dir, "..", ".."))
+        self.concepts_dir = os.path.join(self.project_root, "concepts")
+        self._identity = None
+
+    @property
+    def identity(self):
+        """Load and cache conceptkernel.yaml."""
+        if self._identity is None:
+            yaml_path = os.path.join(self.ck_dir, "conceptkernel.yaml")
+            with open(yaml_path) as f:
+                self._identity = yaml.safe_load(f)
+        return self._identity
+
+    @property
+    def name(self):
+        return self.identity.get("metadata", {}).get("name", "")
+
+    @property
+    def urn(self):
+        return self.identity.get("metadata", {}).get("urn", "")
+
+    @property
+    def kernel_type(self):
+        return self.identity.get("qualities", {}).get("type", "unknown")
+
+    @property
+    def governance(self):
+        return self.identity.get("qualities", {}).get("governance_mode", "unknown")
+
+    def handle_message(self, msg):
+        """Dispatch incoming message to @on handler by action name.
+
+        Resolution order:
+          1. @on handlers registered by subclass
+          2. Built-in actions (status, ontology)
+          3. Composed actions via COMPOSES/EXTENDS edges
+          4. Error: unknown action
+        """
+        action = msg.get("action", "status") if isinstance(msg, dict) else "status"
+        data = msg.get("data", {}) if isinstance(msg, dict) else {}
+
+        # Check for @on handler
+        handlers = self._get_handlers()
+        if action in handlers:
+            method_name = handlers[action]
+            method = getattr(self, method_name)
+            return method(data)
+
+        # Built-in actions
+        if action == "status":
+            return self._status()
+        elif action == "ontology":
+            return self._ontology()
+
+        # Composed action resolution via edges
+        composed = self._resolve_composed(action)
+        if composed:
+            target_kernel, target_action = composed
+            return self._forward_to_edge(target_kernel, action, data)
+
+        return {"status": "error", "message": "unknown action: %s" % action,
+                "kernel": self.name}
+
+    def _resolve_composed(self, action):
+        """Check if action is available via COMPOSES/EXTENDS edges."""
+        try:
+            from cklib.actions import resolve_composed_actions
+            composed = resolve_composed_actions(self.ck_dir)
+            if action in composed:
+                return composed[action], action
+        except Exception:
+            pass
+        return None
+
+    def _forward_to_edge(self, target_kernel, action, data):
+        """Forward action to a composed kernel via dispatch."""
+        try:
+            from cklib.dispatch import send_action
+            result = send_action(target_kernel, action, data)
+            result["_composed_from"] = self.name
+            result["_target_kernel"] = target_kernel
+            return result
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": "edge forward failed: %s" % str(e),
+                "kernel": self.name,
+                "target_kernel": target_kernel,
+                "action": action,
+            }
+
+    def _get_handlers(self):
+        """Collect @on handlers from this class and all parents."""
+        if self.__class__._handlers is not None:
+            return self.__class__._handlers
+
+        handlers = {}
+        for cls in reversed(type(self).__mro__):
+            for attr_name in dir(cls):
+                attr = getattr(cls, attr_name, None)
+                if callable(attr) and hasattr(attr, "_on_action"):
+                    handlers[attr._on_action] = attr_name
+        self.__class__._handlers = handlers
+        return handlers
+
+    def _status(self):
+        """Built-in status action."""
+        return {
+            "status": "ok",
+            "kernel": self.name,
+            "urn": self.urn,
+            "type": self.kernel_type,
+            "governance": self.governance,
+            "processed_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def _ontology(self):
+        """Built-in ontology action — return conceptkernel.yaml."""
+        return {
+            "status": "ok",
+            "kernel": self.name,
+            "content_type": "text/yaml",
+            "data": self.identity,
+        }
+
+    def listen(self):
+        """Start NATS listener using NatsKernelLoop."""
+        sys.path.insert(0, os.path.join(self.concepts_dir, "CK.Lib", "tool"))
+        from nats_kernel import NatsKernelLoop
+        loop = NatsKernelLoop(self.ck_dir, self.handle_message)
+        asyncio.run(loop.run())
+
+    def status_cli(self):
+        """Print status to stdout."""
+        print("[status] %s" % self.name)
+        print("  urn: %s" % self.urn)
+        print("  type: %s" % self.kernel_type)
+        print("  governance: %s" % self.governance)
+
+    def serve(self, port=8901, api_token=None):
+        """Start FastAPI HTTP server wrapping this processor's @on handlers."""
+        from cklib.serve import KernelServer
+        token = api_token or os.environ.get("CK_API_TOKEN")
+        server = KernelServer(self, api_token=token, port=port)
+        server.run(port=port)
+
+    @classmethod
+    def run(cls):
+        """CLI entry point — parse args, dispatch."""
+        parser = argparse.ArgumentParser(description=cls.__doc__ or cls.__name__)
+        parser.add_argument("--status", action="store_true", help="Show kernel status")
+        parser.add_argument("--listen", action="store_true", help="NATS listener mode")
+        parser.add_argument("--serve", action="store_true", help="HTTP server mode")
+        parser.add_argument("--port", type=int, default=8901, help="HTTP port (default: 8901)")
+        parser.add_argument("--token", type=str, default=None, help="API token for HTTP auth")
+        parser.add_argument("--action", type=str, help="Execute action directly")
+        parser.add_argument("--data", type=str, default=None, help="JSON data for action")
+        parser.add_argument("--pretty", action="store_true", help="Pretty-print output")
+
+        # Let subclasses add their own args
+        cls._add_args(parser)
+        args = parser.parse_args()
+
+        # Resolve ck_dir from the subclass module (not cklib)
+        caller_file = sys.modules[cls.__module__].__file__ if cls.__module__ in sys.modules else None
+        ck_dir = os.path.abspath(os.path.join(os.path.dirname(caller_file), "..")) if caller_file else None
+        instance = cls(ck_dir=ck_dir)
+
+        if args.listen:
+            return instance.listen()
+        elif args.serve:
+            return instance.serve(port=args.port, api_token=args.token)
+        elif args.status:
+            return instance.status_cli()
+        elif args.action:
+            data = json.loads(args.data) if args.data else {}
+            result = instance.handle_message({"action": args.action, "data": data})
+            indent = 2 if args.pretty else None
+            print(json.dumps(result, indent=indent))
+            return 0 if result.get("status") != "error" else 1
+
+        # Let subclass handle remaining args
+        return cls._handle_args(instance, args)
+
+    @classmethod
+    def _add_args(cls, parser):
+        """Override to add subclass-specific CLI args."""
+        pass
+
+    @classmethod
+    def _handle_args(cls, instance, args):
+        """Override to handle subclass-specific CLI args."""
+        instance.status_cli()
+        return 0