clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/operations/manipulators/document.py

@@ -0,0 +1,211 @@
+"""Document Baldwin Modularity Manipulator (Sprint 393 / DEL-393-02).
+
+Algebraic operations over Markdown and structured text documents:
+- split: Partition Markdown by heading hierarchy (e.g. H2 headings).
+- substitute: Replace text blocks, keywords, or section contents.
+- augment: Inject/update YAML frontmatter or append sections.
+- exclude: Redact sections by heading or strip comments/frontmatter.
+- invert: Invert section ordering or reverse document flow.
+- port: Transcode Markdown to plain text or HTML.
+
+Layer 1 module (no imports above L1).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+
+class DocumentManipulator:
+    """Modality manipulator for Markdown and text documents."""
+
+    @staticmethod
+    def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+        """Extract YAML frontmatter if present."""
+        if text.startswith("---\n"):
+            parts = text.split("---\n", 2)
+            if len(parts) >= 3:
+                try:
+                    fm = yaml.safe_load(parts[1])
+                    body = parts[2]
+                    return fm if isinstance(fm, dict) else {}, body
+                except Exception:
+                    pass
+        return {}, text
+
+    @staticmethod
+    def _render_document(frontmatter: dict[str, Any], body: str) -> str:
+        """Combine YAML frontmatter with body."""
+        if not frontmatter:
+            return body
+        fm_str = yaml.dump(frontmatter, sort_keys=False)
+        return f"---\n{fm_str}---\n{body.lstrip()}"
+
+    @classmethod
+    def split(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> dict[str, str]:
+        """Split a Markdown document by heading level (default H2 ##).
+
+        Returns a dictionary mapping section titles to section Markdown text.
+        """
+        params = parameters or {}
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        heading_level = params.get("heading_level", 2)
+        pattern = rf"^({'#' * heading_level}\s+.+)$"
+
+        sections = re.split(pattern, text, flags=re.MULTILINE)
+        if len(sections) <= 1:
+            return {"document": text}
+
+        results: dict[str, str] = {}
+        intro = sections[0].strip()
+        if intro:
+            results["intro"] = intro
+
+        # sections has alternating [heading, content, heading, content...]
+        i = 1
+        while i < len(sections):
+            heading = sections[i].strip().lstrip("#").strip()
+            content = sections[i + 1].strip() if i + 1 < len(sections) else ""
+            clean_key = re.sub(r"[^a-zA-Z0-9_\-]+", "_", heading.lower()).strip("_") or f"section_{i}"
+            results[clean_key] = f"{sections[i]}\n\n{content}".strip()
+            i += 2
+
+        return results
+
+    @classmethod
+    def substitute(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Substitute text or patterns in a document."""
+        params = parameters or {}
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        replacements = params.get("replacements", {})
+
+        res = text
+        for old, new in replacements.items():
+            res = res.replace(old, str(new))
+        return res
+
+    @classmethod
+    def augment(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Augment document by updating frontmatter or appending content."""
+        params = parameters or {}
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        fm, body = cls._parse_frontmatter(text)
+
+        frontmatter_add = params.get("frontmatter", {})
+        append_content = params.get("append", "")
+
+        fm.update(frontmatter_add)
+        new_body = body
+        if append_content:
+            new_body = f"{body.rstrip()}\n\n{append_content}\n"
+
+        return cls._render_document(fm, new_body)
+
+    @classmethod
+    def exclude(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Exclude (redact) sections by heading or remove frontmatter."""
+        params = parameters or {}
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        exclude_sections = set(params.get("sections", []))
+        strip_frontmatter = params.get("strip_frontmatter", False)
+
+        fm, body = cls._parse_frontmatter(text)
+        if strip_frontmatter:
+            fm = {}
+
+        if exclude_sections:
+            # Filter out sections matching headings
+            pattern = r"^(#{1,6}\s+.+)$"
+            parts = re.split(pattern, body, flags=re.MULTILINE)
+            filtered_body = [parts[0]]
+            i = 1
+            while i < len(parts):
+                heading_line = parts[i]
+                heading_text = heading_line.strip().lstrip("#").strip()
+                content = parts[i + 1] if i + 1 < len(parts) else ""
+                if heading_text not in exclude_sections:
+                    filtered_body.append(heading_line)
+                    filtered_body.append(content)
+                i += 2
+            body = "".join(filtered_body)
+
+        return cls._render_document(fm, body)
+
+    @classmethod
+    def invert(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        _ = parameters
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        fm, body = cls._parse_frontmatter(text)
+
+        pattern = r"^(#{1,6}\s+.+)$"
+        parts = re.split(pattern, body, flags=re.MULTILINE)
+        if len(parts) <= 1:
+            return text
+
+        intro = parts[0]
+        sections: list[str] = []
+        i = 1
+        while i < len(parts):
+            heading_line = parts[i]
+            content = parts[i + 1] if i + 1 < len(parts) else ""
+            sections.append(f"{heading_line}{content}")
+            i += 2
+
+        reversed_body = intro + "".join(reversed(sections))
+        return cls._render_document(fm, reversed_body)
+
+    @classmethod
+    def port(
+        cls,
+        data: str | bytes,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Port Markdown to plain text or basic HTML."""
+        params = parameters or {}
+        target_fmt = params.get("target_format", "text").lower()
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        _, body = cls._parse_frontmatter(text)
+
+        if target_fmt == "html":
+            # Simple conversion of headings and paragraphs
+            lines = body.splitlines()
+            html_lines: list[str] = []
+            for ln in lines:
+                if ln.startswith("### "):
+                    html_lines.append(f"<h3>{ln[4:].strip()}</h3>")
+                elif ln.startswith("## "):
+                    html_lines.append(f"<h2>{ln[3:].strip()}</h2>")
+                elif ln.startswith("# "):
+                    html_lines.append(f"<h1>{ln[2:].strip()}</h1>")
+                elif ln.strip():
+                    html_lines.append(f"<p>{ln.strip()}</p>")
+            return "\n".join(html_lines)
+
+        # Default plain text: strip markdown syntax
+        plain = re.sub(r"^#{1,6}\s+", "", body, flags=re.MULTILINE)
+        plain = re.sub(r"\[(.*?)\]\(.*?\)", r"\1", plain)
+        plain = re.sub(r"[*_`]", "", plain)
+        return plain.strip()

clm/layer1/operations/manipulators/media.py

@@ -0,0 +1,134 @@
+"""Media Baldwin Modularity Manipulator (Sprint 393 / DEL-393-02).
+
+Algebraic operations over Binary and Multi-Media assets (images, audio, 3D models):
+- split: Chunk bytes into partitions or slice channels.
+- substitute: Replace byte segments or metadata blocks.
+- augment: Extract and embed structural media headers.
+- exclude: Strip EXIF or trailing metadata chunks for privacy.
+- invert: Invert byte payloads (bit-level complement).
+- port: Transcode representation (raw bytes to base64, SVG to XML).
+
+Layer 1 module (no imports above L1).
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+
+class MediaManipulator:
+    """Modality manipulator for binary and media assets."""
+
+    @staticmethod
+    def _to_bytes(data: Any) -> bytes:
+        if isinstance(data, bytes):
+            return data
+        if isinstance(data, str):
+            # Check if base64 encoded
+            try:
+                return base64.b64decode(data)
+            except Exception:
+                return data.encode("utf-8")
+        return bytes(str(data), encoding="utf-8")
+
+    @classmethod
+    def split(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> dict[str, bytes]:
+        """Split binary asset into chunks."""
+        b = cls._to_bytes(data)
+        params = parameters or {}
+        chunk_size = params.get("chunk_size")
+
+        if chunk_size and chunk_size > 0:
+            chunks: dict[str, bytes] = {}
+            for i in range(0, len(b), chunk_size):
+                chunks[f"chunk_{i // chunk_size}"] = b[i : i + chunk_size]
+            return chunks
+
+        # Default 50/50 split
+        mid = len(b) // 2
+        return {
+            "part_1": b[:mid],
+            "part_2": b[mid:],
+        }
+
+    @classmethod
+    def substitute(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> bytes:
+        """Substitute byte patterns in media."""
+        b = cls._to_bytes(data)
+        params = parameters or {}
+        old_bytes = params.get("old_bytes")
+        new_bytes = params.get("new_bytes", b"")
+
+        if old_bytes and isinstance(old_bytes, bytes):
+            return b.replace(old_bytes, new_bytes)
+        return b
+
+    @classmethod
+    def augment(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Extract and return media metadata annotations."""
+        b = cls._to_bytes(data)
+        params = parameters or {}
+        tag = params.get("tag", "processed")
+
+        meta: dict[str, Any] = {
+            "byte_size": len(b),
+            "tag": tag,
+        }
+        if len(b) >= 8 and b.startswith(b"\x89PNG\r\n\x1a\n"):
+            meta["mime_type"] = "image/png"
+        elif len(b) >= 3 and b.startswith(b"\xff\xd8\xff"):
+            meta["mime_type"] = "image/jpeg"
+        elif b.startswith(b"%PDF-"):
+            meta["mime_type"] = "application/pdf"
+        return meta
+
+    @classmethod
+    def exclude(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> bytes:
+        """Strip trailing padding or metadata from media bytes."""
+        b = cls._to_bytes(data)
+        params = parameters or {}
+        strip_bytes = params.get("strip_trailing_zeros", True)
+        if strip_bytes:
+            return b.rstrip(b"\x00")
+        return b
+
+    @classmethod
+    def invert(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> bytes:
+        """Bitwise complement of media bytes."""
+        b = cls._to_bytes(data)
+        return bytes(x ^ 0xFF for x in b)
+
+    @classmethod
+    def port(
+        cls,
+        data: Any,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Port binary media to base64 string or ASCII hex."""
+        b = cls._to_bytes(data)
+        params = parameters or {}
+        target_fmt = params.get("target_format", "base64").lower()
+        if target_fmt == "hex":
+            return b.hex()
+        return base64.b64encode(b).decode("ascii")

clm/layer1/operations/manipulators/structured.py

@@ -0,0 +1,159 @@
+"""Structured Data Baldwin Modularity Manipulator (Sprint 393 / DEL-393-02).
+
+Algebraic operations over JSON and YAML structured data:
+- split: Partition dictionary keys or array elements into disjoint sub-objects.
+- substitute: Replace values at specific key paths.
+- augment: Merge attributes or enrich structures with metadata.
+- exclude: Redact sensitive keys (PII/secrets) recursively.
+- invert: Invert key-value mappings or reverse arrays.
+- port: Transcode JSON to YAML or YAML to JSON.
+
+Layer 1 module (no imports above L1).
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from typing import Any
+
+import yaml
+
+
+class StructuredManipulator:
+    """Modality manipulator for JSON and YAML structured data."""
+
+    @staticmethod
+    def _parse_data(data: str | bytes | dict | list) -> tuple[Any, str]:
+        """Parse raw JSON/YAML or return structured object."""
+        if isinstance(data, (dict, list)):
+            return copy.deepcopy(data), "object"
+        text = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        stripped = text.strip()
+        if stripped.startswith("{") or stripped.startswith("["):
+            try:
+                return json.loads(stripped), "json"
+            except Exception:
+                pass
+        try:
+            return yaml.safe_load(stripped), "yaml"
+        except Exception:
+            return {"raw": text}, "raw"
+
+    @classmethod
+    def split(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Split a structured object into partitions by key sets."""
+        params = parameters or {}
+        obj, fmt = cls._parse_data(data)
+        if not isinstance(obj, dict):
+            return {"all": obj}
+
+        key_groups = params.get("groups", {})
+        if key_groups:
+            partitions: dict[str, dict[str, Any]] = {}
+            for group_name, keys in key_groups.items():
+                partitions[group_name] = {k: obj[k] for k in keys if k in obj}
+            return partitions
+
+        # Default split: split keys in half
+        keys = list(obj.keys())
+        mid = len(keys) // 2
+        return {
+            "part_1": {k: obj[k] for k in keys[:mid]},
+            "part_2": {k: obj[k] for k in keys[mid:]},
+        }
+
+    @classmethod
+    def substitute(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> Any:
+        """Substitute values or rename keys at specified paths."""
+        params = parameters or {}
+        obj, fmt = cls._parse_data(data)
+        replacements = params.get("replacements", {})
+
+        if isinstance(obj, dict):
+            for k, new_v in replacements.items():
+                if k in obj:
+                    obj[k] = new_v
+        return obj
+
+    @classmethod
+    def augment(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> Any:
+        """Augment structured object with new fields or metadata."""
+        params = parameters or {}
+        obj, fmt = cls._parse_data(data)
+        fields = params.get("fields", {})
+
+        if isinstance(obj, dict):
+            obj.update(fields)
+        elif isinstance(obj, list) and isinstance(fields, dict):
+            obj.append(fields)
+        return obj
+
+    @classmethod
+    def exclude(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> Any:
+        """Recursively exclude specified keys from structured data."""
+        params = parameters or {}
+        obj, fmt = cls._parse_data(data)
+        exclude_keys = set(params.get("keys", []))
+
+        def _prune(item: Any) -> Any:
+            if isinstance(item, dict):
+                return {k: _prune(v) for k, v in item.items() if k not in exclude_keys}
+            elif isinstance(item, list):
+                return [_prune(x) for x in item]
+            return item
+
+        return _prune(obj)
+
+    @classmethod
+    def invert(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> Any:
+        _ = parameters
+        obj, fmt = cls._parse_data(data)
+
+        if isinstance(obj, dict):
+            # Invert key/value if values are hashable
+            inverted: dict[str, str] = {}
+            for k, v in obj.items():
+                if isinstance(v, (str, int, float, bool)):
+                    inverted[str(v)] = str(k)
+                else:
+                    inverted[str(k)] = str(v)
+            return inverted
+        elif isinstance(obj, list):
+            return list(reversed(obj))
+        return obj
+
+    @classmethod
+    def port(
+        cls,
+        data: str | bytes | dict | list,
+        parameters: dict[str, Any] | None = None,
+    ) -> str:
+        """Port between JSON and YAML."""
+        params = parameters or {}
+        target_fmt = params.get("target_format", "yaml").lower()
+        obj, _ = cls._parse_data(data)
+
+        if target_fmt in ("json", "application/json"):
+            return json.dumps(obj, indent=2)
+        return yaml.dump(obj, sort_keys=False)