clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/api.py

@@ -0,0 +1,236 @@
+import uvicorn
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from pydantic import BaseModel
+
+from clm.cross_cutting.config.logging import (
+    SecurityAuditLogger,
+    get_logger,
+    setup_logging,
+)
+from clm.layer0.model.card import MCard
+from clm.layer2.card_collection import CardCollection
+
+# Configure logging
+setup_logging()
+logger = get_logger(__name__)
+security_audit = SecurityAuditLogger()
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="MCard API",
+    description="API for managing MCard content-addressable storage.",
+    version="1.0.0",
+)
+
+# Initialize CardCollection. This will use the default database path.
+try:
+    card_collection = CardCollection()
+    db_path = getattr(card_collection.engine, "db_path", "unknown")
+    logger.info(f"CardCollection initialized with DB at: {db_path}")
+except Exception as e:
+    logger.critical(f"Failed to initialize CardCollection: {e}")
+    raise RuntimeError(f"Could not initialize database connection: {e}") from e
+
+
+@app.post("/content/cards", status_code=201)
+async def store_content_card(
+    content: UploadFile = File(...),
+    metadata: str | None = Form(None),  # Metadata sent as a JSON string
+):
+    """
+    Store new content and create an MCard.
+
+    - **content**: The file content to be stored.
+    - **metadata**: Optional JSON string containing metadata.
+    """
+    try:
+        # Read content from the uploaded file
+        file_content = await content.read()
+        if not file_content:
+            raise HTTPException(status_code=400, detail="Content cannot be empty.")
+
+        # Create an MCard instance
+        mcard = MCard(content=file_content)
+
+        # Add the card to the collection using a thread pool
+        import asyncio
+
+        card_hash = await asyncio.to_thread(card_collection.add, mcard)
+
+        # Retrieve the newly stored card to return its details
+        stored_card = await asyncio.to_thread(card_collection.get, mcard.get_hash())
+        if not stored_card:
+            raise HTTPException(
+                status_code=500, detail="Failed to retrieve card after adding."
+            )
+
+        response_data = {
+            "hash": stored_card.get_hash(),
+            "content_type": stored_card.get_content_type(),
+            "g_time": stored_card.get_g_time(),
+            "message": "Content stored successfully",
+        }
+
+        if card_hash != mcard.get_hash():
+            collision_msg = (
+                f"Content already exists or a hash collision occurred. "
+                f"Event card created with hash: {card_hash}"
+            )
+            response_data["message"] = collision_msg
+            response_data["event_hash"] = card_hash
+
+        return response_data
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(f"Validation error while creating card: {e}")
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    except Exception as e:
+        logger.error(
+            f"An unexpected error occurred while storing content: {e}", exc_info=True
+        )
+        raise HTTPException(
+            status_code=500, detail="An internal server error occurred."
+        ) from e
+
+
+# --- Pydantic Models for API Responses ---
+
+
+class CardResponse(BaseModel):
+    hash: str
+    content_type: str
+    g_time: str
+    metadata: dict | None = None
+
+
+class PaginatedCardResponse(BaseModel):
+    items: list[CardResponse]
+    total_items: int
+    page_number: int
+    page_size: int
+    total_pages: int
+    has_next: bool
+    has_previous: bool
+
+
+@app.get("/content/cards", response_model=PaginatedCardResponse)
+async def list_content_cards(
+    query: str | None = None, page: int = 1, page_size: int = 10
+):
+    """
+    List content cards with pagination and optional search.
+
+    - **query**: Optional search string to filter cards by content.
+    - **page**: The page number to retrieve.
+    - **page_size**: The number of items per page.
+    """
+    try:
+        import asyncio
+
+        # Ensure await is used for asynchronous operations by threading sync operations
+        if query:
+            page_obj = await asyncio.to_thread(
+                card_collection.search_by_content,
+                search_string=query,
+                page_number=page,
+                page_size=page_size,
+            )
+        else:
+            page_obj = await asyncio.to_thread(
+                card_collection.get_page, page_number=page, page_size=page_size
+            )
+
+        # Convert MCard objects to a serializable format
+        response_items = [
+            CardResponse(
+                hash=card.get_hash(),
+                content_type=card.get_content_type(),
+                g_time=card.get_g_time(),
+            )
+            for card in page_obj.items
+        ]
+
+        return PaginatedCardResponse(
+            items=response_items,
+            total_items=page_obj.total_items,
+            page_number=page_obj.page_number,
+            page_size=page_obj.page_size,
+            total_pages=page_obj.total_pages,
+            has_next=page_obj.has_next,
+            has_previous=page_obj.has_previous,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error listing cards: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500, detail="An internal server error occurred."
+        ) from e
+
+
+@app.get("/content/cards/{hash}", response_model=CardResponse)
+async def get_content_card(hash: str):
+    """
+    Retrieve a single content card by its hash.
+
+    - **hash**: The SHA-256 hash of the content card to retrieve.
+    """
+    try:
+        import asyncio
+
+        # Ensure await is used via thread pool
+        card = await asyncio.to_thread(card_collection.get, hash)
+        if not card:
+            raise HTTPException(status_code=404, detail="Card not found.")
+
+        return CardResponse(
+            hash=card.get_hash(),
+            content_type=card.get_content_type(),
+            g_time=card.get_g_time(),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error retrieving card {hash}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500, detail="An internal server error occurred."
+        ) from e
+
+
+@app.delete("/content/cards/{hash}", status_code=204)
+async def delete_content_card(hash: str):
+    """
+    Delete a content card by its hash.
+
+    - **hash**: The SHA-256 hash of the content card to delete.
+    """
+    try:
+        import asyncio
+
+        # Ensure await is used via thread pool
+        success = await asyncio.to_thread(card_collection.delete, hash)
+        if not success:
+            raise HTTPException(
+                status_code=404, detail="Card not found or could not be deleted."
+            )
+        # Return None to produce a 204 No Content response
+        return None
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting card {hash}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500, detail="An internal server error occurred."
+        ) from e
+
+
+def start_api_server():
+    """Starts the Uvicorn server."""
+    logger.info("Starting MCard API server...")
+    uvicorn.run(app, host="0.0.0.0", port=28302, log_level="info")  # nosec B104
+
+
+if __name__ == "__main__":
+    start_api_server()

clm/layer4/bootstrap/__init__.py

@@ -0,0 +1,13 @@
+"""MCard Bootstrap logic encapsulation.
+
+Defines natively pure functionality previously housed implicitly in shell wrapper architecture.
+"""
+
+from clm.layer4.bootstrap.bootstrapper import KernelBootstrapper
+from clm.layer4.bootstrap.injection import SchemaInjector, compute_shannon_entropy
+
+__all__ = [
+    "KernelBootstrapper",
+    "SchemaInjector",
+    "compute_shannon_entropy",
+]

clm/layer4/bootstrap/bootstrapper.py

@@ -0,0 +1,118 @@
+"""Kernel Bootstrapper.
+
+Enforces the Inception Constraint by deriving the initial system state and database
+topology exclusively from the narrative architectural documentation rather than
+hardcoded scripts.
+"""
+
+import logging
+import re
+from pathlib import Path
+
+import yaml
+
+from clm.cross_cutting.config.config_constants import _PROJECT_ROOT, META_FUNCTIONALITY_DB_PATH
+from clm.layer0.model.card import MCard
+from clm.layer2.card_collection import CardCollection
+
+logger = logging.getLogger(__name__)
+
+ARCHITECTURE_DOC_PATH = _PROJECT_ROOT / "clm" / "seed_clm_playbook.yaml"
+
+
+class KernelBootstrapper:
+    """Parses architectural docs to bootstrap the Kenotic Root `meta_functionality.db`."""
+
+    def __init__(
+        self,
+        override_doc_path: Path | None = None,
+        override_db_path: Path | None = None,
+    ) -> None:
+        self.doc_path = override_doc_path or ARCHITECTURE_DOC_PATH
+        self.db_path = override_db_path or META_FUNCTIONALITY_DB_PATH
+
+    def extract_yaml_clm(self) -> dict:
+        """Parse the resource to extract the executable configuration.
+
+        If the file is a YAML file, parses directly. If markdown, extracts the last YAML block.
+        Raises ValueError if the YAML block is missing or malformed.
+        """
+        if not self.doc_path.exists():
+            raise FileNotFoundError(
+                f"Architectural document not found: {self.doc_path}"
+            )
+
+        content = self.doc_path.read_text("utf-8")
+
+        if self.doc_path.suffix in (".yaml", ".yml"):
+            try:
+                return yaml.safe_load(content)
+            except yaml.YAMLError as exc:
+                raise ValueError(f"Failed to parse CLM YAML file: {exc}") from exc
+
+        # We look for the final yaml block (after the "Executable Kernel Topology Map" header)
+        matches = list(re.finditer(r"```yaml(.*?)```", content, flags=re.DOTALL))
+        if not matches:
+            raise ValueError(
+                "No YAML configuration blocks found in the architecture document."
+            )
+
+        # Take the last YAML block assuming it's the Bootloader Map
+        yaml_str = matches[-1].group(1).strip()
+
+        try:
+            return yaml.safe_load(yaml_str)
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Failed to parse CLM YAML block: {exc}") from exc
+
+    def bootstrap(self) -> CardCollection:
+        """Instantiate the Kenotic Root and provision foundational tables.
+
+        Returns:
+            CardCollection: The verified root collection pointing to the Mesh dependencies.
+        """
+        clm = self.extract_yaml_clm().get("clm")
+        if not clm or "concrete_impl" not in clm:
+            raise ValueError(
+                "Malformed CLM: expected root 'clm' dict with 'concrete_impl'."
+            )
+
+        databases = clm["concrete_impl"].get("databases", {})
+        if not databases:
+            raise ValueError("No databases map defined in the executable topology.")
+
+        # We construct the meta_functionality.db
+        root_collection = CardCollection(db_path=str(self.db_path))
+
+        # 1. Store the CLM bootloader itself as the initial N_0 Generalized Number
+        boot_card = MCard(content=yaml.dump({"clm": clm}, sort_keys=False))
+        if not root_collection.get(boot_card.hash):
+            root_collection.add(boot_card)
+
+        # 2. Extract database topologies and register their Pointers mapping to the Project Root
+        for db_name, rel_path in databases.items():
+            handle_name = f"pkc://db/{db_name}"
+            # The PCard/Pointer simply stores JSON metadata about the path
+            pointer_card = MCard(
+                content=yaml.dump(
+                    {
+                        "path": str(_PROJECT_ROOT / rel_path),
+                        "schema_version": "v1",
+                    }
+                )
+            )
+            if not root_collection.resolve_handle(handle_name):
+                root_collection.add_with_handle(pointer_card, handle_name)
+
+        # 3. Simulate codebase hash (normally this would be git hash)
+        codebase_pointer = MCard(
+            content=yaml.dump({"source": "local", "commit": "HEAD"})
+        )
+        if not root_collection.resolve_handle("pkc://codebase/current"):
+            root_collection.add_with_handle(codebase_pointer, "pkc://codebase/current")
+
+        # 4. Bootstrap complete.
+        logger.info(
+            "KernelBootstrapper successfully instantiated meta_functionality.db."
+        )
+        return root_collection

clm/layer4/bootstrap/cleanup.py

@@ -0,0 +1,44 @@
+import sys
+from pathlib import Path
+
+
+def execute(target_dir: str):
+    """
+    Executes the Database Cleanup Execution dynamically.
+    """
+    try:
+        from clm.layer0.loader import CLMChapterLoader
+    except ImportError:
+        print(
+            "[CLEANUP] Critical Error: clm core modules not detected. Ensure uv dependencies are synchronized."
+        )
+        sys.exit(1)
+
+    from clm.cross_cutting.config.settings import settings
+
+    bs_dir = Path(target_dir)
+    db_path = bs_dir / settings.bootstrap.db_dir
+
+    yaml_path = (
+        bs_dir / settings.bootstrap.manifests_dir / settings.bootstrap.cleanup_manifest
+    )
+    if not yaml_path.exists():
+        print(f"[CLEANUP] Critical Error: Cleanup schematic missing at {yaml_path}")
+        sys.exit(1)
+
+    chapter = CLMChapterLoader.load_from_yaml(str(yaml_path))
+
+    from clm.layer4.bootstrap.clm_hooks import execute_cleanup
+
+    payload = {"db_dir": str(db_path), "execute_cleanup": execute_cleanup}
+
+    chapter.run(payload, {})
+    print("\n[CLEANUP] Data execution explicitly removed cleanly.")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("[CLEANUP] Critical Error: Expected target directory as first argument.")
+        sys.exit(1)
+
+    execute(sys.argv[1])

clm/layer4/bootstrap/clm_hooks.py

@@ -0,0 +1,49 @@
+"""
+Logical implementation hooks extracted from standard Bootstrap CLM Manifests.
+Allows the YAML manifests to be devoid of massive inline implementation logic.
+"""
+
+
+def execute_cleanup(context: dict) -> dict:
+    """
+    Executes the cleanup logic explicitly wiping redundant duplicate content.
+    Extracted from cleanup_procedure.yaml
+    """
+    identities_db = context.get("identities_db")
+    content_db = context.get("content_db")
+    log_db = context.get("log_db")
+
+    if not identities_db or not content_db:
+        return {"status": "error", "message": "Missing topological database"}
+
+    print("\\n[CLEANUP] Requested deduplication on database.")
+
+    # A simple deduplication pass: if we have multiple hashes mapping to the identical content bytes,
+    # we leave the earliest (oldest) one and prune the rest to strictly save space and maintain topological soundness.
+    content_hashes_seen = set()
+    duplicates_removed = 0
+
+    all_cards = content_db.get_all_mcards_raw()
+
+    for card in all_cards:
+        # Maintain purely unique content. If content already exists, it is functionally redundant.
+        if card.content in content_hashes_seen:
+            content_db.delete(card.hash)
+            duplicates_removed += 1
+        else:
+            content_hashes_seen.add(card.content)
+
+    print(
+        f"[CLEANUP] Successfully wiped and decoupled isolated duplicates from disk. Deduped {duplicates_removed} cards."
+    )
+
+    # Record the cleanup execution natively into logs
+    if log_db:
+        from clm.layer0.model.card import MCard
+
+        log_message = (
+            f"Execution Trace: Deduplicated {duplicates_removed} cards dynamically."
+        )
+        log_db.add(MCard(log_message))
+
+    return {"status": "success", "duplicates_removed": duplicates_removed}

clm/layer4/bootstrap/genesis.py

@@ -0,0 +1,77 @@
+import sys
+from pathlib import Path
+
+from clm.layer2.card_collection import CardCollection
+
+
+def execute(target_dir: str):
+    """
+    Executes the Genesis Bootstrapping Procedure natively against the sandbox.
+    """
+    import importlib.util
+
+    if importlib.util.find_spec("clm.layer0.loader") is None:
+        print(
+            "[BOOTSTRAP] Critical Error: clm core modules not detected. Ensure uv dependencies are synchronized."
+        )
+        sys.exit(1)
+
+    from clm.cross_cutting.config.settings import settings
+
+    bs_dir = Path(target_dir)
+    db_path = bs_dir / settings.bootstrap.db_dir
+    db_path.mkdir(parents=True, exist_ok=True)
+
+    idx_db = CardCollection(db_path=str(db_path / settings.bootstrap.identity_db_name))
+    cont_db = CardCollection(db_path=str(db_path / settings.bootstrap.content_db_name))
+    log_db = CardCollection(db_path=str(db_path / settings.bootstrap.log_db_name))
+
+    yaml_path = (
+        bs_dir / settings.bootstrap.manifests_dir / settings.bootstrap.genesis_manifest
+    )
+    if not yaml_path.exists():
+        print(f"[BOOTSTRAP] Critical Error: Genesis schematic missing at {yaml_path}")
+        sys.exit(1)
+
+    from clm.layer1.engine import PTREngine
+
+    engine = PTREngine(storage_collection=cont_db)
+
+    payload = {
+        "identities_db": idx_db,
+        "content_db": cont_db,
+        "log_db": log_db,
+    }
+
+    from clm.layer0.model.card import MCard
+
+    dummy_target = MCard("genesis_bootstrap_target")
+    cont_db.add(dummy_target)
+    target_hash = dummy_target.hash
+
+    pcard_ref = f"file://{yaml_path.absolute()}"
+    print(f"\n[BOOTSTRAP] Initiating Petri Net Flow: {yaml_path.name}")
+
+    result = engine.execute_net(pcard_ref, target_hash, context=payload)  # type: ignore
+
+    if result.deadlocked or not result.completed:
+        print("\n[BOOTSTRAP] Genesis execution failed or deadlocked.")
+        if result.firings:
+            for f in result.firings:
+                if not f.success:
+                    print(f"  - Transition {f.transition_name} failed: {f.error}")
+        sys.exit(1)
+
+    print(
+        "\n[BOOTSTRAP] Genesis execution successfully verified and initialized fully natively."
+    )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(
+            "[BOOTSTRAP] Critical Error: Expected target directory as first argument."
+        )
+        sys.exit(1)
+
+    execute(sys.argv[1])

clm/layer4/bootstrap/injection.py

@@ -0,0 +1,125 @@
+"""Phase B: Schema Injection Module.
+
+Handles mapping abstract external configurations (YAML, text, binary blobs) into
+concrete MCard Database structures. Derives Categorical Typologies and securely
+populates information into the tri-database mesh using the Universal Polyglot structure.
+
+Incorporates the 5-E Framework by aggressively profiling informational density
+(Entropy) at the categorical inference stage.
+"""
+
+import logging
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import scipy.stats
+import yaml
+
+from clm.layer0.model.card import MCard
+from clm.layer2.card_collection import CardCollection
+
+logger = logging.getLogger(__name__)
+
+
+def compute_shannon_entropy(data: bytes) -> float:
+    """Compute the Shannon Entropy of the byte sequence for the 5-E framework.
+
+    This acts as a heuristic for Information Density and topological chaos limits.
+    """
+    if not data:
+        return 0.0
+    _, counts = np.unique(list(data), return_counts=True)
+    return float(scipy.stats.entropy(counts, base=2))
+
+
+class SchemaInjector:
+    """Injects and normalizes external configurations/blobs into the 3-table MCard Data Plane."""
+
+    def __init__(self, target_collection: CardCollection) -> None:
+        """Initialize the injector against a sovereign boundary.
+
+        Args:
+            target_collection: The root or isolated collection acting as the target Database.
+        """
+        self.collection = target_collection
+
+    def inject_blob(
+        self,
+        content: bytes,
+        handle_name: str | None = None,
+        inferred_mime: str | None = None,
+    ) -> tuple[MCard, float]:
+        """Inject an abstract binary/text blob into the structured Data Plane.
+
+        Evaluates the 5-E Entropy framework against the content, instantiates the MCard,
+        and derives a generic Categorical Topology wrapper.
+
+        Args:
+            content: The raw byte content.
+            handle_name: Optional persistent PKI/handle routing registry.
+            inferred_mime: Optional categorical modality.
+
+        Returns:
+            Tuple of the materialized MCard and its computed Shannon Entropy.
+        """
+        entropy = compute_shannon_entropy(content)
+        mcard = MCard(content)
+
+        if handle_name:
+            if not self.collection.resolve_handle(handle_name):
+                self.collection.add_with_handle(mcard, handle_name)
+                logger.info(
+                    f"Injected new MCard -> Handle '{handle_name}' (Entropy: {entropy:.4f})"
+                )
+            else:
+                self.collection.engine.update_handle(handle_name, mcard.hash)
+                logger.info(
+                    f"Updated Handle '{handle_name}' -> New Hash: {mcard.hash[:8]} (Entropy: {entropy:.4f})"
+                )
+        else:
+            self.collection.add(mcard)
+
+        # Log categorical typologies
+        logger.debug(
+            f"Categorical Inference: MIME={inferred_mime or 'application/octet-stream'}, Entropy={entropy:.4f}"
+        )
+
+        return mcard, entropy
+
+    def inject_file(
+        self, file_path: Path, explicit_handle: str | None = None
+    ) -> tuple[MCard, float]:
+        """Load an external file and dynamically infer its topological placement.
+
+        Args:
+            file_path: Physical disk path to inject.
+            explicit_handle: Optional handle. If none, falls back to `file://{name}`.
+        """
+        if not file_path.exists() or not file_path.is_file():
+            raise FileNotFoundError(
+                f"Cannot inject missing or non-file path: {file_path}"
+            )
+
+        mime_type, _ = mimetypes.guess_type(str(file_path))
+        mime_type = mime_type or "application/octet-stream"
+
+        handle = explicit_handle or f"file://{file_path.name}"
+        raw_bytes = file_path.read_bytes()
+
+        return self.inject_blob(raw_bytes, handle_name=handle, inferred_mime=mime_type)
+
+    def inject_yaml_schema(
+        self, clm_dict: dict[str, Any], handle_name: str | None = None
+    ) -> tuple[MCard, float]:
+        """Inject a rigorously structured dictionary acting as a Categorical Schema or CLM PCard.
+
+        Args:
+            clm_dict: Abstract Specification dictionary.
+            handle_name: Address.
+        """
+        content_bytes = yaml.dump(clm_dict, sort_keys=False).encode("utf-8")
+        return self.inject_blob(
+            content_bytes, handle_name=handle_name, inferred_mime="application/x-yaml"
+        )