lar1semantic 0.3.0__tar.gz

lar1semantic-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,42 @@
+# 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/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lar1semantic"
+version = "0.3.0"
+description = "Reference Python implementation of LAR-1 semantic overlay"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "LAR-1 contributors" }]
+keywords = ["lar-1", "agent", "mcp", "a2a", "semantic-overlay"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "langchain-core>=0.3.0"]
+
+[project.scripts]
+lar1 = "lar1.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/carlsonchik/larone"
+Repository = "https://github.com/carlsonchik/larone"
+Documentation = "https://github.com/carlsonchik/larone/blob/main/SPEC.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lar1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]

lar1semantic-0.3.0/src/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"

lar1semantic-0.3.0/src/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()

lar1semantic-0.3.0/src/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:"

lar1semantic-0.3.0/src/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)

lar1semantic-0.3.0/src/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))

lar1semantic-0.3.0/src/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)}

lar1semantic-0.3.0/src/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)

lar1semantic-0.3.0/src/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/tests/helpers.py

@@ -0,0 +1,17 @@
+"""Conformance fixture loader."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+CONFORMANCE_ROOT = REPO_ROOT / "SPEC" / "conformance"
+
+
+def load_fixtures(subdir: str) -> list[dict]:
+    directory = CONFORMANCE_ROOT / subdir
+    return [
+        json.loads(path.read_text(encoding="utf-8"))
+        for path in sorted(directory.glob("*.json"))
+    ]

lar1semantic-0.3.0/tests/test_conformance.py

@@ -0,0 +1,54 @@
+"""Conformance tests against SPEC/conformance fixtures."""
+
+from __future__ import annotations
+
+import pytest
+
+from lar1 import compact, parse, validate
+from lar1.errors import Lar1ParseError
+from tests.helpers import load_fixtures
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    load_fixtures("valid") + load_fixtures("enum"),
+    ids=lambda f: f["id"],
+)
+def test_valid_fixtures(fixture: dict) -> None:
+    parsed = parse(fixture["input"])
+    assert {"LAR-1": parsed} == fixture["expected"]
+    assert validate(parsed)
+    assert compact(parsed) == fixture["input"]
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    load_fixtures("invalid"),
+    ids=lambda f: f["id"],
+)
+def test_invalid_fixtures(fixture: dict) -> None:
+    with pytest.raises(Lar1ParseError) as exc:
+        parse(fixture["input"])
+    assert exc.value.code == fixture["error"]
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    [f for f in load_fixtures("boundary") if f.get("expected")],
+    ids=lambda f: f["id"],
+)
+def test_boundary_valid(fixture: dict) -> None:
+    parsed = parse(fixture["input"])
+    assert {"LAR-1": parsed} == fixture["expected"]
+    assert validate(parsed)
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    [f for f in load_fixtures("boundary") if f.get("error")],
+    ids=lambda f: f["id"],
+)
+def test_boundary_invalid(fixture: dict) -> None:
+    with pytest.raises(Lar1ParseError) as exc:
+        parse(fixture["input"])
+    assert exc.value.code == fixture["error"]

lar1semantic-0.3.0/tests/test_langgraph.py

@@ -0,0 +1,30 @@
+"""Tests for LangGraph integration helpers."""
+
+from langchain_core.messages import AIMessage
+
+from lar1.langgraph import (
+    attach_lar1_message,
+    lar1_for_node,
+    middleware_tag_node,
+    read_lar1_message,
+)
+
+
+def test_attach_and_read():
+    msg = AIMessage(content="hi")
+    tagged = attach_lar1_message(msg, {"C": "obs", "L": 0.9, "V": "verified_tool"})
+    block = read_lar1_message(tagged)
+    assert block is not None
+    assert block["C"] == "obs"
+
+
+def test_middleware_tag_node():
+    msg = AIMessage(content="research output")
+    tagged = middleware_tag_node("researcher", msg)
+    block = read_lar1_message(tagged)
+    assert block["C"] == "obs"
+
+
+def test_lar1_for_node_critic():
+    fields = lar1_for_node("critic")
+    assert fields["C"] == "rev"

lar1semantic-0.3.0/tests/test_roundtrip.py

@@ -0,0 +1,56 @@
+"""Round-trip tests for compact and JSON wire formats."""
+
+from __future__ import annotations
+
+import pytest
+
+from lar1 import compact, deserialize_fields, parse, serialize
+from lar1.enums import ENUMS
+from tests.helpers import load_fixtures
+
+
+@pytest.mark.parametrize("key,values", list(ENUMS.items()))
+def test_compact_roundtrip_enums(key: str, values: tuple[str, ...]) -> None:
+    for value in values:
+        first = parse(f"LAR:{key}={value}")
+        second = parse(compact(first))
+        assert second == first
+
+
+@pytest.mark.parametrize("l_val", [0, 0.5, 1])
+def test_compact_roundtrip_likelihood(l_val: float) -> None:
+    first = parse(f"LAR:L={l_val}")
+    second = parse(compact(first))
+    assert second == first
+
+
+@pytest.mark.parametrize("key,values", list(ENUMS.items()))
+def test_json_roundtrip_enums(key: str, values: tuple[str, ...]) -> None:
+    for value in values:
+        first = parse(f"LAR:{key}={value}")
+        second = deserialize_fields(serialize(first))
+        assert second == first
+
+
+def test_full_roundtrip_samples() -> None:
+    samples = [
+        "LAR:T=now,S=here,C=obs,E=direct,L=0.95,V=verified_tool",
+        "LAR:C=inf,L=0.72,V=unverified",
+    ]
+    for input_str in samples:
+        a = parse(input_str)
+        b = deserialize_fields(serialize(a))
+        assert b == a
+        c = parse(compact(a))
+        assert c == a
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    load_fixtures("valid") + load_fixtures("enum"),
+    ids=lambda f: f["id"],
+)
+def test_fixture_roundtrip(fixture: dict) -> None:
+    first = parse(fixture["input"])
+    assert parse(compact(first)) == first
+    assert deserialize_fields(serialize(first)) == first