conceptkernel 1.0.0__py3-none-any.whl

cklib/__init__.py

@@ -0,0 +1,29 @@
+"""cklib — CKP v3.5 Python runtime for Concept Kernels.
+
+Usage:
+    from cklib import KernelProcessor, on, emit
+    from cklib.urn import parse_urn, validate_urn, build_urn
+    from cklib.instance import create_instance, seal_instance
+    from cklib.dispatch import send_action
+    from cklib.serve import KernelServer
+    from cklib.auth import CKAuth
+    from cklib.entities import EntityManager
+    from cklib.actions import resolve_action_type, check_access
+    from cklib.prov import ProvChain, Session, ActionRecord, verified_action, list_sessions, get_session
+    from cklib.ledger import log_action, read_ledger
+"""
+from cklib.processor import KernelProcessor
+from cklib.events import on, emit
+from cklib.entities import EntityManager
+from cklib.actions import resolve_action_type, check_access
+from cklib.prov import ProvChain, Session, ActionRecord, verified_action, list_sessions, get_session
+from cklib.ledger import log_action, read_ledger
+
+__version__ = "1.0.0"
+__all__ = [
+    "KernelProcessor", "on", "emit", "EntityManager",
+    "resolve_action_type", "check_access",
+    "ProvChain", "Session", "ActionRecord", "verified_action",
+    "list_sessions", "get_session",
+    "log_action", "read_ledger",
+]

cklib/actions.py

@@ -0,0 +1,277 @@
+"""Action type resolution, composition via edges, and RBAC checks.
+
+Implements SPEC.ACTION-TYPES.md §4 (type resolution), §3 (composition),
+and v3.4 access level enforcement.
+
+Usage:
+    from cklib.actions import resolve_action_type, resolve_composed_actions, check_access
+
+    atype = resolve_action_type("email.send")        # "operate"
+    composed = resolve_composed_actions("concepts/CS.Voting")
+    # {'email.send': 'CK.Email', 'email.invite': 'CK.Email', 'register': 'CK.Signup'}
+    ok = check_access("email.send", "auth", {"sub": "alice"}, grants)
+"""
+import os
+
+import yaml
+
+
+# ---------------------------------------------------------------------------
+# §4 — Action Type Map (from SPEC.ACTION-TYPES.md)
+# ---------------------------------------------------------------------------
+
+ACTION_TYPE_MAP = {
+    # inspect
+    "status": "inspect", "ontology": "inspect", "show": "inspect",
+    "list": "inspect", "version": "inspect",
+
+    # check
+    "check.*": "check", "validate": "check", "probe.*": "check",
+
+    # mutate
+    "create": "mutate", "update": "mutate", "complete": "mutate",
+    "assign": "mutate", "enable": "mutate", "disable": "mutate",
+    "save": "mutate", "load": "mutate",
+
+    # operate
+    "spawn": "operate", "execute": "operate", "render": "operate",
+    "run": "operate", "fire": "operate", "play": "operate", "stop": "operate",
+    "send": "operate", "invite": "operate",
+
+    # query
+    "catalog": "query", "graph": "query", "search": "query",
+    "pending": "query", "tasks": "query",
+
+    # deploy
+    "deploy.*": "deploy", "apply": "deploy", "route.*": "deploy",
+
+    # transfer
+    "export.*": "transfer", "import.*": "transfer",
+    "sync": "transfer", "regenerate": "transfer",
+}
+
+VALID_ACTION_TYPES = {"inspect", "check", "mutate", "operate", "query", "deploy", "transfer"}
+
+
+def resolve_action_type(action_name):
+    """Resolve dotted action name to its type per SPEC.ACTION-TYPES.md §4.
+
+    Resolution order:
+      1. Exact match (e.g. "status" → inspect)
+      2. Suffix match (e.g. "task.create" → "create" → mutate)
+      3. Prefix wildcard (e.g. "check.identity" → "check.*" → check)
+      4. Default: inspect (read-only)
+    """
+    # Exact match
+    if action_name in ACTION_TYPE_MAP:
+        return ACTION_TYPE_MAP[action_name]
+
+    # Suffix match: task.create → create → mutate
+    suffix = action_name.rsplit(".", 1)[-1]
+    if suffix in ACTION_TYPE_MAP:
+        return ACTION_TYPE_MAP[suffix]
+
+    # Prefix wildcard: check.identity → check.* → check
+    prefix = action_name.split(".")[0]
+    pattern = prefix + ".*"
+    if pattern in ACTION_TYPE_MAP:
+        return ACTION_TYPE_MAP[pattern]
+
+    return "inspect"  # default: read-only
+
+
+# ---------------------------------------------------------------------------
+# §3 — Composed Actions via Edges
+# ---------------------------------------------------------------------------
+
+def _load_ck_yaml(ck_dir):
+    """Load conceptkernel.yaml, return (data, error)."""
+    yaml_path = os.path.join(ck_dir, "conceptkernel.yaml")
+    if not os.path.isfile(yaml_path):
+        return None, "conceptkernel.yaml not found"
+    try:
+        with open(yaml_path) as f:
+            return yaml.safe_load(f), None
+    except Exception as e:
+        return None, str(e)
+
+
+def _get_actions_from_spec(data):
+    """Extract action names from spec.actions (common + unique)."""
+    actions = {}
+    spec_actions = data.get("spec", {}).get("actions", {})
+    for section in ("common", "unique"):
+        for act in spec_actions.get(section, []):
+            if isinstance(act, dict) and "name" in act:
+                actions[act["name"]] = act
+    return actions
+
+
+def _find_ck_dir_by_name(target_name, concepts_dir):
+    """Find a CK directory by its metadata.name."""
+    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
+        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:
+            continue
+    return None
+
+
+def resolve_composed_actions(ck_dir):
+    """Walk COMPOSES/EXTENDS edges, collect target kernel actions.
+
+    Returns dict: {action_name: target_kernel_name}
+    Only follows COMPOSES and EXTENDS edges (not TRIGGERS/PRODUCES/LOOPS_WITH).
+    """
+    ck_dir = os.path.abspath(ck_dir)
+    data, err = _load_ck_yaml(ck_dir)
+    if err:
+        return {}
+
+    # Derive concepts_dir
+    concepts_dir = os.path.dirname(ck_dir)
+
+    edges_section = data.get("spec", {}).get("edges", data.get("edges", {}))
+    outbound = edges_section.get("outbound", [])
+
+    composed = {}
+    for edge in outbound:
+        if not isinstance(edge, dict):
+            continue
+        predicate = edge.get("predicate", "")
+        if predicate not in ("COMPOSES", "EXTENDS"):
+            continue
+
+        target_name = edge.get("target_kernel", "")
+        if not target_name:
+            continue
+
+        target_dir = _find_ck_dir_by_name(target_name, concepts_dir)
+        if not target_dir:
+            continue
+
+        target_data, terr = _load_ck_yaml(target_dir)
+        if terr:
+            continue
+
+        target_actions = _get_actions_from_spec(target_data)
+        for action_name in target_actions:
+            # Don't override — first edge wins
+            if action_name not in composed:
+                composed[action_name] = target_name
+
+    return composed
+
+
+def get_effective_actions(ck_dir):
+    """Return the full effective action set: own + composed.
+
+    Returns dict: {action_name: {"source": "own"|kernel_name, "spec": action_dict}}
+    """
+    ck_dir = os.path.abspath(ck_dir)
+    data, err = _load_ck_yaml(ck_dir)
+    if err:
+        return {}
+
+    effective = {}
+
+    # Own actions
+    own_actions = _get_actions_from_spec(data)
+    for name, spec in own_actions.items():
+        effective[name] = {"source": "own", "spec": spec}
+
+    # Composed actions
+    composed = resolve_composed_actions(ck_dir)
+    for name, kernel_name in composed.items():
+        if name not in effective:
+            effective[name] = {"source": kernel_name, "spec": {}}
+
+    return effective
+
+
+# ---------------------------------------------------------------------------
+# RBAC — Access Level Enforcement
+# ---------------------------------------------------------------------------
+
+VALID_ACCESS_LEVELS = {"anon", "auth", "owner"}
+
+
+def check_access(action_name, access_level, caller_claims, grants=None):
+    """Verify caller has permission for action based on access level + grants.
+
+    Args:
+        action_name: the action being invoked
+        access_level: "anon" | "auth" | "owner" from spec.actions
+        caller_claims: JWT claims dict (empty for anonymous)
+        grants: optional list of grant dicts from conceptkernel.yaml
+
+    Returns:
+        True if access is allowed, False otherwise.
+    """
+    if access_level not in VALID_ACCESS_LEVELS:
+        return False
+
+    # anon — always allowed
+    if access_level == "anon":
+        return True
+
+    # auth — caller must have a subject
+    if not caller_claims or not caller_claims.get("sub"):
+        return False
+
+    if access_level == "auth":
+        # If grants exist, check if caller's identity matches any grant
+        if grants:
+            return _check_grants(action_name, caller_claims, grants)
+        # No grants = any authenticated user
+        return True
+
+    # owner — caller must match kernel owner or have admin role
+    if access_level == "owner":
+        roles = caller_claims.get("realm_access", {}).get("roles", [])
+        if "admin" in roles:
+            return True
+        # Check grants for owner-level access
+        if grants:
+            return _check_grants(action_name, caller_claims, grants)
+        return False
+
+    return False
+
+
+def _check_grants(action_name, caller_claims, grants):
+    """Check if caller matches any grant entry for the given action."""
+    if not isinstance(grants, list):
+        grants = [grants]
+
+    caller_sub = caller_claims.get("sub", "")
+    caller_user = caller_claims.get("preferred_username", "")
+
+    for grant in grants:
+        if not isinstance(grant, dict):
+            continue
+
+        identity = grant.get("identity", "")
+        actions = grant.get("actions", [])
+
+        # Check identity match
+        if identity == "*" or identity == caller_sub or identity == caller_user:
+            # Check action match
+            if isinstance(actions, list):
+                if "*" in actions or action_name in actions:
+                    return True
+            elif actions == "*" or actions == action_name:
+                return True
+
+    return False

cklib/auth.py

@@ -0,0 +1,98 @@
+"""Shared auth — JWKS + X-Token for CK HTTP endpoints.
+
+Loads Keycloak JWKS once at startup. Supports dual auth:
+- X-Token header or ?token= query param (for API clients like Claude voice)
+- Authorization: Bearer <jwt> (for browser/Keycloak-authenticated users)
+
+Usage:
+    from cklib.auth import CKAuth
+
+    auth = CKAuth(api_token="my-secret")
+    await auth.load_jwks()
+    claims = auth.authenticate(request)
+"""
+import os
+
+import httpx
+import jwt as pyjwt
+
+KEYCLOAK_BASE = "https://id.tech.games"
+KEYCLOAK_REALM = "techgames"
+JWKS_URL = f"{KEYCLOAK_BASE}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/certs"
+
+
+class CKAuth:
+    """Dual auth: static API token + Keycloak JWT."""
+
+    def __init__(self, api_token=None):
+        self.api_token = api_token or os.environ.get("CK_API_TOKEN")
+        self._jwks_keys = None
+
+    async def load_jwks(self):
+        """Fetch JWKS from Keycloak once at startup."""
+        try:
+            async with httpx.AsyncClient(verify=True, timeout=15) as client:
+                resp = await client.get(JWKS_URL)
+                resp.raise_for_status()
+                data = resp.json()
+            self._jwks_keys = {k["kid"]: k for k in data.get("keys", [])}
+            return len(self._jwks_keys)
+        except Exception as e:
+            print(f"[auth]  JWKS load failed: {e}")
+            self._jwks_keys = {}
+            return 0
+
+    @property
+    def jwks_loaded(self):
+        return self._jwks_keys is not None and len(self._jwks_keys) > 0
+
+    def authenticate(self, request) -> dict:
+        """Authenticate request. Returns claims dict or raises HTTPException."""
+        from fastapi import HTTPException
+
+        # Check X-Token first (API client path)
+        x_token = (request.headers.get("X-Token")
+                   or request.query_params.get("token"))
+        if x_token:
+            if not self.api_token:
+                raise HTTPException(401, "API token not configured")
+            if x_token != self.api_token:
+                raise HTTPException(401, "Invalid API token")
+            return {"preferred_username": "api-client", "sub": "api-client"}
+
+        # Fall back to JWT
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer "):
+            raise HTTPException(401, "Missing X-Token or Bearer token")
+
+        token = auth_header[7:]
+        return self._verify_jwt(token)
+
+    def _verify_jwt(self, token: str) -> dict:
+        from fastapi import HTTPException
+
+        if not self._jwks_keys:
+            raise HTTPException(401, "JWKS not loaded")
+
+        try:
+            header = pyjwt.get_unverified_header(token)
+        except pyjwt.DecodeError:
+            raise HTTPException(401, "Invalid token")
+
+        kid = header.get("kid")
+        if kid not in self._jwks_keys:
+            raise HTTPException(401, "Unknown key ID")
+
+        jwk_data = self._jwks_keys[kid]
+        alg = header.get("alg", jwk_data.get("alg", "RS256"))
+        public_key = pyjwt.algorithms.RSAAlgorithm.from_jwk(jwk_data)
+
+        try:
+            return pyjwt.decode(
+                token, public_key, algorithms=[alg],
+                options={"verify_aud": False},
+            )
+        except pyjwt.ExpiredSignatureError:
+            raise HTTPException(401, "Token expired")
+        except pyjwt.InvalidTokenError as e:
+            raise HTTPException(401, f"Invalid token: {e}")

cklib/dispatch.py

@@ -0,0 +1,179 @@
+"""Action dispatch — send actions to kernels locally or via queue.
+
+All actions go through the queue. The queue processes FIFO locally.
+
+Usage:
+    from cklib.dispatch import send_action, queue_action, run_queue
+
+    # Immediate (bypasses queue for inspect/query actions):
+    result = send_action("CK.Task", "status")
+
+    # Queued (for operate/mutate/check/deploy actions):
+    queue_action("CK.Task", "task.create", data={...}, persona="builder")
+
+    # Process queue:
+    run_queue()
+"""
+import importlib.util
+import json
+import os
+import time
+import glob
+
+PROJECT_ROOT = None
+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")
+
+
+def resolve_kernel(name):
+    """Resolve kernel name to directory + processor path."""
+    _init_paths()
+    for prefix in ["", "CK.", "TG.", "LOCAL.", "Test."]:
+        ck_dir = os.path.join(CONCEPTS_DIR, prefix + name)
+        proc = os.path.join(ck_dir, "tool", "processor.py")
+        if os.path.isfile(proc):
+            return ck_dir, proc
+    return None, None
+
+
+def load_handler(processor_path):
+    """Import handle_message from a processor.py."""
+    spec = importlib.util.spec_from_file_location("processor", processor_path)
+    mod = importlib.util.module_from_spec(spec)
+    old_cwd = os.getcwd()
+    os.chdir(os.path.dirname(processor_path))
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        os.chdir(old_cwd)
+    return getattr(mod, "handle_message", None)
+
+
+def send_action(kernel_name, action, data=None):
+    """Send action directly — no queue. For inspect/query (stateless reads)."""
+    ck_dir, proc_path = resolve_kernel(kernel_name)
+    if not proc_path:
+        return {"status": "error", "message": "kernel not found: %s" % kernel_name}
+
+    handler = load_handler(proc_path)
+    if not handler:
+        return {"status": "error", "message": "no handle_message in %s" % kernel_name}
+
+    msg = {"action": action}
+    if data:
+        msg["data"] = data
+
+    try:
+        return handler(msg)
+    except Exception as e:
+        return {"status": "error", "message": str(e), "kernel": kernel_name}
+
+
+# ---------------------------------------------------------------------------
+# Queue — FIFO for local execution
+# ---------------------------------------------------------------------------
+
+def _queue_dir():
+    _init_paths()
+    qdir = os.path.join(CONCEPTS_DIR, "LOCAL.ClaudeCode", "storage", "queue")
+    os.makedirs(qdir, exist_ok=True)
+    return qdir
+
+
+def queue_action(kernel_name, action, data=None, persona="operator",
+                 task_id="", goal_id=""):
+    """Add an action to the FIFO queue."""
+    qdir = _queue_dir()
+    ts = int(time.time() * 1000)  # millisecond precision for ordering
+    seq = len(glob.glob(os.path.join(qdir, "*.json"))) + 1
+
+    entry = {
+        "seq": seq,
+        "kernel": kernel_name,
+        "action": action,
+        "data": data or {},
+        "persona": persona,
+        "task_id": task_id,
+        "goal_id": goal_id,
+        "queued_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "status": "pending",
+    }
+
+    filename = "%03d-%s-%s-%d.json" % (seq, kernel_name.replace(".", "-"), action.replace(".", "-"), ts)
+    with open(os.path.join(qdir, filename), "w") as f:
+        json.dump(entry, f, indent=2)
+
+    return entry
+
+
+def list_queue():
+    """List all pending queue entries in FIFO order."""
+    qdir = _queue_dir()
+    entries = []
+    for fname in sorted(os.listdir(qdir)):
+        if fname.endswith(".json"):
+            with open(os.path.join(qdir, fname)) as f:
+                entry = json.load(f)
+            entry["_file"] = fname
+            entries.append(entry)
+    return [e for e in entries if e.get("status") == "pending"]
+
+
+def run_queue():
+    """Process the queue FIFO — one at a time."""
+    _init_paths()
+    lock_path = os.path.join(CONCEPTS_DIR, "LOCAL.ClaudeCode", "storage", "lock")
+
+    # Check lock
+    if os.path.exists(lock_path):
+        with open(lock_path) as f:
+            pid = f.read().strip()
+        # Check if process still running
+        try:
+            os.kill(int(pid), 0)
+            return {"status": "locked", "pid": pid, "message": "Queue runner already active"}
+        except (OSError, ValueError):
+            os.remove(lock_path)
+
+    # Acquire lock
+    with open(lock_path, "w") as f:
+        f.write(str(os.getpid()))
+
+    try:
+        pending = list_queue()
+        results = []
+        total = len(pending)
+
+        for i, entry in enumerate(pending, 1):
+            kernel = entry["kernel"]
+            action = entry["action"]
+            persona = entry.get("persona", "operator")
+
+            print("[%d/%d] %s → %s (%s)" % (i, total, entry.get("task_id") or action, kernel, persona))
+
+            result = send_action(kernel, action, entry.get("data"))
+            results.append({"entry": entry, "result": result})
+
+            # Mark as completed
+            entry["status"] = "completed"
+            entry["completed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+            entry["result_status"] = result.get("status", "unknown")
+
+            qpath = os.path.join(_queue_dir(), entry["_file"])
+            with open(qpath, "w") as f:
+                json.dump(entry, f, indent=2)
+
+            status = result.get("status", "?")
+            print("       %s" % status)
+
+        return {"status": "ok", "processed": len(results), "results": results}
+    finally:
+        if os.path.exists(lock_path):
+            os.remove(lock_path)

cklib/entities.py

@@ -0,0 +1,95 @@
+"""EntityManager — shared in-memory entity store with code-based lookup.
+
+Extracted from VoiceScreen (_sessions) and CS.Voting (_rooms) patterns.
+Both use: dict store + reverse code index + status tracking + 4-char codes.
+
+Usage:
+    from cklib.entities import EntityManager
+
+    rooms = EntityManager(prefix="room")
+    room_id, room = rooms.create(owner="alice", name="Quick Vote")
+    room_id, room = rooms.get_by_code("AB12")
+    rooms.update_status(room_id, "closed")
+"""
+import time
+import uuid
+from datetime import datetime, timezone
+
+
+def generate_code(length=4):
+    """Generate a random uppercase hex code (4 chars by default)."""
+    return uuid.uuid4().hex[:length].upper()
+
+
+def generate_entity_id(prefix, code):
+    """Generate a timestamped entity ID: {prefix}-{epoch}-{code}."""
+    return f"{prefix}-{int(time.time())}-{code.lower()}"
+
+
+class EntityManager:
+    """In-memory entity store with code-based lookup.
+
+    Entities are dicts with at least: code, status, created_at.
+    Additional fields come from create() kwargs.
+    """
+
+    def __init__(self, prefix="entity"):
+        self.prefix = prefix
+        self._store = {}        # entity_id → entity dict
+        self._by_code = {}      # CODE → entity_id
+
+    def create(self, **fields):
+        """Create a new entity. Returns (entity_id, entity_dict).
+
+        Always generates: code, status='active', created_at.
+        Extra fields are merged in.
+        """
+        code = generate_code()
+        entity_id = generate_entity_id(self.prefix, code)
+        entity = {
+            "code": code,
+            "status": "active",
+            "created_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            **fields,
+        }
+        self._store[entity_id] = entity
+        self._by_code[code] = entity_id
+        return entity_id, entity
+
+    def get(self, entity_id):
+        """Get entity by ID. Returns entity dict or None."""
+        return self._store.get(entity_id)
+
+    def get_by_code(self, code):
+        """Look up entity by code. Returns (entity_id, entity_dict) or (None, None)."""
+        code = code.upper()
+        entity_id = self._by_code.get(code)
+        if entity_id and entity_id in self._store:
+            return entity_id, self._store[entity_id]
+        return None, None
+
+    def resolve_or_404(self, code):
+        """Look up entity by code, raise FastAPI 404 if not found."""
+        from fastapi import HTTPException
+        entity_id, entity = self.get_by_code(code)
+        if not entity_id:
+            raise HTTPException(404, f"No {self.prefix} for code {code}")
+        return entity_id, entity
+
+    def update_status(self, entity_id, status):
+        """Update an entity's status field."""
+        entity = self._store.get(entity_id)
+        if entity:
+            entity["status"] = status
+        return entity
+
+    def list_active(self):
+        """Return list of (entity_id, entity) where status == 'active'."""
+        return [
+            (eid, e) for eid, e in self._store.items()
+            if e.get("status") == "active"
+        ]
+
+    def list_all(self):
+        """Return all (entity_id, entity) pairs."""
+        return list(self._store.items())