diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100755 index 0000000..ba4b5f8 --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +set -euo pipefail + +remote_name="${1:-}" +current_branch="$(git rev-parse --abbrev-ref HEAD)" + +# Prevent server-side protected-branch push failures with a clear local message. +if [[ "$current_branch" == "main" && "$remote_name" == "origin" && "${ALLOW_MAIN_PUSH:-}" != "1" ]]; then + cat <<'MSG' >&2 +Blocked push to origin/main. +Use protected-branch workflow: +1) git switch -c +2) git push -u origin +3) open a PR to main + +To bypass once, run: +ALLOW_MAIN_PUSH=1 git push origin main +MSG + exit 1 +fi diff --git a/STATUS.md b/STATUS.md index 6502a19..ac8ab85 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-09 23:25 +Last updated: 2026-05-09 20:46 ## Project Purpose @@ -81,13 +81,12 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins ### Notable Audit Findings -- `STATUS.md` previously used external SVG image links for diagrams. This update replaces that with inline SVG diagrams to match repository agent instructions. -- `src/configs/config-llama.yaml` still contains two stale `src/headers/system_instructions/...` paths for augmented modes. The shipped default `src/configs/config.yaml` points to existing `src/assets/system_instructions/...` files. -- `src/configs/config.yaml.bak` is tracked and appears to be a mutable configurator backup with a different model (`mistral-small:latest`) and altered gameplay values. It should be reviewed before release because backup/config artefacts are normally risky to keep in source control. -- A tracked top-level file named `sdf` appears to contain captured Ollama/model-pull terminal output with ANSI control sequences and model warm-up text. It is not referenced by the audited launchers, docs, or tests and should be reviewed for removal or archival. -- `run_tests.py` defines `OLLAMA_HELPER = ROOT / "src" / "ollama_service.py"`, but no such file exists and the constant is unused in the inspected runner. -- `docs/ROADMAP.md` still describes the "current 0.2.x line" even though `VERSION` is `0.3.5`; it should be refreshed in a future documentation pass. -- `docs/images/architecture-modelito.svg` still says "Modelito 1.2.2 Cleanup" in its title while the dependency is `modelito==1.4.0`; the inline diagram below uses current wording, but the standalone image should be updated or removed later. +- `STATUS.md` now embeds architecture and runtime diagrams via repository SVG image links for markdown-renderer compatibility. +- Removed tracked repository-hygiene artefacts: top-level `sdf` and `src/configs/config.yaml.bak`. +- Fixed stale augmented system-instruction paths in `src/configs/config-llama.yaml` to use `src/assets/system_instructions/...`. +- Removed the unused `OLLAMA_HELPER` constant from `run_tests.py`. +- Refreshed `docs/ROADMAP.md` opening wording from `0.2.x` to `0.3.x`. +- Updated standalone `docs/images/*modelito.svg` wording to retire stale `modelito 1.2.2` references. - Generated Doxygen output under `docs/code/` is large and tracked. It appears intentional, but it dominates repository size and should be regenerated only as part of deliberate API-documentation updates. - The current git worktree was clean before this status update. @@ -139,181 +138,13 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins ## Architecture Overview -### Inline Architecture Diagram - - - BatLLM architecture - Architecture diagram showing launchers, Kivy surfaces, game logic, replay logic, configuration, the BatLLM LLM service facade, modelito, Ollama, packaging, tests, and documentation. - - - - - - - - BatLLM Current Architecture - - - Root launchers - run_batllm.py - run_game_analyzer.py - - - Gameplay Kivy app - main.py, home/settings/history - game_board.py, bot.py, bullet.py - ollama_config_screen.py - - - Standalone analyzer - analyzer_main.py - analyzer_model.py - load/review/board screens - - - Config and state - config.yaml + app_config.py - BATLLM_HOME overlays - saved sessions - prompt/system assets - - - LLM service facade - src/llm/service.py - timeouts, readiness, metadata - start/stop/download/delete - - - Runtime - modelito 1.4.0 - local Ollama - models/server - - - Replay/session layer - history_manager.py - session_schema.py - replay_engine.py - - - Docs and API reference - docs/*.md - docs/code generated output - - - Tests and smoke tools - src/tests/*.py - ollama_mock_server.py - packaging_smoke.py - - - Release packaging - release bundles - Homebrew formula - GitHub Actions - - - - - - - - - - - - - - -### Inline Runtime Flow Diagram - - - BatLLM runtime flow - Runtime flow from configuration and model selection through model readiness, prompt execution, turn resolution, persistence, and analyzer replay. - - - - - - - - BatLLM Runtime Flow - - - Load configuration - defaults + shipped YAML - optional BATLLM_HOME overlay - - - Select model - Ollama screen or defaults - local or remote inventory - - - Local model - available? - - - Ensure model readiness - resolve timeout and warm-up - record last_served_model - report structured errors - - - Download remote model - stream progress through modelito - refresh local inventory - - - Submit player prompt - build command context - use independent/shared history - - - Model provider call - OllamaConnector to modelito - assistant response text - - - Resolve turn - parse move/rotate/shoot/shield - update board and history - - - Save or analyse - v2 session payload - replay in analyzer - - - - - - - - - - - +### Architecture Diagram + +![BatLLM architecture](docs/images/architecture-modelito.svg) + +### Runtime Flow Diagram + +![BatLLM runtime flow](docs/images/request-flow-modelito.svg) ## Important Files And Directories @@ -344,7 +175,7 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `docs/README.md` is the canonical project overview and includes setup, Homebrew install notes, concepts, compatibility, troubleshooting, and glossary material. - `docs/USER_GUIDE.md` is the user-facing manual for gameplay, commands, screens, settings, analyzer use, sessions, and troubleshooting. - `docs/CONTRIBUTING.md` is the developer manual for setup, architecture, tests, release workflow, docs workflow, coding conventions, and troubleshooting. -- `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction, but its opening version wording needs a minor refresh from `0.2.x` to the current `0.3.x` line. +- `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction using current `0.3.x` line wording. - `docs/RELEASE_CRITERIA_1_0.md` defines CI, reliability, UX, bundle, and documentation gates for a future 1.0 candidate. - `docs/CHANGELOG.md` keeps active unreleased notes on the `0.x` hold and draft 1.0 notes. - `docs/FIRST_RUN_RELEASE_CHECKLIST.md` and `docs/UI_UNIFICATION_PLAN_1_0.md` remain release-preparation references. @@ -387,12 +218,6 @@ The previous status report recorded these successful checks from the same releas - Local Ollama operations are inherently stateful. Starting/stopping the service, warming models, downloading models, or deleting models can affect real user state. - GUI validation is limited in headless/non-interactive environments; many UI paths rely on Kivy event-loop behaviour and manual spot checks. - `run_tests.py full` can affect a real Ollama service and should be run only with explicit maintainer intent. -- `src/configs/config-llama.yaml` contains stale augmented-system-instruction paths under `src/headers/...` that do not match the current asset tree. -- Tracked `src/configs/config.yaml.bak` appears to be mutable local backup data and should be reviewed before any release freeze. -- Tracked `sdf` appears to be a captured Ollama terminal log and is likely accidental or at least unexplained repository material. -- `run_tests.py` has an unused `OLLAMA_HELPER` constant pointing to a missing `src/ollama_service.py` path. -- `docs/ROADMAP.md` has stale wording that describes the current line as `0.2.x`. -- Standalone diagram files under `docs/images/` still include modelito 1.2.2 wording even though current requirements pin modelito 1.4.0. - Generated API docs under `docs/code/` may become stale when source changes unless regenerated deliberately. - Homebrew distribution remains source-based and macOS/Apple-Silicon oriented. - The saved-session v2 schema is the supported path; unsupported legacy sessions are intentionally rejected by schema helpers. @@ -401,12 +226,7 @@ The previous status report recorded these successful checks from the same releas ### High Priority Before Release Freeze -- Decide whether to remove, ignore, or document the tracked `sdf` terminal-capture file. -- Decide whether tracked `src/configs/config.yaml.bak` is intentional; remove it or document why it is shipped. -- Fix stale `src/configs/config-llama.yaml` augmented-system-instruction paths. -- Remove or update the unused `OLLAMA_HELPER` constant in `run_tests.py`. -- Refresh `docs/ROADMAP.md` opening version wording from `0.2.x` to the current `0.3.x` line. -- Update or retire standalone `docs/images/*modelito.svg` files whose titles mention modelito 1.2.2. +- Repository-hygiene follow-ups from this audit have been addressed in this update (`sdf`, `config.yaml.bak`, stale alternate config paths, unused test-runner constant, stale roadmap wording, and stale standalone modelito diagram wording). ### Validation Pending @@ -425,7 +245,7 @@ The previous status report recorded these successful checks from the same releas ## Next Steps 1. Run the narrow validation for this documentation update: `python -m pytest -q`. -2. Review and address the repository-hygiene findings (`sdf`, `config.yaml.bak`, stale alternate config paths, unused test-runner constant). +2. Keep repository-hygiene checks active for future artefacts and generated-file drift. 3. Refresh stale documentation/diagram wording identified by the audit. 4. Run full non-live CI-equivalent checks across source, tests, packaging smoke, and Homebrew formula generation. 5. Schedule a maintainer-owned live Ollama validation pass before any release candidate. @@ -438,4 +258,4 @@ The previous status report recorded these successful checks from the same releas - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing. - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour. -Last updated: 2026-05-09 23:25 +Last updated: 2026-05-09 20:46 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8bd5758..1cf9c98 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # ROADMAP -BatLLM is approaching 1.0 as a stable local desktop product. The current 0.2.x line already includes the core game loop, session saving, replay analysis, cross-platform launchers, and Ollama integration, so the remaining work for 1.0 is product consistency, reliability, and release hardening. +BatLLM is approaching 1.0 as a stable local desktop product. The current 0.3.x line already includes the core game loop, session saving, replay analysis, cross-platform launchers, and Ollama integration, so the remaining work for 1.0 is product consistency, reliability, and release hardening. Version 2.0 is the planned architecture shift. It should focus on networked play first, then use that foundation to support additional clients and shared content. diff --git a/docs/images/architecture-modelito.svg b/docs/images/architecture-modelito.svg index ca881cd..4721881 100644 --- a/docs/images/architecture-modelito.svg +++ b/docs/images/architecture-modelito.svg @@ -21,7 +21,7 @@ - BatLLM Architecture After The Modelito 1.2.2 Cleanup + BatLLM Architecture After The Modelito 1.4.0 Migration Gameplay, UI, timeout policy, and config-overlay rules stay inside BatLLM. Generic provider and model-management behaviour now routes through modelito. diff --git a/docs/images/request-flow-modelito.svg b/docs/images/request-flow-modelito.svg index 4427c75..c7695a2 100644 --- a/docs/images/request-flow-modelito.svg +++ b/docs/images/request-flow-modelito.svg @@ -22,7 +22,7 @@ BatLLM Runtime Flow With Direct Modelito Integration - The same `modelito` toolchain now drives local selection, remote downloads, smoke validation, the configurator console, and live gameplay requests. + The same modelito toolchain now drives local selection, remote downloads, smoke validation, the configurator console, and live gameplay requests. 1. Select Or Refresh A Model diff --git a/run_batllm.py b/run_batllm.py index 342663a..46b6586 100644 --- a/run_batllm.py +++ b/run_batllm.py @@ -1,6 +1,7 @@ """Cross-platform launcher for BatLLM.""" from __future__ import annotations +from util.compat import require_supported_python import sys from pathlib import Path @@ -11,7 +12,6 @@ if str(SRC) not in sys.path: sys.path.insert(0, str(SRC)) -from util.compat import require_supported_python require_supported_python("BatLLM") diff --git a/run_game_analyzer.py b/run_game_analyzer.py index 3903c21..035d946 100644 --- a/run_game_analyzer.py +++ b/run_game_analyzer.py @@ -1,6 +1,7 @@ """Cross-platform launcher for the standalone BatLLM Game Analyzer.""" from __future__ import annotations +from util.compat import require_supported_python import sys from pathlib import Path @@ -11,7 +12,6 @@ if str(SRC) not in sys.path: sys.path.insert(0, str(SRC)) -from util.compat import require_supported_python require_supported_python("BatLLM Game Analyzer") diff --git a/run_tests.py b/run_tests.py index 5f15f02..f7c5c56 100644 --- a/run_tests.py +++ b/run_tests.py @@ -1,6 +1,7 @@ """Cross-platform test runner for BatLLM.""" from __future__ import annotations +from util.compat import require_supported_python import argparse import os @@ -13,12 +14,10 @@ VENV_PYTHON = ( ROOT / ".venv_BatLLM" / ("Scripts/python.exe" if os.name == "nt" else "bin/python") ) -OLLAMA_HELPER = ROOT / "src" / "ollama_service.py" if str(SRC) not in sys.path: sys.path.insert(0, str(SRC)) -from util.compat import require_supported_python def build_parser() -> argparse.ArgumentParser: """Create the CLI argument parser.""" diff --git a/sdf b/sdf deleted file mode 100644 index d3c93ae..0000000 --- a/sdf +++ /dev/null @@ -1,17 +0,0 @@ -Config: model=llama3.2:latest host=localhost port=11434 -ollama already serving at localhost:11434 -Loading model into memory: llama3.2:latest -[?2026h[?25lpulling manifest ā ‹ [?25h[?2026l[?2026h[?25lpulling manifest ā ™ [?25h[?2026l[?2026h[?25lpulling manifest ā ¹ [?25h[?2026l[?2026h[?25lpulling manifest ā ø [?25h[?2026l[?2026h[?25lpulling manifest ā ¼ [?25h[?2026l[?2026h[?25lpulling manifest ā ¦ [?25h[?2026l[?2026h[?25lpulling manifest ā ¦ [?25h[?2026l[?2026h[?25lpulling manifest  -pulling dde5aa3fc5ff: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 2.0 GB  -pulling 966de95ca8a6: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 1.4 KB  -pulling fcc5a6bec9da: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 7.7 KB  -pulling a70ff7e570d9: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 6.0 KB  -pulling 56bb8bd477a5: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 96 B  -pulling 34bb5ab01051: 100% ā–•ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā– 561 B  -verifying sha256 digest  -writing manifest  -success [?25h[?2026l -Warming up model: llama3.2:latest -[?2026h[?25lā ™ [?25h[?2026l[?25l[?2026h[?25l[?25h[?2026l[?25hI[?25l[?25h'm[?25l[?25h happy[?25l[?25h to[?25l[?25h help[?25l[?25h you[?25l[?25h,[?25l[?25h but[?25l[?25h it[?25l[?25h seems[?25l[?25h like[?25l[?25h your[?25l[?25h question[?25l[?25h got[?25l[?25h cut[?25l[?25h off[?25l[?25h.[?25l[?25h Could[?25l[?25h you[?25l[?25h please[?25l[?25h re[?25l[?25hphrase[?25l[?25h or[?25l[?25h provide[?25l[?25h more[?25l[?25h context[?25l[?25h so[?25l[?25h I[?25l[?25h can[?25l[?25h better[?25l[?25h assist[?25l[?25h you[?25l[?25h?[?25l[?25h What[?25l[?25h's[?25l[?25h on[?25l[?25h your[?25l[?25h mind[?25l[?25h?[?25l[?25h - -[?25l[?25h \ No newline at end of file diff --git a/src/configs/config-llama.yaml b/src/configs/config-llama.yaml index 818be46..c6cd321 100644 --- a/src/configs/config-llama.yaml +++ b/src/configs/config-llama.yaml @@ -19,8 +19,8 @@ llm: num_ctx: 4096 path: /api/chat port: 11434 - system_instructions_augmented_independent: src/headers/system_instructions/augmented_independent_1.txt - system_instructions_augmented_shared: src/headers/system_instructions/augmented_shared_1.txt + system_instructions_augmented_independent: src/assets/system_instructions/augmented_independent_1.txt + system_instructions_augmented_shared: src/assets/system_instructions/augmented_shared_1.txt system_instructions_not_augmented_independent: src/assets/system_instructions/not_augmented_independent_1.txt system_instructions_not_augmented_shared: src/assets/system_instructions/not_augmented_shared_1.txt url: http://localhost diff --git a/src/configs/config.yaml.bak b/src/configs/config.yaml.bak deleted file mode 100644 index fea13b9..0000000 --- a/src/configs/config.yaml.bak +++ /dev/null @@ -1,40 +0,0 @@ -data: - saved_sessions_folder: saved_sessions -game: - bot_diameter: 0.1 - bot_step_length: 0.21 - bullet_damage: 5 - bullet_diameter: 0.02 - bullet_step_length: 0.01 - independent_contexts: true - initial_health: 30 - prompt_augmentation: true - shield_initial_state: true - shield_size: 40 - total_rounds: 2 - turns_per_round: 8 -llm: - debug_requests: false - model: mistral-small:latest - num_ctx: 4096 - path: /api/chat - port: 11434 - system_instructions_augmented_independent: src/assets/system_instructions/augmented_independent_1.txt - system_instructions_augmented_shared: src/assets/system_instructions/augmented_shared_1.txt - system_instructions_not_augmented_independent: src/assets/system_instructions/not_augmented_independent_1.txt - system_instructions_not_augmented_shared: src/assets/system_instructions/not_augmented_shared_1.txt - url: http://localhost - temperature: null - top_p: null - top_k: null - timeout: null - max_tokens: null - stop: null - seed: null - num_thread: null - num_predict: null -ui: - font_size: 16 - frame_rate: 60 - primary_color: '#0b0b0b' - title: BatLLM