File size: 14,238 Bytes
53a1a96
17f27e0
8fe0918
53a1a96
8fe0918
53a1a96
 
 
17f27e0
e9c63c4
 
 
5bf88e7
a12000e
 
 
 
17f27e0
 
 
 
53a1a96
 
7ab6016
 
 
 
 
17f27e0
8fe0918
 
 
 
 
 
 
 
 
 
17f27e0
8fe0918
6834a74
8fe0918
e9c63c4
8fe0918
e9c63c4
8fe0918
d421c7a
8fe0918
 
 
 
 
 
 
 
d421c7a
e9c63c4
 
8fe0918
e9c63c4
 
 
 
 
 
 
 
 
 
6834a74
8fe0918
6834a74
8fe0918
 
6834a74
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e9c63c4
17f27e0
71a1d23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71a1d23
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71a1d23
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71a1d23
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71a1d23
17f27e0
71a1d23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e9c63c4
17f27e0
 
 
 
e9c63c4
17f27e0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
---
title: HealixPath
emoji: 🧬
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: true
hf_oauth: true
hf_oauth_scopes:
  - inference-api
short_description: Updated Β· free open models, HF sign-in
tags:
    - mcp-hackathon
    - building-mcp-track-enterprise
    - building-mcp-track
    - healthcare
    - ai
    - personas
    - storytelling
---

<div align="center">

![HealixPath β€” stories that spiral from a persona](docs/assets/healix-banner.png)

</div>

<p align="center">
  <a href="https://huggingface.co/spaces/mackenzietechdocs/HealixPath"><img src="https://img.shields.io/badge/Live%20Space-b8ff3c?style=for-the-badge&labelColor=050805" alt="Live Space"></a>
  <a href="https://huggingface.co/spaces/MCP-1st-Birthday/TeamHealix"><img src="https://img.shields.io/badge/Hackathon%20Space-frozen-9ef6c8?style=for-the-badge&labelColor=050805" alt="Hackathon Space, frozen"></a>
  <a href="https://huggingface.co/collections/mackenzietechdocs/healixpath"><img src="https://img.shields.io/badge/Collection-healixpath-b8ff3c?style=for-the-badge&labelColor=050805" alt="Collection"></a>
  <a href="https://mso-docs.github.io/HealixPath/"><img src="https://img.shields.io/badge/Project%20page-d4ff6b?style=for-the-badge&labelColor=050805" alt="Project page"></a>
  <a href="https://github.com/mso-docs/HealixPath"><img src="https://img.shields.io/badge/GitHub-mso--docs%2FHealixPath-9ef6c8?style=for-the-badge&labelColor=050805&logo=github&logoColor=b8ff3c" alt="GitHub"></a>
  <a href="https://youtu.be/zz5AliukXKk"><img src="https://img.shields.io/badge/Demo%20video-YouTube-ff3c3c?style=for-the-badge&labelColor=050805&logo=youtube&logoColor=white" alt="Demo video"></a>
  <a href="#sign-in-with-hugging-face-free-ai-no-api-key"><img src="https://img.shields.io/badge/Sign%20in-free%20open%20models-b8ff3c?style=for-the-badge&labelColor=050805" alt="Sign in, free open models"></a>
  <img src="https://img.shields.io/badge/License-MIT-9ef6c8?style=for-the-badge&labelColor=050805" alt="MIT License">
</p>

# HealixPath

**Stories that spiral from a persona.** HealixPath is an AI-powered storytelling engine that turns a product, a problem, or a journey stage into structured, realistic narratives for the people who will actually use the work.

Built by **Mackenzie O'Brien** ([@mackenzietechdocs](https://huggingface.co/mackenzietechdocs), [GitHub](https://github.com/mso-docs)) and **co-author @DevRubenArevalo** ([Hugging Face](https://huggingface.co/DevRubenArevalo), [GitHub](https://github.com/DevRubenArevalo)). Together we are Team Healix.

The official November 2025 hackathon submission lives at [MCP-1st-Birthday/TeamHealix](https://huggingface.co/spaces/MCP-1st-Birthday/TeamHealix) and is kept unchanged. This repository and the live Space are the maintained copy.

| | |
| :--- | :--- |
| **Project page** | [mso-docs.github.io/HealixPath](https://mso-docs.github.io/HealixPath/) |
| **Hackathon Space (frozen)** | [MCP-1st-Birthday/TeamHealix](https://huggingface.co/spaces/MCP-1st-Birthday/TeamHealix) |
| **Live Space** | [mackenzietechdocs/HealixPath](https://huggingface.co/spaces/mackenzietechdocs/HealixPath) |
| **Collection** | [HealixPath](https://huggingface.co/collections/mackenzietechdocs/healixpath) |
| **GitHub** | [mso-docs/HealixPath](https://github.com/mso-docs/HealixPath) |
| **Demo video** | [youtu.be/zz5AliukXKk](https://youtu.be/zz5AliukXKk) |

## Sign in with Hugging Face (free AI, no API key)

This live copy does not use any paid API key. Text generation runs on open models through [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers), using **your own** Hugging Face account:

1. Click **Sign in with Hugging Face** at the top of the app and approve the `inference-api` permission.
2. Generate stories, journeys, and personas. Each request is billed to your account's free monthly Inference Providers allowance. If you run out, Hugging Face will tell you; PRO accounts get a larger allowance.
3. Signed-out visitors can browse and search personas, but generation shows a "please sign in" message. The Space never falls back to its owner's token or any secret.

Model: [`openai/gpt-oss-20b`](https://huggingface.co/openai/gpt-oss-20b) (open weights, Apache 2.0, instruction-tuned). When running your own copy, set the `HEALIXPATH_MODEL` environment variable to any chat model served by Inference Providers.

**MCP clients:** the Gradio MCP endpoint is `https://mackenzietechdocs-healixpath.hf.space/gradio_api/mcp/`. Tools that generate text need a Hugging Face token with the "Make calls to Inference Providers" permission; send it as `Authorization: Bearer <your token>`.

**Running locally:** `pip install -r requirements.txt && python app.py`. Local OAuth sign-in needs a Space; the app does not read `HF_TOKEN`. Duplicate the Space to your account to get your own copy with sign-in enabled.

## Posts and video

- LinkedIn: [announcement](https://www.linkedin.com/feed/update/urn:li:activity:7401032353361477633/) and [hackathon post](https://www.linkedin.com/posts/mackenzieoc_mcp1stbirthday-hackathon-huggingface-activity-7395261430117060608-CLZA)
- Demo video: [youtu.be/zz5AliukXKk](https://youtu.be/zz5AliukXKk)

---

## 🧠 1. Product Overview (README + Pitch)

**HealixPath** delivers AI-powered persona storytelling for UX, product, and design teams. Instead of vague bullet points like β€œUser gets frustrated during checkout,” HealixPath generates:

- actionable narratives  
- persona-grounded insights  
- pain points & opportunities  
- before/after feature impact stories  
- journey-map narratives  

Designed to help product teams feel their users, not just document them.

---

## πŸ› οΈ 2. MCP-Compatible Tools

Each tool is exposed through the MCP server (`src/index.ts`) and powered by open models via Hugging Face Inference Providers in the Gradio app (the original hackathon build used Claude). Prompts request JSON-only output.

### 1. `list_personas`
Lists all available personas with their key attributes.

**Input**
```json
{
  "limit": "number (optional)"
}
```

**Output**
```json
{
  "personas": [
    {
      "id": "string",
      "name": "string",
      "age": "number",
      "location": "string",
      "job_title": "string",
      "industry": "string",
      "tech_literacy": "string",
      "primary_goals": ["string"],
      "pain_points": ["string"],
      "user_story": "string"
    }
  ],
  "total": "number"
}
```

### 2. `search_personas`
Search and filter personas by various criteria.

**Input**
```json
{
  "role": "string (optional)",
  "industry": "string (optional)",
  "age_range": "string (optional, e.g., '25-35')",
  "tech_literacy": "string (optional)",
  "location": "string (optional)"
}
```

**Output**
```json
{
  "personas": ["array of matching personas"],
  "count": "number",
  "filters": "object with applied filters"
}
```

### 3. `user_story`
Generates a structured narrative user story + acceptance criteria from a product and persona.

**Input**
```json
{
  "product": "string",
  "persona_id": "string (optional)",
  "persona_override": "string (optional)"
}
```

**Output**
```json
{
  "story": "string",
  "acceptance_criteria": ["string"],
  "risks": ["string"]
}
```

### 4. `customer_experience_tale`
Creates a short narrative describing a persona experiencing a specific problem.

**Input**
```json
{
  "persona_id": "string (optional)",
  "persona_override": "string (optional)",
  "problem": "string"
}
```

**Output**
```json
{
  "title": "string",
  "narrative": "string",
  "pain_points": ["string"],
  "opportunities": ["string"]
}
```

### 5. `feature_impact_story`
Shows the before and after of a persona interacting with a feature.

**Input**
```json
{
  "feature_description": "string",
  "persona_id": "string (optional)",
  "persona_override": "string (optional)"
}
```

**Output**
```json
{
  "before_story": "string",
  "after_story": "string",
  "key_benefits": ["string"],
  "success_metrics": ["string"]
}
```

### 6. `journey_map_story`
Generates a narrative for a specific stage of the user journey.

**Input**
```json
{
  "stage": "string",
  "product": "string",
  "persona_id": "string (optional)",
  "persona_override": "string (optional)"
}
```

**Output**
```json
{
  "stage": "string",
  "narrative": "string",
  "touchpoints": ["string"],
  "emotions": ["string"],
  "breakdowns": ["string"],
  "opportunities": ["string"]
}
```

---

## πŸ“¦ 3. MCP Resources

Personas are also exposed as MCP resources for easy browsing:

- `personas://all` - Complete list of all personas with summaries
- `personas://[id]` - Individual persona details (e.g., `personas://persona-001`)

Resources allow LLM clients to browse and reference personas without making tool calls.

---

## 🧬 4. Persona Data (`data/personas.json`)

The persona database contains detailed user profiles with:
- Demographics (age, location, income, education)
- Job information (title, industry, experience)
- Technology preferences (literacy level, devices, apps)
- Goals and motivations
- Pain points and frustrations
- Purchasing habits and interests
- Personality traits and communication style

Example personas include marketing managers, developers, healthcare directors, customer support specialists, and more across various industries and demographics.

---
    "id": "ops_engineer",
    "name": "Ops Engineer",
    "role": "On-call site reliability engineer",
    "goals": ["Reduce alerts", "Stability", "Automate repetitive tasks"],
    "frustrations": ["Pager fatigue", "Unclear incident logs", "Slow dashboards"],
    "tech_comfort": "high",
    "quote": "If it breaks, it's my problem at 3am."
  }
]
```

Add more personas anytimeβ€”`src/utils/persona_loader.ts` automatically loads them.

---

## πŸ›‘ 4. System Prompt (Paste into MCP Server or Claude Playground)

```
You are HealixPath, an enterprise-grade AI persona path engine.
Your goal is to help product, UX, and design teams deeply understand users by generating realistic, structured persona-driven stories.

You ALWAYS:
- adopt the persona’s perspective (from persona_id data or persona_override text)
- integrate goals, frustrations, role, and quote into narrative context
- maintain realism with specific details (environment, device, timing)
- highlight both pain points and business opportunities
- write with clarity, professionalism, and grounded emotional tone
- output ONLY valid JSON in the exact schema specified by the user

Style:
- narratives: 250–600 words
- avoid buzzwords and marketing fluff
- focus on concrete behaviors & motivations
- connect the story directly back to the product input or feature description

If persona_id is provided, load persona data from the persona database.
If persona_override is provided, use it as supplemental context, not a replacement.

If both are missing, create a plausible persona from scratch with sensible traits.

Strictly follow schemas provided in each tool.
```

This exact prompt is codified in `src/utils/prompts.ts`.

---

## πŸ§ͺ 5. Few-Shot Example (Use in Prompting or README)

```
Example for customer_experience_tale
Input:
persona:
- name: Busy Parent
- role: Working parent of two kids
- goals: ["Save time", "Reduce mental load", "Keep kids on schedule"]
- frustrations: ["Too many apps", "Slow support", "Juggling work and home"]
- quote: "If it's not simple, I don't have time for it."
problem: "Promo code fails during mobile checkout on a flash sale"

Expected Output:
{
  "title": "Promo Panic at Bedtime",
  "narrative": "It's 8:45pm and Maya sinks into her couch after finally putting her two kids to bed...",
  "pain_points": [
    "Ambiguous promo code error message",
    "Checkout form resets when navigating back",
    "Customer support queue too long for short sessions"
  ],
  "opportunities": [
    "Clearer inline error messaging",
    "Auto-saving form state",
    "Fast support path during busy sale windows"
  ]
}
```

---

## πŸ“‚ 6. Recommended Repo Structure (already implemented)

```
healixpath/
β”œβ”€ src/
β”‚  β”œβ”€ tools/
β”‚  β”‚   β”œβ”€ user_story.ts
β”‚  β”‚   β”œβ”€ customer_experience_tale.ts
β”‚  β”‚   β”œβ”€ feature_impact_story.ts
β”‚  β”‚   └─ journey_map_story.ts
β”‚  β”œβ”€ utils/
β”‚  β”‚   β”œβ”€ persona_loader.ts
β”‚  β”‚   β”œβ”€ helpers.ts
β”‚  β”‚   └─ prompts.ts
β”‚  └─ index.ts
β”œβ”€ data/
β”‚  └─ personas.json
β”œβ”€ app.py
β”œβ”€ package.json
β”œβ”€ tsconfig.json
β”œβ”€ requirements.txt
β”œβ”€ README.md
└─ .env (create from .env.example)
```

---

## βš™οΈ 7. Getting Started

### Node.js MCP Server
```bash
cp .env.example .env   # optional: only the original local Node demo used an Anthropic key
npm install
npm run build
npm run start
```
`src/index.ts` boots the HealixPath MCP server, enumerates tools, and shows sample tool calls. This local TypeScript demo is the original hackathon prototype; the live Gradio app does not use it.

### Gradio Demo
```bash
pip install -r requirements.txt
python app.py
```
`app.py` offers a quick UI to showcase personas and tool outputs during demos or on Hugging Face Spaces.

---

## πŸš€ 8. Hackathon Demo Script (60 Seconds)

> β€œWe built HealixPath, an AI engine that generates realistic persona-based stories for UX and product teams. Instead of vague bullet points like β€˜User is frustrated at checkout,’ HealixPath produces rich narratives, pain points, opportunities, and journey maps β€” all grounded in real personas. It takes a product description or problem, merges it with persona data, and instantly produces a believable, actionable user story. This helps teams design better flows, features, and experiences by understanding the human side behind the analytics. In just one click, a PM can generate a story that feels like it came from weeks of user research.”

Then show a persona β†’ problem β†’ generated JSON/story.

---

## 🎨 9. Want Next?

1. Logo explorations for HealixPath (neon, simple, minimal, enterprise)
2. Brand color palette or landing page copy
3. Full MCP client or UI mockup for demos
4. Domain availability research

Ping me when you’re ready for the next layer of polish!

---

**Built for the MCP Hackathon πŸš€**