CS3704 Canvas Project

A maintainable, team-ready Canvas LMS productivity client with a Textual TUI frontend, Chrome extension, Python SDK, and a fine-tuned calendar agent — with a documented shared-core architecture.

---

Canvas Tracker — the fastest path from Canvas API token to a local calendar agent, polished TUI, and contribution-ready dataset pipeline.

Deploy	Link
PyPI (SDK)
Codespaces
HF Space
Docker

See Quick Start · Examples · Public Roadmap

---

---

Distribution

Surface	Channel	Status
canvas-sdk (Python)	PyPI	live — v1.2.3 on PyPI
canvas-tui (Python)	PyPI	not yet published — pyproject.toml v2.0.0; tracked in #177
canvas-tui (Docker)	ghcr.io/kleinpanic/canvas-tui	live — built nightly + on tag (#140)
Chrome extension	Chrome Web Store	listing in progress — install via Load unpacked for now
HF Space demo	Live	live — auto-deploys on push to main
HF Model	v7-DPO	live

canvas-sdk v1.2.3 live on PyPI (API token). OIDC trusted publisher not yet registered at pypi.org. Chrome Web Store listing in progress — install via Load unpacked for now.

---

Quick Start

Chrome Extension

1. Clone or download this repo.
2. In Chrome, open chrome://extensions/ and enable Developer mode.
3. Click Load unpacked and select the extension/ directory.
4. Pin the extension, open a Canvas page, and click the icon.

Python SDK

pip install canvas-sdk[autodownload]    # fetches the v7-dpo Gemma4 model from HF on first run
pip install canvas-sdk[gemini]          # optional Gemini fallback
pip install canvas-sdk[all]             # both

Note: PyPI publishes v1.2.3. The v2.0.0 local source (with the updated agent architecture) can be installed with pip install -e src/sdk/.

import os
from canvas_sdk import CanvasAgent

os.environ["CANVAS_TOKEN"]    = "..."        # your Canvas API token
os.environ["CANVAS_BASE_URL"] = "https://canvas.vt.edu"

agent = CanvasAgent.auto()                   # auto-resolves: env -> local -> HF -> Gemini
print(agent.run("What is due this week?"))

CanvasAgent.auto() resolution order:

1. CANVAS_LLM_ENDPOINT env (skip auto-download, use your own server)
2. Local cache at ~/.cache/canvas-agent/v7-dpo/ (spawns vLLM on :8765)
3. Download kleinpanic93/canvas-calendar-agent-v7-dpo from HF, then (2)
4. Fall back to Gemini (gemini-2.5-flash by default)

TUI (Terminal UI)

export CANVAS_TOKEN="your_canvas_token_here"
export CANVAS_BASE_URL="https://canvas.yourschool.edu"  # required — no default; tool exits with error if unset

pipx install .          # recommended
# or: pip install .

canvas-tui

---

Live Demo

Try the fine-tuned Canvas Calendar Agent in your browser — no install required, no tokens needed:

• Agent demo (mock Canvas data, hosted DPO model): https://kleinpanic.github.io/CS3704-Canvas-Project/agent-demo/
• HF Space (full model, mock tools): https://huggingface.co/spaces/kleinpanic93/canvas-calendar-agent-demo
• HF Collection (v3.0 method matrix): https://huggingface.co/collections/kleinpanic93/canvas-calendar-agent-v30-69fa6462f697e0342b21dfe0

Demo architecture (no tokens in client JS)

Browser  ->  Cloudflare Worker  ->  HF Space (ZeroGPU)
              ^                       ^
              |                       |
              | HF_TOKEN held as      | Gemma4 v7-dpo behind
              | Cloudflare secret     | gradio 5 ChatInterface +
              | (never reaches the    | 18 mock tool dispatchers
              | browser)              |

The HF token is stored as a Cloudflare Worker secret. Public clients only see the proxy URL (cs3704-demo-proxy.kleinpanic.workers.dev); they never receive any credential. See proxy/README.md for the deploy procedure and proxy/iframe-fallback.html for a zero-infra alternative that embeds the Space directly.

Token policy: the SDK reads CANVAS_TOKEN and GOOGLE_API_KEY from your local environment. Tokens never enter the published browser demo, the GH Pages site, or any committed file. The Cloudflare Worker proxy is the only place an HF token is held, and it sits server-side as a Cloudflare secret. If you fork this project and host your own demo, follow the same pattern — see proxy/README.md.

---

Documentation

• Docs site — live project docs
• Agent demo — chat with the Canvas Calendar Agent in your browser
• Roadmap — planned milestones and feature backlog
• HF Space — full v7-dpo model behind a Gradio chat UI
• How it Works — DPO methodology, 9-method ablation matrix, G1–G13 guardrails, bench harness
• PyPI: canvas-sdk — pip install canvas-sdk
• Architecture docs — system design decisions
• Browser extension docs — shared client/runtime architecture
• Contributing — contribution guidelines and developer setup
• Maintainers — maintainer responsibilities
• Security policy — security procedures

---

Development

For team workflow, branch naming, repo structure, and dev setup, see CONTRIBUTING.md.

---

Contributors

Made with contrib.rocks.

---

License

GPL-3.0-or-later. See LICENSE.