clm-kernel 0.0.0__py3-none-any.whl

clm/schemas/mcard_vector_schema.sql

@@ -0,0 +1,283 @@
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- MCard Vector Database Schema (mcard_vectors.db)
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- 
+-- This schema defines the structure for "Secondary Qualities" (Extrinsic Embeddings).
+-- It is separated from the core mcard.db (Monadic Intrinsic Properties) to ensure:
+-- 1. Separation of Concerns (Intrinsic vs Extrinsic)
+-- 2. Linearity (Vectors are observer-dependent and large)
+-- 3. Upgradability (Embedding models change frequently)
+--
+-- See: Monadic Justification for Schema Design.md
+-- ═══════════════════════════════════════════════════════════════════════════════
+
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- LAYER 3: VECTOR STORAGE (Semantic Embeddings)
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- Storage for vector embeddings enabling semantic search.
+-- Links to content via hash for content-addressing.
+
+-- @table mcard_vector_metadata
+-- @description Metadata for stored embeddings
+-- @column id          - Auto-increment primary key
+-- @column hash        - FK to card.hash
+-- @column model_name  - Embedding model used (e.g., "nomic-embed-text")
+-- @column dimensions  - Vector dimensions
+-- @column chunk_index - Index for chunked documents (0 = first/whole)
+-- @column chunk_total - Total chunks for this document
+-- @column chunk_text  - Preview text for this chunk
+-- @column created_at  - When embedding was created
+CREATE TABLE IF NOT EXISTS mcard_vector_metadata (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    hash TEXT NOT NULL,
+    model_name TEXT NOT NULL,
+    dimensions INTEGER NOT NULL,
+    chunk_index INTEGER DEFAULT 0,
+    chunk_total INTEGER DEFAULT 1,
+    chunk_text TEXT,
+    created_at TEXT NOT NULL,
+    UNIQUE(hash, chunk_index)
+);
+
+-- @index idx_vector_metadata_hash
+-- @description Efficient lookup of embeddings by content hash
+CREATE INDEX IF NOT EXISTS idx_vector_metadata_hash 
+ON mcard_vector_metadata(hash);
+
+-- @table mcard_embeddings
+-- @description Fallback embedding storage when sqlite-vec is unavailable
+-- @column id          - Auto-increment primary key
+-- @column metadata_id - FK to mcard_vector_metadata.id
+-- @column embedding   - Serialized float32 vector as BLOB
+CREATE TABLE IF NOT EXISTS mcard_embeddings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    metadata_id INTEGER NOT NULL,
+    embedding BLOB NOT NULL,
+    UNIQUE(metadata_id),
+    FOREIGN KEY (metadata_id) REFERENCES mcard_vector_metadata(id)
+);
+
+-- @virtual_table mcard_fts
+-- @description Full-text search for hybrid retrieval
+-- @note Uses Porter stemming with Unicode support
+CREATE VIRTUAL TABLE IF NOT EXISTS mcard_fts USING fts5(
+    hash,
+    content,
+    tokenize='porter unicode61'
+);
+
+-- Note: sqlite-vec virtual table is created dynamically with dimensions:
+-- CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
+--     metadata_id INTEGER PRIMARY KEY,
+--     embedding float[${dimensions}]
+-- );
+
+
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- LAYER 4: SEMANTIC VERSIONING (Handle-Vector Bridge)
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- Bridges handles to vector embeddings for semantic version comparison.
+-- Enables measuring semantic drift between document versions.
+
+-- @table handle_version_vectors
+-- @description Links handle versions to their semantic embeddings
+-- @column id                        - Auto-increment primary key
+-- @column handle                    - FK to handle_registry.handle
+-- @column hash                      - FK to card.hash (this version)
+-- @column parent_hash               - FK to card.hash (previous version)
+-- @column version_order             - 0 = current, 1 = previous, etc.
+-- @column is_current                - TRUE if this is the current version
+-- @column embedding_id              - FK to mcard_vector_metadata.id
+-- @column semantic_delta_from_parent - Cosine similarity to parent [-1, 1]
+-- @column upgrade_type              - Classification: 'trivial' | 'minor' | 'major' | 'breaking'
+-- @column created_at                - When this version was linked
+CREATE TABLE IF NOT EXISTS handle_version_vectors (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    handle TEXT NOT NULL,
+    hash TEXT NOT NULL,
+    parent_hash TEXT,
+    version_order INTEGER NOT NULL,
+    is_current BOOLEAN DEFAULT FALSE,
+    embedding_id INTEGER,
+    semantic_delta_from_parent REAL,
+    upgrade_type TEXT,
+    created_at TEXT NOT NULL,
+    UNIQUE(handle, hash),
+    FOREIGN KEY (embedding_id) REFERENCES mcard_vector_metadata(id)
+);
+
+-- @index idx_hvv_handle
+-- @description Efficient lookup of versions by handle
+CREATE INDEX IF NOT EXISTS idx_hvv_handle 
+ON handle_version_vectors(handle);
+
+-- @index idx_hvv_hash
+-- @description Efficient lookup of versions by hash
+CREATE INDEX IF NOT EXISTS idx_hvv_hash 
+ON handle_version_vectors(hash);
+
+-- @index idx_hvv_current
+-- @description Efficient lookup of current versions
+CREATE INDEX IF NOT EXISTS idx_hvv_current 
+ON handle_version_vectors(is_current);
+
+-- @index idx_hvv_parent
+-- @description Efficient lookup by parent hash
+CREATE INDEX IF NOT EXISTS idx_hvv_parent 
+ON handle_version_vectors(parent_hash);
+
+-- @table version_similarity_cache
+-- @description Precomputed pairwise similarities for performance
+-- @column id               - Auto-increment primary key
+-- @column handle           - Handle these versions belong to
+-- @column hash_a           - First version hash
+-- @column hash_b           - Second version hash
+-- @column similarity_score - Cosine similarity [-1, 1]
+-- @column distance_euclidean - L2 distance [0, ∞)
+-- @column computed_at      - When similarity was computed
+CREATE TABLE IF NOT EXISTS version_similarity_cache (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    handle TEXT NOT NULL,
+    hash_a TEXT NOT NULL,
+    hash_b TEXT NOT NULL,
+    similarity_score REAL NOT NULL,
+    distance_euclidean REAL,
+    computed_at TEXT NOT NULL,
+    UNIQUE(handle, hash_a, hash_b)
+);
+
+-- @index idx_vsc_handle
+-- @description Efficient lookup of cached similarities by handle
+CREATE INDEX IF NOT EXISTS idx_vsc_handle 
+ON version_similarity_cache(handle);
+
+
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- LAYER 5: KNOWLEDGE GRAPH (GraphRAG)
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- Storage for extracted knowledge graph entities and relationships.
+
+-- @table graph_entities
+-- @description Nodes in the knowledge graph
+-- @column id          - Auto-increment primary key
+-- @column name        - Entity name
+-- @column type        - Entity type (e.g., "Person", "Organization")
+-- @column description - Optional description
+-- @column source_hash - FK to card.hash where entity was extracted
+-- @column embedding   - Optional entity embedding
+-- @column created_at  - When entity was created
+CREATE TABLE IF NOT EXISTS graph_entities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    type TEXT NOT NULL,
+    description TEXT,
+    source_hash TEXT NOT NULL,
+    embedding BLOB,
+    created_at TEXT NOT NULL,
+    UNIQUE(name, type, source_hash)
+);
+
+-- @index idx_entity_name
+-- @description Efficient entity lookup by name
+CREATE INDEX IF NOT EXISTS idx_entity_name 
+ON graph_entities(name);
+
+-- @index idx_entity_type
+-- @description Efficient entity lookup by type
+CREATE INDEX IF NOT EXISTS idx_entity_type 
+ON graph_entities(type);
+
+-- @index idx_entity_source
+-- @description Efficient entity lookup by source document
+CREATE INDEX IF NOT EXISTS idx_entity_source 
+ON graph_entities(source_hash);
+
+-- @table graph_relationships
+-- @description Edges in the knowledge graph
+-- @column id               - Auto-increment primary key
+-- @column source_entity_id - FK to graph_entities.id (from)
+-- @column target_entity_id - FK to graph_entities.id (to)
+-- @column relationship     - Relationship type/label
+-- @column description      - Optional description
+-- @column weight           - Relationship strength
+-- @column source_hash      - FK to card.hash where relationship was extracted
+-- @column created_at       - When relationship was created
+CREATE TABLE IF NOT EXISTS graph_relationships (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_entity_id INTEGER NOT NULL,
+    target_entity_id INTEGER NOT NULL,
+    relationship TEXT NOT NULL,
+    description TEXT,
+    weight REAL DEFAULT 1.0,
+    source_hash TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    UNIQUE(source_entity_id, target_entity_id, relationship, source_hash),
+    FOREIGN KEY (source_entity_id) REFERENCES graph_entities(id),
+    FOREIGN KEY (target_entity_id) REFERENCES graph_entities(id)
+);
+
+-- @index idx_rel_source
+-- @description Efficient lookup of relationships by source entity
+CREATE INDEX IF NOT EXISTS idx_rel_source 
+ON graph_relationships(source_entity_id);
+
+-- @index idx_rel_target
+-- @description Efficient lookup of relationships by target entity
+CREATE INDEX IF NOT EXISTS idx_rel_target 
+ON graph_relationships(target_entity_id);
+
+-- @table graph_communities
+-- @description Hierarchical community summaries (GraphRAG)
+-- @column id                  - Auto-increment primary key
+-- @column level               - Hierarchy level (0 = leaf)
+-- @column title               - Community title
+-- @column summary             - AI-generated summary
+-- @column embedding           - Community embedding
+-- @column member_entity_ids   - JSON array of entity IDs
+-- @column parent_community_id - FK to parent community
+-- @column created_at          - When community was created
+CREATE TABLE IF NOT EXISTS graph_communities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    level INTEGER NOT NULL DEFAULT 0,
+    title TEXT,
+    summary TEXT NOT NULL,
+    embedding BLOB,
+    member_entity_ids TEXT,
+    parent_community_id INTEGER,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (parent_community_id) REFERENCES graph_communities(id)
+);
+
+-- @index idx_community_level
+-- @description Efficient lookup of communities by level
+CREATE INDEX IF NOT EXISTS idx_community_level 
+ON graph_communities(level);
+
+-- @table graph_extractions
+-- @description Tracks which documents have been processed for entity extraction
+-- @column hash               - FK to card.hash (primary key)
+-- @column entity_count       - Number of entities extracted
+-- @column relationship_count - Number of relationships extracted
+-- @column extracted_at       - When extraction was performed
+CREATE TABLE IF NOT EXISTS graph_extractions (
+    hash TEXT PRIMARY KEY,
+    entity_count INTEGER DEFAULT 0,
+    relationship_count INTEGER DEFAULT 0,
+    extracted_at TEXT NOT NULL
+);
+
+-- ═══════════════════════════════════════════════════════════════════════════════
+-- SCHEMA METADATA (Vector DB)
+-- ═══════════════════════════════════════════════════════════════════════════════
+
+-- @table schema_version
+-- @description Tracks schema version for migrations
+CREATE TABLE IF NOT EXISTS vector_schema_version (
+    version TEXT PRIMARY KEY,
+    applied_at TEXT NOT NULL,
+    description TEXT
+);
+
+-- Insert current schema version
+INSERT OR IGNORE INTO vector_schema_version (version, applied_at, description)
+VALUES ('1.0.0', datetime('now'), 'Initial MCard Vector Schema');

clm/schemas/mlp-context-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcard.org/schemas/mlp-context-v1.json",
+  "title": "Multi-Language Protocol (MLP) Context Schema",
+  "description": "Defines the standardized context block passed to all polyglot runtimes via stdin or env variables in the CLM kernel.",
+  "type": "object",
+  "required": [
+    "context",
+    "environment",
+    "databases"
+  ],
+  "properties": {
+    "context": {
+      "type": "object",
+      "required": [
+        "operation",
+        "clm_file",
+        "a_hash",
+        "c_hash"
+      ],
+      "properties": {
+        "operation": {
+          "type": "string",
+          "description": "The active function/operation name executing in the CLM."
+        },
+        "clm_file": {
+          "type": "string",
+          "description": "Absolute filesystem path to the target CLM manifest."
+        },
+        "a_hash": {
+          "type": "string",
+          "pattern": "^sha256:[a-fA-F0-9]{64}$",
+          "description": "Cryptographic SHA-256 hash of the Abstract Specification (A-MCard)."
+        },
+        "c_hash": {
+          "type": "string",
+          "pattern": "^sha256:[a-fA-F0-9]{64}$",
+          "description": "Cryptographic SHA-256 hash of the Concrete Implementation (C-MCard)."
+        },
+        "payload": {
+          "type": "string",
+          "description": "Optional payload input parameter passed to the active process."
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "CLM_ROOT",
+        "g_time"
+      ],
+      "properties": {
+        "CLM_ROOT": {
+          "type": "string",
+          "description": "Absolute path to the active clm/ repository directory."
+        },
+        "PROJECT_ROOT": {
+          "type": "string",
+          "description": "Absolute path to the parent MCard_TDD/ directory."
+        },
+        "g_time": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
+          "description": "Standardized ISO 8601 global evaluation timestamp."
+        }
+      }
+    },
+    "databases": {
+      "type": "object",
+      "required": [
+        "identity_db",
+        "content_db",
+        "execution_log_db"
+      ],
+      "properties": {
+        "identity_db": {
+          "type": "string",
+          "description": "Absolute path to the SQLite identity_space database."
+        },
+        "content_db": {
+          "type": "string",
+          "description": "Absolute path to the SQLite content_memory database."
+        },
+        "execution_log_db": {
+          "type": "string",
+          "description": "Absolute path to the SQLite execution_log database."
+        }
+      }
+    }
+  }
+}

clm_kernel-0.0.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: clm-kernel
+Version: 0.0.0
+Summary: Card Lifecycle Manager (CLM) Kernel — Sovereign Functional Agentic Operating System
+Author: GovTech Digital Identity & Autonomous Systems
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.17.0
+Requires-Dist: base58>=2.1.1
+Requires-Dist: blake3>=0.4.0
+Requires-Dist: chardet>=5.1.0
+Requires-Dist: cryptography>=44.0.0
+Requires-Dist: duckdb>=1.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: result>=0.17.0
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: sqlalchemy>=1.4.0
+Requires-Dist: typing-extensions>=4.5.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: hatchling>=1.20.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: native
+Description-Content-Type: text/markdown
+
+# clm-kernel
+
+Card Lifecycle Manager (CLM) Kernel — Sovereign Functional Agentic Operating System.
+
+`clm-kernel` is the foundational Python implementation of the Cubical Logic Model (CLM), providing a stratified 5-layer architecture for sovereign, functional, deterministically auditable agentic execution.
+
+## Architectural Layers
+
+- **Layer 0: Cryptographic Substrate & Storage**
+  - Content-addressable storage via BLAKE3 hashing
+  - Merkle DAG tree synthesis and verification
+  - TriDatabase manager and multi-agent Vector Clocks
+- **Layer 1: Type Lattice & Schema Model**
+  - Pydantic-backed invariant validation
+  - Deterministic AST transformations and MCard schemas
+- **Layer 2: Reactive Graph & CPN-VM**
+  - Coloured Petri Net (CPN) virtual machine
+  - Token passing, transition firings, and concurrency invariants
+- **Layer 3: Cordis Spatiotemporal Actor Model**
+  - Effect isolation, savepoints (`SavepointGuard`), and cleanup scopes (`DisposableList`)
+  - Monadic execution with rollback guarantees
+- **Layer 4: Sovereign Execution & Gateway**
+  - Full CLI (`clm`, `clmEval`)
+  - Triad Gateway and Model Context Protocol (MCP) server integration
+
+## Installation
+
+```bash
+pip install clm-kernel
+```
+
+## CLI Usage
+
+```bash
+# Display CLI help
+clm --help
+
+# Evaluate an action or workflow manifest
+clm evaluate --file workflow.yaml
+
+# Initialize TriDatabase storage
+clm init-tridb --path ./data
+```
+
+## Python API Quick Start
+
+```python
+from clm.layer0.merkle import MerkleTree
+from clm.layer4 import SovereignExecutor
+
+# Create and verify Merkle DAG
+tree = MerkleTree()
+tree.insert("card-1", b"payload data")
+root_hash = tree.compute_root()
+print(f"Merkle Root: {root_hash}")
+```
+
+## License
+
+MIT License. See [LICENSE](https://github.com/xlp0/CLM/blob/main/LICENSE) for details.
+
+## Monorepo & Documentation
+
+Source code, formal proofs, and multi-language kernels (Rust, JavaScript/TypeScript, WASM) are maintained in the main [CLM Repository](https://github.com/xlp0/CLM).