lar1semantic 0.3.0__py3-none-any.whl

lar1/__init__.py

@@ -0,0 +1,21 @@
+"""LAR-1 semantic overlay — reference Python SDK."""
+
+from lar1.errors import Lar1ParseError
+from lar1.parse import parse, parse_envelope
+from lar1.serialize import compact, deserialize, deserialize_fields, serialize
+
+__all__ = [
+    "Lar1ParseError",
+    "parse",
+    "parse_envelope",
+    "validate",
+    "validate_envelope",
+    "serialize",
+    "deserialize",
+    "deserialize_fields",
+    "compact",
+]
+
+from lar1.validate import validate, validate_envelope
+
+__version__ = "0.3.0"

lar1/cli.py

@@ -0,0 +1,85 @@
+"""LAR-1 command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from lar1 import compact, deserialize_fields, parse, serialize, validate
+from lar1.errors import Lar1ParseError
+
+
+def _read_input(path: str | None) -> str:
+    if path and path != "-":
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    return sys.stdin.read()
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    raw = _read_input(args.file).strip()
+    try:
+        if raw.startswith("{"):
+            data = deserialize_fields(raw)
+        else:
+            data = parse(raw)
+        if validate(data):
+            print("OK")
+            return 0
+        print("INVALID", file=sys.stderr)
+        return 1
+    except (Lar1ParseError, ValueError) as exc:
+        code = getattr(exc, "code", "INVALID")
+        print(code, file=sys.stderr)
+        return 1
+
+
+def cmd_compact(args: argparse.Namespace) -> int:
+    raw = _read_input(args.file).strip()
+    try:
+        if raw.startswith("{"):
+            data = deserialize_fields(raw)
+        else:
+            data = parse(raw)
+        print(compact(data))
+        return 0
+    except (Lar1ParseError, ValueError) as exc:
+        code = getattr(exc, "code", str(exc))
+        print(code, file=sys.stderr)
+        return 1
+
+
+def cmd_json(args: argparse.Namespace) -> int:
+    raw = _read_input(args.file).strip()
+    try:
+        data = parse(raw)
+        print(serialize(data))
+        return 0
+    except Lar1ParseError as exc:
+        print(exc.code, file=sys.stderr)
+        return 1
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="lar1", description="LAR-1 semantic overlay CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_validate = sub.add_parser("validate", help="Validate compact or JSON input")
+    p_validate.add_argument("file", nargs="?", default="-", help="File path or - for stdin")
+    p_validate.set_defaults(func=cmd_validate)
+
+    p_compact = sub.add_parser("compact", help="Output canonical compact string")
+    p_compact.add_argument("file", nargs="?", default="-")
+    p_compact.set_defaults(func=cmd_compact)
+
+    p_json = sub.add_parser("json", help="Convert compact to application/lar+json")
+    p_json.add_argument("file", nargs="?", default="-")
+    p_json.set_defaults(func=cmd_json)
+
+    args = parser.parse_args()
+    raise SystemExit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

lar1/enums.py

@@ -0,0 +1,55 @@
+"""LAR-1 v0.2 field enums."""
+
+from __future__ import annotations
+
+from typing import Final, Literal, TypedDict
+
+TemporalFrame = Literal["now", "past", "recall", "future"]
+SpatialFrame = Literal["here", "there", "meta"]
+CognitionStance = Literal["obs", "hyp", "mem", "det", "inf", "rev"]
+EvidenceGrounding = Literal["direct", "derived", "aggregated", "reported"]
+VerificationStatus = Literal[
+    "unverified", "verified_human", "verified_tool", "verified_crossref"
+]
+
+Lar1ErrorCode = Literal[
+    "EMPTY_INPUT",
+    "MISSING_PREFIX",
+    "NO_PAIRS",
+    "UNKNOWN_KEY",
+    "INVALID_ENUM",
+    "INVALID_LIKELIHOOD",
+    "DUPLICATE_KEY",
+    "MALFORMED_PAIR",
+    "EMPTY_OBJECT",
+]
+
+
+class Lar1Fields(TypedDict, total=False):
+    T: TemporalFrame
+    S: SpatialFrame
+    C: CognitionStance
+    E: EvidenceGrounding
+    L: float
+    V: VerificationStatus
+
+
+Lar1Envelope = TypedDict("Lar1Envelope", {"LAR-1": Lar1Fields})
+
+
+ENUMS: Final[dict[str, tuple[str, ...]]] = {
+    "T": ("now", "past", "recall", "future"),
+    "S": ("here", "there", "meta"),
+    "C": ("obs", "hyp", "mem", "det", "inf", "rev"),
+    "E": ("direct", "derived", "aggregated", "reported"),
+    "V": (
+        "unverified",
+        "verified_human",
+        "verified_tool",
+        "verified_crossref",
+    ),
+}
+
+VALID_KEYS: Final[frozenset[str]] = frozenset({"T", "S", "C", "E", "L", "V"})
+FIELD_ORDER: Final[tuple[str, ...]] = ("T", "S", "C", "E", "L", "V")
+PREFIX: Final[str] = "LAR:"

lar1/errors.py

@@ -0,0 +1,7 @@
+"""LAR-1 parse errors."""
+
+
+class Lar1ParseError(Exception):
+    def __init__(self, code: str, message: str | None = None) -> None:
+        self.code = code
+        super().__init__(message or code)

lar1/langgraph.py

@@ -0,0 +1,60 @@
+"""LangGraph / LangChain message integration for LAR-1."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lar1 import validate
+
+LAR1_KEY = "lar-1"
+
+# Default cognitive tags by node role name (substring match)
+NODE_COGNITION: dict[str, str] = {
+    "research": "obs",
+    "retrieve": "obs",
+    "critic": "rev",
+    "review": "rev",
+    "synth": "inf",
+    "merge": "inf",
+    "plan": "hyp",
+    "memory": "mem",
+}
+
+
+def attach_lar1_message(message: Any, fields: dict[str, Any]) -> Any:
+    """Attach LAR-1 to LangChain message additional_kwargs."""
+    if not validate(fields):
+        raise ValueError("Invalid LAR-1 fields")
+    kwargs = dict(getattr(message, "additional_kwargs", {}) or {})
+    kwargs[LAR1_KEY] = fields
+    return message.model_copy(update={"additional_kwargs": kwargs})
+
+
+def read_lar1_message(message: Any) -> dict[str, Any] | None:
+    block = getattr(message, "additional_kwargs", {}).get(LAR1_KEY)
+    if isinstance(block, dict) and validate(block):
+        return block
+    return None
+
+
+def lar1_for_node(node_name: str, *, likelihood: float = 0.75) -> dict[str, Any]:
+    """Suggest LAR-1 fields from LangGraph node name."""
+    name = node_name.lower()
+    cognition = "inf"
+    for key, c in NODE_COGNITION.items():
+        if key in name:
+            cognition = c
+            break
+    return {
+        "T": "now",
+        "S": "here",
+        "C": cognition,
+        "E": "derived" if cognition == "inf" else "direct",
+        "L": likelihood,
+        "V": "unverified",
+    }
+
+
+def middleware_tag_node(node_name: str, message: Any) -> Any:
+    """Auto-tag agent message from node name (LangGraph middleware helper)."""
+    return attach_lar1_message(message, lar1_for_node(node_name))

lar1/parse.py

@@ -0,0 +1,67 @@
+"""Parse LAR-1 compact strings."""
+
+from __future__ import annotations
+
+from lar1.enums import ENUMS, PREFIX, VALID_KEYS, Lar1Fields
+from lar1.errors import Lar1ParseError
+
+
+def _assert_enum(key: str, value: str) -> str:
+    allowed = ENUMS[key]
+    if value not in allowed:
+        raise Lar1ParseError("INVALID_ENUM", f"Invalid {key}={value}")
+    return value
+
+
+def _parse_likelihood(raw: str) -> float:
+    try:
+        n = float(raw)
+    except ValueError:
+        raise Lar1ParseError("INVALID_LIKELIHOOD", f"Invalid L={raw}") from None
+    if n < 0 or n > 1:
+        raise Lar1ParseError("INVALID_LIKELIHOOD", f"L out of range: {n}")
+    return n
+
+
+def parse(compact: str) -> Lar1Fields:
+    """Parse compact string into inner LAR-1 fields."""
+    trimmed = compact.strip()
+    if trimmed == "":
+        raise Lar1ParseError("EMPTY_INPUT")
+    if not trimmed.startswith(PREFIX):
+        raise Lar1ParseError("MISSING_PREFIX")
+
+    body = trimmed[len(PREFIX) :]
+    if body == "":
+        raise Lar1ParseError("NO_PAIRS")
+
+    pairs = body.split(",")
+    if not pairs or (len(pairs) == 1 and pairs[0] == ""):
+        raise Lar1ParseError("NO_PAIRS")
+
+    seen: set[str] = set()
+    data: Lar1Fields = {}
+
+    for pair in pairs:
+        if "=" not in pair:
+            raise Lar1ParseError("MALFORMED_PAIR", f"Missing '=': {pair}")
+        key, _, value = pair.partition("=")
+        key = key.strip()
+        value = value.strip()
+
+        if key not in VALID_KEYS:
+            raise Lar1ParseError("UNKNOWN_KEY", f"Unknown key: {key}")
+        if key in seen:
+            raise Lar1ParseError("DUPLICATE_KEY", f"Duplicate key: {key}")
+        seen.add(key)
+
+        if key == "L":
+            data["L"] = _parse_likelihood(value)
+        elif key in ENUMS:
+            data[key] = _assert_enum(key, value)  # type: ignore[literal-required]
+
+    return data
+
+
+def parse_envelope(compact: str) -> dict[str, Lar1Fields]:
+    return {"LAR-1": parse(compact)}

lar1/serialize.py

@@ -0,0 +1,42 @@
+"""Serialize and deserialize LAR-1 data."""
+
+from __future__ import annotations
+
+import json
+
+from lar1.enums import FIELD_ORDER, PREFIX, Lar1Fields
+from lar1.validate import validate, validate_envelope
+
+
+def serialize(data: Lar1Fields) -> str:
+    return json.dumps({"LAR-1": data}, separators=(",", ":"))
+
+
+def deserialize(json_str: str) -> dict[str, Lar1Fields]:
+    try:
+        parsed = json.loads(json_str)
+    except json.JSONDecodeError as exc:
+        raise ValueError("Invalid JSON") from exc
+    if not validate_envelope(parsed):
+        raise ValueError("Invalid LAR-1 envelope")
+    return parsed
+
+
+def deserialize_fields(json_str: str) -> Lar1Fields:
+    return deserialize(json_str)["LAR-1"]
+
+
+def _format_value(key: str, value: object) -> str:
+    if key == "L" and isinstance(value, float) and value == int(value):
+        return str(int(value))
+    return str(value)
+
+
+def compact(data: Lar1Fields) -> str:
+    parts: list[str] = []
+    for key in FIELD_ORDER:
+        if key in data:
+            parts.append(f"{key}={_format_value(key, data[key])}")
+    if not parts:
+        raise ValueError("Cannot compact empty LAR-1 object")
+    return PREFIX + ",".join(parts)

lar1/validate.py

@@ -0,0 +1,34 @@
+"""Validate LAR-1 fields."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lar1.enums import ENUMS, Lar1Fields
+
+
+def _is_likelihood(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and 0 <= value <= 1
+
+
+def validate(data: Lar1Fields | Any) -> bool:
+    if not isinstance(data, dict) or not data:
+        return False
+
+    for key, value in data.items():
+        if key in ENUMS:
+            if value not in ENUMS[key]:
+                return False
+        elif key == "L":
+            if not _is_likelihood(value):
+                return False
+        else:
+            return False
+
+    return True
+
+
+def validate_envelope(envelope: Any) -> bool:
+    if not isinstance(envelope, dict) or "LAR-1" not in envelope:
+        return False
+    return validate(envelope["LAR-1"])

lar1semantic-0.3.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: lar1semantic
+Version: 0.3.0
+Summary: Reference Python implementation of LAR-1 semantic overlay
+Project-URL: Homepage, https://github.com/carlsonchik/larone
+Project-URL: Repository, https://github.com/carlsonchik/larone
+Project-URL: Documentation, https://github.com/carlsonchik/larone/blob/main/SPEC.md
+Author: LAR-1 contributors
+License-Expression: MIT
+Keywords: a2a,agent,lar-1,mcp,semantic-overlay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lar-1 (Python)
+
+Reference Python implementation of **LAR-1** v0.2 semantic overlay.
+
+## Install
+
+```bash
+pip install lar-1
+# or from monorepo:
+cd packages/lar1-python && pip install -e ".[dev]"
+```
+
+## API
+
+```python
+from lar1 import parse, validate, compact, serialize, deserialize_fields
+
+data = parse("LAR:T=now,C=obs,L=0.9,V=verified_tool")
+validate(data)  # True
+compact(data)   # canonical LAR: string
+serialize(data)  # application/lar+json
+```
+
+## CLI
+
+```bash
+lar1 validate 'LAR:C=obs,L=0.9'
+lar1 compact message.json
+lar1 json 'LAR:T=now,C=inf,L=0.7'
+```
+
+## Tests
+
+```bash
+pytest
+```
+
+Runs the same 74+ conformance fixtures as `@lar-1/core`.
+
+## License
+
+MIT

lar1semantic-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lar1/__init__.py,sha256=maN2Z7Gni_lnzXOi_fFdmvNSLy5SY4WIAVPKr0mvmTs,487
+lar1/cli.py,sha256=NmQjrqdhLB_0D-74J99ZZju_Ip9ozkTEqkY1N2S7cwA,2462
+lar1/enums.py,sha256=bv0AlJY7RzgW3ZjOwQ4TNL50P6axQJi1zjiHBHsl4LY,1457
+lar1/errors.py,sha256=UQaYuCCSKYc_6s43u-9djTXA4NCWGCXam5U3NbrSJUY,199
+lar1/langgraph.py,sha256=Lx6FNleounSeADswN2NGODDWYoTogC3_hYr2QKUBULE,1739
+lar1/parse.py,sha256=jQXxTKk5Rf_-Mi-54TPXWYeBfva5xXBfT0KxzzP0MTs,1962
+lar1/serialize.py,sha256=7pyx4gmdAmbJNW6Hc24-BAM1m7TVdTtANFT6ii-BJes,1186
+lar1/validate.py,sha256=b9q_Ih13UEsQeIKVbzXp4CB9KvhbMu3SCmKpjbwLzeY,841
+lar1semantic-0.3.0.dist-info/METADATA,sha256=CAHzccSNY5_leDxf0dJi9s-bohT7SFHP2bxYx8NEx1U,1523
+lar1semantic-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+lar1semantic-0.3.0.dist-info/entry_points.txt,sha256=wHhgI9GMzcOgqSGvJXHHuD7bI9prrS146iGw8kg6PBU,39
+lar1semantic-0.3.0.dist-info/RECORD,,

lar1semantic-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

lar1semantic-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lar1 = lar1.cli:main