claimtrace 0.1.0__py3-none-any.whl

claimtrace/__init__.py

@@ -0,0 +1,19 @@
+"""ClaimTrace public API."""
+
+from claimtrace.api import ClaimTracePackage, export_package, init_package, load_package, validate_package
+from claimtrace.constants import CAL_SCHEMA_VERSION, PACKAGE_VERSION
+from claimtrace.errors import ClaimTraceError, SchemaVersionError, SecurityError, ValidationError
+
+__all__ = [
+    "CAL_SCHEMA_VERSION",
+    "PACKAGE_VERSION",
+    "ClaimTraceError",
+    "SchemaVersionError",
+    "SecurityError",
+    "ValidationError",
+    "ClaimTracePackage",
+    "init_package",
+    "load_package",
+    "validate_package",
+    "export_package",
+]

claimtrace/__main__.py

@@ -0,0 +1,5 @@
+from claimtrace.cli import app
+
+
+if __name__ == "__main__":
+    app()

claimtrace/_finite.py

@@ -0,0 +1,23 @@
+"""Recursive finite-number checks for JSON- and YAML-derived data."""
+
+from __future__ import annotations
+
+import math
+from typing import TypeVar
+
+
+T = TypeVar("T")
+
+
+def ensure_finite(value: T, path: str = "$") -> T:
+    """Return *value* after rejecting NaN and infinite floats anywhere inside it."""
+
+    if isinstance(value, float) and not math.isfinite(value):
+        raise ValueError(f"Non-finite numeric value is not allowed at {path}.")
+    if isinstance(value, dict):
+        for key, child in value.items():
+            ensure_finite(child, f"{path}.{key}")
+    elif isinstance(value, (list, tuple, set)):
+        for index, child in enumerate(value):
+            ensure_finite(child, f"{path}[{index}]")
+    return value

claimtrace/_simple_yaml.py

@@ -0,0 +1,184 @@
+"""Small YAML reader/writer used when PyYAML is unavailable.
+
+The fallback intentionally supports only the answer-template subset used by ClaimTrace:
+mappings, lists, strings, booleans, numbers and null-like values.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from claimtrace._finite import ensure_finite
+
+
+def loads(text: str) -> Any:
+    stripped = text.strip()
+    if not stripped:
+        return {}
+    try:
+        return ensure_finite(
+            json.loads(stripped, parse_constant=_reject_json_constant),
+            "answers",
+        )
+    except json.JSONDecodeError:
+        pass
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        lines = _prepare_lines(text)
+        value, index = _parse_block(lines, 0, 0)
+        if index < len(lines):
+            raise ValueError(f"Could not parse YAML near line {index + 1}")
+        return ensure_finite(value, "answers")
+    try:
+        value = yaml.safe_load(text) or {}
+        ensure_finite(value, "answers")
+        return value
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        location = f" at line {mark.line + 1}, column {mark.column + 1}" if mark else ""
+        raise ValueError(f"Invalid answers YAML{location}: {exc}") from exc
+
+
+def dumps(data: Any) -> str:
+    ensure_finite(data, "answers")
+    try:
+        import yaml  # type: ignore
+
+        return yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+    except ImportError:
+        return _dump_value(data, 0).rstrip() + "\n"
+
+
+def load_path(path: str) -> Any:
+    with open(path, "r", encoding="utf-8") as handle:
+        return loads(handle.read())
+
+
+def dump_path(data: Any, path: str) -> None:
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(dumps(data))
+
+
+def _prepare_lines(text: str) -> list[tuple[int, str]]:
+    prepared: list[tuple[int, str]] = []
+    for raw in text.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip(" "))
+        prepared.append((indent, raw.strip()))
+    return prepared
+
+
+def _reject_json_constant(value: str) -> None:
+    raise ValueError(f"Non-finite numeric value {value} is not valid JSON.")
+
+
+def _parse_block(lines: list[tuple[int, str]], index: int, indent: int) -> tuple[Any, int]:
+    if index >= len(lines):
+        return {}, index
+    is_list = lines[index][0] == indent and lines[index][1].startswith("- ")
+    result: Any = [] if is_list else {}
+    while index < len(lines):
+        line_indent, content = lines[index]
+        if line_indent < indent:
+            break
+        if line_indent > indent:
+            raise ValueError(f"Unexpected indentation at line {index + 1}")
+        if is_list:
+            if not content.startswith("- "):
+                break
+            item_text = content[2:].strip()
+            if not item_text:
+                item, index = _parse_block(lines, index + 1, indent + 2)
+                result.append(item)
+                continue
+            if ":" in item_text and not item_text.startswith(("'", '"')):
+                key, value_text = item_text.split(":", 1)
+                item = {key.strip(): _parse_scalar(value_text.strip())} if value_text.strip() else {}
+                index += 1
+                if index < len(lines) and lines[index][0] > indent:
+                    nested, index = _parse_block(lines, index, indent + 2)
+                    if isinstance(nested, dict):
+                        item.update(nested)
+                    else:
+                        item[key.strip()] = nested
+                result.append(item)
+                continue
+            result.append(_parse_scalar(item_text))
+            index += 1
+            continue
+        if ":" not in content:
+            raise ValueError(f"Expected key/value mapping at line {index + 1}")
+        key, value_text = content.split(":", 1)
+        key = key.strip()
+        value_text = value_text.strip()
+        index += 1
+        if value_text:
+            result[key] = _parse_scalar(value_text)
+        elif index < len(lines) and lines[index][0] > indent:
+            result[key], index = _parse_block(lines, index, indent + 2)
+        else:
+            result[key] = {}
+    return result, index
+
+
+def _parse_scalar(value: str) -> Any:
+    if value in {"null", "Null", "NULL", "~"}:
+        return None
+    if value in {"true", "True", "TRUE"}:
+        return True
+    if value in {"false", "False", "FALSE"}:
+        return False
+    if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
+        return value[1:-1]
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        return value
+
+
+def _dump_value(data: Any, indent: int) -> str:
+    prefix = " " * indent
+    if isinstance(data, dict):
+        lines = []
+        for key, value in data.items():
+            if isinstance(value, (dict, list)):
+                lines.append(f"{prefix}{key}:")
+                lines.append(_dump_value(value, indent + 2))
+            else:
+                lines.append(f"{prefix}{key}: {_format_scalar(value)}")
+        return "\n".join(lines)
+    if isinstance(data, list):
+        lines = []
+        for item in data:
+            if isinstance(item, dict):
+                lines.append(f"{prefix}-")
+                lines.append(_dump_value(item, indent + 2))
+            elif isinstance(item, list):
+                lines.append(f"{prefix}-")
+                lines.append(_dump_value(item, indent + 2))
+            else:
+                lines.append(f"{prefix}- {_format_scalar(item)}")
+        return "\n".join(lines)
+    return f"{prefix}{_format_scalar(data)}"
+
+
+def _format_scalar(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value)
+    if not text or text.strip() != text or any(ch in text for ch in [":", "#", "[", "]", "{", "}"]):
+        return json.dumps(text)
+    return text

claimtrace/api.py

@@ -0,0 +1,368 @@
+"""Stable Python API for ClaimTrace."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from claimtrace.completion import (
+    apply_answers,
+    check_answers,
+    completed_answer_sections,
+    completion_tasks_for_template,
+    ensure_scene_for_images,
+    load_answers,
+)
+from claimtrace.constants import SEMANTIC_LAYER_FILENAME
+from claimtrace.errors import PackageError
+from claimtrace.importers.base import default_importers, detect_importer
+from claimtrace.models import Claim, ProvenancedString, SemanticLayer
+from claimtrace.models.semantic_layer import ClaimType, ConfidenceValue, ReviewStatus, SourceType, utc_now
+from claimtrace.models.validation import ValidationReport
+from claimtrace.package.layout import (
+    _validate_force_replace_root,
+    append_extraction_report,
+    create_package_root,
+    load_semantic_layer,
+    read_completion_tasks,
+    write_completion_tasks,
+    write_semantic_layer,
+)
+from claimtrace.package.registry import infer_role, register_local_artifact, replay_destination_for
+from claimtrace.path_hints import windows_path_hint
+from claimtrace.package.resources import synchronize_resource_bindings
+
+
+class ClaimTracePackage:
+    """A package directory loaded with its CAL semantic layer."""
+
+    def __init__(self, root: Path, semantic_layer: SemanticLayer):
+        self.root = Path(root)
+        self.semantic_layer = semantic_layer
+
+    def save(self) -> None:
+        """Write `semantic_layer.json` to disk."""
+
+        synchronize_resource_bindings(self.semantic_layer)
+        write_semantic_layer(self.root, self.semantic_layer)
+
+    def add_claim(
+        self,
+        text: str,
+        claim_type: str = "unknown",
+        figure_ref: str = "unknown",
+        *,
+        scope: str = "panel",
+    ) -> Claim:
+        """Add or replace a claim in the CAL."""
+
+        claim = Claim(
+            id=f"claim:{len(self.semantic_layer.claims) + 1:03d}",
+            claim_text=ProvenancedString(
+                value=text,
+                source_type=SourceType.user_asserted,
+                confidence=ConfidenceValue.unknown,
+                review_status=ReviewStatus.confirmed,
+                reviewer="api",
+                reviewed_at=utc_now(),
+            ),
+            claim_type=ClaimType(claim_type),
+            figure_ref=figure_ref,
+            scope=scope,
+            scene_ids=[scene.id for scene in self.semantic_layer.scenes],
+            claim_status="reviewable",
+            review_status=ReviewStatus.confirmed,
+        )
+        self.semantic_layer.claims.append(claim)
+        self.semantic_layer.add_activity(
+            "api_add_claim",
+            f"Added claim {claim.id}.",
+            generated_ids=[claim.id],
+        )
+        self.save()
+        return claim
+
+    def add_artifact(
+        self,
+        path: str | Path,
+        role: str | None = None,
+        *,
+        detached: bool = False,
+        scene_id: str | None = None,
+    ):
+        """Register a local artifact and copy it into the package by default."""
+
+        source = Path(path)
+        inferred_role = infer_role(source, role)
+        if scene_id is not None and inferred_role.value != "render_image":
+            raise ValueError("--scene/scene_id can only be used with a rendered-image artifact.")
+        if scene_id is not None and not any(
+            scene.id == scene_id for scene in self.semantic_layer.scenes
+        ):
+            raise ValueError(f"Unknown scene id for rendered panel: {scene_id}")
+        artifact = register_local_artifact(
+            self.root,
+            self.semantic_layer,
+            source,
+            role=role,
+            copy=True,
+            detached=detached,
+            relative_destination=replay_destination_for(self.semantic_layer, source),
+        )
+        if artifact.role.value == "render_image":
+            ensure_scene_for_images(
+                self.semantic_layer,
+                [artifact.id],
+                scene_id=scene_id,
+            )
+        self.semantic_layer.add_activity(
+            "api_add_artifact",
+            f"Added artifact {artifact.id}.",
+            generated_ids=[artifact.id],
+        )
+        self.save()
+        return artifact
+
+    def complete_from_answers(self, answers_path: str | Path) -> "ClaimTracePackage":
+        """Apply a user-friendly answer file to the package."""
+
+        answers_path = Path(answers_path)
+        answers = load_answers(answers_path)
+        problems = check_answers(
+            answers,
+            self.semantic_layer,
+            root=self.root,
+            answer_base=answers_path.parent,
+        )
+        if problems:
+            raise ValueError("Answer file needs updates:\n" + "\n".join(f"- {problem}" for problem in problems))
+        apply_answers(self.root, self.semantic_layer, answers, answer_base=answers_path.parent)
+        self.save()
+        completed_sections = completed_answer_sections(answers)
+        tasks = read_completion_tasks(self.root)
+        for task in tasks:
+            if task.status != "waived":
+                task.status = "answered" if task.section in completed_sections else "open"
+        write_completion_tasks(self.root, tasks)
+        return self
+
+    def validate(self, mode: str = "draft") -> ValidationReport:
+        """Run validation and return a validation report."""
+
+        from claimtrace.validation.engine import validate_package
+
+        return validate_package(self.root, mode=mode)
+
+    def export(
+        self,
+        output: str | Path,
+        mode: str = "archive",
+        zip_output: bool | None = None,
+        *,
+        force: bool = False,
+    ) -> Path:
+        """Export this package as a directory or zip archive."""
+
+        from claimtrace.export.directory import export_package
+
+        output_path = Path(output)
+        if zip_output is None:
+            zip_output = output_path.suffix.lower() == ".zip"
+        return export_package(self.root, output_path, mode=mode, zip_output=zip_output, force=force)
+
+
+def init_package(
+    native: str | Path | list[str | Path] | None = None,
+    image: str | Path | list[str | Path] | None = None,
+    out: str | Path | None = None,
+    template: str = "simple-structure-view",
+    artifacts: list[str | Path] | None = None,
+    title: str = "Untitled ClaimTrace package",
+    force: bool = False,
+    blank: bool = False,
+) -> ClaimTracePackage:
+    """Initialize a ClaimTrace package from native, image and optional evidence artifacts."""
+
+    root = Path(out) if out is not None else Path("scene-package")
+    native_paths = _coerce_paths(native)
+    image_paths = _coerce_paths(image)
+    artifact_paths = _coerce_paths(artifacts)
+    input_paths = native_paths + image_paths + artifact_paths
+    if not input_paths and not blank:
+        raise PackageError("No input files were provided. Add --native, --image or --artifact, or pass --blank.")
+    _ensure_inputs_exist(input_paths)
+    if force and root.exists() and root.is_dir() and any(root.iterdir()):
+        _validate_force_replace_root(root)
+    _ensure_inputs_outside_output(input_paths, root)
+    _ensure_supported_inputs(native_paths, {".pml", ".cxc", ".mvsj", ".mvsx"}, "native scene")
+    _ensure_supported_inputs(
+        image_paths,
+        {".png", ".jpg", ".jpeg", ".tif", ".tiff", ".gif", ".webp", ".svg"},
+        "rendered image",
+    )
+    tasks = completion_tasks_for_template(template)
+    root_was_absent = not root.exists()
+    root_was_empty = root.exists() and root.is_dir() and not any(root.iterdir())
+    backup_container: Path | None = None
+    backup_root: Path | None = None
+    if force and root.exists() and root.is_dir() and any(root.iterdir()):
+        backup_container = Path(
+            tempfile.mkdtemp(
+                prefix=f".{root.name}.claimtrace-backup-",
+                dir=root.parent.resolve(),
+            )
+        )
+        backup_root = backup_container / "original"
+        root.rename(backup_root)
+    try:
+        semantic = create_package_root(
+            root,
+            title=title,
+            force=force and backup_root is None,
+        )
+        semantic.package.profile = template
+        importers = default_importers(include_experimental=False)
+        for path in native_paths:
+            _register_and_import(root, semantic, Path(path), importers)
+        for path in image_paths:
+            _register_and_import(root, semantic, Path(path), importers)
+        for path in artifact_paths:
+            source = Path(path)
+            artifact = register_local_artifact(
+                root,
+                semantic,
+                source,
+                copy=True,
+                relative_destination=replay_destination_for(semantic, source),
+            )
+            semantic.add_activity(
+                "artifact_registration",
+                f"Registered artifact {artifact.id}.",
+                generated_ids=[artifact.id],
+            )
+        ensure_scene_for_images(semantic)
+        synchronize_resource_bindings(semantic)
+        write_semantic_layer(root, semantic)
+        write_completion_tasks(root, tasks + read_completion_tasks(root))
+        package = ClaimTracePackage(root=root, semantic_layer=semantic)
+        if backup_container is not None:
+            shutil.rmtree(backup_container)
+        return package
+    except Exception:
+        if backup_root is not None and backup_root.exists():
+            if root.exists():
+                if root.is_dir() and not root.is_symlink():
+                    shutil.rmtree(root)
+                else:
+                    root.unlink()
+            backup_root.rename(root)
+            if backup_container is not None:
+                shutil.rmtree(backup_container)
+        elif (root_was_absent or root_was_empty) and root.exists():
+            shutil.rmtree(root)
+            if root_was_empty:
+                root.mkdir(parents=True, exist_ok=True)
+        raise
+
+
+def load_package(package: str | Path) -> ClaimTracePackage:
+    """Load an existing ClaimTrace package directory."""
+
+    root = Path(package)
+    if not (root / SEMANTIC_LAYER_FILENAME).exists():
+        raise PackageError(f"Missing {SEMANTIC_LAYER_FILENAME}: {root}")
+    return ClaimTracePackage(root=root, semantic_layer=load_semantic_layer(root))
+
+
+def validate_package(package: str | Path | ClaimTracePackage, mode: str = "draft") -> ValidationReport:
+    """Validate a package directory."""
+
+    from claimtrace.validation.engine import validate_package as _validate
+
+    root = package.root if isinstance(package, ClaimTracePackage) else Path(package)
+    return _validate(root, mode=mode)
+
+
+def export_package(
+    package: str | Path | ClaimTracePackage,
+    output: str | Path,
+    mode: str = "archive",
+    zip_output: bool | None = None,
+    *,
+    force: bool = False,
+) -> Path:
+    """Export a package as a directory or zip archive."""
+
+    from claimtrace.export.directory import export_package as _export
+
+    root = package.root if isinstance(package, ClaimTracePackage) else Path(package)
+    output_path = Path(output)
+    if zip_output is None:
+        zip_output = output_path.suffix == ".zip"
+    return _export(root, output_path, mode=mode, zip_output=zip_output, force=force)
+
+
+def _register_and_import(root: Path, semantic: SemanticLayer, source: Path, importers: list[Any]) -> None:
+    artifact = register_local_artifact(root, semantic, source, copy=True)
+    package_path = root / str(artifact.path)
+    plugin = detect_importer(package_path, importers)
+    result = plugin.import_into(package_path, artifact.id, semantic)
+    append_extraction_report(root, result.importer_name, result.fact_dicts())
+    existing_tasks = read_completion_tasks(root)
+    write_completion_tasks(root, existing_tasks + result.tasks)
+    semantic.add_activity(
+        "static_import",
+        f"Imported {artifact.path} with {result.importer_name}.",
+        used_artifact_ids=[artifact.id],
+        importer=result.importer_name,
+        warnings=result.warnings,
+    )
+
+
+def _coerce_paths(value: Any) -> list[Path]:
+    if value is None:
+        return []
+    if isinstance(value, (str, Path)):
+        return [Path(value)]
+    return [Path(item) for item in value]
+
+
+def _ensure_inputs_exist(paths: list[Path]) -> None:
+    for path in paths:
+        if not path.exists():
+            raise PackageError(
+                f"Input file not found: {path}. "
+                "Run from the directory containing the file or pass an absolute path."
+                f"{windows_path_hint(path)}"
+            )
+
+
+def _ensure_inputs_outside_output(paths: list[Path], root: Path) -> None:
+    root_resolved = root.resolve(strict=False)
+    for path in paths:
+        if path.resolve().is_relative_to(root_resolved):
+            raise PackageError(
+                f"Input file is inside the output package and could be deleted or overwritten: {path}. "
+                "Move the input outside --out or choose a different output directory."
+            )
+
+
+def _ensure_supported_inputs(paths: list[Path], suffixes: set[str], label: str) -> None:
+    allowed = ", ".join(sorted(suffixes))
+    for path in paths:
+        if not path.is_file():
+            raise PackageError(f"{label.capitalize()} input must be a regular file: {path}")
+        if path.suffix.lower() not in suffixes:
+            raise PackageError(
+                f"Unsupported {label} format for {path}. Supported extensions: {allowed}. "
+                "Use --artifact for other supporting files."
+            )
+
+
+def semantic_to_json(semantic: SemanticLayer) -> str:
+    """Serialize a CAL object as stable pretty JSON."""
+
+    return json.dumps(semantic.model_dump(mode="json", exclude_none=True), indent=2) + "\n"