README.md

---
title: Step-Zero
emoji: 🧭
colorFrom: gray
colorTo: green
sdk: docker
app_port: 7860
---

# Step-Zero

Step-Zero is a local-first hackathon demo for a "Cognitive Pacemaker": it shows only one next action at a time, lets the user mark it done or too hard, and trips a circuit breaker when friction stays too high. 

It leverages a custom dual-model architecture:
1. **Nemotron-Mini-4B-Instruct (Fine-Tuned)**: SFT fine-tuned specifically on daily goal breakdown datasets to produce extremely strict 8-word physical atomic actions without "assistant" conversational filler.
2. **MiniCPM-3-4B**: Acts as a robust fallback and history-aware router for rejected step breakdown and stylistic rewriting (Encouraging vs Calm tones).

## Hugging Face Assets
The resulting fine-tuned model and synthetic dataset from this project have been published to Hugging Face:
- **Model:** [tc043/step-zero-nemotron](https://huggingface.co/tc043/step-zero-nemotron)
- **Dataset:** [tc043/step-zero-dataset](https://huggingface.co/datasets/tc043/step-zero-dataset)

## Quick Start (Mock Mode)

```bash
python -m pip install -r requirements.txt
python app.py
```

Open `http://localhost:7860`.

The app starts in mock mode by default if the GGUF models are not found, so the custom UI and Gradio event handlers work out-of-the-box.
Choose Direct, Calm, or Encouraging before starting a session.

## Full Local Model Mode (Production)

To run the full LLM backend, you can let the app automatically download the models from Hugging Face on startup (when running with `STEP_ZERO_MOCK=0`), or you can download them manually beforehand:

You can download them using a quick Python script (since `huggingface-hub` is installed):
```bash
mkdir -p models

# Download the fine-tuned Nemotron model
python3 -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='tc043/step-zero-nemotron', filename='step-zero-nemotron-finetuned.gguf', local_dir='models')"

# Download the MiniCPM fallback model (Q4_K_M recommended for 4GB VRAM)
python3 -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='mradermacher/MiniCPM3-4B-GGUF', filename='MiniCPM3-4B.Q4_K_M.gguf', local_dir='models')"

# Rename fallback model to match path config
mv models/MiniCPM3-4B.Q4_K_M.gguf models/minicpm-3-4b.gguf
```

Then run:

```bash
STEP_ZERO_MOCK=0 \
NEMOTRON_MODEL_PATH=./models/step-zero-nemotron-finetuned.gguf \
MINICPM_MODEL_PATH=./models/minicpm-3-4b.gguf \
python app.py
```

> **Note on "Sharing is Caring" Badge:** If you wish to use the "Push to Hub" button to export your trace to Hugging Face, ensure you have exported your `HF_TOKEN` environment variable before running the app.

## Modal Fine-Tuning Pipeline

If you want to reproduce the Nemotron fine-tuning run:

1. Generate the synthetic dataset:
```bash
python generate_dataset.py
```
2. Authenticate and launch the Modal training job:
```bash
modal setup
modal run modal_train.py
```

`modal_train.py` handles the Unsloth LoRA SFT training on `verbs.jsonl` and merges the weights into a single GGUF artifact on Modal volumes.

## System Architecture Fixes
During development, we successfully mitigated several core "Small LLM Alignment Taxes":
* **The "Paragraph" Tax:** MiniCPM stylistic rewrites are strictly constrained to exactly one sentence under 12 words via robust system prompting.
* **The "Cognitive Planning" Bug:** Fallback breakdowns explicitly ban cognitive verbs (think, plan, remember) to force strictly physical next steps.
* **The Syntactic Rut & Repetition Loops:** Implemented a short-memory sliding window (`history[-3:]`) and a semantic word overlap check (>70%) that detects repeated semantic tasks and bounces them to the fallback model to generate a fresh step.