dMath

Tidal 2025

Here’s the bare-minimum stuff they need plus copy-paste setup commands for macOS, Linux, and Windows.

1) Prereqs

• Python 3.10+ (3.11/3.12 fine)
• Ollama installed locally (for kid-friendly rewrites)
• Llama 3 instruct model (or any local model you choose)

2) Python libraries (pip)

• flask
• sympy
• requests
• orjson (fast JSON; if it fails on your platform, use ujson or Python’s built-in json and remove the orjson import/write path.)

Optional (nice to have):

• waitress (to serve on Windows without Flask’s dev server)

requirements.txt (drop this next to your script)

flask>=3.0
sympy>=1.12
requests>=2.31
orjson>=3.10

---

3) One-time model setup (Ollama)

After installing Ollama:

# pull a small-ish instruct model (as used in your code)
ollama pull llama3:instruct

If you want to swap models, change OLLAMA_MODEL env var (see below).

---

4) Quick install & run (macOS/Linux)

# From the folder with your .py file:
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

# Make sure Ollama is running (app or daemon), then:
ollama list            # sanity check; should show llama3:instruct

# (Optional) tweak env:
export OLLAMA_MODEL="llama3:instruct"   # default already
export OLLAMA_URL="http://127.0.0.1:11434"  # default already
export OLLAMA_TIMEOUT_S=60
export AIMATH_HISTORY="$HOME/.aimathcoach/history.jsonl"

# Run the app:
python your_file_name.py
# Open http://127.0.0.1:5000 in your browser

---

5) Quick install & run (Windows PowerShell)

# From the folder with your .py file:
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

# Ensure Ollama is running (Windows app/service), then:
ollama list

# (Optional) env vars for this session:
$env:OLLAMA_MODEL = "llama3:instruct"
$env:OLLAMA_URL = "http://127.0.0.1:11434"
$env:OLLAMA_TIMEOUT_S = "60"
$env:AIMATH_HISTORY = "$env:USERPROFILE\.aimathcoach\history.jsonl"

# Run the app:
py your_file_name.py
# Open http://127.0.0.1:5000

If you prefer a production server on Windows:

pip install waitress
waitress-serve --listen=127.0.0.1:5000 your_file_name:app

---

6) Environment variables (optional)

• OLLAMA_URL (default: http://127.0.0.1:11434)
• OLLAMA_MODEL (default: llama3:instruct)
• OLLAMA_TIMEOUT_S (default: 60.0)
• OLLAMA_TEMPERATURE (default: 0.3)
• OLLAMA_NUM_PREDICT (default: 700)
• AIMATH_HISTORY (default: ~/.aimathcoach/history.jsonl)
• READING_LEVEL (default: Grade 6)

Example .env-style snippet (bash):

export OLLAMA_MODEL="llama3:instruct"
export OLLAMA_TIMEOUT_S="60"
export READING_LEVEL="Grade 6"

---

7) Common gotchas

• “AI unavailable / model not installed” banner → Run ollama pull llama3:instruct and ensure the Ollama service is running.

• orjson install issues on unusual platforms → Replace import orjson with import json as orjson and adjust write_history to use orjson.dumps(...).encode() or just json.dumps(...).

• Firewall/port → The app serves on 127.0.0.1:5000. If you change the host to 0.0.0.0, your OS firewall may prompt you.

• Model too slow / timeouts → Lower OLLAMA_NUM_PREDICT, increase OLLAMA_TIMEOUT_S, or try a smaller model. The UI has a Retry button and shows verified steps even if AI times out.

That’s it—ship the file with requirements.txt, and these commands are all your teammate/judges need to bring it up on their machine.