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.

Quick Start

Chrome Extension

Clone or download this repo.
In Chrome, open chrome://extensions/ and enable Developer mode.
Click Load unpacked and select the extension/ directory.
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

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:

CANVAS_LLM_ENDPOINT env (skip auto-download, use your own server)
Local cache at ~/.cache/canvas-agent/v7-dpo/ (spawns vLLM on :8765)
Download kleinpanic93/canvas-calendar-agent-v7-dpo from HF, then (2)
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.vt.edu"   # optional, defaults to VT

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.

Overview

This is the CS3704 team project repository for a Canvas LMS productivity tool. It combines a working Textual TUI application with architecture documentation, team governance, and automated CI/CD.

What this project does

Centralized dashboard for Canvas assignments, announcements, and grades
Offline-first caching for reliable access
Calendar integration and ICS export
Pomodoro timer and notification support
Course filtering and quick navigation

Architecture goals

Current: Feature-complete TUI application
Current: Browser extension with popup, background worker, IndexedDB cache, and shared JS client/runtime layer
Shared core direction: Reusable domain logic and orchestration where practical across surfaces
Future: Deeper parity between TUI and browser-facing features

ML/AI Components

The v2 milestone adds a specialized calendar+study agent that combines Canvas API tool calls with neuroscience-grounded study planning heuristics (spaced repetition, deep-work block sizing, exam bracketing).

The v7-DPO model is published on HuggingFace and the accompanying paper is on Zenodo.

Fine-tuned model resources

Model card: huggingface.co/kleinpanic93/canvas-calendar-agent-v7-dpo
Preference dataset: huggingface.co/datasets/kleinpanic93/canvas-calendar-preferences-v7
Training pipeline (paper + code): github.com/kleinpanic/CS3704-DPO-SSOT
Bench comparison (SFT vs DPO): docs/bench_v7_comparison.md

v3.0 fine-tuning matrix

The published 9-method matrix (Gemma-4-E2B-IT trained on the same v7 dataset, varying only the loss/method) currently ships DPO. The remaining 8 methods (SFT, KTO, IPO, APO-Zero, SPPO, NCA, LoRA, QLoRA) plus the 12-quant GGUF expansion are queued — recipes and exact commands live in MINIMAX-HANDOFF-v3.md in the SSOT repo.

Run locally with Ollama

The fine-tuned agent is available as a GGUF for local inference via Ollama:

ollama pull hf.co/kleinpanic93/canvas-calendar-agent-v7-dpo-gguf:Q4_K_M
ollama run hf.co/kleinpanic93/canvas-calendar-agent-v7-dpo-gguf:Q4_K_M "What assignments are due this week?"

Tag	Size	Notes
`Q4_K_M`	~3.2 GB	Recommended — fast + good quality
`Q8_0`	~4.7 GB	Higher quality, larger memory
`f16`	~8.7 GB	Reference / no quality loss

Full GGUF repo: kleinpanic93/canvas-calendar-agent-v7-dpo-gguf

Architecture

v2 ML stack — agent runtime

flowchart LR
  USER[User]
  EXT[Browser Extension<br/>presentation only]
  NH[Native Messaging Host<br/>stdio bridge]
  SDK[canvas_sdk<br/>Python]
  AGENT[CanvasAgent<br/>agent loop]
  G4[Gemma4Backend<br/>vLLM /v1/chat]
  GEM[GeminiBackend<br/>fallback]
  VLLM[(vLLM serving<br/>v7-dpo)]
  GAPI[(Gemini API)]

  USER --> EXT
  EXT -- AGENT_QUERY --> NH
  NH --> SDK
  SDK --> AGENT
  AGENT --> G4
  AGENT --> GEM
  G4 --> VLLM
  GEM --> GAPI

Contract: the extension is GUI; the SDK is the only agent. Never duplicate tool parsing or agent loops in the extension.

High-level system design

flowchart TB
  subgraph CLI[CLI Frontend]
    CMD[Command Router]
    TUI[Textual TUI Screens]
    NOTIF[Notifications]
  end

  subgraph EXT[Browser Extension]
    POPUP[Popup UI]
    BG[Background Worker]
    CONTENT[Content Scripts]
  end

  subgraph CORE[Shared Domain Core]
    ORCH[Orchestrators]
    POLICY[Policy Engine]
    NORM[Normalization Layer]
    DIFF[State and Diff Engine]
  end

  subgraph INFRA[Infrastructure Layer]
    API[Canvas API Gateway]
    AUTH[Auth Manager]
    CACHE[SQLite and IndexedDB Cache]
    QUEUE[Event Scheduler]
  end

  CMD --> ORCH
  TUI --> ORCH
  NOTIF --> ORCH
  POPUP --> ORCH
  BG --> ORCH
  CONTENT --> ORCH
  ORCH --> POLICY --> API
  ORCH --> NORM --> CACHE
  ORCH --> DIFF --> CACHE
  ORCH --> QUEUE
  API --> AUTH

Static diagrams

Full Architecture — component relationships
Sync Flow — data refresh sequence

Development

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Testing

ruff check src tests      # linting
pytest -q                 # run tests
python -m build           # build package

Repository Structure

.github/                  CI/CD workflows and governance
extension/                Browser extension source (presentation only)
src/canvas_tui/           TUI application source code
  agent/                  v2 CalendarAgent (tool calls + study planning)
src/sdk/canvas_sdk/       Python SDK — single source of agent logic
hf-space/                 HuggingFace Space (Gradio app loading v7-dpo)
tests/                    Test suite
scripts/                  Data contribution utilities (see scripts/README.md)
docs/                     Architecture and research docs
docs-site/                GitHub Pages documentation + browser demo
data/
  trajectories/           v2 SFT training data
    collab/               Teammate-contributed trajectory JSONL files
    seeds/                Canonical seed examples
  v1-reranker/            Legacy v1 preference pair data

Team Workflow

For maintainers

Treat main as the only long-term branch
Use short-lived feature branches for scoped work when possible
Ensure CI passes before merging others' PRs
Prefer squash merges and let GitHub auto-delete merged branches

For team members

Never push directly to main
Create a short-lived branch using one of the prefixes below
Open a Pull Request into main
Wait for CI to pass and a maintainer to review
Merge with squash when approved

Branch naming convention

All branches must match <prefix>/<slug> where slug is lowercase letters, digits, dots, and hyphens.

Prefix	Use for
`feature/*`	New features
`fix/*`	Bug fixes
`docs/*`	Documentation updates
`chore/*`	Maintenance and tooling
`refactor/*`	Code refactoring without behavior change
`test/*`	Test additions or fixes
`hotfix/*`	Urgent production fixes
`dependabot/*`	Automated dependency updates

Automation

Workflow	Purpose
CI	Ruff linting, pytest on Python 3.11/3.12/3.13, package build
Security	CodeQL analysis, dependency review
Pages	Auto-deploy documentation site
Release	Create snapshot release on main push
Stale	Close inactive issues/PRs after 30 days
Labeler	Auto-label PRs by changed files

The repository is configured for squash-only merges into protected main, linear history, and branch auto-delete after merge. All commits to protected branches must be GPG signed.

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
Read the Docs — auto-published API + architecture docs (project import pending — see .readthedocs.yaml)
GHCR Docker image — docker pull ghcr.io/kleinpanic/canvas-tui (built on push-to-main + tags)
PyPI: canvas-sdk — pip install canvas-sdk (publishes on stable releases via OIDC trusted publishing)
Architecture docs — system design decisions
Browser extension docs — shared client/runtime architecture
Workflow guide — how the team works
Contributing — contribution guidelines
Maintainers — maintainer responsibilities
Security policy — security procedures

Course Context

This repository supports CS3704: Intermediate Software Design and Engineering project milestones:

PM3: Design documentation, architecture visualization, process evidence
PM4+: Implementation, testing, and delivery

The architecture emphasizes maintainability for a mixed-skill team while protecting the codebase from accidental damage.

License

GPL-3.0-or-later. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 261 Commits
.github		.github
data		data
docker/canvas-tui		docker/canvas-tui
docs-site		docs-site
docs		docs
extension		extension
hf-space		hf-space
newsfragments		newsfragments
proxy		proxy
scripts		scripts
src		src
tests		tests
tools		tools
.czrc		.czrc
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.readthedocs.yaml		.readthedocs.yaml
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
IMPLEMENTATION.md		IMPLEMENTATION.md
LICENSE		LICENSE
MAINTAINERS.md		MAINTAINERS.md
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
ruff.toml		ruff.toml

Folders and files

Latest commit

History

Repository files navigation

CS3704 Canvas Project

Quick Start

Chrome Extension

Python SDK

TUI (Terminal UI)

Live Demo

Demo architecture (no tokens in client JS)

Overview

What this project does

Architecture goals

ML/AI Components

Fine-tuned model resources

v3.0 fine-tuning matrix

Run locally with Ollama

Architecture

v2 ML stack — agent runtime

High-level system design

Static diagrams

Development

Setup

Testing

Repository Structure

Team Workflow

For maintainers

For team members

Branch naming convention

Automation

Documentation

Course Context

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 8

Uh oh!

Contributors

Uh oh!

Languages