"""
CHEX - Document Intelligence
HuggingFace Spaces Gradio Demo
Tab 1: Analyze Contract — paste a contract, ask a question, get a structured answer
Tab 2: Benchmark Demo — side-by-side table showing base model hallucinations vs CHEX
Tab 3: Analyse Bank Statement — paste / upload a bank statement, get a summary + Q&A
"""
from __future__ import annotations
import os
import sys
from pathlib import Path
from typing import Optional
import gradio as gr
sys.path.insert(0, str(Path(__file__).parent.parent))
# ---------------------------------------------------------------------------
# Model loading
# ---------------------------------------------------------------------------
MODEL_PATH = os.environ.get(
"HF_MODEL_REPO", "PLACEHOLDER/chex-document-intelligence"
)
SAMPLE_DIR = Path(__file__).parent / "sample_contracts"
STATEMENT_DIR = Path(__file__).parent / "sample_statements"
analyzer = None
model_load_error: Optional[str] = None
bank_analyzer = None
try:
from serving.inference import ContractAnalyzer # type: ignore
from serving.bank_statement import BankStatementAnalyzer # type: ignore
analyzer = ContractAnalyzer(model_path=MODEL_PATH)
bank_analyzer = BankStatementAnalyzer(contract_analyzer=analyzer)
print(f"Model loaded successfully: {MODEL_PATH}")
except Exception as e:
model_load_error = str(e)
print(f"WARNING: Model failed to load: {e}")
print("Demo is running in preview mode — analysis will return a placeholder response.")
# ---------------------------------------------------------------------------
# Sample contract content
# ---------------------------------------------------------------------------
def _read_sample(filename: str) -> str:
p = SAMPLE_DIR / filename
if p.exists():
return p.read_text(encoding="utf-8")
return f"[Sample contract '{filename}' not found. Place it in demo/sample_contracts/]"
SOFTWARE_LICENSE = _read_sample("software_license.txt")
NDA = _read_sample("nda.txt")
SERVICE_AGREEMENT = _read_sample("service_agreement.txt")
# Suggested questions for each sample contract
SAMPLE_QUESTIONS = {
"software_license.txt": "What is the limitation of liability in this agreement?",
"nda.txt": "Does this agreement include a non-compete clause?",
"service_agreement.txt": "Does this contract include a termination for convenience clause?",
}
# ---------------------------------------------------------------------------
# Label badge HTML
# ---------------------------------------------------------------------------
_BADGE_CFG = {
"GROUNDED": ("#0f9d58", "rgba(34,197,94,0.10)", "rgba(34,197,94,0.28)", "✓"),
"ABSENT": ("#d23131", "rgba(239,68,68,0.09)", "rgba(239,68,68,0.28)", "✗"),
"CONTRADICTS_PRIOR": ("#b87800", "rgba(245,158,11,0.10)", "rgba(245,158,11,0.30)", "⚠"),
"N/A": ("#8a91a3", "rgba(139,145,163,0.10)","rgba(139,145,163,0.25)","—"),
"ERROR": ("#991b1b", "rgba(220,38,38,0.10)", "rgba(220,38,38,0.32)", "!"),
}
def format_label_html(label: str) -> str:
fg, bg, border, icon = _BADGE_CFG.get(label, _BADGE_CFG["N/A"])
display = "CONTRADICTS PRIOR" if label == "CONTRADICTS_PRIOR" else label
return (
f''
f'{icon}'
f'{display}
'
)
# ---------------------------------------------------------------------------
# Analysis handler
# ---------------------------------------------------------------------------
def analyze_contract(
contract_text: str,
question: str,
) -> tuple[str, str, str, str]:
"""
Returns (label_html, answer_text, citation_text, reasoning_text).
"""
if not contract_text.strip():
return format_label_html("N/A"), "", "", "Please paste a contract above."
if not question.strip():
return format_label_html("N/A"), "", "", "Please enter a question."
if analyzer is None:
return (
format_label_html("N/A"),
"Model not loaded",
"",
f"Model failed to load: {model_load_error}. "
"Set HF_MODEL_REPO in Space secrets to the correct model repo.",
)
try:
result = analyzer.analyze(contract_text, question)
label_html = format_label_html(result.label.value)
answer = result.answer if result.answer else "(none — clause is absent or not applicable)"
citation = result.citation if result.citation else "(none)"
reasoning = result.reasoning
return label_html, answer, citation, reasoning
except Exception as e:
return format_label_html("ERROR"), "", "", f"Inference error: {e}"
# ---------------------------------------------------------------------------
# Sample bank statement
# ---------------------------------------------------------------------------
def _read_sample_statement(filename: str) -> str:
p = STATEMENT_DIR / filename
if p.exists():
return p.read_text(encoding="utf-8")
return f"[Sample statement '{filename}' not found. Place it in demo/sample_statements/]"
SAMPLE_STATEMENT = _read_sample_statement("sample_statement.txt")
# ---------------------------------------------------------------------------
# Bank statement handlers
# ---------------------------------------------------------------------------
def _get_statement_text(
paste_text: str,
pdf_file,
csv_file,
) -> tuple[str, str]:
"""
Resolve whichever input was provided and return (statement_text, error_msg).
Priority: PDF > CSV > paste text.
"""
if pdf_file is not None:
if bank_analyzer is None:
return "", "Model not loaded — PDF extraction unavailable."
try:
text = bank_analyzer.extract_text_from_pdf(pdf_file)
if not text.strip():
return "", "PDF was uploaded but no text could be extracted."
return text, ""
except Exception as e:
return "", f"PDF extraction error: {e}"
if csv_file is not None:
if bank_analyzer is None:
return "", "Model not loaded — CSV parsing unavailable."
try:
text = bank_analyzer.parse_csv(csv_file)
return text, ""
except Exception as e:
return "", f"CSV parsing error: {e}"
if paste_text and paste_text.strip():
return paste_text.strip(), ""
return "", "Please paste a bank statement or upload a PDF / CSV file."
def analyse_bank_statement(
paste_text: str,
pdf_file,
csv_file,
) -> tuple[str, str]:
"""
Returns (summary_markdown, extracted_text_for_qa).
"""
statement_text, error = _get_statement_text(paste_text, pdf_file, csv_file)
if error:
return f"**Error:** {error}", ""
if analyzer is None:
return (
"**Model not loaded.** "
f"Set `HF_MODEL_REPO` in Space secrets. Error: {model_load_error}",
statement_text,
)
try:
summary = bank_analyzer.summarize(statement_text)
lines = ["## Statement Summary", ""]
lines.append(f"**Total Credits:** {summary.total_credits or 'N/A'}")
lines.append(f"**Total Debits:** {summary.total_debits or 'N/A'}")
lines.append(f"**Largest Transaction:** {summary.largest_transaction or 'N/A'}")
if summary.recurring_payments:
lines.append("\n**Recurring Payments:**")
for p in summary.recurring_payments:
lines.append(f"- {p}")
if summary.flags:
lines.append("\n**Flags / Unusual Activity:**")
for f in summary.flags:
lines.append(f"- {f}")
lines.append(f"\n*{summary.raw_reasoning}*")
return "\n".join(lines), statement_text
except Exception as e:
return f"**Summarisation error:** {e}", statement_text
def bank_qa(
statement_text: str,
question: str,
) -> tuple[str, str, str, str]:
"""
Returns (label_html, answer_text, citation_text, reasoning_text).
"""
if not statement_text.strip():
return (
format_label_html("N/A"), "", "",
"Please run 'Analyse Statement' first to load the statement.",
)
if not question.strip():
return format_label_html("N/A"), "", "", "Please enter a question."
if analyzer is None:
return (
format_label_html("N/A"), "Model not loaded", "",
f"Model failed to load: {model_load_error}.",
)
try:
result = bank_analyzer.answer_question(statement_text, question)
label_html = format_label_html(result.label.value)
answer = result.answer if result.answer else "(none — information not found in statement)"
citation = result.citation if result.citation else "(none)"
return label_html, answer, citation, result.reasoning
except Exception as e:
return format_label_html("ERROR"), "", "", f"Inference error: {e}"
# ---------------------------------------------------------------------------
# Benchmark table data (hardcoded — pre-computed base model outputs)
# ---------------------------------------------------------------------------
import pandas as pd
BENCHMARK_ROWS = [
{
"Question": "What is the limitation of liability?",
"Ground Truth": "GROUNDED — $50,000 cap",
"Base Model (untuned)": "GROUNDED — $100,000 cap (wrong amount)",
"CHEX Fine-tuned": "GROUNDED — $50,000 cap ✓",
"Hallucinated?": "No (wrong value)",
},
{
"Question": "Does this contract include a non-compete clause?",
"Ground Truth": "ABSENT",
"Base Model (untuned)": "🚨 GROUNDED — 'Licensee shall not engage in competing activities...' (fabricated)",
"CHEX Fine-tuned": "ABSENT — null ✓",
"Hallucinated?": "YES",
},
{
"Question": "What is the term of the NDA?",
"Ground Truth": "GROUNDED — 3 years",
"Base Model (untuned)": "GROUNDED — 2 years (wrong duration)",
"CHEX Fine-tuned": "GROUNDED — three (3) years ✓",
"Hallucinated?": "No (wrong value)",
},
{
"Question": "Is there a termination for convenience clause?",
"Ground Truth": "ABSENT",
"Base Model (untuned)": "🚨 GROUNDED — 'Either party may terminate at any time...' (fabricated)",
"CHEX Fine-tuned": "ABSENT — null ✓",
"Hallucinated?": "YES",
},
{
"Question": "What are the monthly payment terms?",
"Ground Truth": "GROUNDED — $5,000/month",
"Base Model (untuned)": "GROUNDED — $5,000/month ✓",
"CHEX Fine-tuned": "GROUNDED — $5,000/month ✓",
"Hallucinated?": "No",
},
]
BENCHMARK_DF = pd.DataFrame(BENCHMARK_ROWS)
# ---------------------------------------------------------------------------
# Warning banner
# ---------------------------------------------------------------------------
WARNING_HTML = ""
if model_load_error:
WARNING_HTML = (
''
'
⚠'
f'
Model not loaded · '
f'{model_load_error} — set HF_MODEL_REPO in Space secrets.
'
'
CX
CHEX
grounded answers from documents
MI300X · ready
"""
FOOTER_HTML = """
"""
BENCH_INTRO_HTML = """
Why grounding matters
We ran the same questions through a base instruction-tuned model and through CHEX.
The base model invented or extrapolated answers in 4 of 5 cases — confident, plausible, wrong.
CHEX returned a verifiable label, a verbatim citation, and refused to answer when the source was silent.
"""
CONTRACT_SOURCE_HEADER_HTML = """
"""
CONTRACT_RESULTS_HEADER_HTML = """
"""
CHIP_ROW_HTML = """
Load sample
"""
STATEMENT_SOURCE_HEADER_HTML = """
"""
STATEMENT_RESULTS_HEADER_HTML = """
"""
# ---------------------------------------------------------------------------
# Gradio UI
# ---------------------------------------------------------------------------
with gr.Blocks(
title="CHEX — Document Intelligence",
theme=gr.themes.Base(),
css=CHEX_CSS,
) as demo:
# ── Topbar ──────────────────────────────────────────────────────────── #
gr.HTML(TOPBAR_HTML)
# ── Warning banner (only if model failed) ───────────────────────────── #
if WARNING_HTML:
gr.HTML(WARNING_HTML)
# ── Tabs ────────────────────────────────────────────────────────────── #
with gr.Tabs():
# ================================================================== #
# Tab 01 — Contract Analysis #
# ================================================================== #
with gr.Tab("01 Contract analysis"):
with gr.Row(equal_height=False):
# ── Left panel: source document ──────────────────────────── #
with gr.Column(scale=9):
with gr.Group():
gr.HTML(CONTRACT_SOURCE_HEADER_HTML)
contract_input = gr.Textbox(
label="Contract text",
lines=20,
placeholder="Paste your contract text here, or load a sample below…",
show_label=False,
)
gr.HTML(CHIP_ROW_HTML)
with gr.Row():
btn_software = gr.Button("Software License", variant="secondary", size="sm")
btn_nda = gr.Button("NDA", variant="secondary", size="sm")
btn_service = gr.Button("Service Agreement", variant="secondary", size="sm")
suggested_q = gr.HTML(value="", visible=False)
# ── Right panel: question + results ──────────────────────── #
with gr.Column(scale=11):
with gr.Group():
gr.HTML(CONTRACT_RESULTS_HEADER_HTML)
with gr.Row():
question_input = gr.Textbox(
label="Question",
placeholder="e.g., What is the limitation of liability?",
lines=1,
show_label=False,
scale=8,
)
analyze_btn = gr.Button("Analyze ↵", variant="primary", scale=2)
label_display = gr.HTML(value=format_label_html("N/A"))
answer_output = gr.Textbox(label="Answer", interactive=False, lines=3)
citation_output = gr.Textbox(label="Citation", interactive=False, lines=2)
reasoning_output = gr.Textbox(label="Reasoning", interactive=False, lines=3)
# ================================================================== #
# Tab 02 — Bank Statements #
# ================================================================== #
with gr.Tab("02 Bank statements"):
with gr.Row(equal_height=False):
# ── Left panel: statement input ───────────────────────────── #
with gr.Column(scale=9):
with gr.Group():
gr.HTML(STATEMENT_SOURCE_HEADER_HTML)
with gr.Tabs():
with gr.Tab("Paste text"):
bank_paste_input = gr.Textbox(
label="Bank statement text",
lines=20,
placeholder="Paste your bank statement here, or load the sample below…",
show_label=False,
)
btn_load_statement = gr.Button("Load sample statement", variant="secondary", size="sm")
with gr.Tab("Upload PDF"):
bank_pdf_input = gr.File(label="PDF bank statement", file_types=[".pdf"])
with gr.Tab("Upload CSV"):
bank_csv_input = gr.File(label="CSV bank statement", file_types=[".csv"])
# ── Right panel: summary + Q&A ───────────────────────────── #
with gr.Column(scale=11):
with gr.Group():
gr.HTML(STATEMENT_RESULTS_HEADER_HTML)
analyse_stmt_btn = gr.Button("Analyse statement", variant="primary")
summary_output = gr.Markdown(value="*Run 'Analyse statement' to generate a financial summary.*")
gr.HTML('')
gr.HTML('Ask a question')
with gr.Row():
bank_question_input = gr.Textbox(
label="Question",
placeholder="e.g., What was the largest debit this month?",
lines=1,
show_label=False,
scale=8,
)
bank_ask_btn = gr.Button("Ask ↵", variant="secondary", scale=2)
bank_label_display = gr.HTML(value=format_label_html("N/A"))
bank_answer_output = gr.Textbox(label="Answer", interactive=False, lines=3)
bank_citation_output = gr.Textbox(label="Citation", interactive=False, lines=2)
bank_reasoning_output = gr.Textbox(label="Reasoning", interactive=False, lines=3)
bank_statement_state = gr.State("")
# ================================================================== #
# Tab 03 — Benchmark #
# ================================================================== #
with gr.Tab("03 Benchmark"):
gr.HTML(BENCH_INTRO_HTML)
gr.Dataframe(
value=BENCHMARK_DF,
headers=list(BENCHMARK_DF.columns),
datatype=["str"] * len(BENCHMARK_DF.columns),
wrap=True,
interactive=False,
)
# ── Footer ──────────────────────────────────────────────────────────── #
gr.HTML(FOOTER_HTML)
# ====================================================================== #
# Event handlers #
# ====================================================================== #
def load_software():
hint = (
''
'💡'
'Suggested: What is the limitation of liability in this agreement?'
'
'
)
return (
SOFTWARE_LICENSE,
SAMPLE_QUESTIONS["software_license.txt"],
gr.update(value=hint, visible=True),
)
def load_nda():
hint = (
''
'💡'
'Suggested: Does this agreement include a non-compete clause?'
'
'
)
return (
NDA,
SAMPLE_QUESTIONS["nda.txt"],
gr.update(value=hint, visible=True),
)
def load_service():
hint = (
''
'💡'
'Suggested: Does this contract include a termination for convenience clause? '
'(expected: ABSENT)'
'
'
)
return (
SERVICE_AGREEMENT,
SAMPLE_QUESTIONS["service_agreement.txt"],
gr.update(value=hint, visible=True),
)
btn_software.click(
fn=load_software,
inputs=[],
outputs=[contract_input, question_input, suggested_q],
)
btn_nda.click(
fn=load_nda,
inputs=[],
outputs=[contract_input, question_input, suggested_q],
)
btn_service.click(
fn=load_service,
inputs=[],
outputs=[contract_input, question_input, suggested_q],
)
analyze_btn.click(
fn=analyze_contract,
inputs=[contract_input, question_input],
outputs=[label_display, answer_output, citation_output, reasoning_output],
)
# Trigger on Enter in question field
question_input.submit(
fn=analyze_contract,
inputs=[contract_input, question_input],
outputs=[label_display, answer_output, citation_output, reasoning_output],
)
# ── Bank Statement handlers ──────────────────────────────────────────── #
btn_load_statement.click(
fn=lambda: SAMPLE_STATEMENT,
inputs=[],
outputs=[bank_paste_input],
)
analyse_stmt_btn.click(
fn=analyse_bank_statement,
inputs=[bank_paste_input, bank_pdf_input, bank_csv_input],
outputs=[summary_output, bank_statement_state],
)
bank_ask_btn.click(
fn=bank_qa,
inputs=[bank_statement_state, bank_question_input],
outputs=[bank_label_display, bank_answer_output, bank_citation_output, bank_reasoning_output],
)
bank_question_input.submit(
fn=bank_qa,
inputs=[bank_statement_state, bank_question_input],
outputs=[bank_label_display, bank_answer_output, bank_citation_output, bank_reasoning_output],
)
if __name__ == "__main__":
demo.launch(show_error=True)