Skip to content

docs(ollama): Ollama launcher + setup docs + fix README misdirection (closes #118) - #119

Open
MoonlightByte wants to merge 8 commits into
mainfrom
fix/ollama-docs-launcher
Open

MoonlightByte wants to merge 8 commits into
mainfrom
fix/ollama-docs-launcher

Conversation

@MoonlightByte

Copy link
Copy Markdown
Owner

Summary

  • Fixes README.md lines 458-459 which misdirected users to configure a non-existent endpoint setting in config.py (issue [DOCUMENTATION] Ollama support #118).
  • Adds a dedicated Ollama integration section in README.md mirroring the existing LM Studio section.
  • Adds run_with_ollama_direct.bat and run_with_ollama_direct.sh — self-contained launchers that handle Ollama alias setup inline on first run. Both of the game's internal model tiers are aliased to a single user-chosen Ollama model (matches LM Studio's single-model behavior; avoids VRAM thrashing).
  • Adds OLLAMA_SETUP.md and OLLAMA_QUICKSTART.txt.

UX parity with LM Studio

Step LM Studio Ollama
1 Install LM Studio Install Ollama
2 Load a model in the LM Studio UI `ollama pull `
3 Double-click `run_with_lmstudio_direct.bat` Double-click `run_with_ollama_direct.bat`

On first run, the launcher auto-creates two aliases (`gpt-4.1-2025-04-14` and `gpt-4.1-mini-2025-04-14`) both pointing at the user's single pulled model. No separate setup script, no manual `ollama cp` calls. Setting `OLLAMA_MODEL=` before launch forces re-aliasing to a different model.

Out of scope

  • No Python code changes. The `multi-model-refactor` branch is the long-term home for first-class Ollama integration.
  • Image generation and TTS remain broken under Ollama (no compatible endpoint upstream). Documented in the Known Issues section.
  • `README.md` lines 416 and 954 have the same `config.py` misdirection class-bug; left for a follow-up docs sweep because they don't block issue [DOCUMENTATION] Ollama support #118.
  • No `run_with_lmstudio_direct.sh` added for macOS/Linux — that gap predates this PR.

Test plan

End-to-end testing with a live Ollama server was not performed on the author's machine (local Ollama is 0.1.29, below the documented 0.4+ floor, and the daemon wasn't running). Static verification was done instead:

  • Shell script `bash -n` clean
  • Spec compliance review: files match plan verbatim
  • Code quality review approved after 3 fix commits (macOS bash 3.2 portability, `OLLAMA_MODEL` override working correctly, `curl` timeout, `findstr /L /C:` literal match)
  • No Python files modified
  • LM Studio integration section preserved; no LM Studio files touched
  • First-run with one pulled model auto-creates both aliases and starts the game (requires Ollama 0.4+ to test)
  • Re-run with aliases present skips setup and starts immediately
  • With multiple pulled models, launcher aborts and requires `OLLAMA_MODEL`
  • With `OLLAMA_MODEL` set, launcher re-points aliases even when they exist
  • A game action round-trips through Ollama on `/v1/chat/completions`
  • `run_with_lmstudio_direct.bat` still works (Windows regression check)

Closes #118.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCUMENTATION] Ollama support

2 participants