dgenio / dgenio/contextweaver

[Parked until product proof] Colab notebook gallery for showcase demos

Open
#435 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

adoption blocked documentation needs-info priority: low
Dominant language
Python
Stars
9
Forks
17
Avg merge
21h 36m
Merged PRs (30d)
22

Description

Summary

The project has exactly one notebook (notebooks/context_rot_live.ipynb)
and no zero-install way to interact with contextweaver. Because the
demos are deterministic and network-free, they are ideal Colab material:
add a small notebook gallery mirroring the four showcase scenarios, each
with an "Open in Colab" badge, linked from the README and docs.

Why this matters

  • A Colab badge is the lowest-friction "try it now" path that exists —
    no install, no API keys (the demos already need none), runs on any
    laptop or phone browser.
  • Notebooks convert README visitors into users at the exact moment of
    curiosity, and give talks/workshops ready-made material.
  • The existing showcase (docs/showcase.md) is currently read-only;
    notebooks make it executable.

Proposed scope

  • notebooks/ gains four notebooks mirroring docs/showcase.md:
    1. Route 1,000 tools → 5 ChoiceCards (with RouteTrace inspection)
    2. Firewall a 16 KB tool result (artifact drilldown)
    3. 50-turn conversation → phase-budgeted pack (BuildStats deep dive)
    4. The 60-second failure mode (killer demo, narrated)
  • Each notebook: %pip install contextweaver first cell, markdown
    narration between steps, ends with "where to go next" links.
  • "Open in Colab" badges in notebooks/README.md (new), docs/showcase.md,
    and the README links row.
  • CI execution check: run notebooks headlessly (e.g.
    jupyter nbconvert --execute or papermill) in the Python 3.12 cell so
    they can't drift — same philosophy as the existing demo drift gates.

Implementation notes

  • Colab badge URL pattern:
    https://colab.research.google.com/github/dgenio/contextweaver/blob/main/notebooks/<name>.ipynb.
  • Keep outputs stripped in git (pre-commit nbstripout or committed
    clean) to keep diffs reviewable; the execution check validates they
    still run.
  • Pin nothing inside notebooks beyond contextweaver itself; they should
    exercise the released package, with a commented pip install -e . line
    for development.
  • The existing context_rot_live.ipynb should join the gallery and get
    the same badge + CI treatment.

Acceptance criteria

  • Four new notebooks run top-to-bottom in a fresh Colab runtime with
    no API keys.
  • Badges visible in README, showcase page, and notebooks README.
  • CI executes all notebooks in one matrix cell; failures gate.
  • Notebook outputs stripped in version control.

Out of scope

  • Hosted JupyterHub/Binder infrastructure.
  • Notebooks requiring API keys or network.
  • The in-browser Pyodide playground (separate proposal).

References


Priority: P2 · Effort: S · Impact: Medium

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with notebooks/context_rot_live.ipynb and docs/showcase.md to map the four scenarios and existing demo drift gates. Add the four gallery notebooks, badges in notebooks/README.md, docs/showcase.md, and the README links row, then run the notebooks headlessly in the Python 3.12 CI cell. Done means all notebooks run without API keys, outputs are stripped, and CI gates on execution failures.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook, python
Domain
documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.