HealixPath / QUICKSTART.md
mackenzietechdocs's picture DevRubenArevalo's picture
project-init-alpha (#2)
c6a01e9 verified
|
Raw History Blame Contribute Delete
5.06 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

HealixPath - Quick Start Guide

πŸš€ 30-Second Setup

# 1. Install dependencies
npm install
pip install -r requirements.txt

# 2. Build TypeScript
npm run build

# 3. Run Gradio App
python app.py

# 4. Open browser to http://localhost:7860

πŸ“– 60-Second Demo

  1. Open the Gradio UI at http://localhost:7860
  2. Navigate to "User Story" tab
  3. Enter Product: "Healthcare appointment scheduling app"
  4. Select Persona: "Busy Parent"
  5. Click "Generate User Story"
  6. See the generated narrative and acceptance criteria!

πŸ”§ MCP Server Usage

Start the Server

# Terminal 1: Start MCP Server
npm run start

Use with Claude (Terminal 2)

# Example: Call user_story tool
curl -X POST http://localhost:3000/tool/user_story \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Healthcare platform",
    "persona_id": "busy_parent"
  }'

πŸ“ Key Files to Modify

Add Custom Personas

Edit data/personas.json:

{
  "id": "custom_persona",
  "name": "Custom Name",
  "role": "Role description",
  "goals": ["goal 1", "goal 2"],
  "frustrations": ["frustration 1"],
  "tech_comfort": "medium",
  "quote": "Inspirational quote"
}

Connect Claude API

In src/tools/user_story.ts:

// Replace placeholder with actual Claude call
import Anthropic from "@anthropic-sdk/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [{ role: "user", content: userPrompt }],
});

🌐 Deploy to Hugging Face Spaces

1. Create Space

2. Push Code

git clone https://huggingface.co/spaces/<username>/healixpath
cd healixpath
# Copy all files from local repo
git add .
git commit -m "Deploy HealixPath"
git push

3. Space Auto-Deploys

  • Hugging Face automatically builds and deploys
  • Your app is live at huggingface.co/spaces/<username>/healixpath

🎯 Tool Examples

Generate User Story

Input:

{
  "product": "Mental health mobile app",
  "persona_id": "busy_parent"
}

Output:

{
  "story": "As a busy parent...",
  "acceptance_criteria": ["...", "...", "..."],
  "risks": ["..."]
}

Generate Experience Tale

Input:

{
  "problem": "App crashes when uploading large files",
  "persona_id": "ops_engineer"
}

Generate Feature Impact

Input:

{
  "feature_description": "Offline mode with sync",
  "persona_id": "busy_parent"
}

Generate Journey Map

Input:

{
  "stage": "adoption",
  "product": "Healthcare platform",
  "persona_id": "product_manager"
}

πŸ› Troubleshooting

Port Already in Use

# Kill process on port 7860
# Windows:
netstat -ano | findstr :7860
taskkill /PID <PID> /F

# Mac/Linux:
lsof -ti:7860 | xargs kill -9

Missing Dependencies

# Reinstall all
rm -rf node_modules
npm install
pip install -r requirements.txt --force-reinstall

Gradio Won't Start

# Check Python version
python --version  # Should be 3.10+

# Check Gradio installation
pip show gradio

Build Errors

# Check TypeScript syntax
npm run build

# View error details
cat dist/*.d.ts

πŸ“š Documentation

  • Full Documentation: See README.md
  • Project Summary: See PROJECT_SUMMARY.md
  • Deployment Guide: See DEPLOYMENT.md
  • API Reference: Check src/index.ts for tool definitions

πŸŽ“ Learning Resources

Understanding Personas

Each persona has:

  • Goals: What they want to achieve
  • Frustrations: What blocks them
  • Quote: Their perspective
  • Tech Comfort: Skill level (low/medium/high)

Story Generation Workflow

  1. Load persona data β†’ 2. Create context β†’ 3. Generate with AI β†’ 4. Format output β†’ 5. Return JSON

MCP Protocol

  • Tools are registered with name, description, input schema
  • Input schema defines required/optional parameters
  • Output is always JSON
  • Errors are caught and returned as JSON

πŸš€ Next Steps

  1. βœ… Get it running locally
  2. βœ… Try each tool with different personas
  3. βœ… Customize personas for your domain
  4. βœ… Deploy to Hugging Face Spaces
  5. βœ… Integrate Claude API for real generations
  6. βœ… Share with your team!

πŸ’‘ Tips & Tricks

  • Persona Override: Use custom persona text if ID not found
  • Batch Generation: Call tools multiple times for different personas
  • JSON Export: Copy generated JSON for further processing
  • Gradio Sharing: Use demo.share() in app.py for public URL

πŸ“ž Support

For issues or questions:

  1. Check DEPLOYMENT.md for deployment issues
  2. Review PROJECT_SUMMARY.md for architecture details
  3. Inspect src/index.ts for MCP implementation
  4. Check Gradio docs at gradio.app

Happy Storytelling! 🎭