Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

feat: add agentic form filler workspace

Tiioluwani02126d472afe
diff --git a/agentic-form-filler/.gitignore b/agentic-form-filler/.gitignore
new file mode 100644
index 0000000..08a566d
--- /dev/null
+++ b/agentic-form-filler/.gitignore
@@ -0,0 +1,27 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.venv/
+env/
+venv/
+ENV/
+
+# Configuration
+.env
+
+# Session Data & Backups (User Specific)
+sessions/
+*.log
+
+# Temp Files
+temp*.pdf
+*.tmp
+
+# IDE Metadata
+.idea/
+.vscode/
+*.swp
+*.swo
diff --git a/agentic-form-filler/README.md b/agentic-form-filler/README.md
new file mode 100644
index 0000000..e789245
--- /dev/null
+++ b/agentic-form-filler/README.md
@@ -0,0 +1,76 @@
+# πŸ“ Form-Fill AI: Pro Workspace
+
+A powerful, agentic form-filling application that uses **Landing AI** for Layout Parsing and **MiniMax M2.7** for multi-turn conversational data gathering. Features a cinematic "Live Inking" engine for visual document stamping and a full dual-pane audit workflow.
+
+---
+
+## 🎨 Key Features
+
+* **9-Step "Agentic" Workflow**: A structured journey from Document Analysis to Final Export.
+* **Conversational Data Gathering**: Talk to the Agent to provide missing information via a persistent chat interface.
+* **Flicker-Free Live Auto-Filling**: Watch the document update in real-time as the Agent "inks" the fields without browser flickering.
+* **Dual-Pane Verification**: Compare the original blank form and the final result side-by-side.
+* **Session Persistence**: Every workspace is saved locally. Refreshing your browser or restarting the app will restore your progress perfectly via URL-based Session IDs.
+* **History Explorer**: A sidebar gallery to manage and toggle between multiple active forms.
+
+---
+
+## 🏎️ The 9-Step Journey
+
+1. **Upload**: Provide the target form (PDF/Image) and optional source context (CV/ID).
+2. **Analysis**: Landing AI parses the physical layout and detects interactive fields.
+3. **Extraction**: The Agent extracts values from your source documents.
+4. **Audit**: The Agent reports what was found and what is still missing.
+5. **Conversation**: Fill in missing gaps or clarify information via the chat interface.
+6. **The Trigger**: Once details are complete, the user triggers the "Visual Auto-Fill".
+7. **Auto-Filling**: A cinematic live-action loop "paints" the PDF field-by-field.
+8. **Verification**: A high-resolution side-by-side audit of the Original vs. Filled PDF.
+9. **Export**: Download the finalized PDF or the raw JSON data registry.
+
+---
+
+## πŸ› οΈ Setup & Installation
+
+### 1. Prerequisites
+You will need API keys for the following services:
+* **Landing AI**: For high-accuracy Document extraction.
+* **MiniMax**: For the M2.7 LLM conversation and logic.
+
+### 2. Environment Configuration
+Create a `.env` file in the root directory:
+```env
+VISION_AGENT_API_KEY=your_landing_ai_key
+MINIMAX_API_KEY=your_minimax_key
+MINIMAX_GROUP_ID=your_minimax_group_id
+```
+
+### 3. Install Dependencies
+```bash
+python -m venv .venv
+source .venv/bin/activate # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+---
+
+## πŸš€ How to Run
+
+1. Start the application using the provides batch script (Windows):
+ ```cmd
+ run.cmd
+ ```
+ *Or run manually via:*
+ ```bash
+ streamlit run app.py
+ ```
+2. Upload the provided `sample_complex_employment_application.pdf` to see the Agent in action!
+
+---
+
+## πŸ—οΈ Technology Stack
+
+* **Frontend**: Streamlit (Python-based Web Framework)
+* **Layout Engine**: Landing AI (Vision Agent API)
+* **Intelligence**: MiniMax M2.7 (Large Language Model)
+* **Document Engine**: PyMuPDF (Fitz)
+* **Persistence**: URL-based State Synchronization & JSON Storage
diff --git a/agentic-form-filler/app.py b/agentic-form-filler/app.py
new file mode 100644
index 0000000..f38948d
--- /dev/null
+++ b/agentic-form-filler/app.py
@@ -0,0 +1,370 @@
+import streamlit as st
+import os
+import tempfile
+import json
+import uuid
+import base64
+import datetime
+from dotenv import load_dotenv
+
+from extractor import extract_form_data
+from llm import extract_form_and_prefill, validate_field_input, chat_and_update_fields_stream
+from pdf_filler import get_pdf_field_names, create_field_mapping, fill_pdf_with_mapping, render_pdf_to_image
+
+load_dotenv()
+st.set_page_config(page_title="Form-Fill AI: Workspace", page_icon="πŸ“", layout="wide")
+
+SESSION_DIR = "sessions"
+os.makedirs(SESSION_DIR, exist_ok=True)
+
+def save_session():
+ if "session_id" in st.session_state:
+ filepath = os.path.join(SESSION_DIR, f"{st.session_state.session_id}.json")
+ dump = {
+ "form_state": st.session_state.get("form_state", {}),
+ "chat_history": st.session_state.get("chat_history", []),
+ "target_pdf_path": st.session_state.get("target_pdf_path"),
+ "target_filename": st.session_state.get("target_filename"),
+ "live_fill_complete": st.session_state.get("live_fill_complete", False),
+ "pdf_bytes_b64": base64.b64encode(st.session_state.get("pdf_bytes")).decode('utf-8') if st.session_state.get("pdf_bytes") else None,
+ "timestamp": datetime.datetime.now().isoformat(),
+ "form_name": st.session_state.get("target_filename")
+ }
+ with open(filepath, "w") as f:
+ json.dump(dump, f)
+
+def load_session(sid: str):
+ filepath = os.path.join(SESSION_DIR, f"{sid}.json")
+ if os.path.exists(filepath):
+ with open(filepath, "r", encoding="utf-8") as f:
+ data = json.load(f)
+ st.session_state.form_state = data.get("form_state", {})
+ st.session_state.chat_history = data.get("chat_history", [])
+ st.session_state.target_pdf_path = data.get("target_pdf_path")
+ st.session_state.target_filename = data.get("target_filename")
+ st.session_state.live_fill_complete = data.get("live_fill_complete", False)
+ pb64 = data.get("pdf_bytes_b64")
+ if pb64:
+ st.session_state.pdf_bytes = base64.b64decode(pb64)
+
+def get_session_history():
+ """Scans the sessions folder and returns sorted metadata."""
+ history = []
+ if not os.path.exists(SESSION_DIR):
+ return []
+ for f in os.listdir(SESSION_DIR):
+ if f.endswith(".json"):
+ sid = f.replace(".json", "")
+ try:
+ with open(os.path.join(SESSION_DIR, f), "r") as json_f:
+ data = json.load(json_f)
+ # We only show sessions that have at least some data
+ if data.get("target_filename") or data.get("form_state"):
+ m_time = os.path.getmtime(os.path.join(SESSION_DIR, f))
+ history.append({
+ "id": sid,
+ "name": data.get("target_filename", sid),
+ "time": data.get("timestamp"),
+ "mtime": m_time
+ })
+ except Exception:
+ continue
+ # Sort by mtime descending
+ return sorted(history, key=lambda x: x["mtime"], reverse=True)
+
+# State Initialization
+if "session_id" not in st.session_state:
+ qp = st.query_params
+ if "session" in qp:
+ st.session_state.session_id = qp["session"]
+ load_session(qp["session"])
+ else:
+ new_id = str(uuid.uuid4())[:8]
+ st.session_state.session_id = new_id
+ st.query_params["session"] = new_id
+
+if "form_state" not in st.session_state:
+ st.session_state.form_state = {}
+if "chat_history" not in st.session_state:
+ st.session_state.chat_history = []
+if "target_pdf_path" not in st.session_state:
+ st.session_state.target_pdf_path = None
+if "target_markdown" not in st.session_state:
+ st.session_state.target_markdown = ""
+if "source_markdown" not in st.session_state:
+ st.session_state.source_markdown = ""
+if "ready_to_generate" not in st.session_state:
+ st.session_state.ready_to_generate = False
+if "field_mapping" not in st.session_state:
+ st.session_state.field_mapping = {}
+if "is_live_filling" not in st.session_state:
+ st.session_state.is_live_filling = False
+if "current_filling_idx" not in st.session_state:
+ st.session_state.current_filling_idx = -1
+if "live_fill_complete" not in st.session_state:
+ st.session_state.live_fill_complete = False
+if "pdf_bytes" not in st.session_state:
+ st.session_state.pdf_bytes = None
+
+def render_pdf_iframe(pdf_source, height=700):
+ if pdf_source is None:
+ return st.warning("PDF data is still being processed or is currently unavailable.")
+
+ if isinstance(pdf_source, bytes):
+ b64 = base64.b64encode(pdf_source).decode('utf-8')
+ else:
+ with open(pdf_source, "rb") as f:
+ b64 = base64.b64encode(f.read()).decode('utf-8')
+ pdf_html = f'<iframe src="data:application/pdf;base64,{b64}#toolbar=0" width="100%" height="{height}" type="application/pdf" style="border:1px solid #D1D5DB; border-radius:8px;"></iframe>'
+ st.markdown(pdf_html, unsafe_allow_html=True)
+
+# 🎩 Activity Tracker
+st.title("πŸ“ Form-Fill AI: Workspace")
+
+if not st.session_state.form_state:
+ st.info("πŸ‘‹ Welcome! Start by uploading your documents in the sidebar.")
+else:
+ # 🏎️ Stepper Logic
+ s1, s2, s3, s4 = st.columns(4)
+ with s1:
+ st.write("βœ… 1. Analysis")
+ with s2:
+ st.write("πŸ”΅ 2. Conversation" if not st.session_state.get("live_fill_complete") else "βœ… 2. Conversation")
+ with s3:
+ st.write("πŸ”΅ 3. Auto-Filling" if st.session_state.get("is_live_filling") else ("βœ… 3. Auto-Filling" if st.session_state.get("live_fill_complete") else "βšͺ 3. Auto-Filling"))
+ with s4:
+ st.write("🏁 4. Ready" if st.session_state.get("live_fill_complete") else "βšͺ 4. Final Review")
+ st.divider()
+
+# Sidebar Config
+with st.sidebar:
+ st.header("1. Upload Documents")
+ target_form = st.file_uploader("Target Blank Form (PDF/Img)", type=["pdf", "png", "jpg", "jpeg"], key="target")
+ source_doc = st.file_uploader("Source Data Context (CV, ID)", type=["pdf", "png", "jpg", "jpeg"], key="source")
+
+ if st.button("πŸš€ Extract & Pre-Fill", use_container_width=True):
+ st.session_state.pop("pdf_bytes", None)
+ if not target_form:
+ st.error("Target Form is required!")
+ elif not os.environ.get("VISION_AGENT_API_KEY") or not os.environ.get("MINIMAX_API_KEY"):
+ st.error("Ensure API keys are provided in your .env file.")
+ else:
+ with st.spinner("Extracting Target Layout (Landing AI)..."):
+ with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as t1:
+ t1.write(target_form.getvalue())
+ target_path = t1.name
+ st.session_state.target_markdown = extract_form_data(target_path)
+ st.session_state.target_pdf_path = target_path # Persist the file for final PDF rendering
+ st.session_state.target_filename = target_form.name
+
+ src_md = ""
+ if source_doc:
+ with st.spinner("Extracting Source Document (Landing AI)..."):
+ with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as t2:
+ t2.write(source_doc.getvalue())
+ src_path = t2.name
+ src_md = extract_form_data(src_path)
+ st.session_state.source_markdown = src_md
+ os.unlink(src_path)
+
+ with st.spinner("Minimax M2.7 is Mapping Fields..."):
+ extracted_dict = extract_form_and_prefill(st.session_state.target_markdown, src_md)
+
+ # Build rich state dict
+ st.session_state.form_state = {}
+ for k, v in extracted_dict.items():
+ if k == "READY_TO_GENERATE":
+ st.session_state.ready_to_generate = bool(v)
+ continue
+ if v and str(v).strip():
+ st.session_state.form_state[k] = {"value": str(v), "source": "AUTO", "status": "FILLED"}
+ else:
+ st.session_state.form_state[k] = {"value": "", "source": "MISSING", "status": "MISSING"}
+
+ # Pre-calculate internal PDF field mapping for fast live stamping
+ with st.spinner("Preparing Live Stamping Engine..."):
+ pdf_names = get_pdf_field_names(st.session_state.target_pdf_path)
+ st.session_state.field_mapping = create_field_mapping(list(st.session_state.form_state.keys()), pdf_names)
+
+ # Proactive AI Chat Initialization
+ st.session_state.chat_history = []
+ missing_keys = [k for k, v in st.session_state.form_state.items() if v["status"] == "MISSING"]
+ if missing_keys:
+ msg = "I successfully extracted the context! However, I still need your inputs for the following missing fields:\n"
+ for m in missing_keys:
+ msg += f"- **{m}**\n"
+ msg += "\nPlease provide them here so I can seamlessly complete the document."
+ st.session_state.chat_history.append({"role": "assistant", "content": msg})
+ else:
+ msg = "Excellent! I was able to successfully extract and map every single field from your source document. I am generating your final PDF now!"
+ st.session_state.chat_history.append({"role": "assistant", "content": msg})
+
+ # Save the explicitly initialized session state to disk!
+ save_session()
+
+ # πŸ“š Session History Section
+ st.divider()
+ st.subheader("πŸ“š Recent Forms")
+ history = get_session_history()
+ if not history:
+ st.caption("No previous forms found.")
+ else:
+ for item in history[:8]: # Show last 8 sessions
+ t_str = ""
+ if item["time"]:
+ try:
+ dt = datetime.datetime.fromisoformat(item["time"])
+ t_str = dt.strftime("%b %d, %H:%M")
+ except:
+ t_str = ""
+ else:
+ # Fallback to file mtime
+ dt = datetime.datetime.fromtimestamp(item["mtime"])
+ t_str = dt.strftime("%b %d, %H:%M")
+
+ label = f"πŸ“„ {item['name'][:20]}... ({t_str})" if len(item['name']) > 20 else f"πŸ“„ {item['name']} ({t_str})"
+ if st.button(label, key=f"hist_{item['id']}", use_container_width=True):
+ # FORCE RELOAD MORPHING
+ st.session_state.session_id = item["id"]
+ st.query_params["session"] = item["id"]
+ load_session(item["id"])
+ st.rerun()
+
+# Main Content Area
+# Step 3 & 4: Data Collection Phase
+if st.session_state.get("form_state") and not st.session_state.get("is_live_filling") and not st.session_state.get("live_fill_complete"):
+ main_col, side_col = st.columns([1.5, 1])
+
+ with side_col:
+ st.subheader("πŸ€– AI Agent")
+ chat_container = st.container(height=500)
+ with chat_container:
+ for msg in st.session_state.chat_history:
+ with st.chat_message(msg["role"]):
+ st.write(msg["content"])
+
+ with st.expander("πŸ“Š Logical Data Registry", expanded=True):
+ registry_df = []
+ for k, v in st.session_state.form_state.items():
+ registry_df.append({
+ "Field": k,
+ "Value": v["value"] if v["status"] != "SKIPPED" else "⏩ SKIPPED",
+ "Status": "βœ… READY" if v["status"] != "MISSING" else "❌ MISSING"
+ })
+ st.table(registry_df)
+
+ missing_keys = [k for k, v in st.session_state.form_state.items() if v["status"] == "MISSING"]
+ is_complete = len(missing_keys) == 0
+
+ if is_complete or st.session_state.get("ready_to_generate"):
+ st.success("🎯 I've gathered all necessary information!")
+ if st.button("πŸš€ Step 6: Start Auto-Filling!", type="primary", use_container_width=True):
+ st.session_state["is_live_filling"] = True
+ st.rerun()
+
+ if prompt := st.chat_input("Ex: My SSN is 111-22-3333"):
+ st.session_state.chat_history.append({"role": "user", "content": prompt})
+
+ with chat_container:
+ st.chat_message("user").write(prompt)
+ with st.chat_message("assistant"):
+ stream_gen, result_ref = chat_and_update_fields_stream(st.session_state.chat_history, st.session_state.get("form_state"))
+
+ # Dynamic Interlaced Loop
+ message_placeholder = st.empty()
+ full_reply = ""
+
+ for signal in stream_gen:
+ stype = signal[0]
+ if stype == "TEXT":
+ full_reply += signal[1]
+ message_placeholder.markdown(full_reply + "β–Œ")
+ elif stype == "FIELD_UPDATE":
+ fid, val = signal[1], signal[2]
+ fs = st.session_state.get("form_state")
+ if fid in fs:
+ if val == "[[BLANK]]":
+ fs[fid]["value"] = ""
+ fs[fid]["status"] = "SKIPPED"
+ else:
+ fs[fid]["value"] = str(val)
+ fs[fid]["status"] = "FILLED"
+
+ message_placeholder.markdown(full_reply)
+ updates = result_ref.get("updates_json", {})
+ if "READY_TO_GENERATE" in updates:
+ st.session_state["ready_to_generate"] = bool(updates["READY_TO_GENERATE"])
+
+ st.session_state.chat_history.append({"role": "assistant", "content": full_reply})
+ save_session()
+ st.rerun()
+
+ with main_col:
+ st.subheader("πŸ“„ Original Document")
+ render_pdf_iframe(st.session_state.get("target_pdf_path"), height=750)
+
+# Step 7: Live Action Painting (Flicker-Free Mode)
+elif st.session_state.get("is_live_filling"):
+ import time
+ st.markdown("<h2 style='text-align: center;'>⚑ AI Agent: Writing to PDF...</h2>", unsafe_allow_html=True)
+
+ # Progress & Log
+ all_fields = [f for f in st.session_state.form_state.items() if f[1]["status"] != "SKIPPED"]
+ total = len(all_fields)
+ progress_bar = st.progress(0)
+ log_slot = st.empty()
+ img_slot = st.empty()
+
+ current_data = {}
+ for i, (fid, fmeta) in enumerate(all_fields):
+ log_slot.markdown(f"🎨 **Painting field:** `{fid}`... ({i+1}/{total})")
+ current_data[fid] = fmeta["value"]
+
+ # 1. Fill logical doc
+ filled_bytes = fill_pdf_with_mapping(st.session_state.target_pdf_path, current_data, st.session_state.field_mapping)
+
+ # 2. Convert to Image for FLICKER-FREE UI (Step 7)
+ img_bytes = render_pdf_to_image(filled_bytes)
+ img_slot.image(img_bytes, use_column_width=True)
+
+ progress_bar.progress((i + 1) / total)
+ time.sleep(0.4)
+
+ # Finalize
+ st.session_state.pdf_bytes = filled_bytes
+ st.session_state.live_fill_complete = True
+ st.session_state.is_live_filling = False
+ save_session()
+ st.rerun()
+
+# Step 8 & 9: Verification & Export Mode
+elif st.session_state.get("live_fill_complete"):
+ st.success("βœ… Form Successfully Filled! Please perform your final review below.")
+
+ # Dual Feed (Verification Table View)
+ v_col1, v_col2 = st.columns(2)
+ with v_col1:
+ st.subheader("πŸ“„ Original Blank")
+ render_pdf_iframe(st.session_state.get("target_pdf_path"), height=800)
+ with v_col2:
+ st.subheader("✨ Filled Final")
+ render_pdf_iframe(st.session_state.get("pdf_bytes"), height=800)
+
+ st.divider()
+
+ # Export Toolbar
+ e1, e2, e3 = st.columns([1, 1, 1])
+ with e1:
+ json_export = json.dumps({k: v["value"] for k, v in st.session_state.form_state.items()}, indent=4)
+ st.download_button("πŸ“‚ Export JSON Data", data=json_export, file_name="form_data.json", use_container_width=True)
+ with e2:
+ if st.session_state.get("pdf_bytes"):
+ base_name = os.path.splitext(st.session_state.get("target_filename", "form"))[0]
+ st.download_button("πŸ“„ Download Final PDF", data=st.session_state.get("pdf_bytes"), file_name=f"{base_name}_filled.pdf", type="primary", use_container_width=True)
+ with e3:
+ if st.button("πŸ”„ Start New Form", use_container_width=True):
+ st.query_params.clear()
+ st.session_state.clear()
+ st.rerun()
+else:
+ st.info("πŸ‘ˆ Please upload your Target Form and Context (optional) in the sidebar and click Extract to begin.")
diff --git a/agentic-form-filler/extractor.py b/agentic-form-filler/extractor.py
new file mode 100644
index 0000000..67769d4
--- /dev/null
+++ b/agentic-form-filler/extractor.py
@@ -0,0 +1,22 @@
+import os
+from pathlib import Path
+from landingai_ade import LandingAIADE
+
+def extract_form_data(file_path: str) -> str:
+ """
+ Extracts purely semantic text, form fields, and structure from a document
+ using the Landing AI Agentic Document Extraction (ADE) SDK.
+ """
+ api_key = os.environ.get("VISION_AGENT_API_KEY", "").strip()
+ if not api_key:
+ raise ValueError("VISION_AGENT_API_KEY is not set.")
+
+ client = LandingAIADE(apikey=api_key)
+ response = client.parse(document=Path(file_path), model="dpt-2-latest")
+
+ if hasattr(response, 'markdown') and response.markdown:
+ return response.markdown
+ elif hasattr(response, 'text') and response.text:
+ return response.text
+ else:
+ return str(response)
diff --git a/agentic-form-filler/llm.py b/agentic-form-filler/llm.py
new file mode 100644
index 0000000..01849e1
--- /dev/null
+++ b/agentic-form-filler/llm.py
@@ -0,0 +1,161 @@
+import os
+import json
+import re
+from openai import OpenAI
+
+def get_client() -> OpenAI:
+ api_key = os.environ.get("MINIMAX_API_KEY", "").strip()
+ if not api_key:
+ raise ValueError("MINIMAX_API_KEY is not set.")
+ return OpenAI(api_key=api_key, base_url="https://api.minimaxi.chat/v1")
+
+def _parse_json_safely(text: str) -> dict:
+ # Strip out '<think>...</think>' blocks generated by reasoning models
+ cleaned = re.sub(r'<think>[\s\S]*?</think>', '', text)
+ cleaned = re.sub(r'```json\n?', '', cleaned)
+ cleaned = re.sub(r'```', '', cleaned).strip()
+ try:
+ return json.loads(cleaned)
+ except Exception as e:
+ print(f"JSON Parsing Error: {e}\nRaw output: {text}")
+ return {}
+
+def extract_form_and_prefill(form_markdown: str, context_markdown: str = "") -> dict:
+ """Mode A: Extracts form schema and maps context info if available."""
+ client = get_client()
+ system_prompt = (
+ "You are an expert form filling assistant.\n"
+ "1. Extract all logical form fields from the provided 'Form Layout'.\n"
+ "2. If 'Context Data' is provided, intelligently map the context into the identified form fields.\n"
+ "3. Output ONLY valid JSON where keys are the field names and values are the extracted value (or empty string if missing).\n"
+ )
+
+ user_prompt = f"--- Form Layout ---\n{form_markdown}\n"
+ if context_markdown:
+ user_prompt += f"\n--- Context Data ---\n{context_markdown}\n"
+
+ response = client.chat.completions.create(
+ model="MiniMax-M2.7",
+ messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+ temperature=1.0, top_p=0.95
+ )
+ return _parse_json_safely(response.choices[0].message.content)
+
+def validate_field_input(field_name: str, raw_input: str) -> str:
+ """Mode B: Canonicalize short manual inputs (formatting, capitalization, etc)."""
+ client = get_client()
+ system_prompt = (
+ "You are a strict data validation format tool. "
+ "Fix capitalization, spelling, and standard formatting for the user's manual input for the specific form field. "
+ "Output ONLY the corrected text string directly. No explanations."
+ )
+ user_prompt = f"Field: {field_name}\nRaw Input: {raw_input}"
+
+ response = client.chat.completions.create(
+ model="MiniMax-M2.7",
+ messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+ temperature=0.1, top_p=0.95
+ )
+ return response.choices[0].message.content.strip()
+
+def chat_and_update_fields_stream(chat_history: list, current_state: dict) -> tuple:
+ """Mode C: Process user chat and stream dynamically to UI."""
+ client = get_client()
+ missing_fields = [k for k, v in current_state.items() if not v["value"]]
+
+ system_prompt = (
+ "You are a conversational form-filling assistant answering the user.\n"
+ f"The user needs to fill out these missing fields: {missing_fields}\n"
+ "Review the conversation history and naturally ask the user for missing info, or answer their questions.\n"
+ "\n"
+ "SPECIAL PROTOCOLS:\n"
+ "1. SKIPPING FIELDS: If a user explicitly asks to leave a field blank or skip it, map that field in your JSON as '[[BLANK]]'.\n"
+ "2. READY TO GENERATE: If ALL fields are now either filled or marked as '[[BLANK]]', include a top-level key 'READY_TO_GENERATE': true in your UPDATES JSON. Otherwise set it to false.\n"
+ "\n"
+ "You MUST output exactly two distinct blocks in this exact format:\n\n"
+ "REPLY:\n<your conversational response to the user>\n"
+ "UPDATES:\n```json\n<JSON dict including 'READY_TO_GENERATE' and any field updates logic. Return {'READY_TO_GENERATE': false} if no field updates.>\n```"
+ )
+
+ messages = [{"role": "system", "content": system_prompt}]
+ for msg in chat_history:
+ messages.append({"role": msg["role"], "content": msg["content"]})
+
+ response = client.chat.completions.create(
+ model="MiniMax-M2.7",
+ messages=messages,
+ temperature=1.0, top_p=0.95,
+ stream=True
+ )
+
+ result_ref = {"updates_json": {}}
+
+ def generator():
+ buffer = ""
+ in_think = False
+ in_reply = False
+ in_updates = False
+ updates_buffer = ""
+ last_found_fields = set()
+
+ for chunk in response:
+ if not chunk.choices or not chunk.choices[0].delta.content:
+ continue
+
+ token = chunk.choices[0].delta.content
+ buffer += token
+
+ if not in_think and "<think>" in buffer:
+ in_think = True
+ buffer = buffer.split("<think>")[-1]
+ continue
+
+ if in_think:
+ if "</think>" in buffer:
+ in_think = False
+ buffer = buffer.split("</think>")[-1]
+ continue
+
+ if in_updates:
+ updates_buffer += token
+ # Live extract fields from buffer
+ # Look for "key": "value" patterns
+ # This regex catches simple string values.
+ matches = re.findall(r'"([^"]+)":\s*"([^"]*)"', updates_buffer)
+ for k, v in matches:
+ if k not in last_found_fields and k != "READY_TO_GENERATE":
+ yield ("FIELD_UPDATE", k, v)
+ last_found_fields.add(k)
+ continue
+
+ if "REPLY:" in buffer:
+ in_reply = True
+ buffer = buffer.replace("REPLY:", "").lstrip()
+
+ if "UPDATES:" in buffer:
+ in_updates = True
+ parts = buffer.split("UPDATES:")
+ if parts[0]:
+ yield ("TEXT", parts[0])
+ updates_buffer += parts[1] if len(parts) > 1 else ""
+ buffer = ""
+ continue
+
+ if in_reply:
+ if len(buffer) > 15:
+ safe_len = len(buffer) - 10
+ yield ("TEXT", buffer[:safe_len])
+ buffer = buffer[safe_len:]
+
+ if buffer and not in_updates and not in_think:
+ yield ("TEXT", buffer)
+
+ if updates_buffer:
+ result_ref["updates_json"] = _parse_json_safely(updates_buffer)
+ # Final check for any missed fields (like non-string values or trailing)
+ final_json = result_ref["updates_json"]
+ for k, v in final_json.items():
+ if k not in last_found_fields and k != "READY_TO_GENERATE":
+ yield ("FIELD_UPDATE", k, v)
+
+ return generator(), result_ref
diff --git a/agentic-form-filler/pdf_filler.py b/agentic-form-filler/pdf_filler.py
new file mode 100644
index 0000000..8cda85e
--- /dev/null
+++ b/agentic-form-filler/pdf_filler.py
@@ -0,0 +1,77 @@
+import fitz
+import os
+import json
+from llm import get_client, _parse_json_safely
+
+def get_pdf_field_names(pdf_path: str) -> list:
+ """Extract all interactive field names from a PDF."""
+ doc = fitz.open(pdf_path)
+ fields = []
+ for page in doc:
+ for widget in page.widgets():
+ if widget.field_name:
+ fields.append(widget.field_name)
+ doc.close()
+ return list(set(fields))
+
+def render_pdf_to_image(pdf_bytes) -> bytes:
+ """Renders the first page of a PDF to a high-resolution PNG."""
+ doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+ page = doc[0]
+ # Zoom for high-res (2x)
+ mat = fitz.Matrix(2, 2)
+ pix = page.get_pixmap(matrix=mat)
+ img_bytes = pix.tobytes("png")
+ doc.close()
+ return img_bytes
+
+def create_field_mapping(logical_keys: list, pdf_field_names: list) -> dict:
+ """Use LLM once to create a translation map between logical names and PDF internal names."""
+ client = get_client()
+ sys_prompt = (
+ "You are a PDF mapping specialist. You will be given a list of 'Logical Field Names' (from an extraction) "
+ "and a list of 'Internal PDF Field Names'.\n"
+ "Your job is to create a 1-to-1 mapping JSON where the KEY is the Logical Name and the VALUE is the Internal PDF Name.\n"
+ "Only map fields that clearly correspond. Return an empty JSON {} if no matches are found."
+ )
+ user_prompt = f"Logical Names: {logical_keys}\nPDF Names: {pdf_field_names}"
+
+ response = client.chat.completions.create(
+ model="MiniMax-M2.7",
+ messages=[{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_prompt}],
+ temperature=0.1
+ )
+ return _parse_json_safely(response.choices[0].message.content)
+
+def fill_pdf_with_mapping(input_pdf_path: str, data: dict, mapping: dict) -> bytes:
+ """Fast, non-LLM stamping using a pre-calculated map. Returns PDF bytes."""
+ doc = fitz.open(input_pdf_path)
+
+ # Invert mapping for easier lookup: Logical -> Internal
+ # Data is {Logical: Value}
+
+ fields_filled = 0
+ for page in doc:
+ for widget in page.widgets():
+ internal_name = widget.field_name
+ # Find which logical key maps to this internal name
+ logical_key = next((k for k, v in mapping.items() if v == internal_name), None)
+
+ if logical_key and logical_key in data:
+ val = data[logical_key]
+ if val is not None:
+ widget.field_value = str(val)
+ widget.update()
+ fields_filled += 1
+
+ pdf_bytes = doc.write()
+ doc.close()
+ return pdf_bytes
+
+def fill_pdf_form(input_pdf_path: str, data: dict, output_pdf_path: str):
+ """Legacy wrapper for compatibility - combines mapping and filling."""
+ pdf_fields = get_pdf_field_names(input_pdf_path)
+ mapping = create_field_mapping(list(data.keys()), pdf_fields)
+ pdf_bytes = fill_pdf_with_mapping(input_pdf_path, data, mapping)
+ with open(output_pdf_path, "wb") as f:
+ f.write(pdf_bytes)
diff --git a/agentic-form-filler/requirements.txt b/agentic-form-filler/requirements.txt
new file mode 100644
index 0000000..3af3156
--- /dev/null
+++ b/agentic-form-filler/requirements.txt
@@ -0,0 +1,5 @@
+landingai-ade
+streamlit
+openai
+python-dotenv
+pandas
diff --git a/agentic-form-filler/run.cmd b/agentic-form-filler/run.cmd
new file mode 100644
index 0000000..a00756b
--- /dev/null
+++ b/agentic-form-filler/run.cmd
@@ -0,0 +1,4 @@
+@echo off
+echo Starting Streamlit Form Filling App...
+call .venv\Scripts\activate.bat
+streamlit run app.py