File size: 5,055 Bytes
c6a01e9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
# 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! 🎭**