mackenzietechdocs commited on
Commit
17f27e0
Β·
1 Parent(s): a12000e

test push

Browse files
Files changed (1) hide show
  1. README.md +285 -6
README.md CHANGED
@@ -1,17 +1,296 @@
1
  ---
2
- title: TeamHealix
3
- emoji: πŸ¦€
4
  colorFrom: green
5
- colorTo: red
6
  sdk: gradio
7
  sdk_version: 5.49.1
8
  app_file: app.py
9
- pinned: false
10
- short_description: Healing the world through AI innovations.
11
  tags:
12
  - mcp-hackathon
13
  - building-mcp-track-enterprise
14
  - building-mcp-track
 
 
 
 
15
  ---
16
 
17
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ title: HealixPath
3
+ emoji: πŸ’š
4
  colorFrom: green
5
+ colorTo: blue
6
  sdk: gradio
7
  sdk_version: 5.49.1
8
  app_file: app.py
9
+ pinned: true
10
+ short_description: AI-powered persona storytelling engine for UX, product, and design teams.
11
  tags:
12
  - mcp-hackathon
13
  - building-mcp-track-enterprise
14
  - building-mcp-track
15
+ - healthcare
16
+ - ai
17
+ - personas
18
+ - storytelling
19
  ---
20
 
21
+ # HealixPath β€” The AI-Powered Persona Path & Story Engine
22
+
23
+ ✨ HealixPath transforms product inputs, personas, problems, and customer journey stages into rich, structured, realistic stories. Use this exact package for your MCP server, repo, and hackathon pitch.
24
+
25
+ ---
26
+
27
+ ## 🧠 1. Product Overview (README + Pitch)
28
+
29
+ **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:
30
+
31
+ - actionable narratives
32
+ - persona-grounded insights
33
+ - pain points & opportunities
34
+ - before/after feature impact stories
35
+ - journey-map narratives
36
+
37
+ Designed to help product teams feel their users, not just document them.
38
+
39
+ ---
40
+
41
+ ## πŸ› οΈ 2. MCP-Compatible Tools
42
+
43
+ Each tool is exposed through the MCP server (`src/index.ts`) and powered by Claude via the `@anthropic-sdk/sdk`. Schemas are enforced through Anthropic’s JSON mode so outputs are always valid.
44
+
45
+ ### 1. `user_story`
46
+ Generates a structured narrative user story + acceptance criteria from a product and persona.
47
+
48
+ **Input**
49
+ ```json
50
+ {
51
+ "product": "string",
52
+ "persona_id": "string (optional)",
53
+ "persona_override": "string (optional)"
54
+ }
55
+ ```
56
+
57
+ **Output**
58
+ ```json
59
+ {
60
+ "story": "string",
61
+ "acceptance_criteria": ["string"],
62
+ "risks": ["string"]
63
+ }
64
+ ```
65
+
66
+ ### 2. `customer_experience_tale`
67
+ Creates a short narrative describing a persona experiencing a specific problem.
68
+
69
+ **Input**
70
+ ```json
71
+ {
72
+ "persona_id": "string (optional)",
73
+ "persona_override": "string (optional)",
74
+ "problem": "string"
75
+ }
76
+ ```
77
+
78
+ **Output**
79
+ ```json
80
+ {
81
+ "title": "string",
82
+ "narrative": "string",
83
+ "pain_points": ["string"],
84
+ "opportunities": ["string"]
85
+ }
86
+ ```
87
+
88
+ ### 3. `feature_impact_story`
89
+ Shows the before and after of a persona interacting with a feature.
90
+
91
+ **Input**
92
+ ```json
93
+ {
94
+ "feature_description": "string",
95
+ "persona_id": "string (optional)",
96
+ "persona_override": "string (optional)"
97
+ }
98
+ ```
99
+
100
+ **Output**
101
+ ```json
102
+ {
103
+ "before_story": "string",
104
+ "after_story": "string",
105
+ "key_benefits": ["string"],
106
+ "success_metrics": ["string"]
107
+ }
108
+ ```
109
+
110
+ ### 4. `journey_map_story`
111
+ Generates a narrative for a specific stage of the user journey.
112
+
113
+ **Input**
114
+ ```json
115
+ {
116
+ "stage": "string",
117
+ "product": "string",
118
+ "persona_id": "string (optional)",
119
+ "persona_override": "string (optional)"
120
+ }
121
+ ```
122
+
123
+ **Output**
124
+ ```json
125
+ {
126
+ "stage": "string",
127
+ "narrative": "string",
128
+ "touchpoints": ["string"],
129
+ "emotions": ["string"],
130
+ "breakdowns": ["string"],
131
+ "opportunities": ["string"]
132
+ }
133
+ ```
134
+
135
+ ---
136
+
137
+ ## 🧬 3. Persona Data (`data/personas.json`)
138
+
139
+ ```json
140
+ [
141
+ {
142
+ "id": "busy_parent",
143
+ "name": "Busy Parent",
144
+ "role": "Working parent of two kids",
145
+ "goals": ["Save time", "Reduce mental load", "Keep kids on schedule"],
146
+ "frustrations": ["Too many apps", "Slow support", "Juggling work and home"],
147
+ "tech_comfort": "medium",
148
+ "quote": "If it's not simple, I don't have time for it."
149
+ },
150
+ {
151
+ "id": "ops_engineer",
152
+ "name": "Ops Engineer",
153
+ "role": "On-call site reliability engineer",
154
+ "goals": ["Reduce alerts", "Stability", "Automate repetitive tasks"],
155
+ "frustrations": ["Pager fatigue", "Unclear incident logs", "Slow dashboards"],
156
+ "tech_comfort": "high",
157
+ "quote": "If it breaks, it's my problem at 3am."
158
+ }
159
+ ]
160
+ ```
161
+
162
+ Add more personas anytimeβ€”`src/utils/persona_loader.ts` automatically loads them.
163
+
164
+ ---
165
+
166
+ ## πŸ›‘ 4. System Prompt (Paste into MCP Server or Claude Playground)
167
+
168
+ ```
169
+ You are HealixPath, an enterprise-grade AI persona path engine.
170
+ Your goal is to help product, UX, and design teams deeply understand users by generating realistic, structured persona-driven stories.
171
+
172
+ You ALWAYS:
173
+ - adopt the persona’s perspective (from persona_id data or persona_override text)
174
+ - integrate goals, frustrations, role, and quote into narrative context
175
+ - maintain realism with specific details (environment, device, timing)
176
+ - highlight both pain points and business opportunities
177
+ - write with clarity, professionalism, and grounded emotional tone
178
+ - output ONLY valid JSON in the exact schema specified by the user
179
+
180
+ Style:
181
+ - narratives: 250–600 words
182
+ - avoid buzzwords and marketing fluff
183
+ - focus on concrete behaviors & motivations
184
+ - connect the story directly back to the product input or feature description
185
+
186
+ If persona_id is provided, load persona data from the persona database.
187
+ If persona_override is provided, use it as supplemental context, not a replacement.
188
+
189
+ If both are missing, create a plausible persona from scratch with sensible traits.
190
+
191
+ Strictly follow schemas provided in each tool.
192
+ ```
193
+
194
+ This exact prompt is codified in `src/utils/prompts.ts`.
195
+
196
+ ---
197
+
198
+ ## πŸ§ͺ 5. Few-Shot Example (Use in Prompting or README)
199
+
200
+ ```
201
+ Example for customer_experience_tale
202
+ Input:
203
+ persona:
204
+ - name: Busy Parent
205
+ - role: Working parent of two kids
206
+ - goals: ["Save time", "Reduce mental load", "Keep kids on schedule"]
207
+ - frustrations: ["Too many apps", "Slow support", "Juggling work and home"]
208
+ - quote: "If it's not simple, I don't have time for it."
209
+ problem: "Promo code fails during mobile checkout on a flash sale"
210
+
211
+ Expected Output:
212
+ {
213
+ "title": "Promo Panic at Bedtime",
214
+ "narrative": "It's 8:45pm and Maya sinks into her couch after finally putting her two kids to bed...",
215
+ "pain_points": [
216
+ "Ambiguous promo code error message",
217
+ "Checkout form resets when navigating back",
218
+ "Customer support queue too long for short sessions"
219
+ ],
220
+ "opportunities": [
221
+ "Clearer inline error messaging",
222
+ "Auto-saving form state",
223
+ "Fast support path during busy sale windows"
224
+ ]
225
+ }
226
+ ```
227
+
228
+ ---
229
+
230
+ ## πŸ“‚ 6. Recommended Repo Structure (already implemented)
231
+
232
+ ```
233
+ healixpath/
234
+ β”œβ”€ src/
235
+ β”‚ β”œβ”€ tools/
236
+ β”‚ β”‚ β”œβ”€ user_story.ts
237
+ β”‚ β”‚ β”œβ”€ customer_experience_tale.ts
238
+ β”‚ β”‚ β”œβ”€ feature_impact_story.ts
239
+ β”‚ β”‚ └─ journey_map_story.ts
240
+ β”‚ β”œβ”€ utils/
241
+ β”‚ β”‚ β”œβ”€ persona_loader.ts
242
+ β”‚ β”‚ β”œβ”€ helpers.ts
243
+ β”‚ β”‚ └─ prompts.ts
244
+ β”‚ └─ index.ts
245
+ β”œβ”€ data/
246
+ β”‚ └─ personas.json
247
+ β”œβ”€ app.py
248
+ β”œβ”€ package.json
249
+ β”œβ”€ tsconfig.json
250
+ β”œβ”€ requirements.txt
251
+ β”œβ”€ README.md
252
+ └─ .env (create from .env.example)
253
+ ```
254
+
255
+ ---
256
+
257
+ ## βš™οΈ 7. Getting Started
258
+
259
+ ### Node.js MCP Server
260
+ ```bash
261
+ cp .env.example .env # add your Anthropic key
262
+ npm install
263
+ npm run build
264
+ npm run start
265
+ ```
266
+ `src/index.ts` boots the HealixPath MCP server, enumerates tools, and shows sample tool calls. Claude responses stream through `@anthropic-sdk/sdk` with enforced JSON schemas; when the API key is absent, deterministic fallbacks keep the demo running.
267
+
268
+ ### Gradio Demo
269
+ ```bash
270
+ pip install -r requirements.txt
271
+ python app.py
272
+ ```
273
+ `app.py` offers a quick UI to showcase personas and tool outputs during demos or on Hugging Face Spaces.
274
+
275
+ ---
276
+
277
+ ## πŸš€ 8. Hackathon Demo Script (60 Seconds)
278
+
279
+ > β€œ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.”
280
+
281
+ Then show a persona β†’ problem β†’ generated JSON/story.
282
+
283
+ ---
284
+
285
+ ## 🎨 9. Want Next?
286
+
287
+ 1. Logo explorations for HealixPath (neon, simple, minimal, enterprise)
288
+ 2. Brand color palette or landing page copy
289
+ 3. Full MCP client or UI mockup for demos
290
+ 4. Domain availability research
291
+
292
+ Ping me when you’re ready for the next layer of polish!
293
+
294
+ ---
295
+
296
+ **Built for the MCP Hackathon πŸš€**