README.md

metadata

title: CredentialWatch
emoji: 🛡️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
python_version: 3.11

CredentialWatch 🛡️

CredentialWatch is a demo product for the "MCP 1st Birthday / Gradio Agents Hackathon" (Hugging Face).

0. What I’m building (TL;DR)

• Domain: US-style healthcare admin / provider credentialing & expiries (state licenses, board certs, DEA/CDS, malpractice, hospital privileges, etc.).
• Goal: Show how Model Context Protocol (MCP) + LangGraph agents + Gradio + Modal + SQLite can turn messy, fragmented credential data into:
  • One unified, queryable view of each provider, and
  • A proactive alerting system for expiring / at-risk credentials.
• Constraint: Use only open / public tools & APIs (no closed vendor APIs, no real PHI).

1. Problem & motivation

Real-world (simplified):

• Provider groups (clinics, hospitals, multi-specialty practices) have dozens of contracts with different health plans and institutions.
• Multiple credentials can expire or go stale:
  • State licenses, board certifications, DEA/CDS numbers,
  • Malpractice insurance,
  • Hospital privileges, etc.
• Today:
  • Each health plan / hospital sends its own emails / portal tasks asking to update credentials and directory data.
  • Staff maintain local spreadsheets, trackers, email threads, often with inconsistent formats.
• It’s easy to miss an expiry, leading to:
  • Compliance issues,
  • Denied claims (revenue loss),
  • Inability to schedule or bill a provider after a certain date.

CredentialWatch acts as a central radar:

“For all my providers, tell me what’s expiring when, what’s high risk, and log alerts we can action.”

2. Solution concept

CredentialWatch provides:

• A single, internal “source-of-truth” SQLite DB for providers, credentials and alerts.
• Three separate MCP servers (strict separation of concerns, each can be its own HF Space/repo):
  1. npi_mcp → read-only public provider info from NPPES NPI Registry API.
  2. cred_db_mcp → internal provider & credential DB operations.
  3. alert_mcp → alert logging, listing & resolution.
• A LangGraph-based agent that:
  • Periodically runs an expiry sweep and logs alerts.
  • Answers free-text questions like:
    • “Who has credentials expiring in the next 60 days in Cardiology?”
    • “Show me the credential snapshot for Dr. Jane Doe.”
• A Gradio UI where:
  • Judges/users chat with the agent,
  • They can click a “Run Nightly Sweep” button,
  • They see tables for “expiring soon” and an Alert Inbox.

3. Hackathon & design constraints

• Event: Hugging Face – MCP 1st Birthday / Gradio Agents Hackathon.
• Judging goals:
  • Strong MCP usage (tools/resources as first-class interfaces).
  • Agentic sophistication: planning, multi-step tool use, long-running flows.
  • Clear UX/Teachability.

Constraints & safety:

• Only public / open APIs (NPPES NPI Registry, OpenAI GPT).
• No real PHI: use synthetic/internal IDs + public NPI data.
• Safety boundaries:
  • Read-only to external systems.
  • Writes only to internal SQLite DB.

4. Tech stack 🧱

• Language: Python 3.11
• Package management: uv
• Frontend / UI: Gradio 6 (Hosted as a Hugging Face Space)
• Agents: LangGraph (Python)
• LLM: OpenAI gpt-5.1 (or gpt-4o)
• Tool protocol: Model Context Protocol (MCP), via SSE.
• Backend web framework: FastAPI, running on Modal.
• Database: SQLite, persisted on a Modal volume.
• ORM: SQLAlchemy 2.x.

5. Architecture overview 🧩

Logical components

HF Space #1 – Agent UI (credentialwatch-agent-ui)

• Gradio frontend.
• LangGraph agent runtime (expiry_sweep_graph, interactive_query_graph).
• MCP client configured for 3 remote MCP servers (via SSE).

HF Space #2 – npi_mcp

• MCP server for NPI/NPPES tools (search_providers, get_provider_by_npi).
• Calls NPI_API FastAPI service on Modal.

HF Space #3 – cred_db_mcp

• MCP server for internal data tools (sync_provider_from_npi, add_or_update_credential, etc.).
• Calls CRED_API FastAPI service on Modal.

HF Space #4 – alert_mcp

• MCP server for alert tools (log_alert, get_open_alerts, etc.).
• Calls ALERT_API FastAPI service on Modal.

Modal backend

• FastAPI microservices: NPI_API, CRED_API, ALERT_API.
• Shared SQLite DB on a Modal volume.

6. The 3 MCP servers – separation of concerns 🧱

6.1 npi_mcp

Read-only access to public provider data.

• search_providers(query, state?, taxonomy?)
• get_provider_by_npi(npi)

6.2 cred_db_mcp

Interface to internal provider & credential data.

• sync_provider_from_npi(npi)
• add_or_update_credential(...)
• list_expiring_credentials(...)
• get_provider_snapshot(...)

6.3 alert_mcp

Manage alerts generated by the agent.

• log_alert(...)
• get_open_alerts(...)
• mark_alert_resolved(...)

7. Agent behaviors (LangGraph) 🧠

7.1 expiry_sweep_graph

Batch / nightly graph.

1. Call cred_db_mcp.list_expiring_credentials.
2. Decide severity.
3. Call alert_mcp.log_alert.

7.2 interactive_query_graph

Chat / Q&A graph (ReAct-style).

• Plans tool calls (NPI, DB, Alerts).
• Summarizes results.

8. Database model 🗄️

DB engine: SQLite on Modal volume.

• providers: Internal provider records.
• credentials: Licenses, certifications, etc.
• alerts: Generated alerts for expiries.

---

How to Run Locally

To run the CredentialWatch Agent UI locally:

1. Prerequisites:

   • Python 3.11+
   • uv package manager

2. Environment Variables: Create a .env file or set the following environment variables:

   OPENAI_API_KEY=sk-...
   # URLs for your deployed MCP servers (or local if running locally)
   NPI_MCP_URL=https://<your-npi-space>.hf.space/sse
   CRED_DB_MCP_URL=https://<your-cred-db-space>.hf.space/sse
   ALERT_MCP_URL=https://<your-alert-space>.hf.space/sse
   

3. Run the Agent:

   uv run -m credentialwatch_agent.main
   

   This will start the Gradio interface locally at http://localhost:7860.