Spaces:
Running
Running
|
Download PROJECT_SUMMARY.md from mackenzietechdocs/HealixPath: direct link, hf CLI and curl.
- Browser
- Download file 8.37 kB
-
https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/PROJECT_SUMMARY.md
- Command line
-
hf download hf://spaces/mackenzietechdocs/HealixPath/PROJECT_SUMMARY.md
-
curl -L -o PROJECT_SUMMARY.md https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/PROJECT_SUMMARY.md
8.37 kB
| # HealixPath - Project Summary | |
| ## π― Mission | |
| HealixPath is an enterprise-grade **Model Context Protocol (MCP) server** and **Gradio web interface** that generates realistic, actionable user stories grounded in deeply researched personas. It transforms product inputs, personas, problems, and customer journey stages into rich, structured, realistic narratives. | |
| ## π Project Structure | |
| ``` | |
| healixpath/ | |
| βββ src/ | |
| β βββ tools/ | |
| β β βββ user_story.ts # Generate structured user stories | |
| β β βββ customer_experience_tale.ts # Create experience narratives | |
| β β βββ feature_impact_story.ts # Before/after feature stories | |
| β β βββ journey_map_story.ts # Journey stage narratives | |
| β βββ utils/ | |
| β β βββ persona_loader.ts # Load and manage personas | |
| β β βββ helpers.ts # Utility functions | |
| β βββ index.ts # MCP server initialization | |
| βββ data/ | |
| β βββ personas.json # Pre-defined personas | |
| βββ app.py # Gradio web interface | |
| βββ package.json # Node.js dependencies | |
| βββ tsconfig.json # TypeScript configuration | |
| βββ requirements.txt # Python dependencies | |
| βββ README.md # Project documentation (with HF Spaces config) | |
| βββ DEPLOYMENT.md # Deployment guide | |
| βββ mcp.config.json # MCP server configuration | |
| βββ .env.example # Environment variables template | |
| βββ .gitignore # Git ignore patterns | |
| ``` | |
| ## πΉ Four Core Tools | |
| ### 1. **user_story** | |
| Generates structured narrative user stories with acceptance criteria and risks. | |
| **Input:** | |
| - `product`: Description of the product/feature | |
| - `persona_id` (optional): ID of the persona (busy_parent, ops_engineer, product_manager) | |
| - `persona_override` (optional): Custom persona description | |
| **Output:** | |
| ```json | |
| { | |
| "story": "Detailed narrative (150-300 words)", | |
| "acceptance_criteria": ["criterion 1", "criterion 2"], | |
| "risks": ["risk 1", "risk 2"] | |
| } | |
| ``` | |
| ### 2. **customer_experience_tale** | |
| Creates narratives describing a persona experiencing a specific problem. | |
| **Input:** | |
| - `problem`: The problem the persona is experiencing | |
| - `persona_id` (optional): ID of the persona | |
| - `persona_override` (optional): Custom persona description | |
| **Output:** | |
| ```json | |
| { | |
| "title": "Compelling title", | |
| "narrative": "250-400 word story", | |
| "pain_points": ["pain 1", "pain 2"], | |
| "opportunities": ["opportunity 1", "opportunity 2"] | |
| } | |
| ``` | |
| ### 3. **feature_impact_story** | |
| Shows before and after of a persona interacting with a feature. | |
| **Input:** | |
| - `feature_description`: Description of the feature | |
| - `persona_id` (optional): ID of the persona | |
| - `persona_override` (optional): Custom persona description | |
| **Output:** | |
| ```json | |
| { | |
| "before_story": "300 word narrative without feature", | |
| "after_story": "300 word narrative with feature", | |
| "key_benefits": ["benefit 1", "benefit 2"], | |
| "success_metrics": ["metric 1", "metric 2"] | |
| } | |
| ``` | |
| ### 4. **journey_map_story** | |
| Generates narrative for specific stages of the user journey. | |
| **Input:** | |
| - `stage`: Journey stage (awareness, consideration, adoption, retention) | |
| - `product`: Description of the product | |
| - `persona_id` (optional): ID of the persona | |
| - `persona_override` (optional): Custom persona description | |
| **Output:** | |
| ```json | |
| { | |
| "stage": "adoption", | |
| "narrative": "250-300 word narrative", | |
| "touchpoints": ["touchpoint 1", "touchpoint 2"], | |
| "emotions": ["emotion 1", "emotion 2"], | |
| "breakdowns": ["breakdown 1", "breakdown 2"], | |
| "opportunities": ["opportunity 1", "opportunity 2"] | |
| } | |
| ``` | |
| ## π₯ Built-in Personas | |
| ### 1. **Busy Parent** (`busy_parent`) | |
| - **Role**: Working parent of two kids | |
| - **Goals**: Save time, reduce mental load, keep kids on schedule | |
| - **Tech Comfort**: Medium | |
| - **Quote**: "If it's not simple, I don't have time for it." | |
| ### 2. **Ops Engineer** (`ops_engineer`) | |
| - **Role**: On-call site reliability engineer | |
| - **Goals**: Reduce alerts, improve stability, automate tasks | |
| - **Tech Comfort**: High | |
| - **Quote**: "If it breaks, it's my problem at 3am." | |
| ### 3. **Product Manager** (`product_manager`) | |
| - **Role**: PM at a healthcare startup | |
| - **Goals**: Understand users deeply, make data-driven decisions, validate quickly | |
| - **Tech Comfort**: High | |
| - **Quote**: "I need to understand my users' hearts, not just their actions." | |
| ## π Getting Started | |
| ### Prerequisites | |
| - Node.js 20+ | |
| - Python 3.10+ | |
| - npm or yarn | |
| ### Installation | |
| ```bash | |
| # Install Node dependencies | |
| npm install | |
| # Install Python dependencies | |
| pip install -r requirements.txt | |
| ``` | |
| ### Development | |
| ```bash | |
| # Build TypeScript | |
| npm run build | |
| # Run MCP Server | |
| npm run start | |
| # Run Gradio Interface (in another terminal) | |
| python app.py | |
| ``` | |
| ### Production | |
| ```bash | |
| # Build for production | |
| npm run build | |
| # Deploy to Hugging Face Spaces | |
| git push # (after setting up Space repo) | |
| ``` | |
| ## π§ Configuration | |
| ### Hugging Face Spaces YAML (in README.md) | |
| ```yaml | |
| --- | |
| title: HealixPath | |
| emoji: π | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: gradio | |
| sdk_version: 5.49.1 | |
| app_file: app.py | |
| pinned: true | |
| short_description: AI-powered persona storytelling engine | |
| tags: | |
| - mcp-hackathon | |
| - building-mcp-track-enterprise | |
| - healthcare | |
| - ai | |
| --- | |
| ``` | |
| ### Environment Variables | |
| Create `.env` file (see `.env.example`): | |
| ```env | |
| ANTHROPIC_API_KEY=sk_your_key_here | |
| HF_TOKEN=hf_your_token_here | |
| GRADIO_SERVER_PORT=7860 | |
| ``` | |
| ## π User Interfaces | |
| ### MCP Server (Node.js) | |
| - **Port**: Configurable (default 3000) | |
| - **Integration**: Works with Claude, other AI models, and custom applications | |
| - **Usage**: See `src/index.ts` for implementation example | |
| ### Gradio Web Interface (Python) | |
| - **Port**: 7860 (Hugging Face Spaces default) | |
| - **Features**: | |
| - Interactive UI with 4 tabs (one for each tool) | |
| - Pre-loaded personas dropdown | |
| - Custom persona input | |
| - Real-time generation | |
| ## π Key Technologies | |
| ### Backend | |
| - **TypeScript** - Type-safe JavaScript | |
| - **Node.js** - JavaScript runtime | |
| - **Model Context Protocol (MCP)** - Standard interface for AI assistants | |
| - **Anthropic SDK** - Claude API integration | |
| ### Frontend | |
| - **Gradio** - Python web framework for ML demos | |
| - **Python** - Scripting language | |
| ### Deployment | |
| - **Hugging Face Spaces** - Free hosting for ML demos | |
| - **Docker** - Containerization (optional) | |
| - **Git** - Version control | |
| ## π― Hackathon Features | |
| β¨ **Ready for Demo:** | |
| - Complete MCP server implementation | |
| - Interactive Gradio web UI | |
| - Pre-loaded sample personas | |
| - Hugging Face Spaces configuration | |
| - Full project documentation | |
| - Example tool calls in index.ts | |
| π **Integration Ready:** | |
| - Works with Claude API (placeholder ready for integration) | |
| - Standard MCP interface for tools | |
| - JSON-based I/O for easy integration | |
| - Extensible persona system | |
| π **Deploy Ready:** | |
| - One-click deployment to Hugging Face Spaces | |
| - Docker support for custom deployments | |
| - Environment variable configuration | |
| - Logging and monitoring | |
| ## π Next Steps for Production | |
| 1. **API Integration**: Replace placeholder functions with actual Claude API calls | |
| 2. **Custom Personas**: Add domain-specific personas for your use case | |
| 3. **Data Persistence**: Connect to database for storing generated stories | |
| 4. **Authentication**: Add user authentication with Hugging Face OAuth | |
| 5. **Caching**: Implement Redis for response caching | |
| 6. **Testing**: Add comprehensive unit and integration tests | |
| 7. **Monitoring**: Set up error tracking and analytics | |
| 8. **Documentation**: Add API documentation and user guides | |
| ## π€ Contributing | |
| To extend HealixPath: | |
| 1. Add new personas to `data/personas.json` | |
| 2. Create new tools in `src/tools/` | |
| 3. Update `src/index.ts` to register new tools | |
| 4. Add corresponding UI tabs in `app.py` | |
| 5. Test with MCP server examples | |
| ## π License | |
| MIT License - See LICENSE file for details | |
| ## π Built for MCP Hackathon | |
| HealixPath is an enterprise-ready solution demonstrating the power of MCP in building AI-driven applications for real-world use cases in healthcare, product management, and UX design. | |
| --- | |
| **Version**: 1.0.0 | |
| **Last Updated**: November 2025 | |
| **Status**: Production Ready for Hackathon Demo | |