mudra-interact 0.2.0__py3-none-any.whl

mudra_interact_core/catalog/mudra_catalog.json

@@ -0,0 +1,65 @@
+{
+  "catalog_version": "2.0.0",
+  "entries": [
+    {
+      "gesture_id": "contact_thumb_index",
+      "display_name": "Thumb-index contact",
+      "contact_pattern": "I",
+      "confidence": 0.72,
+      "limitations": [
+        "A geometric contact cue does not establish full finger posture, handedness or cultural meaning.",
+        "Palm orientation and participant context are outside the core rule."
+      ],
+      "provenance": {
+        "status": "specification_source",
+        "reference": "MUDRA_INTERACT_CORE_SPEC.md section 4 contact rule table",
+        "content_license": "Apache-2.0"
+      }
+    },
+    {
+      "gesture_id": "contact_thumb_middle",
+      "display_name": "Thumb-middle contact",
+      "contact_pattern": "M",
+      "confidence": 0.70,
+      "limitations": [
+        "A geometric contact cue does not establish full finger posture, handedness or cultural meaning.",
+        "Participant confirmation is required before any sharing or action."
+      ],
+      "provenance": {
+        "status": "specification_source",
+        "reference": "MUDRA_INTERACT_CORE_SPEC.md section 4 contact rule table",
+        "content_license": "Apache-2.0"
+      }
+    },
+    {
+      "gesture_id": "contact_thumb_ring",
+      "display_name": "Thumb-ring contact",
+      "contact_pattern": "R",
+      "confidence": 0.70,
+      "limitations": [
+        "A geometric contact cue does not establish full finger posture, handedness or cultural meaning.",
+        "Participant confirmation is required before any sharing or action."
+      ],
+      "provenance": {
+        "status": "specification_source",
+        "reference": "MUDRA_INTERACT_CORE_SPEC.md section 4 contact rule table",
+        "content_license": "Apache-2.0"
+      }
+    },
+    {
+      "gesture_id": "contact_thumb_middle_ring",
+      "display_name": "Thumb-middle-ring contact",
+      "contact_pattern": "M+R",
+      "confidence": 0.78,
+      "limitations": [
+        "A geometric contact cue does not establish full finger posture, handedness or cultural meaning.",
+        "The rule is neutral and does not infer a named tradition or efficacy claim."
+      ],
+      "provenance": {
+        "status": "specification_source",
+        "reference": "MUDRA_INTERACT_CORE_SPEC.md section 4 contact rule table",
+        "content_license": "Apache-2.0"
+      }
+    }
+  ]
+}

mudra_interact_core/catalog.py

@@ -0,0 +1,124 @@
+"""Strict neutral v2 catalogue loader with detached lookup results."""
+
+from __future__ import annotations
+
+import copy
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from .errors import MudraValidationError
+from .validation import CATALOG_VERSION, MAX_STRING_SCALARS, parse_json_bytes, require_finite_float
+
+
+CATALOG_IDS = frozenset(
+    {"contact_thumb_index", "contact_thumb_middle", "contact_thumb_ring", "contact_thumb_middle_ring"}
+)
+CONTACT_PATTERNS = frozenset({"I", "M", "R", "M+R"})
+ENTRY_FIELDS = {"gesture_id", "display_name", "contact_pattern", "confidence", "limitations", "provenance"}
+PROVENANCE_FIELDS = {"status", "reference", "content_license"}
+PROVENANCE_STATUSES = frozenset({"specification_source", "unverified_historical_alias"})
+
+
+def _invalid() -> None:
+    raise MudraValidationError("catalog_invalid")
+
+
+def validate_catalog_payload(payload: Any) -> dict[str, Any]:
+    if type(payload) is not dict or set(payload) != {"catalog_version", "entries"}:
+        _invalid()
+    if payload["catalog_version"] != CATALOG_VERSION or type(payload["entries"]) is not list:
+        _invalid()
+    entries = payload["entries"]
+    if len(entries) != 4:
+        _invalid()
+    seen: set[str] = set()
+    normalized: list[dict[str, Any]] = []
+    for entry in entries:
+        if type(entry) is not dict or set(entry) != ENTRY_FIELDS:
+            _invalid()
+        gesture_id = entry["gesture_id"]
+        display_name = entry["display_name"]
+        pattern = entry["contact_pattern"]
+        if type(gesture_id) is not str or gesture_id not in CATALOG_IDS or gesture_id in seen:
+            _invalid()
+        if type(display_name) is not str or not (1 <= len(display_name) <= 80):
+            _invalid()
+        if type(pattern) is not str or pattern not in CONTACT_PATTERNS:
+            _invalid()
+        try:
+            confidence = require_finite_float(entry["confidence"], minimum=0.0, maximum=1.0, code="catalog_invalid")
+        except MudraValidationError:
+            _invalid()
+        limitations = entry["limitations"]
+        if type(limitations) is not list or not (1 <= len(limitations) <= 8):
+            _invalid()
+        if any(type(item) is not str or not (1 <= len(item) <= 240) for item in limitations):
+            _invalid()
+        provenance = entry["provenance"]
+        if type(provenance) is not dict or set(provenance) != PROVENANCE_FIELDS:
+            _invalid()
+        if type(provenance["status"]) is not str or provenance["status"] not in PROVENANCE_STATUSES:
+            _invalid()
+        if type(provenance["reference"]) is not str or not (1 <= len(provenance["reference"]) <= 240):
+            _invalid()
+        if type(provenance["content_license"]) is not str or not (1 <= len(provenance["content_license"]) <= 80):
+            _invalid()
+        seen.add(gesture_id)
+        normalized.append(
+            {
+                "gesture_id": gesture_id,
+                "display_name": display_name,
+                "contact_pattern": pattern,
+                "confidence": confidence,
+                "limitations": list(limitations),
+                "provenance": dict(provenance),
+            }
+        )
+    if seen != CATALOG_IDS:
+        _invalid()
+    return {"catalog_version": CATALOG_VERSION, "entries": normalized}
+
+
+def load_catalog(path: str | Path | None = None) -> dict[str, dict[str, Any]]:
+    try:
+        if path is None:
+            resource = files("mudra_interact_core").joinpath("catalog/mudra_catalog.json")
+            data = resource.read_bytes()
+        else:
+            candidate = Path(path)
+            if candidate.is_symlink() or not candidate.is_file():
+                _invalid()
+            data = candidate.read_bytes()
+        payload = parse_json_bytes(data, limit=65_536)
+        validated = validate_catalog_payload(payload)
+    except MudraValidationError:
+        raise
+    except (OSError, UnicodeError):
+        _invalid()
+    return {entry["gesture_id"]: copy.deepcopy(entry) for entry in validated["entries"]}
+
+
+def lookup(gesture_id: str) -> dict[str, Any] | None:
+    if type(gesture_id) is not str or len(gesture_id) > MAX_STRING_SCALARS:
+        _invalid()
+    entry = load_catalog().get(gesture_id)
+    return copy.deepcopy(entry) if entry is not None else None
+
+
+def validate_label_pack(payload: Any) -> dict[str, Any]:
+    """Validate a review record without implying that a reviewer approved it."""
+
+    if type(payload) is not dict or set(payload) != {"pack_version", "entries"} or type(payload["entries"]) is not list:
+        _invalid()
+    for entry in payload["entries"]:
+        if type(entry) is not dict or set(entry) != {
+            "gesture_id", "label", "reviewer", "evidence_reference", "rights", "language_scope", "prohibited_claims", "withdrawal"
+        }:
+            _invalid()
+        if any(type(entry[key]) is not str or not entry[key] for key in entry):
+            _invalid()
+    return copy.deepcopy(payload)
+
+
+__all__ = ["CATALOG_IDS", "load_catalog", "lookup", "validate_catalog_payload", "validate_label_pack"]

mudra_interact_core/cli.py

@@ -0,0 +1,371 @@
+"""Fail-closed local command line interface for Mudra Interact Core.
+
+The CLI is deliberately a thin boundary around the validated public API. It
+never discovers files, accepts stdin or URLs, writes input data, or treats a
+JSON value as consent. Successful output is built before one write so a
+non-zero exit is always an unsuccessful operation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+from datetime import UTC, datetime
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any, Sequence
+
+from .errors import MudraValidationError
+from .frame import Frame, parse_batch, parse_frame
+from .protocol import InteractionParty, RecognitionState, parse_event
+from .session import RecognitionSession
+from .validation import (
+    MAX_BATCH_BYTES,
+    MAX_EVENT_BYTES,
+    MAX_FRAME_BYTES,
+    SCHEMA_VERSION,
+    fail,
+    parse_json_bytes,
+    require_canonical_uuid,
+)
+
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_DENIED = 3
+EXIT_IO = 4
+EXIT_INTERRUPTED = 130
+_OUTPUT_LIMIT = 512
+_VERSION_FALLBACK = "0.2.0"
+_REASON_PRECEDENCE = (
+    "unsupported_pattern",
+    "ambiguous_contacts",
+    "low_confidence",
+    "gesture_changed",
+    "frame_gap",
+    "hold_incomplete",
+    "insufficient_frames",
+)
+
+
+class _UsageError(Exception):
+    """An argparse error whose user input must not be echoed."""
+
+
+class _OutputError(Exception):
+    """The selected output stream failed, including a partial write."""
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, _message: str) -> None:
+        raise _UsageError
+
+
+def _package_version() -> str:
+    try:
+        return version("mudra-interact")
+    except PackageNotFoundError:
+        return _VERSION_FALLBACK
+
+
+def _build_parser() -> _ArgumentParser:
+    parser = _ArgumentParser(
+        prog="mudra-interact",
+        description="Run offline v2 landmark recognition and validate image-free events.",
+        add_help=False,
+        allow_abbrev=False,
+    )
+    parser.add_argument("command", nargs="?", choices=("recognize", "validate-event"))
+    parser.add_argument("--help", action="store_true", help="show this help and exit")
+    parser.add_argument("--version", action="store_true", help="show the installed package version and exit")
+    parser.add_argument("--input", dest="input_path")
+    parser.add_argument("--stabilize", action="store_true", help="process a bounded frame batch through one session")
+    parser.add_argument("--emit-event", action="store_true", help="emit one event after explicit consent and confirmation")
+    parser.add_argument("--consent", action="store_true", help="explicitly attest sharing consent for this selected batch")
+    parser.add_argument("--confirm", action="store_true", help="explicitly attest participant confirmation for this selected batch")
+    parser.add_argument("--sender", default=None, help="event sender: human or agent")
+    parser.add_argument("--recipient", default=None, help="event recipient: human or agent")
+    parser.add_argument("--conversation-id", default=None)
+    parser.add_argument("--project-id", default=None)
+    return parser
+
+
+def _write_stream(stream: Any, data: bytes) -> None:
+    """Write all bytes exactly once; never retry a failed or partial write."""
+
+    target = getattr(stream, "buffer", stream)
+    try:
+        written = target.write(data)
+    except TypeError:
+        # Test harnesses may provide a text-only stream. Real CLI streams are
+        # binary and therefore never take this branch.
+        try:
+            written = target.write(data.decode("utf-8"))
+        except (BrokenPipeError, OSError, UnicodeError) as exc:
+            raise _OutputError from exc
+    except (BrokenPipeError, OSError, UnicodeError) as exc:
+        raise _OutputError from exc
+    if written is not None and written != len(data):
+        raise _OutputError
+    flush = getattr(target, "flush", None)
+    if callable(flush):
+        try:
+            flush()
+        except (BrokenPipeError, OSError) as exc:
+            raise _OutputError from exc
+
+
+def _emit_error(code: str) -> None:
+    payload = json.dumps({"error": {"code": code}}, separators=(",", ":"), ensure_ascii=True).encode("ascii") + b"\n"
+    if len(payload) > _OUTPUT_LIMIT:
+        return
+    try:
+        _write_stream(sys.stderr, payload)
+    except _OutputError:
+        # A broken diagnostic pipe must not trigger a traceback or a retry.
+        return
+
+
+def _emit_success(payload: bytes) -> int:
+    try:
+        _write_stream(sys.stdout, payload + b"\n")
+    except _OutputError:
+        return EXIT_IO
+    return EXIT_OK
+
+
+def _is_explicit_remote_or_special(text: str) -> str | None:
+    if not text or text == "-":
+        return "input_unavailable"
+    lowered = text.lower()
+    if "://" in lowered or lowered.startswith(("data:", "stdin:", "\\\\", "//")):
+        return "unsupported_platform"
+    if "\x00" in text:
+        return "input_unavailable"
+    return None
+
+
+def _read_local_file(raw_path: str | None, *, limit: int) -> bytes:
+    if type(raw_path) is not str:
+        fail("input_unavailable")
+    special = _is_explicit_remote_or_special(raw_path)
+    if special is not None:
+        fail(special)
+    path = Path(raw_path)
+    try:
+        initial = os.lstat(path)
+    except (OSError, ValueError):
+        fail("input_unavailable")
+    if stat.S_ISLNK(initial.st_mode) or not stat.S_ISREG(initial.st_mode):
+        fail("input_unavailable")
+    # Windows reparse points include symlinks and remote/device forms. A
+    # regular-file mode bit alone is not enough to make those safe.
+    if getattr(initial, "st_file_attributes", 0) & 0x400:
+        fail("unsupported_platform")
+
+    flags = os.O_RDONLY
+    flags |= getattr(os, "O_BINARY", 0)
+    flags |= getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except (OSError, ValueError):
+        fail("input_unavailable")
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode):
+            fail("input_unavailable")
+        if getattr(opened, "st_file_attributes", 0) & 0x400:
+            fail("unsupported_platform")
+        # On POSIX, O_NOFOLLOW plus this identity check closes the ordinary
+        # symlink/replacement race. Windows receives the opened-handle type
+        # check and retains its documented caller-owned mount policy.
+        if hasattr(initial, "st_ino") and hasattr(opened, "st_ino"):
+            if initial.st_ino != opened.st_ino or initial.st_dev != opened.st_dev:
+                fail("input_unavailable")
+        if opened.st_size > limit:
+            fail("input_too_large")
+        chunks: list[bytes] = []
+        total = 0
+        while True:
+            chunk = os.read(descriptor, min(64 * 1024, limit + 1 - total))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+            if total > limit:
+                fail("input_too_large")
+        return b"".join(chunks)
+    except MudraValidationError:
+        raise
+    except (OSError, ValueError):
+        fail("input_unavailable")
+    finally:
+        try:
+            os.close(descriptor)
+        except OSError:
+            pass
+
+
+def _parse_frames(data: bytes, *, stabilize: bool) -> tuple[Frame, ...]:
+    if not stabilize:
+        return (parse_frame(data),)
+    # A one-frame --stabilize input proves that one observation cannot become
+    # stable. A batch is fully parsed before any session state advances, so a
+    # malformed late frame has no partial-success path.
+    document = parse_json_bytes(data, limit=MAX_BATCH_BYTES)
+    if isinstance(document, dict) and "frames" not in document:
+        if len(data) > MAX_FRAME_BYTES:
+            fail("input_too_large")
+        return (parse_frame(document),)
+    return parse_batch(document).frames
+
+
+def _party(value: str | None, default: InteractionParty) -> InteractionParty:
+    selected = default.value if value is None else value
+    if type(selected) is not str:
+        fail("invalid_shape")
+    try:
+        return InteractionParty(selected)
+    except (ValueError, TypeError):
+        fail("invalid_shape")
+
+
+def _reason_code(state: RecognitionState, uncertainties: Sequence[str]) -> str | None:
+    if state is RecognitionState.STABLE:
+        return None
+    present = set(uncertainties)
+    for code in _REASON_PRECEDENCE:
+        if code in present:
+            return code
+    if state is RecognitionState.CANDIDATE:
+        return "insufficient_frames"
+    return "unsupported_pattern"
+
+
+def _recognition_report(session: RecognitionSession) -> bytes:
+    recognition = session.current
+    result = {
+        "schema_version": SCHEMA_VERSION,
+        "recognition": recognition.payload(),
+        "reason_code": _reason_code(recognition.state, recognition.uncertainties),
+    }
+    return json.dumps(result, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def _run_recognize(args: argparse.Namespace) -> bytes:
+    if args.emit_event and not args.stabilize:
+        raise _UsageError
+    if not args.emit_event and (args.consent or args.confirm):
+        raise _UsageError
+    data = _read_local_file(args.input_path, limit=MAX_BATCH_BYTES if args.stabilize else MAX_FRAME_BYTES)
+    frames = _parse_frames(data, stabilize=args.stabilize)
+
+    # Parse and validate all event-only options before checking either consent
+    # flag, matching the contract's precedence rule.
+    sender = _party(args.sender, InteractionParty.HUMAN)
+    recipient = _party(args.recipient, InteractionParty.AGENT)
+    conversation_id = require_canonical_uuid(args.conversation_id, nullable=True)
+    project_id = require_canonical_uuid(args.project_id, nullable=True)
+    session = RecognitionSession(
+        frames[0].stream_id,
+        conversation_id=conversation_id,
+        project_id=project_id,
+    )
+    for frame in frames:
+        session.observe(frame)
+    final_time = frames[-1].monotonic_ms
+
+    if args.emit_event:
+        if args.consent is not True:
+            fail("consent_required")
+        if args.confirm is not True:
+            fail("confirmation_required")
+        session.confirm(True, True, final_time)
+        event = session.emit_event(
+            sender=sender,
+            recipient=recipient,
+            now_ms=final_time,
+            occurred_at=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
+        )
+        return event.to_bytes()
+    return _recognition_report(session)
+
+
+def _run_validate_event(args: argparse.Namespace) -> bytes:
+    data = _read_local_file(args.input_path, limit=MAX_EVENT_BYTES)
+    parse_event(data)
+    return b'{"schema_version":"2.0.0","valid":true}'
+
+
+def _validate_namespace(args: argparse.Namespace) -> None:
+    if args.command is None:
+        args.command = "recognize"
+    if args.command == "validate-event":
+        if args.input_path is None or args.stabilize or args.emit_event or args.consent or args.confirm:
+            raise _UsageError
+        if any(value is not None for value in (args.sender, args.recipient, args.conversation_id, args.project_id)):
+            raise _UsageError
+    elif args.input_path is None:
+        raise _UsageError
+
+
+def _help_bytes(parser: argparse.ArgumentParser) -> bytes:
+    return parser.format_help().encode("utf-8")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(list(argv) if argv is not None else None)
+        if args.help:
+            return _emit_success(_help_bytes(parser).rstrip(b"\n"))
+        if args.version:
+            meaningful = [
+                args.command,
+                args.input_path,
+                args.stabilize,
+                args.emit_event,
+                args.consent,
+                args.confirm,
+                args.sender,
+                args.recipient,
+                args.conversation_id,
+                args.project_id,
+            ]
+            if any(value not in (None, False) for value in meaningful):
+                raise _UsageError
+            return _emit_success(_package_version().encode("ascii"))
+        _validate_namespace(args)
+        output = _run_validate_event(args) if args.command == "validate-event" else _run_recognize(args)
+        return _emit_success(output)
+    except _UsageError:
+        _emit_error("invalid_shape")
+        return EXIT_USAGE
+    except MudraValidationError as error:
+        _emit_error(error.code)
+        if error.code in {"consent_required", "confirmation_required", "stale_confirmation"}:
+            return EXIT_DENIED
+        if error.code in {"input_unavailable", "unsupported_platform", "internal_error"}:
+            return EXIT_IO
+        return EXIT_USAGE
+    except KeyboardInterrupt:
+        _emit_error("internal_error")
+        return EXIT_INTERRUPTED
+    except _OutputError:
+        return EXIT_IO
+    except Exception:
+        # No implementation detail, path, raw input or traceback may cross the
+        # command boundary.
+        _emit_error("internal_error")
+        return EXIT_IO
+
+
+__all__ = ["main"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mudra_interact_core/coordinates.py

@@ -0,0 +1,43 @@
+"""Declared coordinate-space conversion for the geometric recognizer."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .errors import MudraValidationError
+from .frame import COORDINATE_SPACES, Frame, Landmark
+from .validation import MAX_IMAGE_DIMENSION, fail, require_coordinate
+
+
+def convert_landmarks(
+    landmarks: Sequence[Landmark],
+    *,
+    coordinate_space: str,
+    image_width: int | None = None,
+    image_height: int | None = None,
+) -> tuple[Landmark, ...]:
+    """Convert declared image-normalized y units into the Cartesian rule space."""
+
+    if type(landmarks) not in (list, tuple) or len(landmarks) != 21:
+        fail("invalid_shape")
+    if type(coordinate_space) is not str or coordinate_space not in COORDINATE_SPACES:
+        fail("invalid_configuration")
+    if coordinate_space == "cartesian_relative_v1":
+        if image_width is not None or image_height is not None:
+            fail("invalid_configuration")
+        return tuple(Landmark(point.x, point.y, point.z) for point in landmarks)
+    if type(image_width) is not int or type(image_height) is not int:
+        fail("invalid_configuration")
+    if not (1 <= image_width <= MAX_IMAGE_DIMENSION and 1 <= image_height <= MAX_IMAGE_DIMENSION):
+        fail("invalid_configuration")
+    factor = image_height / image_width
+    return tuple(Landmark(point.x, point.y * factor, point.z) for point in landmarks)
+
+
+def to_cartesian(frame: Frame) -> tuple[Landmark, ...]:
+    if not isinstance(frame, Frame):
+        fail("invalid_shape")
+    return frame.converted_landmarks()
+
+
+__all__ = ["convert_landmarks", "to_cartesian"]

mudra_interact_core/errors.py

@@ -0,0 +1,49 @@
+"""Safe public errors for Mudra Interact Core.
+
+The error code is the complete public message.  Input values, paths and
+exception text are deliberately never included.
+"""
+
+from __future__ import annotations
+
+
+SAFE_ERROR_CODES = frozenset(
+    {
+        "invalid_json",
+        "input_too_large",
+        "invalid_shape",
+        "invalid_number",
+        "invalid_geometry",
+        "unsupported_version",
+        "invalid_configuration",
+        "invalid_sequence",
+        "invalid_state",
+        "consent_required",
+        "confirmation_required",
+        "stale_confirmation",
+        "scope_mismatch",
+        "catalog_invalid",
+        "unsupported_platform",
+        "input_unavailable",
+        "internal_error",
+    }
+)
+
+
+class MudraValidationError(ValueError):
+    """A deterministic, non-sensitive validation failure."""
+
+    __slots__ = ("code",)
+
+    def __init__(self, code: str) -> None:
+        if code not in SAFE_ERROR_CODES:
+            code = "internal_error"
+        self.code = code
+        super().__init__(code)
+
+    def __str__(self) -> str:
+        return self.code
+
+    def __repr__(self) -> str:
+        return f"MudraValidationError({self.code!r})"
+