A comprehensive healthcare consultation platform that combines a modern ChatGPT-style interface with intelligent AI agents for medical information collection, symptom analysis, hospital search, appointment processing, and patient support throughout their healthcare journey.

• 🤖 Multi-Agent AI System: Three specialized CrewAI agents for different phases of patient care
• 💬 Intelligent Chat Interface: Natural conversation flow with context-aware responses
• 🏥 Hospital Discovery: Automated search for nearby medical institutions using Exa.ai
• 📅 Appointment Processing: Parallel processing of hospital websites to find available slots
• 🛣️ Journey Support: Comfort guidance and reassurance during travel to hospital
• 📊 Data Extraction: Structured JSON output for seamless integration with other systems
• 🔄 Background Processing: Non-blocking appointment scraping and data processing

• 🎨 Modern UI: Clean, responsive design with dark/light theme support
• � Mobile Responsive: Works perfectly on all device sizes
• ⚡ Real-time Processing: Live updates and background task management
• 🔒 Session Management: Persistent sessions with conversation history
• 📈 Monitoring: Comprehensive logging with W&B Weave integration
• 🛡️ Error Handling: Robust error handling and graceful fallbacks

┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Chat Agent    │    │ Reasoning Agent  │    │ Extraction Agent │
│ (Info Collect)  │ -> │ (Symptom Analys) │ -> │ (Data Structure) │
└─────────────────┘    └──────────────────┘    └──────────────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │     Gemini 2.5 Flash     │
                    │    (Google AI API)       │
                    └───────────────────────────┘

User Input -> Chat Agent -> Basic Info Complete? 
                              │
                              ├─ No: Continue Collection
                              │
                              └─ Yes: Hospital Search (Exa.ai)
                                      │
                                      ├─ Background: Appointment Processing
                                      │
                                      └─ Reasoning Agent -> Comfort Guidance

• FastAPI Server: REST API with session management
• CrewAI Agents: Specialized AI agents for different tasks
• Playwright: Browser automation for appointment scraping
• Exa.ai Integration: Hospital and clinic discovery
• W&B Weave: AI interaction monitoring and tracing

• Node.js 18+
• Python 3.11+
• Google Gemini API Key
• W&B API Key (for monitoring)
• Exa.ai API Key (for hospital search)

git clone <repository-url>
cd PatientHero

# Install frontend dependencies
npm install

# Setup Python environment
cd crewai_agents
chmod +x setup.sh
./setup.sh

# Install Playwright browsers
conda activate patienthero-crewai
playwright install

Create .env files with your API keys:

Root .env:

GEMINI_API_KEY=your_gemini_api_key
WANDB_API_KEY=your_wandb_api_key
WANDB_PROJECT=patienthero-crewai
WANDB_ENTITY=your_wandb_entity
EXA_API_KEY=your_exa_api_key

crewai_agents/.env:

GEMINI_API_KEY=your_gemini_api_key
WANDB_API_KEY=your_wandb_api_key
WANDB_PROJECT=patienthero-crewai
WANDB_ENTITY=your_wandb_entity
EXA_API_KEY=your_exa_api_key

# Terminal 1: Start the API server
python api_server.py

# Terminal 2: Start the frontend
npm run dev

• Frontend: http://localhost:3000
• API Documentation: http://localhost:8000/docs
• API Health Check: http://localhost:8000

1. User starts conversation with greeting
2. Chat Agent activates to collect:
   • Medical condition/symptoms
   • ZIP code for location
   • Phone number for contact
   • Insurance information

3. Automatic hospital search using Exa.ai
4. Background appointment processing with Playwright
5. Data structure extraction with confidence scoring

6. Reasoning Agent analysis of symptoms and conditions
7. Comfort guidance provision (2 rounds of support)
8. Journey assistance with practical tips

• Framework: Next.js 14 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Radix UI primitives
• Icons: Lucide React
• State Management: React hooks and context
• Theme: next-themes for dark/light mode

• API Framework: FastAPI
• AI Framework: CrewAI with custom Gemini LLM
• Language Model: Google Gemini 2.5 Flash
• Browser Automation: Playwright
• Search Engine: Exa.ai API
• Monitoring: W&B Weave
• Session Storage: In-memory (production: Redis/DB)

• Package Management: npm, conda/pip
• Code Quality: ESLint, Prettier
• Type Checking: TypeScript
• API Documentation: FastAPI auto-docs

PatientHero/
├── app/                    # Next.js 14 app directory
│   ├── globals.css        # Global styles and themes
│   ├── layout.tsx         # Root layout with providers
│   └── page.tsx           # Main chat interface
├── components/            # React components
│   ├── ui/               # Reusable UI primitives
│   ├── providers/        # Context providers
│   ├── medical-consultation.tsx  # Main chat component
│   ├── appointment-flow.tsx      # Appointment processing UI
│   ├── sidebar.tsx       # Navigation sidebar
│   └── theme-toggle.tsx  # Dark/light mode toggle
├── lib/                  # Utility functions and services
│   ├── ai-service.ts     # API communication layer
│   ├── utils.ts          # Helper functions
│   └── hooks.ts          # Custom React hooks
├── crewai_agents/        # AI agent system
│   ├── main.py           # Core CrewAI implementation
│   ├── exa_helper.py     # Hospital search integration
│   ├── requirements.txt  # Python dependencies
│   ├── environment.yml   # Conda environment
│   └── setup.sh          # Automated setup script
├── api_server.py         # FastAPI backend server
├── process_clinics_parallel.py  # Appointment processing
├── docs/                 # Documentation
│   ├── DEPLOYMENT_GUIDE.md
│   ├── PROMPT_SYSTEM.md
│   └── WANDB_SUMMARY.md
└── scripts/              # Utility scripts

• POST /api/chat - Process user input through AI agents
• GET /api/status/{session_id} - Get session status and patient data

• POST /api/complete-flow/{session_id} - Full medical flow processing
• GET /api/appointments/{session_id} - Get processed appointment data
• POST /api/appointments/process - Manual appointment processing

• GET /api/comfort-guidance/{session_id} - Comfort guidance rounds
• POST /api/sessions/{session_id}/end - End patient session

• GET /api/sessions - List active sessions (debug)
• GET / - API health check

interface PatientData {
  session_id: string;
  timestamp: string;
  medical_condition?: string;
  zip_code?: string;
  phone_number?: string;
  insurance?: string;
  symptoms?: string[];
  reasoning_analysis?: string;
  conversation_history: ConversationEntry[];
}

interface AppointmentData {
  hospital_name: string;
  website: string;
  institution_type: string;
  accepts_user_insurance: string;
  appointment_availability: {
    available_slots: AppointmentSlot[];
    total_slots_found: number;
    next_available: string;
    booking_method: string;
  };
}

• Role: Friendly medical intake specialist
• Goal: Collect essential patient information naturally
• Behavior: One question at a time, empathetic responses
• Transition: Switches to Reasoning Agent when basic info complete

• Role: Medical reasoning specialist
• Goal: Analyze symptoms and provide preliminary guidance
• Behavior: Evidence-based analysis, follow-up questions
• Output: Detailed symptom analysis and medical reasoning

• Role: Data extraction specialist
• Goal: Structure conversation data into JSON format
• Behavior: Intelligent parsing, confidence scoring
• Output: Structured patient data with metadata

• Search scope: .org and .gov domains only
• Filters: Location-based, insurance compatibility
• Output: Structured hospital data with contact information

• Method: Parallel Playwright browser automation
• Target: Hospital booking pages and forms
• Extraction: Available time slots, booking methods
• Performance: Concurrent processing for speed

• Standardization: Consistent appointment slot formats
• Validation: Remove invalid or malformed data
• Enhancement: Add booking methods and availability status

• Agent Interactions: Every AI model call traced
• Session Tracking: Complete conversation flows
• Performance Metrics: Response times, success rates
• Error Tracking: Detailed error logs and context

• Information Collection Rate: Percentage of complete patient profiles
• Agent Transition Success: Chat -> Reasoning -> Extraction flow
• Appointment Processing: Success rate of hospital data extraction
• User Engagement: Session duration and interaction quality

• Session Isolation: Each session independent and secure
• Temporary Storage: Patient data not permanently stored
• API Security: CORS protection and request validation
• Privacy: No data sharing with external services (except AI APIs)

• Content Filtering: Gemini safety settings configured
• Error Boundaries: Graceful handling of API failures
• Input Validation: Sanitization of user inputs
• Rate Limiting: Protection against abuse

# Start both services locally
python api_server.py &
npm run dev

• Frontend: Vercel, Netlify, or similar
• Backend: Railway, Render, or VPS
• Database: PostgreSQL or MongoDB for persistence
• Monitoring: W&B dashboard for production monitoring

# Build and run with Docker
docker build -t patienthero .
docker run -p 3000:3000 -p 8000:8000 patienthero

npm run test          # Run test suite
npm run test:watch    # Watch mode
npm run lint          # Code quality check

cd crewai_agents
python test_complete_flow.py  # Test complete AI flow
python -m pytest tests/       # Run unit tests

# Test core endpoints
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"user_input": "Hi, I have a fever", "session_id": "test-123"}'

curl -X POST http://localhost:8000/api/complete-flow/test-123

1. Fork the repository
2. Create a feature branch
3. Set up development environment
4. Make your changes
5. Add tests if applicable
6. Submit a pull request

• Frontend: ESLint + Prettier configuration
• Backend: PEP 8 Python style guide
• Commits: Conventional commit messages
• Documentation: Update README for significant changes

Important: This application is designed for educational and demonstration purposes. It should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult with qualified healthcare providers for medical concerns.

• User Authentication: Persistent user accounts
• Database Integration: Long-term data storage
• Real Appointment Booking: Direct integration with hospital systems
• Telemedicine: Video consultation capabilities
• Multi-language: Support for multiple languages
• Mobile App: Native iOS/Android applications

• Memory Enhancement: Long-term conversation memory
• Specialized Models: Domain-specific medical AI models
• Voice Interface: Speech-to-text and text-to-speech
• Predictive Analytics: Early symptom detection
• Personalization: Adaptive responses based on user history

• EHR Systems: Electronic health record integration
• Insurance APIs: Real-time coverage verification
• Pharmacy Systems: Prescription management
• Wearable Devices: Health data integration
• Emergency Services: Direct 911/emergency routing

This project is licensed under the MIT License - see the LICENSE file for details.

• CrewAI: Multi-agent AI framework
• Google Gemini: Advanced language model capabilities
• Exa.ai: Intelligent web search for healthcare
• W&B Weave: AI application monitoring and tracing
• Radix UI: Accessible component primitives
• Playwright: Reliable browser automation

• Deployment Guide - Detailed deployment instructions
• Prompt System Documentation - AI agent prompt engineering
• W&B Integration Guide - Monitoring and analytics setup
• API Documentation - Interactive API documentation

For technical support, bug reports, or feature requests:

1. Check existing Issues
2. Create a new issue with detailed description
3. Include environment details and error logs
4. Tag with appropriate labels

Built with ❤️ for better healthcare accessibility │ ├── ui/ # Reusable UI components │ ├── providers/ # Context providers │ ├── sidebar.tsx # Chat sidebar │ └── theme-toggle.tsx # Theme switcher ├── lib/ # Utility functions │ └── utils.ts # Helper functions ├── public/ # Static assets │ └── manifest.json # PWA manifest └── types/ # TypeScript type definitions

## Key Components

### Chat Interface
- **Message Display**: Shows user and AI messages with timestamps
- **Real-time Input**: Send messages with Enter key or button click
- **Typing Indicators**: Visual feedback when AI is responding
- **Message History**: Persistent chat history across sessions

### Sidebar Navigation
- **Chat List**: Organized by date (Today, Yesterday, Previous 7 days, Older)
- **New Chat**: Create new conversations
- **Search**: Filter chats by title
- **Responsive**: Collapsible on mobile devices

### Theme System
- **Dark/Light Mode**: Toggle between themes
- **System Preference**: Respects user's system theme
- **Persistent**: Theme preference saved locally

## Customization

### Styling
The app uses Tailwind CSS with a custom color system. You can modify the theme in:
- `tailwind.config.js` - Tailwind configuration
- `app/globals.css` - CSS custom properties for colors

### AI Integration
To connect to actual AI services, modify the `sendMessage` function in `app/page.tsx`:

```typescript
// Replace the simulation with actual AI API calls
const sendMessage = async () => {
  // Your AI API integration here
}

All UI components are in the components/ui/ directory and are built with Radix UI primitives for accessibility and customization.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

This application is designed for educational and demonstration purposes. It should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult with qualified healthcare providers for medical concerns.

• Modern Next.js 14 + TypeScript setup
• Responsive chat interface with sidebar
• Dark/light theme toggle
• Message input with auto-resize textarea
• Chat history management
• Loading states and animations
• Settings dialog
• PWA configuration with manifest
• Modern UI components (Button, Input, Card, Avatar, etc.)
• Proper favicon and app icons
• TypeScript type safety
• Tailwind CSS styling
• Radix UI component primitives
• Med42-8B Integration: Production-ready medical AI on Fly.io
• AI Service Layer: OpenAI-compatible API for seamless integration
• Medical Specialization: Healthcare-focused prompts and responses

• Deploy Med42-8B: Run cd fly-llm-server && ./deploy.sh for cloud deployment
• User authentication
• Database integration for chat persistence
• Message export functionality
• File upload support
• Voice input/output
• Medical data integration
• Advanced settings (model parameters)
• Chat sharing and collaboration
• Analytics and usage tracking

• Multi-language support
• Plugin system for medical tools
• Integration with EHR systems
• Appointment scheduling
• Medication reminders
• Health data visualization
• Telemedicine integration

The application is production-ready with complete AI integration!

• ✅ Med42-8B Integration: Production-ready medical AI on Fly.io
• ✅ OpenAI-Compatible API: Seamless integration with standard formats
• ✅ Medical Specialization: Healthcare-focused system prompts
• ✅ Scalable Deployment: Auto-scaling GPU infrastructure on Fly.io

Production Deployment (Recommended)

cd fly-llm-server && ./deploy.sh  # Deploy Med42-8B to Fly.io
npm run dev                       # Start the frontend

1. Deploy Med42-8B: Follow the deployment guide in fly-llm-server/DEPLOYMENT.md
2. Configure environment: Update .env.local with your Fly.io URL
3. Test integration: Ensure the frontend connects to your deployed backend
4. Add authentication: For user management and chat persistence

The UI is production-ready and follows modern design patterns. All core components are implemented and the application is responsive across all device sizes.