{"id":30388645,"url":"https://github.com/chanmeng666/wellness-agent","last_synced_at":"2026-04-28T23:35:46.740Z","repository":{"id":303780866,"uuid":"986200330","full_name":"ChanMeng666/wellness-agent","owner":"ChanMeng666","description":"【⭐️ Star this repo to support AI-powered workplace wellness innovation!】Enterprise-grade workplace wellness platform. Features 5 specialized AI agents, privacy-first multi-role support, persistent memory system, real-time wellness tracking \u0026 comprehensive organizational insights with role-based access for employees, HR managers \u0026 employers.","archived":false,"fork":false,"pushed_at":"2025-07-09T10:45:48.000Z","size":715,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-09T11:52:57.416Z","etag":null,"topics":["ai-assistant","employee-wellness","employer-insights","fastapi","gemini-ai","google-adk","hr-analytics","memory-system","multi-agent-system","nextjs","privacy-first","python","wellness-agent","workplace-wellness"],"latest_commit_sha":null,"homepage":"https://sanicle-wellness-agent-2lxj5uw.gamma.site/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChanMeng666.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"chanmeng66u","thanks_dev":null,"custom":null}},"created_at":"2025-05-19T08:59:18.000Z","updated_at":"2025-07-09T10:45:51.000Z","dependencies_parsed_at":"2025-07-09T11:53:34.229Z","dependency_job_id":"75022dee-242b-4c4e-aec8-c5b0f2d2d6f6","html_url":"https://github.com/ChanMeng666/wellness-agent","commit_stats":null,"previous_names":["chanmeng666/wellness-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChanMeng666/wellness-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fwellness-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fwellness-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fwellness-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fwellness-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChanMeng666","download_url":"https://codeload.github.com/ChanMeng666/wellness-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fwellness-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271447299,"owners_count":24761425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-assistant","employee-wellness","employer-insights","fastapi","gemini-ai","google-adk","hr-analytics","memory-system","multi-agent-system","nextjs","privacy-first","python","wellness-agent","workplace-wellness"],"created_at":"2025-08-21T07:48:39.283Z","updated_at":"2026-04-28T23:35:46.733Z","avatar_url":"https://github.com/ChanMeng666.png","language":"TypeScript","funding_links":["https://buymeacoffee.com/chanmeng66u"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n \u003ch1\u003e🌿 Wellness Support Agent\u003cbr/\u003e\u003csmall\u003eAI-Powered Workplace Wellness Platform\u003c/small\u003e\u003c/h1\u003e\n \u003cimg src=\"https://img.shields.io/badge/next.js-%23000000.svg?style=for-the-badge\u0026logo=next.js\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge\u0026logo=react\u0026logoColor=%2361DAFB\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/Google%20ADK-%234285F4.svg?style=for-the-badge\u0026logo=google\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?style=for-the-badge\u0026logo=tailwind-css\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/FastAPI-%23009688.svg?style=for-the-badge\u0026logo=fastapi\u0026logoColor=white\"/\u003e\n \u003cimg src=\"https://img.shields.io/badge/Gemini%20AI-%23FF6000.svg?style=for-the-badge\u0026logo=google\u0026logoColor=white\"/\u003e\n\u003c/div\u003e\n\n\u003e [!IMPORTANT]\n\u003e This is a comprehensive workplace wellness platform that combines Google's Agent Development Kit (ADK) with intelligent multi-agent systems. Built with Next.js frontend and Python backend, it provides privacy-focused support for employees, HR managers, and employers.\n\n# 🌟 Introduction\n\nA comprehensive AI-powered workplace wellness agent that leverages Google's Agent Development Kit (ADK) to provide intelligent, role-based wellness support across organizations. This full-stack application demonstrates modern multi-agent architecture with privacy-first design, real-time memory systems, and specialized agents for different organizational roles.\n\n\u003e [!NOTE]\n\u003e - Python \u003e= 3.9 required\n\u003e - Node.js \u003e= 18.0 required  \n\u003e - Google Cloud Platform account required\n\u003e - Google ADK toolkit required\n\u003e - Environment setup for Google AI services\n\n\u003cbr/\u003e\n\n[![🚀 Visit Documentation 🚀](https://gradient-svg-generator.vercel.app/api/svg?text=%F0%9F%9A%80Visit%20Documentation%F0%9F%9A%80\u0026color=000000\u0026height=60\u0026gradientType=radial\u0026duration=6s\u0026color0=ffffff\u0026template=pride-rainbow)](https://sanicle-wellness-agent-2lxj5uw.gamma.site/)\n\n\u003cbr/\u003e\n\n## ✨ Key Features\n\n🤖 **Multi-Agent AI System**\n- 5 specialized wellness agents with distinct expertise\n- Intelligent agent coordination and routing\n- Privacy-focused role-based access controls\n- Real-time conversational AI assistance\n\n🏥 **Comprehensive Wellness Support**\n- Employee symptom tracking and accommodation requests\n- HR manager anonymous trend analysis and policy creation\n- Employer ROI calculation and workforce insights\n- Privacy-first design with data protection\n\n🧠 **Advanced Memory System**\n- Persistent conversation memory across sessions\n- Personalized user experience with preference retention\n- Role-based memory access and data segregation\n- Default profile loading for new users\n\n🔒 **Enterprise Privacy Controls**\n- Role-based data access restrictions\n- Anonymous aggregation for organizational insights\n- GDPR-compliant data handling\n- Custom privacy callbacks and validation\n\n## 📚 Table of Contents\n\n- [🌟 Introduction](#-introduction)\n  - [✨ Key Features](#-key-features)\n  - [📚 Table of Contents](#-table-of-contents)\n  - [🛠️ Tech Stack](#️-tech-stack)\n  - [🏗️ Architecture Overview](#️-architecture-overview)\n    - [Multi-Agent System Architecture](#multi-agent-system-architecture)\n    - [Frontend Architecture](#frontend-architecture)\n    - [Backend Architecture](#backend-architecture)\n    - [Data Flow Architecture](#data-flow-architecture)\n  - [🎯 User Journey Workflows](#-user-journey-workflows)\n    - [For Employees](#for-employees)\n    - [For HR Managers](#for-hr-managers)\n    - [For Employers](#for-employers)\n  - [📂 Project Structure](#-project-structure)\n  - [🚀 Getting Started](#-getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Quick Start Installation](#quick-start-installation)\n    - [Environment Configuration](#environment-configuration)\n    - [Database Setup](#database-setup)\n  - [🤖 AI Agent System](#-ai-agent-system)\n    - [Available Agents](#available-agents)\n    - [Agent Capabilities](#agent-capabilities)\n  - [💾 Memory System](#-memory-system)\n  - [📖 Development Guide](#-development-guide)\n    - [Adding New Agent Modules](#adding-new-agent-modules)\n    - [Creating Custom Privacy Controls](#creating-custom-privacy-controls)\n    - [Performance Optimization](#performance-optimization)\n  - [🧪 Testing](#-testing)\n  - [🚀 Deployment](#-deployment)\n    - [Google Cloud Deployment](#google-cloud-deployment)\n    - [Frontend Deployment](#frontend-deployment)\n    - [Environment Variables](#environment-variables)\n  - [🧪 Testing](#-testing-1)\n  - [🤝 Contributing](#-contributing)\n  - [📄 License](#-license)\n  - [🙋‍♀️ Author](#️-author)\n\n## 🛠️ Tech Stack\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/nextdotjs\" width=\"48\" height=\"48\" alt=\"Next.js\" /\u003e\n        \u003cbr\u003eNext.js 15\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/react\" width=\"48\" height=\"48\" alt=\"React\" /\u003e\n        \u003cbr\u003eReact 19\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/typescript\" width=\"48\" height=\"48\" alt=\"TypeScript\" /\u003e\n        \u003cbr\u003eTypeScript\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/python\" width=\"48\" height=\"48\" alt=\"Python\" /\u003e\n        \u003cbr\u003ePython 3.9+\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/google\" width=\"48\" height=\"48\" alt=\"Google ADK\" /\u003e\n        \u003cbr\u003eGoogle ADK\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/fastapi\" width=\"48\" height=\"48\" alt=\"FastAPI\" /\u003e\n        \u003cbr\u003eFastAPI\n      \u003c/td\u003e\n      \u003ctd align=\"center\" width=\"96\"\u003e\n        \u003cimg src=\"https://cdn.simpleicons.org/googlecloud\" width=\"48\" height=\"48\" alt=\"Google Cloud\" /\u003e\n        \u003cbr\u003eGoogle Cloud\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n\u003e [!TIP]\n\u003e Each technology was carefully selected for enterprise-ready deployment, scalability, and Google Cloud integration. The multi-agent architecture allows for specialized AI assistance across different organizational roles while maintaining strict privacy controls.\n\n## 🏗️ Architecture Overview\n\n### Multi-Agent System Architecture\n\nThe platform employs a sophisticated multi-agent architecture built on Google's Agent Development Kit (ADK):\n\n```mermaid\ngraph TD\n    A[User Input] --\u003e B[Root Wellness Agent]\n    B --\u003e C[Agent Router \u0026 Coordinator]\n    \n    C --\u003e D[Employee Support Agent]\n    C --\u003e E[HR Manager Agent]\n    C --\u003e F[Employer Insights Agent]\n    C --\u003e G[Search Agent]\n    C --\u003e H[Leave Requests Agent]\n    \n    D --\u003e I[Memory System]\n    E --\u003e I\n    F --\u003e I\n    G --\u003e I\n    H --\u003e I\n    \n    I --\u003e J[Privacy Controls]\n    J --\u003e K[Database Layer]\n    K --\u003e L[Response Generation]\n    L --\u003e M[User Interface]\n```\n\n### Frontend Architecture\n\nBuilt with modern React patterns and Google Cloud integration:\n\n- **Component Architecture**: Modular, reusable components with TypeScript\n- **State Management**: Custom hooks with persistent memory integration\n- **Real-time Updates**: Agent-powered live interactions\n- **Performance**: Optimized rendering and memory caching\n- **Accessibility**: WCAG 2.1 compliant with screen reader support\n\n### Backend Architecture\n\nPython-based agent system with Google ADK orchestration:\n\n| Component | Purpose | Technology |\n|-----------|---------|------------|\n| Root Agent | Coordinates requests between specialized agents | Google ADK |\n| Sub-Agents | Domain-specific wellness assistance | Gemini 1.5 Flash |\n| Memory System | Persistent conversation and preference storage | Custom Implementation |\n| Privacy Layer | Role-based access controls and data protection | Custom Callbacks |\n| API Gateway | RESTful API with FastAPI | FastAPI + Uvicorn |\n\n### Data Flow Architecture\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant F as Frontend\n    participant R as Root Agent\n    participant A as Sub-Agent\n    participant M as Memory System\n    participant D as Database\n    \n    U-\u003e\u003eF: Wellness Request\n    F-\u003e\u003eR: Process Request\n    R-\u003e\u003eA: Route to Specialist\n    A-\u003e\u003eM: Check/Update Memory\n    M-\u003e\u003eD: Persistent Storage\n    A-\u003e\u003eR: Generated Response\n    R-\u003e\u003eF: AI Response\n    F-\u003e\u003eU: Real-time Updates\n```\n\n## 🎯 User Journey Workflows\n\n### For Employees\n\n```mermaid\njourney\n    title Employee Wellness Journey\n    section Awareness\n        Understand symptoms impact: 5\n    section Onboarding\n        Private account setup: 4\n    section Tracking\n        Log daily wellness: 5\n        Request accommodations: 4\n    section Support\n        Get personalized tips: 5\n    section Reflection\n        View personal trends: 4\n```\n\n**Employee Experience:**\n- **Symptom Continuity**: Track personal wellness patterns over time\n- **Preference Retention**: Have communication style and accommodations remembered\n- **Personalized Experience**: Receive increasingly tailored wellness tips\n- **Privacy Control**: Maintain full control over personal health information\n\n### For HR Managers\n\n```mermaid\njourney\n    title HR Manager Journey\n    section Awareness\n        Identify workplace patterns: 5\n    section Onboarding\n        Configure company policies: 4\n    section Insights\n        View anonymous trends: 5\n        Manage accommodation requests: 4\n    section Action\n        Develop evidence-based policies: 5\n    section Continuity\n        Track policy effectiveness: 4\n```\n\n**HR Manager Experience:**\n- **Organizational Context**: Maintain continuity in policy decisions\n- **Pattern Recognition**: Identify anonymous wellness trends\n- **Accommodation Consistency**: Handle similar requests fairly\n- **Policy Evolution**: Track policy effectiveness over time\n\n### For Employers\n\n```mermaid\njourney\n    title Employer Journey\n    section Awareness\n        Understand wellness ROI: 5\n    section Integration\n        Secure system setup: 4\n    section Impact\n        Quantify wellness outcomes: 5\n        Forecast workforce needs: 4\n    section Strategy\n        Develop wellness strategy: 5\n    section Continuity\n        Track long-term impact: 4\n```\n\n**Employer Experience:**\n- **Strategic Memory**: Track ROI and impacts over time\n- **Benchmarking**: Compare effectiveness of different programs\n- **Reporting Continuity**: Maintain consistent metrics\n- **Cultural Progress**: Monitor improvements in workplace wellness\n\n## 📂 Project Structure\n\n```\nwellness-agent/\n├── frontend/                     # Next.js frontend application\n│   ├── app/\n│   │   ├── (auth)/              # Authentication routes\n│   │   ├── (chat)/              # Chat interface\n│   │   └── api/                 # API routes\n│   ├── components/              # Reusable UI components\n│   │   ├── ui/                  # Base UI components\n│   │   ├── chat.tsx             # Chat interface\n│   │   ├── sidebar.tsx          # Navigation sidebar\n│   │   └── auth-form.tsx        # Authentication forms\n│   ├── hooks/                   # Custom React hooks\n│   └── lib/                     # Utility libraries\n├── wellness_agent/              # Backend AI agent system\n│   ├── sub_agents/              # Specialized agent modules\n│   │   ├── employee_support/    # Employee wellness agent\n│   │   ├── hr_manager/          # HR management agent\n│   │   ├── employer_insights/   # Employer analytics agent\n│   │   ├── search/              # Web search agent\n│   │   └── leave_requests/      # Leave request agent\n│   ├── services/                # Business logic services\n│   │   ├── db/                  # Database services\n│   │   ├── analytics_service.py # Analytics processing\n│   │   └── service_factory.py   # Service orchestration\n│   ├── shared_libraries/        # Common utilities\n│   │   ├── memory.py            # Memory management system\n│   │   └── emoji_inputs.py      # UI helper utilities\n│   ├── privacy/                 # Privacy control system\n│   │   ├── anonymizer.py        # Data anonymization\n│   │   └── callbacks.py         # Privacy validation\n│   ├── db/                      # Database models and schemas\n│   │   ├── models/              # Data models\n│   │   └── default_profiles/    # Default user profiles\n│   ├── tools/                   # Agent tools and handlers\n│   ├── agent.py                 # Main agent coordinator\n│   ├── server.py                # FastAPI server\n│   └── prompts.py               # Agent instructions\n├── deployment/                  # Deployment scripts\n│   ├── deploy.py                # Google Cloud deployment\n│   └── test_deployment.py       # Deployment testing\n├── eval/                        # Evaluation framework\n├── tests/                       # Test suites\n├── mock_db/                     # Mock data for development\n└── requirements.txt             # Python dependencies\n```\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n\u003e [!IMPORTANT]\n\u003e Ensure you have the following installed:\n\u003e - Python 3.9 or higher\n\u003e - Node.js 18.0 or higher\n\u003e - npm or yarn package manager\n\u003e - Git version control\n\u003e - Google Cloud Platform account\n\u003e - Google ADK toolkit\n\u003e - Environment access to Google AI services\n\n### Quick Start Installation\n\n**1. Clone and Setup Backend:**\n\n```bash\n# Clone the repository\ngit clone https://github.com/ChanMeng666/wellness-agent.git\ncd wellness-agent\n\n# Create virtual environment\npython -m venv .venv\n\n# Activate virtual environment\n# Windows:\n.venv\\Scripts\\activate\n# macOS/Linux:\nsource .venv/bin/activate\n\n# Install Python dependencies\npip install -r requirements.txt\n```\n\n**2. Setup Frontend:**\n\n```bash\n# Navigate to frontend directory\ncd frontend\n\n# Install frontend dependencies\nnpm install\n```\n\n**3. Initialize Mock Database:**\n\n```bash\n# Return to root directory\ncd ..\n\n# Setup mock data for development\npython setup_mock_data.py\n```\n\n### Environment Configuration\n\n**Root Environment (.env):**\n\n```bash\n# Google AI Configuration\nGOOGLE_API_KEY=your_google_api_key_here\nGOOGLE_CLOUD_PROJECT=your_gcp_project_id\nGOOGLE_CLOUD_LOCATION=us-central1\nGOOGLE_CLOUD_STORAGE_BUCKET=your_storage_bucket\n\n# Development Configuration\nUSE_MOCK_SERVICES=true\nLOG_LEVEL=INFO\n\n# Demo User Configuration\nDEMO_PROFILE_ID=demo_profile_123\nDEMO_ORGANIZATION_ID=demo_org_456\n```\n\n**Frontend Environment (frontend/.env.local):**\n\n```bash\n# Backend API Configuration\nNEXT_PUBLIC_BACKEND_URL=http://localhost:8000\n\n# Authentication Configuration\nNEXTAUTH_SECRET=your_nextauth_secret_here\nNEXTAUTH_URL=http://localhost:3000\n\n# Database Configuration (if using persistent storage)\nPOSTGRES_URL=your_postgres_connection_string\n```\n\n### Database Setup\n\n**For Development (Mock Database):**\n\nThe project includes a comprehensive mock database system that simulates real enterprise data:\n\n```bash\n# Initialize mock data\npython setup_mock_data.py\n\n# This creates:\n# - Sample employee profiles\n# - Mock accommodation requests\n# - Wellness program data\n# - Anonymized trend data\n```\n\n**For Production (Google Cloud):**\n\n```bash\n# Setup Google Cloud services\ngcloud auth application-default login\ngcloud config set project YOUR_PROJECT_ID\n\n# Initialize Firestore database\n# (This will be handled automatically by the deployment script)\n```\n\n**4. Start the Application:**\n\n**Terminal 1 - Backend:**\n```bash\n# Activate virtual environment\n.venv\\Scripts\\activate  # Windows\n# source .venv/bin/activate  # macOS/Linux\n\n# Start the ADK development server\nadk web\n# Or start the FastAPI server directly\npython run_dev_server.py\n```\n\n**Terminal 2 - Frontend:**\n```bash\ncd frontend\nnpm run dev\n```\n\n**5. Access the Application:**\n\n- **Frontend**: http://localhost:3000\n- **Backend API**: http://localhost:8000\n- **ADK Web Interface**: http://localhost:8080\n- **API Documentation**: http://localhost:8000/docs\n\n## 🤖 AI Agent System\n\n### Available Agents\n\nThe platform features 5 specialized AI agents built on Google's Agent Development Kit:\n\n| Agent | Purpose | Capabilities | Privacy Level |\n|-------|---------|-------------|---------------|\n| **Employee Support** | Personal wellness assistance | Symptom tracking, wellness tips, accommodation requests | Fully Private |\n| **HR Manager** | Anonymous trend analysis | Department metrics, policy creation, request management | Anonymized Data |\n| **Employer Insights** | Organizational analytics | ROI calculation, workforce planning, culture insights | Aggregated Data |\n| **Search Agent** | Web-based wellness information | Evidence-based research, policy templates, best practices | Public Data |\n| **Leave Requests** | Accommodation processing | Request handling, plan creation, privacy-first processing | Role-Based Access |\n\n### Agent Capabilities\n\n**🗣️ Natural Language Processing:**\n- Conversational wellness queries with context awareness\n- Multi-turn dialogue support with memory persistence\n- Intent recognition across different organizational roles\n- Empathetic response generation for sensitive topics\n\n**📊 Data Integration:**\n- Real-time database operations with privacy controls\n- Cross-agent data correlation and insights\n- Intelligent data validation and sanitization\n- Automated trend analysis and reporting\n\n**🎯 Role-Based Personalization:**\n- Individual user profile adaptation and learning\n- Organization-specific policy and culture integration\n- Learning from interaction patterns and feedback\n- Adaptive response optimization by user role\n\n## 💾 Memory System\n\nThe platform implements a sophisticated memory system that enhances user experience while preserving privacy:\n\n```mermaid\ngraph LR\n    A[Memory System] --\u003e B[Core Functions]\n    A --\u003e C[Storage Layer]\n    A --\u003e D[Privacy Controls]\n    \n    B --\u003e B1[\"memorize()\"]\n    B --\u003e B2[\"memorize_list()\"]\n    B --\u003e B3[\"forget()\"]\n    B --\u003e B4[\"get_memory()\"]\n    B --\u003e B5[\"clear_memory_key()\"]\n    \n    C --\u003e C1[Session State]\n    C --\u003e C2[Database Persistence]\n    C --\u003e C3[Default Profiles]\n    \n    D --\u003e D1[Role-Based Access]\n    D --\u003e D2[Privacy Levels]\n    D --\u003e D3[Data Expiration]\n```\n\n**Memory Functions:**\n- `memorize(key, value)`: Store single key-value pairs for user preferences\n- `memorize_list(key, value)`: Append to lists for tracking multiple items\n- `forget(key, value)`: Remove specific information while preserving context\n- `get_memory(key)`: Retrieve stored information with privacy validation\n- `clear_memory_key(key)`: Erase entire categories of information\n\n**Privacy Architecture:**\n- **Employee Memory**: Personal health data, preferences, accommodation history\n- **HR Memory**: Policy decisions, department patterns, process improvements\n- **Employer Memory**: Business metrics, ROI data, strategic initiatives\n- **Cross-Role Protection**: Strict data segregation between user types\n\n## 📖 Development Guide\n\n### Adding New Agent Modules\n\n**1. Create Agent Structure:**\n\n```bash\n# Create new agent directory\nmkdir wellness_agent/sub_agents/new_agent\n\n# Create agent files\ntouch wellness_agent/sub_agents/new_agent/__init__.py\ntouch wellness_agent/sub_agents/new_agent/agent.py\n```\n\n**2. Implement Agent Logic:**\n\n```python\n# wellness_agent/sub_agents/new_agent/agent.py\nfrom google.adk.agents import Agent\nfrom google.adk.tools.agent_tool import AgentTool\nfrom wellness_agent.shared_libraries.memory import memorize, get_memory\nfrom google.adk.tools import FunctionTool\n\n# Create memory tools\nmemory_tools = [\n    FunctionTool(func=memorize),\n    FunctionTool(func=get_memory)\n]\n\n# Create specialized agent\nnew_agent = Agent(\n    name=\"new_wellness_agent\",\n    description=\"Agent for specialized wellness functionality\",\n    model=\"gemini-1.5-flash\",\n    instruction=\"\"\"Your agent instruction here...\"\"\",\n    tools=memory_tools\n)\n\n# Create agent tool\nnew_agent_tool = AgentTool(agent=new_agent)\n```\n\n**3. Register Agent:**\n\n```python\n# Add to wellness_agent/agent.py\nfrom wellness_agent.sub_agents.new_agent.agent import new_agent_tool\n\n# Add to root agent tools list\nroot_agent = Agent(\n    # ... existing configuration\n    tools=[\n        # ... existing tools\n        new_agent_tool\n    ]\n)\n```\n\n### Creating Custom Privacy Controls\n\n**Privacy Callback Template:**\n\n```python\nfrom typing import Dict, Any\n\ndef custom_privacy_callback(state: Dict[str, Any]) -\u003e Dict[str, Any]:\n    \"\"\"\n    Custom privacy control implementation.\n    \"\"\"\n    user_role = state.get(\"user_role\", \"unknown\")\n    \n    # Implement role-based filtering\n    if user_role == \"employee\":\n        # Full access to personal data\n        return state\n    elif user_role == \"hr_manager\":\n        # Filter individual health data\n        return filter_individual_data(state)\n    elif user_role == \"employer\":\n        # Only aggregated organizational data\n        return filter_to_aggregated_data(state)\n    \n    return state\n\ndef filter_individual_data(state: Dict[str, Any]) -\u003e Dict[str, Any]:\n    \"\"\"Remove individual employee health information\"\"\"\n    filtered_state = state.copy()\n    sensitive_keys = ['employee_symptoms', 'personal_health_data']\n    for key in sensitive_keys:\n        filtered_state.pop(key, None)\n    return filtered_state\n```\n\n### Performance Optimization\n\n**Memory Caching Strategy:**\n\n```python\n# Implement intelligent caching\nclass MemoryCache:\n    def __init__(self):\n        self.cache = {}\n        self.ttl = {\n            'user_preferences': 86400,    # 24 hours\n            'wellness_tips': 3600,        # 1 hour\n            'trend_data': 1800,           # 30 minutes\n            'policy_documents': 7200      # 2 hours\n        }\n    \n    def get_with_cache(self, key: str, data_type: str):\n        # Implement cache-first data retrieval\n        if key in self.cache and not self.is_expired(key, data_type):\n            return self.cache[key]\n        \n        # Fetch fresh data and cache\n        fresh_data = self.fetch_from_database(key)\n        self.cache[key] = fresh_data\n        return fresh_data\n```\n\n## 🧪 Testing\n\n**Testing Framework:**\n\nRun the comprehensive test suite:\n\n```bash\n# Backend tests\npytest tests/\n\n# Test specific agent functionality  \npython -m pytest tests/test_agents.py\n\n# Test deployment\ncd deployment\npython test_deployment.py --resource_id YOUR_DEPLOYED_AGENT_ID --user_id test_user\n```\n\n**Frontend Testing:**\n\n```bash\ncd frontend\nnpm test\nnpm run test:e2e\n```\n\n**Test Coverage Areas:**\n- ✅ Agent initialization and tool configuration\n- ✅ Memory system persistence and retrieval\n- ✅ Privacy controls and role-based access\n- ✅ Multi-agent coordination and routing\n- ✅ API integration and responses\n- ✅ End-to-end user journey validation\n\n## 🚀 Deployment\n\n### Google Cloud Deployment\n\n**Using ADK Deployment Tools:**\n\n```bash\n# Authenticate with Google Cloud\ngcloud auth application-default login\ngcloud config set project YOUR_PROJECT_ID\n\n# Deploy agent to Google Cloud\ncd deployment\npython deploy.py --create --project_id YOUR_PROJECT_ID --location us-central1\n```\n\n**Agent Engine Configuration:**\n\n```python\n# deployment/deploy.py configuration\nremote_agent = agent_engines.create(\n    adk_app,\n    display_name=\"Wellness Support Agent\",\n    requirements=[\n        \"google-adk (\u003e=0.0.2)\",\n        \"google-cloud-aiplatform[agent_engines] (\u003e=1.91.0)\",\n        \"google-genai (\u003e=1.5.0)\",\n        \"pydantic (\u003e=2.10.6)\",\n        \"python-dotenv (\u003e=1.0.0)\"\n    ]\n)\n```\n\n### Frontend Deployment\n\n**Vercel Deployment:**\n\n```bash\n# Frontend deployment\ncd frontend\nnpm run build\nvercel --prod\n```\n\n**Docker Deployment:**\n\n```dockerfile\n# Dockerfile for backend\nFROM python:3.9-slim\nWORKDIR /app\nCOPY . .\nRUN pip install -r requirements.txt\nCMD [\"python\", \"run_dev_server.py\"]\n```\n\n### Environment Variables\n\n**Production Environment Variables:**\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `GOOGLE_API_KEY` | Google AI services access | ✅ |\n| `GOOGLE_CLOUD_PROJECT` | GCP project identifier | ✅ |\n| `GOOGLE_CLOUD_LOCATION` | GCP deployment region | ✅ |\n| `GOOGLE_CLOUD_STORAGE_BUCKET` | File storage bucket | ✅ |\n| `USE_MOCK_SERVICES` | Development mode toggle | 🔶 |\n| `LOG_LEVEL` | Application logging level | 🔶 |\n\n## 🧪 Testing\n\n```mermaid\nflowchart LR\n    A[Testing] --\u003e B[Unit Tests]\n    A --\u003e C[Integration Tests]\n    A --\u003e D[Agent Behavior Tests]\n    \n    B --\u003e B1[Memory System Tests]\n    B --\u003e B2[Privacy Control Tests]\n    B --\u003e B3[Tool Function Tests]\n    \n    C --\u003e C1[API Integration]\n    C --\u003e C2[Database Integration]\n    C --\u003e C3[Agent Engine Tests]\n    \n    D --\u003e D1[User Journey Tests]\n    D --\u003e D2[Multi-Agent Coordination]\n```\n\n**Testing Framework:**\n\nRun the comprehensive test suite:\n\n```bash\n# Backend tests\npytest tests/\n\n# Test specific agent functionality\npython -m pytest tests/test_agents.py\n\n# Test deployment\ncd deployment\npython test_deployment.py --resource_id YOUR_DEPLOYED_AGENT_ID --user_id test_user\n```\n\n**Frontend Testing:**\n\n```bash\ncd frontend\nnpm test\nnpm run test:e2e\n```\n\n**Evaluation Framework:**\n\n```bash\n# Run agent evaluation\ncd eval\npython test_eval.py\n```\n\n**Test Coverage Areas:**\n- ✅ **Agent Initialization**: All 5 agents properly initialize with correct tools\n- ✅ **Memory System**: Persistent storage and retrieval across sessions\n- ✅ **Privacy Controls**: Role-based data access and filtering\n- ✅ **Multi-Agent Routing**: Proper request routing to specialized agents\n- ✅ **API Integration**: RESTful API endpoints and responses\n- ✅ **User Journeys**: End-to-end workflow validation\n\n## 🤝 Contributing\n\nWe welcome contributions to the Wellness Support Agent! Here's how you can help:\n\n**Development Process:**\n\n1. **Fork and Clone:**\n```bash\ngit clone https://github.com/ChanMeng666/wellness-agent.git\ncd wellness-agent\n```\n\n2. **Create Feature Branch:**\n```bash\ngit checkout -b feature/amazing-wellness-feature\n```\n\n3. **Development Setup:**\n```bash\n# Backend setup\npython -m venv .venv\nsource .venv/bin/activate  # or .venv\\Scripts\\activate on Windows\npip install -r requirements.txt\n\n# Frontend setup\ncd frontend\nnpm install\nnpm run dev\n```\n\n4. **Code Guidelines:**\n- ✅ Follow Google ADK best practices\n- ✅ Implement comprehensive privacy controls\n- ✅ Add unit tests for new agent functionality\n- ✅ Follow accessibility guidelines (WCAG 2.1)\n- ✅ Add proper error handling and validation\n- ✅ Document agent instructions and capabilities\n\n5. **Submit Pull Request:**\n- Provide clear description of wellness functionality changes\n- Include test cases for new agent behaviors\n- Reference related issues or feature requests\n- Ensure all privacy controls are properly implemented\n\n**Issue Reporting:**\n- 🐛 Bug reports with agent behavior details\n- 💡 Feature requests for new wellness capabilities\n- 📚 Documentation improvements\n- 🔒 Privacy and security enhancements\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 🙋‍♀️ Author\n\n**Chan Meng** - Senior AI/ML Infrastructure Engineer\n- \u003cimg src=\"https://cdn.simpleicons.org/linkedin/0A66C2\" width=\"16\" height=\"16\"\u003e LinkedIn: [chanmeng666](https://www.linkedin.com/in/chanmeng666/)\n- \u003cimg src=\"https://cdn.simpleicons.org/github/181717\" width=\"16\" height=\"16\"\u003e GitHub: [ChanMeng666](https://github.com/ChanMeng666)\n- \u003cimg src=\"https://cdn.simpleicons.org/gmail/EA4335\" width=\"16\" height=\"16\"\u003e Email: chanmeng.dev@gmail.com\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003cstrong\u003e🌿 Empowering Workplace Wellness Through AI 💼\u003c/strong\u003e\n\u003cbr/\u003e\n\u003cem\u003ePrivacy-first AI agents for organizational health and wellbeing\u003c/em\u003e\n\u003cbr/\u003e\u003cbr/\u003e\n⭐ Star us on GitHub | 📖 Read the Docs | 🐛 Report Issues | 💡 Request Features\n\u003cbr/\u003e\u003cbr/\u003e\n\u003cimg src=\"https://img.shields.io/github/stars/ChanMeng666/wellness-agent?style=social\" alt=\"GitHub stars\"\u003e\n\u003cimg src=\"https://img.shields.io/github/forks/ChanMeng666/wellness-agent?style=social\" alt=\"GitHub forks\"\u003e\n\u003cimg src=\"https://img.shields.io/github/watchers/ChanMeng666/wellness-agent?style=social\" alt=\"GitHub watchers\"\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanmeng666%2Fwellness-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanmeng666%2Fwellness-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanmeng666%2Fwellness-agent/lists"}