langparse 0.1.0__py3-none-any.whl

langparse/workbooks/objects.py

@@ -0,0 +1,229 @@
+"""Source-grounded drawing facts and semantic blocks; no image inference or I/O."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from langparse.types import ParseDiagnostics
+from langparse.workbooks.types import (
+    SourceRef,
+    WorkbookBlock,
+    WorkbookIR,
+    WorkbookSnapshot,
+    stable_id,
+)
+
+
+@dataclass
+class ChartSeries:
+    title: str | None = None
+    title_reference: str | None = None
+    categories: str | None = None
+    values: str | None = None
+    x_values: str | None = None
+    y_values: str | None = None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass
+class DrawingFact:
+    object_id: str
+    kind: str
+    anchor: str | None
+    title: str | None = None
+    chart_types: list[str] = field(default_factory=list)
+    series: list[ChartSeries] = field(default_factory=list)
+    axes: list[dict[str, Any]] = field(default_factory=list)
+    width: float | None = None
+    height: float | None = None
+    media_id: str | None = None
+    enhancement_status: str = "not_requested"
+    diagnostics: list[str] = field(default_factory=list)
+
+
+def _text(value: Any) -> str | None:
+    if isinstance(value, str):
+        return value
+    # DrawingML rich text can split a title over multiple runs/paragraphs.
+    rich = getattr(getattr(value, "tx", None), "rich", None)
+    paragraphs = getattr(rich, "p", [])
+    lines = []
+    for paragraph in paragraphs:
+        runs = [getattr(run, "t", "") for run in getattr(paragraph, "r", [])]
+        lines.append("".join(runs))
+    return "\n".join(lines).strip() or None
+
+
+def _formula(value: Any) -> str | None:
+    for field_name in ("numRef", "strRef", "multiLvlStrRef"):
+        reference = getattr(value, field_name, None)
+        if reference is not None:
+            return getattr(reference, "f", None)
+    return None
+
+
+def _source(formula: str, diagnostics: list[str], sheet_names: dict[str, str]) -> SourceRef | None:
+    # External, union and dynamic expressions remain explicit raw facts.
+    match = re.fullmatch(
+        r"(?:'((?:[^']|'')+)'|([^'!]+))!(\$?[A-Z]+\$?[1-9][0-9]*(?::\$?[A-Z]+\$?[1-9][0-9]*)?)",
+        formula,
+    )
+    if match and "[" not in formula:
+        from langparse.workbooks.lineage import _bounds
+
+        name = (match[1] or match[2]).replace("''", "'")
+        cell_range = match[3].replace("$", "")
+        try:
+            _bounds(cell_range)
+        except ValueError:
+            pass
+        else:
+            if name.casefold() in sheet_names:
+                return SourceRef(sheet_names[name.casefold()], cell_range)
+    diagnostics.append(f"unresolved_chart_reference: {formula}")
+    return None
+
+
+def extract_objects(sheet: Any) -> list[DrawingFact]:
+    from openpyxl.utils import get_column_letter
+
+    sheet_names = {name.casefold(): name for name in sheet.parent.sheetnames}
+    result = []
+    for kind, objects in (("chart", sheet._charts), ("image", sheet._images)):
+        for index, obj in enumerate(objects):
+            anchor = obj.anchor if isinstance(obj.anchor, str) else None
+            marker = getattr(obj.anchor, "_from", None)
+            if marker is not None:
+                anchor = f"{get_column_letter(marker.col + 1)}{marker.row + 1}"
+            fact = DrawingFact(stable_id("object", sheet.title, kind, str(index)), kind, anchor)
+            if anchor is None:
+                fact.diagnostics.append("unresolved_anchor")
+            if kind == "image":
+                fact.width, fact.height = obj.width, obj.height
+                fact.media_id = stable_id("media", sheet.title, str(index))
+            else:
+                fact.title = _text(obj.title)
+                for chart in getattr(obj, "_charts", [obj]):
+                    fact.chart_types.append(type(chart).__name__)
+                    for axis_name in ("x_axis", "y_axis", "z_axis"):
+                        axis = getattr(chart, axis_name, None)
+                        if axis is not None:
+                            fact.axes.append(
+                                {
+                                    "axis": axis_name,
+                                    "id": axis.axId,
+                                    "title": _text(axis.title),
+                                    "position": axis.axPos,
+                                }
+                            )
+                    for series in chart.series:
+                        tx = getattr(series, "tx", None)
+                        item = ChartSeries(
+                            title=getattr(tx, "v", None),
+                            title_reference=_formula(tx),
+                            categories=_formula(getattr(series, "cat", None)),
+                            values=_formula(getattr(series, "val", None)),
+                            x_values=_formula(getattr(series, "xVal", None)),
+                            y_values=_formula(getattr(series, "yVal", None)),
+                        )
+                        for expression in (
+                            item.title_reference,
+                            item.categories,
+                            item.values,
+                            item.x_values,
+                            item.y_values,
+                        ):
+                            if expression:
+                                ref = _source(expression, fact.diagnostics, sheet_names)
+                                if ref is not None:
+                                    item.source_refs.append(ref)
+                        fact.series.append(item)
+            result.append(fact)
+    return result
+
+
+def attach_objects(
+    snapshot: WorkbookSnapshot, ir: WorkbookIR, diagnostics: ParseDiagnostics
+) -> None:
+    """Add semantic objects after cell interpretation without claiming cell coverage."""
+    total = covered = 0
+    sheets = {sheet.name: sheet for sheet in ir.sheets}
+    for source in snapshot.sheets:
+        target = sheets[source.name]
+        for obj in source.objects:
+            total += 1
+            anchor = obj.get("anchor")
+            notes = list(obj.get("diagnostics", []))
+            try:
+                validate_object_source(snapshot, f"{source.name}!{anchor or ''}")
+            except (TypeError, ValueError):
+                notes.append("unresolved_anchor")
+                diagnostics.warnings.append(f"Object on {source.name}: unresolved_anchor")
+                diagnostics.status = "partial"
+                continue
+            refs = [SourceRef(source.name, anchor)]
+            for series in obj.get("series", []):
+                for raw in series.get("source_refs", []):
+                    if raw["sheet_name"] in sheets:
+                        ref = SourceRef(**raw)
+                        if ref not in refs:
+                            refs.append(ref)
+                    else:
+                        notes.append(f"missing_chart_sheet: {raw['sheet_name']}")
+            if notes:
+                diagnostics.status = "partial"
+                diagnostics.warnings.extend(f"Object on {source.name}: {note}" for note in notes)
+            target.blocks.append(
+                WorkbookBlock(
+                    block_id=obj.get("object_id")
+                    or stable_id("object", source.name, anchor, str(total)),
+                    kind=obj["kind"],
+                    source_refs=refs,
+                    metadata={"anchor": anchor, "object": obj},
+                    diagnostics=[{"code": note} for note in notes],
+                )
+            )
+            covered += 1
+            kind = obj["kind"]
+            diagnostics.block_count_by_kind[kind] = diagnostics.block_count_by_kind.get(kind, 0) + 1
+    diagnostics.object_coverage_ratio = covered / total if total else 1.0
+    if snapshot.metadata.get("drawing_read_errors"):
+        diagnostics.status = "partial"
+        diagnostics.object_coverage_ratio = None
+        diagnostics.unsupported_features.extend(snapshot.metadata["drawing_read_errors"])
+
+
+def render_object(block: WorkbookBlock) -> str:
+    obj = block.metadata["object"]
+    source = ", ".join(ref.key for ref in block.source_refs)
+    title = obj.get("title") or obj["kind"].capitalize()
+    lines = [f"<!-- source_ranges: {source} -->", f"**{title}** ({obj['kind']})"]
+    for series in obj.get("series", []):
+        references = [
+            series[key]
+            for key in ("categories", "values", "x_values", "y_values")
+            if series.get(key)
+        ]
+        lines.append("- " + (series.get("title") or "Series") + ": " + ", ".join(references))
+    if obj["kind"] == "image":
+        lines.append(
+            f"Image {obj.get('media_id')}; {obj.get('width')} × {obj.get('height')}; OCR/VLM not requested."
+        )
+    return "\n\n".join(lines)
+
+
+def validate_object_source(snapshot: WorkbookSnapshot | None, source: str) -> None:
+    """Drawing anchors can be outside used cells, but must be valid Excel coordinates."""
+    from openpyxl.utils.cell import range_boundaries
+
+    sheet_name, cell_range = source.rsplit("!", 1)
+    if snapshot is None or not any(sheet.name == sheet_name for sheet in snapshot.sheets):
+        raise ValueError(f"Object source references unknown sheet: {sheet_name}")
+    try:
+        left, top, right, bottom = range_boundaries(cell_range)
+        if not (1 <= left <= right <= 16384 and 1 <= top <= bottom <= 1048576):
+            raise ValueError("out of bounds")
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"Invalid object source range: {source}") from exc

langparse/workbooks/quality/__init__.py

@@ -0,0 +1,23 @@
+"""Whole-workbook quality evaluation primitives."""
+
+from .evaluator import (
+    WORKBOOK_QUALITY_METRIC_SCHEMA_VERSION,
+    WorkbookQualityMetrics,
+    evaluate_workbook_result,
+)
+from .schema import (
+    WorkbookQualityGate,
+    WorkbookQualityManifest,
+    WorkbookQualityManifestError,
+    load_workbook_quality_manifest,
+)
+
+__all__ = [
+    "WorkbookQualityManifest",
+    "WorkbookQualityManifestError",
+    "WorkbookQualityMetrics",
+    "WorkbookQualityGate",
+    "WORKBOOK_QUALITY_METRIC_SCHEMA_VERSION",
+    "evaluate_workbook_result",
+    "load_workbook_quality_manifest",
+]

langparse/workbooks/quality/bundle.py

@@ -0,0 +1,53 @@
+"""Check exported workbook consumption contracts against the same frozen truth."""
+
+from langparse.workbooks.bundle import WorkbookBundle
+
+
+def evaluate_bundle_contract(expectation, parsed) -> dict[str, float]:
+    bundle = WorkbookBundle.from_result(parsed, max_rows=None)
+    payload = bundle.to_dict()
+    refs: set[str] = set()
+
+    def collect(value):
+        if isinstance(value, str):
+            refs.add(value)
+        elif isinstance(value, list):
+            for item in value:
+                collect(item)
+
+    def visit(value):
+        if isinstance(value, dict):
+            for key, item in value.items():
+                if key in {"source_ref", "dependent", "target"} and isinstance(item, str):
+                    refs.add(item)
+                elif key.endswith("source_refs"):
+                    collect(item)
+                else:
+                    visit(item)
+        elif isinstance(value, list):
+            for item in value:
+                visit(item)
+
+    visit(payload)
+    expected_refs = set(expectation.required_source_refs)
+    expected_blocks = {
+        (sheet.name, block.kind, block.source_range)
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+    }
+    actual_blocks = {
+        (block["sheet"], block["kind"], block["source_refs"][0].rsplit("!", 1)[1])
+        for block in payload["structures"]["blocks"]
+        if block["source_refs"]
+    }
+    encoded = bundle.to_json()
+    stable = WorkbookBundle.from_json(encoded).to_json() == encoded
+    return {
+        "bundle_source_ref_completeness": len(expected_refs & refs) / len(expected_refs)
+        if expected_refs
+        else 1.0,
+        "bundle_structure_recall": len(expected_blocks & actual_blocks) / len(expected_blocks)
+        if expected_blocks
+        else 1.0,
+        "bundle_roundtrip_stability": float(stable),
+    }

langparse/workbooks/quality/evaluator.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterable
+from dataclasses import dataclass, fields, is_dataclass
+from typing import Any
+
+from langparse.types import ParsedDocumentResult
+from langparse.workbooks.quality.bundle import evaluate_bundle_contract
+from langparse.workbooks.quality.facts import evaluate_fact_truth
+from langparse.workbooks.quality.schema import WorkbookExpectation
+from langparse.workbooks.types import SourceRef, WorkbookIR
+
+WORKBOOK_QUALITY_METRIC_SCHEMA_VERSION = 2
+
+
+@dataclass(frozen=True)
+class WorkbookQualityMetrics:
+    block_precision: float
+    block_recall: float
+    header_path_accuracy: float | None
+    row_role_f1: float | None
+    form_field_exact_match: float | None
+    matrix_axis_accuracy: float | None
+    continuation_precision: float | None
+    continuation_recall: float | None
+    source_ref_completeness: float
+    source_ref_validity_ratio: float
+    cell_coverage_ratio: float
+    fallback_rate: float
+    object_fact_precision: float | None
+    object_fact_recall: float | None
+    object_semantic_recall: float | None
+    formula_accuracy: float | None = None
+    named_range_accuracy: float | None = None
+    excel_table_accuracy: float | None = None
+    visibility_accuracy: float | None = None
+    dependency_precision: float | None = None
+    dependency_recall: float | None = None
+    bundle_source_ref_completeness: float = 0.0
+    bundle_structure_recall: float = 0.0
+    bundle_roundtrip_stability: float = 0.0
+
+
+def evaluate_workbook_result(
+    expectation: WorkbookExpectation,
+    parsed: ParsedDocumentResult,
+) -> WorkbookQualityMetrics:
+    if not isinstance(parsed.structure, WorkbookIR):
+        raise TypeError("Workbook quality evaluation requires WorkbookIR")
+    workbook = parsed.structure
+
+    expected_blocks = [
+        (sheet.name, block.source_range, block.kind)
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+    ]
+    observed_blocks = [
+        (sheet.name, _block_range(block), block.kind)
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.kind not in {"chart", "image"}
+    ]
+    block_precision, block_recall = _precision_recall(expected_blocks, observed_blocks)
+
+    expected_headers = [
+        (sheet.name, block.source_range, header.coordinate, header.path)
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+        for header in block.headers
+    ]
+    observed_headers = [
+        (sheet.name, _block_range(block), column.coordinate, tuple(column.path))
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.logical_table is not None
+        for column in block.logical_table.columns
+    ]
+
+    expected_rows = [
+        (sheet.name, row.source_range, row.role)
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+        for row in block.rows
+    ]
+    observed_rows = [
+        (sheet.name, row.source_ref.range, row.role)
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.logical_table is not None
+        for row in block.logical_table.rows
+    ]
+
+    expected_fields = [
+        (sheet.name, block.source_range, label, _stable_value(value))
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+        for label, value in block.form_fields
+    ]
+    observed_fields = [
+        (sheet.name, _block_range(block), field.label, _stable_value(field.value))
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.form is not None
+        for field in block.form.fields
+    ]
+
+    expected_axes = [
+        (sheet.name, block.source_range, axis, value)
+        for sheet in expectation.sheets
+        for block in sheet.blocks
+        for axis, values in (
+            ("row", block.matrix_axes.rows),
+            ("column", block.matrix_axes.columns),
+        )
+        for value in values
+    ]
+    observed_axes = [
+        (sheet.name, _block_range(block), axis, header.value)
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.matrix is not None
+        for axis, headers in (
+            ("row", block.matrix.row_headers),
+            ("column", block.matrix.column_headers),
+        )
+        for header in headers
+    ]
+
+    expected_continuations = list(expectation.continuations)
+    observed_continuations = [
+        tuple(ref.key for ref in continuation.source_refs)
+        for continuation in workbook.table_continuations
+    ]
+    continuation_precision, continuation_recall = _optional_precision_recall(
+        expected_continuations,
+        observed_continuations,
+    )
+
+    available_refs = _collect_source_refs(workbook)
+    required_refs = set(expectation.required_source_refs)
+    source_ref_completeness = (
+        len(required_refs & available_refs) / len(required_refs) if required_refs else 1.0
+    )
+
+    expected_objects = [(item.sheet_name, item.kind, item.anchor) for item in expectation.objects]
+    observed_object_facts = [
+        (sheet.name, str(item.get("kind")), str(item.get("anchor")))
+        for sheet in (workbook.snapshot.sheets if workbook.snapshot is not None else [])
+        for item in sheet.objects
+        if item.get("kind") is not None and item.get("anchor") is not None
+    ]
+    observed_semantic_objects = [
+        (sheet.name, block.kind, str(block.metadata.get("anchor")))
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+        if block.kind in {"chart", "image"} and block.metadata.get("anchor") is not None
+    ]
+    object_fact_precision, object_fact_recall = _optional_precision_recall(
+        expected_objects,
+        observed_object_facts,
+    )
+    _, object_semantic_recall = _optional_precision_recall(
+        expected_objects,
+        observed_semantic_objects,
+    )
+
+    block_count = sum(
+        block.kind not in {"chart", "image"} for sheet in workbook.sheets for block in sheet.blocks
+    )
+    fallback_count = sum(
+        block.kind == "unclassified" or not block.source_refs
+        for sheet in workbook.sheets
+        for block in sheet.blocks
+    )
+    diagnostics = parsed.diagnostics
+    return WorkbookQualityMetrics(
+        block_precision=block_precision,
+        block_recall=block_recall,
+        header_path_accuracy=_set_accuracy(expected_headers, observed_headers),
+        row_role_f1=_set_f1(expected_rows, observed_rows),
+        form_field_exact_match=_set_accuracy(expected_fields, observed_fields),
+        matrix_axis_accuracy=_set_accuracy(expected_axes, observed_axes),
+        continuation_precision=continuation_precision,
+        continuation_recall=continuation_recall,
+        source_ref_completeness=source_ref_completeness,
+        source_ref_validity_ratio=(
+            diagnostics.source_ref_validity_ratio if diagnostics is not None else 0.0
+        ),
+        cell_coverage_ratio=diagnostics.coverage_ratio if diagnostics is not None else 0.0,
+        fallback_rate=fallback_count / block_count if block_count else 0.0,
+        object_fact_precision=object_fact_precision,
+        object_fact_recall=object_fact_recall,
+        object_semantic_recall=object_semantic_recall,
+        **evaluate_fact_truth(expectation.facts, workbook),
+        **evaluate_bundle_contract(expectation, parsed),
+    )
+
+
+def _precision_recall(expected: Iterable[Any], observed: Iterable[Any]) -> tuple[float, float]:
+    expected_counts = Counter(expected)
+    observed_counts = Counter(observed)
+    matched = sum((expected_counts & observed_counts).values())
+    expected_total = expected_counts.total()
+    observed_total = observed_counts.total()
+    precision = matched / observed_total if observed_total else float(not expected_total)
+    recall = matched / expected_total if expected_total else float(not observed_total)
+    return precision, recall
+
+
+def _optional_precision_recall(
+    expected: Iterable[Any], observed: Iterable[Any]
+) -> tuple[float | None, float | None]:
+    expected = tuple(expected)
+    observed = tuple(observed)
+    if not expected and not observed:
+        return None, None
+    return _precision_recall(expected, observed)
+
+
+def _set_accuracy(expected: Iterable[Any], observed: Iterable[Any]) -> float | None:
+    expected_counts = Counter(expected)
+    observed_counts = Counter(observed)
+    if not expected_counts and not observed_counts:
+        return None
+    return sum((expected_counts & observed_counts).values()) / max(
+        expected_counts.total(), observed_counts.total()
+    )
+
+
+def _set_f1(expected: Iterable[Any], observed: Iterable[Any]) -> float | None:
+    expected = tuple(expected)
+    observed = tuple(observed)
+    if not expected and not observed:
+        return None
+    precision, recall = _precision_recall(expected, observed)
+    return 2 * precision * recall / (precision + recall) if precision + recall else 0.0
+
+
+def _block_range(block: Any) -> str:
+    return block.source_refs[0].range if block.source_refs else "<missing-source-ref>"
+
+
+def _stable_value(value: Any) -> str:
+    return repr(value)
+
+
+def _collect_source_refs(value: Any) -> set[str]:
+    refs: set[str] = set()
+
+    def visit(item: Any) -> None:
+        if isinstance(item, SourceRef):
+            refs.add(item.key)
+        elif is_dataclass(item):
+            for item_field in fields(item):
+                if item_field.name != "snapshot":
+                    visit(getattr(item, item_field.name))
+        elif isinstance(item, dict):
+            for nested in item.values():
+                visit(nested)
+        elif isinstance(item, (list, tuple, set)):
+            for nested in item:
+                visit(nested)
+
+    visit(value)
+    return refs