KAZIK/docs/FORTUNE_AI.md

Offline Fortune Teller

Currently Shelved (2026-10-22)

The seated visual session no longer starts the worker or generates readings. The native scene deals and reveals cards, then explicitly says that explanation is not implemented. The crystal-ball scene is visual only, without academic grade selection or collection of student identity details. Existing inference sources and local model files are retained for future work, not required by the current game. The older AI archive is not an updated visual-session release. See FORTUNE_SESSION.md for the current runtime and verification.

The following documents the previous experimental neural integration.

The approved C++ exception is limited to the neural worker. MASM still owns the room, interaction, question input, card selection, dialogue rendering, process lifetime and all gameplay. No OpenAI API, Ollama, Python runtime, listening port, runtime downloader or external AI application is used by the game.

Model And Resources

• Qwen3-4B-Instruct-2507, Apache-2.0, Q4_K_M GGUF by Unsloth.
• Exact file: 2,497,281,120 bytes. Revision and SHA-256 are in ai/model.json.
• llama.cpp source is pinned in the same manifest; its MIT license is shipped.
• CPU-only x64 worker, AVX baseline, static MSVC runtime, no GPU driver required.
• Initial measurement: about 3 GB working set; allow additional RAM for Windows and the game. 8 GB system RAM is a practical starting point, not a tested minimum.
• On the development i7-14700K, baseline CPU generation took 41-53 seconds per answer in the first three-question test. Do not advertise instant replies.
• Model loads only for the conversation and is terminated on exit or shutdown. The game continues rendering while the model loads or answers.

The model produces entertainment, not reliable predictions or factual judgements about people. It must not determine real student grades from names, birth years or cards. No academic grading form or grade recommendation is implemented.

Native Integration

MODE_FORTUNE replaces the previous unavailable dialog only at the fortune teller. Users can type up to 240 CP1251 characters, ask a question, read a paged answer, ask a follow-up, or leave. Three distinct major arcana are chosen in assembly, including orientation; the worker interprets those exact cards. The initial catalogue contains 22 major arcana, not a full 78-card deck. History retains one previous question/answer in worker RAM, not a save or log.

Communication is through inherited anonymous pipes, not HTTP. The only child process is ai/fortune-engine.exe, created directly without a shell or console. Requests are five little-endian DWORDs (FCQ1 magic, byte length, three card IDs), then CP1251 question bytes. IDs 0-21 are upright, 22-43 reversed. Maximum worker question length is 768 bytes; the game UI imposes the tighter 240-byte bound. Responses contain three DWORDs (FCR1 magic, status, length), then CP1251 text. Status 0 means ready, 1 answer, 2 failure, 3 token-limited answer. Output is capped at 8192 bytes. Incomplete frames, pipe failures and a 180-second wait are handled without blocking the game. Request text cannot inject ChatML role delimiters.

Developer Build And Release

Install CMake and a Visual Studio C++ toolchain on the development machine only. tools/fortune_ai/build.ps1 builds the pinned worker and checks the model hash; -DownloadModel is an explicit development/release preparation option, never a game startup or installer action. The weights are deliberately ignored by Git. Copying only the Git checkout is not a complete offline distribution.

tools/fortune_ai/package.py makes dist/Assembler Casino Offline.zip with the game, assets, worker, prompts, licenses and actual GGUF, using ZIP64 for the model. Extract it and run Assembler Casino.exe; nothing else needs installing or downloading. --check-only validates the release inputs without creating it. The existing legacy C# self-extracting installer reads its entire embedded payload into a byte array. Do not embed the 2.5 GB model in that installer: it requires a separate streaming-installer update before it can ship this release.

Verification

tools/tests/check_fortune_ai.py runs the actual model, tests Russian output, follow-ups and oversized frame rejection, with no external service. Fictional test prompts and responses are written only to ignored build/fortune-ai. check_hall_expansion.py --with-fortune-ai tests the real native input, purchase- free request, pipe polling, displayed response, bounds and cleanup. The ordinary hall test also checks entering/leaving the dialog, stairs and previous fixes. These tests are not a full interactive desktop playthrough.

Published Build

Root/bin/build game copies and launcher metadata have SHA-256 C1714FEA01C6AA594A1895F56CCC287E5D1F35CDC829F5C2658FF05A4CBB6ECF. Fresh assembly, native dialogue/room/bar tests, function parity (including the WM_CHAR dispatch), billiards, card ranks, terminals and asset-loading checks pass. The worker also reuses only exact cached token prefixes between questions; failed inference clears that cache and history. It has only Windows system DLL imports.