Spaces:
Running
Running
|
Download QUICKSTART.md from mackenzietechdocs/HealixPath: direct link, hf CLI and curl.
- Browser
- Download file 5.06 kB
-
https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/QUICKSTART.md
- Command line
-
hf download hf://spaces/mackenzietechdocs/HealixPath/QUICKSTART.md
-
curl -L -o QUICKSTART.md https://huggingface.co/spaces/mackenzietechdocs/HealixPath/resolve/main/QUICKSTART.md
5.06 kB
| # HealixPath - Quick Start Guide | |
| ## π 30-Second Setup | |
| ```bash | |
| # 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 | |
| ```bash | |
| # Terminal 1: Start MCP Server | |
| npm run start | |
| ``` | |
| ### Use with Claude (Terminal 2) | |
| ```bash | |
| # 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`: | |
| ```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`: | |
| ```typescript | |
| // 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 | |
| - Go to [huggingface.co/new-space](https://huggingface.co/new-space) | |
| - Choose "Gradio" as SDK | |
| - Name it "healixpath" | |
| ### 2. Push Code | |
| ```bash | |
| 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:** | |
| ```json | |
| { | |
| "product": "Mental health mobile app", | |
| "persona_id": "busy_parent" | |
| } | |
| ``` | |
| **Output:** | |
| ```json | |
| { | |
| "story": "As a busy parent...", | |
| "acceptance_criteria": ["...", "...", "..."], | |
| "risks": ["..."] | |
| } | |
| ``` | |
| ### Generate Experience Tale | |
| **Input:** | |
| ```json | |
| { | |
| "problem": "App crashes when uploading large files", | |
| "persona_id": "ops_engineer" | |
| } | |
| ``` | |
| ### Generate Feature Impact | |
| **Input:** | |
| ```json | |
| { | |
| "feature_description": "Offline mode with sync", | |
| "persona_id": "busy_parent" | |
| } | |
| ``` | |
| ### Generate Journey Map | |
| **Input:** | |
| ```json | |
| { | |
| "stage": "adoption", | |
| "product": "Healthcare platform", | |
| "persona_id": "product_manager" | |
| } | |
| ``` | |
| ## π Troubleshooting | |
| ### Port Already in Use | |
| ```bash | |
| # Kill process on port 7860 | |
| # Windows: | |
| netstat -ano | findstr :7860 | |
| taskkill /PID <PID> /F | |
| # Mac/Linux: | |
| lsof -ti:7860 | xargs kill -9 | |
| ``` | |
| ### Missing Dependencies | |
| ```bash | |
| # Reinstall all | |
| rm -rf node_modules | |
| npm install | |
| pip install -r requirements.txt --force-reinstall | |
| ``` | |
| ### Gradio Won't Start | |
| ```bash | |
| # Check Python version | |
| python --version # Should be 3.10+ | |
| # Check Gradio installation | |
| pip show gradio | |
| ``` | |
| ### Build Errors | |
| ```bash | |
| # 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](https://www.gradio.app) | |
| --- | |
| **Happy Storytelling! π** | |