# Shared Demo Helpers 🧰 ## Problem Map 3.0 Troubleshooting Atlas ## Official reusable support layer for flagship demos This folder contains the shared support assets used by the official flagship demo pack. Its purpose is simple: > keep each demo readable > keep repeated support logic reusable > keep the notebooks small enough to audit This folder exists so that the demo pack can stay clean, teachable, and maintainable. It should never become a dumping ground. It should also be read as part of the **official demo surface**, not as a separate mini-project. --- ## What this folder is for The official flagship demos are meant to be: - small - sharp - readable - replay-friendly - optionally runnable where it adds real proof value - easy to extend later If every notebook repeats the same support logic, the code becomes noisy very quickly. So this shared folder exists to hold only the support pieces that are: - small - generic enough to reuse - stable across multiple official demos - not part of the main teaching story In short: > demo-specific teaching stays inside each demo folder > reusable support logic lives here --- ## Current MVP reality The current flagship demo pack is **replay-first by design**. At the moment: - **Demo 1** includes a live notebook because live comparison adds direct proof value - **Demo 2** is replay-first, with the cleaner v2 replay notebook serving as the recommended entry point - **Demo 3** is replay-first, with the cleaner v2 replay notebook serving as the recommended entry point - **Demo 4** is replay-first, with the cleaner v2 replay notebook serving as the recommended entry point This matters because shared helpers should reflect the real teaching center of the pack. ### What this means in practice The first version of `shared/` should primarily support: - replay fixture loading - compact route display - before / after formatting - consistent notebook labels - small, explicit mode handling It should **not** assume that all demos are evolving toward a heavy live runtime layer. ### Honest design rule Use shared helpers to support the strongest current teaching mode. Right now, that means: > replay-first support is the default > live support remains small and optional --- ## Current files in this folder 📂 At the current MVP stage, this folder already has a small real support layer. ### `README.md` This file. Purpose: - define folder role - define discipline - define scope - define boundaries ### `demo_utils.py` Current purpose: - lightweight reusable helper functions - JSON loading - compact output formatting - simple route rendering - small replay / live mode helpers This file is intended to be imported by notebooks. It is a support module, not a standalone demo. ### `display_helpers.py` Current purpose: - before / after result formatting - compact comparison rendering - display cleanup for notebook readability - small output presentation helpers This file exists to improve clarity, not to introduce a custom display framework. ### `routing_schema.md` Current purpose: - document the stable output fields used across demo notebooks - explain what each output field means - keep naming consistent across demos This file helps the official demos stay aligned without flattening away their teaching differences. --- ## How notebooks should use this folder The shared layer is meant to be used in a small and explicit way. Typical use looks like this: 1. a notebook stays inside its own demo folder 2. the notebook imports a small helper from `shared/` 3. the notebook still loads its own local JSON fixtures 4. the teaching logic remains inside the notebook and that demo’s README That means shared code should support the notebook, not replace it. In short: > shared provides the small tools > each demo still tells its own story --- ## What belongs in `shared/` The following types of assets belong here. ### 1. Lightweight display helpers These are small helpers that make before / after results easier to read. Examples: - route summary rendering - before / after comparison formatting - compact fixture preview formatting - replay output pretty-print helpers These should help the user see the demo faster. They should not become a custom UI framework. --- ### 2. Minimal schema loaders These are tiny helpers for loading and validating the common demo JSON files. Examples: - reading `input_case.json` - reading `replay_outputs.json` - reading `expected_output.json` - checking required top-level keys These should remain minimal and explicit. --- ### 3. Small mode helpers These are small helpers for handling the notebook execution mode safely and clearly. Examples: - replay mode defaults - optional live mode switch - minimal API key intake helper for the one live notebook - small prompt loading helper if clearly reused These helpers should only support the demos. They should not become a full execution framework. --- ### 4. Common notebook constants These include small shared constants that make the notebooks more consistent. Examples: - file naming conventions - common field names - output labels - route display labels - replay mode defaults These should reduce duplication, not add abstraction for its own sake. --- ### 5. Tiny documentation references If needed, this folder may hold small reference notes that are clearly reusable across the official demos. Examples: - routing output field list - demo JSON field description - minimal notebook expectations These should remain short and clearly tied to the official demo pack. --- ## What does **not** belong in `shared/` ❌ This matters just as much. The following should **not** be placed here. ### 1. Full case explanations Each demo’s teaching story belongs in that demo’s own `README.md`. Do not move: - case meaning - why-primary-not-secondary explanation - misrepair explanation - family teaching notes into shared helpers. That would make the demos harder to read and easier to blur together. --- ### 2. Large framework code Do not turn this folder into a mini product runtime. Avoid putting in: - large orchestration layers - giant helper classes - hidden workflow engines - over-abstracted adapter logic - generic AI platform wrappers The flagship demo pack is meant to stay inspectable. --- ### 3. Secret management logic beyond minimal safe input This folder may contain a tiny helper for runtime API key input. It should **not** contain: - stored keys - repo secrets - hidden environment hacks - service-specific credential systems - anything that makes the demos harder to audit --- ### 4. Per-demo logic If a helper is really only used by one demo, it probably belongs in that demo folder, not here. The shared folder is for genuinely reusable support, not for lazily centralizing unrelated logic. --- ### 5. Community contributions This folder is part of the **official flagship demo pack**. Community utilities, experiments, or alternate demo helpers should live under the community side, not here. See [Community Fix Lab](../../../community/README.md) for that path. --- ## Design principles for shared helpers 🧭 This folder should follow five design principles. ### Principle 1 · Small over clever Prefer short, obvious helpers over smart abstractions. A reader should be able to understand a helper in one glance. ### Principle 2 · Reusable over magical If a helper only works because of hidden assumptions, it is probably too magical for this folder. Shared helpers should be boring in a good way. ### Principle 3 · Teaching-first The demos are teaching assets, not just runnable code. Shared helpers should support teaching clarity, not hide the logic that users came to learn. ### Principle 4 · Replay-first compatibility Replay mode is the public teaching baseline. Any shared helper should make replay mode easier, not accidentally make live mode the default center. ### Principle 5 · Auditability matters A contributor or reviewer should be able to inspect this folder quickly and understand what each file does. If the folder starts to feel like a black box, it has already gone too far. --- ## Relationship to replay mode and live mode This folder supports both modes, but the balance matters. ### Replay mode Replay mode is the most important public teaching mode. Shared helpers should support replay mode through: - clean JSON loading - structured formatting - readable comparison display - compact route summaries ### Live mode Live mode is currently secondary in the official MVP pack. Shared helpers may support live mode through: - minimal API key intake - small request helpers - prompt loading - response normalization But live mode must never force the whole folder to become heavy. ### Golden rule > replay mode should remain first-class > live mode should remain optional That rule should stay visible in every shared-helper decision. --- ## Suggested files in this folder 📂 The exact file list may evolve, but this is the recommended first set. ### `README.md` This file. Purpose: - define folder role - define discipline - define scope - define boundaries --- ### `demo_utils.py` Recommended purpose: - lightweight reusable helper functions - file loading - compact output formatting - simple route rendering - small replay / live mode switch helpers This file should remain small. --- ### `routing_schema.md` Recommended purpose: - document the stable output fields used across demo notebooks - explain what each output field means - keep naming consistent across demos This is especially useful now that the four flagship demos are being aligned more tightly. --- ### `display_helpers.py` Recommended purpose: - before / after result formatting - route card formatting - compact comparison helpers - notebook display cleanup This file should stay lightweight and readability-first. --- ### Optional tiny reference notes Only add these if they clearly reduce duplication. Examples: - JSON field guide - notebook field guide - mode reference note Do not create extra files just because the folder feels empty. --- ## Coding discipline for shared helpers 💻 If helper code is added here, it should follow these rules. ### 1. Keep functions short Prefer small functions with explicit inputs and outputs. ### 2. Avoid hidden side effects A helper should not silently modify environment state unless that behavior is obvious and necessary. ### 3. Keep imports minimal Do not make the flagship demos depend on a long stack of packages unless absolutely necessary. ### 4. Keep names literal Prefer names like: - `load_input_case` - `load_replay_outputs` - `load_expected_output` - `format_route_summary` - `format_before_after` Avoid vague names like: - `engine` - `manager` - `controller` - `runtime_core` ### 5. Keep notebook readers in mind Someone reading a demo notebook should be able to understand what the helper does without opening ten other files. --- ## Review rules for this folder ✅ Anything added to `shared/` should pass these checks. ### Required review questions 1. Is this helper truly reused across multiple official demos? 2. Does this helper improve clarity, not just reduce duplication? 3. Does this helper preserve replay-first readability? 4. Is the file small enough to audit quickly? 5. Would moving this logic into a single demo folder actually be cleaner? If the answer to the last question is yes, then the helper probably does not belong here. --- ## How this folder fits into the full repair system 🔗 This folder is not the repair system itself. It is only a support layer for the flagship demo pack. The larger system is: 1. the atlas routes the failure 2. the fix surface suggests the first repair move 3. the flagship demos make that shift visible 4. WFGY 3.0 supports deeper exploration if needed 5. the community grows long-tail runnable variations later So this folder is only one small but useful piece of the picture. It exists to make the demos cleaner, not to become the center of the architecture. --- ## Relationship to community growth 🌱 This folder supports the **official** demos. That means it should stay conservative. If the community later contributes: - alternate notebook helpers - different visualization utilities - model-specific wrappers - extra schema helpers those should generally begin in the community area first. Only helpers that become clearly useful for the official flagship demo pack should be promoted here. This keeps the official layer stable and easy to review. --- ## What this folder proves This folder may look small, but it proves something important: > the demo pack is being designed as a real, reusable teaching system > not as four isolated notebooks thrown together in a rush That matters for long-term growth. It means: - official demos can stay consistent - future contributors can understand the structure - later MVP code does not need to be rewritten from scratch --- ## What this folder does **not** prove This folder does **not** prove that: - the whole demo system is productionized - every future demo should use the same helper structure - the official demos need a large code layer - community content should be merged into shared by default This folder only proves that the first flagship demos are being built with clean reuse and review discipline. That is enough. --- ## One-line version **This folder contains the small, reusable support layer that keeps the official flagship demos readable, replay-first, and easy to audit.** --- ## Closing note ✨ A good demo pack should feel sharp, not messy. This shared folder exists to support that goal. If it stays small, clear, and disciplined, it will quietly make all four demos better. If it grows into a hidden mini-framework, it will hurt the demos instead of helping them. So the rule is simple: > keep shared helpers useful > keep them small > keep the teaching story inside each demo