Instructions to use Maelstrome/lora-wave-session with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use Maelstrome/lora-wave-session with PEFT:

from peft import PeftModel
from transformers import AutoModelForCausalLM

base_model = AutoModelForCausalLM.from_pretrained("unsloth/gemma-4-e2b-it-unsloth-bnb-4bit")
model = PeftModel.from_pretrained(base_model, "Maelstrome/lora-wave-session")

Notebooks
Google Colab
Kaggle
Local Apps Settings

llama.cpp

How to use Maelstrome/lora-wave-session with llama.cpp:

Install (macOS, Linux)

curl -LsSf https://llama.app/install.sh | sh
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf Maelstrome/lora-wave-session:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf Maelstrome/lora-wave-session:Q4_K_M

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf Maelstrome/lora-wave-session:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf Maelstrome/lora-wave-session:Q4_K_M

Use pre-built binary

# Download pre-built binary from:
# https://github.com/ggerganov/llama.cpp/releases
# Start a local OpenAI-compatible server with a web UI:
./llama-server -hf Maelstrome/lora-wave-session:Q4_K_M
# Run inference directly in the terminal:
./llama-cli -hf Maelstrome/lora-wave-session:Q4_K_M

Build from source code

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j --target llama-server llama-cli
# Start a local OpenAI-compatible server with a web UI:
./build/bin/llama-server -hf Maelstrome/lora-wave-session:Q4_K_M
# Run inference directly in the terminal:
./build/bin/llama-cli -hf Maelstrome/lora-wave-session:Q4_K_M

Use Docker

docker model run hf.co/Maelstrome/lora-wave-session:Q4_K_M

LM Studio
Jan

vLLM

How to use Maelstrome/lora-wave-session with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "Maelstrome/lora-wave-session"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Maelstrome/lora-wave-session",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/Maelstrome/lora-wave-session:Q4_K_M

Ollama
How to use Maelstrome/lora-wave-session with Ollama:
```
ollama run hf.co/Maelstrome/lora-wave-session:Q4_K_M
```
Unsloth Desktop

How to use Maelstrome/lora-wave-session with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf Maelstrome/lora-wave-session:Q4_K_M

Configure the model in Pi

# Install Pi:
npm install -g @earendil-works/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "Maelstrome/lora-wave-session:Q4_K_M"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Docker Model Runner
How to use Maelstrome/lora-wave-session with Docker Model Runner:
```
docker model run hf.co/Maelstrome/lora-wave-session:Q4_K_M
```

Lemonade

How to use Maelstrome/lora-wave-session with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull Maelstrome/lora-wave-session:Q4_K_M

Run and chat with the model

lemonade run user.lora-wave-session-Q4_K_M

List all available models

lemonade list

Hermes Agent

How to use Maelstrome/lora-wave-session with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf Maelstrome/lora-wave-session:Q4_K_M

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default Maelstrome/lora-wave-session:Q4_K_M

Run Hermes

hermes

Atomic Chat

OpenClaw

How to use Maelstrome/lora-wave-session with OpenClaw:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf Maelstrome/lora-wave-session:Q4_K_M

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "Maelstrome/lora-wave-session:Q4_K_M" \
  --custom-provider-id llama-cpp \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

Maelstrome commited on May 12

Commit

b128db0

verified ·

1 Parent(s): a524731

Standardize README: add sibling-runs table, known-quirks, full eval metrics

Browse files

Files changed (1) hide show

README.md +35 -17

README.md CHANGED Viewed

@@ -31,6 +31,20 @@ A unified LoRA adapter on top of **Gemma 4 E2B Instruct** that handles three str
 All three surfaces emit strict JSON, no markdown, no analysis voice, in patient-facing tone.
 ## Provenance and intended use
 Trained for the WAVE app, a wellness/reflection tool — not a medical device, not clinical decision support, not a substitute for professional advice. Use under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
@@ -79,7 +93,7 @@ User prompt:
 <task>Generate exactly 6 patient-facing narration lines. Return only strict JSON. Schema: {"lines":["...", ...]}</task>
 ```
-Expected output (set `max_new_tokens >= 224`):
 ```json
 {"lines":["You've made it to the end of this practice.","Check in with your urge now — has anything shifted?","...","...","...","..."]}
@@ -87,8 +101,6 @@ Expected output (set `max_new_tokens >= 224`):
 ### `reflection` (post-session card)
-User prompt:
 ```
 <surface>reflection</surface>
 <patient_context>{"durationSeconds":780,"endingIntensity":2,"intakeIntensity":7,"matType":"buprenorphine","medicationStatus":"on_time","sessionsCount":12,"trigger":"stress","usedSubstanceToday":false}</patient_context>
@@ -97,8 +109,6 @@ User prompt:
 ### `check_in` (multi-turn)
-User prompt:
 ```
 <surface>check_in</surface>
 <specialized_surface>lora-check-in-1</specialized_surface>
@@ -111,11 +121,11 @@ User prompt:
 | | |
 |---|---|
 | Base | `unsloth/gemma-4-E2B-it` |
-| Method | QLoRA (4-bit) |
-| Adapter rank / alpha / dropout | 16 / 32 / 0 |
 | Target modules | q/k/v/o + gate/up/down (language layers only) |
 | Vision/audio layers | Frozen |
-| Optimizer | adamw_8bit |
 | LR | 2e-4, linear schedule |
 | Warmup | 64 steps (~5%) |
 | Weight decay | 0.001 |
@@ -132,18 +142,22 @@ Loss curve: 1.55 (step 1) → 0.76 (avg first 50) → 0.148 (steps 400-500) →
 ## Evaluation
-### Held-out validation (n=428, completion-only)
-| Metric | Value |
-|---|---|
-| Completion NLL | 4.704 |
-| Completion PPL | 110.4 |
-Surface coverage: `check_in 165`, `phase_narration 155`, `reflection 108`.
-### Generation sanity (n=8 from held-out test)
-| Metric | Value |
 |---|---|
 | JSON validity | 100% (8/8) |
 | Schema pass | 100% (8/8) |
@@ -155,7 +169,11 @@ Surface coverage: `check_in 165`, `phase_narration 155`, `reflection 108`.
 | Check-in turn sequence pass | 100% |
 | Mean tokens/sec (Python QLoRA path) | 10.1 |
-> **Generation-time tip:** `phase_narration` outputs need a budget of **≥ 224 new tokens** (256 recommended). Test outputs needed up to 207 tokens for the six-line JSON to complete cleanly. `check_in` is fine at 96, `reflection` at 192.
 ## Dataset

 All three surfaces emit strict JSON, no markdown, no analysis voice, in patient-facing tone.
+## Sibling runs
+This is the **rank-16 / 3-epoch RTX 5080** training of the WAVE corpus. The rank-32 / 1-epoch A100 sibling lives at [`Maelstrome/lora-wave-session-r32`](https://huggingface.co/Maelstrome/lora-wave-session-r32) and wins on every probability metric on the same frozen 428-row test split:
+| | **rank-16 (this run)** | rank-32 (sibling) |
+|---|---|---|
+| LoRA completion NLL | **4.7149** | 4.5576 |
+| LoRA perplexity | **111.59** | 95.35 |
+| Paired wins vs base | **386 / 428 (90.2%)** | 428 / 428 (100%) |
+| Mean NLL Δ vs base | **0.327 nats** | 0.508 nats |
+| Sign-test p-value | **9.5 × 10⁻⁷¹** | 2.9 × 10⁻¹²⁹ |
+See [`Maelstrome/lora-wave-session-r32-report`](https://huggingface.co/Maelstrome/lora-wave-session-r32-report) for the full head-to-head report (recipes, generation eval, reproducibility check).
 ## Provenance and intended use
 Trained for the WAVE app, a wellness/reflection tool — not a medical device, not clinical decision support, not a substitute for professional advice. Use under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
 <task>Generate exactly 6 patient-facing narration lines. Return only strict JSON. Schema: {"lines":["...", ...]}</task>
 ```
+Expected output (set `max_new_tokens ≥ 224`):
 ```json
 {"lines":["You've made it to the end of this practice.","Check in with your urge now — has anything shifted?","...","...","...","..."]}
 ### `reflection` (post-session card)
 ```
 <surface>reflection</surface>
 <patient_context>{"durationSeconds":780,"endingIntensity":2,"intakeIntensity":7,"matType":"buprenorphine","medicationStatus":"on_time","sessionsCount":12,"trigger":"stress","usedSubstanceToday":false}</patient_context>
 ### `check_in` (multi-turn)
 ```
 <surface>check_in</surface>
 <specialized_surface>lora-check-in-1</specialized_surface>
 | | |
 |---|---|
 | Base | `unsloth/gemma-4-E2B-it` |
+| Method | QLoRA (4-bit) via Unsloth `FastModel` |
+| Adapter rank / alpha / dropout | **16 / 32 / 0** |
 | Target modules | q/k/v/o + gate/up/down (language layers only) |
 | Vision/audio layers | Frozen |
+| Optimizer | `adamw_8bit` |
 | LR | 2e-4, linear schedule |
 | Warmup | 64 steps (~5%) |
 | Weight decay | 0.001 |
 ## Evaluation
+### Held-out completion eval (n=428, full test split)
+| Metric | Base Gemma 4 E2B | This adapter | Delta |
+|---|---|---|---|
+| Completion NLL | 4.9327 | **4.7149** | **−0.218** |
+| Completion perplexity | 138.76 | **111.59** | **−27.16** |
+| Paired wins (LoRA assigned higher prob to reference) | — | **386 / 428 (90.2%)** | — |
+| Mean per-example NLL Δ | — | **0.327** nats | 95% bootstrap CI [0.301, 0.352] |
+| Median per-example NLL Δ | — | 0.285 nats | — |
+| Sign-test p-value | — | **9.54 × 10⁻⁷¹** | overwhelming |
+Surface coverage on test split: `check_in 144`, `phase_narration 147`, `reflection 137`.
+### Generation eval (n=8 sanity sample from held-out test)
+| Gate | Pass rate |
 |---|---|
 | JSON validity | 100% (8/8) |
 | Schema pass | 100% (8/8) |
 | Check-in turn sequence pass | 100% |
 | Mean tokens/sec (Python QLoRA path) | 10.1 |
+This was a small sanity-check sample. For a larger 60-example generation gate sweep on the rank-32 sibling, see [`Maelstrome/lora-wave-session-r32`](https://huggingface.co/Maelstrome/lora-wave-session-r32#evaluation).
+## Known quirks
+- **Phase narration needs a generation budget of `max_new_tokens ≥ 224`** (256 recommended). The six-line JSON output runs to ~207 tokens; with a lower cap the closing `]}` gets truncated and `JSON.parse` fails. `check_in` is fine at 96; `reflection` at 192.
 ## Dataset