canvasctl 0.3.0__py3-none-any.whl

canvasctl/__init__.py

@@ -0,0 +1,3 @@
+"""canvasctl — a read-only Canvas LMS CLI."""
+
+__version__ = "0.3.0"

canvasctl/__main__.py

@@ -0,0 +1,4 @@
+from canvasctl.cli import main
+
+if __name__ == "__main__":
+    main()

canvasctl/agent/__init__.py

@@ -0,0 +1,39 @@
+"""canvasctl chat agent — a Claude-powered assistant over the ops registry.
+
+Public surface: ``run_ask`` (single prompt) and ``run_chat`` (interactive REPL).
+Both return an integer exit code and are safe to wire straight into the CLI.
+``anthropic`` is imported lazily inside ``loop``/``repl`` so importing this
+package never requires the optional dependency.
+"""
+from __future__ import annotations
+
+import sys
+
+from ..formatting import Colors, colorize
+
+
+def run_ask(prompt: str, model: str | None = None) -> int:
+    """Answer a single prompt (``canvasctl ask``). Returns an exit code."""
+    from .loop import AgentError, ask_once
+
+    try:
+        text = ask_once(prompt, model=model)
+    except AgentError as exc:
+        print(colorize(str(exc), Colors.RED), file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(colorize("\nInterrupted.", Colors.YELLOW), file=sys.stderr)
+        return 130
+    if text:
+        print(text)
+    return 0
+
+
+def run_chat(model: str | None = None) -> int:
+    """Start the interactive chat REPL (``canvasctl chat``). Returns an exit code."""
+    from .repl import run_chat as _run_chat
+
+    return _run_chat(model=model)
+
+
+__all__ = ["run_ask", "run_chat"]

canvasctl/agent/loop.py

@@ -0,0 +1,245 @@
+"""Manual tool-use loop against the Anthropic Messages API.
+
+The agent answers questions by calling the ops registry as tools. ``anthropic``
+is an optional dependency, imported lazily so the core CLI works without it.
+
+API facts baked in (do not "fix" from stale priors):
+
+- default model ``claude-opus-4-8`` (override via ``CANVASCTL_MODEL`` or ``model=``)
+- ``thinking={"type": "adaptive"}``; ``max_tokens=16000``
+- NEVER pass ``temperature`` / ``top_p`` / ``top_k`` / ``budget_tokens`` (400s)
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from ..formatting import Colors, colorize
+from ..ops import WRITE, all_ops, dispatch
+
+MODEL_DEFAULT = "claude-opus-4-8"
+MAX_TOKENS = 16000
+MAX_ITERATIONS = 20
+
+SYSTEM_PROMPT = (
+    "You are canvasctl, a terminal assistant for Canvas LMS. You answer "
+    "questions about the user's courses, assignments, quizzes, due dates, "
+    "announcements, and files using the provided tools, which read from a "
+    "local vault synced from Canvas.\n\n"
+    "Guidelines:\n"
+    "- Answer only from tool results. Never invent course data or due dates.\n"
+    "- Cite due dates and times concretely (e.g. 'due Fri Mar 14 at 11:59pm').\n"
+    "- If the vault looks empty or the data seems stale, suggest running "
+    "`canvasctl sync`.\n"
+    "- Be concise and terminal-appropriate: short sentences, no filler, no "
+    "markdown headers."
+)
+
+
+class AgentError(RuntimeError):
+    """Raised when the agent cannot run (missing dep or unconfigured key)."""
+
+
+# --------------------------------------------------------------------------- #
+# Registry / tool wiring
+# --------------------------------------------------------------------------- #
+def _load_ops() -> list[Any]:
+    """All registered ops. Importing the catalog populates the registry.
+
+    ``catalog.py`` is written by a separate agent and may not exist yet; fall
+    back to whatever is already registered so this module is self-sufficient.
+    """
+    try:
+        import canvasctl.ops.catalog  # noqa: F401
+    except ImportError:
+        pass
+    return all_ops()
+
+
+def _build_tools(ops: list[Any]) -> list[dict[str, Any]]:
+    """Tool definitions in the shape the Messages API expects."""
+    return [
+        {
+            "name": o.name,
+            "description": o.description,
+            "input_schema": o.input_schema,
+        }
+        for o in ops
+    ]
+
+
+def _resolve_model(model: str | None = None) -> str:
+    return model or os.environ.get("CANVASCTL_MODEL") or MODEL_DEFAULT
+
+
+# --------------------------------------------------------------------------- #
+# Anthropic client (lazy)
+# --------------------------------------------------------------------------- #
+def _make_client() -> Any:
+    """Build a real Anthropic client, or raise a friendly ``AgentError``."""
+    try:
+        import anthropic  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - exercised via message only
+        raise AgentError(
+            "Chat features need the 'anthropic' package.\n"
+            "  Install it with:  pip install canvasctl[agent]"
+        ) from exc
+
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        raise AgentError(
+            "No Anthropic API key found.\n"
+            "  Run `canvasctl setup` to add one, or set ANTHROPIC_API_KEY."
+        )
+    return anthropic.Anthropic()
+
+
+# --------------------------------------------------------------------------- #
+# Response helpers
+# --------------------------------------------------------------------------- #
+def _collect_text(response: Any) -> str:
+    chunks: list[str] = []
+    for block in getattr(response, "content", None) or []:
+        if getattr(block, "type", None) == "text":
+            chunks.append(block.text)
+    return "\n".join(chunks).strip()
+
+
+def _is_error_payload(text: str) -> bool:
+    """dispatch() returns JSON; an error is ``{"error": ...}``."""
+    try:
+        parsed = json.loads(text)
+    except (ValueError, TypeError):
+        return False
+    return isinstance(parsed, dict) and "error" in parsed
+
+
+def _print_activity(name: str, args: dict[str, Any]) -> None:
+    parts = " ".join(f"{k}={v}" for k, v in (args or {}).items())
+    line = f"→ {name} {parts}".rstrip()
+    print(colorize(line, Colors.DIM))
+
+
+def _confirm_write(name: str, args: dict[str, Any]) -> bool:
+    """Interactive y/N gate before executing a WRITE op."""
+    print(colorize(f"About to run write operation: {name}", Colors.YELLOW + Colors.BOLD))
+    if args:
+        print(colorize(f"  args: {json.dumps(args, default=str)}", Colors.YELLOW))
+    try:
+        answer = input(colorize("Proceed? [y/N] ", Colors.BOLD))
+    except EOFError:
+        answer = ""
+    return answer.strip().lower() in ("y", "yes")
+
+
+def _execute_tools(response: Any, ops: list[Any]) -> list[dict[str, Any]]:
+    """Run every tool_use block; return all tool_result blocks (one batch)."""
+    by_name = {o.name: o for o in ops}
+    results: list[dict[str, Any]] = []
+    for block in getattr(response, "content", None) or []:
+        if getattr(block, "type", None) != "tool_use":
+            continue
+        name = block.name
+        args = block.input or {}
+        _print_activity(name, args)
+
+        op = by_name.get(name)
+        if op is not None and op.kind == WRITE:
+            if not _confirm_write(name, args):
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": "The user declined to run this write operation.",
+                    }
+                )
+                continue
+
+        text = dispatch(name, args)
+        results.append(
+            {
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": text,
+                "is_error": _is_error_payload(text),
+            }
+        )
+    return results
+
+
+# --------------------------------------------------------------------------- #
+# Core loop
+# --------------------------------------------------------------------------- #
+def _run_loop(
+    client: Any,
+    messages: list[dict[str, Any]],
+    *,
+    model: str,
+    ops: list[Any],
+    tools: list[dict[str, Any]],
+) -> str:
+    """Drive the tool-use loop, mutating ``messages`` in place.
+
+    Always leaves ``messages`` ending on the assistant turn so multi-turn chat
+    can simply append the next user message. Returns the final text.
+    """
+    for _ in range(MAX_ITERATIONS):
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "max_tokens": MAX_TOKENS,
+            "thinking": {"type": "adaptive"},
+            "system": SYSTEM_PROMPT,
+            "messages": messages,
+        }
+        if tools:
+            kwargs["tools"] = tools
+        response = client.messages.create(**kwargs)
+        stop = getattr(response, "stop_reason", None)
+
+        if stop == "pause_turn":
+            # Server paused a long turn; echo it back and resend to continue.
+            messages.append({"role": "assistant", "content": response.content})
+            continue
+
+        if stop == "tool_use":
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append(
+                {"role": "user", "content": _execute_tools(response, ops)}
+            )
+            continue
+
+        # Terminal turn: end_turn / max_tokens / refusal / stop_sequence / ...
+        messages.append({"role": "assistant", "content": response.content})
+        text = _collect_text(response)
+        if stop == "refusal":
+            print(colorize("Claude declined to respond to that request.", Colors.YELLOW))
+        elif stop == "max_tokens":
+            print(colorize("(output was truncated — hit the max token limit)", Colors.YELLOW))
+        return text
+
+    print(colorize("(stopped after too many tool-use rounds)", Colors.YELLOW))
+    return ""
+
+
+# --------------------------------------------------------------------------- #
+# Public entry points
+# --------------------------------------------------------------------------- #
+def ask_once(
+    prompt: str,
+    *,
+    client: Any = None,
+    model: str | None = None,
+    ops: list[Any] | None = None,
+) -> str:
+    """Answer a single prompt and return Claude's final text.
+
+    ``client`` and ``ops`` are injectable for tests; production callers leave
+    them unset so a real client and the full registry are used.
+    """
+    if ops is None:
+        ops = _load_ops()
+    tools = _build_tools(ops)
+    if client is None:
+        client = _make_client()
+    messages: list[dict[str, Any]] = [{"role": "user", "content": prompt}]
+    return _run_loop(client, messages, model=_resolve_model(model), ops=ops, tools=tools)

canvasctl/agent/repl.py

@@ -0,0 +1,76 @@
+"""Interactive chat REPL for ``canvasctl chat``.
+
+Preserves conversation history across turns and reuses the tool-use loop in
+``loop.py``. Supports ``/help``, ``/clear``, ``/exit``; Ctrl-C and Ctrl-D exit
+cleanly.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..formatting import Colors, colorize
+from . import loop
+
+_BANNER = (
+    "canvasctl chat — ask about your courses, assignments, and due dates.\n"
+    "Type /help for commands, /exit to quit."
+)
+
+_HELP = (
+    "Commands:\n"
+    "  /help    Show this help\n"
+    "  /clear   Forget the current conversation history\n"
+    "  /exit    Quit (Ctrl-D or Ctrl-C also work)"
+)
+
+
+def run_chat(model: str | None = None) -> int:
+    """Run the chat REPL. Returns an exit code."""
+    ops = loop._load_ops()
+    tools = loop._build_tools(ops)
+    try:
+        client = loop._make_client()
+    except loop.AgentError as exc:
+        print(colorize(str(exc), Colors.RED))
+        return 1
+
+    resolved_model = loop._resolve_model(model)
+    print(colorize(_BANNER, Colors.CYAN))
+    messages: list[dict[str, Any]] = []
+
+    while True:
+        try:
+            line = input(colorize("\ncanvasctl> ", Colors.GREEN + Colors.BOLD))
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        cmd = line.strip()
+        if not cmd:
+            continue
+        if cmd in ("/exit", "/quit"):
+            break
+        if cmd == "/help":
+            print(_HELP)
+            continue
+        if cmd == "/clear":
+            messages.clear()
+            print(colorize("(conversation history cleared)", Colors.GRAY))
+            continue
+
+        messages.append({"role": "user", "content": cmd})
+        try:
+            text = loop._run_loop(
+                client, messages, model=resolved_model, ops=ops, tools=tools
+            )
+        except KeyboardInterrupt:
+            print(colorize("\n(interrupted)", Colors.YELLOW))
+            break
+        except loop.AgentError as exc:
+            print(colorize(str(exc), Colors.RED))
+            continue
+        if text:
+            print("\n" + text)
+
+    print(colorize("bye.", Colors.GRAY))
+    return 0

canvasctl/cli.py

@@ -0,0 +1,197 @@
+"""CLI entrypoint for canvasctl."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+
+from . import __version__, agent, credentials, setup_wizard
+from .commands import (
+    announcements as cmd_announcements,
+)
+from .commands import (
+    changes as cmd_changes,
+)
+from .commands import (
+    config_cmd,
+    list_cmd,
+)
+from .commands import (
+    due as cmd_due,
+)
+from .commands import (
+    ics as cmd_ics,
+)
+from .commands import (
+    pull as cmd_pull,
+)
+from .commands import (
+    show as cmd_show,
+)
+from .commands import (
+    status as cmd_status,
+)
+from .commands import (
+    sync as cmd_sync,
+)
+from .commands import (
+    today as cmd_today,
+)
+from .formatting import Colors, colorize
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="canvasctl",
+        description="Canvas in your terminal: local vault, chat agent, and MCP server for Canvas LMS.",
+    )
+    p.add_argument("--version", action="version", version=f"canvasctl {__version__}")
+    p.add_argument("--vault", default=None, help="Vault directory (default: ~/canvas-vault)")
+    p.add_argument("--json", action="store_true", help="Emit JSON output where supported")
+    p.add_argument("-v", "--verbose", action="count", default=0, help="Increase log verbosity")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pcfg = sub.add_parser("config", help="Show or modify configuration")
+    pcfg.add_argument("--get", action="store_true")
+    pcfg.add_argument("--set-alias", dest="set_alias", help="COURSE_ID=ALIAS")
+    pcfg.add_argument("--unset-alias", dest="unset_alias", help="COURSE_ID")
+
+    psync = sub.add_parser("sync", help="Pull metadata from Canvas")
+    psync.add_argument("--course", default=None, help="Sync a single course only")
+    psync.add_argument("--workers", type=int, default=8, help="Concurrent course fetches")
+    psync.add_argument("--no-modules", action="store_true", help="Skip slow module-items fetch")
+    psync.add_argument("--no-files", action="store_true", help="Skip files fetch")
+
+    ptoday = sub.add_parser("today", help="Show items due today")
+    ptoday.add_argument("--course", default=None)
+    ptoday.add_argument("--type", choices=["assignment", "quiz", "all"], default="all")
+
+    pdue = sub.add_parser("due", help="Show items due in a future window")
+    pdue.add_argument("--course", default=None)
+    pdue.add_argument("--range", default="7d")
+    pdue.add_argument("--type", choices=["assignment", "quiz", "all"], default="all")
+
+    pann = sub.add_parser("announcements", aliases=["ann"], help="Show recent announcements")
+    pann.add_argument("--course", default=None)
+    pann.add_argument("--since", default="7d")
+    pann.add_argument("--verbose", "-V", action="store_true", help="Show message previews")
+
+    sub.add_parser("status", aliases=["dashboard", "dash"], help="Overview dashboard")
+
+    pchg = sub.add_parser("changes", help="Show recent change-log entries")
+    pchg.add_argument("--course", default=None)
+    pchg.add_argument("--since", default="24h")
+    pchg.add_argument("--type", default="all")
+
+    plist = sub.add_parser("list", help="List courses or per-course resources")
+    plist.add_argument("what", choices=list_cmd.LIST_KINDS)
+    plist.add_argument("--course", default=None)
+    plist.add_argument("--verbose", "-V", action="store_true")
+
+    pshow = sub.add_parser("show", help="Show a single item as JSON")
+    pshow.add_argument("--course", required=True)
+    pshow.add_argument("--assignment", default=None)
+    pshow.add_argument("--quiz", default=None)
+    pshow.add_argument("--announcement", default=None)
+    pshow.add_argument("--file", default=None)
+    pshow.add_argument("--module", default=None)
+
+    ppull = sub.add_parser("pull", help="Download course files into the vault")
+    ppull.add_argument("--course", default=None)
+    ppull.add_argument("--workers", type=int, default=4)
+    ppull.add_argument("--dry-run", action="store_true")
+
+    pics = sub.add_parser("ics", help="Export due dates as an .ics calendar file")
+    pics.add_argument("--course", default=None)
+    pics.add_argument("--range", default="60d")
+    pics.add_argument("--output", "-o", default=None)
+
+    sub.add_parser("setup", help="Interactive first-time setup (Canvas URL, token, API key)")
+
+    pask = sub.add_parser("ask", help="Ask Claude a one-off question about your courses")
+    pask.add_argument("prompt", nargs="+", help="Your question (quotes optional)")
+    pask.add_argument("--model", default=None, help="Override the model (default: claude-opus-4-8)")
+
+    pchat = sub.add_parser("chat", help="Start an interactive chat session with your courses")
+    pchat.add_argument("--model", default=None, help="Override the model (default: claude-opus-4-8)")
+
+    sub.add_parser("mcp", help="Run the MCP stdio server (for Claude Code / Claude Desktop)")
+
+    return p
+
+
+_DISPATCH = {
+    "config": config_cmd.run,
+    "sync": cmd_sync.run,
+    "today": cmd_today.run,
+    "due": cmd_due.run,
+    "announcements": cmd_announcements.run,
+    "ann": cmd_announcements.run,
+    "status": cmd_status.run,
+    "dashboard": cmd_status.run,
+    "dash": cmd_status.run,
+    "changes": cmd_changes.run,
+    "list": list_cmd.run,
+    "show": cmd_show.run,
+    "pull": cmd_pull.run,
+    "ics": cmd_ics.run,
+    "setup": setup_wizard.run,
+    "ask": lambda args: agent.run_ask(" ".join(args.prompt), args.model),
+    "chat": lambda args: agent.run_chat(args.model),
+    "mcp": lambda args: _run_mcp(args),
+}
+
+
+def _bridge_vault_env(args: argparse.Namespace) -> None:
+    # The ops catalog reads the vault from CANVASCTL_VAULT; bridge the global flag into it.
+    if getattr(args, "vault", None):
+        os.environ["CANVASCTL_VAULT"] = os.path.expanduser(args.vault)
+
+
+def _run_mcp(args: argparse.Namespace) -> int:
+    from .mcp_server import serve  # lazy: keeps `mcp` an optional dependency
+
+    serve()  # blocks, serving over stdio until the client disconnects
+    return 0
+
+
+def _configure_logging(verbosity: int) -> None:
+    level = logging.WARNING
+    if verbosity == 1:
+        level = logging.INFO
+    elif verbosity >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(level=level, format="%(levelname)s %(name)s: %(message)s")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(args.verbose)
+
+    credentials.apply_to_env()  # bridge ~/.config/canvasctl/config.json into the env (env wins)
+    _bridge_vault_env(args)  # ops catalog (ask/chat/mcp) reads the vault from CANVASCTL_VAULT
+
+    handler = _DISPATCH.get(args.cmd)
+    if handler is None:
+        parser.error(f"Unknown command: {args.cmd}")
+
+    try:
+        return handler(args) or 0
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        print(colorize("\nInterrupted.", Colors.YELLOW), file=sys.stderr)
+        return 130
+    except Exception as e:
+        if args.verbose >= 2:
+            raise
+        print(colorize(f"Error: {e}", Colors.RED), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())