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

Launch GUI via
```
python -m tools
```
(or
```
python tools/gui.py
```
).
Pick a topic from the left tree or use random/smart random.
```
Generate
```
writes a stub into
```
workspace/
```
and opens it in the embedded editor.
Edit in place; save with
```
Cmd/Ctrl+S
```
or the
```
Save
```
button (red dot signals unsaved changes).
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.
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.
Need an external review?
```
Copy Review Prompt
```
(always enabled) pushes a comparison prompt to the clipboard and shows a quick “Prompt copied” toast.
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.

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

Launch GUI via

python -m tools

(or

python tools/gui.py

Pick a topic from the left tree or use random/smart random.

Generate

writes a stub into

workspace/

and opens it in the embedded editor.

Edit in place; save with

Cmd/Ctrl+S

or the

Save

button (red dot signals unsaved changes).

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.

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.

Need an external review?

Copy Review Prompt

(always enabled) pushes a comparison prompt to the clipboard and shows a quick “Prompt copied” toast.

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>

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.

Project Context for Agents

Project Context for Agents

Key Components

Typical Flows

Repo Conventions

For Future Agents

Copilot internals

Useful Commands

Troubleshooting Notes

Related Skills

Markdown Converter

Nano Banana Pro

1password

Project Context for Agents

Key Components

Typical Flows

Repo Conventions

For Future Agents

Copilot internals

Useful Commands

Troubleshooting Notes