Codex: upload Offline Form Pilot Space

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+
+traces/*.json
+traces/*.jsonl
+exports/*.json
+exports/*.csv
+*.log
+
+.env
+.DS_Store

CODEX_BUILD_LOG.md

@@ -0,0 +1,33 @@
+# Codex Build Log
+
+This project is being built with OpenAI Codex as the coding agent for the Build Small Hackathon OpenAI/Codex track.
+
+## Build Principles
+
+- Keep commits small and Codex-attributed.
+- Keep the app review-first: never auto-submit forms.
+- Make model behavior inspectable through structured outputs and traces.
+- Prefer a small-model-friendly workflow over a generic chatbot.
+
+## Timeline
+
+### 2026-06-06
+
+- User selected the form-filling concept.
+- Codex initialized a fresh standalone project under `projects/offline-form-pilot`.
+- Codex added the initial README, build log, requirements, and git hygiene files.
+- Codex implemented the first Gradio app, local structured matcher, optional Hugging Face small-model assist, trace export, and engine tests.
+- Codex ran `pytest` in the project venv and a direct app smoke check.
+- Codex created and pushed the public GitHub repo: https://github.com/rishabhsai/offline-form-pilot
+- Codex confirmed the repo is public and added Hugging Face deployment notes plus a synthetic anonymized trace example.
+- Codex attempted to create the official `build-small-hackathon/offline-form-pilot` Space, but HF returned a 403 for missing namespace creation rights.
+- Codex created the fallback public personal Space: https://huggingface.co/spaces/rishabhsai/offline-form-pilot
+
+## Planned Codex Milestones
+
+1. Scaffold repo and README.
+2. Implement Gradio app and deterministic field matcher.
+3. Add optional small-model backends and trace export.
+4. Add tests and local verification.
+5. Push public GitHub repo with Codex-attributed commits.
+6. Deploy Hugging Face Space after HF auth is available.

DEPLOYMENT.md

@@ -0,0 +1,65 @@
+# Deployment
+
+## GitHub
+
+Public repo:
+
+https://github.com/rishabhsai/offline-form-pilot
+
+The commit history uses Codex-attributed commit messages for the OpenAI/Codex track.
+
+## Hugging Face Space
+
+The local `hf` CLI is installed in the project venv. Authenticate first:
+
+```bash
+source .venv/bin/activate
+hf auth login
+```
+
+If late org access is approved:
+
+```bash
+hf repos create build-small-hackathon/offline-form-pilot --type space --space-sdk gradio --exist-ok
+hf upload build-small-hackathon/offline-form-pilot . --type space \
+  --exclude ".venv/*" \
+  --exclude "traces/*" \
+  --exclude "exports/*" \
+  --commit-message "Codex: upload Offline Form Pilot Space"
+```
+
+If org access is not available, use a personal Space:
+
+```bash
+hf repos create rishabhsai/offline-form-pilot --type space --space-sdk gradio --exist-ok
+hf upload rishabhsai/offline-form-pilot . --type space \
+  --exclude ".venv/*" \
+  --exclude "traces/*" \
+  --exclude "exports/*" \
+  --commit-message "Codex: upload Offline Form Pilot Space"
+```
+
+Current personal Space:
+
+https://huggingface.co/spaces/rishabhsai/offline-form-pilot
+
+After deployment, update `README.md` with the Space URL and push one final Codex-attributed commit to GitHub.
+
+## Space Secrets
+
+For the optional small-model assist mode, add one of these secrets in the Space settings:
+
+- `HF_TOKEN`
+- `HUGGINGFACEHUB_API_TOKEN`
+
+The app still runs without a token using the local structured matcher.
+
+## Demo Checklist
+
+1. Paste a messy form.
+2. Paste safe sample facts.
+3. Run local structured matcher.
+4. Switch to small-model assist if the Space token is configured.
+5. Show ready/review/missing fields.
+6. Show generated questions before copying.
+7. Download trace JSON and field CSV.

FIELD_NOTES.md

@@ -0,0 +1,27 @@
+# Field Notes
+
+## Question
+
+Can a small model make form filling safer and less frustrating by turning messy paperwork into a reviewable field table instead of directly controlling a browser or submitting a form?
+
+## Intended User
+
+One real person who regularly deals with confusing forms or paperwork. The project should name the workflow in the demo without exposing private data.
+
+## What The App Does
+
+- Finds likely fields in pasted form text.
+- Matches user-provided facts to those fields.
+- Separates confident fills from missing or risky fields.
+- Generates plain-English questions for the missing fields.
+- Exports an anonymized trace for review.
+
+## What The App Does Not Do
+
+- It does not submit forms.
+- It does not bypass user review.
+- It does not claim legal, medical, financial, or immigration advice.
+
+## Early Hypothesis
+
+The useful small-model behavior is not "agent fills the website." The useful behavior is "agent prepares a clean checklist the person can verify quickly."

README.md

@@ -1,13 +1,53 @@
 ---
 title: Offline Form Pilot
-emoji: 🐨
-colorFrom: pink
-colorTo: green
+colorFrom: green
+colorTo: blue
 sdk: gradio
 sdk_version: 6.16.0
-python_version: '3.13'
 app_file: app.py
 pinned: false
+license: mit
+short_description: Review confusing forms before copying fields.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Offline Form Pilot
+
+Offline Form Pilot helps a real person fill confusing forms without handing control to an autopilot. Paste a form, paste the facts you are comfortable using, and the app produces a review table with proposed values, confidence, missing fields, and questions to ask before anything is copied.
+
+The app is designed for the Build Small Hackathon:
+
+- **Track:** Backyard AI.
+- **Small model constraint:** default target is a <=4B small model.
+- **Safety posture:** no automatic submission, no hidden form filling, no legal/financial certainty.
+- **Codex track:** this public repo was built with Codex-attributed commits and includes `CODEX_BUILD_LOG.md`.
+
+## Why Small Models Fit
+
+Form help is mostly narrow extraction, matching, and clarification. A small model can do useful work when the interface forces structured fields, review, and missing-information checks.
+
+## Local Run
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+## Deployment
+
+See `DEPLOYMENT.md` for the GitHub and Hugging Face Space commands.
+
+## Submission Checklist
+
+- Public GitHub repo linked from this README.
+- Hugging Face Space link added after deployment.
+- Short demo video.
+- Social post.
+- Field notes.
+- Optional trace dataset with anonymized examples.
+
+## Repository Links
+
+- GitHub: https://github.com/rishabhsai/offline-form-pilot
+- Hugging Face Space: https://huggingface.co/spaces/rishabhsai/offline-form-pilot

app.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+import pandas as pd
+
+from formpilot.engine import analyze_form, export_trace, rows_to_csv
+from formpilot.model_assist import DEFAULT_SMALL_MODEL, try_hf_model_assist
+
+
+APP_DIR = Path(__file__).resolve().parent
+TRACE_DIR = APP_DIR / "traces"
+EXPORT_DIR = APP_DIR / "exports"
+TRACE_DIR.mkdir(exist_ok=True)
+EXPORT_DIR.mkdir(exist_ok=True)
+
+SAMPLE_FORM = """Community Center Membership Form
+
+Full name: ____________________
+Email: ____________________
+Phone: ____________________
+Address: ____________________
+Emergency contact: ____________________
+Relationship: ____________________
+Signature: ____________________
+Date: ____________________
+"""
+
+SAMPLE_FACTS = """Full name: Jordan Lee
+Email: jordan.lee@example.com
+Phone: 555-0137
+Address: 42 Maple Street, Springfield, NY 10027
+Emergency contact: Priya Lee
+Relationship: Sister
+Date: June 6, 2026
+"""
+
+CSS = """
+.gradio-container {
+  max-width: 1240px !important;
+}
+#hero {
+  padding: 8px 0 16px 0;
+  border-bottom: 1px solid #d7dde5;
+}
+#hero h1 {
+  font-size: 34px;
+  line-height: 1.05;
+  letter-spacing: 0;
+  margin: 0 0 8px 0;
+}
+#hero p {
+  color: #5b6470;
+  max-width: 860px;
+  font-size: 15px;
+}
+.status-ready {
+  color: #1f6f4a;
+  font-weight: 700;
+}
+.status-review {
+  color: #9a6500;
+  font-weight: 700;
+}
+.status-missing {
+  color: #a33d3d;
+  font-weight: 700;
+}
+.panel-note {
+  border: 1px solid #d7dde5;
+  border-radius: 8px;
+  background: #ffffff;
+  padding: 12px 14px;
+}
+"""
+
+
+def _status_html(rows: list[dict[str, Any]], risks: list[str]) -> str:
+    ready = sum(1 for row in rows if row["status"] == "ready")
+    review = sum(1 for row in rows if row["status"] == "review")
+    missing = sum(1 for row in rows if row["status"] == "missing")
+    risk_items = "".join(f"<li>{risk}</li>" for risk in risks)
+    return f"""
+<div class="panel-note">
+  <p><span class="status-ready">{ready} ready</span> · <span class="status-review">{review} review</span> · <span class="status-missing">{missing} missing</span></p>
+  <ul>{risk_items}</ul>
+</div>
+"""
+
+
+def _write_export_files(payload: dict[str, Any]) -> tuple[str, str]:
+    trace_path = export_trace(payload, TRACE_DIR)
+    csv_path = EXPORT_DIR / "formpilot_latest_fields.csv"
+    csv_path.write_text(rows_to_csv(payload["rows"]), encoding="utf-8")
+    return trace_path, str(csv_path)
+
+
+def _model_payload_to_rows(model_payload: dict[str, Any]) -> list[dict[str, Any]]:
+    rows = model_payload.get("fields", [])
+    normalized = []
+    for row in rows:
+        normalized.append(
+            {
+                "field": str(row.get("field", "")),
+                "proposed_value": str(row.get("proposed_value", "")),
+                "status": str(row.get("status", "review")),
+                "confidence": int(row.get("confidence", 0) or 0),
+                "source": str(row.get("source", "")),
+                "note": str(row.get("note", "")),
+            }
+        )
+    return normalized
+
+
+def run_pilot(
+    form_text: str,
+    user_facts: str,
+    mode: str,
+    model_id: str,
+) -> tuple[pd.DataFrame, str, str, str, dict[str, Any], str, str]:
+    if not form_text.strip():
+        raise gr.Error("Paste a form or request first.")
+
+    payload = analyze_form(form_text, user_facts)
+    backend_note = "Local structured matcher"
+
+    if mode == "Small model assist":
+        try:
+            model_payload = try_hf_model_assist(form_text, user_facts, model_id.strip() or DEFAULT_SMALL_MODEL)
+            model_rows = _model_payload_to_rows(model_payload)
+            if model_rows:
+                payload["rows"] = model_rows
+                payload["questions"] = model_payload.get("questions", payload["questions"])
+                payload["risk_summary"] = model_payload.get("risk_summary", payload["risk_summary"])
+                payload["copy_ready"] = "\n".join(
+                    f"{row['field']}: {row['proposed_value'] or '[NEEDS USER INPUT]'}"
+                    for row in model_rows
+                )
+                backend_note = f"Small model assist: {model_id.strip() or DEFAULT_SMALL_MODEL}"
+        except Exception as exc:
+            payload["risk_summary"].insert(
+                0,
+                f"Small model assist failed; used local matcher instead. Reason: {exc}",
+            )
+
+    payload["backend"] = backend_note
+    trace_path, csv_path = _write_export_files(payload)
+
+    rows = payload["rows"]
+    table = pd.DataFrame(rows, columns=["field", "proposed_value", "status", "confidence", "source", "note"])
+    questions = "\n".join(f"- {question}" for question in payload["questions"]) or "No missing-field questions detected."
+    summary = _status_html(rows, payload["risk_summary"])
+    return table, payload["copy_ready"], questions, summary, payload, trace_path, csv_path
+
+
+def clear_outputs() -> tuple[pd.DataFrame, str, str, str, dict[str, Any], None, None]:
+    return pd.DataFrame(), "", "", "", {}, None, None
+
+
+def build_demo() -> gr.Blocks:
+    with gr.Blocks(title="Offline Form Pilot") as demo:
+        gr.Markdown(
+            """
+# Offline Form Pilot
+Paste a form and the facts you are willing to use. The app prepares a review table, missing-field questions, and copy-ready text without submitting anything.
+""",
+            elem_id="hero",
+        )
+
+        with gr.Row():
+            with gr.Column(scale=5):
+                form_text = gr.Textbox(
+                    label="Form or request text",
+                    value=SAMPLE_FORM,
+                    lines=12,
+                    max_lines=18,
+                )
+                user_facts = gr.Textbox(
+                    label="User facts",
+                    value=SAMPLE_FACTS,
+                    lines=10,
+                    max_lines=16,
+                )
+            with gr.Column(scale=3):
+                mode = gr.Radio(
+                    label="Analysis mode",
+                    choices=["Local structured matcher", "Small model assist"],
+                    value="Local structured matcher",
+                )
+                model_id = gr.Textbox(label="Small model id", value=DEFAULT_SMALL_MODEL)
+                run_btn = gr.Button("Prepare form review", variant="primary")
+                clear_btn = gr.Button("Clear outputs")
+                gr.Markdown(
+                    """
+Human review is required. Do not paste secrets unless you are comfortable with the selected backend.
+""",
+                    elem_classes=["panel-note"],
+                )
+
+        summary = gr.HTML()
+        table = gr.Dataframe(
+            label="Review table",
+            headers=["field", "proposed_value", "status", "confidence", "source", "note"],
+            wrap=True,
+            interactive=False,
+        )
+        with gr.Row():
+            copy_ready = gr.Textbox(label="Copy-ready draft", lines=10, buttons=["copy"])
+            questions = gr.Textbox(label="Questions before copying", lines=10, buttons=["copy"])
+        with gr.Accordion("Trace and exports", open=False):
+            raw_json = gr.JSON(label="Trace JSON")
+            trace_file = gr.File(label="Download trace JSON")
+            csv_file = gr.File(label="Download field CSV")
+
+        run_btn.click(
+            run_pilot,
+            inputs=[form_text, user_facts, mode, model_id],
+            outputs=[table, copy_ready, questions, summary, raw_json, trace_file, csv_file],
+            api_name="prepare_form_review",
+        )
+        clear_btn.click(
+            clear_outputs,
+            outputs=[table, copy_ready, questions, summary, raw_json, trace_file, csv_file],
+        )
+
+    return demo
+
+
+demo = build_demo()
+
+
+if __name__ == "__main__":
+    demo.launch(css=CSS)

examples/anonymized_trace.jsonl

@@ -0,0 +1 @@
+{"case_id":"community_center_demo","input_type":"pasted_text","form_fields":["Full name","Email","Phone","Address","Emergency contact","Relationship","Signature","Date"],"available_facts":["full name","email","phone","address","emergency contact","relationship","date"],"outcome":{"ready":7,"review":0,"missing":1},"missing_fields":["Signature"],"note":"Synthetic trace for demo and Sharing is Caring badge planning."}

formpilot/__init__.py

@@ -0,0 +1,5 @@
+"""Offline Form Pilot package."""
+
+from formpilot.engine import analyze_form
+
+__all__ = ["analyze_form"]

formpilot/engine.py

@@ -0,0 +1,328 @@
+"""Structured form analysis for Offline Form Pilot."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import re
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any
+
+
+COMMON_FIELDS = [
+    "full name",
+    "first name",
+    "last name",
+    "date of birth",
+    "email",
+    "phone",
+    "address",
+    "city",
+    "state",
+    "postal code",
+    "zip code",
+    "country",
+    "employer",
+    "school",
+    "student id",
+    "account number",
+    "policy number",
+    "emergency contact",
+    "relationship",
+    "signature",
+    "date",
+]
+
+SENSITIVE_TERMS = {
+    "ssn",
+    "social security",
+    "passport",
+    "bank",
+    "routing",
+    "account",
+    "card",
+    "credit",
+    "medical",
+    "diagnosis",
+    "tax",
+    "visa",
+    "immigration",
+}
+
+STOPWORDS = {
+    "the",
+    "a",
+    "an",
+    "your",
+    "you",
+    "of",
+    "for",
+    "and",
+    "or",
+    "to",
+    "in",
+    "on",
+    "with",
+    "please",
+    "enter",
+    "provide",
+}
+
+
+@dataclass(frozen=True)
+class FieldMatch:
+    field: str
+    proposed_value: str
+    status: str
+    confidence: int
+    source: str
+    note: str
+
+
+def normalize_label(text: str) -> str:
+    """Normalize labels for fuzzy matching."""
+
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9]+", " ", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def _tokens(text: str) -> set[str]:
+    return {token for token in normalize_label(text).split() if token not in STOPWORDS}
+
+
+def parse_user_facts(raw_facts: str) -> dict[str, str]:
+    """Parse key-value facts from pasted user notes."""
+
+    facts: dict[str, str] = {}
+    free_lines: list[str] = []
+    for line in raw_facts.splitlines():
+        cleaned = line.strip().strip("-*")
+        if not cleaned:
+            continue
+        match = re.match(r"^([^:=]{2,60})\s*[:=]\s*(.+)$", cleaned)
+        if match:
+            key = normalize_label(match.group(1))
+            value = match.group(2).strip()
+            facts[key] = value
+        else:
+            free_lines.append(cleaned)
+
+    inferred = infer_facts_from_free_text("\n".join(free_lines))
+    for key, value in inferred.items():
+        facts.setdefault(key, value)
+    return facts
+
+
+def infer_facts_from_free_text(text: str) -> dict[str, str]:
+    """Extract a small set of common facts from unstructured text."""
+
+    facts: dict[str, str] = {}
+    email = re.search(r"[\w.+-]+@[\w.-]+\.[a-zA-Z]{2,}", text)
+    if email:
+        facts["email"] = email.group(0)
+
+    phone = re.search(r"(?:\+?\d[\d .()-]{7,}\d)", text)
+    if phone:
+        facts["phone"] = phone.group(0).strip()
+
+    zip_code = re.search(r"\b\d{5}(?:-\d{4})?\b", text)
+    if zip_code:
+        facts["zip code"] = zip_code.group(0)
+        facts["postal code"] = zip_code.group(0)
+
+    dob = re.search(r"\b(?:dob|date of birth)\s*[:=]?\s*([A-Za-z0-9, /.-]{6,20})", text, re.I)
+    if dob:
+        facts["date of birth"] = dob.group(1).strip()
+
+    return facts
+
+
+def detect_fields(form_text: str) -> list[str]:
+    """Find likely form fields from pasted form text."""
+
+    candidates: list[str] = []
+
+    for line in form_text.splitlines():
+        cleaned = line.strip()
+        if not cleaned:
+            continue
+        cleaned = re.sub(r"\s+", " ", cleaned)
+
+        label_match = re.match(r"^([A-Za-z][A-Za-z0-9 /'().,-]{1,70})\s*[:_]{1,}\s*(?:\[\s*\])?\s*$", cleaned)
+        if label_match:
+            candidates.append(label_match.group(1))
+            continue
+
+        bracket_match = re.match(r"^([A-Za-z][A-Za-z0-9 /'().,-]{1,70})\s*\[\s*\]\s*$", cleaned)
+        if bracket_match:
+            candidates.append(bracket_match.group(1))
+            continue
+
+        inline_match = re.match(r"^([A-Za-z][A-Za-z0-9 /'().,-]{1,45})\s*:\s+_{2,}", cleaned)
+        if inline_match:
+            candidates.append(inline_match.group(1))
+
+    lowered_form = normalize_label(form_text)
+    for common in COMMON_FIELDS:
+        if common in lowered_form:
+            candidates.append(common)
+
+    unique: list[str] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        label = normalize_label(candidate)
+        if len(label) < 2 or label in seen:
+            continue
+        seen.add(label)
+        unique.append(candidate.strip(" :_"))
+    return unique
+
+
+def match_field(field: str, facts: dict[str, str]) -> FieldMatch:
+    """Match one field label to available user facts."""
+
+    field_norm = normalize_label(field)
+    field_tokens = _tokens(field)
+    best_key = ""
+    best_score = 0.0
+
+    for key in facts:
+        key_tokens = _tokens(key)
+        overlap = len(field_tokens & key_tokens) / max(1, len(field_tokens | key_tokens))
+        ratio = SequenceMatcher(None, field_norm, key).ratio()
+        score = max(overlap, ratio * 0.85)
+        if score > best_score:
+            best_key = key
+            best_score = score
+
+    if not best_key:
+        return _missing_match(field, "No matching user fact found.")
+
+    value = facts[best_key]
+    sensitive = is_sensitive_field(field)
+    if best_score >= 0.86 or field_norm == best_key:
+        confidence = 95 if not sensitive else 84
+        status = "review" if sensitive else "ready"
+        note = "Strong label match."
+    elif best_score >= 0.58:
+        confidence = int(best_score * 100)
+        status = "review"
+        note = f"Possible match from '{best_key}'."
+    else:
+        return _missing_match(field, "No close enough user fact found.")
+
+    if sensitive:
+        note += " Sensitive field: verify manually before copying."
+
+    return FieldMatch(
+        field=field,
+        proposed_value=value,
+        status=status,
+        confidence=confidence,
+        source=best_key,
+        note=note,
+    )
+
+
+def _missing_match(field: str, note: str) -> FieldMatch:
+    return FieldMatch(
+        field=field,
+        proposed_value="",
+        status="missing",
+        confidence=0,
+        source="",
+        note=note,
+    )
+
+
+def is_sensitive_field(field: str) -> bool:
+    label = normalize_label(field)
+    return any(term in label for term in SENSITIVE_TERMS)
+
+
+def questions_for_missing(matches: list[FieldMatch]) -> list[str]:
+    """Generate plain-English follow-up questions for missing fields."""
+
+    questions = []
+    for match in matches:
+        if match.status == "missing":
+            questions.append(f"What should go in '{match.field}'?")
+    return questions
+
+
+def _risk_summary(matches: list[FieldMatch]) -> list[str]:
+    risks = []
+    missing = sum(1 for match in matches if match.status == "missing")
+    review = sum(1 for match in matches if match.status == "review")
+    sensitive = sum(1 for match in matches if is_sensitive_field(match.field))
+    if missing:
+        risks.append(f"{missing} field(s) still need information.")
+    if review:
+        risks.append(f"{review} field(s) should be reviewed before copying.")
+    if sensitive:
+        risks.append(f"{sensitive} sensitive field(s) detected.")
+    if not risks:
+        risks.append("All detected fields have proposed values, but user review is still required.")
+    return risks
+
+
+def analyze_form(form_text: str, user_facts: str, use_demo_fields: bool = True) -> dict[str, Any]:
+    """Analyze form text and facts into reviewable outputs."""
+
+    fields = detect_fields(form_text)
+    if not fields and use_demo_fields:
+        fields = ["Full name", "Email", "Phone", "Address", "Date", "Signature"]
+
+    facts = parse_user_facts(user_facts)
+    matches = [match_field(field, facts) for field in fields]
+    rows = [asdict(match) for match in matches]
+    return {
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "fields": fields,
+        "facts": facts,
+        "rows": rows,
+        "questions": questions_for_missing(matches),
+        "risk_summary": _risk_summary(matches),
+        "copy_ready": copy_ready_text(matches),
+    }
+
+
+def copy_ready_text(matches: list[FieldMatch]) -> str:
+    """Create a conservative copy-ready field list."""
+
+    lines = []
+    for match in matches:
+        value = match.proposed_value if match.proposed_value else "[NEEDS USER INPUT]"
+        flag = " REVIEW" if match.status == "review" else ""
+        lines.append(f"{match.field}: {value}{flag}")
+    return "\n".join(lines)
+
+
+def export_trace(payload: dict[str, Any], directory: Path | str = "traces") -> str:
+    """Write one anonymizable JSON trace and return its path."""
+
+    out_dir = Path(directory)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = out_dir / f"formpilot_trace_{stamp}.json"
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return str(path)
+
+
+def rows_to_csv(rows: list[dict[str, Any]]) -> str:
+    """Serialize rows for quick export."""
+
+    output = io.StringIO()
+    writer = csv.DictWriter(
+        output,
+        fieldnames=["field", "proposed_value", "status", "confidence", "source", "note"],
+    )
+    writer.writeheader()
+    writer.writerows(rows)
+    return output.getvalue()

formpilot/model_assist.py

@@ -0,0 +1,73 @@
+"""Optional small-model assist for form analysis."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+
+DEFAULT_SMALL_MODEL = os.getenv("FORMPILOT_MODEL", "openbmb/MiniCPM5-1B")
+
+
+def build_model_prompt(form_text: str, user_facts: str) -> str:
+    """Prompt a small model to return conservative form-fill JSON."""
+
+    return f"""You are helping prepare a form for human review. Do not submit anything.
+
+Return only JSON with this schema:
+{{
+  "fields": [
+    {{
+      "field": "field label",
+      "proposed_value": "value or empty string",
+      "status": "ready|review|missing",
+      "confidence": 0,
+      "source": "fact used or empty",
+      "note": "short reason"
+    }}
+  ],
+  "questions": ["questions for missing fields"],
+  "risk_summary": ["review warnings"]
+}}
+
+Rules:
+- Use only the user facts.
+- If a value is absent, mark missing.
+- Sensitive fields must be review, not ready.
+- Never invent account numbers, IDs, dates, signatures, addresses, or legal facts.
+
+FORM:
+{form_text}
+
+USER FACTS:
+{user_facts}
+"""
+
+
+def try_hf_model_assist(form_text: str, user_facts: str, model_id: str = DEFAULT_SMALL_MODEL) -> dict[str, Any]:
+    """Call a small Hugging Face model and parse its JSON response."""
+
+    try:
+        from huggingface_hub import InferenceClient
+    except ImportError as exc:
+        raise RuntimeError("huggingface_hub is not installed.") from exc
+
+    token = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN")
+    client = InferenceClient(model=model_id, token=token)
+    prompt = build_model_prompt(form_text, user_facts)
+    response = client.text_generation(
+        prompt,
+        max_new_tokens=700,
+        temperature=0.1,
+        return_full_text=False,
+    )
+    return _parse_json_response(str(response))
+
+
+def _parse_json_response(raw: str) -> dict[str, Any]:
+    start = raw.find("{")
+    end = raw.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError("Model did not return a JSON object.")
+    return json.loads(raw[start : end + 1])

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=6.16.0
+pandas>=2.2.0
+pydantic>=2.0.0
+huggingface_hub>=0.32.0
+pytest>=8.0.0

tests/test_engine.py

@@ -0,0 +1,32 @@
+from formpilot.engine import analyze_form, detect_fields, parse_user_facts
+
+
+def test_detect_fields_from_underlined_form() -> None:
+    form = """
+    Full name: ____________
+    Email: ________________
+    Emergency contact: ____
+    """
+    assert detect_fields(form) == ["Full name", "Email", "Emergency contact"]
+
+
+def test_parse_user_facts_key_values_and_free_text() -> None:
+    facts = parse_user_facts(
+        """
+        Name: Jordan Lee
+        jordan.lee@example.com
+        Phone: 555-0137
+        """
+    )
+    assert facts["name"] == "Jordan Lee"
+    assert facts["email"] == "jordan.lee@example.com"
+    assert facts["phone"] == "555-0137"
+
+
+def test_analyze_form_marks_missing_fields() -> None:
+    payload = analyze_form("Full name: ____\nEmail: ____\nSignature: ____", "Full name: Jordan Lee")
+    rows = {row["field"]: row for row in payload["rows"]}
+    assert rows["Full name"]["status"] == "ready"
+    assert rows["Email"]["status"] == "missing"
+    assert rows["Signature"]["status"] == "missing"
+    assert payload["questions"]