nex-protocol 0.1.0a1__py3-none-any.whl

nex/__init__.py

@@ -0,0 +1,2 @@
+"""Nex: deterministic language and protocol for agent understanding."""
+__version__ = "0.1.0a1"

nex/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

nex/_data.py

@@ -0,0 +1,27 @@
+"""Loading of packaged JSON data (schemas and registries)."""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+_FALLBACK_ROOT = Path(__file__).resolve().parents[2] / "schemas"
+
+
+def _read(relative: str) -> str:
+    parts = relative.split("/")
+    try:
+        node = resources.files("nex.schemas")
+        for part in parts:
+            node = node.joinpath(part)
+        return node.read_text(encoding="utf-8")
+    except (ModuleNotFoundError, FileNotFoundError, OSError):
+        return (_FALLBACK_ROOT.joinpath(*parts)).read_text(encoding="utf-8")
+
+
+@lru_cache(maxsize=None)
+def load_json(relative: str) -> Any:
+    """Load and cache a JSON document relative to the schemas directory."""
+    return json.loads(_read(relative))

nex/agent.py

@@ -0,0 +1,66 @@
+"""Nex agent: builds, signs and exchanges messages through a runtime."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .canonical import canonical_text
+from .errors import NexError
+from .models import PROTOCOL_VERSION
+from .protocol import build_message
+from .runtime import NexRuntime
+
+Transport = Callable[[str], "str | dict[str, Any] | None"]
+
+
+class NexAgent:
+    """Thin client around a :class:`NexRuntime`.
+
+    ``transport`` receives a canonical Nex-J string and returns the peer's response
+    (a message dict/string) or None. :meth:`connect_local` wires two agents in-process.
+    """
+
+    def __init__(self, agent_id: str, **runtime_kwargs: Any) -> None:
+        self.runtime = NexRuntime(agent_id, **runtime_kwargs)
+        self.agent_id = agent_id
+        self.transport: Transport | None = None
+
+    def connect_local(self, peer: "NexAgent") -> None:
+        self.transport = lambda text: peer.runtime.process(text)
+
+    def build(self, receiver: str, command: str, payload: dict[str, Any], *, session_id: str | None = None,
+              correlation_id: str | None = None, reply_to: str | None = None) -> dict[str, Any]:
+        msg = build_message(sender=self.agent_id, receiver=receiver, command=command, payload=payload,
+                            now=self.runtime.clock(), session_id=session_id, correlation_id=correlation_id,
+                            reply_to=reply_to)
+        return self.runtime.sign(msg)
+
+    def send(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        """Record, transmit and feed the response back through the local runtime."""
+        if self.transport is None:
+            raise RuntimeError("no transport configured")
+        self.runtime.record_outbound(message)
+        response = self.transport(canonical_text(message))
+        if response is None:
+            return None
+        return self.runtime.process(response) or (response if isinstance(response, dict) else None)
+
+    def handshake(self, receiver: str, *, intent: str = "COORDINATE",
+                  algorithms: tuple[str, ...] | None = None) -> str:
+        """Perform the HANDSHAKE and return the established session id."""
+        algs = list(algorithms or (("ED25519",) if self.runtime.key_id else ("NONE",)))
+        payload = {"identity": self.agent_id, "version": PROTOCOL_VERSION,
+                   "capabilities": ["ERROR", "HANDSHAKE", "PLAN", "ACT", "REPORT", "REQUEST", "SYNC", "VERIFY"],
+                   "ontology_modules": list(self.runtime.ontology_modules), "security_algorithms": algs,
+                   "intent": intent}
+        resp = self.send(self.build(receiver, "HANDSHAKE", payload))
+        if resp is None:
+            raise NexError("E705", {"reason": "no handshake response"})
+        body = resp["body"]
+        if body["command"] == "ERROR":
+            raise NexError(body["payload"]["code"], body["payload"].get("details"))
+        if not body["payload"]["accepted"]:
+            raise NexError("E705", {"reason": body["payload"].get("reason")})
+        return body["payload"]["session_id"]
+
+    def request(self, receiver: str, session_id: str, goal: str, **extra: Any) -> dict[str, Any] | None:
+        return self.send(self.build(receiver, "REQUEST", {"goal": goal, **extra}, session_id=session_id))

nex/canonical.py

@@ -0,0 +1,131 @@
+"""Canonical JSON serialization used for hashing and signing (NEP-0003 §6)."""
+from __future__ import annotations
+
+import json
+import math
+import re
+import unicodedata
+from typing import Any
+
+from .errors import NexError
+
+MAX_DEPTH = 64
+_EXP_PAD = re.compile(r"e([+-])0+(\d)")  # 1e-07 -> 1e-7 (shortest form, as in ECMAScript)
+MAX_MESSAGE_CHARS = 1_048_576  # DoS limit on inbound message text
+_nfc = unicodedata.normalize
+_quote = json.encoder.encode_basestring  # C-accelerated, ensure_ascii=False
+
+
+def _dup_hook(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for k, v in pairs:
+        if k in out:
+            raise NexError("E103", {"field": k})
+        out[k] = v
+    return out
+
+
+def _reject_constant(name: str) -> Any:
+    raise NexError("E001", {"reason": f"non-finite number {name} is not allowed"})
+
+
+def loads_strict(text: str | bytes) -> Any:
+    """Parse JSON rejecting duplicate keys, NaN and Infinity."""
+    if isinstance(text, (bytes, bytearray)):
+        try:
+            text = bytes(text).decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise NexError("E001", {"reason": "invalid UTF-8"}) from exc
+    if len(text) > MAX_MESSAGE_CHARS:
+        raise NexError("E104", {"reason": "message too large", "max_chars": MAX_MESSAGE_CHARS})
+    if not text.strip():
+        raise NexError("E005")
+    try:
+        return json.loads(text, object_pairs_hook=_dup_hook, parse_constant=_reject_constant)
+    except NexError:
+        raise
+    except RecursionError as exc:
+        raise NexError("E104", {"reason": "nesting too deep"}) from exc
+    except ValueError as exc:
+        raise NexError("E001", {"reason": str(exc)[:200]}) from exc
+
+
+def _number(value: float) -> str:
+    if not math.isfinite(value):
+        raise NexError("E904", {"reason": "NaN and infinity are prohibited"})
+    if value == 0:
+        return "0"
+    if value.is_integer() and abs(value) < 1e21:
+        return str(int(value))
+    return _EXP_PAD.sub(r"e\1\2", repr(value))
+
+
+def _emit(obj: Any, out: list[str], depth: int) -> None:
+    if depth > MAX_DEPTH:
+        raise NexError("E104", {"reason": "nesting too deep"})
+    if obj is None:
+        out.append("null")
+    elif obj is True:
+        out.append("true")
+    elif obj is False:
+        out.append("false")
+    elif isinstance(obj, str):
+        out.append(_quote(obj if obj.isascii() else _nfc("NFC", obj)))
+    elif isinstance(obj, int):
+        out.append(str(obj))
+    elif isinstance(obj, float):
+        out.append(_number(obj))
+    elif isinstance(obj, (list, tuple)):
+        out.append("[")
+        first = True
+        for item in obj:
+            if not first:
+                out.append(",")
+            first = False
+            _emit(item, out, depth + 1)
+        out.append("]")
+    elif isinstance(obj, dict):
+        normalized: dict[str, Any] = {}
+        for k, v in obj.items():
+            if not isinstance(k, str):
+                raise NexError("E904", {"reason": "object keys must be strings"})
+            nk = k if k.isascii() else _nfc("NFC", k)
+            if nk in normalized:
+                raise NexError("E103", {"field": nk})
+            normalized[nk] = v
+        out.append("{")
+        first = True
+        for k in sorted(normalized):
+            if not first:
+                out.append(",")
+            first = False
+            out.append(_quote(k))
+            out.append(":")
+            _emit(normalized[k], out, depth + 1)
+        out.append("}")
+    else:
+        raise NexError("E904", {"reason": f"unsupported type {type(obj).__name__}"})
+
+
+def canonicalize(obj: Any) -> bytes:
+    """Return canonical UTF-8 JSON bytes for ``obj``."""
+    out: list[str] = []
+    _emit(obj, out, 0)
+    try:
+        return "".join(out).encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise NexError("E904", {"reason": "string is not valid Unicode"}) from exc
+
+
+def canonical_text(obj: Any) -> str:
+    return canonicalize(obj).decode("utf-8")
+
+
+def signable_bytes(message: dict[str, Any]) -> bytes:
+    """Bytes covered by a signature: header, body, signature.algorithm and key_id."""
+    sig = message["signature"]
+    return canonicalize({
+        "header": message["header"],
+        "body": message["body"],
+        "signature": {"algorithm": sig["algorithm"], "key_id": sig["key_id"]},
+    })

nex/cli.py

@@ -0,0 +1,88 @@
+"""Command line interface: ``nex`` / ``python -m nex``."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from . import __version__
+from .canonical import canonical_text
+from .errors import NexError, entry
+from .glyphs import geometry_json, render_png, render_svg, scene_json
+from .parser import parse_nex_t, parse_nexj
+from .validator import validate_message
+
+
+def _read(path: str) -> str:
+    return sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
+
+
+def _fail(err: NexError) -> int:
+    print(json.dumps(err.payload(), sort_keys=True), file=sys.stderr)
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="nex", description="Nex Alpha reference tools")
+    p.add_argument("--version", action="version", version=f"nex {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    v = sub.add_parser("validate", help="validate a Nex-J message file (or - for stdin)")
+    v.add_argument("file")
+    v.add_argument("--no-expiry", action="store_true", help="skip the expiry check")
+    pa = sub.add_parser("parse", help="parse Nex-T and print canonical Nex-J payload")
+    pa.add_argument("file")
+    c = sub.add_parser("canonical", help="print canonical JSON of a Nex-J file")
+    c.add_argument("file")
+    g = sub.add_parser("glyph", help="generate a Nex-G glyph")
+    g.add_argument("text")
+    g.add_argument("--format", choices=("json", "svg", "png", "scene"), default="json")
+    g.add_argument("-o", "--output", help="output file (required for png)")
+    e = sub.add_parser("error", help="describe an error code")
+    e.add_argument("code")
+    sub.add_parser("demo", help="run the two-agent demonstration")
+    a = p.parse_args(argv)
+
+    try:
+        if a.cmd == "validate":
+            validate_message(parse_nexj(_read(a.file)), check_expiry=not a.no_expiry)
+            print("OK")
+        elif a.cmd == "parse":
+            print(canonical_text(parse_nex_t(_read(a.file))))
+        elif a.cmd == "canonical":
+            print(canonical_text(parse_nexj(_read(a.file))))
+        elif a.cmd == "glyph":
+            if a.format == "png":
+                if not a.output:
+                    print("png output requires --output", file=sys.stderr)
+                    return 2
+                with open(a.output, "wb") as fh:
+                    fh.write(render_png(a.text))
+            else:
+                out = {"json": geometry_json, "svg": render_svg, "scene": scene_json}[a.format](a.text)
+                if a.output:
+                    with open(a.output, "w", encoding="utf-8") as fh:
+                        fh.write(out)
+                else:
+                    print(out)
+        elif a.cmd == "error":
+            code = a.code.upper()
+            try:
+                data: dict[str, Any] = entry(code)
+            except ValueError as err:
+                print(f"error: {err}", file=sys.stderr)
+                return 1
+            print(json.dumps(data, sort_keys=True, indent=2))
+        elif a.cmd == "demo":
+            from .demo import run_demo
+            print(run_demo())
+    except NexError as err:
+        return _fail(err)
+    except OSError as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nex/demo.py

@@ -0,0 +1,21 @@
+"""Self-contained two-agent demonstration used by ``nex demo`` and the examples."""
+from __future__ import annotations
+
+import json
+
+from .agent import NexAgent
+from .security import MemoryKeyStore
+
+
+def run_demo() -> str:
+    """Signed handshake + request between two in-process agents; returns a JSON summary."""
+    keys = MemoryKeyStore()
+    keys.generate("KEY-alice", "alice")
+    keys.generate("KEY-bob", "bob")
+    alice = NexAgent("alice", keystore=keys, key_id="KEY-alice")
+    bob = NexAgent("bob", keystore=keys, key_id="KEY-bob")
+    alice.connect_local(bob)
+    bob.connect_local(alice)
+    session = alice.handshake("bob")
+    report = alice.request("bob", session, "MOVE", target="CONTAINER7", destination="ZONE_B")
+    return json.dumps({"session_id": session, "report": report["body"]["payload"]}, sort_keys=True, indent=2)

nex/errors.py

@@ -0,0 +1,52 @@
+"""Nex error registry access and the NexError exception."""
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+from ._data import load_json
+
+REGISTRY_PATH = "registries/nex-error-registry-1.1.json"
+RETIRED_CODES = frozenset({"E505"})
+
+
+@lru_cache(maxsize=1)
+def registry() -> dict[str, dict[str, Any]]:
+    """Return the error registry keyed by code."""
+    return {e["code"]: e for e in load_json(REGISTRY_PATH)["entries"]}
+
+
+def entry(code: str) -> dict[str, Any]:
+    if code in RETIRED_CODES:
+        raise ValueError(f"error code {code} is retired and must not be used")
+    try:
+        return registry()[code]
+    except KeyError:
+        raise ValueError(f"unknown error code {code!r}") from None
+
+
+def error_payload(code: str, details: Any = None, severity: str | None = None,
+                  recovery: str | None = None) -> dict[str, Any]:
+    """Build an ERROR command payload for a registry code."""
+    e = entry(code)
+    return {
+        "code": code,
+        "message": e["name"],
+        "severity": severity or e["default_severity"],
+        "recovery": recovery or e["default_recovery"],
+        "details": details,
+    }
+
+
+class NexError(Exception):
+    """A protocol-level failure carrying a registry code."""
+
+    def __init__(self, code: str, details: Any = None):
+        e = entry(code)
+        self.code = code
+        self.name = e["name"]
+        self.details = details
+        super().__init__(f"{code} {self.name}" + (f": {details}" if details is not None else ""))
+
+    def payload(self) -> dict[str, Any]:
+        return error_payload(self.code, self.details)

nex/fastschema.py

@@ -0,0 +1,193 @@
+"""Fast schema checker: compiles the frozen JSON Schemas into Python closures.
+
+The JSON Schema files remain authoritative. This module supports exactly the keyword subset the
+Nex schemas use and refuses (``Unsupported``) anything else. It only answers valid / invalid; on
+"invalid" the validator re-runs ``jsonschema`` to produce the precise error, so error behaviour is
+unchanged and ``jsonschema`` stays the reference implementation.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Callable
+from urllib.parse import urldefrag, urljoin
+
+Check = Callable[[Any], bool]
+
+_SUPPORTED = {"$schema", "$id", "title", "description", "$defs", "type", "additionalProperties", "required",
+              "properties", "pattern", "not", "const", "enum", "allOf", "oneOf", "$ref", "if", "then",
+              "minLength", "items", "uniqueItems", "minItems", "minimum", "maximum"}
+
+
+class Unsupported(Exception):
+    pass
+
+
+def _is_num(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _is_int(v: Any) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool) or (isinstance(v, float) and v.is_integer())
+
+
+_TYPES: dict[str, Check] = {
+    "object": lambda v: isinstance(v, dict),
+    "array": lambda v: isinstance(v, list),
+    "string": lambda v: isinstance(v, str),
+    "boolean": lambda v: isinstance(v, bool),
+    "null": lambda v: v is None,
+    "number": _is_num,
+    "integer": _is_int,
+}
+
+
+def _eq(a: Any, b: Any) -> bool:
+    """JSON Schema equality: bool is distinct from numbers; 1 == 1.0."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(_eq(x, y) for x, y in zip(a, b))
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_eq(a[k], b[k]) for k in a)
+    if isinstance(a, (list, dict)) or isinstance(b, (list, dict)):
+        return False
+    return a == b
+
+
+class Compiler:
+    def __init__(self, documents: dict[str, Any]) -> None:
+        self.docs = documents
+        self.cache: dict[tuple[str, int], Check] = {}
+
+    def resolve(self, base: str, ref: str) -> tuple[Any, str]:
+        url, frag = urldefrag(urljoin(base, ref))
+        doc = self.docs.get(url)
+        if doc is None:
+            raise Unsupported(f"unresolvable $ref {ref!r}")
+        node = doc
+        for part in [p for p in frag.split("/") if p]:
+            node = node[part.replace("~1", "/").replace("~0", "~")]
+        return node, url
+
+    def compile(self, schema: Any, base: str) -> Check:
+        if schema is True:
+            return lambda v: True
+        if schema is False:
+            return lambda v: False
+        if not isinstance(schema, dict):
+            raise Unsupported("schema must be an object")
+        key = (base, id(schema))
+        if key in self.cache:
+            cached = self.cache[key]
+            return lambda v: cached(v)  # late-bound for recursion
+        holder: list[Check] = []
+        self.cache[key] = lambda v: holder[0](v)
+        holder.append(self._build(schema, schema.get("$id", base)))
+        self.cache[key] = holder[0]
+        return holder[0]
+
+    def _build(self, s: dict[str, Any], base: str) -> Check:
+        unknown = set(s) - _SUPPORTED
+        if unknown:
+            raise Unsupported(f"unsupported keywords: {sorted(unknown)}")
+        checks: list[Check] = []
+        c = self.compile
+
+        if "$ref" in s:
+            node, url = self.resolve(base, s["$ref"])
+            checks.append(c(node, url))
+        if "type" in s:
+            t = s["type"]
+            names = [t] if isinstance(t, str) else list(t)
+            if any(n not in _TYPES for n in names):
+                raise Unsupported("unknown type")
+            if len(names) == 1:
+                checks.append(_TYPES[names[0]])
+            else:
+                fns = [_TYPES[n] for n in names]
+                checks.append(lambda v, fns=fns: any(f(v) for f in fns))
+        if "const" in s:
+            const = s["const"]
+            checks.append(lambda v: _eq(v, const))
+        if "enum" in s:
+            options = s["enum"]
+            if all(isinstance(o, str) for o in options):
+                opts = frozenset(options)
+                checks.append(lambda v: isinstance(v, str) and v in opts)
+            else:
+                checks.append(lambda v: any(_eq(v, o) for o in options))
+        if "pattern" in s:
+            rx = re.compile(s["pattern"])
+            checks.append(lambda v: not isinstance(v, str) or rx.search(v) is not None)
+        if "minLength" in s:
+            n = s["minLength"]
+            checks.append(lambda v: not isinstance(v, str) or len(v) >= n)
+        if "minimum" in s:
+            lo = s["minimum"]
+            checks.append(lambda v: not _is_num(v) or v >= lo)
+        if "maximum" in s:
+            hi = s["maximum"]
+            checks.append(lambda v: not _is_num(v) or v <= hi)
+        if "minItems" in s:
+            n = s["minItems"]
+            checks.append(lambda v: not isinstance(v, list) or len(v) >= n)
+        if s.get("uniqueItems") is True:
+            def unique(v: Any) -> bool:
+                if not isinstance(v, list):
+                    return True
+                for i in range(len(v)):
+                    for j in range(i + 1, len(v)):
+                        if _eq(v[i], v[j]):
+                            return False
+                return True
+            checks.append(unique)
+        if "items" in s:
+            item = c(s["items"], base)
+            checks.append(lambda v: not isinstance(v, list) or all(item(x) for x in v))
+        if "required" in s:
+            req = tuple(s["required"])
+            checks.append(lambda v: not isinstance(v, dict) or all(k in v for k in req))
+        props = s.get("properties")
+        addl = s.get("additionalProperties", True)
+        if props is not None or addl is not True:
+            sub = {k: c(p, base) for k, p in (props or {}).items()}
+            addl_check = c(addl, base) if addl is not True and addl is not False else None
+            closed = addl is False
+
+            def obj(v: Any) -> bool:
+                if not isinstance(v, dict):
+                    return True
+                for k, x in v.items():
+                    f = sub.get(k)
+                    if f is not None:
+                        if not f(x):
+                            return False
+                    elif closed:
+                        return False
+                    elif addl_check is not None and not addl_check(x):
+                        return False
+                return True
+            checks.append(obj)
+        if "not" in s:
+            neg = c(s["not"], base)
+            checks.append(lambda v: not neg(v))
+        if "allOf" in s:
+            subs = [c(x, base) for x in s["allOf"]]
+            checks.append(lambda v: all(f(v) for f in subs))
+        if "oneOf" in s:
+            subs = [c(x, base) for x in s["oneOf"]]
+            checks.append(lambda v: sum(1 for f in subs if f(v)) == 1)
+        if "if" in s:
+            cond = c(s["if"], base)
+            then = c(s["then"], base) if "then" in s else (lambda v: True)
+            checks.append(lambda v: then(v) if cond(v) else True)
+
+        if not checks:
+            return lambda v: True
+        if len(checks) == 1:
+            return checks[0]
+        return lambda v: all(f(v) for f in checks)
+
+
+def compile_schema(documents: dict[str, Any], schema_id: str) -> Check:
+    return Compiler(documents).compile(documents[schema_id], schema_id)