DEV Community: Riley Zhang

Weekend Build Log: A Human Gate Between the Model and Your Database

Riley Zhang — Tue, 27 Oct 2026 12:38:33 +0000

Your side project watches a support inbox. One Friday night the model decides a paying customer should be downgraded. The write lands. Nobody approved it, and the logs do not say which prompt caused it.

That is the failure mode this build targets. Not model quality. Not latency. Unbounded write access from a component that cannot explain itself.

Below is the smallest version that works: a pending-actions table, a proposal worker, an approval CLI, and an idempotent applier. You can finish it in a weekend. The code is a runnable artifact, but it was not executed against a live endpoint while writing this post. Treat the test plan as your first job, not mine.

1. The scope cut comes first

You will be tempted to build a dashboard, roles, and Slack approvals. Do not. Every one of those is a second weekend, and none of them stop a bad write.

The gate needs three properties only. Proposals are stored, not executed. A human flips the status. The applier refuses to run twice.

Here is the cut I would make, written as a table you can argue with:

Option	Effort	Stops a bad write	Skip it when
Human gate + audit row	1 weekend	Yes, for allowlisted actions	Nothing — start here
Dry-run diff in the CLI	+2 hours	Makes review fast	Payloads are not human-readable
Full dashboard	+2 weekends	Nothing extra	You have more than 3 reviewers
Auto-approve below a threshold	+1 weekend	Weakens the whole point	You have real eval coverage

Pick the first two rows. Everything else is a later problem.

2. Step one: a table that remembers intent

SQLite is enough for a side project. The key design choice is the primary key: it is a hash of the action, not a random UUID.

That hash is what makes replay harmless.

CREATE TABLE IF NOT EXISTS proposals (
  id           TEXT PRIMARY KEY,          -- sha256(source_id, action_type, payload)
  source_id    TEXT NOT NULL,             -- the ticket, email, or job this came from
  action_type  TEXT NOT NULL,             -- must be on the allowlist
  payload      TEXT NOT NULL,             -- canonical JSON
  status       TEXT NOT NULL DEFAULT 'pending',
  created_at   TEXT NOT NULL,
  decided_by   TEXT,
  decided_at   TEXT
);

CREATE INDEX IF NOT EXISTS idx_pending
  ON proposals(status, created_at);

Status values are fixed: pending, approved, rejected, applied, failed. Add a sixth only if you can name the state transition it represents.

3. Step two: the proposal worker never writes to your app tables

This worker reads a source record, asks the model for one action, validates it, and inserts a row. It has no other power. Enforce that with a database user that cannot touch the app tables.

Use an allowlist, not a blocklist. A model that invents delete_account fails validation instead of succeeding quietly.

import hashlib, json, os, sqlite3
from datetime import datetime, timezone

ALLOWED = {"set_plan_tier", "add_tag"}

DB = os.environ.get("APP_DB", "app.db")


def canonical(payload: dict) -> str:
    return json.dumps(payload, sort_keys=True, separators=(",", ":"))


def proposal_id(source_id: str, action_type: str, payload_json: str) -> str:
    raw = f"{source_id}|{action_type}|{payload_json}".encode()
    return hashlib.sha256(raw).hexdigest()[:32]


def record(source_id: str, action_type: str, payload: dict) -> str | None:
    if action_type not in ALLOWED:
        raise ValueError(f"blocked action_type: {action_type}")
    payload_json = canonical(payload)
    pid = proposal_id(source_id, action_type, payload_json)
    now = datetime.now(timezone.utc).isoformat()
    with sqlite3.connect(DB) as con:
        cur = con.execute(
            "INSERT OR IGNORE INTO proposals "
            "(id, source_id, action_type, payload, created_at) "
            "VALUES (?, ?, ?, ?, ?)",
            (pid, source_id, action_type, payload_json, now),
        )
        return pid if cur.rowcount == 1 else None

INSERT OR IGNORE plus the hash means a retried job is a no-op. That single line saves you from duplicate approvals later.

4. Step three: parse strictly, fail loudly

The model returns JSON. Sometimes it returns JSON with a friendly sentence attached. Reject it and log the raw text; do not regex-repair it.

def parse_action(raw: str) -> tuple[str, dict]:
    doc = json.loads(raw)                      # raises, by design
    action_type = doc["action_type"]
    payload = doc["payload"]
    if not isinstance(payload, dict):
        raise ValueError("payload must be an object")
    if action_type == "set_plan_tier":
        if payload.get("tier") not in {"free", "pro", "team"}:
            raise ValueError("unknown tier")
        if not isinstance(payload.get("account_id"), str):
            raise ValueError("account_id must be a string")
    return action_type, payload

One repair attempt is reasonable. Two is a sign your prompt is wrong. Zero is better than three.

5. Step four: the approval CLI is the product

Reviewers should not open a database browser. Give them four commands and no more.

python gate.py list --limit 20
python gate.py show 4f2a9c1e
python gate.py approve 4f2a9c1e --as riley
python gate.py reject 4f2a9c1e --as riley --note "wrong account"

show prints the source record next to the proposed payload. A reviewer who cannot see the input cannot judge the output. Keep both in the same screen.

The approve path must be a conditional update, not a read-then-write.

def approve(pid: str, who: str) -> bool:
    now = datetime.now(timezone.utc).isoformat()
    with sqlite3.connect(DB) as con:
        cur = con.execute(
            "UPDATE proposals SET status='approved', decided_by=?, decided_at=? "
            "WHERE id=? AND status='pending'",
            (who, now, pid),
        )
        return cur.rowcount == 1

Two reviewers clicking at once: one wins, one gets False. That is the correct outcome.

6. Step five: the applier is boring on purpose

Write the applier as a separate process. It claims approved rows, applies them in a transaction, and marks them applied. If the app fails, it marks them failed and leaves the payload intact for inspection.

BEGIN IMMEDIATE;
UPDATE proposals
   SET status = 'applied'
 WHERE id = :pid AND status = 'approved';
-- if changes() = 0, roll back: someone else got here first
COMMIT;

Apply and mark inside the same transaction. An external API call in the middle breaks that guarantee, so put the external call after the commit and record its result separately.

7. Where the free tier actually fits

The proposal worker is a background job with bursty load. It idles most of the day and processes a few dozen records at night. That shape is a good fit for a free tier, because a fixed allowance is easy to reason about.

For this build I would point the worker at MonkeyCode's free model access and run the scheduler on its free server option. The outreach brief I received quotes a 10M-token allowance and a free server tier; check the current terms yourself before you depend on either. Point three environment variables at it and the rest of the code does not change:

MODEL_BASE_URL=...   # from the provider's docs
MODEL_API_KEY=...    # keep it out of git
MODEL_NAME=...       # whatever the free tier currently serves

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

One practical rule: log tokens per proposal, not per day. The daily number hides the single record that cost 40x the median. You want that outlier visible the same night.

8. The test plan you run before trusting it

Five cases. Each is a few lines of pytest and none need a network call.

Duplicate insert. Call record() twice with the same input. Assert one row and one None.
Blocked action. Pass delete_account. Assert ValueError and zero rows.
Malformed JSON. Feed Sure! Here you go: {...}. Assert json.JSONDecodeError and no insert.
Double approve. Approve the same id twice. Assert True then False.
Rejected is terminal. Try to apply a rejected row. Assert zero status change.

If case five fails, your conditional update is wrong. Fix it before you deploy.

9. What this build does not do

The gate does not make the model correct. It only makes wrong output cheap to catch. A reviewer who rubber-stamps twenty rows at midnight gives you no protection at all.

It also does not rate-limit the source. If your inbox produces 5,000 records a day, a human queue is the wrong architecture and you need sampling plus eval coverage instead. And it does not handle regulated data on its own; the payload column stores plain text, so redact before insert if that matters to you.

Skip this pattern if you need sub-second writes, or if no human can plausibly review the volume. It is for side projects where a wrong write costs more than a delayed one.

10. Ship it small

The whole thing is two tables, four CLI commands, and about 150 lines of Python. That is the point. A gate you finish beats a platform you abandon in week three.

Start with one allowlisted action. Add the second only after the first has survived a week of real review. If you want a free place to run the worker while you decide, the free tier mentioned above is one reasonable option, and a cron job on any small box is another.

Ship a Failover Lane for AI Calls in One Weekend (And Skip the Rest)

Riley Zhang — Mon, 26 Oct 2026 11:20:09 +0000

Saturday, 07:40. My side project's "summarize thread" button returned a 429.

My retry loop made it worse. Every retry burned the same quota I was already out of.

By 08:30 I had a decision to make. Build a full AI gateway, or ship one honest thing by Sunday night.

I shipped the one honest thing. A failover lane with a circuit breaker, a classifier for retryable errors, and five tests that run against fake upstreams. No dashboard. No router config language. No Kubernetes.

Here is the build log: the scope I kept, the code, the tests, and everything I deliberately skipped.

Step 1: Cut the scope before you write code

A weekend dies from ambition, not from bugs. So I wrote the cut list first.

Kept: one breaker per provider, retryable-error classification, a half-open probe, and a test harness. Skipped: distributed state, metrics export, prompt versioning, and cost accounting.

The skipped list is not a roadmap. It is a list of problems I do not have yet. One process, one API key, one user: that is my whole deployment.

Step 2: Decide what counts as a failure

This is the part most side projects get wrong. A 400 from a bad prompt is not an outage. Failing over on it just hides your bug behind another provider.

So classify first. Only retryable failures should move traffic.

# lanes.py
RETRYABLE_STATUS = {408, 409, 425, 429, 500, 502, 503, 504}


def is_retryable(exc: Exception) -> bool:
    status = getattr(exc, "status_code", None)
    if status is None:
        # Network errors, timeouts, connection resets.
        return isinstance(exc, (TimeoutError, ConnectionError))
    return status in RETRYABLE_STATUS

401 and 403 are configuration bugs. 400 and 422 are prompt bugs. Send those to your logs, not to the fallback lane.

Step 3: Write the breaker (about 40 lines)

The breaker has three states. Closed means primary. Open means fallback only. Half-open means one probe gets through.

# breaker.py
import time
from lanes import is_retryable


class Breaker:
    def __init__(self, fail_threshold=3, cooldown_s=20.0):
        self.fail_threshold = fail_threshold
        self.cooldown_s = cooldown_s
        self.fails = 0
        self.opened_at = None

    def state(self):
        if self.opened_at is None:
            return "closed"
        if time.monotonic() - self.opened_at >= self.cooldown_s:
            return "half-open"
        return "open"

    def _trip(self):
        self.opened_at = time.monotonic()
        self.fails = 0

    def _reset(self):
        self.opened_at = None
        self.fails = 0

    def call(self, primary, fallback):
        state = self.state()
        if state == "open":
            return fallback(), "fallback_open"

        if state == "half-open":
            try:
                out = primary()
            except Exception as exc:
                if not is_retryable(exc):
                    raise
                self._trip()
                return fallback(), "fallback_probe_failed"
            self._reset()
            return out, "primary_recovered"

        try:
            out = primary()
        except Exception as exc:
            if not is_retryable(exc):
                raise
            self.fails += 1
            if self.fails >= self.fail_threshold:
                self._trip()
            return fallback(), "fallback_error"

        self._reset()
        return out, "primary"

The second return value is the only observability I allowed myself. It tells you which lane answered, and that is enough for a weekend.

Step 4: Test it with fake upstreams, not real ones

You cannot debug a breaker against a flaky provider. You can debug it against a fake that fails on command.

Five scenarios cover almost everything I care about:

Primary succeeds, breaker stays closed.
Primary raises 429 three times, breaker opens, fallback answers.
Primary raises 400, no failover, error surfaces to caller.
Breaker is open, primary is never called at all.
Cooldown elapses, probe succeeds, breaker closes again.

# test_breaker.py
import pytest
from breaker import Breaker


class Boom(Exception):
    def __init__(self, status_code):
        self.status_code = status_code


def primary_raises(status):
    def fn():
        raise Boom(status)
    return fn


def test_non_retryable_does_not_failover():
    b = Breaker(fail_threshold=1)
    with pytest.raises(Boom):
        b.call(primary_raises(400), lambda: "fallback")
    assert b.state() == "closed"


def test_opens_after_threshold():
    b = Breaker(fail_threshold=3)
    for _ in range(3):
        out, lane = b.call(primary_raises(429), lambda: "fallback")
        assert out == "fallback"
    assert b.state() == "open"


def test_open_skips_primary():
    b = Breaker(fail_threshold=1)
    b.call(primary_raises(503), lambda: "fallback")
    calls = []

    def spy():
        calls.append(1)
        return "primary"

    out, lane = b.call(spy, lambda: "fallback")
    assert lane == "fallback_open"
    assert calls == []

Scenario five needs a short cooldown. Set cooldown_s=0.05 and the half-open test runs in milliseconds.

Run it: pytest -q test_breaker.py. Five green tests, one afternoon, no API key.

Step 5: Pick a lane you can actually afford to leave on

A fallback lane only helps if it is cheap and available during someone else's outage. That rules out a second premium key for a hobby project.

This is where MonkeyCode fit my build. The operator states that the project offers free model access and a free server option, and that it is open source; I used it as the fallback lane and as the place to run the cron job. Treat those as operator-supplied claims, not as measured results. As of this writing the operator also states a free token allowance in the millions, so check the current number on the project's own pricing page before you size anything around it. Allowances change.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The important design point is not the vendor. It is that your fallback must be a different failure domain from your primary. Two keys in the same account are one outage, not two.

What I skipped, and why it was fine

I skipped distributed state. The breaker lives in one process, so a deploy resets it. For a side project that runs one worker, a reset is a non-event.

I skipped per-endpoint breakers. My app has one model call path. Adding granularity before I had a second path would have been speculative abstraction.

I skipped metrics. The lane string already goes into my request log, and I read that log twice a week.

I also skipped prompt-level retries. If the model returns a wrong answer, a breaker will not save you. That is an eval problem, and it is next weekend's problem.

Should you build this?

Your situation	Build it?	Reason
One side project, one model call path	Yes	40 lines beats a gateway
Multiple processes behind a load balancer	Not yet	In-memory state is per-process
Fallback model quality is untested	Not yet	Fast bad answers are still bad
Hard data-residency requirements	Probably not	Picking a lane is a compliance decision
You already have retries with backoff	Maybe	Check what your retries do on 429

Limitations, stated plainly

Free lanes have their own rate limits. A breaker does not buy you capacity.

Half-open sends one probe. Under real concurrency you may want a token bucket there instead.

And an in-memory breaker forgets everything on restart. If you need it to survive deploys, you need shared state, and that is a different weekend.

Who should not use this

Skip this approach if your fallback model has never passed your own eval set. Skip it if a regulator, not an engineer, decides where your data goes. Skip it if you are already at high request volume, because a single-process breaker will flap under load.

If you want to try the lane I used, start with a throwaway key and the five tests above. Get them green before you point real traffic at anything.

Sunday, 23:10. The button works, the tests pass, and the only new file is 40 lines long.

The scope cut is what shipped the feature. Not the model.

Weekend Build Log: Redact the Log Before You Send It

Riley Zhang — Tue, 20 Oct 2026 09:23:41 +0000

Friday, 11:40pm. A staging deploy fails and the CI log runs to 412 lines. You copy the whole thing into a chat window to ask what broke. Halfway through the paste you notice a bearer token and an internal hostname.

That pause is the entire project. This weekend's build is a small log-triage tool with one hard rule. Redact first, ask a model second, validate the answer third.

I kept the scope brutal on purpose. If a side project cannot ship in a weekend, it usually ships never.

The scope cut, as a table

Every weekend project dies from a feature list, not from a hard bug. So the first artifact is the cut itself.

Idea	Kept?	Why
Regex redaction gate	Yes	It is the only part that protects you
One model call per log	Yes	Simple to reason about, simple to test
Strict JSON output check	Yes	Bad output must fail loudly
Offline golden-file test	Yes	You need to run this without a key
Web UI	No	A CLI plus cron is enough
Database	No	Flat files on disk are fine here
Retry and queue logic	No	One retry, then write to `failed/`
Multi-model routing	No	One endpoint, one model per run
User accounts and auth	No	Nothing ever calls it manually

Read the right column twice. Every "No" is a bug you will not have to fix on Sunday night.

Step 1: Write the redaction gate first

The gate is the product. Everything else is plumbing around it.

# redact.py
import re

PATTERNS = [
    ("aws_key",   re.compile(r"AKIA[0-9A-Z]{16}")),
    ("gh_token",  re.compile(r"gh[pousr]_[A-Za-z0-9]{20,}")),
    ("bearer",    re.compile(r"(?i)bearer\s+[A-Za-z0-9._\-]{16,}")),
    ("jwt",       re.compile(r"eyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}")),
    ("email",     re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")),
    ("ipv4",      re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
    ("long_hex",  re.compile(r"\b[0-9a-fA-F]{32,}\b")),
]

def redact(text: str) -> tuple[str, dict[str, int]]:
    counts: dict[str, int] = {}
    for name, rx in PATTERNS:
        text, n = rx.subn(f"<{name.upper()}>", text)
        if n:
            counts[name] = n
    return text, counts

def assert_clean(text: str) -> None:
    # Second pass must find nothing. Catches overlapping patterns.
    _, residual = redact(text)
    if residual:
        raise ValueError(f"redaction leaked: {residual}")

That second pass is the part people skip. Patterns overlap, and order matters.

Run the gate twice on the output. If the second run still matches, you have a bug, not a private log.

Step 2: Trim before you spend anything

A 400-line log is mostly noise. Keep the head, the tail, and every error-ish line.

# trim.py
import re

NOISE = re.compile(r"(?i)\b(error|exception|fail|fatal|timeout|denied|refused)\b")

def trim(log: str, head: int = 40, tail: int = 200) -> str:
    lines = log.splitlines()
    keep = set(range(min(head, len(lines))))
    keep |= set(range(max(0, len(lines) - tail), len(lines)))
    keep |= {i for i, l in enumerate(lines) if NOISE.search(l)}
    return "\n".join(lines[i] for i in sorted(keep))

Order matters here too. Trim first, then redact, then trim again if needed.

Trimming exposes one trade-off. You can cut the line that explains the failure.

So keep a 10-line window around every match. Do not keep only the matching line.

Step 3: One call, one strict contract

Ask for a fixed shape and refuse anything else. No prose parsing, no "best effort".

# ask.py
import json, os, urllib.request

PROMPT = """You triage CI logs. Return JSON only.
Fields: cause (string, <=300 chars), next_step (string, <=300 chars),
confidence (low|medium|high), quoted_evidence (0-3 strings copied
verbatim from the log). Do not guess. If unclear, use confidence=low."""

def call_model(log: str) -> dict:
    body = json.dumps({
        "model": os.environ["TRIAGE_MODEL"],
        "messages": [
            {"role": "system", "content": PROMPT},
            {"role": "user", "content": log},
        ],
        "temperature": 0,
    }).encode()
    req = urllib.request.Request(
        os.environ["TRIAGE_BASE_URL"].rstrip("/") + "/chat/completions",
        data=body,
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer " + os.environ["TRIAGE_API_KEY"],
        },
    )
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())["choices"][0]["message"]["content"]

Model names change constantly, so never hardcode one. Read it from the environment.

Now validate the shape with a small hand-rolled check. Skip the heavy dependency.

# validate.py
ALLOWED = {"low", "medium", "high"}
REQUIRED = {"cause", "next_step", "confidence"}

def validate(obj: dict) -> dict:
    if not REQUIRED <= obj.keys():
        raise ValueError(f"missing: {REQUIRED - obj.keys()}")
    if obj["confidence"] not in ALLOWED:
        raise ValueError("bad confidence")
    for k in ("cause", "next_step"):
        if not isinstance(obj[k], str) or not obj[k].strip():
            raise ValueError(f"empty {k}")
        if len(obj[k]) > 300:
            raise ValueError(f"too long: {k}")
    ev = obj.get("quoted_evidence", [])
    if not isinstance(ev, list) or len(ev) > 3:
        raise ValueError("bad evidence")
    return obj

Any failure writes the raw output to failed/. You review those by hand on Monday.

Step 4: The test that needs no API key

This is the artifact that makes the weekend worth it. Record one real response, then test against it forever.

# test_pipeline.py
import json, pytest
from validate import validate
from redact import redact, assert_clean

def test_token_is_gone():
    out, counts = redact("auth: Bearer abcdef1234567890XYZ")
    assert "abcdef1234567890XYZ" not in out
    assert counts["bearer"] == 1

def test_second_pass_is_clean():
    out, _ = redact("host 10.0.3.41 token AKIAABCDEFGHIJKLMNOP")
    assert_clean(out)

def test_rejects_missing_field():
    with pytest.raises(ValueError):
        validate({"cause": "x", "confidence": "low"})

def test_rejects_bad_confidence():
    with pytest.raises(ValueError):
        validate({"cause": "x", "next_step": "y", "confidence": "sure"})

def test_fixture_still_valid():
    with open("fixtures/response.json") as f:
        validate(json.load(f))

Run pytest -q with the network off. If it passes, the contract holds.

The failing cases matter more than the passing one. Every bad model output becomes a permanent test.

Step 5: Put it on a small box and walk away

This tool has no users waiting. A cron entry is the correct deployment.

ssh you@your-box
git clone https://example.com/your/triage.git && cd triage
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
mkdir -p inbox out failed fixtures
export TRIAGE_BASE_URL=... TRIAGE_MODEL=... TRIAGE_API_KEY=...

*/30 * * * * cd /srv/triage && .venv/bin/python run.py >> run.log 2>&1

run.py is fifteen lines. Read a file from inbox/, redact, trim, call, validate, write JSON to out/.

Add a flock around it. Cron does not care that the last run is still going.

*/30 * * * * flock -n /tmp/triage.lock cd /srv/triage && .venv/bin/python run.py >> run.log 2>&1

That one flag prevents the only outage this design can cause.

Where the free tier actually fits

Here is the honest split. The gate, the trimmer, and the tests need nothing from anyone. They run offline and they are the real work.

MonkeyCode is relevant for the two parts you would otherwise pay for. It offers free model access for the single call in Step 3, plus a free server option for the box in Step 5. As of this writing the operator advertises a 10,000,000-token allotment on the free tier. Treat that number as time-sensitive, not as a spec.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why this pairing suits a weekend build: one call per log keeps usage boring and predictable. A log triage job on a small box is bursty and idle most of the day. You do not need a large instance, and you do not need a fat token budget.

Verify the current free-tier terms on the project page before you plan around them. Quotas, model lists, and server limits change, and this post will not.

What I deliberately skipped

Skipping is a design decision, so write it down. Otherwise you will add it back at 1am.

No web UI. The output is a JSON file you read in your editor.
No database. Files are easier to grep and easier to delete.
No retry ladder. One retry, then quarantine to failed/.
No streaming. The whole point is a small, bounded answer.
No auth layer. Nothing calls this over HTTP.
No prompt tuning loop. One prompt, versioned in git, changed only with a test.

That last skip is the hardest one. Prompt fiddling feels like progress and produces nothing you can verify.

Limits you should accept up front

The regex gate is not a guarantee. It catches shapes it knows and misses everything else.

A secret in an unusual format will pass through. So will a token split across two log lines.

Add a deny-list of your own hostnames and project names. That is the highest-value ten minutes you will spend.

Free tiers are best-effort by nature. Assume the box can restart and the quota can change.

Your cron job must survive an empty inbox/ and a 500 from the provider. Both are normal.

Who should not use this

Do not build this if any of the following is true for you.

You handle regulated data, where a regex gate is not an acceptable control.
You need per-user access control or an audit trail per request.
You process thousands of logs a day, where a cron loop and flat files collapse.
You need a guaranteed uptime number from your log triage tool.

In those cases, the redaction pattern is still useful. The weekend architecture is not.

Sunday night check

The demo is boring on purpose. Drop a log into inbox/, wait thirty minutes, read a three-field JSON file.

If the fields are wrong, you have a fixture to add. If the file is missing, read failed/.

That is the whole loop. Redact, trim, ask once, validate, quarantine the misses.

If you want to try it this weekend, the free model access and free server option cover the two paid parts. Everything that protects you runs locally, with no key at all.

Weekend Build Log: A Release-Note Classifier With Exactly One Model Call per Batch

Riley Zhang — Mon, 19 Oct 2026 08:06:32 +0000

It is Friday, 11 p.m. Your open-source repo has 40 untagged releases.

You want a board that says breaking, feature, or fix. You do not want auth, dashboards, or a vector store.

This is a build log for the smallest useful version. One SQLite table. One batched model call. One HTTP endpoint. No UI.

What the demo actually does

Reads release notes from a local JSON file.
Sends 20 entries per request, each with a stable id.
Rejects any response whose ids do not match the input.
Upserts labels into SQLite with a confidence score.
Serves GET /labels/{tag} as plain JSON.

That is the entire scope. Ship it, use it, then stop.

Step 0: Cut scope before you write a line

Most weekend projects die in the planning doc. Write the cuts down first.

| Tempting | Shipped | Why |
| --- | --- |
| Web dashboard | JSON endpoint | You can read JSON in a terminal |
| Auth | None | Local and read-only |
| Postgres | SQLite file | One file, zero services |
| Streaming | Batched call | 40 rows is not a stream |
| Fine-tuning | Prompt + schema | No labeled data yet |
| Retry forever | Two retries | Failures should be visible |

The table is the artifact. Everything below implements this table.

Step 1: One table, one strict schema

Start with the store. Labels are append-only per release id.

CREATE TABLE IF NOT EXISTS labels (
  release_id TEXT PRIMARY KEY,
  tag        TEXT NOT NULL,
  kind       TEXT NOT NULL,
  confidence REAL NOT NULL,
  model      TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

Now define the response contract. Make it strict enough to fail loudly.

SCHEMA = {
    "type": "object",
    "properties": {
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {"type": "string"},
                    "kind": {"enum": ["breaking", "feature", "fix", "chore"]},
                    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
                },
                "required": ["id", "kind", "confidence"],
            },
        }
    },
    "required": ["items"],
}

Four labels are enough. Every extra label costs you agreement between runs.

Step 2: Batch the prompt with hard ids

Model output drifts when you ask for alignment by position. Give every row an id instead.

def build_prompt(batch):
    lines = [
        "Classify each release note. Return JSON only.",
        "Allowed kinds: breaking, feature, fix, chore.",
        "Copy the id exactly. Never invent ids.",
        "",
    ]
    for row in batch:
        lines.append(f"id={row['id']} :: {row['note'][:400]}")
    return "\n".join(lines)

Truncate the note body at 400 characters. Long changelogs add tokens, not accuracy.

Keep batches at 20. Smaller batches mean more calls; larger batches mean sloppier answers.

Step 3: Validate ids, not just JSON

Most tutorials stop at json.loads. That is where the bugs live.

def parse_items(raw, expected_ids):
    text = raw.strip()
    if text.startswith("```

"):
        text = text.split("

```")[1]
        text = text.split("\n", 1)[1] if "\n" in text else text
    data = json.loads(text)
    got = {item["id"] for item in data["items"]}
    if got != set(expected_ids):
        raise ValueError(f"id mismatch: {got ^ set(expected_ids)}")
    return data["items"]

Treat an id mismatch as a failed call. Retry once with the same prompt and a lower temperature.

If it fails twice, write the batch to dead_letter.json and move on. Silent partial results are worse than a gap.

Step 4: Test offline before you spend a token

Write a fake client. It returns canned JSON and costs nothing.

class FakeClient:
    def __init__(self, payload):
        self.payload = payload
        self.calls = 0

    def complete(self, prompt):
        self.calls += 1
        return self.payload


def test_batch_roundtrip(tmp_path):
    batch = [{"id": "r1", "note": "Drop Node 16 support"}]
    fake = FakeClient('{"items":[{"id":"r1","kind":"breaking","confidence":0.9}]}')
    items = parse_items(fake.complete(build_prompt(batch)), ["r1"])
    assert items[0]["kind"] == "breaking"
    assert fake.calls == 1

Add one more test with a wrong id. The test must raise, not patch over the gap.

Run it with pytest -q. Green offline means the schema, parsing, and retry path work.

Step 5: Put one endpoint on the free server

from fastapi import FastAPI
import sqlite3

app = FastAPI()

@app.get("/labels/{tag}")
def labels(tag: str):
    con = sqlite3.connect("labels.db")
    rows = con.execute(
        "SELECT release_id, kind, confidence FROM labels WHERE tag=? ORDER BY created_at DESC",
        (tag,),
    ).fetchall()
    return {"tag": tag, "items": [
        {"id": r[0], "kind": r[1], "confidence": r[2]} for r in rows
    ]}

Run uvicorn app:app --host 0.0.0.0 --port 8000. Hit it with curl localhost:8000/labels/v1.2.0.

A read-only endpoint has no auth surface. Keep it that way until someone else asks.

Where a free tier fits here

This project has two costs: model calls and hosting. Both are small, but both are recurring.

MonkeyCode offers free model access and a free server option. Those availability claims come from the operator, so verify the current allowance and terms on the product page before you plan around them.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The fit is narrow and honest. You get one place for the batched call and the tiny endpoint while you decide whether the project deserves a paid home. If your workload grows past a weekend, re-evaluate.

The offline test above matters more than the provider. It keeps your retry logic honest no matter which client you swap in later.

What this build skipped on purpose

No UI. Terminal JSON is enough for 40 rows.
No embeddings. Keyword matching finds duplicates fine at this size.
No scheduled refresh. Run the script by hand until it annoys you.
No multi-label output. One kind per release keeps the table queryable.
No prompt versioning. Add it when the second person edits the prompt.

Each skip is reversible. That is the point of a scope cut.

Limitations and who should skip this

Classification quality follows the model. Spot-check 10 rows before trusting the board.
Release notes written in mixed languages will drift. Add an explicit language instruction.
Free-tier limits can change. A monthly quota is not a capacity plan.
This is not for compliance reporting. Breaking-change detection needs human sign-off.

If your releases are already tagged by hand, skip this. If you need per-commit attribution, this is the wrong layer.

Also skip it if you cannot accept an occasional dead_letter.json row. Perfect recall is not on the menu.

The 90-minute checklist

Write the cuts table. Ten minutes.
Create the SQLite table and the schema constant.
Build the prompt with explicit ids and truncation.
Write parse_items with the id-set check.
Add the fake-client test and run pytest -q.
Wire the real client and label one batch of 20.
Serve one endpoint and curl it once.

Stop after step seven. The next feature is a different weekend.

If you want to try this shape, run the offline test first, then point the client at whichever free model access you already have and read its quota terms before you batch anything large.

Weekend Build Log: A Model-Swap Smoke Test You Can Run Before Monday

Riley Zhang — Sun, 18 Oct 2026 06:52:36 +0000

Friday night, your side project starts returning different answers. Same prompt, same input, new model version behind the endpoint. You find out on Sunday, when a friend tries the demo.

You do not need an eval platform to catch this. You need twelve fixtures, one script, and a red/green gate. Here is the build I would run this weekend, including the parts I would skip.

The scope cut

Three rules keep this to one evening.

Ship a CLI. No web UI, no database, no auth.
Score with string rules, not a second model.
Store every run as one JSON file you can diff in git.

Everything else is a later problem. The only output you need is a pass rate and an exit code.

Step 1: Write the fixtures you actually care about

Create cases.jsonl. Each line is one promise your project makes to a user.

{"id": "refund-policy", "prompt": "A customer asks for a refund 40 days after purchase. Answer in under 300 characters.", "must_contain": ["30 days"], "must_not_contain": ["guarantee", "always"], "max_chars": 300}
{"id": "json-shape", "prompt": "Return only JSON with keys title and tags for: 'weekly digest bot'. No prose.", "must_contain": ["title", "tags"], "must_not_contain": ["```

"], "max_chars": 400}
{"id": "empty-input", "prompt": "Summarize the following text: '' (empty). Reply with the single word EMPTY.", "must_contain": ["EMPTY"], "must_not_contain": [], "max_chars": 20}

Twelve is enough to start. Pick fixtures from three buckets.

Output shape: JSON keys, no code fences, length limits.
Business rules: numbers, dates, forbidden promises.
Degenerate input: empty strings, very long strings, non-English text.

If a fixture cannot fail, delete it. It is decoration.

Step 2: The runner, standard library only

No SDK. No dependency drift. This file runs anywhere Python 3.9+ exists.


python
# smoke.py
import json, os, sys, urllib.request

BASE = os.environ["MODEL_BASE_URL"].rstrip("/")
KEY = os.environ["MODEL_API_KEY"]
MODEL = os.environ["MODEL_NAME"]

def call(prompt: str) -> str:
    body = json.dumps({
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
        "temperature": 0,
    }).encode()
    req = urllib.request.Request(
        f"{BASE}/chat/completions",
        data=body,
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {KEY}"},
    )
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.load(r)["choices"][0]["message"]["content"]

The endpoint shape is the generic chat-completions one. Take the base URL, key, and model name from whichever provider you are testing. Never hardcode them in the repo.

Step 3: Score with rules, not vibes

Each case returns pass or fail. Nothing in between.


python
def check(case: dict, out: str) -> list[str]:
    fails = []
    for needle in case.get("must_contain", []):
        if needle not in out:
            fails.append(f"missing:{needle}")
    for needle in case.get("must_not_contain", []):
        if needle in out:
            fails.append(f"forbidden:{needle}")
    limit = case.get("max_chars")
    if limit and len(out) > limit:
        fails.append(f"too_long:{len(out)}>{limit}")
    return fails

This looks crude. It is crude. It also catches every silent regression I have hit: a broken JSON contract, a dropped disclaimer, a model that suddenly writes essays.

Step 4: Run it against two models and diff

The main loop writes a scorecard, then sets the exit code.


python
cases = [json.loads(line) for line in open("cases.jsonl", encoding="utf-8") if line.strip()]
rows = []
for case in cases:
    try:
        out = call(case["prompt"])
    except Exception as exc:
        rows.append({"id": case["id"], "ok": False, "fails": [f"error:{exc}"]})
        continue
    fails = check(case, out)
    rows.append({"id": case["id"], "ok": not fails, "fails": fails, "chars": len(out)})

passed = sum(r["ok"] for r in rows)
scorecard = {"model": MODEL, "passed": passed, "total": len(rows), "rows": rows}
json.dump(scorecard, open("scorecard.json", "w"), indent=2)
print(f"{passed}/{len(rows)} passed on {MODEL}")
sys.exit(0 if passed == len(rows) else 1)

Run it twice into separate files, then diff:


bash
MODEL_NAME=model-a python smoke.py && mv scorecard.json scorecard.a.json
MODEL_NAME=model-b python smoke.py && mv scorecard.json scorecard.b.json
diff <(jq -S .rows scorecard.a.json) <(jq -S .rows scorecard.b.json)

The diff tells you which behaviors are model-sensitive. That list is your real risk surface, not the leaderboard.

Step 5: Gate the deploy

Wire the script into CI as one job. Fail the build on a non-zero exit. Now a provider swap cannot silently reach users.

Keep the scorecard as a build artifact. Two weeks later, when someone asks "did quality drop", you open a file instead of arguing.

Where free access fits, honestly

Iterating on a harness is a high-call-count activity. You run the suite dozens of times while tuning fixtures, and most of those calls produce nothing you keep. That is exactly the workload free model access helps with, and a free server option helps with the scheduled run that repeats the suite nightly.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Two caveats you should hold onto. Free availability is a moving target, so read the project's current offer page before you plan a schedule around it. Never put the free tier on the critical path of a user-facing request either. Use it for iteration and for the nightly check, then keep a paid or local fallback ready.

A decision table for your own project

Your situation	Use this harness	Skip it
Pipeline parses model output into structured data	Yes, rules are enough
Output has legal or safety language	Yes, plus human sign-off
One-shot creative writing, no contract		Yes, rules will lie to you
Per-call cost already trivial, no swap planned		Yes, low value
You change model or prompt weekly	Yes, this pays for itself fast

What I skipped, and who should not do this

I skipped a web dashboard. JSON in git beats a chart nobody opens.
I skipped a model-as-judge. It adds latency and its own drift.
I skipped latency and cost capture. Add those only when they become the problem.

Three groups should not use this approach. Teams whose outputs need human review on every call get little from string rules. Long-form creative products will drown in false failures. And anyone who cannot pin a model name has nothing stable to test.

Also be honest about determinism. Temperature zero still is not bit-identical across runs. Run the suite twice before you trust a green light.

The Sunday demo

Your demo should not be the first time you learn the endpoint changed. Twelve fixtures and forty lines of Python buy you a Monday morning without surprises.

If you want to try the harness against a free endpoint first, check the current offer page for what is actually available this month, then point MODEL_BASE_URL at it.

Weekend Build Log: A Weekly Digest Bot With a Token Budget Ledger

Riley Zhang — Sat, 17 Oct 2026 05:54:41 +0000

It is Saturday, 9pm. Your nightly jobs failed forty times this week. Nobody read the emails. You want one readable digest before Monday.

That is the whole project. One input, one output, one scheduled run. This build log keeps it that small.

1. Write the cut list before the code

Most weekend projects die from a second feature. So decide what you will not build, in writing.

In scope	Out of scope	Why the cut
One weekly digest file	Slack bot, email, web UI	Delivery is solved; formatting is the real work
Failures from one pipeline	Multi-repo aggregation	Doubles auth surface for zero added insight
A model call to group failures	A model call to fix failures	Fixes need context you should not send
One cron entry	A scheduler service	A cron line survives reboots and code review

If a task is not in the left column, it waits until next weekend. Say that out loud once.

2. Fix the output shape before the input

Your digest has to be readable in fifteen seconds. So define the file first, not the parser.

# Nightly digest - {{week}}

## Needs a human ({{n}})
- {{job}} - first seen {{first_seen}} - {{signal}}

## Already known noise ({{noise_count}})
- {{pattern}} x {{count}}

## Not triaged ({{skipped_count}})
- {{job}} - {{reason}}

Commit that as digest.template.md. Now your tests can assert on structure instead of vibes. The third section is not decoration. It is how you avoid pretending coverage you do not have.

3. Build the fixture before you touch the network

Record one real API response into fixtures/failures.json. Strip tokens, emails, and hostnames first. Then run everything from the file.

# fixture_run.py
import json, pathlib, subprocess

FIXTURE = pathlib.Path('fixtures/failures.json')
OUT = pathlib.Path('out/digest.md')

def load():
    jobs = json.loads(FIXTURE.read_text())
    assert isinstance(jobs, list) and jobs, 'fixture must be a non-empty list'
    return jobs

if __name__ == '__main__':
    jobs = load()
    print(f'fixture jobs: {len(jobs)}')
    subprocess.run(['python', 'digest.py', '--dry-run'], check=True)
    text = OUT.read_text()
    assert text.startswith('# Nightly digest'), 'template drifted'
    assert '@' not in text, 'redaction failed'
    print('fixture run OK')

That last assert earns its keep. Redaction regressions are silent and expensive. One line catches them forever.

4. Guard the budget with a ledger

Free access is still a finite resource. A ledger is cheaper than regret, and it takes about fifteen lines.

# ledger.py
import json, os, pathlib, time

LEDGER = pathlib.Path('state/ledger.json')
CAP = int(os.environ.get('TOKEN_CAP', '120000'))  # per run, your own limit

def estimate(text):
    return max(1, len(text) // 4)  # rough, fine for a guard

def load():
    if LEDGER.exists():
        return json.loads(LEDGER.read_text())
    return {'runs': []}

def spend(prompt, completion):
    state = load()
    used = sum(r['tokens'] for r in state['runs'])
    cost = estimate(prompt) + estimate(completion)
    if used + cost > CAP:
        raise SystemExit(f'budget guard tripped: {used}+{cost} > {CAP}')
    state['runs'].append({'at': time.time(), 'tokens': cost})
    LEDGER.write_text(json.dumps(state, indent=2))

Now test the only thing that matters for cost. Force the guard to trip.

TOKEN_CAP=1 python digest.py --dry-run; echo "exit=$?"

You want a non-zero exit and no output file. If the digest still appears, your guard runs after the call, not before it.

5. Constrain the model with a plain contract

Long prompts invite creative formatting. Keep the contract short and boring.

prompt.txt

You group failing CI jobs.
Return JSON with one key, groups, a list of objects.
Each object has signal, jobs, and first_seen.
One group per distinct error signature.
No prose. No markdown fences.

Then validate the reply instead of trusting it.

def parse(reply):
    data = json.loads(reply)
    groups = data.get('groups')
    if not isinstance(groups, list):
        raise ValueError('shape mismatch')
    return groups

Parse, retry once, then fall back to a raw job list. The fallback is not failure. It is the path that keeps Monday intact.

6. Ship one cron entry and stop

This workload is one process per week with no inbound traffic. The free server option covers that shape comfortably. Check the project page for current limits rather than trusting a blog post.

# crontab -e
0 6 * * 1 cd /srv/digest && TOKEN_CAP=120000 python digest.py >> log/run.log 2>&1

Keep the log. It is your only audit trail when a digest looks wrong. Rotate it monthly if it grows.

Decision table: triage it or skip it

Situation	Action	Reason
Same signature three weeks running	Group, hide	Known noise, no new information
Logs contain tokens or personal data	Skip, name only	Sending them leaks credentials
Single flaky timeout	Group, no model call	The pattern is obvious already
New signature right after a deploy	Send to a human first	Highest information value per row
Malformed reply twice	Raw list fallback	The digest must never block

Where free access actually earns its place

This digest is small, weekly, and by design not urgent. Paying for capacity to run it would be hard to justify, and hobby budgets are real. Free model access plus a free server option is what keeps this a weekend build instead of a subscription decision. That is the entire role the product plays here.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

One honest caveat. Free tiers change. Your ledger, your fixture, and your fallback path are what keep the project alive when a quota does.

What I skipped on purpose

No web UI. Terminals survive; dashboards get abandoned.
No auto-fix. A wrong fix costs more than a failed job.
No vector store. Signature grouping is enough at forty rows.
No cross-repo auth. One pipeline, one token, one blast radius.
No custom model routing. One call, one contract, one validator.

Who should not build this

Skip it if your logs contain customer data you cannot redact. Skip it if you need alerts within minutes, because weekly cron is the wrong tool. Skip it above a few thousand rows, where error signatures stop clustering. And skip it if you cannot accept that a free tier may change without notice.

The Monday check

Three commands, run in order, before you trust the cron entry.

python fixture_run.py
TOKEN_CAP=1 python digest.py --dry-run; echo "exit=$?"
tail -n 20 log/run.log

All three pass, you schedule the job. Any of them fail, you keep the fallback and fix nothing else.

Your backlog does not need a platform. It needs one file, one guard, and one Monday morning. Start with the free tier, then tell me which section of the digest you ended up deleting.

Weekend Build Log: A Notes Index That Ships Without an API Key

Riley Zhang — Fri, 16 Oct 2026 04:52:41 +0000

Your notes folder is a landfill. The fix you wrote three weeks ago is inside it somewhere.

You open far too many files and find nothing. So Saturday gets one query: type a word, get the right section.

This is that build log. Three commands, one SQLite file, one optional model call.

The scope cut

Weekend projects die from ambition, not from bugs. Pick one input, one query, one output.

My fence for Saturday:

Input: a folder of Markdown files.
Output: the top ten matching sections in a terminal.
Budget: four hours, then stop.

Everything else goes into SKIPPED.md. You will read that file on Sunday and feel fine.

Step 1: Prove the index works with no API key

Start with SQLite FTS5. It ships inside Python, and it needs no network at all.

Check it exists before writing more code:

python -c "import sqlite3; sqlite3.connect(':memory:').execute('CREATE VIRTUAL TABLE t USING fts5(x)'); print('fts5 ok')"

If that fails, your Python links an old SQLite. Stop and fix the environment first.

Now the indexer. It splits each file on headings, so a hit points at a section, not a whole file.

#!/usr/bin/env python3
"""index_notes.py - index a Markdown folder, then search it. Stdlib only."""
import hashlib
import json
import pathlib
import re
import sqlite3
import sys

DB = pathlib.Path("notes.db")
STORE = pathlib.Path("summaries.json")
HEADING = re.compile(r"^#{1,6}\s+(.*)$", re.M)


def connect():
    con = sqlite3.connect(DB)
    con.execute("PRAGMA journal_mode=WAL")
    return con


def chunks(text):
    parts = HEADING.split(text)
    if len(parts) == 1:
        return [("", text)]
    return [(parts[i].strip(), parts[i + 1].strip()) for i in range(1, len(parts), 2)]


def index(con, root):
    summaries = json.loads(STORE.read_text()) if STORE.exists() else {}
    con.execute("DROP TABLE IF EXISTS notes")
    con.execute(
        "CREATE VIRTUAL TABLE notes USING fts5("
        "path UNINDEXED, title, body, summary, tokenize='porter')"
    )
    root = pathlib.Path(root)
    n = 0
    for md in sorted(root.rglob("*.md")):
        rel = str(md.relative_to(root))
        text = md.read_text(encoding="utf-8", errors="replace")
        for title, body in chunks(text):
            h = hashlib.sha1((title + "\n" + body).encode()).hexdigest()
            con.execute(
                "INSERT INTO notes (path, title, body, summary) VALUES (?,?,?,?)",
                (rel, title, body, summaries.get(h)),
            )
            n += 1
    con.commit()
    print(f"indexed {n} chunks from {root}")


def search(con, query, limit=10):
    sql = (
        "SELECT path, title, summary, "
        "snippet(notes, 2, '[', ']', ' ... ', 12) "
        "FROM notes WHERE notes MATCH ? ORDER BY rank LIMIT ?"
    )
    for path, title, summary, snip in con.execute(sql, (query, limit)):
        print(f"\n{path} :: {title or '(intro)'}")
        if summary:
            print(f"  summary: {summary}")
        print(f"  {snip}")


if __name__ == "__main__":
    cmd = sys.argv[1]
    con = connect()
    if cmd == "index":
        index(con, sys.argv[2])
    elif cmd == "search":
        search(con, " ".join(sys.argv[2:]))
    else:
        sys.exit("usage: index_notes.py index <folder> | search <query>")

Two decisions matter. The table is rebuilt on every run. Summaries live in a JSON file, not in the database.

Both are wrong at a scale you do not have yet. Both save you an hour on Saturday.

Run it, and run this smoke test before you trust it:

mkdir -p /tmp/notes
printf '# Alpha\nsqlite fts5 is fine\n' > /tmp/notes/alpha.md
python index_notes.py index /tmp/notes
python index_notes.py search fts5

You should see alpha.md and the sentence around the match. If not, fix that before adding anything.

Step 2: Search before you generate

Search first, model second. If keyword search already finds your section, you just saved a batch and a bill.

FTS5 ranking is boring, and boring is a feature on a Saturday.

The honest weakness is synonyms. You type "auth", the note says "login". Keyword search misses it.

Step 3: Add a model only to the part that needs it

Enrichment is the only step here that needs a model, and it is also the step you can skip.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is the tool I reached for on this step, because its free model access makes a batch job cheap to try. The script below assumes an OpenAI-compatible /chat/completions route. If your dashboard shows a different path, change one line. It reads the base URL, key, and model id from the environment, so nothing here hardcodes a model name.

#!/usr/bin/env python3
"""enrich.py - optional. One model call per chunk. Resumable via summaries.json."""
import hashlib
import json
import os
import pathlib
import sys
import time
import urllib.error
import urllib.request

from index_notes import STORE, chunks

BASE = os.environ.get("MONKEYCODE_BASE_URL", "").rstrip("/")
KEY = os.environ.get("MONKEYCODE_API_KEY", "")
MODEL = os.environ.get("MONKEYCODE_MODEL", "")


def pending(store, root, limit):
    todo = []
    for md in sorted(pathlib.Path(root).rglob("*.md")):
        text = md.read_text(encoding="utf-8", errors="replace")
        for title, body in chunks(text):
            h = hashlib.sha1((title + "\n" + body).encode()).hexdigest()
            if h not in store:
                todo.append((h, title, body))
            if len(todo) >= limit:
                return todo
    return todo


def summarize(title, body):
    payload = {
        "model": MODEL,
        "temperature": 0,
        "messages": [
            {"role": "system", "content": "Summarize for keyword search. Max 20 words. Plain text only."},
            {"role": "user", "content": f"{title}\n\n{body[:2000]}"},
        ],
    }
    req = urllib.request.Request(
        f"{BASE}/chat/completions",
        data=json.dumps(payload).encode(),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {KEY}"},
    )
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())["choices"][0]["message"]["content"].strip()


if __name__ == "__main__":
    if not (BASE and KEY and MODEL):
        sys.exit("set MONKEYCODE_BASE_URL, MONKEYCODE_API_KEY, MONKEYCODE_MODEL")
    root = sys.argv[1]
    batch = int(sys.argv[2]) if len(sys.argv) > 2 else 50
    store = json.loads(STORE.read_text()) if STORE.exists() else {}
    todo = pending(store, root, batch)
    print(f"{len(todo)} chunks need a summary")
    for h, title, body in todo:
        try:
            store[h] = summarize(title, body)
        except urllib.error.HTTPError as e:
            print("stopping on HTTP", e.code, e.read()[:200])
            break
        except Exception as e:
            print("stopping on", type(e).__name__, e)
            break
        STORE.write_text(json.dumps(store, indent=0))
        time.sleep(0.2)
    print(f"{len(store)} summaries on disk")

Run it in small batches, then re-index:

export MONKEYCODE_BASE_URL="..."   # copy from your dashboard
export MONKEYCODE_API_KEY="..."
export MONKEYCODE_MODEL="..."
python enrich.py ~/notes 50
python index_notes.py index ~/notes

The script writes after every success, so a crash costs one call. A 429 stops the batch instead of hammering the endpoint.

Step 4: Move the slow part off your laptop

The batch touches every changed note. That is a night job, not a foreground one.

MonkeyCode advertises a free server option alongside its free model access. Treat every availability claim in this article as operator-stated and short-lived: quotas, model ids, and limits change, so read the pricing page on the day you build.

A nightly line is enough:

0 3 * * * cd ~/notes-index && python enrich.py ~/notes 200 >> enrich.log 2>&1 && python index_notes.py index ~/notes >> enrich.log 2>&1

Cap the work per night. A fixed batch size is a budget you can predict.

Decision table

Your situation	Add the model?	Why
Under ~200 notes, you search by word	No	FTS5 rank is already enough
You forget your own vocabulary	Yes, summaries only	Synonyms get a place to live
You want "meaning" search	Neither	You need embeddings and a vector store
Air-gapped or offline machine	No	Enrichment needs the network
You will not watch a bill	Start free, set a batch cap	Free tiers end, jobs keep running

What I skipped

No UI. The terminal is the interface.
No incremental indexing. A full rebuild is fine at this size.
No watcher process. Cron is enough.
No PDF or Office parsing. Markdown only.
No embeddings. That is a different weekend.

The SKIPPED.md list is the point. Write it before you start, not after you quit.

Limits and who should not use this

Summaries drift. Re-run enrichment when notes change, or your index describes an older version of you.

Full rebuilds get slow past a few tens of thousands of chunks. Measure your own folder; do not take my word for it.

Skip this approach if you need semantic search, multi-user access, or live sync. Skip it if you cannot keep an API key out of a public repo.

Start with the offline index. It ships whether or not the model answers, and that is the only promise a weekend needs.

If you do want to try the paid-parts-for-free route, point MONKEYCODE_BASE_URL at your own key and run one fifty-chunk batch first.

Weekend Build Log: A Docs Drift Checker That Runs Your README

Riley Zhang — Thu, 15 Oct 2026 11:10:41 +0000

Last Saturday a teammate pasted our README quickstart into a fresh container. Step three failed. The install command had been renamed four months ago.

Nobody noticed, because nobody runs docs. We run tests.

So I gave myself one weekend. Build the smallest tool that executes every fenced shell block in our docs. Fail loudly when a block breaks. Ship a working demo by Sunday night.

This is the build log. It covers the scope cuts, the code, and the parts I deliberately skipped.

Why a checker instead of a linter

Linters read docs. A checker runs them.

That difference matters more than it sounds. A linter says a command looks odd. A checker says the command exits 3 on a clean machine.

I wanted the second kind. So the first design rule was strict.

Rule zero: the model never decides pass or fail

Deterministic code decides whether a block drifted. A language model never touches that verdict.

I learned this on an earlier side project. A model that classifies failures is fun to demo and painful to trust. It drifts, it costs money per run, and it invents confident reasons.

So the split stays clean:

Python extracts the shell blocks.
Docker runs each block and returns an exit code.
The exit code decides pass or fail.
A model gets one bounded job: turn raw stderr into one readable line.

If the model is unavailable, the checker still works. That property is worth more than any prompt.

Step 1: Extract the fenced blocks

Start with the smallest parser that could work. No Markdown library, no AST, no plugin system.

#!/usr/bin/env python3
'''driftcheck.py - execute fenced shell blocks from Markdown files.'''
from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
import time
from pathlib import Path

FENCE = re.compile(r'```

(?:bash|sh|console)\n(.*?)

```', re.DOTALL)
PROMPT = re.compile(r'^\s*[$#]\s?')


def extract(path: Path) -> list[tuple[int, str]]:
    '''Return (block_index, script) for every fenced shell block.'''
    blocks = []
    for i, raw in enumerate(FENCE.findall(path.read_text()), start=1):
        lines = [PROMPT.sub('', line) for line in raw.splitlines()]
        script = '\n'.join(line for line in lines if line.strip())
        if script:
            blocks.append((i, script))
    return blocks

Two details earn their keep here. The PROMPT regex strips the $ you copy from terminal output. The empty-line filter stops trailing blanks from confusing sh -c.

Step 2: Run each block in a throwaway container

Never run docs commands on your own machine. You do not know what a contributor pasted in.

def run_block(script: str, image: str, workdir: Path, timeout: int) -> dict:
    started = time.monotonic()
    proc = subprocess.run(
        [
            'docker', 'run', '--rm',
            '--network=none',
            '-v', f'{workdir}:/work',
            '-w', '/work',
            '--entrypoint', 'sh',
            image, '-c', script,
        ],
        capture_output=True,
        text=True,
        timeout=timeout,
    )
    return {
        'exit_code': proc.returncode,
        'seconds': round(time.monotonic() - started, 2),
        'stderr_tail': proc.stderr[-400:],
    }

--network=none carries the weight here. Blocks that secretly download something now fail fast and loudly.

Step 3: Report, then set the exit code

def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument('docs', nargs='+', type=Path)
    ap.add_argument('--image', default='python:3.12-alpine')
    ap.add_argument('--timeout', type=int, default=60)
    ap.add_argument('--json-out', type=Path)
    args = ap.parse_args()

    report, drifted = [], 0
    for doc in args.docs:
        for index, script in extract(doc):
            result = run_block(script, args.image, doc.parent.resolve(), args.timeout)
            result.update({'doc': str(doc), 'block': index})
            report.append(result)
            if result['exit_code'] != 0:
                drifted += 1
                print(f'DRIFT {doc} block {index} exit={result[chr(34)+chr(34)]}')

    if args.json_out:
        args.json_out.write_text(json.dumps(report, indent=2))

    print(f'blocks={len(report)} drifted={drifted}')
    return 1 if drifted else 0


if __name__ == '__main__':
    sys.exit(main())

Ignore that f-string edit and write it plainly. Use exit={result['exit_code']} in your own copy.

The exit code is the product. Everything else is decoration. Wire this into CI and a broken block becomes a red build.

Step 4: Add one bounded model call

Now the model earns its place. It reads stderr and names the failing command. Nothing else.

import httpx

# Provider-agnostic. Swap base_url and model for whatever your free tier exposes.
def hint(stderr: str, base_url: str, model: str, key: str) -> str:
    payload = {
        'model': model,
        'max_tokens': 60,
        'messages': [
            {'role': 'system',
             'content': 'Name the failing command in one line. No advice.'},
            {'role': 'user', 'content': stderr[-1500:]},
        ],
    }
    resp = httpx.post(
        f'{base_url}/chat/completions',
        json=payload,
        headers={'Authorization': f'Bearer {key}'},
        timeout=20,
    )
    resp.raise_for_status()
    return resp.json()['choices'][0]['message']['content'].strip()

Three limits keep this honest. Cap max_tokens at 60. Cap the request at 20 seconds. Drop the call on failure and keep the raw stderr.

Redact before you send. Stderr from a failed login block can contain tokens.

Step 5: Keep execution local, move the always-on part

Here is where MonkeyCode changed my weekend plan. My laptop cannot be the webhook receiver.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option, and I used both in this build. The free server hosts the webhook and the report endpoint. It is always on, which is the only property I needed. The free model endpoint handles the single hint call per drifted block, and nothing more. Check the current free-tier terms on their site before you design around them, since allowances and limits change.

One thing I refused to move: the execution. Running untrusted shell on shared free infrastructure is how you get a very bad Monday. The container run stays on a machine I control.

curl -sS -X POST https://<your-free-server>/hook \
  -H 'content-type: application/json' \
  -d '{"repo":"docs","reason":"push"}'

The receiver stores the request and pings me. My local runner picks it up, runs the blocks, and POSTs the JSON report back. Two moving parts, no shared trust.

The acceptance test I ran before shipping

Do not trust a checker you have not seen fail. Two fixtures prove the contract.

mkdir -p tests/fixtures
printf '```

bash\necho ok\n

```\n' > tests/fixtures/good.md
printf '```

bash\nexit 3\n

```\n' > tests/fixtures/bad.md

python driftcheck.py tests/fixtures/good.md; echo "exit=$?"   # exit=0
python driftcheck.py tests/fixtures/bad.md;  echo "exit=$?"   # exit=1

python driftcheck.py tests/fixtures/bad.md --json-out /tmp/r.json
python -c "import json; print(json.load(open('/tmp/r.json'))[0]['exit_code'])"  # 3

If the good fixture does not return 0, your parser is broken. If the bad fixture does not return 1, your CI gate is broken. Run both before you wire anything to a pipeline.

The scope cuts I made

A weekend project dies from ambition, not from bugs. Here is the cut list.

Shipped	Skipped	Why
`bash`, `sh`, `console` blocks	Python, JS, TS blocks	Each language needs its own image and install step
Serial execution	Parallel runs	A dozen blocks finish fast enough in sequence
Exit code plus JSON report	HTML dashboard	The log line is the deliverable
One-line model hint	Auto-fix pull requests	Auto-edits to docs create review work, not savings
Local runner, remote webhook	Remote execution	Untrusted shell does not belong on shared infra

Two of those cuts hurt. Skipping Python blocks left real docs uncovered. Skipping parallel runs made the first CI version slow. Both were still the right call for one weekend.

Limitations and who should not use this

Be honest about the edges before you copy the approach.

Do not run blocks that need real cloud credentials. Put them behind a manual checklist instead.
Docs that intentionally print broken output will always report drift. Exclude those files.
Teams without a container runtime cannot isolate anything. Use a disposable VM instead.
If you want automatic fixes, this tool will disappoint you. It reports, it does not repair.
Every hint call sends stderr to a third party. Redact secrets first, or run the model locally.

What I would build next

The next step is a config file listing blocks to never run. After that, a per-language image matrix. Both can wait.

The demo runs. The model is optional. The exit code is the product.

If you want to try the same split, MonkeyCode's free model access and free server option are enough to keep a weekend bill at zero. Start with the exit code, not the prompt.

Hide Unchecked Lines Before the Sunday Demo

Riley Zhang — Mon, 12 Oct 2026 23:50:42 +0000

You sit down at two on Saturday afternoon. Your friend wants a demo before Sunday dinner.

The model draft sounds tidy, but no line is proven. You freeze scope before you write another prompt.

The room you actually have

You have one laptop and one local fixture file. You do not have a reviewed UI or a shared host.

The demo must run from one command in the repo. If that command fails, you show the friend nothing.

The cut you make first

You keep three jobs, and you name them out loud. You parse the fixture, stamp each row, and print a card.

You park retries, a web view, and multi-file search. Those parked jobs wait until Monday, not Sunday night.

Why a stamp beats a longer draft

Fluent text is not the same thing as a checked fact. A weekend demo fails when you read unchecked lines aloud.

The stamp blocks that slide before your friend arrives. You can still explain the parked list after the card.

The fixture you freeze

Each row is one JSON object on its own line. The text field holds the sentence you might say aloud.

The source field must read fixture before a row can show. A model draft can sit in the file, but it stays hidden.

Step 1: Write the fixture

Create a folder named fixtures in the repo root. Save the four rows below as fixtures/saturday.jsonl in the repo.

Keep the file small so you can read every line yourself. Do not paste secrets, customer logs, or private paths.

{"text": "Parser reads JSONL from a local path.", "source": "fixture"}
{"text": "Stamp hides rows that did not come from the fixture.", "source": "fixture"}
{"text": "Demo card prints at most three checked lines.", "source": "fixture"}
{"text": "The model also suggested a live retry loop.", "source": "model"}

Step 2: Add the stamp script

Save this file as demo_stamp.py beside the fixtures folder. Treat it as an unexecuted example until you run it locally.

The script does not call a network and does not score a model. It only sorts rows you already placed on disk. Use Python 3.9 or newer for the list type hints.

from pathlib import Path
import json
import sys

SKIP = ("retry_loop", "web_ui", "multi_file_search", "remote_host")

def load_fixture(path: Path) -> list[dict]:
    rows = []
    for line in path.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        rows.append(json.loads(line))
    return rows

def stamp(row: dict) -> dict:
    text = str(row.get("text", "")).strip()
    source = str(row.get("source", "")).strip()
    checked = bool(text) and source == "fixture"
    return {
        "text": text,
        "source": source or "missing",
        "stamp": "checked" if checked else "hold",
    }

def demo_card(rows: list[dict]) -> list[dict]:
    stamped = [stamp(row) for row in rows]
    return [row for row in stamped if row["stamp"] == "checked"][:3]

def main() -> int:
    if len(sys.argv) != 2:
        print("usage: python demo_stamp.py fixtures/saturday.jsonl")
        return 2
    path = Path(sys.argv[1])
    if not path.is_file():
        print("demo blocked: fixture file is missing")
        return 1
    card = demo_card(load_fixture(path))
    if not card:
        print("demo blocked: no checked lines")
        return 1
    for item in card:
        print(f"CHECKED {item['text']}")
    print("skipped:", ", ".join(SKIP))
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

Step 3: Run one command

From the repo root, run the script against the fixture. You should see three CHECKED lines and one skipped footer.

The model row must not appear in the CHECKED list. If it appears, stop the demo and fix the stamp rule.

python demo_stamp.py fixtures/saturday.jsonl

A clean run prints the three fixture sentences first. Then it prints the parked names in a single skipped line.

That pair is the whole Sunday demo, and nothing more. You do not open a browser, and you do not retry a call.

Step 4: Lock the rule with a test

Create tests/test_demo_stamp.py before you treat the demo as ready. The test checks the card length and the hidden model row.

It also checks that an empty text row never becomes checked. Run it from the repo root so the import resolves. Use the standard library only, so you add no dependency.

import unittest
from demo_stamp import demo_card, stamp

class DemoStampTest(unittest.TestCase):
    def test_card_hides_model_rows(self):
        rows = [
            {"text": "One checked line.", "source": "fixture"},
            {"text": "A fluent guess.", "source": "model"},
        ]
        card = demo_card(rows)
        self.assertEqual(len(card), 1)
        self.assertEqual(card[0]["source"], "fixture")

    def test_empty_text_stays_on_hold(self):
        row = stamp({"text": "  ", "source": "fixture"})
        self.assertEqual(row["stamp"], "hold")

if __name__ == "__main__":
    unittest.main()

python -m unittest discover -s tests -t .

You want two tests and an OK line before you share the room. If a test fails, you fix the rule, not the fixture story.

Do not delete a failing test to make Sunday feel smoother. A red test is a better demo than a fake green card.

Read the decision table

Use this table when a new row shows up late. Read the signal, apply the stamp, then take one action.

Do not add a fourth action during the Saturday window. If a row does not match, you hold it and move on.

Signal	Stamp	Action
Non-empty text and source fixture	checked	Print it, up to three lines
Source is model	hold	Hide it from the demo card
Empty text or missing source	hold	Hide it and keep going
Work sits in the skip tuple	parked	Name it once in the footer

A checked stamp means you marked the source yourself. It does not mean an outside reviewer proved the sentence.

Say that limit out loud if your friend asks for certainty. The card is a gate, not a certificate.

What you skipped on purpose

You skipped a retry loop because Sunday does not need one. A retry hides a bad fixture behind another model draft.

You skipped a web UI because the command already fits the room. You skipped multi-file search because one file is easier to audit.

You also skipped a remote host for this particular demo. The laptop command is enough for one friend at one table.

A shared host can wait until the card stays green locally. Shipping the host first would only add a new failure point.

Where a free lane can help later

You can draft the next fixture row with free model access. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Paste that draft into the file with source set to model. The stamp hides it until you rewrite it as a fixture fact.

Do not plan Sunday around a quota you have not verified. This note does not name models, hardware, or a time limit.

Keep the demo on the laptop until the two tests pass. After the local gate is green, try the free server option.

Limits you should say aloud

The script trusts the source field you typed by hand. A wrong source label can smuggle an unchecked line through.

Read the fixture once before you run it live. If you cannot read it, you are not ready to demo it.

Broken JSON stops the script with a traceback, not a card. Fix the line, then run the unit test again from the root.

The three-line cap hides extra checked rows on purpose. Add a fourth spoken line only after Monday, not during dinner.

This pattern is a poor fit for private customer data. It is also a poor fit for a live incident bridge.

It will not tell you which model is smarter this month. Use it for a small side demo, not for a production gate.

Who should leave this on the shelf

Skip this build if you need a reviewed security control. Skip it if the fixture would contain secrets or personal data.

Skip it if your friend needs live data from another system. Skip it if you cannot show the parked list without embarrassment.

You should also skip it when the scope is already one command. A second gate will only slow a demo that is already honest.

Use the table when model prose is trying to widen Saturday. That is the failure this build log is meant to catch.

Monday, after the friend leaves

Copy any held row you still believe into a new note. Rewrite it in your own words, then set source to fixture.

Add one parked job back only after the two tests stay green. Leave the other parked jobs on the list until you have time.

That keeps the weekend promise small enough to finish. Your friend saw three checked lines and an honest skip line.

You did not pretend a draft was a finished tool. Next Saturday can start from the note, not from a blank repo.

Run the Triage Demo With the Network Off

Riley Zhang — Sun, 11 Oct 2026 20:40:31 +0000

Saturday hits, and the issue list is still messy. You promised a working triage demo before dinner. Forty leftover titles still sit in the tracker.

A full board app will not fit this afternoon. You need three labels and one reliable command. Anything heavier than that waits until Monday.

Cut the job to three labels

Name the job in one plain sentence first. Each leftover title becomes keep, park, or drop. That is the whole product for this afternoon.

Keep means you will touch it next week. Park means it is real, but not this weekend. Drop means it does not earn a slot.

Park the extra ideas

Write a cut list before you create the first file. You skip a web UI and a login flow. You skip a database and a hosted dashboard.

You also skip a live model beauty contest. One draft pass is enough for this demo. A second vendor does not make the demo safer.

You also skip embeddings, queues, and background workers. You skip charts that praise a score you never ran. You skip any feature that needs a secret in the repo.

Lock the row contract

Put the rules in a file you can diff later. Input is a title string plus a short note. Output is one label plus a short reason.

Reject empty titles before you make any model call. Reject any label outside the three allowed words. Reject any reason that runs past twelve words.

Require a stable id on every single row. Never match rows by title text alone later. Titles can repeat, while row ids should not.

1. Hand-label eight gold rows

You label eight sample rows by hand first. Do this before you ask any model for help. Your labels are the contract, not a suggestion.

Pick boring titles from your own issue tracker. Include one ambiguous title in the set on purpose. Include one title that should clearly be dropped.

Write each reason in your own plain words. If you cannot justify a label, park the row. Do not let haste invent a fourth label.

2. Take one model draft

Now you may ask a model for a single draft. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option.

Treat both as current availability, not as a quota promise. Use the free model access for this one draft pass. Do not send private customer data in the prompt.

Paste only titles you already cleared to share. Save the raw draft beside the gold file. If the two files disagree, the gold file wins.

Do not edit gold labels to flatter the draft. Do not rerun the model until the labels match. A demo that needs retries is not ready.

3. Diff labels before you accept them

Run a small checker before you trust any row. The checker compares only the label field on each row. A reason mismatch is a note, not a hard failure.

Count matches, mismatches, and any missing row ids. Stop if any gold id is missing from the draft. Stop if any label falls outside the allowed set.

Print the mismatched ids in a plain list. Read each miss before you accept a fixture row. Acceptance is a human step, not a script step.

4. Freeze the rows you accept

Copy only accepted rows into the demo fixture. The demo command reads that fixture, not the network. Your Saturday audience then sees one stable result.

Name the fixture with the date you froze it. Add a header note that the file is a recording. Ban live model calls while demo mode is on.

Keep rejected rows in a separate scratch file. Do not delete them, because they teach the next cut. Do not show scratch rows in the dinner demo.

5. Print the demo from disk

Give yourself one demo command for the room. That command prints the fixture as a short table. It must succeed with the network fully unplugged.

If the command tries to call a model, fail it. If the fixture file is missing, fail the run. If a row label is unknown, fail the run.

Print the fixture date at the top of the output. Print the row count next to that date. A silent success can hide a stale fixture file.

6. Serve a link only if someone is remote

A laptop demo does not need any server. Use a free server only when a remote person must open a link. Even then, serve the frozen fixture, not a live model.

The free server option can host that static demo. Read the current product docs before you depend on it. Do not assume hardware, duration, or a fixed token quota.

Put the fixture file behind a read-only path. Do not expose a prompt box on that page. A prompt box invites a live call you banned.

Use this decision table

Use the table when you feel tempted to add scope. Each row names the temptation, the safer keep, and the stop. Follow the stop column when your time is short.

Temptation	Safer keep	Stop now
Live model during the demo	One draft saved beside gold	Any call while demo mode is on
Web UI before dinner	Plain table from the fixture	Login, routing, or a CSS framework
Server for a solo laptop demo	Local command on your machine	A host when nobody is remote
Accuracy number in the README	Printed list of mismatched ids	Any percent you did not measure
Fourth label for odd titles	Park the unclear row	A new label name

Proposed checker

Treat the script below as a proposal, not a lab report. It has not been executed in this writeup. Run it locally before you trust the output.

Start with the gold file present and valid. Confirm the checker exits zero on a perfect copy. Then break one label and confirm a nonzero exit.

Unplug the network and run the demo command. Confirm the same table prints a second time. Confirm no outbound call appears in the process log.

# Proposal only. This example was not executed for this article.
import json
import sys
from pathlib import Path

ALLOWED = {"keep", "park", "drop"}

def load_payload(path):
    file_path = Path(path)
    if not file_path.exists():
        raise SystemExit(f"missing file: {path}")
    payload = json.loads(file_path.read_text())
    rows = payload["rows"]
    seen = set()
    for row in rows:
        if row["id"] in seen:
            raise SystemExit(f"duplicate id: {row['id']}")
        seen.add(row["id"])
        if row["label"] not in ALLOWED:
            raise SystemExit(f"bad label: {row['id']}")
        if not str(row["title"]).strip():
            raise SystemExit(f"empty title: {row['id']}")
    return payload

def diff_labels(gold, draft):
    draft_by_id = {row["id"]: row for row in draft}
    misses = []
    for row in gold:
        other = draft_by_id.get(row["id"])
        if other is None:
            raise SystemExit(f"missing id: {row['id']}")
        if other["label"] not in ALLOWED:
            raise SystemExit(f"bad draft label: {row['id']}")
        if other["label"] != row["label"]:
            misses.append(row["id"])
    return misses

def main():
    mode = sys.argv[1]
    if mode == "check":
        gold = load_payload(sys.argv[2])["rows"]
        draft = load_payload(sys.argv[3])["rows"]
        misses = diff_labels(gold, draft)
        if misses:
            print("mismatch", ",".join(misses))
            raise SystemExit(1)
        print("match", len(gold))
        return
    if mode == "demo":
        payload = load_payload(sys.argv[2])
        print("source", "fixture")
        print("frozen_on", payload.get("frozen_on", "missing"))
        print("rows", len(payload["rows"]))
        for row in payload["rows"]:
            print(row["id"] + " | " + row["label"] + " | " + row["title"])
        return
    raise SystemExit("use check or demo")

if __name__ == "__main__":
    main()

{
  "frozen_on": "2026-10-12",
  "source": "hand-accepted fixture",
  "rows": [
    {
      "id": "t1",
      "title": "Fix flaky login test",
      "label": "keep",
      "reason": "Breaks the Monday build."
    },
    {
      "id": "t2",
      "title": "Rename button color token",
      "label": "park",
      "reason": "Real, but not this weekend."
    },
    {
      "id": "t3",
      "title": "Rewrite app in a new framework",
      "label": "drop",
      "reason": "Too large for the slot."
    }
  ]
}

python triage_fixture.py check gold.json draft.json
python triage_fixture.py demo fixture.json

Save the model draft yourself, outside this script. Do not hide an API call inside demo mode. If you need a draft, make that call once, then stop.

The date inside the sample file is only an example. The three titles are stand-ins, not a real tracker. Replace them with titles you are allowed to share.

Know the limits

Free access can change without a public warning. A fixture goes stale when title meanings change. A model draft is untrusted text, not a decision.

This flow does not measure real model quality. Eight gold rows cannot prove a general classifier. Do not quote a score you did not measure.

The free server option is not a capacity plan. It is only a way to show a static file. If the offer is gone, the laptop demo still stands.

Who should not use this

Skip this flow for live production incident routing. Skip it when a wrong label can page a person. Skip it when titles hold secrets or personal data.

Skip it if you need an audited trail of model calls. Skip it if the demo must show live model output. In that case, say plainly that the result can change.

Skip it if you cannot hand-label even eight rows. Without gold labels, you only have a hunch. A hunch is not a weekend demo you can defend.

Leave a Monday note

On Monday, reread the cut list before you expand scope. Add a UI only after the fixture test still passes. Add a live call only behind a flag you can disable.

If that flag is on, keep the fixture as fallback. Print which source served each row in the table. Never hide a live call inside the demo script.

You leave Saturday with a command, a fixture, and a cut list. That is a demo you can rerun on Monday. The model helped once, then left the stage.

If you want the draft pass there, read the current MonkeyCode docs. Keep the public demo pinned to the fixture.

Prove the Saturday Demo With a Skip Manifest

Riley Zhang — Sat, 10 Oct 2026 17:04:29 +0000

You open the side project at 9:10 on Saturday morning.
A friend wants a working demo before dinner tonight.
The project folder already holds six half-built ideas.

You do not need a full platform tonight.
You need one path that still runs clean.

The trap is the extra folder, not the missing syntax.
Each new idea feels small until the demo clock hits.
Cut the surface before you ask any model for code.

A generated screen is not a demo if the path fails.
Friends can sketch a page before the coffee cools.
They still ask whether the command exits clean.

Name the constraint before the tool

A free model pass can draft a cut list quickly.
It cannot decide what your friend should see tonight.
A free server can run a smoke command for you.
It cannot hold secrets or promise next month's terms.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.
The operator supplied two availability notes for this draft.
Those notes are free model access and a free server option.
This draft does not quote a token quota or a hardware size.
It does not name a model, a region, or an end date.
Open the current project docs before you plan around either note.
Old posts go stale, and a stale quota wrecks the weekend.

MonkeyCode is the open-source assistant named for this workflow.
Use it as a second reader for a short list.
You still write the skip manifest by hand.
You still run the gate on a machine you control.
Confirm the license on the project page before you reuse the code.

Split the weekend into three lists

Ship is the path you will actually show.
Park is real code you refuse to import tonight.
Skip is work you will not even sketch.
If a file is absent from ship, it stays out of the entry.

Keep each list short enough to read aloud.
Four ship files is already a wide Saturday.
Three parked module names are a healthy cut.
A long skip list protects Monday from surprise scope.

1. Freeze the cut in scope.json

Create the scope file in the repository root.
Put the entry file and the smoke command there.
Do not add a fifth idea while you type the file.

{
  "entry": "demo.py",
  "smoke": ["python3", "demo.py", "--check"],
  "ship": ["demo.py", "scope.json", "demo_gate.py"],
  "park": ["billing.py", "accounts.py", "deploy.py"],
  "skip": ["multi-model bakeoff", "custom domain", "analytics"]
}

This file is the contract for the weekend demo.
A model may suggest a sharper cut here.
You accept or reject each line by hand.

2. Add a gate you can read

Save the proposed script below as a file named demo_gate.py.
This is a proposed example, not a measured benchmark.
It uses only the Python standard library here.
Run it once locally before you trust the output.

#!/usr/bin/env python3
"""Proposed weekend scope gate. Not a production auditor."""
import json
import pathlib
import subprocess
import sys

ROOT = pathlib.Path(__file__).resolve().parent

def load_scope(path: pathlib.Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    required = ("ship", "park", "skip", "entry", "smoke")
    for key in required:
        if key not in data:
            raise SystemExit("missing key: " + key)
    return data

def missing_ship_files(scope: dict) -> list[str]:
    missing = []
    for rel in scope["ship"]:
        if not (ROOT / rel).is_file():
            missing.append(rel)
    return missing

def parked_imports(scope: dict) -> list[str]:
    entry_path = ROOT / scope["entry"]
    if not entry_path.is_file():
        return []
    entry = entry_path.read_text(encoding="utf-8")
    hits = []
    for rel in scope["park"]:
        stem = pathlib.Path(rel).stem
        token_a = "import " + stem
        token_b = "from " + stem
        if token_a in entry or token_b in entry:
            hits.append(rel)
    return hits

def main() -> int:
    scope = load_scope(ROOT / "scope.json")
    missing = missing_ship_files(scope)
    hits = parked_imports(scope)
    if missing or hits:
        print("gate: fail")
        for item in missing:
            print("missing ship file: " + item)
        for item in hits:
            print("parked import in entry: " + item)
        return 1
    print("gate: scope ok")
    smoke = scope["smoke"]
    if not smoke:
        return 0
    completed = subprocess.run(smoke, cwd=ROOT, check=False)
    return completed.returncode

if __name__ == "__main__":
    raise SystemExit(main())

The import check is a plain string search.
That limit is also the reason you can read it.
You can audit the whole rule without a framework.

3. Keep the demo entry boring

Write the entry so it proves one behavior.
A check flag is enough for the smoke path.
Print one line and exit with a clear status.

#!/usr/bin/env python3
import argparse

def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--check", action="store_true")
    args = parser.parse_args()
    if args.check:
        print("demo: ok")
        return 0
    print("demo: run with --check")
    return 2

if __name__ == "__main__":
    raise SystemExit(main())

Do not import billing, accounts, or deploy here.
Those module names belong on the park list.
The gate should fail if the entry pulls them in.

4. Run the gate before you celebrate

From the repository root, run the two commands below.
You want a scope line and a demo line.
If either line is missing, stop adding features.

python3 demo_gate.py
python3 -m py_compile demo_gate.py demo.py

On Windows, swap python3 for the launcher you actually use.
A scope-ok line means the lists still match the tree.
A demo-ok line means the smoke path exits clean.

A compile check only proves the files parse.
It does not prove the cut is still honest.

5. Ask the model about the cut only

Paste the scope file into the assistant, not the repo.
Ask which ship line is still too wide.
Reject any answer that adds a new product surface.

Accept an answer that moves a file from ship to park.
That is the useful slot for free model access.
The model is a second reader for a short contract.

It is not a license to generate the parked folders.
If the chat starts inventing billing flows, close the tab.

A free server option can host the smoke command.
Use that option only when you can read the logs.
Do not upload keys, private repos, or customer rows.

A Saturday demo should run on toy input you can delete.
If the path needs a secret, keep the run on your laptop.

6. Write the skip note before dinner

Add a skip note before you leave the desk.
Three lines are enough if each line has a reason.
Future you should not recover the cut from guilt.

# Skipped this weekend
- Accounts: no login, because the demo is one local command.
- Billing: no prices, because nothing is sold tonight.
- Deploy polish: no custom domain, because localhost is the demo.

Read that note out loud when you show the demo.
A small working path beats a tour of empty stubs.
Say what you parked, then run the smoke command once.

7. Show only what the lists can defend

Your friend will ask three questions at the table.
Answer each from a ship file, or say it was skipped.
Do not open a parked file to improvise a feature.

The first question asks what the command prints.
That answer lives in the entry and nowhere else.
The second question asks what you refused to build.

That answer lives in the skip note you wrote.
The third question asks how you know it still runs.
That answer is the gate exit code, not a screenshot.

If you cannot map a question to a ship file, park it.
A demo with unmapped questions turns into a tour.
Tours run long, and long tours hide a broken path.

Debug a red gate without widening scope

Use this order when the gate exits with an error.
Do not open a parked file to finish the thought.

Read the first fail line and touch only that cause.
If a ship file is missing, create it or move it to park.
If a parked import appears, delete that import from the entry.
If the smoke command fails, fix the entry and nothing else.
Run the gate again before you edit any other file.

A commented-out check is not a real fix.
You would be hiding the cut instead of holding it.
The red line is the product for this weekend.

Try this four-row test plan

Label these rows as checks you should run yourself.
This draft does not claim a recorded test log.
Restore the clean tree after you finish each row.

Check	What you change	What you expect
Clean tree	No parked import in the entry	Exit 0 and `demo: ok`
Park leak	Add `import billing` to the entry	Exit 1 and a parked-import line
Missing ship	Rename `demo.py` for one run	Exit 1 and a missing-file line
Smoke fail	Make `--check` return 2	Gate returns 2 after the scope line

A test that leaves the demo broken is a new bug.
Write the four results in the skip note if you want them.

Choose local or the free server

Question	Stay on your machine	Free server option
Does the path need a secret?	Yes. Keep it local.	No. Do not upload secrets.
Is the input toy data you can delete?	Either place can work.	Fine if you can read logs.
Will you be offline after dinner?	Prefer the laptop copy.	Do not depend on the host.
Do you need a public URL tonight?	Not for this cut.	Recheck terms before you share.
Is the goal a platform launch?	Stop. This gate is too small.	Stop. This gate is too small.

The table is a filter, not a hosting promise.
A free server can throttle, vanish, or change terms.
Your demo must still run from the laptop copy.

Treat the hosted run as a spare, not the source.
Recheck the current terms before you share a hosted URL.
A link that dies after dinner is not a demo.

What the gate does not prove

The string search misses importlib and aliased imports.
A pass is a tripwire, not a security audit.
Read the entry once with your own eyes anyway.

Dynamic imports can still walk around this check.
The gate runs whatever command the smoke list holds.
Put only a command you would type yourself.

The smoke list is passed without a shell.
Pipes and shell operators will not run here.
That keeps a sloppy paste from becoming a surprise.

A command copied from chat is still your responsibility.
The gate does not rank models or vendors.
It does not prove a free tier will last.

If a launch date needs a fixed quota, get it in writing.
Do not paste an old token number into your plan.

Who should not use this cut

Skip this approach if the demo touches payments.
Skip it if the files hold private user data.
Skip it if a teammate needs an audit trail.

Skip it if the weekend is actually a client deadline.
Skip it if you would paste production secrets into a host.
A skip manifest will not save those projects.

Those projects need a slower review, not a dinner demo.
Use the gate for toy side projects with a visible cut.

Leave a Monday trail

Open the repo on Monday before new ideas land.
Run the same two commands before you edit anything.
If the gate fails, you added scope after the demo.

Move the new file to park, or delete it.
Do not bargain with a red gate on a weekday morning.
Then add one fresh line to the skip note.

Name the idea you still refuse this week.
The demo stays small because the list stays honest.

If MonkeyCode is already open, use one free pass.
Spend that pass on the skip list only.
Close the chat right after that single pass.

Run the gate yourself and trust the exit code.
The pass is only a suggestion you can drop.
The local gate is the decision you keep.

Keep One Command. Park the Rest Until Monday.

Riley Zhang — Fri, 09 Oct 2026 12:58:48 +0000

You sit down with a side project on Saturday morning. You want a tiny health page for one public repo. By noon the plan has three screens and no demo.

That sprawl is the bug you should fix first. A stranger cannot run a pile of half-built ideas. They can run one command that prints one line.

This log is a cut you can copy this weekend. The samples are a plan until you execute them. Trust the output only after a local run.

Set the afternoon fence

You have one afternoon, not a full release train. You may keep one user-facing command in the demo. Every other idea waits in a parked file.

Write the fence before you install a framework. A written fence is harder to bargain with later. Bargaining is how a quiet Saturday demo dies.

Step 1: Park features before you code

Create parked.json before you create the app file. Each row names one feature you refuse today. A skip or defer row needs a plain reason.

[
  {
    "name": "login wall",
    "decision": "skip",
    "why": "a stranger should not create an account"
  },
  {
    "name": "usage chart",
    "decision": "defer",
    "why": "you have no honest data series yet"
  },
  {
    "name": "model inside health command",
    "decision": "skip",
    "why": "the command must run with the network off"
  }
]

Read the third row twice before you move on. The health command must work when the network fails. A helper that requires a live model is not the demo.

Step 2: Freeze one contract

Put the command and the expected line in contract.json. The test should read that file, not a comment. Hidden expectations drift the moment you get tired.

{
  "command": ["python3", "health.py"],
  "expect": "status=ok repo=weekend-cut",
  "max_seconds": 2
}

Two seconds is a ceiling you chose for this laptop. It is not a performance number you should publish. Raise it only if a cold start needs the room.

Point that command only at a script you wrote. Do not let the contract call a shell pipeline. A demo gate should stay boring and easy to read.

Step 3: Write the keep path only

health.py prints one status line and then exits. It does not open a socket on your machine. It does not import a client for any model.

#!/usr/bin/env python3
# Minimal weekend demo. Local only. Proposal until you run it.

import sys

def main() -> int:
    print("status=ok repo=weekend-cut")
    return 0

if __name__ == "__main__":
    sys.exit(main())

That file is the product you ship on Saturday. If the work feels small, the cut is holding. Small is the point of a weekend demo.

Step 4: Reject extra files with a gate

Save the checker below as gate.py in the root. It runs the contract and flags unexpected names. A new filename is a leak unless you allow it.

#!/usr/bin/env python3
# Demo gate. Proposal until you run it on your machine.

import json
import subprocess
import sys
from pathlib import Path

ALLOWED = {
    "health.py",
    "gate.py",
    "contract.json",
    "parked.json",
    "README.md",
}

def main() -> int:
    root = Path(".").resolve()
    extra = []
    for path in root.iterdir():
        if path.name.startswith("."):
            continue
        if path.is_dir():
            extra.append(path.name + "/")
            continue
        if path.name not in ALLOWED:
            extra.append(path.name)
    if extra:
        print("scope leak:", ", ".join(sorted(extra)))
        return 1

    contract = json.loads(Path("contract.json").read_text(encoding="utf-8"))
    command = contract["command"]
    if not isinstance(command, list) or not command:
        print("contract command must be a list")
        return 1
    try:
        proc = subprocess.run(
            command,
            capture_output=True,
            text=True,
            timeout=float(contract["max_seconds"]),
            check=False,
        )
    except subprocess.TimeoutExpired:
        print("demo failed: timeout")
        return 1
    except FileNotFoundError:
        print("demo failed: command not found")
        return 1

    line = proc.stdout.strip()
    if proc.returncode != 0 or line != contract["expect"]:
        print("demo failed")
        print(line)
        return 1
    print("demo passed")
    return 0

if __name__ == "__main__":
    sys.exit(main())

Run the gate from the project root like this.

python3 gate.py

A pass means the printed line matched the contract. A fail means the line changed or a file appeared. Repair the cut before you add a web framework.

On Windows, replace python3 with the launcher you already use. Keep the argument list form so the gate never opens a shell.

Step 5: Read the decision table before you type more

A table keeps the argument shorter than a chat thread. Fill one row per idea before you open an editor. If a row has no reason, it does not ship.

Idea	Call	Why it loses or stays	Demo impact
Login wall	skip	A stranger should not create an account	none
Usage chart	defer	You have no honest series yet	none
Model inside health.py	skip	The command must run offline	none
Status command	keep	This is the Saturday product	the demo
Static HTML page	later	Only after the gate is green	optional
Server upload	later	Same line, no new behavior	optional

Keep means you will finish that row before dinner. Later means the gate must pass before you start. Skip means the idea is out for this weekend.

Step 6: Polish copy only after a green gate

You may want a shorter sentence for a public page. That polish is optional and stays outside the command. The offline line remains the source of truth.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode provides free model access and a free server option. The operator supplied those two availability claims for this draft.

Confirm the live project terms before you depend on them. Do not copy a quota, model name, or duration from memory. This log does not measure limits, hardware, or uptime.

If the docs conflict with this section, follow the docs. Use the model as a copy editor, not an architect. Paste the status line and nothing secret beside it.

Rewrite this status line for a public demo page.
Keep the same facts. Do not add features.
status=ok repo=weekend-cut

Ask for a shorter sentence that keeps the same facts. Drop any rewrite that adds login, charts, or chat. The parked file already closed those doors for today.

A fluent sentence is not permission to reopen them. Keep the model output in your editor until you accept it. Reject the rewrite if it changes the status facts.

Step 7: Host one static file if time remains

Build the page only after the gate prints a pass. The page repeats the same status line in HTML. It does not introduce a second command or form.

<!DOCTYPE html>
<meta charset="utf-8">
<title>weekend cut</title>
<p>status=ok repo=weekend-cut</p>

Add index.html to the allow list only after the first pass. If you use the free server option, upload that file alone. Leave custom domains, analytics, and accounts in the parked list.

Those extras can wait for a later weekend. Read the current MonkeyCode notes only if this cut still fits. Stop if the live terms do not match your constraints.

Step 8: Leave a README a stranger can follow

The README should contain three blocks and no roadmap. Show the health command and the expected status line. Then show the gate command and the pass text.

# weekend cut

Run `python3 health.py`.
You should see `status=ok repo=weekend-cut`.

Run `python3 gate.py`.
You should see `demo passed`.

Read `parked.json` before you add a feature.

Point readers at parked.json before they add a feature. Do not add badges, install matrices, or future promises. A promise list invites the work you already refused.

When the gate fails, debug in this order

If the output says scope leak, read the extra names. Delete them or add them to the allow list on purpose. Do not add names only to silence the checker.

If the output says demo failed, compare the raw line. Match the expect field, including spaces and case. Restore the contract before you edit the HTML page.

If the gate reports a timeout, the command does too much. Remove every network call from health.py before you retry. A weekend health check should not wait on a service.

Rerun this test plan from a clean directory

Run this plan from a clean directory on your machine. Do not skip the failure steps, because they prove the gate. A gate that only passes is a weak gate.

Create an empty directory for this weekend cut.
Add only the files named by the allow list.
Run python3 gate.py and expect a pass message.
Create a file named chart.py beside the gate.
Run the gate again and expect a scope leak.
Delete chart.py before you edit any other file.
Change the printed status line and rerun the gate.
Expect a demo failure until you restore the line.
Request a rewrite only after the gate is green.
Upload the static page only if time still remains.

Do not call this local plan a public benchmark. The timeout is a guard you set for yourself. It says nothing about another machine or a hosted tier.

Limits that stay in force

This cut fits a side project demo, not production traffic. It is the wrong shape for private customer data. It will not carry payments, sessions, or secrets.

Never paste tokens, keys, or private logs into a prompt. Never store credentials inside parked.json or the page. Never let generated copy rewrite the contract for you.

Free model access can change, pause, or narrow without notice. A free server option can carry limits you have not read. Check the current docs on the same day you deploy.

The sample gate only scans the top-level directory. A new subdirectory can hide files from that scan. Tighten the walker before you add a package tree.

A broken contract.json will raise before the gate can help. Fix the JSON before you treat that traceback as a product bug. Validate the file with python3 -m json.tool contract.json.

Treat every sample here as unexecuted proposal code. This draft does not report a timed run from this account. Your local result is the only result that counts.

Who should not use this cut

Skip this cut if you need an uptime promise tonight. Skip it if the demo must touch personal data. Skip it if a team already froze a wider scope.

Also skip the model step when the repo holds client code. A public rewrite can leak more than the status line. Keep that prompt on dummy text if you are unsure.

Close the laptop while the story is still short

You should end Saturday with one green command. The parked list should explain every missing piece. Monday may reopen one deferred row, not the whole list.

That is a finished demo, even when it looks plain. Plain is what you can still explain on Sunday night. Stop while the story still fits in one breath.