agent-assure 0.3.0__py3-none-any.whl

agent_assure/__init__.py

@@ -0,0 +1,4 @@
+"""agent-assure public package."""
+
+__version__ = "0.3.0"
+SCHEMA_VERSION = "0.2.0"

agent_assure/artifact_io.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+
+
+def file_sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def git_output(project_root: Path, *args: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=project_root,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None

agent_assure/authoring/__init__.py

@@ -0,0 +1,4 @@
+from agent_assure.authoring.compiler import compile_suite
+from agent_assure.authoring.yaml_lint import lint_yaml
+
+__all__ = ["compile_suite", "lint_yaml"]

agent_assure/authoring/compiler.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_assure.authoring.yaml_nodes import LoadedYaml, load_yaml_nodes
+from agent_assure.canonical.digests import sha256_hexdigest
+from agent_assure.schema.expectation import Expectation
+from agent_assure.schema.suite import CompiledSuite, SuiteCase, SuiteDefaults
+
+
+def compile_suite(path: Path) -> CompiledSuite:
+    loaded = load_yaml_nodes(path)
+    return compile_loaded_suite(loaded, source_digest=sha256_hexdigest(loaded.data))
+
+
+def compile_loaded_suite(loaded: LoadedYaml, source_digest: str) -> CompiledSuite:
+    data = loaded.data
+    defaults_data = dict(_mapping(data.get("defaults", {})))
+    expectation_defaults = _mapping(
+        defaults_data.pop("expectation", defaults_data.pop("expectation_defaults", {}))
+    )
+    defaults = SuiteDefaults(**defaults_data)
+    cases: list[SuiteCase] = []
+    expectations: list[Expectation] = []
+    for case_data in _sequence(data.get("cases", ())):
+        case_map = _mapping(case_data)
+        expectation_data = _merge_expectation_defaults(
+            expectation_defaults,
+            _mapping(case_map.get("expectation", {})),
+        )
+        expectation_data.setdefault("case_id", str(case_map["case_id"]))
+        expectation_data.setdefault("expectation_id", f"{case_map['case_id']}:expectation")
+        expectation_without_digest = Expectation(**expectation_data)
+        expectation = expectation_without_digest.model_copy(
+            update={
+                "expectation_digest": sha256_hexdigest(
+                    expectation_without_digest.model_dump(
+                        mode="json",
+                        exclude={"expectation_digest"},
+                    )
+                )
+            }
+        )
+        case = SuiteCase(
+            case_id=str(case_map["case_id"]),
+            title=str(case_map["title"]),
+            expectation_id=expectation.expectation_id,
+            fixture_id=_optional_string(case_map.get("fixture_id")),
+            tags=tuple(str(tag) for tag in _sequence(case_map.get("tags", ()))),
+        )
+        cases.append(case)
+        expectations.append(expectation)
+    return CompiledSuite(
+        suite_id=str(data["suite_id"]),
+        suite_version=str(data["suite_version"]),
+        defaults=defaults,
+        cases=tuple(cases),
+        resolved_expectations=tuple(expectations),
+        source_digest=source_digest,
+    )
+
+
+def _mapping(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError("expected mapping")
+    return value
+
+
+def _sequence(value: Any) -> tuple[Any, ...]:
+    if not isinstance(value, tuple | list):
+        raise TypeError("expected sequence")
+    return tuple(value)
+
+
+def _optional_string(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _merge_expectation_defaults(
+    defaults: dict[str, Any],
+    overrides: dict[str, Any],
+) -> dict[str, Any]:
+    merged = dict(defaults)
+    for key, value in overrides.items():
+        if isinstance(merged.get(key), dict) and isinstance(value, dict):
+            merged[key] = _merge_expectation_defaults(merged[key], value)
+            continue
+        merged[key] = value
+    return merged

agent_assure/authoring/string_fields.py

@@ -0,0 +1,15 @@
+SEMANTIC_STRING_FIELDS = {
+    "suite_id",
+    "suite_version",
+    "case_id",
+    "expectation_id",
+    "expected_recommendation",
+    "allowed_outcomes",
+    "forbidden_outcomes",
+    "required_evidence_refs",
+    "material_claim_ids",
+    "allowed_providers",
+    "forbidden_providers",
+    "allowed_tools",
+    "forbidden_tools",
+}

agent_assure/authoring/yaml_lint.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_assure.authoring.yaml_nodes import YamlWarning, load_yaml_nodes
+
+
+def lint_yaml(path: Path) -> tuple[YamlWarning, ...]:
+    return load_yaml_nodes(path).warnings

agent_assure/authoring/yaml_loader.py

@@ -0,0 +1,4 @@
+
+from agent_assure.authoring.yaml_nodes import LoadedYaml, load_yaml_nodes
+
+__all__ = ["LoadedYaml", "load_yaml_nodes"]

agent_assure/authoring/yaml_nodes.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class YamlWarning:
+    path: str
+    message: str
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class LoadedYaml:
+    data: dict[str, Any]
+    warnings: tuple[YamlWarning, ...]
+
+
+AMBIGUOUS_TAGS = {
+    "tag:yaml.org,2002:int",
+    "tag:yaml.org,2002:float",
+    "tag:yaml.org,2002:timestamp",
+}
+
+
+def load_yaml_nodes(path: Path) -> LoadedYaml:
+    text = path.read_text(encoding="utf-8")
+    node = yaml.compose(text)
+    warnings: list[YamlWarning] = []
+    data = _convert_node(node, "$", warnings)
+    if not isinstance(data, dict):
+        raise ValueError("suite YAML root must be a mapping")
+    return LoadedYaml(data=data, warnings=tuple(warnings))
+
+
+def _convert_node(node: yaml.Node | None, path: str, warnings: list[YamlWarning]) -> Any:
+    if node is None:
+        return {}
+    if isinstance(node, yaml.MappingNode):
+        result: dict[str, Any] = {}
+        for key_node, value_node in node.value:
+            key = str(_convert_node(key_node, path, warnings))
+            if key in result:
+                raise ValueError(
+                    f"duplicate YAML mapping key at {path}.{key}: "
+                    f"line {key_node.start_mark.line + 1}, "
+                    f"column {key_node.start_mark.column + 1}"
+                )
+            result[key] = _convert_node(value_node, f"{path}.{key}", warnings)
+        return result
+    if isinstance(node, yaml.SequenceNode):
+        return tuple(_convert_node(item, f"{path}[]", warnings) for item in node.value)
+    if isinstance(node, yaml.ScalarNode):
+        if unicodedata.normalize("NFC", node.value) != node.value:
+            warnings.append(
+                YamlWarning(
+                    path=path,
+                    message="string is not NFC-normalized",
+                    line=node.start_mark.line + 1,
+                    column=node.start_mark.column + 1,
+                )
+            )
+        if node.tag in AMBIGUOUS_TAGS:
+            warnings.append(
+                YamlWarning(
+                    path=path,
+                    message=f"ambiguous scalar preserved as string: {node.value!r}",
+                    line=node.start_mark.line + 1,
+                    column=node.start_mark.column + 1,
+                )
+            )
+            return node.value
+        if node.tag == "tag:yaml.org,2002:bool":
+            return node.value.lower() in {"true", "yes", "on"}
+        if node.tag == "tag:yaml.org,2002:null":
+            return None
+        return node.value
+    raise TypeError(f"unsupported YAML node: {type(node).__name__}")

agent_assure/canonical/__init__.py

@@ -0,0 +1,11 @@
+from agent_assure.canonical.digests import sha256_hexdigest
+from agent_assure.canonical.hmac_tokens import hmac_sha256_token, verify_hmac_token
+from agent_assure.canonical.normalize import digest_projection, normalize_decimal
+
+__all__ = [
+    "digest_projection",
+    "hmac_sha256_token",
+    "normalize_decimal",
+    "sha256_hexdigest",
+    "verify_hmac_token",
+]

agent_assure/canonical/digests.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from agent_assure.canonical.jcs import canonical_bytes
+from agent_assure.canonical.normalize import digest_projection
+
+
+def sha256_hexdigest(value: Any) -> str:
+    return hashlib.sha256(canonical_bytes(digest_projection(value))).hexdigest()

agent_assure/canonical/hmac_tokens.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def hmac_sha256_token(value: str, key: bytes) -> str:
+    _validate_hmac_key(key)
+    return hmac.new(key, value.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def verify_hmac_token(received_token: str, value: str, key: bytes) -> bool:
+    expected_token = hmac_sha256_token(value, key)
+    return hmac.compare_digest(received_token, expected_token)
+
+
+def _validate_hmac_key(key: bytes) -> None:
+    if not isinstance(key, bytes):
+        raise TypeError("HMAC key must be bytes")
+    if not key:
+        raise ValueError("HMAC key must not be empty")

agent_assure/canonical/jcs.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+import rfc8785
+
+
+def canonical_bytes(projected: Any) -> bytes:
+    result = rfc8785.dumps(projected)
+    if isinstance(result, bytes):
+        return result
+    return result.encode("utf-8")

agent_assure/canonical/manifest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def posix_manifest_path(path: Path, root: Path) -> str:
+    resolved = path.resolve()
+    resolved_root = root.resolve()
+    relative = resolved.relative_to(resolved_root)
+    return relative.as_posix()

agent_assure/canonical/normalize.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import unicodedata
+from decimal import Decimal, localcontext
+from math import isfinite
+from typing import Any
+
+from agent_assure.schema.common import ReasonCode
+
+DECIMAL_QUANTUM = Decimal("0.000001")
+
+
+class CanonicalizationError(ValueError):
+    def __init__(self, reason_code: ReasonCode, message: str) -> None:
+        self.reason_code = reason_code
+        super().__init__(message)
+
+
+def normalize_decimal(value: Decimal | str) -> str:
+    decimal = Decimal(str(value))
+    if not decimal.is_finite():
+        raise CanonicalizationError(ReasonCode.NON_FINITE_NUMBER, "decimal is not finite")
+    quantum_exponent = DECIMAL_QUANTUM.as_tuple().exponent
+    if not isinstance(quantum_exponent, int):
+        raise CanonicalizationError(ReasonCode.NON_FINITE_NUMBER, "decimal quantum is not finite")
+    fractional_places = abs(quantum_exponent)
+    integer_digits = max(decimal.adjusted() + 1, 1)
+    with localcontext() as context:
+        context.prec = max(context.prec, integer_digits + fractional_places + 1)
+        return format(decimal.quantize(DECIMAL_QUANTUM), "f")
+
+
+def ensure_nfc(value: str) -> str:
+    if unicodedata.normalize("NFC", value) != value:
+        raise CanonicalizationError(ReasonCode.NON_NFC_STRING, "string is not NFC-normalized")
+    return value
+
+
+def digest_projection(value: Any) -> Any:
+    """Project typed values into deterministic canonical digest material.
+
+    Explicit ``None`` values are preserved as identity data. Digest roles that
+    need missing fields and null fields to be equivalent must apply a
+    role-specific projection before using this generic path.
+    """
+    if isinstance(value, Decimal):
+        return normalize_decimal(value)
+    if isinstance(value, str):
+        return ensure_nfc(value)
+    if isinstance(value, bool) or value is None or isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise CanonicalizationError(ReasonCode.NON_FINITE_NUMBER, "float is not finite")
+        raise TypeError("float values must be converted to Decimal before digest projection")
+    if isinstance(value, tuple | list):
+        return [digest_projection(item) for item in value]
+    if isinstance(value, dict):
+        projected_items: list[tuple[str, Any]] = []
+        seen_keys: set[str] = set()
+        for key, item in value.items():
+            projected_key = ensure_nfc(str(key))
+            if projected_key in seen_keys:
+                raise TypeError(f"duplicate projected object key: {projected_key!r}")
+            seen_keys.add(projected_key)
+            projected_items.append((projected_key, digest_projection(item)))
+        return {key: item for key, item in sorted(projected_items, key=lambda pair: pair[0])}
+    if hasattr(value, "model_dump"):
+        return digest_projection(value.model_dump(mode="json"))
+    raise TypeError(f"unsupported digest projection type: {type(value).__name__}")

agent_assure/canonical/projection.py

@@ -0,0 +1,3 @@
+from agent_assure.canonical.normalize import digest_projection
+
+__all__ = ["digest_projection"]