Multi-Agentic Data-Management Workflow

A local-first, multi-agent workflow for B2B contact data management: business-card ingestion, approval-gated database remediation (public verification + deduplication), and personalized outreach with RSVP tracking.

Architecture framing: a multi-agent workflow of 4 specialized agents coordinated through shared database state and human-in-the-loop (HITL) approval gates. Agents are event-triggered and sequentially dependent between stages — not a parallel orchestration runtime. Agent loops live at the harness level (graders, policy gates, feedback memory); model calls are single-shot with bounded rule-based retry. Models are stateless; the harness is stateful via persistent file-based state.

The Four Agents

Sprint	Agent	What it does
Sprint 1	Card ingestion & triage	VLM/Tesseract OCR → LLM classification (8 categories) → fuzzy duplicate check → Excel persistence
Sprint 2 · Step 1	Public verification	Public-source research adapters (Perplexity / SiliconFlow) verify contact facts; review-gated; citation-backed evidence
Sprint 2 · Step 2	Deduplication	Deterministic candidate generation + scoring; LLM judge adjudicates ambiguous pairs only; approval-gated merge execution with rollback
Sprint 3	Outreach & RSVP	Natural-language query → filtered lists → personalized email drafts (public evidence only) with LLM tone scoring → RSVP parsing

Guardrails: no agent self-approves a HITL gate; VIP/CRM data never leaves the machine (only verified public evidence reaches LLM providers); every merge flows through MergeExecutor with stale-plan detection and rollback.

Layout

Path	Purpose
IST_CD/	Flask + HTMX local web app (UI + Excel persistence)
POC/sprint_1/	Ingestion: capture, OCR, classify, dedup, enrich
POC/sprint_2/	Remediation: verification adapters, Step 2 service, merge executor
POC/dedup_agent/	Dedup agent core: candidates → scoring → LLM judge → merge plans
POC/sprint_3/	Outreach: query filter, drafting, tone evaluation, RSVP
POC/tests/	Test suite

Install

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt   # Windows
# source .venv/bin/activate && pip install -r requirements.txt   # macOS/Linux

Requirements: Python 3.10+, Tesseract OCR with chi_sim + chi_tra + eng language packs (installed via the Tesseract installer — see DEPLOYMENT.md §4.1), and API keys via environment variables (copy .env.template to .env).

Run & Test

python -m IST_CD.serve          # start the local web app
pytest POC/tests/ POC/sprint_1/tests/ POC/sprint_2/tests/ POC/sprint_3/tests/ -v
ruff check POC/ IST_CD/

See DEPLOYMENT.md for full deployment, and MIGRATION_POSTGRESQL.md for moving storage from Excel/SQLite to PostgreSQL.