{"id":32556306,"url":"https://github.com/harshhh28/hia-js","last_synced_at":"2026-04-06T09:33:21.609Z","repository":{"id":319767352,"uuid":"1073281096","full_name":"harshhh28/hia-js","owner":"harshhh28","description":"Hia (Health Insights Agent) - AI Agent to analyze blood reports and provide detailed health insights.","archived":false,"fork":false,"pushed_at":"2026-02-11T22:45:49.000Z","size":409,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T05:58:04.383Z","etag":null,"topics":["docker-compose","groq-sdk","huggingface","next-auth","nextjs","nodejs","oauth","pgvector","postgresql"],"latest_commit_sha":null,"homepage":"https://hia-js.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harshhh28.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T21:59:44.000Z","updated_at":"2026-02-11T22:45:54.000Z","dependencies_parsed_at":"2025-10-20T06:29:52.965Z","dependency_job_id":null,"html_url":"https://github.com/harshhh28/hia-js","commit_stats":null,"previous_names":["harshhh28/hia-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/harshhh28/hia-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshhh28%2Fhia-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshhh28%2Fhia-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshhh28%2Fhia-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshhh28%2Fhia-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harshhh28","download_url":"https://codeload.github.com/harshhh28/hia-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshhh28%2Fhia-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31466629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","groq-sdk","huggingface","next-auth","nextjs","nodejs","oauth","pgvector","postgresql"],"created_at":"2025-10-28T22:54:44.672Z","updated_at":"2026-04-06T09:33:21.603Z","avatar_url":"https://github.com/harshhh28.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🩺 HIA (Health Insights Agent)\n\nAI Agent to analyze blood reports and provide detailed health insights.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/harshhh28/hia-js/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/harshhh28/hia-js\"\u003e\u003c/a\u003e \n  \u003ca href=\"https://github.com/harshhh28/hia-js/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/harshhh28/hia-js\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/harshhh28/hia-js/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/harshhh28/hia-js\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/harshhh28/hia-js/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e |\n  \u003ca href=\"#%EF%B8%8F-tech-stack\"\u003eTech Stack\u003c/a\u003e |\n  \u003ca href=\"#-installation\"\u003eInstallation\u003c/a\u003e |\n  \u003ca href=\"#-contributing\"\u003eContributing\u003c/a\u003e |\n  \u003ca href=\"#%EF%B8%8F-author\"\u003eAuthor\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/harshhh28/hia-js\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/harshhh28/hia/main/public/HIA_demo.gif\" alt=\"Usage Demo\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## 🌟 Features\n\n### 🩺 Medical Report Analysis\n\n- **PDF Medical Report Upload**: Secure PDF upload with validation (up to 10MB)\n- **Medical Content Validation**: Strict validation ensures only medical-related PDFs are processed\n- **Intelligent Medical Analysis**: AI-powered comprehensive health insights using specialized medical prompts\n- **Multi-Domain Expertise**: Covers CBC, liver function, pancreatic markers, metabolic panels, lipid profiles, and common diseases\n- **Risk Assessment**: Identifies potential health risks with Low/Medium/High risk levels\n- **Personalized Recommendations**: Lifestyle modifications, dietary advice, and follow-up test suggestions\n- **Offline Analysis**: Basic medical analysis when AI services are unavailable\n\n### 🧠 AI-Powered Intelligence\n\n- **In-Context Learning**: Vector embeddings with pgvector for contextual medical conversations\n- **Medical-Only Responses**: AI strictly responds only to medical and health-related questions\n- **Contextual Responses**: AI responses that reference uploaded medical reports\n- **Multi-Model Architecture**: Groq AI integration with specialized medical analysis prompts\n- **Offline Fallback**: Basic medical guidance when AI services are unavailable\n- **Knowledge Retention**: Maintains conversation context across sessions\n\n### 🔐 Authentication \u0026 Security\n\n- **Multi-Provider Authentication**: Google OAuth, GitHub OAuth, and email/password\n- **Secure JWT Token System**: Access tokens (15 min) + Refresh tokens (7 days)\n- **Automatic Token Refresh**: Seamless token renewal without user interruption\n- **File Security**: Secure PDF processing with medical content validation\n- **Session Management**: User-specific medical report storage and access control\n\n### 📊 User Experience\n\n- **Session History**: Track all medical report analyses and conversations\n- **Real-time Processing**: Instant PDF analysis and AI response generation\n- **Modern UI**: Responsive design with real-time feedback\n- **Medical Disclaimer**: Proper AI-generated analysis disclaimers\n- **Logging System**: Comprehensive logging for maintenance and debugging\n\n## 🛠️ Tech Stack\n\n- **Frontend**: Next.js 15, React 19, TailwindCSS 4\n- **Backend**: Node.js, Express.js 5\n- **Database**: PostgreSQL with UUID support + pgvector extension\n- **Authentication**:\n  - NextAuth.js 4 (OAuth + JWT)\n  - Google OAuth 2.0\n  - GitHub OAuth 2.0\n  - JWT tokens with automatic refresh\n- **AI Integration**:\n  - Groq AI with specialized medical analysis prompts and offline fallback\n  - Multi-tier model architecture with automatic fallback\n  - Hugging Face Inference API (sentence-transformers/all-MiniLM-L6-v2) - FREE\n  - Fallback hash-based embeddings (no API key required)\n  - pgvector for similarity search\n  - Medical-only question validation and responses\n- **PDF Processing**: pdf-parse for medical report text extraction\n- **File Upload**: Multer with medical content validation\n- **Security**: HTTP-only cookies, CSRF protection, bcrypt hashing\n\n## 🚀 Installation\n\n#### Requirements 📋\n\n- Node.js 18+\n\n#### Getting Started 📝\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/harshhh28/hia-js.git\ncd hia-js\n```\n\n2. Install dependencies:\n\n```bash\ncd frontend\nnpm install\n\ncd backend\nnpm install\n```\n\n3. Required environment variables:\n\n**Backend** (`backend/.env`):\n\n```env\n# Server Configuration\nPORT=5000\nFRONTEND_URL=http://localhost:3000\n\n# Database Configuration\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=hia_db\nDB_USER=postgres\nDB_PASSWORD=password\n\n# JWT Configuration\nJWT_SECRET=your-super-secret-jwt-key-here\n\n# AI Integration\nGROQ_API_KEY=your-groq-api-key-here\nHUGGINGFACE_API_KEY=your-huggingface-api-key-here\n\n# File Upload Configuration\nMAX_FILE_SIZE=10485760\nUPLOAD_DIR=uploads/medical-reports\n\n# Logging Configuration\nLOG_LEVEL=INFO\nLOG_DIR=logs\n```\n\n**Frontend** (`frontend/.env`):\n\n```env\n# Backend API URL\nNEXT_PUBLIC_BACKEND_URL=http://localhost:5000\n\n# NextAuth Configuration\nNEXTAUTH_URL=http://localhost:3000\nNEXTAUTH_SECRET=your-secret-key-here\n\n# OAuth Provider Credentials (optional)\nGOOGLE_CLIENT_ID=your-google-client-id\nGOOGLE_CLIENT_SECRET=your-google-client-secret\nGITHUB_CLIENT_ID=your-github-client-id\nGITHUB_CLIENT_SECRET=your-github-client-secret\n```\n\n4. Set up PostgreSQL database with pgvector extension:\n\n```bash\n# Using Docker (Recommended)\ncd backend\ndocker-compose up -d\n\n# Or manually create database with pgvector\ncreatedb hia_db\npsql hia_db -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\n```\n\n5. **Set up free embedding models (Optional)**:\n\n**Option 1: Hugging Face Inference API (Recommended)**\n\n- Get a free API key from [Hugging Face](https://huggingface.co/settings/tokens)\n- Add `HUGGINGFACE_API_KEY=your_huggingface_api_key_here` to backend `.env`\n- Uses `sentence-transformers/all-MiniLM-L6-v2` model (384 dimensions)\n- Direct API integration with `@huggingface/inference` package\n\n**Option 2: Fallback Embeddings (No API Key Required)**\n\n- If no Hugging Face API key is provided, the system uses hash-based fallback embeddings\n- Still provides basic similarity search functionality\n- No external API calls required\n\n6. **Set up OAuth providers (Optional)**:\n\nFor Google OAuth:\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select existing one\n3. Enable Google+ API\n4. Create OAuth 2.0 credentials\n5. Add `http://localhost:3000/api/auth/callback/google` to authorized redirect URIs\n6. Copy Client ID and Client Secret to frontend `.env`\n\nFor GitHub OAuth:\n\n1. Go to GitHub Settings \u003e Developer settings \u003e OAuth Apps\n2. Create a new OAuth App\n3. Set Authorization callback URL to `http://localhost:3000/api/auth/callback/github`\n4. Copy Client ID and Client Secret to frontend `.env`\n\n5. Run the application:\n\n```bash\n# Terminal 1: Start frontend\ncd frontend\nnpm run dev\n\n# Terminal 2: Start backend\ncd backend\nnpm run dev\n```\n\n## 📁 Project Structure\n\n```\nhia-js/\n├── backend/                 # Express backend with medical analysis\n│   ├── controllers/         # API controllers\n│   │   ├── medicalReport.js # Medical report upload \u0026 analysis\n│   │   ├── chatMessage.js   # Contextual chat responses\n│   │   └── chatSession.js   # Session management\n│   ├── models/              # Database models\n│   │   ├── MedicalReport.js # Medical report storage\n│   │   ├── VectorEmbedding.js # Vector embeddings for AI\n│   │   └── ChatSession.js   # Enhanced session model\n│   ├── utils/               # Utilities\n│   │   ├── PDFProcessor.js  # PDF text extraction\n│   │   ├── VectorService.js # AI embeddings \u0026 context\n│   │   └── Prompt.js        # Medical analysis prompts\n│   ├── middlewares/         # Middleware functions\n│   │   └── pdfUpload.js     # PDF upload validation\n│   ├── uploads/             # Medical report storage\n│   └── logs/                # Application logs\n├── frontend/                # Next.js frontend\n└── README.md               # This file\n```\n\n## 🩺 Medical Report Workflow\n\n### How It Works\n\n1. **Create Session**: User creates a new chat session\n2. **Upload Report**: Upload a PDF medical report (blood test, lab results, etc.)\n3. **AI Analysis**: System automatically:\n   - Validates PDF format and medical content\n   - Extracts text from the PDF\n   - Generates comprehensive medical analysis using AI (with offline fallback)\n   - Stores embeddings for contextual learning\n4. **Interactive Chat**: User can ask medical questions about their report\n5. **Contextual Responses**: AI provides medical answers based on the uploaded report\n6. **Medical-Only Validation**: System ensures only medical questions are answered\n\n### Supported Medical Reports\n\n- **Blood Tests**: CBC, Complete Blood Count, Hematology\n- **Liver Function**: ALT, AST, ALP, Bilirubin tests\n- **Metabolic Panels**: Glucose, Cholesterol, Kidney function\n- **Specialized Tests**: Thyroid, Vitamin levels, Inflammatory markers\n- **Lab Reports**: Any medical laboratory test results\n\n### AI Analysis Features\n\n- **Risk Assessment**: Identifies potential health risks (Low/Medium/High)\n- **Personalized Recommendations**: Lifestyle and dietary advice\n- **Follow-up Suggestions**: Recommended additional tests\n- **Medical Disclaimers**: Proper AI-generated analysis warnings\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**OAuth Authentication Errors:**\n\n- Verify OAuth provider credentials are correctly set in frontend `.env`\n- Check that redirect URIs match exactly (including `http://localhost:3000`)\n- Ensure backend is running and accessible from frontend\n\n**Database Connection Issues:**\n\n- Verify PostgreSQL is running (`docker-compose ps` for Docker)\n- Check database credentials in backend `.env`\n- Ensure database exists (`createdb hia_db` if needed)\n\n**Token/Authentication Issues:**\n\n- Check JWT_SECRET is set in backend `.env`\n- Verify NEXTAUTH_SECRET is set in frontend `.env`\n- Clear browser cookies and try again\n- Check browser console for detailed error messages\n\n**CORS Issues:**\n\n- Verify FRONTEND_URL in backend `.env` matches your frontend URL\n- Check that credentials are enabled in CORS configuration\n\n**Medical Report Upload Issues:**\n\n- Verify PDF file is under 10MB and contains medical content\n- Check that PDF contains medical keywords (blood, lab, test, etc.)\n- System validates medical content before processing\n- Non-medical PDFs are rejected with clear error messages\n- Verify pgvector extension is installed in PostgreSQL\n- System works with or without Hugging Face API key (uses fallback embeddings)\n\n**AI Analysis Issues:**\n\n- Check GROQ_API_KEY is set in backend `.env`\n- System includes offline fallback when API is unavailable\n- Verify Hugging Face API key is valid (optional - fallback embeddings work without it)\n- Ensure medical report contains sufficient medical content\n- AI only responds to medical-related questions\n- Check logs directory for detailed error messages\n\n**Vector Database Issues:**\n\n- Verify pgvector extension is enabled: `CREATE EXTENSION IF NOT EXISTS vector;`\n- Use Docker image with pgvector: `pgvector/pgvector:pg15`\n- Check database connection and permissions\n- Ensure vector embeddings table is created properly\n\n**Free Embedding Issues:**\n\n- Hugging Face API key is optional - system works with fallback embeddings\n- If using Hugging Face, verify API key has inference permissions\n- Fallback embeddings provide basic similarity search without external API calls\n\n## 👥 Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, the development workflow, coding standards, and more.\n\nWe appreciate all contributions, from reporting bugs and improving documentation to implementing new features.\n\n## 👨‍💻 Contributors\n\nThanks to all the amazing contributors who have helped improve this project!\n\n| Avatar                                                                                          | Name         | GitHub                                    | Role                         | Contributions                      | PR(s) | Notes          |\n| ----------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------- | ---------------------------- | ---------------------------------- | ----- | -------------- |\n| \u003cimg src=\"https://github.com/harshhh28.png\" width=\"50px\" height=\"50px\" alt=\"harshhh28 avatar\"/\u003e | Harsh Gajjar | [harshhh28](https://github.com/harshhh28) | Project Creator \u0026 Maintainer | Core implementation, Documentation | N/A   | Lead Developer |\n\n\u003c!-- To future contributors: Your profile will be added here when your PR is merged! --\u003e\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/harshhh28/hia-js/blob/main/LICENSE) file for details.\n\n## 🆕 Recent Updates\n\n### Medical Content Validation \u0026 Offline Support\n\n- **Strict Medical Validation**: Only medical-related PDFs are processed and analyzed\n- **Medical-Only Chat**: AI responds only to medical and health-related questions\n- **Offline Analysis**: Basic medical analysis when AI services are unavailable\n- **Multi-Tier AI Fallback**: Automatic fallback between different AI models\n- **Enhanced Error Handling**: Better connectivity detection and graceful degradation\n\n### Key Improvements\n\n- ✅ **PDF Medical Content Validation**: Rejects non-medical PDFs with clear error messages\n- ✅ **Medical Question Filtering**: AI only answers medical questions, redirects others\n- ✅ **Offline Medical Analysis**: Basic analysis when Groq API is unavailable\n- ✅ **Connectivity Detection**: Automatic detection of API connectivity issues\n- ✅ **Enhanced Prompts**: Medical-only response enforcement in all AI interactions\n- ✅ **Rollback Mechanism**: Clean rollback for failed PDF processing\n\n## 🙋‍♂️ Author\n\nCreated by [Harsh Gajjar](https://harshgajjar.vercel.app)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshhh28%2Fhia-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharshhh28%2Fhia-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshhh28%2Fhia-js/lists"}