cks-runtime 0.1.2__tar.gz → 0.4.0__tar.gz

{cks_runtime-0.1.2 → cks_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cks-runtime
-Version: 0.1.2
+Version: 0.4.0
 Summary: Canonical Runtime for the Canonical Knowledge Structure ecosystem
 Author: Vladyslav Hruznov
 License: MIT
@@ -11,12 +11,13 @@ Keywords: canonical-knowledge-structure,runtime,knowledge-runtime,transactions,s
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: cks-core>=1.1.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
@@ -28,7 +29,8 @@ Dynamic: license-file
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Status](https://img.shields.io/badge/status-alpha-orange)
+![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
 Canonical Knowledge Structures (CKS).
@@ -40,6 +42,20 @@ Runtime provides the infrastructure required to execute,
 manage, version, persist and expose Canonical Knowledge Structures
 without becoming a semantic authority itself.
 
+---
+
+# Ecosystem
+
+CKS Runtime is part of a family of interoperable projects built on the
+Canonical Knowledge Structure.
+
+| Project | Description | Repository |
+|---------|-------------|------------|
+| **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) |
+
+
 ---
 
 # Why Runtime?
@@ -168,6 +184,10 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
+- **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
 
 ---
 
@@ -213,7 +233,6 @@ Runtime communicates exclusively through the public CKS Core API.
 From PyPI:
 
 ```bash
-pip install cks-core
 pip install cks-runtime
 ```
 
@@ -233,17 +252,20 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
+from cks_runtime_plugins.cks_core import CksCoreAdapter
+from cks_runtime.operations.operation_types import ValidateOperation
 
-runtime = Runtime()
+# 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.
+# Runtime coordinates execution. CKS Core defines semantics.
 ```
 
 ---
@@ -272,9 +294,9 @@ Supporting documents include:
 
 ---
 
-# Project Status
+## Project Status
 
-Current implementation status:
+Current implementation status (v0.4.0):
 
 | Component | Status |
 |----------|--------|
@@ -285,9 +307,17 @@ Current implementation status:
 | Diagnostics | ✅ Complete |
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
-| Runtime Documentation | ✅ Complete |
-| Reference Implementation | 🚧 In Progress |
-| Adapter Integration | ⏳ Planned |
+| 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.1.2 → cks_runtime-0.4.0}/README.md

@@ -4,7 +4,8 @@
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Status](https://img.shields.io/badge/status-alpha-orange)
+![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
 Canonical Knowledge Structures (CKS).
@@ -16,6 +17,20 @@ Runtime provides the infrastructure required to execute,
 manage, version, persist and expose Canonical Knowledge Structures
 without becoming a semantic authority itself.
 
+---
+
+# Ecosystem
+
+CKS Runtime is part of a family of interoperable projects built on the
+Canonical Knowledge Structure.
+
+| Project | Description | Repository |
+|---------|-------------|------------|
+| **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) |
+
+
 ---
 
 # Why Runtime?
@@ -144,6 +159,10 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
+- **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
 
 ---
 
@@ -189,7 +208,6 @@ Runtime communicates exclusively through the public CKS Core API.
 From PyPI:
 
 ```bash
-pip install cks-core
 pip install cks-runtime
 ```
 
@@ -209,17 +227,20 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
+from cks_runtime_plugins.cks_core import CksCoreAdapter
+from cks_runtime.operations.operation_types import ValidateOperation
 
-runtime = Runtime()
+# 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.
+# Runtime coordinates execution. CKS Core defines semantics.
 ```
 
 ---
@@ -248,9 +269,9 @@ Supporting documents include:
 
 ---
 
-# Project Status
+## Project Status
 
-Current implementation status:
+Current implementation status (v0.4.0):
 
 | Component | Status |
 |----------|--------|
@@ -261,9 +282,17 @@ Current implementation status:
 | Diagnostics | ✅ Complete |
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
-| Runtime Documentation | ✅ Complete |
-| Reference Implementation | 🚧 In Progress |
-| Adapter Integration | ⏳ Planned |
+| 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).
 
 ---
 
@@ -279,4 +308,4 @@ This preserves a single semantic authority while allowing unlimited operational
 
 # License
 
-MIT
+MIT

cks_runtime-0.4.0/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.0/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.0/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.0/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