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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cks-runtime
-Version: 0.1.2
+Version: 0.2.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-89%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](https://github.com/Deus-corp/CKS) |
+| **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,7 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
+- **CKS Core Integration** (via `cks_runtime_core`)
 
 ---
 
@@ -213,7 +230,6 @@ Runtime communicates exclusively through the public CKS Core API.
 From PyPI:
 
 ```bash
-pip install cks-core
 pip install cks-runtime
 ```
 
@@ -233,8 +249,10 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
+from cks_runtime_core import CksCoreAdapter
 
-runtime = Runtime()
+# Create Runtime with real CKS Core attached
+runtime = Runtime(core=CksCoreAdapter())
 
 session = runtime.sessions.create(
     knowledge_structure=my_structure
@@ -242,8 +260,7 @@ session = runtime.sessions.create(
 
 transaction = runtime.transactions.begin(session)
 
-# Runtime coordinates execution.
-# CKS Core defines semantics.
+# Runtime coordinates execution. CKS Core defines semantics.
 ```
 
 ---
@@ -286,8 +303,9 @@ Current implementation status:
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
 | Runtime Documentation | ✅ Complete |
-| Reference Implementation | 🚧 In Progress |
-| Adapter Integration | ⏳ Planned |
+| Core Integration | ✅ Complete |
+| Reference Implementation | ✅ Complete |
+| Adapter Infrastructure | 🚧 In Progress |
 
 ---
 

{cks_runtime-0.1.2 → cks_runtime-0.2.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-89%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](https://github.com/Deus-corp/CKS) |
+| **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,7 @@ The current Reference Runtime provides:
 - Canonical Runtime API
 - Reference Runtime Architecture
 - Runtime Conformance Model
+- **CKS Core Integration** (via `cks_runtime_core`)
 
 ---
 
@@ -189,7 +205,6 @@ Runtime communicates exclusively through the public CKS Core API.
 From PyPI:
 
 ```bash
-pip install cks-core
 pip install cks-runtime
 ```
 
@@ -209,8 +224,10 @@ pip install -e .
 
 ```python
 from cks_runtime import Runtime
+from cks_runtime_core import CksCoreAdapter
 
-runtime = Runtime()
+# Create Runtime with real CKS Core attached
+runtime = Runtime(core=CksCoreAdapter())
 
 session = runtime.sessions.create(
     knowledge_structure=my_structure
@@ -218,8 +235,7 @@ session = runtime.sessions.create(
 
 transaction = runtime.transactions.begin(session)
 
-# Runtime coordinates execution.
-# CKS Core defines semantics.
+# Runtime coordinates execution. CKS Core defines semantics.
 ```
 
 ---
@@ -262,8 +278,9 @@ Current implementation status:
 | Storage Abstraction | ✅ Complete |
 | Runtime API | ✅ Complete |
 | Runtime Documentation | ✅ Complete |
-| Reference Implementation | 🚧 In Progress |
-| Adapter Integration | ⏳ Planned |
+| Core Integration | ✅ Complete |
+| Reference Implementation | ✅ Complete |
+| Adapter Infrastructure | 🚧 In Progress |
 
 ---
 
@@ -279,4 +296,4 @@ This preserves a single semantic authority while allowing unlimited operational
 
 # License
 
-MIT
+MIT

{cks_runtime-0.1.2 → cks_runtime-0.2.0}/cks_runtime/config.py

@@ -19,4 +19,8 @@ class RuntimeConfig:
 
     runtime_name: str = "CKS Runtime"
 
-    runtime_version: str = "0.1.2"
+    runtime_version: str = "0.2.0"
+
+    auto_version_on_commit: bool = True
+
+    collect_runtime_diagnostics: bool = True

cks_runtime-0.2.0/cks_runtime/core_api/adapter.py

@@ -0,0 +1,154 @@
+"""
+Runtime Core Adapter.
+
+The Core Adapter is the exclusive Runtime gateway
+to CKS Core.
+
+Runtime never communicates with CKS Core directly.
+
+The adapter isolates Runtime from future changes
+to the Core API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cks_runtime.core_api.interfaces import CoreInterface
+from cks_runtime.core_api.validation_result import (
+    RuntimeValidationResult,
+)
+
+
+class CoreAdapter:
+    """
+    Runtime adapter over CKS Core.
+
+    Owns Runtime → Core interaction.
+
+    Never owns semantic behaviour.
+    """
+
+    def __init__(
+        self,
+        core: CoreInterface | None,
+    ) -> None:
+
+        self._core = core
+
+    @property
+    def attached(self) -> bool:
+        """
+        Whether a Core implementation is attached.
+        """
+
+        return self._core is not None
+
+    #
+    # Validation
+    #
+
+    def validate(
+        self,
+        knowledge_structure: Any,
+    ) -> RuntimeValidationResult:
+        """
+        Delegate validation to CKS Core.
+
+        Runtime never receives Core-native
+        ValidationResult objects.
+
+        They are translated into
+        RuntimeValidationResult.
+        """
+
+        if self._core is None:
+
+            return RuntimeValidationResult(
+                valid=True,
+            )
+
+        result = self._core.validate(
+            knowledge_structure,
+        )
+
+        return RuntimeValidationResult(
+            valid=getattr(
+                result,
+                "is_valid",
+                True,
+            ),
+            diagnostics=tuple(
+                getattr(
+                    result,
+                    "diagnostics",
+                    (),
+                )
+            ),
+            metadata=dict(
+                getattr(
+                    result,
+                    "metadata",
+                    {},
+                )
+            ),
+        )
+
+    #
+    # Evolution
+    #
+
+    def evolve(
+        self,
+        knowledge_structure: Any,
+        operation: Any,
+    ) -> Any:
+        """
+        Delegate semantic evolution to CKS Core.
+        """
+
+        if self._core is None:
+            return knowledge_structure
+
+        return self._core.evolve(
+            knowledge_structure,
+            operation,
+        )
+
+    #
+    # Serialization
+    #
+
+    def serialize(
+        self,
+        knowledge_structure: Any,
+    ) -> Any:
+        """
+        Delegate serialization to CKS Core.
+        """
+
+        if self._core is None:
+            return knowledge_structure
+
+        return self._core.serialize(
+            knowledge_structure,
+        )
+
+    #
+    # Explainability
+    #
+
+    def explain(
+        self,
+        knowledge_structure: Any,
+    ) -> Any:
+        """
+        Delegate semantic explanation to CKS Core.
+        """
+
+        if self._core is None:
+            return None
+
+        return self._core.explain(
+            knowledge_structure,
+        )

{cks_runtime-0.1.2 → cks_runtime-0.2.0}/cks_runtime/core_api/interfaces.py

@@ -63,6 +63,13 @@ class CoreInterface(ABC):
         Runtime coordinates execution.
 
         CKS Core defines the resulting semantic state.
+
+        Implementations should return the resulting
+        Knowledge Structure.
+
+        Runtime makes no assumptions about whether
+        evolution is performed in-place or by returning
+        a new object.
         """
 
     @abstractmethod

cks_runtime-0.2.0/cks_runtime/core_api/validation_result.py

@@ -0,0 +1,53 @@
+"""
+Runtime Validation Result.
+
+Represents the Runtime view of semantic validation.
+
+This object is intentionally independent from the
+internal ValidationResult implementation of CKS Core.
+
+The Core Adapter is responsible for translating
+Core-specific validation objects into this Runtime model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeValidationResult:
+    """
+    Runtime representation of semantic validation.
+
+    Runtime consumes only this abstraction.
+
+    CKS Core may evolve independently.
+    """
+
+    valid: bool
+
+    diagnostics: tuple[Any, ...] = field(
+        default_factory=tuple,
+    )
+
+    metadata: dict[str, Any] = field(
+        default_factory=dict,
+    )
+
+    @property
+    def has_diagnostics(self) -> bool:
+        """
+        Whether validation produced diagnostics.
+        """
+
+        return bool(self.diagnostics)
+
+    @property
+    def diagnostic_count(self) -> int:
+        """
+        Number of diagnostics.
+        """
+
+        return len(self.diagnostics)

{cks_runtime-0.1.2 → cks_runtime-0.2.0}/cks_runtime/diagnostics/aggregator.py

@@ -1,14 +1,15 @@
 """
 Runtime Diagnostic Aggregator.
 
-Aggregates Runtime and Core diagnostics.
+Aggregates Runtime and Core Diagnostics.
 
 Aggregation preserves ordering and ownership.
 """
 
 from __future__ import annotations
 
-from typing import Iterable
+from collections.abc import Iterable
+from collections.abc import Iterator
 
 from .diagnostic import (
     Diagnostic,
@@ -22,29 +23,32 @@ class DiagnosticAggregator:
 
     Diagnostics remain immutable.
 
-    Aggregation never modifies their meaning.
+    Aggregation never modifies
+    their semantic meaning.
     """
 
     def __init__(self) -> None:
-        self._diagnostics: list[Diagnostic] = []
-
+        self._diagnostics: list[
+            Diagnostic
+        ] = []
 
     def add(
         self,
         diagnostic: Diagnostic,
     ) -> None:
         """
-        Add a Diagnostic.
+        Add one Diagnostic.
         """
 
         self._diagnostics.append(
             diagnostic
         )
 
-
     def extend(
         self,
-        diagnostics: Iterable[Diagnostic],
+        diagnostics: Iterable[
+            Diagnostic
+        ],
     ) -> None:
         """
         Add multiple Diagnostics.
@@ -54,20 +58,21 @@ class DiagnosticAggregator:
             diagnostics
         )
 
-
     def clear(
         self,
     ) -> None:
         """
-        Remove all Diagnostics.
+        Remove every collected Diagnostic.
         """
 
         self._diagnostics.clear()
 
-
     def all(
         self,
-    ) -> tuple[Diagnostic, ...]:
+    ) -> tuple[
+        Diagnostic,
+        ...
+    ]:
         """
         Return an immutable snapshot.
         """
@@ -76,20 +81,33 @@ class DiagnosticAggregator:
             self._diagnostics
         )
 
+    @property
+    def empty(
+        self,
+    ) -> bool:
+        """
+        Whether no Diagnostics exist.
+        """
+
+        return not self._diagnostics
 
     def count(
         self,
     ) -> int:
+        """
+        Number of collected Diagnostics.
+        """
+
         return len(
             self._diagnostics
         )
 
-
     def has_errors(
         self,
     ) -> bool:
         """
-        True if any Runtime Diagnostic has ERROR severity.
+        True if at least one Diagnostic
+        has ERROR severity.
         """
 
         return any(
@@ -98,7 +116,6 @@ class DiagnosticAggregator:
             for diagnostic in self._diagnostics
         )
 
-
     def __len__(
         self,
     ) -> int:
@@ -106,10 +123,11 @@ class DiagnosticAggregator:
             self._diagnostics
         )
 
-
     def __iter__(
         self,
-    ):
+    ) -> Iterator[
+        Diagnostic
+    ]:
         return iter(
             self._diagnostics
         )

{cks_runtime-0.1.2 → cks_runtime-0.2.0}/cks_runtime/diagnostics/diagnostic.py

@@ -3,6 +3,8 @@ Runtime Diagnostic model.
 
 Runtime Diagnostics describe operational observations.
 
+Diagnostics are immutable.
+
 They never modify Runtime state and never redefine
 CKS Core semantics.
 """
@@ -44,7 +46,8 @@ class Diagnostic:
 
     - Core Diagnostics belong to CKS Core;
     - Runtime Diagnostics belong to Runtime;
-    - Runtime preserves diagnostics without modifying them.
+    - Runtime preserves Diagnostics without
+      modifying them.
     """
 
     message: str
@@ -64,5 +67,18 @@ class Diagnostic:
     )
 
     created_at: datetime = field(
-        default_factory=lambda: datetime.now(UTC)
-    )
+        default_factory=lambda: datetime.now(
+            UTC
+        )
+    )
+
+    def __str__(self) -> str:
+        """
+        Human-readable representation.
+        """
+
+        return (
+            f"[{self.severity.value.upper()}] "
+            f"{self.source.value}: "
+            f"{self.message}"
+        )

cks_runtime-0.2.0/cks_runtime/explainability/explainability_manager.py

@@ -0,0 +1,13 @@
+class ExplainabilityManager:
+    """
+    Coordinates Runtime explainability.
+
+    Runtime delegates semantic explanations
+    to the attached Core.
+
+    Future versions may combine Runtime
+    diagnostics and Core explanations into
+    a unified explanation model.
+    """
+
+    pass