nightshift/examples/tutorial/03-pastebin/README.md

Tutorial 03: Pastebin With Model Fallback And Telemetry

This tutorial uses the tutorial-pastebin template: a small Flask snippet-hosting service designed for deterministic NightShift orchestration tests.

It is intentionally simpler than the imageboard tutorial. There are no uploads, thumbnails, sessions, or moderation queues. The work is ordinary web-app behavior: snippet creation, viewing, listing, filtering, expiration handling, and simple HTML forms.

What The Template Creates

Run this from a disposable parent directory:

nightshift init --template tutorial-pastebin --root nightshift-pastebin
cd nightshift-pastebin

For an isolated local integration run, use the integration sandbox command from the NightShift repository root:

python -m nightshift.cli integ-run --template tutorial-pastebin

To create the sandbox and set up the Python project immediately:

python -m nightshift.cli integ-run --template tutorial-pastebin --setup

Then set up the generated Python project:

python -m nightshift.cli integ-setup --project integ_runs/<timestamp>/project

integ-setup cannot activate the venv for your current shell. In PowerShell, activate it manually if you want plain python and nightshift to use the integration venv:

integ_runs\<timestamp>\.venv\Scripts\Activate.ps1

The template creates:

nightshift.yaml
.nightshift/
  agents/
    planner.md
    test-writer.md
    implementer.md
    debugger.md
    reviewer.md
  tasks.md
src/
  pastebin_app/
templates/
tests/
pyproject.toml
README.md

The template includes a tiny Flask create_app(database_path=None) scaffold and fixed TASK-001 tests. The default tutorial pipeline asks the implementation agent to make those deterministic tests pass before review.

Prerequisites

Install NightShift from this repository:

python -m pip install -e .

Install target dependencies:

python -m pip install -e . pytest flask

Install and start Ollama, then pull the fallback models you want available:

ollama pull qwen2.5-coder:14b
ollama pull carstenuhlig/omnicoder-9b
ollama pull deepseek-coder-v2:16b
ollama list

NightShift uses Ollama's local HTTP API, normally at http://localhost:11434.

Model Fallback

The implementation stage uses this fallback order:

1. qwen2.5-coder:14b
2. carstenuhlig/omnicoder-9b
3. deepseek-coder-v2:16b

NightShift records which agent/model handled each stage in telemetry-summary.md.

TDD Pipeline

The task pipeline runs in this shape:

plan -> semantic_context -> context -> implement -> pytest -> review

The default template uses fixed task tests instead of model-generated tests. This keeps the tutorial focused on implementation and NightShift orchestration instead of letting a test-writing model invent an incompatible architecture.

Task Plan

The template writes the full task list to .nightshift/tasks.md. A copy is included here as tasks.md.

1. Snippet creation and viewing
2. Snippet metadata fields
3. Snippet listing and filtering
4. Expiration handling
5. HTML forms and templates

Run one task first:

python -m nightshift.cli validate
python -m nightshift.cli run --task TASK-001
python -m nightshift.cli what-happened

Then inspect:

.nightshift/runs/<run-id>/devlog.md
.nightshift/runs/<run-id>/telemetry-summary.md
.nightshift/runs/<run-id>/tasks/TASK-001/semantic-context.md
.nightshift/runs/<run-id>/tasks/TASK-001/telemetry-summary.md
.nightshift/runs/<run-id>/tasks/TASK-001/artifact-index.md
.nightshift/runs/<run-id>/tasks/TASK-001/test-output.txt

Pipeline Reference

A copy of the template pipeline is included here as nightshift.yaml. The canonical runnable template lives under nightshift/project_templates/tutorial-pastebin/.