rag-wright 0.1.0__py3-none-any.whl

rag_wright/ontology/codegen.py

@@ -0,0 +1,84 @@
+"""ADR-0066 Phase 1: render the GENERATED Python contract vocabulary FROM the ontology `.ttl`.
+
+The single place the ttl -> Python generation lives (imported by scripts/generate_contract_python.py to WRITE the
+file, and by tests/ontology/test_generated_vocab_in_sync.py to ASSERT the committed file equals a fresh render).
+The ttl is the source of truth (ADR-0066); the generated file is regenerable and CI-diff-enforced, never hand-
+edited -- staleness is impossible by construction, not solved by moving truth back into code (Rule 2)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rag_wright.ontology.loader import load_contract_ontology, load_template_fields
+
+VOCAB_MODULE_PATH = Path(__file__).with_name("_generated_vocab.py")
+TEMPLATE_META_MODULE_PATH = Path(__file__).with_name("_generated_template_meta.py")
+
+_HEADER = '''"""GENERATED FROM contract_bridge.ttl by scripts/generate_contract_python.py -- DO NOT EDIT BY HAND.
+
+ADR-0066: the ontology `.ttl` is the single source of truth. To change the closed vocabulary, edit the ttl and
+re-run the generator; a hand-edit here (or a stale regeneration) is caught by
+tests/ontology/test_generated_vocab_in_sync.py."""
+
+from __future__ import annotations
+
+'''
+
+
+def render_vocab_module() -> str:
+    """The exact text the generated vocab module must contain (deterministic: sorted dimensions + values)."""
+    view = load_contract_ontology()
+    lines = [_HEADER, "VOCAB: dict[str, frozenset[str]] = {"]
+    for dim in sorted(view.closed_vocab):
+        values = ", ".join(repr(v) for v in sorted(view.closed_vocab[dim]))
+        lines.append(f"    {dim!r}: frozenset({{{values}}}),")
+    lines.append("}")
+    # issue 0037: ingest value synonyms (skos:broader surface -> canonical member), keyed by dimension then
+    # normalized surface term. Used by clause_kg_extractor to canonicalize an out-of-vocab extracted value.
+    lines.append("")
+    lines.append("VALUE_SYNONYMS: dict[str, dict[str, str]] = {")
+    for dim in sorted(view.value_synonyms):
+        pairs = ", ".join(f"{k!r}: {v!r}" for k, v in sorted(view.value_synonyms[dim].items()))
+        lines.append(f"    {dim!r}: {{{pairs}}},")
+    lines.append("}")
+    # DD-7: the entity-graph taxonomy -- entity node types + entity-to-entity relationship types. Named constants
+    # (identifier = UPPER_SNAKE of the label) for ergonomic use, plus the two frozensets; `contract_taxonomy.py`
+    # re-exports these so no engine/domain code hardcodes the values (the ttl is the source of truth).
+    lines.append("")
+    for label in sorted(view.entity_types | view.relationship_types):
+        lines.append(f"{label.upper().replace(' ', '_')} = {label!r}")
+    ent = ", ".join(repr(v) for v in sorted(view.entity_types))
+    rel = ", ".join(repr(v) for v in sorted(view.relationship_types))
+    lines.append("")
+    lines.append(f"ENTITY_TYPES: frozenset[str] = frozenset({{{ent}}})")
+    lines.append(f"RELATIONSHIP_TYPES: frozenset[str] = frozenset({{{rel}}})")
+    return "\n".join(lines) + "\n"
+
+
+_META_HEADER = '''"""GENERATED FROM contract_bridge.ttl by scripts/generate_contract_python.py -- DO NOT EDIT BY HAND.
+
+ADR-0066 P1b-2 (Rule 3): the extraction template's KNOWLEDGE -- each field's LOOK-FOR description and examples,
+generated from the ttl. `clause_template.py` CONSUMES this (via `_d()` / `_ex()`); the mechanism (validators,
+normalizers, __str__, config) stays clean hand-code there. To change a description/example, edit the ttl and
+re-run the generator; a hand-edit here is caught by tests/ontology/test_generated_template_meta_in_sync.py."""
+
+from __future__ import annotations
+
+'''
+
+
+def render_template_meta_module() -> str:
+    """The generated template-knowledge module: `DESCRIPTIONS` + `EXAMPLES` keyed by `<Model>.<field>` (in the
+    template's declared field order). Empty descriptions are omitted (the accessor defaults to '')."""
+    specs = load_template_fields()
+    lines = [_META_HEADER, "DESCRIPTIONS: dict[str, str] = {"]
+    for s in specs:
+        if s.definition:
+            lines.append(f"    {f'{s.model}.{s.name}'!r}: {s.definition!r},")
+    lines.append("}\n")
+    lines.append("EXAMPLES: dict[str, tuple[str, ...]] = {")
+    for s in specs:
+        if s.examples:
+            lines.append(f"    {f'{s.model}.{s.name}'!r}: {tuple(s.examples)!r},")
+    lines.append("}")
+    return "\n".join(lines) + "\n"

rag_wright/ontology/compliance_bridge.ttl

@@ -0,0 +1,186 @@
+# compliance_bridge.ttl — the compliance-module ontology (CC-1, roadmap §13.1).
+#
+# A small AUTHORED sibling to contract_bridge.ttl (NOT an edit of it — different domain, kept separate).
+# Reuses the public deontic backbone (ODRL permission/prohibition/duty; LKIF obligation/permission/prohibition
+# family) + PROV-O provenance + the same odrl:Constraint typed-dimension pattern the contract bridge uses for
+# applicability. The thin advertising vocab (ClaimType) is authored here (closed). The rule/claim INSTANCES are
+# extracted from text (CC-2/CC-3); this file is only the schema.
+
+@prefix cmp:   <https://ragwright.local/ontology/compliance-bridge#> .
+@prefix odrl:  <http://www.w3.org/ns/odrl/2/> .
+@prefix lkif:  <http://www.estrellaproject.org/lkif-core/norm.owl#> .
+@prefix prov:  <http://www.w3.org/ns/prov#> .
+@prefix owl:   <http://www.w3.org/2002/07/owl#> .
+@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix skos:  <http://www.w3.org/2004/02/skos/core#> .
+@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
+
+<https://ragwright.local/ontology/compliance-bridge> a owl:Ontology ;
+    rdfs:label "RAG_Wright compliance bridge" ;
+    rdfs:comment "Two-sided compliance schema: deontic Requirement rules (ODRL/LKIF) + subject Claims, PROV-O provenance. Grounds the requirement_extraction / claim_extraction / compliance_judgment capabilities." .
+
+# =============================================================================
+# Deontic backbone — the rule's force. Reuse the public standards (ODRL/LKIF); our closed values map to them.
+# =============================================================================
+cmp:DeonticType a owl:Class ; skos:prefLabel "Deontic force" ;
+    owl:oneOf ( cmp:obligation cmp:prohibition cmp:permission ) .
+cmp:obligation  a cmp:DeonticType ; rdfs:subClassOf lkif:Obligation, odrl:Duty        ; skos:prefLabel "obligation" .
+cmp:prohibition a cmp:DeonticType ; rdfs:subClassOf lkif:Prohibition, odrl:Prohibition ; skos:prefLabel "prohibition" .
+cmp:permission  a cmp:DeonticType ; rdfs:subClassOf lkif:Permission, odrl:Permission  ; skos:prefLabel "permission" .
+
+# ADR-0066 P3c (Gap 1): the deontic CUES -- the lexical markers of operative normative force, per deontic type.
+# The requirement-ingestion validity gate uses them: a section with NONE of these cues is non-operative (a
+# definitions / purpose / scope statement) and is skipped SYMBOLICALLY -- replacing the brittle
+# "definition"-in-heading keyword hack (domain-neutral, heading-agnostic). Linguistic KNOWLEDGE -> the ontology.
+cmp:cue a owl:DatatypeProperty ; rdfs:domain cmp:DeonticType ; rdfs:range xsd:string ;
+    rdfs:comment "A lexical marker that this deontic force is present in a rule's text." .
+cmp:obligation  cmp:cue "must", "shall", "will", "required", "requires", "obligated", "responsible for", "agrees to" .
+cmp:prohibition cmp:cue "must not", "shall not", "may not", "will not", "prohibited", "forbidden", "not permitted" .
+cmp:permission  cmp:cue "may", "permitted", "allowed", "entitled", "at its discretion", "reserves the right" .
+
+# =============================================================================
+# ADR-0066 P4a: Actor ROLE synonyms -- a canonical role (skos:prefLabel) + its surface variants (skos:altLabel).
+# The query-side actor gate (canonical_actor) normalizes a rule's bound actor + a subject's role to the canonical
+# form before matching, so 'manufacturer' aligns with 'advertiser'. Generic role KNOWLEDGE -> the ontology (a
+# new customer domain extends this pack, not the code). Not owl:oneOf: an open, extensible SKOS role scheme.
+#
+# ADR-0068 (engine issue 0013): each role also declares a cmp:roleDomain -- the DISJOINTNESS knowledge the actor
+# gate reasons over. The gate is RECALL-FIRST: two specific roles are treated as COMPATIBLE (a pair worth judging)
+# unless the ontology makes them DISJOINT, and two roles are disjoint ONLY when both declare a roleDomain and the
+# domains DIFFER. All the advertising-ecosystem roles share domain "advertising", so an advertiser rule pairs with
+# a seller/endorser/consumer assertion (a seller advertising IS the advertiser) -- the fix for the silent drop
+# where two independent extractions picked different-but-overlapping role words. A role with NO roleDomain (an
+# unmodelled/exotic term) is compatible with everything (recall-first). Cross-DOMAIN narrowing (e.g. a labor
+# 'employer' rule not judged against an advertising assertion) is a customer domain pack declaring its own roles
+# under a different roleDomain -- never an engine edit.
+# =============================================================================
+cmp:ActorRole a owl:Class ; skos:prefLabel "Actor role" ;
+    rdfs:comment "A canonical party role a rule can bind or a subject can carry; skos:altLabel lists its synonyms." .
+cmp:roleDomain a owl:DatatypeProperty ; skos:prefLabel "role domain" ;
+    rdfs:comment "The domain a canonical actor role belongs to (ADR-0068). Two roles are DISJOINT iff both declare a roleDomain and the domains differ; the actor gate excludes only disjoint role pairs (recall-first)." .
+cmp:advertiser a cmp:ActorRole ; skos:prefLabel "advertiser" ; cmp:roleDomain "advertising" ;
+    skos:altLabel "manufacturer", "marketer", "brand", "company", "business", "sponsor" .
+cmp:endorser a cmp:ActorRole ; skos:prefLabel "endorser" ; cmp:roleDomain "advertising" ;
+    skos:altLabel "influencer", "spokesperson", "ambassador", "reviewer" .
+cmp:expert a cmp:ActorRole ; skos:prefLabel "expert" ; cmp:roleDomain "advertising" ;
+    skos:altLabel "physician", "doctor", "specialist", "professional" .
+cmp:consumer a cmp:ActorRole ; skos:prefLabel "consumer" ; cmp:roleDomain "advertising" ;
+    skos:altLabel "buyer", "customer", "user" .
+cmp:seller a cmp:ActorRole ; skos:prefLabel "seller" ; cmp:roleDomain "advertising" ;
+    skos:altLabel "merchant", "retailer", "vendor" .
+
+# =============================================================================
+# Requirement — a single regulatory rule (the rulebook side). requirement_id = <source_reg>:<section>:<hash>.
+# =============================================================================
+cmp:Requirement a owl:Class ; skos:prefLabel "Requirement" ;
+    rdfs:comment "One deontic rule extracted from a regulatory corpus; always carries a citation (PROV)." .
+cmp:deonticType a owl:ObjectProperty, owl:FunctionalProperty ; rdfs:domain cmp:Requirement ; rdfs:range cmp:DeonticType .
+cmp:actor a owl:DatatypeProperty ; rdfs:domain cmp:Requirement ; rdfs:range xsd:string ;
+    skos:prefLabel "bound actor" ; rdfs:comment "Who the rule binds: advertiser, endorser, ..." .
+cmp:requirementText a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:Requirement ; rdfs:range xsd:string .
+cmp:citation a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:Requirement ; rdfs:range xsd:string ;
+    rdfs:subPropertyOf prov:wasDerivedFrom ; rdfs:comment "Section/paragraph provenance; always present (FR-Q.6)." .
+cmp:evidenceStandard a owl:DatatypeProperty ; rdfs:domain cmp:Requirement ; rdfs:range xsd:string .
+cmp:severity a owl:DatatypeProperty ; rdfs:domain cmp:Requirement ; rdfs:range cmp:Severity .
+
+# ADR-0066 P3b: Severity is a closed vocab (completes the ontology; was an open xsd:string). low/med/high.
+cmp:Severity a owl:Class ; skos:prefLabel "Severity" ; owl:oneOf ( cmp:low cmp:med cmp:high ) .
+cmp:low a cmp:Severity . cmp:med a cmp:Severity . cmp:high a cmp:Severity .
+
+# Applicability — typed (dimension, value) conditions the rule applies under. Same odrl:Constraint pattern as
+# the contract bridge, matched against a Claim's scope by the reused retrieval router (CC-6).
+cmp:ApplicabilityConstraint a owl:Class ; rdfs:subClassOf odrl:Constraint ; skos:prefLabel "Applicability condition" .
+cmp:dimension a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:ApplicabilityConstraint ; rdfs:range xsd:string .
+cmp:value a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:ApplicabilityConstraint ; rdfs:range xsd:string .
+cmp:hasApplicabilityScope a owl:ObjectProperty ; rdfs:domain cmp:Requirement ; rdfs:range cmp:ApplicabilityConstraint .
+
+# =============================================================================
+# Claim — a checkable element from the SUBJECT document (the ad side). claim_id + span = provenance.
+# =============================================================================
+cmp:Claim a owl:Class ; skos:prefLabel "Claim" ;
+    rdfs:comment "One checkable assertion extracted from a subject document (ad), cited to its span (PROV)." .
+cmp:ClaimType a owl:Class ; skos:prefLabel "Claim type" ;
+    owl:oneOf ( cmp:efficacy cmp:comparative cmp:pricing cmp:health cmp:environmental cmp:endorsement cmp:performance cmp:guarantee ) .
+cmp:efficacy a cmp:ClaimType . cmp:comparative a cmp:ClaimType . cmp:pricing a cmp:ClaimType .
+cmp:health a cmp:ClaimType . cmp:environmental a cmp:ClaimType . cmp:endorsement a cmp:ClaimType .
+cmp:performance a cmp:ClaimType . cmp:guarantee a cmp:ClaimType .
+cmp:claimType a owl:ObjectProperty, owl:FunctionalProperty ; rdfs:domain cmp:Claim ; rdfs:range cmp:ClaimType .
+cmp:assertionText a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:Claim ; rdfs:range xsd:string .
+cmp:disclosurePresent a owl:DatatypeProperty ; rdfs:domain cmp:Claim ; rdfs:range xsd:string .
+cmp:evidenceReferenced a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:Claim ; rdfs:range xsd:boolean .
+cmp:medium a owl:DatatypeProperty ; rdfs:domain cmp:Claim ; rdfs:range xsd:string .
+cmp:hasSpan a owl:ObjectProperty, owl:FunctionalProperty ; rdfs:domain cmp:Claim ; rdfs:range prov:Entity ;
+    rdfs:comment "The subject-document span the claim was read from (provenance, cited)." .
+
+# =============================================================================
+# RuleScope — how a requirement is narrowed at check time (CC-8a, the ontology routing tag). content = narrow by
+# semantic similarity to the claim; context = apply to any claim in an endorsement (always included, e.g. §255.5).
+# =============================================================================
+cmp:RuleScope a owl:Class ; skos:prefLabel "Rule scope" ; owl:oneOf ( cmp:content cmp:context ) .
+cmp:content a cmp:RuleScope ; skos:prefLabel "content rule (substantiation / claim-specific)" .
+cmp:context a cmp:RuleScope ; skos:prefLabel "context rule (disclosure; applies regardless of claim content)" .
+cmp:ruleScope a owl:ObjectProperty, owl:FunctionalProperty ; rdfs:domain cmp:Requirement ; rdfs:range cmp:RuleScope .
+
+# =============================================================================
+# ADR-0066 P4b: SectionOverride -- a DOMAIN PACK's curated per-section override (DEON-1 rule scope + DEON-8
+# applicable claim types). The engine ontology declares the SHAPE here; the INSTANCES live in a domain-pack ttl
+# (e.g. packs/ftc_16cfr255.ttl). A customer domain ships its own pack; nothing is FTC-hardcoded in code.
+# =============================================================================
+cmp:SectionOverride a owl:Class ; skos:prefLabel "Section override" ;
+    rdfs:comment "Pins a cited section's rule scope and/or its applicable claim types; a domain pack provides instances." .
+cmp:section a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:SectionOverride ; rdfs:range xsd:string ;
+    rdfs:comment "The section citation this override applies to, e.g. '255.5'." .
+cmp:overrideRuleScope a owl:ObjectProperty, owl:FunctionalProperty ; rdfs:domain cmp:SectionOverride ; rdfs:range cmp:RuleScope .
+cmp:appliesToAllClaimTypes a owl:DatatypeProperty, owl:FunctionalProperty ; rdfs:domain cmp:SectionOverride ; rdfs:range xsd:boolean ;
+    rdfs:comment "true -> the section applies to ALL claim types; false with no cmp:appliesToClaimType -> none (e.g. a definitions section)." .
+cmp:appliesToClaimType a owl:ObjectProperty ; rdfs:domain cmp:SectionOverride ; rdfs:range cmp:ClaimType ;
+    rdfs:comment "A specific claim type the section applies to (used only when cmp:appliesToAllClaimTypes is false)." .
+
+# =============================================================================
+# Verdict — the judgment output (CC-4). Closed vocab; every 'violation' is human-gated before it leaves.
+# =============================================================================
+cmp:Verdict a owl:Class ; skos:prefLabel "Compliance verdict" ;
+    owl:oneOf ( cmp:compliant cmp:violation cmp:needs_review ) .
+cmp:compliant a cmp:Verdict . cmp:violation a cmp:Verdict . cmp:needs_review a cmp:Verdict .
+
+# =============================================================================
+# Decision criteria (ADR-0119) — the typed-decision (Jev) question knowledge, authored here (NOT in capability
+# code) per ADR-0066. `cmp:decisionCriterion` is a vocab member's one-line criterion for a yes/no (noul) or a
+# choice option; `cmp:DecisionQuestion` holds a binary gate's instructions + true/false criteria. The engine's
+# `jev_decision` question-builder reads these from the ttl; the few-shot/prompt framing stays a code overlay.
+# =============================================================================
+cmp:decisionCriterion a owl:DatatypeProperty ; rdfs:range xsd:string ;
+    skos:prefLabel "decision criterion" ;
+    rdfs:comment "A one-line criterion for a vocab member as a typed-decision answer option (ADR-0119)." .
+
+# ClaimType criteria (the 8 noul questions: 'does this rule apply to <type> claims?')
+cmp:efficacy      cmp:decisionCriterion "the product WORKS / is effective at its purpose (cures, treats, achieves the promised result); NOT mere speed/durability" .
+cmp:comparative   cmp:decisionCriterion "COMPARES the product to competitors or alternatives (better than, #1, versus)" .
+cmp:pricing       cmp:decisionCriterion "PRICE, discount, 'reduced', 'free', 2-for-1, or savings" .
+cmp:health        cmp:decisionCriterion "HEALTH, medical, disease, nutrition, or bodily-safety" .
+cmp:environmental cmp:decisionCriterion "ENVIRONMENTAL / green / eco / sustainable / biodegradable" .
+cmp:endorsement   cmp:decisionCriterion "ENDORSEMENTS, testimonials, reviews, or who may endorse" .
+cmp:performance   cmp:decisionCriterion "measurable HOW-WELL -- speed, durability, strength, capacity, output level (not merely that it works)" .
+cmp:guarantee     cmp:decisionCriterion "a GUARANTEE, warranty, or money-back promise" .
+
+# ActorRole criteria (the actor `choice` options) + the workplace-domain `employer` role (OSHA).
+cmp:advertiser cmp:decisionCriterion "the advertiser / marketer / manufacturer / brand making the claim" .
+cmp:endorser   cmp:decisionCriterion "the endorser / testimonial-giver / reviewer / influencer" .
+cmp:expert     cmp:decisionCriterion "an expert whose evaluation is relied upon" .
+cmp:seller     cmp:decisionCriterion "the seller / vendor / retailer, when named distinctly" .
+cmp:consumer   cmp:decisionCriterion "the consumer / customer / audience" .
+cmp:employer a cmp:ActorRole ; skos:prefLabel "employer" ; cmp:roleDomain "workplace" ;
+    skos:altLabel "establishment", "worksite", "employing entity" ;
+    cmp:decisionCriterion "the employer responsible (workplace safety / injury recordkeeping)" .
+
+# The operative-rule binary gate (ADR-0119): is a span itself a binding rule?
+cmp:DecisionQuestion a owl:Class ; skos:prefLabel "Decision question" ;
+    rdfs:comment "A typed yes/no decision: instructions + the true/false criteria a decision model is asked." .
+cmp:questionInstructions a owl:DatatypeProperty ; rdfs:domain cmp:DecisionQuestion ; rdfs:range xsd:string .
+cmp:criterionTrue  a owl:DatatypeProperty ; rdfs:domain cmp:DecisionQuestion ; rdfs:range xsd:string .
+cmp:criterionFalse a owl:DatatypeProperty ; rdfs:domain cmp:DecisionQuestion ; rdfs:range xsd:string .
+cmp:operativeRuleQuestion a cmp:DecisionQuestion ;
+    cmp:questionInstructions "Is this sentence itself a BINDING operative rule (obligation/prohibition/permission or a binding liability/conditional consequence)?" ;
+    cmp:criterionTrue "it binds conduct directly" ;
+    cmp:criterionFalse "an illustrative example, definition, scope, cross-reference, negated requirement, or descriptive remark" .