lhumina_code/hero_demo
0
0
Fork 0
Code Issues 60 Pull requests Projects Releases 2 Packages Wiki Activity Actions

[goal] Killer demo capabilities — what hero_demo should be able to demonstrate #51

New issue
Open
opened 2026-04-30 23:01:22 +00:00 by mik-tf · 1 comment
mik-tf commented 2026-04-30 23:01:22 +00:00
Owner
Copy link

Vision

A "killer demo" of Hero OS — what someone visiting herodemo.gent01.grid.tf should be able to do live, without any explanation, that proves out the platform's value proposition. The demo isn't a feature list; it's a story a stakeholder can play through and walk away thinking I get it.

This issue is the spec. Everything below is what we want; the gap analysis below tells us what's already there vs. what blocks each capability.

The four-act demo

Act 1 — Browse and search content (foundation)

  • Login → desktop with archipelagos
  • Open Library → Books → search across multiple libraries (mycelium, ourworld, geomind, hero docs)
  • Read a markdown doc inline
  • AI summary of a book / library / doc — click a book, get a one-paragraph summary generated by hero_agent grounding on the content. This is the simplest "AI sees your stuff" moment and it's missing today.

Act 2 — Per-context isolation (the multi-tenancy story)

  • Switch context (Default / Geomind / ThreeFold / Incubaid) — each shows distinct content
  • Biz dashboard shows different Persons / Companies / Contacts / Deals counts per context
  • Photos / Videos library shows different content per context
  • Per-context routing verified end-to-end (no silent fallback to root)

Act 3 — AI Assistant as the operating layer

  • AI Assistant island accepts chat input
  • Voice playback works (TTS via Groq/Kokoro)
  • AI Assistant can search Hero docs — "what can I do with Hero OS?" → grounds on docs_hero library via MCP, returns useful answer with citations. The plumbing exists (search_hero_docs tool); needs verification + tightening.
  • AI Assistant can query hero_biz — "what are my contacts in Biz?" → calls business.contact.list via MCP through the right context, returns the list as a usable answer. Requires per-context credentials in tool calls.
  • AI Assistant can write to hero_biz — "add Alice Smith from Acme as a contact" → creates a Contact + Company via MCP. Requires write-side tool exposure + confirmation UX.
  • AI Assistant can run uv-managed Python scripts — "graph the deal pipeline by month" → spawns a uv-isolated Python process with sandboxed deps, returns inline plot or written file. Requires a Python MCP tool with safe execution.
  • AI Assistant reaches arbitrary MCP services — beyond just docs and biz. The MCP registry should be discoverable from the conversation; new MCP services come online without recompiling the agent.

Act 4 — Real productivity flows (the "this is mine" moment)

  • Office: open a seeded .docx in OnlyOffice, edit, save back to hero_foundry. Today the docs are listed but PDF-only; full edit round-trip is broken.
  • Photos / Videos: upload a new file, see it appear in the per-context library
  • Voice: speak a message, transcribed to text (STT working both ways, today TTS-only)
  • Office collaboration: two browsers in the same Collab room editing the same doc

Status today (2026-04-30)

Items currently working in the demo:

  • Login + desktop shell ✅
  • Per-context routing (post-#42 fix today) ✅
  • Photos rendering per context (post-#foundry-restart today) ✅
  • Biz dashboard with seeded data per context (post-e0b014c deploy today) ✅
  • Native "Business" island removed in favor of Biz iframe (post-#123 WASM rebuild today) ✅
  • Books read + search ✅
  • AI Assistant TTS playback ✅
  • LiveKit + voice infra running ✅

Items missing or fragile:

  • AI summary of books/docs — never wired
  • AI Assistant grounding on docs_hero — needs verification (tool call works in code, never end-to-end-tested live)
  • AI Assistant querying hero_biz — not exposed as a tool
  • AI Assistant writing to hero_biz — not exposed as a tool
  • AI Assistant running Python — not implemented
  • Office edit round-trip — OnlyOffice is up but the round-trip is broken (home#174)
  • STT — voice listens but transcription path not verified
  • hero_voice ONNX 1.24 incompat (home#173)
  • Various supervisor reliability bugs that put the demo in a half-broken state (lhumina_code/hero_proc#86 — META)

Gap analysis — what blocks each capability

Capability Primary blocker Tracking
AI summary of books Need a books.summarize MCP tool that grounds on book content + calls hero_agent new issue needed (file under hero_books)
AI grounding on docs_hero Verify search_hero_docs MCP tool works end-to-end from the AI Assistant UI new issue needed (file under hero_agent)
AI querying biz Expose business.*.list as MCP tools with per-context routing new issue needed (file under hero_biz or hero_agent)
AI writing to biz Same as above + write-side confirmation UX depends on read-side first
AI running Python Build an MCP tool that spawns uv run in an isolated subprocess, captures stdout/files new issue needed (file under hero_agent)
Office edit round-trip OnlyOffice CONNECTOR_EXTERNAL_URL + JWT secret + foundry write-back lhumina_code/home#174
STT Verify voice transcription path needs investigation
hero_voice ONNX 1.24 incompat Pin or upgrade ONNX lhumina_code/home#173
Demo stability Supervisor reliability + smoke loop + readiness contract hero_proc#86 (META), hero_proc#83/#84/#85, home#201/#202/#204

Acceptance — what "killer demo" means

  • All four acts can be played through in <10 minutes by someone seeing the demo for the first time, without us narrating fixes mid-flow.
  • No service_proc start --reset or restart needed during the demo.
  • No "let me check the action env" or env-var workarounds visible.
  • Each AI Assistant capability above is invoked by a natural-language prompt, not by clicking a button labeled exactly that.
  • At least one full round-trip through MCP — docs query, biz query, biz write — works the first time.
  • After the demo, a 24-hour soak run with no human intervention shows zero supervisor restarts, zero dropped_total log entries, zero half-broken-listener events, zero context-routing fallbacks.

Why we file this as a goal

We've been playing whack-a-mole on individual symptoms (today: contexts island, photos, biz, business duplicate, log_batcher, hero_proc restart). Each fix was needed but the cumulative result is "the demo doesn't immediately fall over" — not "the demo is impressive." This issue is the explicit standard against which we measure that gap.

The structural fixes already filed (hero_proc#83/#84/#85, hero_osis#43, home#202/#204) are necessary for the demo to be reliable. The new MCP/AI capabilities listed in Act 3 are necessary for the demo to be memorable. We need both.

Cross-references

Signed-off-by: mik-tf

## Vision A "killer demo" of Hero OS — what someone visiting `herodemo.gent01.grid.tf` should be able to do live, without any explanation, that proves out the platform's value proposition. The demo isn't a feature list; it's a story a stakeholder can play through and walk away thinking *I get it.* This issue is the spec. Everything below is what we want; the gap analysis below tells us what's already there vs. what blocks each capability. ## The four-act demo ### Act 1 — Browse and search content (foundation) - [x] Login → desktop with archipelagos - [x] Open Library → Books → search across multiple libraries (mycelium, ourworld, geomind, hero docs) - [x] Read a markdown doc inline - [ ] **AI summary of a book / library / doc** — click a book, get a one-paragraph summary generated by hero_agent grounding on the content. This is the simplest "AI sees your stuff" moment and it's missing today. ### Act 2 — Per-context isolation (the multi-tenancy story) - [x] Switch context (Default / Geomind / ThreeFold / Incubaid) — each shows distinct content - [x] Biz dashboard shows different Persons / Companies / Contacts / Deals counts per context - [x] Photos / Videos library shows different content per context - [x] Per-context routing verified end-to-end (no silent fallback to root) ### Act 3 — AI Assistant as the operating layer - [x] AI Assistant island accepts chat input - [x] Voice playback works (TTS via Groq/Kokoro) - [ ] **AI Assistant can search Hero docs** — "what can I do with Hero OS?" → grounds on `docs_hero` library via MCP, returns useful answer with citations. The plumbing exists (`search_hero_docs` tool); needs verification + tightening. - [ ] **AI Assistant can query hero_biz** — "what are my contacts in Biz?" → calls `business.contact.list` via MCP through the right context, returns the list as a usable answer. Requires per-context credentials in tool calls. - [ ] **AI Assistant can write to hero_biz** — "add Alice Smith from Acme as a contact" → creates a Contact + Company via MCP. Requires write-side tool exposure + confirmation UX. - [ ] **AI Assistant can run uv-managed Python scripts** — "graph the deal pipeline by month" → spawns a uv-isolated Python process with sandboxed deps, returns inline plot or written file. Requires a Python MCP tool with safe execution. - [ ] **AI Assistant reaches arbitrary MCP services** — beyond just docs and biz. The MCP registry should be discoverable from the conversation; new MCP services come online without recompiling the agent. ### Act 4 — Real productivity flows (the "this is mine" moment) - [ ] Office: open a seeded `.docx` in OnlyOffice, edit, save back to hero_foundry. Today the docs are listed but PDF-only; full edit round-trip is broken. - [ ] Photos / Videos: upload a new file, see it appear in the per-context library - [ ] Voice: speak a message, transcribed to text (STT working both ways, today TTS-only) - [ ] Office collaboration: two browsers in the same Collab room editing the same doc ## Status today (2026-04-30) Items currently working in the demo: - Login + desktop shell ✅ - Per-context routing (post-#42 fix today) ✅ - Photos rendering per context (post-#foundry-restart today) ✅ - Biz dashboard with seeded data per context (post-e0b014c deploy today) ✅ - Native "Business" island removed in favor of Biz iframe (post-#123 WASM rebuild today) ✅ - Books read + search ✅ - AI Assistant TTS playback ✅ - LiveKit + voice infra running ✅ Items missing or fragile: - AI summary of books/docs — never wired - AI Assistant grounding on docs_hero — needs verification (tool call works in code, never end-to-end-tested live) - AI Assistant querying hero_biz — not exposed as a tool - AI Assistant writing to hero_biz — not exposed as a tool - AI Assistant running Python — not implemented - Office edit round-trip — OnlyOffice is up but the round-trip is broken (home#174) - STT — voice listens but transcription path not verified - hero_voice ONNX 1.24 incompat (home#173) - Various supervisor reliability bugs that put the demo in a half-broken state (https://forge.ourworld.tf/lhumina_code/hero_proc/issues/86 — META) ## Gap analysis — what blocks each capability | Capability | Primary blocker | Tracking | |---|---|---| | AI summary of books | Need a `books.summarize` MCP tool that grounds on book content + calls hero_agent | new issue needed (file under hero_books) | | AI grounding on docs_hero | Verify `search_hero_docs` MCP tool works end-to-end from the AI Assistant UI | new issue needed (file under hero_agent) | | AI querying biz | Expose `business.*.list` as MCP tools with per-context routing | new issue needed (file under hero_biz or hero_agent) | | AI writing to biz | Same as above + write-side confirmation UX | depends on read-side first | | AI running Python | Build an MCP tool that spawns `uv run` in an isolated subprocess, captures stdout/files | new issue needed (file under hero_agent) | | Office edit round-trip | OnlyOffice CONNECTOR_EXTERNAL_URL + JWT secret + foundry write-back | https://forge.ourworld.tf/lhumina_code/home/issues/174 | | STT | Verify voice transcription path | needs investigation | | hero_voice ONNX 1.24 incompat | Pin or upgrade ONNX | https://forge.ourworld.tf/lhumina_code/home/issues/173 | | Demo stability | Supervisor reliability + smoke loop + readiness contract | hero_proc#86 (META), hero_proc#83/#84/#85, home#201/#202/#204 | ## Acceptance — what "killer demo" means - [ ] All four acts can be played through in <10 minutes by someone seeing the demo for the first time, without us narrating fixes mid-flow. - [ ] No `service_proc start --reset` or restart needed during the demo. - [ ] No "let me check the action env" or env-var workarounds visible. - [ ] Each AI Assistant capability above is invoked by a natural-language prompt, not by clicking a button labeled exactly that. - [ ] At least one full round-trip through MCP — docs query, biz query, biz write — works the first time. - [ ] After the demo, a 24-hour soak run with no human intervention shows zero supervisor restarts, zero `dropped_total` log entries, zero half-broken-listener events, zero context-routing fallbacks. ## Why we file this as a goal We've been playing whack-a-mole on individual symptoms (today: contexts island, photos, biz, business duplicate, log_batcher, hero_proc restart). Each fix was needed but the cumulative result is "the demo doesn't immediately fall over" — not "the demo is impressive." This issue is the explicit standard against which we measure that gap. The structural fixes already filed (hero_proc#83/#84/#85, hero_osis#43, home#202/#204) are necessary for the demo to be **reliable**. The new MCP/AI capabilities listed in Act 3 are necessary for the demo to be **memorable**. We need both. ## Cross-references - Reliability roadmap: https://forge.ourworld.tf/lhumina_code/hero_proc/issues/86 (the META on every supervisor reliability bug) - Smoke loop: https://forge.ourworld.tf/lhumina_code/home/issues/201 - Half-broken listener: https://forge.ourworld.tf/lhumina_code/home/issues/202 - OServer panic isolation: https://forge.ourworld.tf/lhumina_code/home/issues/204 - Contexts as data: https://forge.ourworld.tf/lhumina_code/hero_osis/issues/43 - Codegen drift audit: https://forge.ourworld.tf/lhumina_code/home/issues/203 Signed-off-by: mik-tf
mik-tf self-assigned this 2026-04-30 23:01:22 +00:00
mik-tf commented 2026-05-01 02:05:41 +00:00
Author
Owner
Copy link

Update — corrective state assessment 2026-04-30

This issue's original "Items missing or fragile" section was wrong. After live verification, most of the AI capabilities I marked as missing are already working:

Capability Original status Verified state
AI summary of books "never wired" ✅ Working — "Ask the Librarian" produces clean AI summaries from library content
AI grounding on docs_hero "never end-to-end-tested" ✅ Working — "What is Hero OS?" returns coherent answer with citations
AI querying hero_biz "not exposed" ✅ Working — agent queries biz, eventually returns clean data
AI Python (uv) "not implemented" ✅ Working — agent invoked Python during reasoning chain
Library architecture "partial" ✅ 4 libraries / 40 books, embedded via hero_embedder, AI grounds on it

So the killer demo is already mostly built — what's missing is polish + ambient access + reliability, not features.

The 24-hour execution plan and the long-term picture are now split into a more useful structure:

Closing this issue's role as a single index — the work is now distributed across the issues above. This issue stays open as the running gap-list against the four-act demo flow.

Signed-off-by: mik-tf

## Update — corrective state assessment 2026-04-30 This issue's original "Items missing or fragile" section was wrong. After live verification, most of the AI capabilities I marked as missing are **already working**: | Capability | Original status | Verified state | |---|---|---| | AI summary of books | "never wired" | ✅ Working — "Ask the Librarian" produces clean AI summaries from library content | | AI grounding on docs_hero | "never end-to-end-tested" | ✅ Working — "What is Hero OS?" returns coherent answer with citations | | AI querying hero_biz | "not exposed" | ✅ Working — agent queries biz, eventually returns clean data | | AI Python (uv) | "not implemented" | ✅ Working — agent invoked Python during reasoning chain | | Library architecture | "partial" | ✅ 4 libraries / 40 books, embedded via hero_embedder, AI grounds on it | So the killer demo is *already mostly built* — what's missing is **polish + ambient access + reliability**, not features. The 24-hour execution plan and the long-term picture are now split into a more useful structure: - **Vision**: https://forge.ourworld.tf/lhumina_code/hero_demo/issues/52 (ambient AI desktop, the v1 picture) - **24-hour plan**: https://forge.ourworld.tf/lhumina_code/hero_demo/issues/53 (concrete hour-by-hour execution) - **AI tool discovery**: https://forge.ourworld.tf/lhumina_code/hero_agent/issues/15 (stop the brute-forcing — wire embedder + indexer) - **Ambient AI widget**: https://forge.ourworld.tf/lhumina_code/hero_agent/issues/16 (top-right widget + wake word + conversation mode) - **docs_hero coverage**: https://forge.ourworld.tf/lhumina_code/docs_hero/issues/1 (the leverage multiplier) - **Reliability META**: https://forge.ourworld.tf/lhumina_code/hero_proc/issues/86 Closing this issue's role as a single index — the work is now distributed across the issues above. This issue stays open as the running gap-list against the four-act demo flow. Signed-off-by: mik-tf
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
v0.9.3-dev
v0.9.0-dev
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
mik-tf
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_demo#51
No description provided.