HITL UI for Document Extraction¶

What it is¶

A Human-in-the-Loop (HITL) interface designed to bridge the gap between AI-driven metadata extraction and the final system of record (e.g., Google Calendar, Vikunja, Paperless-ngx). It allows users to review, correct, and approve data before it is permanently committed to the database. It leverages Claude 4.8 and GPT-5.5 for initial processing, with a human gatekeeper for final validation.

What problem it solves¶

LLMs occasionally hallucinate or misinterpret dates and priorities in scanned documents. Automatically pushing these to a calendar can lead to cluttered or incorrect schedules. This UI provides a "staging area" for human verification, ensuring 100% accuracy for critical data like bill due dates or medical appointments. It eliminates the risk of "silent failures" in autonomous workflows.

Where it fits in the stack¶

This interface sits in the Interaction layer of the AI-augmented home office. It acts as an optional "gatekeeper" within a workflow, triggered after the AI Service layer (using Claude 4.8 or GPT-5.5) has processed a document but before the Productivity API layer has written the final result. It is often implemented as a Streamlit app or integrated into the Home Admin UI.

Typical use cases¶

Financial Document Ingestion: Reviewing extracted amounts and account numbers from scanned invoices.
Appointment Capture: Confirming dates and times extracted from medical or school correspondence.
Data Labeling: Using the corrections made in the UI to create a "golden dataset" for fine-tuning future LLM extractions.
Complex Task Delegation: Reviewing a multi-step project plan generated by an agent before it is added to a task manager.

Strengths¶

Accuracy: Human verification eliminates AI hallucinations for high-stakes data.
Speed: Streamlit allows for an extremely fast development-to-deployment cycle for the review interface.
Feedback Loop: Provides a mechanism to capture "ground truth" data for system improvement and future model fine-tuning.
Transparency: Gives the user a clear view of how the AI is interpreting their documents.

Limitations¶

Manual Effort: Requires user time, which can become a bottleneck if document volume is very high.
Latency: The final action (e.g., adding to calendar) is delayed until the human review is complete.
UI Constraints: Reference implementations (like Streamlit) are excellent for functional internal tools but less flexible for complex, highly custom UX/UI designs.

When to use it¶

For high-stakes data where errors have financial or legal consequences (e.g., taxes, medical).
When the LLM confidence score for a specific extraction is below a certain threshold.
During the initial "pilot" phase of an automation to build trust in the AI's performance.

When not to use it¶

For low-priority data where an occasional error is acceptable (e.g., tagging a recipe).
When the extraction logic is proven to be 99%+ accurate over a long period.
For high-velocity automated systems where human intervention is physically impossible or creates unacceptable delays.

Getting started¶

Set up the Environment: Ensure you have the required dependencies for the Home Admin UI.
```
pip install streamlit fastapi pydantic
```
Run the UI: Launch the reference Streamlit implementation.
```
streamlit run scripts/home_admin_ui.py
```
Integrate with n8n: Configure your n8n workflow to send extracted metadata to the staging database instead of directly to the final service.
Agentic Review (MCP): As of July 2026, HITL actions are increasingly exposed via MCP 3.0 servers. An agent (like Claude Code) can detect that a document requires human verification and use an MCP tool to "stage" the document.

CLI examples¶

Running the HITL Backend¶

# Start the FastAPI staging server
uvicorn scripts.hitl_backend:app --reload --port 8000

Staging a document via cURL¶

curl -X POST http://localhost:8000/staged-docs \
     -H "Content-Type: application/json" \
     -d '{
       "source_ref": "DOC_123",
       "original_metadata": {"title": "Water Bill", "due_date": "2026-06-20", "amount": 45.50}
     }'

API examples¶

Approve Document Endpoint (FastAPI)¶

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class MetadataUpdate(BaseModel):
    corrected_metadata: dict

@app.post("/approve/{doc_id}")
async def approve_doc(doc_id: str, update: MetadataUpdate):
    # Logic to move data to Vikunja/Google Calendar
    # Then mark as 'approved' in staging DB
    print(f"Approving {doc_id} with data: {update.corrected_metadata}")
    return {"status": "committed"}

Streamlit HITL Interface Snippet¶

import streamlit as st

st.title("HITL Document Review")
doc = get_next_staged_doc()

if doc:
    st.image(doc['source_url'])
    with st.form("review_form"):
        title = st.text_input("Title", doc['original_metadata']['title'])
        due_date = st.date_input("Due Date", doc['original_metadata']['due_date'])

        if st.form_submit_button("Approve"):
            approve_doc(doc['id'], {"title": title, "due_date": str(due_date)})
            st.success("Approved!")

FastAPI: The recommended backend framework for the HITL service.
n8n: The workflow engine that coordinates the staging and final delivery.
Paperless-ngx: The primary source of document images and metadata.
Google Calendar: A typical final destination for verified data.
Vikunja: For creating tasks after human verification.
Home Admin UI: The reference Streamlit implementation.
Model Context Protocol (MCP): For exposing HITL actions to autonomous agents.

Sources / references¶

Contribution Metadata¶

Last reviewed: 2026-07-21
Confidence: high