Spaces:
Running
Running
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">

</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 π**
|