# 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