RosterIQ: Memory-Driven Provider Roster Intelligence Agent

Overview

RosterIQ is an autonomous AI agent designed to operate on provider roster pipeline and market transaction data. It maintains layered memory across interactions, uses tools to diagnose pipeline behavior and record quality issues, and communicates operational insights through dynamic visualizations.

Project Structure

• data/: Contains datasets (roster_processing_details.csv, aggregated_operational_metrics.csv).
• src/: Source code for the agent.
• docs/: Documentation and architecture diagrams.
• notebooks/: Jupyter notebooks for exploration and testing.
• tests/: Unit and integration tests.

Setup

1. Clone the repository.
2. Install dependencies: pip install -r requirements.txt.
3. Create a .env file:

   MISTRAL_API_KEY=your_mistral_api_key_here
   TAVILY_API_KEY=your_api_key_here
   

4. Place datasets in the data/ directory.
5. Build/read-only SQLite DB: python sql_setup/create_database.py.
6. Run the agent: python -m src.main.

Dependencies

• Python 3.8+
• Pandas
• Plotly
• ChromaDB (for memory storage)
• Tavily API (for web search)

Memory Architecture

• Episodic Memory: Logs queries, actions, and findings.
• Procedural Memory: Encodes diagnostic workflows.
• Semantic Memory: Maintains domain knowledge.

Tools

• Web Search: Fetch external context.
• Visualization: Generate charts and dashboards.
• Data Query: Filter, aggregate, and analyze data.
• Report Generator: Produce structured reports.

Usage

Command-Line Interface (CLI)

1. Start the agent: python -m src.main.
2. Interact with the agent using natural language queries. Examples:
   • "What are the pipeline stages?"
   • "Run triage_stuck_ros for CA with limit 10"
   • "Run market_health_report for CA"
   • "Run retry_effectiveness_analysis"
   • "Run pipeline_error_period_report for 2026-02"
3. The agent uses LangChain routing with procedural memory and optional web search.

Web User Interface (UI)

1. Start the web UI: ./run_web_ui.sh.
2. Open your browser to the URL provided by Streamlit (usually http://localhost:8501).
3. Interact with the agent using the chat interface in the browser.

MCP Server

1. Start MCP server: python -m src.mcp_server.
2. Available MCP tools: list_procedures, get_procedure, run_procedure, update_procedure, web_search.

Example Queries

• Semantic Memory: "What are the pipeline stages?", "What are health flags?"
• Procedural Memory: "triage_stuck_ros", "market_health_report", "retry_effectiveness_analysis"
• Report Generation: "Generate a pipeline health report", "Generate an anomaly report"
• Visualization: "Plot pipeline health", "Plot market success"
• Web Search: "Search for CMS rule changes" (requires valid Tavily API key)

License

This project is proprietary and should not be shared publicly.