osmp 2.0.0__tar.gz

osmp-2.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: osmp
+Version: 2.0.0
+Summary: OSMP -- Octid Semantic Mesh Protocol. Deterministic agentic instruction encoding.
+Author-email: Clay Holberg <clay@octid.io>
+Project-URL: Homepage, https://github.com/Octid-io/cloudless-sky
+Project-URL: Documentation, https://github.com/Octid-io/cloudless-sky/blob/main/protocol/spec/OSMP-SPEC-v1.md
+Project-URL: Repository, https://github.com/Octid-io/cloudless-sky
+Project-URL: Issues, https://github.com/Octid-io/cloudless-sky/issues
+Keywords: osmp,agentic,mesh,protocol,semantic,encoding,lora,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dpack
+Requires-Dist: zstandard>=0.21; extra == "dpack"
+
+# OSMP Python SDK
+
+Reference implementation of the Octid Semantic Mesh Protocol. Encodes, decodes, and validates agentic AI instructions using SAL (Semantic Assembly Language). 342 opcodes across 26 namespaces. Inference-free decode by table lookup.
+
+## Install
+
+```
+pip install osmp
+```
+
+Zero dependencies beyond Python standard library (optional `zstandard` for D:PACK).
+
+## Tier 1: Two Functions, Zero Setup
+
+```python
+from osmp import encode, decode
+
+sal = encode(["H:HR@NODE1>120", "H:CASREP", "M:EVA@*"])
+# "H:HR@NODE1>120;H:CASREP;M:EVA@*"
+
+text = decode("H:HR@NODE1>120;H:CASREP;M:EVA@*")
+# "heart_rate at NODE1 priority 120; casualty_report; evacuation at broadcast"
+```
+
+Three lines. No instantiation. Module-level singleton, cached on first call.
+
+### Additional Tier 1 Functions
+
+```python
+from osmp import validate, lookup, byte_size
+
+result = validate("R:MOV@BOT1⚠")
+print(result.valid)    # False -- ⚠ requires I:§ precondition
+
+definition = lookup("R:WPT")
+# "waypoint"
+
+print(byte_size("H:HR@NODE1>120"))
+# 15
+```
+
+## Tier 2: Class-Based Interface
+
+For configuration beyond defaults (custom ASD floor, pre-loaded dependency rules, direct ASD access):
+
+```python
+from osmp.core import OSMP
+
+o = OSMP()
+sal = o.encode(["H:HR@NODE1>120", "H:CASREP"])
+text = o.decode(sal)
+result = o.validate(sal)
+definition = o.lookup("H", "HR")
+```
+
+## Tier 3: Full Protocol Access
+
+Direct access to encoder, decoder, ASD, and all protocol internals:
+
+```python
+from osmp.protocol import SALEncoder, SALDecoder, AdaptiveSharedDictionary, validate_composition
+
+asd = AdaptiveSharedDictionary()
+enc = SALEncoder(asd)
+dec = SALDecoder(asd)
+
+sal = enc.encode_frame("R", "MOV", target="BOT1", cc="↺")
+result = dec.decode_frame(sal)
+# result.namespace = "R"
+# result.opcode = "MOV"
+# result.opcode_meaning = "move"
+# result.consequence_class_name = "REVERSIBLE"
+```
+
+## Composition Validation
+
+Eight deterministic rules enforced before any instruction hits the wire:
+
+1. **Hallucination check** -- every opcode must exist in the ASD
+2. **Namespace-as-target** -- `@` must not be followed by `NS:OPCODE`
+3. **R namespace consequence class** -- mandatory except `R:ESTOP`
+4. **I:§ precondition** -- ⚠ and ⊘ require `I:§` in the chain
+5. **Byte check** -- SAL bytes must not exceed NL bytes (exception: R safety chains)
+6. **Slash rejection** -- `/` is not a SAL operator
+7. **Mixed-mode check** -- no natural language embedded in SAL frames
+8. **Regulatory dependency** -- REQUIRES rules from loaded MDR corpora
+
+## Domain Code Resolution
+
+```python
+from osmp.protocol import BlockCompressor
+
+bc = BlockCompressor()
+bc.load("mdr/icd10cm/MDR-ICD10CM-FY2026-blk.dpack")
+result = bc.resolve("J93.0")
+# "Spontaneous tension pneumothorax"
+```
+
+Three corpora bundled: ICD-10-CM (74,719 codes), ISO 20022 (47,835 codes), MITRE ATT&CK (1,661 codes).
+
+## MCP Server
+
+The MCP server is a separate package that wraps this SDK:
+
+```
+pip install osmp-mcp
+osmp-mcp
+```
+
+Nine tools for AI client integration. Connect from Claude Code (`claude mcp add osmp -- osmp-mcp`), Claude Desktop, Cursor, or any MCP-compatible client.
+
+## License
+
+Apache 2.0. Patent pending. Filed March 17, 2026.

osmp-2.0.0/README.md

@@ -0,0 +1,114 @@
+# OSMP Python SDK
+
+Reference implementation of the Octid Semantic Mesh Protocol. Encodes, decodes, and validates agentic AI instructions using SAL (Semantic Assembly Language). 342 opcodes across 26 namespaces. Inference-free decode by table lookup.
+
+## Install
+
+```
+pip install osmp
+```
+
+Zero dependencies beyond Python standard library (optional `zstandard` for D:PACK).
+
+## Tier 1: Two Functions, Zero Setup
+
+```python
+from osmp import encode, decode
+
+sal = encode(["H:HR@NODE1>120", "H:CASREP", "M:EVA@*"])
+# "H:HR@NODE1>120;H:CASREP;M:EVA@*"
+
+text = decode("H:HR@NODE1>120;H:CASREP;M:EVA@*")
+# "heart_rate at NODE1 priority 120; casualty_report; evacuation at broadcast"
+```
+
+Three lines. No instantiation. Module-level singleton, cached on first call.
+
+### Additional Tier 1 Functions
+
+```python
+from osmp import validate, lookup, byte_size
+
+result = validate("R:MOV@BOT1⚠")
+print(result.valid)    # False -- ⚠ requires I:§ precondition
+
+definition = lookup("R:WPT")
+# "waypoint"
+
+print(byte_size("H:HR@NODE1>120"))
+# 15
+```
+
+## Tier 2: Class-Based Interface
+
+For configuration beyond defaults (custom ASD floor, pre-loaded dependency rules, direct ASD access):
+
+```python
+from osmp.core import OSMP
+
+o = OSMP()
+sal = o.encode(["H:HR@NODE1>120", "H:CASREP"])
+text = o.decode(sal)
+result = o.validate(sal)
+definition = o.lookup("H", "HR")
+```
+
+## Tier 3: Full Protocol Access
+
+Direct access to encoder, decoder, ASD, and all protocol internals:
+
+```python
+from osmp.protocol import SALEncoder, SALDecoder, AdaptiveSharedDictionary, validate_composition
+
+asd = AdaptiveSharedDictionary()
+enc = SALEncoder(asd)
+dec = SALDecoder(asd)
+
+sal = enc.encode_frame("R", "MOV", target="BOT1", cc="↺")
+result = dec.decode_frame(sal)
+# result.namespace = "R"
+# result.opcode = "MOV"
+# result.opcode_meaning = "move"
+# result.consequence_class_name = "REVERSIBLE"
+```
+
+## Composition Validation
+
+Eight deterministic rules enforced before any instruction hits the wire:
+
+1. **Hallucination check** -- every opcode must exist in the ASD
+2. **Namespace-as-target** -- `@` must not be followed by `NS:OPCODE`
+3. **R namespace consequence class** -- mandatory except `R:ESTOP`
+4. **I:§ precondition** -- ⚠ and ⊘ require `I:§` in the chain
+5. **Byte check** -- SAL bytes must not exceed NL bytes (exception: R safety chains)
+6. **Slash rejection** -- `/` is not a SAL operator
+7. **Mixed-mode check** -- no natural language embedded in SAL frames
+8. **Regulatory dependency** -- REQUIRES rules from loaded MDR corpora
+
+## Domain Code Resolution
+
+```python
+from osmp.protocol import BlockCompressor
+
+bc = BlockCompressor()
+bc.load("mdr/icd10cm/MDR-ICD10CM-FY2026-blk.dpack")
+result = bc.resolve("J93.0")
+# "Spontaneous tension pneumothorax"
+```
+
+Three corpora bundled: ICD-10-CM (74,719 codes), ISO 20022 (47,835 codes), MITRE ATT&CK (1,661 codes).
+
+## MCP Server
+
+The MCP server is a separate package that wraps this SDK:
+
+```
+pip install osmp-mcp
+osmp-mcp
+```
+
+Nine tools for AI client integration. Connect from Claude Code (`claude mcp add osmp -- osmp-mcp`), Claude Desktop, Cursor, or any MCP-compatible client.
+
+## License
+
+Apache 2.0. Patent pending. Filed March 17, 2026.

osmp-2.0.0/osmp/__init__.py

@@ -0,0 +1,146 @@
+"""
+OSMP — Octid Semantic Mesh Protocol
+Tier 1 API: Two functions. Zero setup.
+
+    from osmp import encode, decode
+
+    sal = encode(["H:HR@NODE1>120", "H:CASREP", "M:EVA@*"])
+    print(sal)    # "H:HR@NODE1>120;H:CASREP;M:EVA@*"
+
+    text = decode("H:HR@NODE1>120;H:CASREP;M:EVA@*")
+    print(text)   # "heart_rate at NODE1 priority 120; casualty_report; evacuation at broadcast"
+
+Patent: OSMP-001-UTIL (pending) — inventor Clay Holberg
+License: Apache 2.0
+"""
+
+from __future__ import annotations
+
+# Lazy-loaded singleton. The protocol module is heavy (~2700 lines).
+# We don't import it until the first call, and we cache the instances.
+_asd = None
+_encoder = None
+_decoder = None
+
+
+def _init():
+    """Initialize singleton ASD, encoder, and decoder on first use."""
+    global _asd, _encoder, _decoder
+    if _asd is not None:
+        return
+
+    # Import from wherever the protocol internals live.
+    # This supports both the current osmp_mcp.osmp layout and
+    # the future osmp.protocol layout.
+    try:
+        from osmp.protocol import AdaptiveSharedDictionary, SALEncoder, SALDecoder
+    except ImportError:
+        try:
+            from osmp_mcp.osmp import AdaptiveSharedDictionary, SALEncoder, SALDecoder
+        except ImportError:
+            # Fallback: same package, different module name
+            from .osmp import AdaptiveSharedDictionary, SALEncoder, SALDecoder
+
+    _asd = AdaptiveSharedDictionary()
+    _encoder = SALEncoder(_asd)
+    _decoder = SALDecoder(_asd)
+
+
+def encode(input_data) -> str:
+    """Encode to SAL.
+
+    Accepts:
+        list[str]  — opcode strings, joined with ; (sequence operator)
+        str        — if it looks like SAL (contains :), validates and returns as-is
+                     if it looks like natural language, returns as NL_PASSTHROUGH
+
+    Returns:
+        SAL string ready for transmission.
+
+    Examples:
+        encode(["H:HR@NODE1>120", "H:CASREP", "M:EVA@*"])
+        → "H:HR@NODE1>120;H:CASREP;M:EVA@*"
+
+        encode("H:HR@NODE1>120;H:CASREP;M:EVA@*")
+        → "H:HR@NODE1>120;H:CASREP;M:EVA@*"  (passthrough)
+    """
+    _init()
+
+    if isinstance(input_data, list):
+        return _encoder.encode_sequence(input_data)
+
+    if isinstance(input_data, str):
+        # If it contains namespace:opcode patterns, treat as pre-formatted SAL
+        if ":" in input_data and any(
+            c in input_data for c in "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        ):
+            # Looks like SAL already — return as-is
+            return input_data
+        # Natural language — return as NL passthrough
+        # (Future: NL-to-SAL conversion when composition engine is available)
+        return input_data
+
+    raise TypeError(
+        f"encode() accepts str or list[str], got {type(input_data).__name__}. "
+        f"Example: encode(['H:HR@NODE1>120', 'H:CASREP', 'M:EVA@*'])"
+    )
+
+
+def decode(sal: str) -> str:
+    """Decode SAL to natural language description.
+
+    Accepts:
+        str — a SAL instruction string (single frame or ;-separated sequence)
+
+    Returns:
+        Human-readable natural language expansion of the SAL instruction,
+        resolved by ASD dictionary lookup. Zero inference.
+
+    Examples:
+        decode("H:HR@NODE1>120;H:CASREP;M:EVA@*")
+        → "H:heart_rate →NODE1>120; H:casualty_report; M:evacuation →*"
+    """
+    _init()
+    frames = [f.strip() for f in sal.split(";") if f.strip()]
+    if len(frames) <= 1:
+        return _decoder.decode_natural_language(sal)
+    return "; ".join(_decoder.decode_natural_language(f) for f in frames)
+
+
+def validate(sal: str, nl: str = "", dependency_rules=None):
+    """Validate a composed SAL instruction against all eight rules.
+
+    Returns a CompositionResult with .valid (bool) and .issues (list).
+    """
+    _init()
+    try:
+        from osmp.protocol import validate_composition
+    except ImportError:
+        try:
+            from osmp_mcp.osmp import validate_composition
+        except ImportError:
+            from .osmp import validate_composition
+
+    return validate_composition(sal, nl, _asd, dependency_rules=dependency_rules)
+
+
+def lookup(namespace_opcode: str) -> str | None:
+    """Look up an opcode definition in the ASD.
+
+    Accepts: "H:HR" or namespace="H", opcode="HR"
+    Returns: definition string or None if not found.
+    """
+    _init()
+    if ":" in namespace_opcode:
+        parts = namespace_opcode.split(":", 1)
+        return _asd.lookup(parts[0], parts[1])
+    return None
+
+
+def byte_size(sal: str) -> int:
+    """Return UTF-8 byte count of a SAL string."""
+    return len(sal.encode("utf-8"))
+
+
+# Version
+__version__ = "2.0.0"

osmp-2.0.0/osmp/core.py

@@ -0,0 +1,124 @@
+"""
+OSMP -- Octid Semantic Mesh Protocol
+Tier 2 API: Class-based interface for advanced use.
+
+    from osmp.core import OSMP
+
+    o = OSMP()
+    sal = o.encode(["H:HR@NODE1>120", "H:CASREP", "M:EVA@*"])
+    text = o.decode(sal)
+    result = o.validate(sal)
+
+For the two-function API, use Tier 1 instead:
+
+    from osmp import encode, decode
+
+Patent: OSMP-001-UTIL (pending) -- inventor Clay Holberg
+License: Apache 2.0
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .protocol import (
+        AdaptiveSharedDictionary,
+        CompositionResult,
+        DependencyRule,
+        SALDecoder,
+        SALEncoder,
+    )
+
+
+class OSMP:
+    """Full-featured OSMP codec with configurable ASD and dependency rules.
+
+    For zero-setup usage, prefer the module-level functions in ``osmp``.
+    This class exposes configuration points (custom ASD floor version,
+    pre-loaded dependency rules, direct ASD access) that the Tier 1
+    functions intentionally hide.
+    """
+
+    def __init__(
+        self,
+        floor_version: str | None = None,
+        dependency_rules: list[DependencyRule] | None = None,
+    ):
+        from .protocol import AdaptiveSharedDictionary, SALDecoder, SALEncoder
+
+        if floor_version is not None:
+            self._asd: AdaptiveSharedDictionary = AdaptiveSharedDictionary(floor_version)
+        else:
+            self._asd = AdaptiveSharedDictionary()
+
+        self._encoder: SALEncoder = SALEncoder(self._asd)
+        self._decoder: SALDecoder = SALDecoder(self._asd)
+        self._dependency_rules: list[DependencyRule] | None = dependency_rules
+
+    # -- Encoding --------------------------------------------------------
+
+    def encode(self, instructions: list[str]) -> str:
+        """Encode a list of opcode strings into a SAL instruction chain."""
+        return self._encoder.encode_sequence(instructions)
+
+    def encode_frame(
+        self,
+        namespace: str,
+        opcode: str,
+        target: str | None = None,
+        query_slot: str | None = None,
+        consequence_class: str | None = None,
+    ) -> str:
+        """Encode a single SAL frame from structured fields."""
+        return self._encoder.encode_frame(
+            namespace, opcode, target, query_slot,
+            consequence_class=consequence_class,
+        )
+
+    # -- Decoding --------------------------------------------------------
+
+    def decode(self, sal: str) -> str:
+        """Decode a SAL string to natural language. Handles sequences."""
+        frames = [f.strip() for f in sal.split(";") if f.strip()]
+        if len(frames) <= 1:
+            return self._decoder.decode_natural_language(sal)
+        return "; ".join(self._decoder.decode_natural_language(f) for f in frames)
+
+    def decode_frame(self, sal: str):
+        """Decode a single SAL frame to a DecodedInstruction."""
+        return self._decoder.decode_frame(sal)
+
+    # -- Validation ------------------------------------------------------
+
+    def validate(self, sal: str, nl: str = ""):
+        """Validate a SAL instruction against all eight composition rules."""
+        from .protocol import validate_composition
+        return validate_composition(
+            sal, nl, self._asd,
+            dependency_rules=self._dependency_rules,
+        )
+
+    # -- Lookup ----------------------------------------------------------
+
+    def lookup(self, namespace: str, opcode: str) -> str | None:
+        """Look up an opcode definition in the ASD."""
+        return self._asd.lookup(namespace, opcode)
+
+    # -- Direct access ---------------------------------------------------
+
+    @property
+    def asd(self):
+        """Direct access to the AdaptiveSharedDictionary instance."""
+        return self._asd
+
+    @property
+    def encoder(self):
+        """Direct access to the SALEncoder instance."""
+        return self._encoder
+
+    @property
+    def decoder(self):
+        """Direct access to the SALDecoder instance."""
+        return self._decoder