MAS: Multi-Agent Clinical Simulation Platform

Welcome to the MAS project, an advanced platform for training the next generation of healthcare professionals. This project leverages a sophisticated multi-agent system powered by Large Language Models (LLMs) to create realistic, interactive clinical scenarios.

1. Introduction

MAS provides a safe and repeatable environment where medical students can practice and hone their clinical reasoning, diagnostic, and communication skills. Students interact with a simulated patient and a virtual clinical environment, allowing them to conduct a full patient workup, from initial conversation to diagnosis and intervention.

The platform is built on a robust multi-agent architecture, where specialized AI agents collaborate to simulate different facets of a clinical encounter, including patient dialogue, physical exams, diagnostic tests, and treatment outcomes.

2. Core Features

• Realistic Patient Dialogue: Converse with an AI patient that exhibits a distinct personality and realistic emotional responses.
• Interactive Clinical Environment: Perform virtual physical exams, order diagnostic tests (labs, imaging), and administer interventions.
• Dynamic Scenarios: The patient's condition evolves in real-time based on the student's actions or inaction.
• Comprehensive Evaluation: Receive detailed performance feedback and scoring based on a critical actions checklist.

3. Technology Stack

• Backend: Python (FastAPI)
• Frontend: Next.js (React)
• Database: PostgreSQL
• ORMs: SQLAlchemy (Python) & Prisma (TypeScript)
• AI: Multi-LLM integration (OpenAI, Anthropic, Google AI)

For a more detailed breakdown, please see the Technology Stack Design.

4. Project Structure

The project is organized into three main directories: backend, frontend, and docs.

/
|-- backend/                # Python/FastAPI Simulation Core
|   |-- app/
|   |   |-- api/            # API endpoint definitions (routers)
|   |   |-- agents/         # Implementation of specialized agents
|   |   |-- core/           # Supervisor, state management, and core logic
|   |   |-- models/         # SQLAlchemy data models
|   |   `-- services/       # Business logic and services (e.g., LLM abstraction)
|   |-- tests/              # Backend tests
|   |-- .env.example        # Example environment variables
|   |-- main.py             # Main entry point for the FastAPI application
|   `-- requirements.txt    # Python dependencies
|
|-- frontend/               # Next.js User Interface
|   |-- src/
|   |   |-- app/            # Next.js 13+ app router pages and components
|   |   |-- components/     # Reusable UI components
|   |   |-- lib/            # Helper functions, Prisma client
|   |   `-- styles/         # Global styles
|   |-- .env.local.example  # Example environment variables
|   |-- next.config.js      # Next.js configuration
|   `-- package.json        # Frontend dependencies
|
|-- docs/                   # All design and planning documents
|   |-- DESIGN.md
|   |-- SOFTWARE_DESIGN.md
|   |-- DATABASE_DESIGN.md
|   `-- TECH_STACK.md
|
|-- .gitignore
`-- README.md               # You are here

Directory Descriptions

• backend/: Contains the entire Python application that runs the simulation engine. It exposes a REST API that the frontend consumes.
• frontend/: Contains the Next.js application that users interact with. It is responsible for all UI rendering and client-side state management.
• docs/: A crucial directory holding all high-level design documents, architecture diagrams, and planning artifacts.

5. API Documentation

This project features a self-documenting API powered by FastAPI and OpenAPI.

• For detailed information on the API, its endpoints, and how to test them, see the API Documentation.
• While the backend server is running, you can access the interactive Swagger UI at http://127.0.0.1:8000/docs.

This file will be updated as the project progresses.

Progress Summary

So far, we have accomplished the following:

1. System Design: We designed a multi-agent system for a clinical scenario simulator. The design includes a Supervisor Agent orchestrating a Patient Agent, Physical Exam Agent, Diagnostic Agent, Interventions Agent, and Evaluation Agent. This is documented in docs/DESIGN.md.
2. Software Architecture: We created a detailed software design, including Use Case, Sequence, and Class diagrams, along with data models. This is documented in docs/SOFTWARE_DESIGN.md.
3. Database Design: We designed a relational database schema with tables for Users, Scenarios, Simulations, and Logs, documented in docs/DATABASE_DESIGN.md.
4. Technology Stack: We selected a technology stack consisting of Next.js for the frontend, Python with FastAPI for the backend, and PostgreSQL for the database. This is documented in docs/TECH_STACK.md.
5. Backend Setup: We initialized the Python backend with FastAPI, set up a virtual environment, and installed the necessary dependencies.
6. API Definition: We defined the initial API contract with Pydantic models and created placeholder endpoints for the simulation API.
7. Database Connection: We established a connection to the PostgreSQL database and set up Alembic for database migrations.
8. Initial Migration: We successfully ran the initial database migration, creating the necessary tables in the mas_db database.

To-Do List

Here is a high-level to-do list for the rest of the project:

Backend Development

• Implement user authentication (e.g., JWT-based).
• Implement the core logic for the simulation API endpoints:
  • POST /simulations/: Start a new simulation.
  • POST /simulations/{simulation_id}/action: Handle a user action within a simulation.
• Develop the agent services (patient_agent, supervisor_agent, etc.).
• Implement the logic for the "Scenario Engine" to manage the flow of the simulation.
• Write unit and integration tests for the backend.
• Set up CI/CD for the backend.

Frontend Development

• Initialize the Next.js frontend application.
• Create UI wireframes and mockups.
• Implement user authentication flows (login, registration).
• Build the main simulation interface.
• Develop components for displaying patient information, logs, and user actions.
• Connect the frontend to the backend API.
• Write tests for the frontend components.
• Set up CI/CD for the frontend.

General

• Continue to update the documentation as the project evolves.
• Deploy the application to a cloud provider (e.g., AWS, Azure, Heroku).