mirror of
https://github.com/khodges42/nightShift.git
synced 2026-06-14 10:08:37 +00:00
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# Tutorial 01: Building A Small Imageboard With Real Local Models
|
|
|
|
This tutorial starts after the quickstart. The quickstart uses fake command agents so you can verify the pipeline deterministically. Here, you will use a named NightShift template and let a local model build the target application.
|
|
|
|
The target is a compact 4chan-style imageboard: boards, threads, replies, images, tripcodes, sessions, reports, and moderation. That is larger than a toy parser, but it is a better first real-model target because failures are ordinary web-app failures: routes, schema, file handling, tests, and model helpers.
|
|
|
|
## What The Template Creates
|
|
|
|
Run this from a disposable parent directory:
|
|
|
|
```bash
|
|
nightshift init --template tutorial-imageboard --root nightshift-imageboard
|
|
cd nightshift-imageboard
|
|
```
|
|
|
|
The template creates:
|
|
|
|
```text
|
|
nightshift.yaml
|
|
.nightshift/
|
|
agents/
|
|
planner.md
|
|
implementer.md
|
|
reviewer.md
|
|
tasks.md
|
|
src/
|
|
imageboard/
|
|
tests/
|
|
templates/
|
|
static/
|
|
uploads/
|
|
thumbs/
|
|
```
|
|
|
|
NightShift control files live in `.nightshift/`. Application source lives under `src/`, tests under `tests/`, HTML templates under `templates/`, and image/static files under `static/`.
|
|
|
|
The template does not create the Flask app, schema, models, or tests. That is intentional: `TASK-001` asks the agent to create the initial application slice. This is a better exercise of NightShift than pre-building the app and asking for a small patch.
|
|
|
|
## Prerequisites
|
|
|
|
Install NightShift from this repository:
|
|
|
|
```bash
|
|
python -m pip install -e .
|
|
```
|
|
|
|
Install target project dependencies:
|
|
|
|
```bash
|
|
python -m pip install flask pillow pytest flask_sqlalchemy
|
|
```
|
|
|
|
Install and start Ollama, then make sure the model is available:
|
|
|
|
```bash
|
|
ollama pull qwen2.5-coder:14b
|
|
ollama list
|
|
```
|
|
|
|
NightShift uses Ollama's local HTTP API, normally at `http://localhost:11434`.
|
|
|
|
## Task Plan
|
|
|
|
The template writes this task sequence to `.nightshift/tasks.md`.
|
|
|
|
1. Board and thread foundation
|
|
Implement the initial data model, SQLite schema, model helpers, `/board/<name>` and `/thread/<id>` routes, and tests.
|
|
|
|
2. Image upload and thumbnails
|
|
Add image attachments, metadata, upload storage under `static/uploads`, and thumbnails under `static/thumbs`.
|
|
|
|
3. Bump ordering and reply counts
|
|
Sort board threads by most recent reply and maintain reply counters.
|
|
|
|
4. Tripcodes and session cookies
|
|
Add anonymous names, optional tripcodes, and lightweight poster identity.
|
|
|
|
5. Moderation and report queue
|
|
Add reporting, report queue, dismiss actions, and post hiding.
|
|
|
|
Run only `TASK-001` first. Do not ask the model to implement uploads, tripcodes, or moderation until the previous tasks pass.
|
|
|
|
## Validate And Run
|
|
|
|
Validate the project:
|
|
|
|
```bash
|
|
nightshift validate
|
|
```
|
|
|
|
Run the first task:
|
|
|
|
```bash
|
|
nightshift run --task TASK-001
|
|
```
|
|
|
|
Start the dashboard:
|
|
|
|
```bash
|
|
nightshift web --host 127.0.0.1 --port 8765
|
|
```
|
|
|
|
Open `http://127.0.0.1:8765/`.
|
|
|
|
## What To Inspect
|
|
|
|
Useful artifacts:
|
|
|
|
```text
|
|
.nightshift/runs/<run-id>/devlog.md
|
|
.nightshift/runs/<run-id>/run.log
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/plan.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/context-pack.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/proposed.patch
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/test-output.txt
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/final-notes.md
|
|
```
|
|
|
|
The dashboard surfaces `devlog.md`, run status, logs, and links to finer-grained artifacts.
|
|
|
|
## Scope Note
|
|
|
|
This project is still not tiny. The advantage over a language interpreter is that the model works in familiar web-app territory and failures are easier to inspect. If `TASK-001` fails, read `devlog.md`, `test-output.txt`, and the implementer output before increasing retries or changing prompts.
|