conceptkernel 1.1.0__tar.gz → 1.3.0__tar.gz

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conceptkernel
-Version: 1.1.0
+Version: 1.3.0
 Summary: CKP v3.5 Python runtime — kernel processor, provenance, execution proofs
 Author-email: Peter Styk <peter@conceptkernel.org>
 License: MIT

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/cklib/__init__.py

@@ -36,3 +36,4 @@ __all__ = [
     "load_schema", "validate_instance", "has_schema",
     "check_capacity",
 ]
+from cklib.occurrent import ActionOccurrent

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/cklib/actions.py

@@ -108,27 +108,51 @@ def _get_actions_from_spec(data):
 
 
 def _find_ck_dir_by_name(target_name, concepts_dir):
-    """Find a CK directory by its metadata.name."""
+    """Find a CK directory by its metadata.name.
+
+    Searches two levels: direct child (flat layout) and one level deeper
+    (GUID subdirectory layout).
+    """
     if not os.path.isdir(concepts_dir):
         return None
     for entry in os.listdir(concepts_dir):
         candidate = os.path.join(concepts_dir, entry)
         if not os.path.isdir(candidate):
             continue
+        # Level 1: conceptkernel.yaml at kernel root (flat layout)
         yaml_path = os.path.join(candidate, "conceptkernel.yaml")
-        if not os.path.isfile(yaml_path):
-            continue
-        try:
-            with open(yaml_path) as f:
-                d = yaml.safe_load(f)
-            if isinstance(d, dict) and d.get("metadata", {}).get("name") == target_name:
-                return candidate
-        except Exception:
+        if os.path.isfile(yaml_path):
+            try:
+                with open(yaml_path) as f:
+                    d = yaml.safe_load(f)
+                if isinstance(d, dict) and d.get("metadata", {}).get("name") == target_name:
+                    return candidate
+                # Also check kernel_class field
+                if isinstance(d, dict) and d.get("kernel_class") == target_name:
+                    return candidate
+            except Exception:
+                pass
             continue
+        # Level 2: conceptkernel.yaml inside a subdirectory (GUID layout)
+        for sub in os.listdir(candidate):
+            sub_path = os.path.join(candidate, sub)
+            if not os.path.isdir(sub_path):
+                continue
+            yaml_path = os.path.join(sub_path, "conceptkernel.yaml")
+            if os.path.isfile(yaml_path):
+                try:
+                    with open(yaml_path) as f:
+                        d = yaml.safe_load(f)
+                    if isinstance(d, dict) and d.get("metadata", {}).get("name") == target_name:
+                        return sub_path
+                    if isinstance(d, dict) and d.get("kernel_class") == target_name:
+                        return sub_path
+                except Exception:
+                    pass
     return None
 
 
-def resolve_composed_actions(ck_dir):
+def resolve_composed_actions(ck_dir, concepts_dir=None):
     """Walk COMPOSES/EXTENDS edges, collect target kernel actions.
 
     Returns dict: {action_name: target_kernel_name}
@@ -139,8 +163,17 @@ def resolve_composed_actions(ck_dir):
     if err:
         return {}
 
-    # Derive concepts_dir
-    concepts_dir = os.path.dirname(ck_dir)
+    # Derive concepts_dir — walk up until we find a dir containing OTHER kernels
+    if concepts_dir is None:
+        concepts_dir = os.path.dirname(ck_dir)
+        # Check if parent has OTHER kernel directories (not just our own GUID subdir)
+        ck_basename = os.path.basename(ck_dir)
+        siblings = [d for d in os.listdir(concepts_dir)
+                    if d != ck_basename
+                    and os.path.isdir(os.path.join(concepts_dir, d))
+                    and os.path.isfile(os.path.join(concepts_dir, d, "conceptkernel.yaml"))]
+        if not siblings:
+            concepts_dir = os.path.dirname(concepts_dir)
 
     edges_section = data.get("spec", {}).get("edges", data.get("edges", {}))
     outbound = edges_section.get("outbound", [])

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/cklib/dispatch.py

@@ -27,9 +27,36 @@ CONCEPTS_DIR = None
 def _init_paths():
     global PROJECT_ROOT, CONCEPTS_DIR
     if PROJECT_ROOT is None:
-        PROJECT_ROOT = os.path.abspath(
-            os.path.join(os.path.dirname(__file__), "..", "..", "..", ".."))
-        CONCEPTS_DIR = os.path.join(PROJECT_ROOT, "concepts")
+        # Prefer env vars (set by CK.Operator boot or delvinator.sh)
+        if os.environ.get("CK_CONCEPTS_DIR"):
+            CONCEPTS_DIR = os.environ["CK_CONCEPTS_DIR"]
+            PROJECT_ROOT = os.path.dirname(CONCEPTS_DIR)
+        elif os.environ.get("PROJECT_ROOT"):
+            PROJECT_ROOT = os.environ["PROJECT_ROOT"]
+            CONCEPTS_DIR = os.path.join(PROJECT_ROOT, "concepts")
+        else:
+            # Fallback: walk up from cklib to find concepts/ dir containing kernel dirs
+            candidate = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+            for _ in range(5):
+                concepts_candidate = os.path.join(candidate, "concepts")
+                if os.path.isdir(concepts_candidate):
+                    # Verify it has actual kernel directories (not just a stray concepts/ folder)
+                    has_kernels = any(
+                        os.path.isfile(os.path.join(concepts_candidate, d, "conceptkernel.yaml"))
+                        or any(os.path.isfile(os.path.join(concepts_candidate, d, sub, "conceptkernel.yaml"))
+                               for sub in os.listdir(os.path.join(concepts_candidate, d))
+                               if os.path.isdir(os.path.join(concepts_candidate, d, sub)))
+                        for d in os.listdir(concepts_candidate)
+                        if os.path.isdir(os.path.join(concepts_candidate, d))
+                    )
+                    if has_kernels:
+                        PROJECT_ROOT = candidate
+                        CONCEPTS_DIR = concepts_candidate
+                        break
+                candidate = os.path.dirname(candidate)
+            else:
+                PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", ".."))
+                CONCEPTS_DIR = os.path.join(PROJECT_ROOT, "concepts")
 
 
 def resolve_kernel(name):

conceptkernel-1.3.0/cklib/nats.py

@@ -0,0 +1,183 @@
+"""
+nats_kernel.py — shared NATS kernel loop for Concept Kernels.
+
+Not a standalone CK — a library that any CK's processor.py imports to become
+a NATS listener following the CK processing cycle:
+
+    Receive → Validate → Process (primary tool) → Create Instance → Publish Result → Notify
+
+Usage:
+    from nats_kernel import NatsKernelLoop
+
+    def handle_message(msg):
+        return {"status": "ok", "echo": msg}
+
+    loop = NatsKernelLoop(CK_DIR, handle_message)
+    asyncio.run(loop.run())
+"""
+import asyncio
+import json
+import os
+import time
+import uuid
+
+import yaml
+import nats
+
+
+class NatsKernelLoop:
+    """NATS listener that implements the CK processing cycle."""
+
+    # nats:// — native TCP (server processors in cluster)
+    # wss://  — WebSocket (Python CLI from local machine, needs aiohttp)
+    # Set NATS_URL env var to override
+    DEFAULT_ENDPOINT = "nats://localhost:4222"
+
+    def __init__(self, ck_dir, handler_fn):
+        self.ck_dir = os.path.abspath(ck_dir)
+        self.handler_fn = handler_fn
+        self.instance_dir = os.path.join(self.ck_dir, "storage", "instances")
+
+        # NATS endpoint: env var > .ckproject > default
+        self.endpoint = os.environ.get("NATS_URL", self.DEFAULT_ENDPOINT)
+
+        # Load identity from conceptkernel.yaml
+        ck_yaml_path = os.path.join(self.ck_dir, "conceptkernel.yaml")
+        with open(ck_yaml_path) as f:
+            self.ck = yaml.safe_load(f)
+
+        meta = self.ck["metadata"]
+        spec = self.ck["spec"]
+        nats_cfg = spec.get("nats", {})
+
+        self.kernel_name = meta["name"]
+        self.kernel_urn = meta["urn"]
+        self.input_topic = nats_cfg.get("input_topic", f"input.{self.kernel_name}")
+        self.result_topic = nats_cfg.get("result_topic", f"result.{self.kernel_name}")
+        self.event_topic = nats_cfg.get("event_topic", f"event.{self.kernel_name}")
+
+        self.nc = None
+
+    async def run(self):
+        """Connect to NATS and listen on input topic."""
+        print(f"[nats]  connecting to {self.endpoint}...")
+        self.nc = await nats.connect(self.endpoint)
+        print(f"[nats]  connected as {self.kernel_urn}")
+        print(f"[sub]   {self.input_topic}")
+        print(f"[ready] Listening on {self.input_topic}...")
+        print()
+
+        sub = await self.nc.subscribe(self.input_topic)
+
+        try:
+            async for msg in sub.messages:
+                await self._handle(msg)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.nc.drain()
+
+    async def _handle(self, msg):
+        """Process a single incoming message through the CK cycle."""
+        ts = int(time.time())
+
+        # Parse headers from NATS-level headers
+        headers = {}
+        if msg.headers:
+            for key in ("Trace-Id", "Nats-Msg-Id", "X-Kernel-ID", "X-User-ID", "X-Anonymous"):
+                val = msg.headers.get(key)
+                if val:
+                    headers[key] = val
+
+        trace_id = headers.get("Trace-Id", f"tx-{uuid.uuid4().hex[:6]}")
+        sender_kernel = headers.get("X-Kernel-ID", "unknown")
+        user_id = headers.get("X-User-ID", "anonymous")
+
+        # Parse body (pure data — no control attributes)
+        try:
+            body = json.loads(msg.data.decode()) if msg.data else {}
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            body = {"raw": msg.data.decode("utf-8", errors="replace")}
+
+        print(f"[rx]    {trace_id} {msg.subject} {json.dumps(body, separators=(',', ':'))}")
+
+        # Process via primary tool (handler_fn)
+        # Pass nc + trace_id for streaming. Supports both sync and async handlers.
+        try:
+            import inspect
+            try:
+                raw = self.handler_fn(body, nc=self.nc, trace_id=trace_id)
+            except TypeError:
+                raw = self.handler_fn(body)
+
+            # If handler returned a coroutine, await it
+            if inspect.isawaitable(raw):
+                result = await raw
+            else:
+                result = raw
+            status = "ok"
+        except Exception as e:
+            result = {"error": str(e)}
+            status = "error"
+
+        # Create instance record
+        instance_id = f"i-{trace_id}-{ts}"
+        instance_path = os.path.join(self.instance_dir, instance_id)
+        os.makedirs(instance_path, exist_ok=True)
+
+        record = {
+            "instance_id": instance_id,
+            "kernel_urn": self.kernel_urn,
+            "trace_id": trace_id,
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts)),
+            "input": {
+                "subject": msg.subject,
+                "headers": headers,
+                "body": body,
+            },
+            "output": result,
+            "status": status,
+            "sender": sender_kernel,
+            "user_id": user_id,
+        }
+
+        record_path = os.path.join(instance_path, "message.json")
+        with open(record_path, "w") as f:
+            json.dump(record, f, indent=2)
+
+        # Publish result
+        result_envelope = {
+            "trace_id": trace_id,
+            "kernel_urn": self.kernel_urn,
+            "timestamp": record["timestamp"],
+            "status": status,
+            "data": result,
+        }
+
+        result_headers = {
+            "Trace-Id": trace_id,
+            "X-Kernel-ID": self.kernel_urn,
+            "Nats-Msg-Id": str(uuid.uuid4()),
+        }
+
+        await self.nc.publish(
+            self.result_topic,
+            json.dumps(result_envelope).encode(),
+            headers=result_headers,
+        )
+        print(f"[tx]    {trace_id} {self.result_topic}")
+
+        # Publish event notification
+        event = {
+            "type": "instance_created",
+            "instance_id": instance_id,
+            "trace_id": trace_id,
+            "kernel_urn": self.kernel_urn,
+            "timestamp": record["timestamp"],
+        }
+
+        await self.nc.publish(
+            self.event_topic,
+            json.dumps(event).encode(),
+            headers={"Trace-Id": trace_id, "X-Kernel-ID": self.kernel_urn},
+        )

conceptkernel-1.3.0/cklib/occurrent.py

@@ -0,0 +1,218 @@
+"""Occurrent tracking — ontology-verified action substeps with PROV-O proof.
+
+Every CKP action is an Occurrent (bfo:Process). Each substep within an action
+is also an Occurrent, linked to its parent via prov:wasStartedBy.
+
+At completion, the parent action's proof is built from the chain of substep
+occurrents — each one verified before the next can start.
+
+Usage:
+    from cklib.occurrent import ActionOccurrent
+
+    with ActionOccurrent("project.deploy", kernel_urn="ckp://Kernel#CK.Operator:v1.0") as action:
+        action.step("deploy.accepted", {"hostname": "delvinator.tech.games"})
+        action.step("deploy.scanning", {"kernels": 6})
+
+        # Substep with verification
+        with action.substep("deploy.materialising") as sub:
+            sub.detail("resources", 9)
+            sub.verify("namespace_created", True)
+            sub.verify("pv_bound", True)
+            sub.verify("deployment_ready", True)
+
+        action.step("deploy.ready", {"url": "https://delvinator.tech.games/"})
+
+    # action.proof contains the hash chain of all steps
+    # action.occurrents contains the full list with URNs and timestamps
+"""
+
+import hashlib
+import json
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass, field, asdict
+
+
+@dataclass
+class StepRecord:
+    """A single occurrent step within an action."""
+    step_urn: str
+    step_type: str
+    timestamp: str
+    detail: dict = field(default_factory=dict)
+    verifications: list = field(default_factory=list)
+    hash: str = ""
+    parent_hash: str = ""
+    status: str = "ok"
+
+
+@dataclass
+class VerificationRecord:
+    """A verification check within a step."""
+    check: str
+    passed: bool
+    detail: str = ""
+    timestamp: str = ""
+
+
+class ActionOccurrent:
+    """Track an action as a chain of verified occurrent steps.
+
+    Each step gets:
+    - A URN: ckp://Occurrent#{kernel}/{action}/{step}-{ts}
+    - A SHA-256 hash chained to the previous step
+    - Optional verification checks (pass/fail)
+    - PROV-O links: wasStartedBy parent action
+
+    The complete action proof = hash chain of all steps.
+    """
+
+    def __init__(self, action_name, kernel_urn="", ck_dir=None):
+        self.action_name = action_name
+        self.kernel_urn = kernel_urn
+        self.ck_dir = ck_dir
+
+        ts_ms = int(time.time() * 1000)
+        kernel_short = kernel_urn.split("#")[-1].split(":")[0] if "#" in kernel_urn else "unknown"
+
+        self.action_urn = f"ckp://Action#{kernel_short}/{action_name}-{ts_ms}"
+        self.started_at = datetime.now(timezone.utc).isoformat()
+        self.ended_at = None
+        self.steps = []
+        self._prev_hash = self._hash(self.action_urn)
+        self._current_substep = None
+
+    def step(self, step_type, detail=None):
+        """Record a step in the action."""
+        ts = datetime.now(timezone.utc).isoformat()
+        ts_ms = int(time.time() * 1000)
+        kernel_short = self.kernel_urn.split("#")[-1].split(":")[0] if "#" in self.kernel_urn else "unknown"
+
+        step_urn = f"ckp://Occurrent#{kernel_short}/{self.action_name}/{step_type}-{ts_ms}"
+
+        # Chain hash
+        content = json.dumps({"step": step_type, "detail": detail or {}, "prev": self._prev_hash},
+                             sort_keys=True)
+        step_hash = self._hash(content)
+
+        record = StepRecord(
+            step_urn=step_urn,
+            step_type=step_type,
+            timestamp=ts,
+            detail=detail or {},
+            hash=step_hash,
+            parent_hash=self._prev_hash,
+        )
+
+        self.steps.append(record)
+        self._prev_hash = step_hash
+        return record
+
+    def substep(self, step_type):
+        """Context manager for a substep with verification checks."""
+        return _Substep(self, step_type)
+
+    def verify_chain(self):
+        """Verify the hash chain is intact."""
+        prev = self._hash(self.action_urn)
+        for s in self.steps:
+            content = json.dumps({"step": s.step_type, "detail": s.detail, "prev": prev},
+                                 sort_keys=True)
+            expected = self._hash(content)
+            if s.hash != expected:
+                return False, f"Chain broken at {s.step_type}: expected {expected[:12]}, got {s.hash[:12]}"
+            prev = s.hash
+        return True, "Chain intact"
+
+    @property
+    def proof(self):
+        """Generate the action proof from the step chain."""
+        valid, message = self.verify_chain()
+        all_verified = all(
+            all(v.passed for v in s.verifications)
+            for s in self.steps
+        )
+        return {
+            "action_urn": self.action_urn,
+            "kernel_urn": self.kernel_urn,
+            "action": self.action_name,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+            "steps": len(self.steps),
+            "chain_valid": valid,
+            "chain_message": message,
+            "all_verified": all_verified,
+            "final_hash": self._prev_hash,
+            "prov:wasAssociatedWith": self.kernel_urn,
+            "prov:startedAtTime": self.started_at,
+            "prov:endedAtTime": self.ended_at,
+        }
+
+    @property
+    def occurrents(self):
+        """Return all step records as dicts."""
+        return [asdict(s) for s in self.steps]
+
+    def save(self, path=None):
+        """Save proof + occurrents to storage/proof/."""
+        if path is None and self.ck_dir:
+            proof_dir = os.path.join(self.ck_dir, "storage", "proof")
+            os.makedirs(proof_dir, exist_ok=True)
+            ts = int(time.time())
+            path = os.path.join(proof_dir, f"proof-{self.action_name}-{ts}.json")
+
+        if path:
+            doc = {
+                "proof": self.proof,
+                "occurrents": self.occurrents,
+            }
+            with open(path, "w") as f:
+                json.dump(doc, f, indent=2)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.ended_at = datetime.now(timezone.utc).isoformat()
+        if exc_type:
+            self.step("action.failed", {"error": str(exc_val)})
+        if self.ck_dir:
+            self.save()
+
+    @staticmethod
+    def _hash(content):
+        if isinstance(content, dict):
+            content = json.dumps(content, sort_keys=True)
+        return hashlib.sha256(content.encode()).hexdigest()
+
+
+class _Substep:
+    """Context manager for a substep with verification."""
+
+    def __init__(self, parent, step_type):
+        self.parent = parent
+        self.step_type = step_type
+        self._detail = {}
+        self._verifications = []
+
+    def detail(self, key, value):
+        self._detail[key] = value
+
+    def verify(self, check_name, passed, detail=""):
+        self._verifications.append(VerificationRecord(
+            check=check_name,
+            passed=passed,
+            detail=detail,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        ))
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        record = self.parent.step(self.step_type, self._detail)
+        record.verifications = self._verifications
+        if not all(v.passed for v in self._verifications):
+            record.status = "verification_failed"

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/cklib/processor.py

@@ -168,8 +168,7 @@ class KernelProcessor:
 
     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
+        from cklib.nats import NatsKernelLoop
         loop = NatsKernelLoop(self.ck_dir, self.handle_message)
         asyncio.run(loop.run())
 

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/conceptkernel.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conceptkernel
-Version: 1.1.0
+Version: 1.3.0
 Summary: CKP v3.5 Python runtime — kernel processor, provenance, execution proofs
 Author-email: Peter Styk <peter@conceptkernel.org>
 License: MIT

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/conceptkernel.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ cklib/events.py
 cklib/execution.py
 cklib/instance.py
 cklib/ledger.py
+cklib/nats.py
+cklib/occurrent.py
 cklib/processor.py
 cklib/prov.py
 cklib/schema.py

{conceptkernel-1.1.0 → conceptkernel-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "conceptkernel"
-version = "1.1.0"
+version = "1.3.0"
 description = "CKP v3.5 Python runtime — kernel processor, provenance, execution proofs"
 readme = "README.md"
 license = {text = "MIT"}