feat: add sponsor model strategy selector

README.md

@@ -23,6 +23,7 @@ GitHub repo: [awilliams88/neighbordocs](https://github.com/awilliams88/neighbord
 
 - Accepts a PDF, TXT, or MD upload plus optional user notes.
 - Extracts readable text from the first pages of a PDF.
+- Lets the user choose a sponsor-aligned model strategy.
 - Shows an extracted-text preview.
 - Produces a plain-English summary and next-step checklist.
 
@@ -47,9 +48,10 @@ Award surfaces:
 | Model or tool | Role | Status | Parameter count |
 | --- | --- | --- | --- |
 | `pypdf` | Basic PDF text extraction | Active | Not a model |
-| `nvidia/NVIDIA-Nemotron-Parse-v1.1` | Layout-aware PDF/PPT extraction | Planned | <1B class |
+| `nvidia/NVIDIA-Nemotron-Parse-v1.1` | Layout-aware PDF/PPT extraction | Recommended path | <1B |
 | Small text reasoner | Summary, obligations, deadlines, next actions | Planned | <=4B target |
-| `openbmb/MiniCPM-V-4.6` | Optional scanned-image/document understanding | Candidate | 1B class |
+| `openbmb/MiniCPM-V-4.6` | Scanned-image/document understanding | Candidate | 1B class |
+| Cohere tiny multilingual LLM family | Translation and local-language explanation | Candidate | 3.3B class |
 
 The final model list will stay within the hackathon rule that every model must
 be under 32B total parameters. The first planned sponsor path is NVIDIA
@@ -60,6 +62,7 @@ Nemotron Parse because document extraction is central to the product.
 ```text
 Upload + notes
   -> file type router
+  -> sponsor model strategy selector
   -> PDF/text extraction
   -> extracted text preview
   -> model or rule-based document interpreter
@@ -72,6 +75,7 @@ Key files:
 - `src/neighbordocs/config.py` - app constants, URLs, and model plan.
 - `src/neighbordocs/core.py` - document extraction and analysis logic.
 - `src/neighbordocs/ui.py` - Gradio layout and event wiring.
+- `examples/` - sample demo documents for judges and screenshots.
 - `requirements.txt` - runtime dependencies.
 - `run.sh` - setup, lint, format, verify, and local app launch.
 

examples/sample_bill.txt

@@ -0,0 +1,10 @@
+City Utilities
+Statement Date: June 3, 2026
+Account: 1047-5521
+Amount Due: $82.40
+Due Date: June 18, 2026
+
+Your previous balance was paid in full. This bill covers electricity and water
+service from May 1 through May 31. A late fee of $8.00 may be charged if payment
+is received after the due date. Call customer support if the amount looks wrong
+or if you need a payment extension.

examples/school_notice.txt

@@ -0,0 +1,8 @@
+Riverside Middle School
+Family Notice
+
+The seventh grade field trip is scheduled for Friday, June 12, 2026. Students
+must bring a signed permission slip, packed lunch, water bottle, and comfortable
+shoes. Buses leave at 8:30 AM and return by 3:15 PM. Permission slips are due by
+Tuesday, June 9. Contact the front office if your child needs medication support
+or transportation help.

requirements.txt

@@ -1 +1,3 @@
+gradio==6.16.0
 pypdf==6.13.0
+ruff==0.15.16

run.sh

@@ -13,7 +13,6 @@ setup() {
   # shellcheck disable=SC1091
   source .venv/bin/activate
   python -m pip install --disable-pip-version-check -r requirements.txt
-  python -m pip install --disable-pip-version-check gradio==6.16.0 ruff==0.15.16
 }
 
 ensure_venv() {

src/neighbordocs/config.py

@@ -6,27 +6,45 @@ APP_DESCRIPTION = "Plain-English help for everyday paperwork."
 SUPPORTED_SUFFIXES = {".pdf", ".txt", ".md"}
 PDF_PAGE_LIMIT = 3
 PREVIEW_LIMIT = 2000
+DEFAULT_MODEL_KEY = "nvidia_parse"
 
 GITHUB_URL = "https://github.com/awilliams88/neighbordocs"
 SPACE_URL = "https://huggingface.co/spaces/build-small-hackathon/neighbordocs"
 
-MODEL_PLAN = [
-    {
-        "name": "pypdf",
-        "role": "Basic PDF text extraction",
-        "status": "active",
-        "parameters": "not a model",
+MODEL_CHOICES = {
+    "nvidia_parse": {
+        "label": "NVIDIA Nemotron Parse + tiny reasoner",
+        "model": "nvidia/NVIDIA-Nemotron-Parse-v1.1",
+        "parameters": "<1B parser + <=4B reasoner target",
+        "sponsor": "NVIDIA",
+        "best_for": "Forms, bills, reports, tables, structured PDFs, and document intelligence.",
+        "status": "recommended path",
     },
-    {
-        "name": "nvidia/NVIDIA-Nemotron-Parse-v1.1",
-        "role": "Planned layout-aware document parsing",
-        "status": "planned",
-        "parameters": "<1B class",
+    "openbmb_vision": {
+        "label": "OpenBMB MiniCPM-V document vision",
+        "model": "openbmb/MiniCPM-V-4.6",
+        "parameters": "1B class",
+        "sponsor": "OpenBMB",
+        "best_for": "Image uploads, screenshots, scanned paperwork, OCR-heavy documents.",
+        "status": "candidate path",
     },
-    {
-        "name": "Small <=4B text reasoner",
-        "role": "Planned summary, obligations, deadlines, and next actions",
-        "status": "planned",
+    "cohere_multilingual": {
+        "label": "Cohere tiny multilingual explanation",
+        "model": "Cohere tiny multilingual LLM family",
+        "parameters": "3.3B class",
+        "sponsor": "Cohere",
+        "best_for": "Translation, multilingual summaries, cross-lingual paperwork help.",
+        "status": "candidate path",
+    },
+    "tiny_local": {
+        "label": "Tiny local reasoner",
+        "model": "MiniCPM 1B / <=4B local text model",
         "parameters": "<=4B target",
+        "sponsor": "Tiny Titan / Off the Grid",
+        "best_for": "Small CPU/ZeroGPU-friendly summary and checklist generation.",
+        "status": "badge path",
     },
-]
+}
+
+MODEL_LABELS = [choice["label"] for choice in MODEL_CHOICES.values()]
+MODEL_KEY_BY_LABEL = {choice["label"]: key for key, choice in MODEL_CHOICES.items()}

src/neighbordocs/core.py

@@ -5,12 +5,20 @@ from pathlib import Path
 
 from pypdf import PdfReader
 
-from .config import PDF_PAGE_LIMIT, PREVIEW_LIMIT, SUPPORTED_SUFFIXES
+from .config import (
+    DEFAULT_MODEL_KEY,
+    MODEL_CHOICES,
+    MODEL_KEY_BY_LABEL,
+    PDF_PAGE_LIMIT,
+    PREVIEW_LIMIT,
+    SUPPORTED_SUFFIXES,
+)
 
 
 @dataclass(frozen=True)
 class DocumentReport:
     preview: str
+    model_path: str
     summary: str
     checklist: str
 
@@ -32,15 +40,31 @@ def extract_text(file_path: str | None) -> str:
     return f"Unsupported file type: {suffix or 'unknown'}. Try one of: {allowed}."
 
 
-def analyze_document(file_path: str | None, notes: str) -> DocumentReport:
+def analyze_document(
+    file_path: str | None,
+    notes: str,
+    model_label: str | None,
+) -> DocumentReport:
     text = extract_text(file_path)
     preview = text[:PREVIEW_LIMIT] if text else "No readable text found."
     user_context = notes.strip()
+    model_choice = get_model_choice(model_label)
 
-    summary = _build_summary(text, user_context)
-    checklist = _build_checklist(text, user_context)
+    model_path = _build_model_path(model_choice)
+    summary = _build_summary(text, user_context, model_choice)
+    checklist = _build_checklist(text, user_context, model_choice)
 
-    return DocumentReport(preview=preview, summary=summary, checklist=checklist)
+    return DocumentReport(
+        preview=preview,
+        model_path=model_path,
+        summary=summary,
+        checklist=checklist,
+    )
+
+
+def get_model_choice(model_label: str | None) -> dict[str, str]:
+    key = MODEL_KEY_BY_LABEL.get(model_label or "", DEFAULT_MODEL_KEY)
+    return MODEL_CHOICES[key]
 
 
 def _extract_pdf_text(path: Path) -> str:
@@ -50,14 +74,27 @@ def _extract_pdf_text(path: Path) -> str:
     return text or "No text could be extracted from the PDF."
 
 
-def _build_summary(text: str, notes: str) -> str:
+def _build_model_path(model_choice: dict[str, str]) -> str:
+    return "\n".join(
+        [
+            f"Selected path: {model_choice['label']}",
+            f"Primary model: {model_choice['model']}",
+            f"Sponsor surface: {model_choice['sponsor']}",
+            f"Parameter compliance: {model_choice['parameters']}",
+            f"Status: {model_choice['status']}",
+        ]
+    )
+
+
+def _build_summary(text: str, notes: str, model_choice: dict[str, str]) -> str:
     if not text or text == "No file uploaded.":
         return "Upload a document to generate a plain-English explanation."
 
     bullets = [
-        "This first version extracts readable document text and prepares it for small-model reasoning.",
-        "The final app will explain the document, surface obligations, and identify dates or next actions.",
-        "The next implementation step is adding the selected sponsor model path from the README.",
+        "Readable document text was extracted and prepared for small-model reasoning.",
+        f"Recommended sponsor path: {model_choice['label']}.",
+        f"Why this path fits: {model_choice['best_for']}",
+        "The final model-backed version will explain the document, surface obligations, and identify dates or next actions.",
     ]
 
     if notes:
@@ -66,7 +103,7 @@ def _build_summary(text: str, notes: str) -> str:
     return "\n".join(f"- {bullet}" for bullet in bullets)
 
 
-def _build_checklist(text: str, notes: str) -> str:
+def _build_checklist(text: str, notes: str, model_choice: dict[str, str]) -> str:
     if not text or text == "No file uploaded.":
         return "- Upload a PDF, TXT, or MD file."
 
@@ -74,6 +111,7 @@ def _build_checklist(text: str, notes: str) -> str:
         "Confirm the document type and sender.",
         "Look for due dates, payment amounts, signatures, or missing attachments.",
         "Ask a follow-up question if any term or obligation is unclear.",
+        f"Use the selected model path for: {model_choice['best_for']}",
     ]
 
     if notes:

src/neighbordocs/ui.py

@@ -2,7 +2,15 @@ from __future__ import annotations
 
 import gradio as gr
 
-from .config import APP_DESCRIPTION, APP_TITLE, GITHUB_URL, SPACE_URL
+from .config import (
+    APP_DESCRIPTION,
+    APP_TITLE,
+    DEFAULT_MODEL_KEY,
+    GITHUB_URL,
+    MODEL_CHOICES,
+    MODEL_LABELS,
+    SPACE_URL,
+)
 from .core import analyze_document
 
 
@@ -21,25 +29,57 @@ def create_app() -> gr.Blocks:
                 placeholder="Example: explain this bill and tell me what I need to do next.",
             )
 
+        model_input = gr.Dropdown(
+            choices=MODEL_LABELS,
+            value=MODEL_CHOICES[DEFAULT_MODEL_KEY]["label"],
+            label="Model strategy",
+            interactive=True,
+        )
+
         run_button = gr.Button("Analyze", variant="primary")
 
         with gr.Row():
             extracted_output = gr.Textbox(label="Extracted text", lines=12)
+            model_output = gr.Textbox(label="Selected model path", lines=8)
+
+        with gr.Row():
             summary_output = gr.Textbox(label="Plain-English summary", lines=12)
+            checklist_output = gr.Textbox(label="Next-action checklist", lines=12)
 
-        checklist_output = gr.Textbox(label="Next-action checklist", lines=8)
+        gr.Examples(
+            examples=[
+                [
+                    "examples/sample_bill.txt",
+                    "Explain what I owe and what happens next.",
+                ],
+                [
+                    "examples/school_notice.txt",
+                    "Summarize what a parent needs to remember.",
+                ],
+            ],
+            inputs=[file_input, notes_input],
+        )
 
         gr.Markdown(f"[GitHub repo]({GITHUB_URL}) | [Hugging Face Space]({SPACE_URL})")
 
         run_button.click(
             fn=_analyze_for_ui,
-            inputs=[file_input, notes_input],
-            outputs=[extracted_output, summary_output, checklist_output],
+            inputs=[file_input, notes_input, model_input],
+            outputs=[
+                extracted_output,
+                model_output,
+                summary_output,
+                checklist_output,
+            ],
         )
 
     return demo
 
 
-def _analyze_for_ui(file_path: str | None, notes: str) -> tuple[str, str, str]:
-    report = analyze_document(file_path, notes)
-    return report.preview, report.summary, report.checklist
+def _analyze_for_ui(
+    file_path: str | None,
+    notes: str,
+    model_label: str | None,
+) -> tuple[str, str, str, str]:
+    report = analyze_document(file_path, notes, model_label)
+    return report.preview, report.model_path, report.summary, report.checklist