Project Context for Agents

This repository is a coding-interview practice workspace with a Tk/Ttk GUI for generating problem stubs, editing code, and running tests. Everything lives under /Users/andrewzhao/Documents/coding_interview.

Key Components

• tools/gui.py: Main desktop GUI. Provides the in-app editor (smart indent/backspace, syntax highlighting), topic browser, stats pane, streak tracking overlay, test runner integration, and a collapsible Copilot (local LLM via Ollama) with streaming chat + Markdown rendering.
• tools/generate_entry.py: Registry of problems (ProblemSpec). Generates stubs/tests and backs the GUI & CLI topic list.
• workspace/: Auto-created package where generated solutions live. Files here run via python -m workspace.<module>.
• ml/, coding/, leetcode/: Reference implementations and topic material used for canonical solutions/tests.
• Makefile: Shortcuts (make / make gui) to launch the GUI.

Typical Flows

1. Launch GUI via python -m tools (or python tools/gui.py).
2. Pick a topic from the left tree or use random/smart random.
3. Generate writes a stub into workspace/ and opens it in the embedded editor.
4. Edit in place; save with Cmd/Ctrl+S or the Save button (red dot signals unsaved changes).
5. Run tests with the Run Tests button; output appears in the Output tab. Stats update automatically, streak counter animates on consecutive passes, and a celebratory popup appears on success.
6. Copilot: Toggle the right-side Copilot (Copilot ▶ in header, or Cmd/Ctrl+Shift+C). Ask questions; it streams replies with Markdown (code fences, lists, tables, bold/italic). Context includes the current topic, your code, and the canonical implementation.
7. Need an external review? Copy Review Prompt (always enabled) pushes a comparison prompt to the clipboard and shows a quick “Prompt copied” toast.
8. Optional: view canonical implementation via View Canonical.

Repo Conventions

• Python 3.10+, Tkinter available. No external dependencies assumed for GUI.
• Soft tabs set to 4 spaces in editor helpers.
• Generated stubs/tests should be deterministic and self-contained (no network calls).
• Stats persisted at .practice_stats.json in repo root; session temp files tracked in GUI.
• When adding topics, update generate_entry.py and, if needed, gui.canonical_path_for_topic.

For Future Agents

• Prefer rg for searching; shell commands should be invoked with ["bash","-lc", ...] and workdir set.
• Editing: use apply_patch for targeted changes; do not overwrite user content or undo unrelated modifications.
• GUI key-bindings are customized (including Cmd/Ctrl ± zoom that scales editor panes and the tree font); verify behavior analytically if you cannot run Tkinter.
• Before major changes, skim README and relevant files to understand current features.
• Tests are usually invoked per-problem via the GUI; if running manually, use python -m workspace.<module>.

Copilot internals

• Backend: Ollama HTTP API (/api/chat) with streaming; keeps models warm via keep_alive and reuses KV via the returned context.
• UI: Built in tools/gui.py via _build_copilot_panel and toggled by toggle_copilot.
• Context assembly: _assemble_copilot_context() gathers topic, candidate code, and canonical content.
• Streaming: _ollama_chat_stream() handles newline-delimited JSON; updates Tk widgets via after().
• Markdown: _apply_markdown_to_range() for headings, bold/italic, inline/fenced code, lists, blockquotes, and Markdown tables.
• Auto-start Ollama: _maybe_start_ollama() spawns ollama serve if found; controlled by PRACTICE_AUTOSTART_OLLAMA and --no-llm-serve.
• KV prewarm: _maybe_prewarm_kv() posts num_predict: 0 with context at startup to reduce first-token latency; captured context is reused on next turns.

Caveats/notes

• Default model is gpt-oss:20b; on small RAM machines, advise switching to a 7B–14B model.
• If you modify context shape/contents, ensure _assemble_copilot_context() and prewarm behavior are kept in sync. Consider re‑prewarming on topic changes.
• Always call Tk updates from the main thread using after().

Useful Commands

• python -m tools — launch GUI.
• python -m tools --no-llm-serve — launch GUI without auto-starting Ollama.
• python tools/generate_entry.py --list — list available topics.
• python tools/generate_entry.py --topic <id> — generate stub/tests without GUI.
• python -m workspace.<module> — run a generated solution (tests included in file).

Troubleshooting Notes

• GUI smart editing handlers live near the bottom of tools/gui.py (search for _on_*).
• Stats issues likely stem from StatsManager in the same file.
• Timers/daily goals handled inside GUI; ensure Tk event loop updates via after.
• If Tk bindings misbehave, check that self.text.bind(...) matches handler logic.
• Clipboard operations show transient toasts via _show_prompt_copied; if they stop appearing, confirm the Toplevel overlay is created (may fail on some WMs without display permissions).
• Copilot not responding: confirm Ollama is running (ollama serve). Status pill shows “Starting Ollama…” / “Ollama ready”. Set OLLAMA_BASE_URL if running on a non-default host/port.
• Slow first token: prewarm builds KV on launch; ensure keep-alive and KV reuse are active. Increase keep_alive if needed.

Keep this file updated when behaviors or workflows change so agents have immediate context.