cks-runtime 0.2.0__tar.gz → 0.4.1__tar.gz

{cks_runtime-0.2.0 → cks_runtime-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cks-runtime
-Version: 0.2.0
+Version: 0.4.1
 Summary: Canonical Runtime for the Canonical Knowledge Structure ecosystem
 Author: Vladyslav Hruznov
 License: MIT
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Tests](https://img.shields.io/badge/tests-89%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-147%20passing-brightgreen)
 ![Status](https://img.shields.io/badge/status-beta-blue)
 
 CKS Runtime is the canonical execution environment for
@@ -51,7 +51,7 @@ Canonical Knowledge Structure.
 
 | Project | Description | Repository |
 |---------|-------------|------------|
-| **cks-core** | Semantic engine – the single source of canonical truth. | [Deus-corp/CKS](https://github.com/Deus-corp/CKS) |
+| **cks-core** | Semantic engine – the single source of canonical truth. | [Deus-corp/cks-core](https://github.com/Deus-corp/cks-core) |
 | **cks-runtime** | Operational environment – sessions, transactions, persistence. | [Deus-corp/cks-runtime](https://github.com/Deus-corp/cks-runtime) |
 | **cks-mcp** | MCP server – exposes CKS to LLMs via the Model Context Protocol. | [Deus-corp/cks-mcp](https://github.com/Deus-corp/cks-mcp) |
 
@@ -184,7 +184,10 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
-- **CKS Core Integration** (via `cks_runtime_core`)
+- **CKS Core Integration** (via `CksCoreAdapter`)
+- **Execution Engine** – canonical operations (Validate, Serialize, Explain, Evolve) via `CoreBridge`
+- **Operation Dispatcher** – registry-based operation resolution
+- **DispatchRequest** support – decoupled operation execution
 
 ---
 
@@ -249,16 +252,18 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
-from cks_runtime_core import CksCoreAdapter
+from cks_runtime_plugins.cks_core import CksCoreAdapter
+from cks_runtime.operations.operation_types import ValidateOperation
 
-# Create Runtime with real CKS Core attached
+# Create Runtime with real CKS Core
 runtime = Runtime(core=CksCoreAdapter())
 
-session = runtime.sessions.create(
-    knowledge_structure=my_structure
-)
+session = runtime.create_session({"example": True})
+tx = runtime.begin_transaction(session)
+tx.add_operation(ValidateOperation("v1", knowledge_structure=session.knowledge_structure))
 
-transaction = runtime.transactions.begin(session)
+version = runtime.commit_transaction(tx)
+print(version)
 
 # Runtime coordinates execution. CKS Core defines semantics.
 ```
@@ -289,9 +294,9 @@ Supporting documents include:
 
 ---
 
-# Project Status
+## Project Status
 
-Current implementation status:
+Current implementation status (v0.4.0):
 
 | Component | Status |
 |----------|--------|
@@ -302,10 +307,17 @@ Current implementation status:
 | Diagnostics | ✅ Complete |
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
-| Runtime Documentation | ✅ Complete |
-| Core Integration | ✅ Complete |
-| Reference Implementation | ✅ Complete |
-| Adapter Infrastructure | 🚧 In Progress |
+| Core Integration (CoreBridge) | ✅ Complete |
+| Execution Engine (Operations + Dispatcher) | ✅ Complete |
+| Test Suite | ✅ 147 tests passing |
+| CLI / MCP Adapters | ✅ Experimental |
+| Event System | 🚧 Planned (Phase 3) |
+
+The current implementation serves as the reference implementation of the
+CKS Runtime Standard (SPEC-001 … SPEC-008).
+
+Future work focuses on Phase 3 (Event System) as outlined in the
+[Roadmap](ROADMAP.md).
 
 ---
 

{cks_runtime-0.2.0 → cks_runtime-0.4.1}/README.md

@@ -4,7 +4,7 @@
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Tests](https://img.shields.io/badge/tests-89%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-147%20passing-brightgreen)
 ![Status](https://img.shields.io/badge/status-beta-blue)
 
 CKS Runtime is the canonical execution environment for
@@ -26,7 +26,7 @@ Canonical Knowledge Structure.
 
 | Project | Description | Repository |
 |---------|-------------|------------|
-| **cks-core** | Semantic engine – the single source of canonical truth. | [Deus-corp/CKS](https://github.com/Deus-corp/CKS) |
+| **cks-core** | Semantic engine – the single source of canonical truth. | [Deus-corp/cks-core](https://github.com/Deus-corp/cks-core) |
 | **cks-runtime** | Operational environment – sessions, transactions, persistence. | [Deus-corp/cks-runtime](https://github.com/Deus-corp/cks-runtime) |
 | **cks-mcp** | MCP server – exposes CKS to LLMs via the Model Context Protocol. | [Deus-corp/cks-mcp](https://github.com/Deus-corp/cks-mcp) |
 
@@ -159,7 +159,10 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
-- **CKS Core Integration** (via `cks_runtime_core`)
+- **CKS Core Integration** (via `CksCoreAdapter`)
+- **Execution Engine** – canonical operations (Validate, Serialize, Explain, Evolve) via `CoreBridge`
+- **Operation Dispatcher** – registry-based operation resolution
+- **DispatchRequest** support – decoupled operation execution
 
 ---
 
@@ -224,16 +227,18 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
-from cks_runtime_core import CksCoreAdapter
+from cks_runtime_plugins.cks_core import CksCoreAdapter
+from cks_runtime.operations.operation_types import ValidateOperation
 
-# Create Runtime with real CKS Core attached
+# Create Runtime with real CKS Core
 runtime = Runtime(core=CksCoreAdapter())
 
-session = runtime.sessions.create(
-    knowledge_structure=my_structure
-)
+session = runtime.create_session({"example": True})
+tx = runtime.begin_transaction(session)
+tx.add_operation(ValidateOperation("v1", knowledge_structure=session.knowledge_structure))
 
-transaction = runtime.transactions.begin(session)
+version = runtime.commit_transaction(tx)
+print(version)
 
 # Runtime coordinates execution. CKS Core defines semantics.
 ```
@@ -264,9 +269,9 @@ Supporting documents include:
 
 ---
 
-# Project Status
+## Project Status
 
-Current implementation status:
+Current implementation status (v0.4.0):
 
 | Component | Status |
 |----------|--------|
@@ -277,10 +282,17 @@ Current implementation status:
 | Diagnostics | ✅ Complete |
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
-| Runtime Documentation | ✅ Complete |
-| Core Integration | ✅ Complete |
-| Reference Implementation | ✅ Complete |
-| Adapter Infrastructure | 🚧 In Progress |
+| Core Integration (CoreBridge) | ✅ Complete |
+| Execution Engine (Operations + Dispatcher) | ✅ Complete |
+| Test Suite | ✅ 147 tests passing |
+| CLI / MCP Adapters | ✅ Experimental |
+| Event System | 🚧 Planned (Phase 3) |
+
+The current implementation serves as the reference implementation of the
+CKS Runtime Standard (SPEC-001 … SPEC-008).
+
+Future work focuses on Phase 3 (Event System) as outlined in the
+[Roadmap](ROADMAP.md).
 
 ---
 

cks_runtime-0.4.1/cks_runtime/__init__.py

@@ -0,0 +1,21 @@
+"""
+CKS Runtime.
+
+Canonical Runtime for the Canonical Knowledge Structure ecosystem.
+
+The public package API intentionally exposes only the
+high-level Runtime façade and its configuration object.
+"""
+
+from __future__ import annotations
+
+from .config import RuntimeConfig
+from .runtime import Runtime
+
+__version__ = RuntimeConfig().runtime_version
+
+__all__ = (
+    "Runtime",
+    "RuntimeConfig",
+    "__version__",
+)

cks_runtime-0.4.1/cks_runtime/adapters/mcp/__init__.py

@@ -0,0 +1,17 @@
+"""
+MCP Adapter.
+
+Public Runtime interface for Model Context Protocol support.
+"""
+
+from .adapter import MCPAdapter
+from .handlers import MCPHandler
+from .tool_registry import ToolRegistry
+from .serializers import MCPSerializer
+
+__all__ = [
+    "MCPAdapter",
+    "MCPHandler",
+    "MCPToolRegistry",
+    "MCPSerializer",
+]

cks_runtime-0.4.1/cks_runtime/adapters/mcp/adapter.py

@@ -0,0 +1,68 @@
+"""
+Runtime MCP Adapter.
+
+Bridges the Model Context Protocol (MCP)
+and the Runtime public API.
+
+The adapter owns only transport translation.
+
+Semantic behaviour belongs to Runtime and
+CKS Core plugins.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cks_runtime.runtime import Runtime
+
+from .tool_registry import ToolRegistry
+
+
+class MCPAdapter:
+    """
+    Runtime MCP adapter.
+
+    Responsible only for translating
+    MCP requests into Runtime API calls.
+    """
+
+    def __init__(
+        self,
+        runtime: Runtime,
+    ) -> None:
+
+        self._runtime = runtime
+
+        self._tools = ToolRegistry()
+
+    #
+    # Public API
+    #
+
+    def list_tools(
+        self,
+    ) -> list[dict[str, Any]]:
+        """
+        Return MCP tool descriptions.
+        """
+
+        return self._tools.list()
+
+    def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+    ) -> Any:
+        """
+        Execute an MCP tool.
+        """
+
+        handler = self._tools.resolve(
+            name,
+        )
+
+        return handler(
+            runtime=self._runtime,
+            arguments=arguments,
+        )

cks_runtime-0.4.1/cks_runtime/adapters/mcp/contracts.py

@@ -0,0 +1,256 @@
+"""
+MCP Contracts.
+
+Canonical Runtime representation of JSON-RPC / MCP messages.
+
+The Runtime never manipulates raw JSON dictionaries directly.
+
+Transport layers convert JSON <-> contract objects.
+
+The Adapter operates exclusively on these contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+#
+# ----------------------------------------------------------------------
+# Base
+# ----------------------------------------------------------------------
+#
+
+
+JSONRPC_VERSION = "2.0"
+
+
+RequestId = str | int
+
+
+#
+# ----------------------------------------------------------------------
+# Requests
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPRequest:
+    """
+    JSON-RPC request.
+
+    Represents a tool invocation coming from an MCP client.
+    """
+
+    id: RequestId
+
+    method: str
+
+    params: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+    jsonrpc: str = JSONRPC_VERSION
+
+
+#
+# ----------------------------------------------------------------------
+# Notifications
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPNotification:
+    """
+    JSON-RPC notification.
+
+    Notifications never expect a response.
+    """
+
+    method: str
+
+    params: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+    jsonrpc: str = JSONRPC_VERSION
+
+
+#
+# ----------------------------------------------------------------------
+# Responses
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPResponse:
+    """
+    Successful JSON-RPC response.
+    """
+
+    id: RequestId
+
+    result: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+    jsonrpc: str = JSONRPC_VERSION
+
+
+#
+# ----------------------------------------------------------------------
+# Error Responses
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPErrorResponse:
+    """
+    JSON-RPC error response.
+    """
+
+    id: RequestId | None
+
+    error: dict[str, Any]
+
+    jsonrpc: str = JSONRPC_VERSION
+
+
+#
+# ----------------------------------------------------------------------
+# Tool Contracts
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPToolCall:
+    """
+    Runtime representation of a tool invocation.
+    """
+
+    tool: str
+
+    arguments: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class MCPToolResult:
+    """
+    Result produced by a Runtime tool.
+    """
+
+    content: Any
+
+    is_error: bool = False
+
+
+#
+# ----------------------------------------------------------------------
+# Lifecycle
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPInitializeRequest:
+    """
+    MCP initialize request.
+    """
+
+    protocol_version: str
+
+    client_info: dict[str, Any]
+
+    capabilities: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class MCPInitializeResponse:
+    """
+    MCP initialize response.
+    """
+
+    protocol_version: str
+
+    server_info: dict[str, Any]
+
+    capabilities: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+
+#
+# ----------------------------------------------------------------------
+# Capabilities
+# ----------------------------------------------------------------------
+#
+
+
+@dataclass(frozen=True, slots=True)
+class MCPServerCapabilities:
+    """
+    Runtime capabilities exposed through MCP.
+    """
+
+    tools: bool = True
+
+    resources: bool = False
+
+    prompts: bool = False
+
+    logging: bool = False
+
+    completion: bool = False
+
+    sampling: bool = False
+
+    roots: bool = False
+
+    experimental: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+    def as_dict(self) -> dict[str, Any]:
+        """
+        Convert capabilities into MCP payload.
+        """
+
+        payload: dict[str, Any] = {}
+
+        if self.tools:
+            payload["tools"] = {}
+
+        if self.resources:
+            payload["resources"] = {}
+
+        if self.prompts:
+            payload["prompts"] = {}
+
+        if self.logging:
+            payload["logging"] = {}
+
+        if self.completion:
+            payload["completion"] = {}
+
+        if self.sampling:
+            payload["sampling"] = {}
+
+        if self.roots:
+            payload["roots"] = {}
+
+        if self.experimental:
+            payload["experimental"] = dict(
+                self.experimental,
+            )
+
+        return payload

cks_runtime-0.4.1/cks_runtime/adapters/mcp/errors.py

@@ -0,0 +1,164 @@
+"""
+MCP Error Model.
+
+Defines Runtime-side JSON-RPC / MCP errors.
+
+This module contains no transport logic.
+
+It only defines the canonical error objects used by
+the MCP Adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any
+
+
+class MCPErrorCode(IntEnum):
+    """
+    Standard JSON-RPC / MCP error codes.
+    """
+
+    #
+    # JSON parsing
+    #
+
+    PARSE_ERROR = -32700
+
+    #
+    # Request validation
+    #
+
+    INVALID_REQUEST = -32600
+
+    #
+    # Method dispatch
+    #
+
+    METHOD_NOT_FOUND = -32601
+
+    #
+    # Parameter validation
+    #
+
+    INVALID_PARAMS = -32602
+
+    #
+    # Internal execution
+    #
+
+    INTERNAL_ERROR = -32603
+
+    #
+    # Runtime-specific server errors.
+    #
+
+    SERVER_ERROR = -32000
+
+    RESOURCE_NOT_FOUND = -32002
+
+    REQUEST_TIMEOUT = -32001
+
+
+@dataclass(frozen=True, slots=True)
+class MCPError:
+    """
+    Runtime representation of a JSON-RPC error.
+    """
+
+    code: MCPErrorCode
+
+    message: str
+
+    data: Any | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        """
+        Serialize into JSON-RPC error object.
+        """
+
+        payload = {
+            "code": int(self.code),
+            "message": self.message,
+        }
+
+        if self.data is not None:
+            payload["data"] = self.data
+
+        return payload
+
+
+#
+# ------------------------------------------------------------------
+# Convenience constructors
+# ------------------------------------------------------------------
+#
+
+def parse_error() -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.PARSE_ERROR,
+        "Parse error",
+    )
+
+
+def invalid_request(
+    message: str = "Invalid request",
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.INVALID_REQUEST,
+        message,
+    )
+
+
+def method_not_found(
+    method: str,
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.METHOD_NOT_FOUND,
+        f"Method '{method}' not found.",
+    )
+
+
+def invalid_params(
+    message: str,
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.INVALID_PARAMS,
+        message,
+    )
+
+
+def internal_error(
+    exc: Exception | str,
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.INTERNAL_ERROR,
+        str(exc),
+    )
+
+
+def resource_not_found(
+    resource: str,
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.RESOURCE_NOT_FOUND,
+        f"Resource '{resource}' not found.",
+    )
+
+
+def timeout(
+    operation: str,
+) -> MCPError:
+
+    return MCPError(
+        MCPErrorCode.REQUEST_TIMEOUT,
+        f"Operation '{operation}' timed out.",
+    )