| # loosecanvas 🕸️ |
|
|
| **Talk through an idea. Watch it become a map — and decide which connections are real.** |
|
|
| ## 🏆 Hackathon submission |
|
|
| Built for the **Build Small Hackathon** — 🌲 Thousand Token Wood track (small local model). |
|
|
| - **Live Space:** [build-small-hackathon/loosecanvas](https://huggingface.co/spaces/build-small-hackathon/loosecanvas) — goes live on transfer to the org + made public. |
| - **Demo video:** _TODO_ |
| - **Field notes (build write-up):** [`submission/FIELD_NOTES.md`](submission/FIELD_NOTES.md) |
| - **Submission packet:** [`submission/`](submission/) — demo script, social drafts, links checklist. |
|
|
| --- |
|
|
| loosecanvas is a **local AI thought-mapping canvas**. A small model (Gemma 4 26B-A4B, |
| ~25B params, via a llama.cpp server) sits beside you and turns conversation into a living |
| knowledge graph: concepts, connections, evidence, and open questions. It can _propose_ a |
| surprising cross-domain link — but it never hides what is a guess, what is grounded, and |
| what you've confirmed. |
|
|
| - **An AI that proposes, but never decides.** Every model-inferred claim carries an |
| independent trust state (origin / support / review) and waits for your judgment. The |
| model can suggest; the validator and reducer decide; you steer. |
| - **100% local.** Inference runs on your machine via llama.cpp — no cloud APIs. |
| - **A real custom UI.** A genuine Cytoscape.js Gradio component, not a chatbot with a |
| decorative graph beside it. |
|
|
| > _Screenshot / demo GIF: a populated graph with trust-tagged nodes — to be added._ |
|
|
| ## How it works |
|
|
| A turn is a negotiation, not autocomplete: |
|
|
| 1. You converse (or paste text to build a graph from scratch). |
| 2. The model **proposes** scene actions — reveal a node, draw an edge, add a hypothesis — |
| streamed as it thinks. |
| 3. A **validator + reducer** decide: every proposed action is checked against the real |
| graph state; invalid ones are rejected with a reason the model can self-correct from. |
| 4. The canvas updates, and the new claims are tagged by **origin** (`deterministic` / |
| `user_asserted` / `model_inferred`), **support**, and **review** — four independent |
| fields that never collapse into one. Model output is permanently marked |
| `model_inferred` and is never silently elevated to a higher-trust origin. |
|
|
| The design philosophy lives in the [constitution](plan/README.md) (files 01–06): the |
| trust model, the three-layer architecture, and the anti-specialization invariant (the |
| turn loop must work on any substrate, not just code). |
|
|
| ## Run it locally (Windows / PowerShell 7) |
|
|
| ```powershell |
| # 1. Python env (requires uv; uv.lock is committed → reproducible) |
| uv sync |
| |
| # 2. Build + install the Gradio custom component (rebuild after any frontend edit) |
| cd cytoscapecanvas |
| & ..\.venv\Scripts\gradio.exe cc build --python-path ..\.venv\Scripts\python.exe |
| cd .. |
| |
| # 3. Configure |
| copy .env.example .env # set LOOSECANVAS_ALLOWED_BASE + GEMMA_MODEL_FILENAME |
| |
| # 4. Place the GGUF model in models/ (see models/README.md) |
| |
| # 5. Start the llama.cpp server (+ optional local monitoring) |
| docker compose up |
| |
| # 6. Run the app |
| $env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe -m uvicorn loosecanvas.main:app --port 8000 |
| ``` |
|
|
| Open **http://localhost:8000**. |
|
|
| > `gradio cc dev` (on :7860/:7861) is a bare component demo with no LLM and no backend — |
| > not the app. Use uvicorn on :8000 for the real product. |
|
|
| ### Deploy as a single container |
|
|
| A self-contained [`Dockerfile`](Dockerfile) + [`entrypoint.sh`](entrypoint.sh) run |
| llama.cpp and the app together in one image (for a Hugging Face Docker Space or any GPU |
| host). See [`deploy/hf-space/README.md`](deploy/hf-space/README.md). |
|
|
| ## Documentation |
|
|
| | Doc | Purpose | |
| | ---------------------------------- | ---------------------------------------------------------------------------- | |
| | [plan/README.md](plan/README.md) | The constitution (files 01–06): trust model, architecture, design philosophy | |
| | [CONTRIBUTING.md](CONTRIBUTING.md) | Commands, quality gate, conventions, pitfalls — operational guidance | |
| | [AGENTS.md](AGENTS.md) | Agent/Copilot dispatch guide | |
| | [CLAUDE.md](CLAUDE.md) | Claude Code guidance: architecture deep-dive | |
| | [plan/STATUS.md](plan/STATUS.md) | Active development tracker | |
|
|
| ## License |
|
|
| [MIT](LICENSE) © 2026 Joshua Sundance Bailey |
|
|
