Clause Lineage & Linkage:
Resolving Relationships and Provenance in Documents

def resolve_with_inheritance(doc_id: str, clause_type: str, as_of: datetime):
    local = doc.get_clause_by_type(clause_type)
    if local:
        return resolve_effective_clause(local.clause_id, as_of)

    # Walk CHILD_OF edges breadth-first toward root
    for parent_doc in graph.get_parents(doc_id, edge_type="CHILD_OF"):
        result = resolve_with_inheritance(parent_doc.doc_id, clause_type, as_of)
        if result:
            result.inherited_from = parent_doc.doc_id   # flag as inherited
            return result
    return None

{
  "eventTime": "2026-05-25T14:55:00Z",
  "eventType": "COMPLETE",
  "run": {
    "runId": "4892c90c-60e1-4569-b570-98df872a08cc",
    "facets": {
      "modelContext": { "model": "gemini-1.5-pro", "constraintGrammar": "clause_schema_v4.gbnf" },
      "lineageResolutionPath": {
        "path": [
          { "clauseId": "cl_4.2_amd1",              "edgeType": "AMENDS" },
          { "clauseId": "cl_4.2_limitation_of_liability", "edgeType": "ROOT"   }
        ]
      }
    }
  },
  "inputs": [{ "namespace": "contract-lake", "name": "MSA_Acme_Corp_v3.pdf",
    "facets": { "documentMetadata": { "sha256": "8f309a96e5dbe4889c20a9a1488e4d0c" } }
  }],
  "outputs": [{ "namespace": "obligation-registry", "name": "obligation_nodes",
    "facets": { "clauseProvenance": {
      "clauseId":    "cl_4.2_amd1",
      "pageNumber":  14,
      "boundingBox": [120, 450, 480, 590],
      "confidence":  0.98
    }}
  }]
}

## SYSTEM
Extract cross-document citation spans from the clause below.

A citation span is a verbatim phrase that explicitly names a different contract
document or a numbered section within a different document that this clause
depends on or references.

Do NOT extract:
  - References to defined terms within the same agreement
    (e.g. "as defined in Section 1.2 of this Agreement")
  - References to applicable law or regulation
    (e.g. "pursuant to GDPR Article 17", "under applicable export control laws")
  - Self-references to other sections within the same document
  - Generic incorporation phrases without a named external document
    (e.g. "incorporated herein by reference" with no document named)

Rules:
  - Return the span character-exact — do not paraphrase
  - If a document name AND a section are both present, include both in the span
  - If no qualifying citation exists, return {"citations": []}
  - Return ONLY valid JSON. No explanation, no commentary.

Output schema:
{
  "citations": [
    {
      "span":           string,        // verbatim, character-exact substring
      "doc_name_hint":  string | null, // e.g. "Master Services Agreement"
      "doc_date_hint":  string | null, // e.g. "January 15, 2026" if present
      "section_hint":   string | null  // e.g. "Article 4.2" if present
    }
  ]
}

## USER
Clause (source document: Amendment_1_to_MSA.pdf · section: § 4.2 · executed: 2026-03-01):
"""
Article 4.2 of this Amendment hereby supersedes and replaces Article 4.2
of the Master Services Agreement dated January 15, 2026 in its entirety.
The liability cap shall not exceed two times (2x) the fees paid in the
twelve (12) months preceding the claim.
"""

{
  "citations": [
    {
      "span":          "Article 4.2 of the Master Services Agreement dated January 15, 2026",
      "doc_name_hint": "Master Services Agreement",
      "doc_date_hint": "January 15, 2026",
      "section_hint":  "Article 4.2"
    }
  ]
}

def resolve_citation_to_clause(citation: dict, doc_registry, clause_store) -> str | None:
    """
    Resolve a Prompt A citation output to a concrete clauseId.
    Entirely deterministic — no LLM involved.
    """
    # Step 1: validate span exists verbatim in source text (hallucination check)
    if citation["span"] not in source_clause.effective_text:
        log.warn(f"Span not found in source text — likely hallucinated: {citation['span']}")
        return None

    # Step 2: match doc_name_hint + doc_date_hint against registry
    candidate_docs = doc_registry.fuzzy_match(
        name=citation["doc_name_hint"],
        date=citation["doc_date_hint"]   # date disambiguates MSA v1 vs v3
    )
    if not candidate_docs:
        return None  # document not in portfolio — flag for review

    target_doc = candidate_docs[0]  # highest-confidence match

    # Step 3: resolve section_hint to a clauseId within the target document
    if citation["section_hint"]:
        clause = clause_store.get_by_section(target_doc.doc_id, citation["section_hint"])
        return clause.clause_id if clause else None

    # No section hint — return doc-level node for inheritance edge
    return target_doc.root_clause_id

## SYSTEM
Classify the legal relationship between two clauses from the same contract
portfolio. You will be given the full text of both clauses.

Relationship definitions:
  AMENDS      – Clause A replaces or modifies specific language in Clause B.
                Partial amendment (changes one term, preserves others) counts.
  SUPPLEMENTS – Clause A adds obligations that do not conflict with Clause B.
                Both remain fully in force after the newer document.
  CHILD_OF    – Clause A is in a document that inherits from Clause B's document
                with no override of this specific clause text.
  TERMINATES  – Clause A explicitly ends or cancels the obligation in Clause B.
  UNRELATED   – Same clause type (e.g. both are payment terms) but govern
                different subjects or counterparties. Do not infer a relationship
                from surface similarity alone.

Output ONLY valid JSON. The "reasoning" field is one sentence max and is
retained for the audit log — it does not affect the graph write.

{
  "edge_type":  "AMENDS" | "SUPPLEMENTS" | "CHILD_OF" | "TERMINATES" | "UNRELATED",
  "confidence": number,  // 0.0–1.0. Be conservative — prefer UNRELATED over
                         // a low-confidence AMENDS that could corrupt the graph.
  "reasoning":  string
}

## USER
Clause A — source (newer):
  Document: SOW_002_Amendment_1.pdf · § 3.1 · executed: 2026-03-15
"""
The Delivery Date defined in Section 3.1 of SOW #2 is hereby revised to
April 30, 2026. All other terms of Section 3.1 remain in full force.
"""

Clause B — target (older):
  Document: SOW_002.pdf · § 3.1 · executed: 2025-11-01
"""
Vendor shall deliver the completed integration no later than March 15, 2026,
subject to the change order process defined in Article 7.
"""

{
  "edge_type":  "AMENDS",
  "confidence": 0.96,
  "reasoning": "Clause A explicitly revises the delivery date in Clause B while preserving all other § 3.1 terms — a partial amendment pattern."
}

## SYSTEM
Extract structured obligation data from the effective clause text below.
This clause has already been resolved through the lineage graph — it is
the currently active version. Do not reference other versions.

Classify the obligation domain and extract all typed parameter fields.
Dates must be ISO 8601. Monetary amounts must include currency.
For relative deadlines (e.g. "within 30 days of Go-Live"), set
trigger_event to the condition name and absolute_date to null.

Output ONLY valid JSON:
{
  "obligation_domain": "FINANCIAL" | "OPERATIONAL" | "REGULATORY" | "RESTRICTIVE",
  "obligation_type":   string,          // specific type within domain
  "party_obligated":   "VENDOR" | "CLIENT" | "BOTH" | "UNCLEAR",
  "parameters": {
    "amount":          string | null,   // e.g. "2x trailing 12-month fees"
    "absolute_date":   string | null,   // ISO 8601 if determinable
    "trigger_event":   string | null,   // condition for relative deadlines
    "jurisdiction":    string | null,
    "notice_period":   string | null
  },
  "risk_flags": [string]                // e.g. ["UNCAPPED", "MISSING_NOTICE_PERIOD"]
}

## USER
Effective clause (resolved as of 2026-05-25):
  clauseId: cl_4.2_amd1_limitation · source: Amendment_1_to_MSA.pdf · § 4.2
  Resolution path: cl_4.2_amd1 → AMENDS → cl_4.2_msa_v3 (original)
"""
The liability of either party under this Agreement shall not exceed two
times (2x) the fees paid by Client in the twelve (12) months immediately
preceding the claim giving rise to liability.
"""

{
  "obligation_domain": "FINANCIAL",
  "obligation_type":   "LIMITATION_OF_LIABILITY",
  "party_obligated":   "BOTH",
  "parameters": {
    "amount":        "2x fees paid in preceding 12 months",
    "absolute_date": null,
    "trigger_event": "claim giving rise to liability",
    "jurisdiction":  null,
    "notice_period": null
  },
  "risk_flags": []
}

{
  "name": "add_lineage_edge",
  "description": "Record a directional lineage edge between two clause nodes in the contract graph. Call this once per detected relationship.",
  "input_schema": {
    "type": "object",
    "properties": {
      "source_clause_id": { "type": "string", "description": "clauseId of the newer/overriding clause" },
      "target_clause_id": { "type": "string", "description": "clauseId of the older/original clause" },
      "edge_type":        { "type": "string", "enum": ["AMENDS","SUPPLEMENTS","CHILD_OF","TERMINATES"] },
      "confidence":       { "type": "number", "minimum": 0, "maximum": 1 },
      "citation_text":    { "type": "string", "description": "Verbatim phrase that establishes the relationship, or empty string if inferred semantically" },
      "effective_from":   { "type": "string", "format": "date" }
    },
    "required": ["source_clause_id", "target_clause_id", "edge_type", "confidence"]
  }
}

{
  "type":  "tool_use",
  "name":  "add_lineage_edge",
  "input": {
    "source_clause_id": "cl_3.1_amd1_delivery_date",
    "target_clause_id": "cl_3.1_sow002_delivery_date",
    "edge_type":        "AMENDS",
    "confidence":       0.96,
    "citation_text":    "The Delivery Date defined in Section 3.1 of SOW #2 is hereby revised",
    "effective_from":   "2026-03-15"
  }
}

from dataclasses import dataclass
from enum import Enum

class GateOutcome(Enum):
    COMMIT       = "commit"         # write to graph immediately
    REVIEW_QUEUE = "review_queue"   # paralegal review before graph write
    REJECT       = "reject"         # discard — too low to queue

# Thresholds differ by edge type — TERMINATES is irreversible, so threshold is higher
CONFIDENCE_THRESHOLDS = {
    "AMENDS":      { "commit": 0.88, "review": 0.60 },
    "SUPPLEMENTS": { "commit": 0.85, "review": 0.55 },
    "CHILD_OF":    { "commit": 0.80, "review": 0.50 },
    "TERMINATES":  { "commit": 0.95, "review": 0.75 },  # strictest
}

def gate_edge(edge_type: str, confidence: float, derivation: str) -> GateOutcome:
    thresholds = CONFIDENCE_THRESHOLDS[edge_type]

    # Explicit citations get a 0.05 bonus — citation_text is hard evidence
    if derivation == "EXPLICIT_CITATION":
        confidence = min(1.0, confidence + 0.05)

    if confidence >= thresholds["commit"]:
        return GateOutcome.COMMIT
    elif confidence >= thresholds["review"]:
        return GateOutcome.REVIEW_QUEUE
    else:
        return GateOutcome.REJECT

def process_tool_call(tool_input: dict, graph, review_queue):
    outcome = gate_edge(
        tool_input["edge_type"],
        tool_input["confidence"],
        "EXPLICIT_CITATION" if tool_input.get("citation_text") else "SEMANTIC_SIMILARITY"
    )

    if outcome == GateOutcome.COMMIT:
        graph.add_edge(**tool_input)
        return { "status": "committed", "edge_id": graph.last_edge_id }

    elif outcome == GateOutcome.REVIEW_QUEUE:
        review_queue.enqueue({
            "edge_candidate": tool_input,
            "reason": f"confidence {tool_input['confidence']:.2f} below commit threshold",
            "priority": "HIGH" if tool_input["edge_type"] == "TERMINATES" else "NORMAL"
        })
        return { "status": "queued_for_review" }

    else:
        return { "status": "rejected", "reason": "confidence below minimum threshold" }

import numpy as np

def cosine_similarity(a: list[float], b: list[float]) -> float:
    a, b = np.array(a), np.array(b)
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

def find_implicit_candidates(
    new_clause: ClauseNode,
    clause_store: ClauseStore,
    similarity_threshold: float = 0.82,
    max_candidates: int = 5
) -> list[dict]:
    """
    For a newly extracted clause with no explicit citation, find existing
    clauses in the graph that it may implicitly amend or supplement.
    Scoped to matching clause_type to reduce cross-domain false positives.
    """
    candidates = []

    # Only compare against clauses of the same legal type
    same_type_clauses = clause_store.get_by_type(new_clause.clause_type)

    for existing in same_type_clauses:
        # Skip clauses from the same document — intra-doc hierarchy handled separately
        if existing.document_id == new_clause.document_id:
            continue

        sim = cosine_similarity(new_clause.embedding, existing.embedding)

        if sim >= similarity_threshold:
            candidates.append({
                "target_clause_id": existing.clause_id,
                "similarity":       sim,
                "target_doc_date":  existing.document_date,
                "needs_llm_confirm": True   # always confirm before edge write
            })

    # Return top-N by similarity, but only candidates older than new clause
    candidates = [c for c in candidates
                  if c["target_doc_date"] < new_clause.document_date]
    candidates.sort(key=lambda x: x["similarity"], reverse=True)
    return candidates[:max_candidates]

def answer_legal_query(
    natural_language_query: str,
    counterparty_id: str,
    as_of: datetime,
    llm_client,
    graph: LineageGraph
) -> dict:
    """
    Graph-augmented RAG: resolve effective clauses through the DAG first,
    then build a minimal context window for the LLM. Never retrieves
    superseded or terminated clauses.
    """

    # 1. Classify which clause types the query is about
    #    (a small fast classifier call — not the full graph query)
    relevant_types = classify_query_intent(natural_language_query)
    # e.g. → ["LIMITATION_OF_LIABILITY", "INDEMNIFICATION"]

    # 2. Fetch all documents for this counterparty
    doc_ids = graph.get_documents_by_counterparty(counterparty_id)

    # 3. For each relevant clause type, resolve the effective clause
    #    through the lineage graph — NOT the vector index
    resolved_clauses = []
    for clause_type in relevant_types:
        for doc_id in doc_ids:
            effective = resolve_with_inheritance(doc_id, clause_type, as_of)
            if effective:
                resolved_clauses.append({
                    "clause_type":     clause_type,
                    "effective_text":  effective.effective_text,
                    "source_doc":      effective.source_file,
                    "resolution_path": effective.resolution_path,
                    "page":            effective.page_number,
                    "inherited_from":  getattr(effective, "inherited_from", None)
                })

    # 4. Build a minimal, provenance-annotated context for the LLM
    context_blocks = []
    for c in resolved_clauses:
        path_summary = " → ".join([e["clauseId"] for e in c["resolution_path"]])
        context_blocks.append(f"""
[{c['clause_type']}]
Source: {c['source_doc']}, page {c['page']}
Resolution path: {path_summary}
Effective text:
{c['effective_text']}
""")

    context = "\n---\n".join(context_blocks)

    # 5. Single LLM call with resolved, provenance-annotated context
    response = llm_client.complete(
        system="You are a legal analyst. Answer the query using ONLY the clause text provided. "
               "Cite the source document and page number for every claim. "
               "Do not infer or extrapolate beyond the provided text.",
        user=f"Clauses (as of {as_of.date()}, already resolved for amendments):\n\n{context}\n\nQuery: {natural_language_query}"
    )

    return {
        "answer":          response.text,
        "resolved_clauses": resolved_clauses,   # full provenance returned to caller
        "as_of":           as_of.isoformat()
    }