rag-wright 0.1.0__py3-none-any.whl

rag_wright/spans/symbolic_validation.py

@@ -0,0 +1,131 @@
+"""JUDGE-ONTOLOGY-1 (ADR-0040): the symbolic ontology-validation gate -- layer 2 of the
+neuro-symbolic extraction-fidelity cascade.
+
+Where the lexical grounding judge (`property_grounding.reground`, ADR-0028) checks whether a value's
+surface cue appears in the text, this gate checks whether the ASSERTED DIMENSION is even APPLICABLE to
+the clause's FUNCTION -- a TYPE constraint the lexical judge structurally cannot see. Example: granite
+emits `nonsolicit_target=employees` on an Anti-Assignment clause. The value is a valid nonsolicit_target
+and its cue may appear in the text, so the lexical judge passes it; but `nonsolicit_target` does not
+belong to Anti-Assignment at all -- a type error, caught here.
+
+The applicability map (`FUNCTION_APPLICABLE_DIMS`) is the NEW ontology content ADR-0040 calls for: each
+clause FUNCTION permits a set of property DIMENSIONS. It is compiled to SHACL `sh:closed` NodeShapes (one
+per function, listing the applicable dimension paths) and validated with `pyshacl` -- the symbolic half of
+neuro-symbolic. A non-applicable assertion is downgraded to AMBIGUOUS (kept but flagged), exactly like
+`reground`, so the shared property-value nodes stay clean and soft-boost down-weights it.
+
+The gate also enforces CARDINALITY (JUDGE-ONTOLOGY-2): a SCALAR dimension asserted with two conflicting
+values (e.g. granite hedging `cap_basis` = both `fixed_fee` and `multiple_of_fees`) violates `sh:maxCount 1`
+and both values are downgraded -- the real intra-clause "contradiction" class, since the dimensions are
+orthogonal facets and same-dimension conflict is where extraction actually contradicts itself. The 3
+multi-valued dimensions (`_LIST_ENUM_DIMS`: carve_out / covered_subject / damage_type) are left unbounded.
+
+The gate also enforces DEONTIC consistency (JUDGE-ONTOLOGY-3, ODRL): a consent-regime dimension carries a
+permission↔restriction polarity in its VALUES (`free`/`unrestricted` = "may freely"; `consent_required` =
+restricted). A function whose defining purpose is to RESTRICT (Anti-Assignment / Non-Transferable License /
+Change Of Control) contradicts a permission-polarity value -- the observed `assignment_consent=free` on a
+"shall not assign" clause. The clause's rule type is DERIVED from its function (reliable, non-circular; not
+parsed from the text), and the check is a `sh:in` (allowed = vocab minus the permission-polarity values) on
+the scoped property shape.
+
+Deliberately NOT enforced here (JUDGE-ONTOLOGY-2 scoping): value-in-vocabulary (`sh:in` over the full vocab)
+is already enforced at the Pydantic contract boundary (`property.PropertyAssertion._value_in_vocab_or_ambiguous`),
+so a whole-vocab SHACL shape would duplicate a working validator; and cross-DIMENSION `sh:sparql` rules are
+omitted because this schema's dimensions are orthogonal facets with no hard intra-clause cross-dimension
+contradiction (deferred to a post-MVP / beta-customer iteration on real production data).
+
+Deterministic, no model, no network. Downgrade is confidence-independent (a type/cardinality/deontic error is
+wrong whether EXTRACTED or INFERRED); an already-AMBIGUOUS assertion is left as is. A function NOT in the map
+is PERMISSIVE (unvalidated) -- coverage is expanded deliberately, never by guessing a closed set we are unsure
+of. All three checks reuse one record->RDF->pyshacl harness.
+"""
+
+from __future__ import annotations
+
+from rdflib import Graph, Literal, Namespace, URIRef
+from rdflib.namespace import RDF, SH
+
+from rag_wright.contracts.property import (
+    ClausePropertyRecord,
+    PropertyAssertion,
+    PropertyDimension,
+)
+from rag_wright.contracts.provenance import ConfidenceTag
+
+_CBR = Namespace("https://ragwright.local/ontology/contract-bridge#")
+
+
+def _function_class(function: str) -> URIRef:
+    """A stable CBR class IRI for a function label (RDF has no spaces; encode deterministically)."""
+    return _CBR[f"Function_{function.replace(' ', '_')}"]
+
+
+def _dim_property(dimension: PropertyDimension) -> URIRef:
+    """The CBR predicate IRI carrying a dimension's asserted value on a clause node."""
+    return _CBR[f"dim_{dimension.value}"]
+
+
+def _shapes_graph() -> Graph:
+    """ADR-0066 P2: the SHACL shapes come FROM contract_bridge.ttl (the source of truth) -- pyshacl reads the
+    persisted sh:NodeShapes directly; no Python-built shapes. The ttl non-SHACL triples are ignored by pyshacl.
+    """
+    from rag_wright.ontology.loader import load_shapes_graph
+
+    return load_shapes_graph()
+
+
+def _record_to_rdf(record: ClausePropertyRecord) -> Graph:
+    """Serialize a record's function + assertions to a tiny data graph: the clause typed by its function,
+    with one triple per assertion (dimension predicate -> value literal)."""
+    g = Graph()
+    clause = URIRef("urn:clause:" + record.clause_id)
+    g.add((clause, RDF.type, _function_class(record.function)))
+    for a in record.assertions:
+        g.add((clause, _dim_property(a.dimension), Literal(a.value)))
+    return g
+
+
+def flagged_dimensions(record: ClausePropertyRecord) -> set[PropertyDimension]:
+    """The dimensions to downgrade: ONLY the FUNCTION-INDEPENDENT contradiction check -- a scalar dimension
+    asserted with more than one value (`sh:maxCount 1`). The FUNCTION-DEPENDENT checks are DELIBERATELY IGNORED
+    (ADR-0082): clause-function classification is not accurate enough to be load-bearing (~0.5 top-1; memory
+    `function-classification-not-load-bearing`), so `sh:closed` (dimension-not-applicable-to-function) and `sh:in`
+    (deontic polarity on a restrictive function) would downgrade CORRECT cross-cutting extractions based on an
+    unreliable (and often narrow) function map. Function is a KG tag / query-time soft signal, never an ingest
+    gate. Empty if the record conforms or the function is unmodeled."""
+    if not record.assertions:
+        return set()
+    from pyshacl import validate
+
+    conforms, results_graph, _ = validate(
+        _record_to_rdf(record), shacl_graph=_shapes_graph(), inference="none", advanced=False
+    )
+    if conforms:
+        return set()
+    flagged: set[PropertyDimension] = set()
+    _prefix = str(_CBR) + "dim_"
+    for result in results_graph.subjects(RDF.type, SH.ValidationResult):
+        # keep ONLY the contradiction (maxCount) violations; drop function-dependent closed/in violations
+        if results_graph.value(result, SH.sourceConstraintComponent) != SH.MaxCountConstraintComponent:
+            continue
+        path = results_graph.value(result, SH.resultPath)
+        if path is not None and str(path).startswith(_prefix):
+            flagged.add(PropertyDimension(str(path)[len(_prefix):]))
+    return flagged
+
+
+def symbolic_validate(record: ClausePropertyRecord) -> ClausePropertyRecord:
+    """Quality gate (ADR-0040 layer 2): downgrade every assertion whose dimension violates a shape -- not
+    applicable to the clause's function, or a scalar dimension asserted with conflicting values -- to
+    AMBIGUOUS (kept but flagged, model-agnostic, confidence-independent). A no-op when the function is
+    unmodeled or every dimension is valid -- mirrors `property_grounding.reground`."""
+    bad = flagged_dimensions(record)
+    if not bad:
+        return record
+    new: list[PropertyAssertion] = [
+        a.model_copy(update={"confidence": ConfidenceTag.AMBIGUOUS})
+        if a.dimension in bad and a.confidence != ConfidenceTag.AMBIGUOUS
+        else a
+        for a in record.assertions
+    ]
+    return record.model_copy(update={"assertions": new})

rag_wright/spans/tag_clause_extractor.py

@@ -0,0 +1,182 @@
+"""TAGPARSE-INGEST-1b: FUNCTION-INDEPENDENT clause property extraction via client-side tag-parse.
+
+The docling-graph path asks a model to fill the whole 35-field `Clause` template in one server-side-JSON call --
+which granite-4.2 flattens/fails (~5/7) on real clauses (ADR-0079). Function-SCOPED extraction was ruled out
+because clause-function classification is not accurate enough to gate on (~0.5 top-1; memory
+`function-classification-not-load-bearing`). So we decompose the schema WITHOUT the function: the 35 fields are
+split into 7 cohesive THEMATIC groups, each a small tag-parse pass over the SAME `Clause` schema (via
+`build_tag_structured(..., fields=group)`), run concurrently and merged into one `Clause`. Small focused schemas
+are where tag-parse already wins (parties 5/5), and `Clause`'s own validators normalize on the final construct.
+
+`CLAUSE_GROUPS` is domain knowledge (which properties belong together); it is a candidate for ontology migration
+(ADR-0066) but lives here for now, like `property_extractor.FUNCTION_DIMENSIONS`. Every non-id `Clause` field is
+in exactly one group (a coverage test enforces this).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from rag_wright.models.profiles import DEFAULT_GENERAL
+from rag_wright.models.tag_structured import _classify, build_tag_structured
+from rag_wright.ontology.clause_template import Clause
+
+# The 7 thematic groups (5a consents/control + 5b restrictions/duties per the design). document_reference is the
+# clause's root id, filled separately (from context / source stem), never asked of the model here.
+CLAUSE_GROUPS: dict[str, tuple[str, ...]] = {
+    "identity_scope": ("clause_type", "covers", "covers_party_scope", "has_mutuality",
+                       "has_asymmetry", "has_favorability"),
+    "liability_damages": ("caps", "has_claim_scope", "prohibits_damage", "ld_trigger"),
+    "temporal_termination": ("bounded_by", "has_renewal", "has_termination_right", "condition_type"),
+    "ip_licensing": ("has_ip_ownership", "has_exclusivity_type", "has_right_of_first_type",
+                     "has_mfn_scope", "royalty_basis"),
+    "consents_control": ("has_assignment_consent", "has_coc_consent", "has_escrow_release_trigger"),
+    "governing_law_dispute": ("governed_by", "dispute_method"),  # split out of the grab-bag: a focused pass so
+                                                                 # jurisdiction isn't buried among 8 other fields
+    "restrictions_duties": ("requires_duty", "has_restriction_scope", "prohibits_solicit", "has_warranty_scope",
+                            "audit_frequency", "commitment_quantum", "collateral_type"),
+    "exceptions": ("excepts", "confidentiality_exception", "force_majeure_event"),
+}
+
+_GROUP_PROMPT = (
+    "You are extracting the typed properties of ONE contract clause. Extract ONLY the properties below that are "
+    "EXPLICITLY stated in the clause; omit any that are not present -- do NOT guess or invent a value. Read each "
+    "value verbatim from the clause.\n\nCLAUSE:\n{text}"
+)
+
+# NOTE (issue 0036): TWO cost-cutting ideas were tried here and BOTH measured a ~15-18% property-recall loss on
+# Qwen (the current default), concentrated in `excepts` (carve-outs) -- so neither was adopted. (1) A coarse
+# "aspect gate" that pruned groups per clause (removed entirely). (2) Batching two clauses per group call (recall
+# 0.818 at samples=1, 0.844 at samples=4 -- still a real regression, not variance). Splitting the model's attention
+# across clauses, or pruning groups, both under-extract the hard cross-cutting fields. So every group always runs,
+# one clause per call; the only recall-preserving cost lever is `is_extractable_span` (fewer spans reach here).
+
+
+import re as _re
+
+_MAX_VALUE_CHARS = 240  # a clause PROPERTY value is short ("12_months", "Delaware"); longer = leaked prose
+_TAG_LIKE = _re.compile(r"<[A-Za-z_][\w-]*>")  # a value must never contain XML tags (model reasoning/prompt leak)
+
+
+def _sane(value: Any) -> Any:
+    """Drop a garbage string value (a leaked chain-of-thought / prompt echo): too long, or containing XML tags.
+    Non-string values pass through (enums/sub-models/lists can't carry this leak). A dropped value -> None so the
+    field falls back to its default (never store reasoning text as a clause property)."""
+    if isinstance(value, str) and (len(value) > _MAX_VALUE_CHARS or _TAG_LIKE.search(value)):
+        return None
+    return value
+
+
+def _uninformative(v: Any) -> bool:
+    """A scalar value carrying no information: None/empty, or an enum OTHER escape (dropped downstream anyway)."""
+    if v is None:
+        return True
+    s = str(getattr(v, "value", v)).strip()
+    return s == "" or s in ("Other", "OTHER") or "Unknown" in s
+
+
+def _item_key(item: Any) -> Any:
+    """A hashable identity for a list item so the union can dedup: an enum by its value, a sub-model by its dump."""
+    if hasattr(item, "model_dump"):
+        return tuple(sorted((k, str(v)) for k, v in item.model_dump().items()))
+    return getattr(item, "value", item)
+
+
+def _union_lists(lists: list[Any]) -> list[Any]:
+    """Order-preserving UNION of a list-valued field across samples -- the fix for granite's list under-enumeration
+    (each sample may emit a different subset; the union recovers the full set)."""
+    out: list[Any] = []
+    seen: set[Any] = set()
+    for lst in lists:
+        for item in (lst or []):
+            k = _item_key(item)
+            if k not in seen:
+                seen.add(k)
+                out.append(item)
+    return out
+
+
+def _combine_group(samples: list[Clause | None], fields: tuple[str, ...]) -> dict[str, Any]:
+    """Combine a group's N sampled passes into one field dict: LIST-valued fields are UNIONed across samples
+    (list-completeness), scalar/nested fields take the first informative (non-OTHER) sane value. A single sample
+    (N=1) reduces to the prior behavior."""
+    valid = [r for r in samples if r is not None]
+    out: dict[str, Any] = {}
+    for f in fields:
+        kind, _sub, _hint = _classify(Clause.model_fields[f].annotation)
+        vals = [getattr(r, f) for r in valid]
+        if kind in ("list_scalar", "nested_list"):
+            merged = _union_lists(vals)
+            if merged:
+                out[f] = merged
+        else:
+            sane = [_sane(v) for v in vals]
+            pick = next((v for v in sane if v is not None and not _uninformative(v)),
+                        next((v for v in sane if v is not None), None))
+            if pick is not None:
+                out[f] = pick
+    return out
+
+
+def _group_has_list(fields: tuple[str, ...]) -> bool:
+    """True if the group has any LIST-valued field (list_scalar / nested_list) -- the fields where under-
+    enumeration bites, and the only ones a cross-model union is worth paying a second model for."""
+    return any(_classify(Clause.model_fields[f].annotation)[0] in ("list_scalar", "nested_list") for f in fields)
+
+
+async def atag_extract_clause(text: str, model_id: str, *, document_reference: str = "",
+                              temperature: float = 0.0, samples: int | None = None,
+                              list_model: str | None = None) -> Clause:
+    """Extract a clause's typed properties as ONE `Clause`, function-independently: EVERY thematic tag-parse pass
+    over the `Clause` schema, merged. Each pass degrades on its own (build_tag_structured re-asks then
+    omits-to-default); a failing pass leaves its group at defaults (never fails the whole clause). (The former
+    aspect gate that pruned groups was removed in issue 0036 -- it measured a ~18% property-recall loss on Qwen.)
+
+    `samples` (env `RAG_INGEST_CLAUSE_SAMPLES`, default 1) runs each group N times and UNIONs the LIST-valued
+    fields across samples -- the inference-time fix for granite's list under-enumeration.
+
+    `list_model` (env `RAG_INGEST_LIST_MODEL`, DEFAULT gemma) enables a CROSS-MODEL union: for LIST-bearing groups
+    ONLY, also run a second (stronger, complementary) model and union its list values with the main model's.
+    granite and gemma under-enumerate DIFFERENT items, so their union is more complete than either alone (it fixes
+    the CONSISTENT misses same-model multi-sample can't); scoping the second model to list-bearing groups keeps its
+    cost off the ~half of groups with no list field. Scalars prefer the main model (its results are unioned first).
+    ON by default; disable with `RAG_INGEST_LIST_MODEL=off`."""
+    n = samples if samples is not None else max(1, int(os.environ.get("RAG_INGEST_CLAUSE_SAMPLES", "1")))
+    # cross-model list model: explicit ARGUMENT wins, else env, else the profile's general model (gemma). Any of
+    # them may be "off"/"none"/"" to disable -- so the default-on model is configurable, never a buried hardcode.
+    _raw = list_model if list_model is not None else os.environ.get("RAG_INGEST_LIST_MODEL", DEFAULT_GENERAL)
+    lm = None if not _raw or str(_raw).strip().lower() in ("none", "off") else str(_raw).strip()
+    stemp = temperature if n == 1 else max(temperature, 0.5)  # diversity across samples for the union to help
+
+    async def _pass(fields: tuple[str, ...], model: str) -> Clause | None:
+        try:
+            return await build_tag_structured(
+                model, Clause, fields=set(fields), temperature=stemp, label="clause-group",
+            ).ainvoke(_GROUP_PROMPT.format(text=text))
+        except Exception:  # noqa: BLE001 - a persistently-failing pass degrades to defaults, not a hard error
+            return None
+
+    async def _group(fields: tuple[str, ...]) -> dict[str, Any]:
+        models = [model_id]  # main model first so its scalar values win 'first informative'
+        if lm and lm != model_id and _group_has_list(fields):
+            models.append(lm)  # cross-model union, LIST-bearing groups only (cost-scoped)
+        runs = [r for m in models for r in await asyncio.gather(*[_pass(fields, m) for _ in range(n)])]
+        return _combine_group(runs, fields)
+
+    dicts = await asyncio.gather(*[_group(f) for f in CLAUSE_GROUPS.values()])
+    merged: dict[str, Any] = {}
+    for d in dicts:
+        merged.update(d)
+    merged["document_reference"] = document_reference or None
+    return Clause(**merged)
+
+
+def tag_extract_clause(text: str, model_id: str, *, document_reference: str = "",
+                       temperature: float = 0.0, samples: int | None = None,
+                       list_model: str | None = None) -> Clause:
+    """Sync wrapper over `atag_extract_clause` (parity with the docling-graph `extract_clause`)."""
+    return asyncio.run(atag_extract_clause(
+        text, model_id, document_reference=document_reference, temperature=temperature,
+        samples=samples, list_model=list_model))

rag_wright/store/__init__.py

@@ -0,0 +1,6 @@
+"""The single ArcadeDB store behind the query-skill seam (FR-S.1, FR-S.5).
+
+Holds both the hybrid retrieval index and the knowledge graph in one multi-model database.
+Reached only through the query-skill interface so the store implementation is swappable
+(Graphify for a prototype graph, and the eval-gated LanceDB fallback for the retrieval leg).
+"""