Clean commit for HF push

.gitignore

@@ -0,0 +1,5 @@
+.env.*
+.venv/
+__pycache__/
+*.pyc
+.DS_Store

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -0,0 +1,69 @@
+# CredentialWatch Agent
+
+MCP-powered agent system for monitoring healthcare provider credentials. This system uses LangGraph to orchestrate workflows for checking credential expiry and answering interactive queries, leveraging Model Context Protocol (MCP) to connect to external data sources.
+
+## Features
+
+- **Interactive Query Agent**: Ask natural language questions about provider credentials.
+- **Expiry Sweep Agent**: Automated workflow to check for expiring credentials and generate alerts.
+- **MCP Integration**: Connects to NPI Registry, Credential Database, and Alerting systems via MCP.
+- **Gradio UI**: User-friendly interface for interaction.
+
+## Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://github.com/astral-sh/uv) (recommended)
+
+## Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone <repository_url>
+    cd credential_watch
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    uv sync
+    ```
+
+## Configuration
+
+Create a `.env` file in the root directory (or copy `.env.local`) and configure your environment variables:
+
+```env
+OPENAI_API_KEY=your_openai_api_key
+# MCP Server URLs (defaults shown)
+NPI_MCP_URL=http://localhost:8001/sse
+CRED_DB_MCP_URL=http://localhost:8002/sse
+ALERT_MCP_URL=http://localhost:8003/sse
+```
+
+## Running the Application
+
+To run the agent system with the Gradio UI using `uv`:
+
+```bash
+uv run python src/credentialwatch_agent/main.py
+```
+OR
+```bash
+uv run -m credentialwatch_agent.main
+```
+
+The UI will be available at `http://localhost:7860`.
+
+## Architecture
+
+- **`src/credentialwatch_agent/agents/`**: Contains LangGraph workflow definitions.
+- **`src/credentialwatch_agent/mcp_client.py`**: Handles connections to MCP servers.
+- **`src/credentialwatch_agent/main.py`**: Entry point and Gradio UI.
+
+## MCP Servers
+
+The agent expects the following MCP servers to be running:
+1.  **NPI Server** (Port 8001)
+2.  **Credential DB Server** (Port 8002)
+3.  **Alert Server** (Port 8003)
+
+If these servers are not reachable, the client will fall back to using mock data for demonstration purposes.

main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from credential-watch!")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "credentialwatch_agent"
+version = "0.1.0"
+description = "MCP-powered agent system for monitoring healthcare provider credentials"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=0.0.10",
+    "langchain-openai>=0.0.5",
+    "pydantic>=2.0.0",
+    "mcp>=0.1.0",
+    "gradio>=4.0.0",
+    "python-dotenv>=1.0.0",
+    "httpx>=0.25.0" 
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/credentialwatch_agent"]

src/credentialwatch_agent/agents/common.py

@@ -0,0 +1,22 @@
+from typing import TypedDict, List, Optional, Any, Dict, Annotated
+import operator
+
+class AgentState(TypedDict):
+    """
+    Common state for agents.
+    """
+    messages: List[Dict[str, Any]]
+    # Add other common fields if needed
+
+class ExpirySweepState(TypedDict):
+    """
+    State for the expiry sweep graph.
+    """
+    providers: List[Dict[str, Any]]
+    alerts_created: int
+    errors: List[str]
+    summary: str
+    window_days: int
+
+def merge_dicts(a: Dict, b: Dict) -> Dict:
+    return {**a, **b}

src/credentialwatch_agent/agents/expiry_sweep.py

@@ -0,0 +1,93 @@
+from typing import Dict, Any, List
+from langgraph.graph import StateGraph, END
+from credentialwatch_agent.agents.common import ExpirySweepState
+from credentialwatch_agent.mcp_client import mcp_client
+
+async def fetch_expiring_credentials(state: ExpirySweepState) -> Dict[str, Any]:
+    """
+    Fetches expiring credentials from the Credential DB MCP.
+    """
+    print("Fetching expiring credentials...")
+    # We check for a window defined in state or default to 90.
+    window_days = state.get("window_days", 90)
+    result = await mcp_client.call_tool(
+        "cred_db", 
+        "list_expiring_credentials", 
+        {"window_days": window_days}
+    )
+    
+    # Handle mock/real response structure
+    expiring_items = result.get("expiring", []) if isinstance(result, dict) else []
+    
+    return {"providers": expiring_items}
+
+async def create_alerts(state: ExpirySweepState) -> Dict[str, Any]:
+    """
+    Creates alerts for the expiring credentials found.
+    """
+    expiring_items = state.get("providers", [])
+    alerts_count = 0
+    errors = []
+
+    print(f"Found {len(expiring_items)} expiring items. Creating alerts...")
+
+    for item in expiring_items:
+        try:
+            # Determine severity based on days_remaining
+            days = item.get("days_remaining", 90)
+            severity = "low"
+            if days <= 30:
+                severity = "critical"
+            elif days <= 60:
+                severity = "high"
+            elif days <= 90:
+                severity = "medium"
+
+            provider_id = item.get("provider_id")
+            credential_id = item.get("credential_id", "unknown") # Fallback if not provided in list
+            message = f"Credential {item.get('credential')} for {item.get('name')} expires in {days} days."
+
+            await mcp_client.call_tool(
+                "alert",
+                "log_alert",
+                {
+                    "provider_id": provider_id,
+                    "credential_id": credential_id,
+                    "severity": severity,
+                    "message": message
+                }
+            )
+            alerts_count += 1
+        except Exception as e:
+            errors.append(f"Failed to create alert for {item}: {e}")
+
+    return {"alerts_created": alerts_count, "errors": errors}
+
+async def summarize_sweep(state: ExpirySweepState) -> Dict[str, Any]:
+    """
+    Summarizes the sweep results.
+    """
+    count = len(state.get("providers", []))
+    alerts = state.get("alerts_created", 0)
+    errors = state.get("errors", [])
+    
+    summary = f"Sweep completed. Scanned {count} expiring items. Created {alerts} alerts."
+    if errors:
+        summary += f" Encountered {len(errors)} errors."
+    
+    return {"summary": summary}
+
+# Build the graph
+workflow = StateGraph(ExpirySweepState)
+
+workflow.add_node("fetch_expiring_credentials", fetch_expiring_credentials)
+workflow.add_node("create_alerts", create_alerts)
+workflow.add_node("summarize_sweep", summarize_sweep)
+
+workflow.set_entry_point("fetch_expiring_credentials")
+
+workflow.add_edge("fetch_expiring_credentials", "create_alerts")
+workflow.add_edge("create_alerts", "summarize_sweep")
+workflow.add_edge("summarize_sweep", END)
+
+expiry_sweep_graph = workflow.compile()

src/credentialwatch_agent/agents/interactive_query.py

@@ -0,0 +1,101 @@
+from typing import Annotated, Literal, TypedDict, List
+from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
+from langchain_core.tools import tool
+from langchain_openai import ChatOpenAI
+from langgraph.graph import StateGraph, END
+from langgraph.prebuilt import ToolNode
+from credentialwatch_agent.mcp_client import mcp_client
+from credentialwatch_agent.agents.common import AgentState
+
+# --- Tool Definitions ---
+
+@tool
+async def search_providers(query: str, state: str = None, taxonomy: str = None):
+    """
+    Search for healthcare providers by name, state, or taxonomy.
+    Useful for finding a provider's NPI or internal ID.
+    """
+    return await mcp_client.call_tool("npi", "search_providers", {"query": query, "state": state, "taxonomy": taxonomy})
+
+@tool
+async def get_provider_by_npi(npi: str):
+    """
+    Get provider details using their NPI number.
+    """
+    return await mcp_client.call_tool("npi", "get_provider_by_npi", {"npi": npi})
+
+@tool
+async def list_expiring_credentials(window_days: int = 90):
+    """
+    List credentials expiring within the specified number of days.
+    """
+    return await mcp_client.call_tool("cred_db", "list_expiring_credentials", {"window_days": window_days})
+
+@tool
+async def get_provider_snapshot(provider_id: int = None, npi: str = None):
+    """
+    Get a comprehensive snapshot of a provider's credentials and status.
+    Provide either provider_id or npi.
+    """
+    return await mcp_client.call_tool("cred_db", "get_provider_snapshot", {"provider_id": provider_id, "npi": npi})
+
+@tool
+async def get_open_alerts():
+    """
+    Get a list of all currently open alerts.
+    """
+    return await mcp_client.call_tool("alert", "get_open_alerts", {})
+
+tools = [
+    search_providers,
+    get_provider_by_npi,
+    list_expiring_credentials,
+    get_provider_snapshot,
+    get_open_alerts
+]
+
+# --- Graph Definition ---
+
+# We can use the prebuilt AgentState or our custom one.
+# For simplicity, we'll use a state compatible with ToolNode (requires 'messages').
+
+async def agent_node(state: AgentState):
+    """
+    Invokes the LLM to decide the next step.
+    """
+    messages = state["messages"]
+    model = ChatOpenAI(model="gpt-5.1", temperature=0) # Using gpt-5.1 as requested
+    # Note: User requested GPT-5.1. I should probably use the model name string they asked for if it's supported, 
+    # or fallback to a standard one. I'll use "gpt-4o" as a safe high-quality default for now, 
+    # or "gpt-5.1-preview" if I want to be cheeky, but let's stick to "gpt-4o" to ensure it works.
+    # Actually, the user said "LLM: OpenAI GPT-5.1". I should try to respect that string if possible, 
+    # but I'll use "gpt-4o" and add a comment.
+    
+    model_with_tools = model.bind_tools(tools)
+    response = await model_with_tools.ainvoke(messages)
+    return {"messages": [response]}
+
+def should_continue(state: AgentState) -> Literal["tools", "__end__"]:
+    """
+    Determines if the agent should continue to tools or end.
+    """
+    messages = state["messages"]
+    last_message = messages[-1]
+    if isinstance(last_message, AIMessage) and last_message.tool_calls:
+        return "tools"
+    return "__end__"
+
+workflow = StateGraph(AgentState)
+
+workflow.add_node("agent", agent_node)
+workflow.add_node("tools", ToolNode(tools))
+
+workflow.set_entry_point("agent")
+
+workflow.add_conditional_edges(
+    "agent",
+    should_continue,
+)
+workflow.add_edge("tools", "agent")
+
+interactive_query_graph = workflow.compile()

src/credentialwatch_agent/main.py

@@ -0,0 +1,112 @@
+import asyncio
+import os
+from typing import Dict, Any, List
+import gradio as gr
+from dotenv import load_dotenv
+from langchain_core.messages import HumanMessage, AIMessage
+
+from credentialwatch_agent.mcp_client import mcp_client
+from credentialwatch_agent.agents.expiry_sweep import expiry_sweep_graph
+from credentialwatch_agent.agents.interactive_query import interactive_query_graph
+
+# Load environment variables
+load_dotenv()
+
+async def run_expiry_sweep(window_days: int = 90) -> Dict[str, Any]:
+    """
+    Runs the expiry sweep workflow.
+    """
+    print(f"Starting expiry sweep for {window_days} days...")
+    # Initialize state
+    initial_state = {
+        "providers": [], 
+        "alerts_created": 0, 
+        "errors": [], 
+        "summary": "",
+        "window_days": window_days
+    }
+    
+    # Run the graph
+    # Note: The graph expects to fetch data itself, so initial state can be minimal.
+    # We might want to pass window_days if the graph supported dynamic config in state,
+    # but for now the graph hardcodes 90 or uses tool defaults. 
+    # To make it dynamic, we'd need to update the graph to read from state.
+    # For this hackathon, we'll assume the graph handles it or we pass it via a modified state if needed.
+    # The current implementation of fetch_expiring_credentials uses a hardcoded 90 or tool default.
+    
+    final_state = await expiry_sweep_graph.ainvoke(initial_state)
+    return {
+        "summary": final_state.get("summary"),
+        "alerts_created": final_state.get("alerts_created"),
+        "errors": final_state.get("errors")
+    }
+
+async def run_chat_turn(message: str, history: List[List[str]]) -> str:
+    """
+    Runs a turn of the interactive query agent.
+    """
+    # Convert history to LangChain format
+    messages = []
+    for human, ai in history:
+        messages.append(HumanMessage(content=human))
+        messages.append(AIMessage(content=ai))
+    messages.append(HumanMessage(content=message))
+    
+    initial_state = {"messages": messages}
+    
+    # Run the graph
+    final_state = await interactive_query_graph.ainvoke(initial_state)
+    
+    # Extract the last message
+    last_message = final_state["messages"][-1]
+    return last_message.content
+
+# --- Gradio UI ---
+
+async def start_app():
+    """Initializes the app and connects to MCP servers."""
+    print("Connecting to MCP servers...")
+    await mcp_client.connect()
+
+async def stop_app():
+    """Closes connections."""
+    print("Closing MCP connections...")
+    await mcp_client.close()
+
+with gr.Blocks(title="CredentialWatch") as demo:
+    gr.Markdown("# CredentialWatch Agent System")
+    
+    with gr.Tab("Interactive Query"):
+        gr.Markdown("Ask questions about provider credentials, e.g., 'Who has expiring licenses?'")
+        chat_interface = gr.ChatInterface(fn=run_chat_turn)
+
+    with gr.Tab("Expiry Sweep"):
+        gr.Markdown("Run a batch sweep to check for expiring credentials and create alerts.")
+        with gr.Row():
+            sweep_btn = gr.Button("Run Sweep", variant="primary")
+        
+        sweep_output = gr.JSON(label="Sweep Results")
+        
+        sweep_btn.click(fn=run_expiry_sweep, inputs=[], outputs=[sweep_output])
+
+# Startup/Shutdown hooks
+# Gradio doesn't have native async startup hooks easily exposed in Blocks without mounting to FastAPI.
+# But we can run the connect logic when the script starts if we run it via `uv run`.
+# For a proper app, we'd use lifespan events in FastAPI.
+# Here, we will just connect globally on import or first use if possible, 
+# or use a startup event if we were using `gr.mount_gradio_app`.
+# For simplicity in this script, we'll rely on the global mcp_client.connect() being called 
+# or we can wrap the demo launch.
+
+if __name__ == "__main__":
+    # Simple async wrapper to run the app
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    
+    try:
+        loop.run_until_complete(mcp_client.connect())
+        demo.launch(server_name="0.0.0.0", server_port=7860)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        loop.run_until_complete(mcp_client.close())

src/credentialwatch_agent/mcp_client.py

@@ -0,0 +1,99 @@
+import os
+import asyncio
+from typing import Any, Dict, List, Optional
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+
+class MCPClient:
+    """
+    Abstraction for calling MCP tools from multiple servers.
+    Manages connections to NPI, Credential DB, and Alert MCP servers.
+    """
+
+    def __init__(self):
+        self.npi_url = os.getenv("NPI_MCP_URL", "http://localhost:8001/sse")
+        self.cred_db_url = os.getenv("CRED_DB_MCP_URL", "http://localhost:8002/sse")
+        self.alert_url = os.getenv("ALERT_MCP_URL", "http://localhost:8003/sse")
+        
+        self._exit_stack = AsyncExitStack()
+        self._sessions: Dict[str, ClientSession] = {}
+
+    async def connect(self):
+        """Establishes connections to all MCP servers."""
+        # In a real app, we might want to connect lazily or in parallel.
+        # For simplicity, we'll try to connect to all.
+        
+        # Connect to NPI MCP
+        try:
+            # Note: mcp.client.sse.sse_client is a context manager that yields (read_stream, write_stream)
+            # We need to keep the context open.
+            npi_transport = await self._exit_stack.enter_async_context(sse_client(self.npi_url))
+            self._sessions["npi"] = await self._exit_stack.enter_async_context(
+                ClientSession(npi_transport[0], npi_transport[1])
+            )
+            await self._sessions["npi"].initialize()
+        except Exception as e:
+            print(f"Failed to connect to NPI MCP at {self.npi_url}: {e}")
+
+        # Connect to Cred DB MCP
+        try:
+            cred_transport = await self._exit_stack.enter_async_context(sse_client(self.cred_db_url))
+            self._sessions["cred_db"] = await self._exit_stack.enter_async_context(
+                ClientSession(cred_transport[0], cred_transport[1])
+            )
+            await self._sessions["cred_db"].initialize()
+        except Exception as e:
+            print(f"Failed to connect to Cred DB MCP at {self.cred_db_url}: {e}")
+
+        # Connect to Alert MCP
+        try:
+            alert_transport = await self._exit_stack.enter_async_context(sse_client(self.alert_url))
+            self._sessions["alert"] = await self._exit_stack.enter_async_context(
+                ClientSession(alert_transport[0], alert_transport[1])
+            )
+            await self._sessions["alert"].initialize()
+        except Exception as e:
+            print(f"Failed to connect to Alert MCP at {self.alert_url}: {e}")
+
+    async def close(self):
+        """Closes all connections."""
+        await self._exit_stack.aclose()
+
+    async def call_tool(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """Calls a tool on a specific MCP server."""
+        session = self._sessions.get(server_name)
+        if not session:
+            # Fallback for testing/mocking if connection failed
+            print(f"Warning: No active session for {server_name}. Returning mock data.")
+            return self._get_mock_response(server_name, tool_name, arguments)
+
+        result = await session.call_tool(tool_name, arguments)
+        return result
+
+    def _get_mock_response(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """Returns mock data when MCP server is unavailable."""
+        if server_name == "npi":
+            if tool_name == "search_providers":
+                return {"providers": [{"npi": "1234567890", "name": "Dr. Jane Doe", "taxonomy": "Cardiology"}]}
+            if tool_name == "get_provider_by_npi":
+                return {"npi": arguments.get("npi"), "name": "Dr. Jane Doe", "licenses": []}
+        
+        if server_name == "cred_db":
+            if tool_name == "list_expiring_credentials":
+                return {"expiring": [{"provider_id": 1, "name": "Dr. Jane Doe", "credential": "Medical License", "days_remaining": 25}]}
+            if tool_name == "get_provider_snapshot":
+                return {"name": "Dr. Jane Doe", "status": "Active", "credentials": []}
+
+        if server_name == "alert":
+            if tool_name == "log_alert":
+                return {"success": True, "alert_id": 101}
+            if tool_name == "get_open_alerts":
+                return {"alerts": []}
+
+        return {"error": "Mock data not found for this tool"}
+
+# Global instance
+mcp_client = MCPClient()