README.md

metadata

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
• Dataset: tc043/step-zero-dataset

Quick Start (Mock Mode)

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):

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:

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:

python generate_dataset.py

2. Authenticate and launch the Modal training job:

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.