Examples

#!/usr/bin/env bash
# A reversible program on a toy card game, offline: the rules and the state are data, the program says
# which card the player plays and why — and `nlir put --alternatives` runs it backwards. Every check is
# asserted. Selections like "the highest card" have many preimages: the program's author says how to go
# back (`_puts`), and the search finds the other consistent explanations, each verified by re-running.
set -euo pipefail
cd "$(dirname "$0")/.."
NLIR=${NLIR:-nlir}
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
run() { "$NLIR" --config config.example.yaml --mode det --quiet --bind game="$1" -f examples/cards.nlir; }
back() { local data=$1 edited=$2; shift 2; printf '%s' "$edited" > "$TMP/edited.json"
  "$NLIR" --config config.example.yaml --mode det put --bind game="$data" -f examples/cards.nlir --edited "$TMP/edited.json" --alternatives 3 --partial --depth 5 "$@" || true; }
check() { python3 -c "$2" "$1" || { echo "FAIL  $3"; exit 1; }; echo "ok    $3"; }
GAME=examples/data/cards.json
python3 -c "import json;d=json.load(open('$GAME'));d['state']['turn']=1;json.dump(d,open('$TMP/later.json','w'))"

# forward
check "$(run $GAME)" 'import sys,json; assert json.loads(sys.argv[1])=={"played_card":5,"reason":"It is the player'"'"'s first turn and 5 is their highest card"}' \
  "forward: first turn, highest card 5"
check "$(run $TMP/later.json)" 'import sys,json; assert json.loads(sys.argv[1])["played_card"]==1' "forward: a later turn, lowest card 1"

# (a) the card becomes 3: the authored put clamps the hand; the search adds other explanations
OUT=$(back $GAME '{"played_card":3,"reason":"It is the player'"'"'s first turn and 5 is their highest card"}')
check "$OUT" 'import sys,json; r=json.loads(sys.argv[1]); a=r["alternatives"][0]
assert a["source"]=="structural" and [(c["path"],c["new"]) for c in a["changes"]]==[("game/state/hand/3",3),("game/state/hand/4",3)], a
assert json.loads(a["output"])["reason"].endswith("3 is their highest card")' "card 5→3: hand [1,2,3,3,3] (authored put), reason follows"

# (b) the reason says lowest: the rule and the hand both have to change
OUT=$(back $GAME '{"played_card":5,"reason":"It is the player'"'"'s first turn and 5 is their lowest card"}')
check "$OUT" 'import sys,json; r=json.loads(sys.argv[1]); a=r["alternatives"][0]; ch={c["path"]:c["new"] for c in a["changes"]}
assert ch["game/rules/1"].endswith("their lowest card.") and all(ch[f"game/state/hand/{i}"]==5 for i in range(4)), ch' \
  "reason says lowest: rule 2 says lowest and the hand becomes [5,5,5,5,5]"

# (c) on a later turn, the card becomes 5: three different explanations
OUT=$(back $TMP/later.json '{"played_card":5,"reason":"It is a later turn and 1 is their lowest card"}')
check "$OUT" 'import sys,json; r=json.loads(sys.argv[1]); ps=[sorted(c["path"] for c in a["changes"]) for a in r["alternatives"]]
assert ["game/rules/2"] in ps and ["game/state/turn"] in ps and any(len(p)==4 and all(x.startswith("game/state/hand/") for x in p) for p in ps), ps' \
  "later turn, card 1→5: rule 3 says highest, OR turn 0, OR hand [5,5,5,5,5]"
OUT=$(back $TMP/later.json '{"played_card":5,"reason":"It is a later turn and 1 is their lowest card"}' --freeze game/rules --freeze game/state/turn)
check "$OUT" 'import sys,json; r=json.loads(sys.argv[1]); assert r["alternatives"] and all(c["path"].startswith("game/state/hand/") for a in r["alternatives"] for c in a["changes"]), r["alternatives"]' \
  "…with the rules and the turn frozen, only the hand can explain it"

# (d) an action the program never outputs: no input can produce it
OUT=$(back $GAME '{"action":"call_uno","reason":"player has one card left"}')
check "$OUT" 'import sys,json; r=json.loads(sys.argv[1]); assert not r["alternatives"] and "never outputs (action)" in r["note"], r["note"]' \
  "call uno: outside what the program can produce — the program itself must change"
echo "cards: all checks passed"

#!/usr/bin/env bash
# The model reads; the evaluator counts. Neither alone does this reliably.
set -euo pipefail
NLIR=${NLIR:-nlir}
show() { printf '\n$ %s\n' "$1"; "$NLIR" --quiet -e "$1"; }
show "{\$0+\$1} ⊘ ['3 apples', '5 oranges', '2 pears']"                     # fuzzy read, exact sum → 10
show "#(\$filter%({\$0 ~> 'a complaint'}, ['love the app', 'it keeps crashing', 'when is dark mode', 'checkout is totally broken']))"
show "urgent={\$0 ~> 'urgent'}; \$if%(#(\$filter%(\$urgent, ['server is down', 'lunch plans', 'payments failing'])) >= 2, 'page on-call', 'queue for morning')"

#!/usr/bin/env bash
# The gap-filled writer end to end (needs a model): read the two lists from an authored text, then write
# every field from the spec plus its lists — K drafts each, trimmed to what states a listed item — and keep
# the draft that covers the lists best. Data: an invented code-review rule from the spec lab, and the guidance
# for its profile format (GUIDE; what each field means — without it, a generic writer scores no better than the
# spec alone).
# Env: NLIR (binary), NLIR_CONFIG (config with a model; default config.example.yaml), NLIR_MODEL, K (default 2),
# GUIDE (default examples/data/code-review-guide.json; empty for none).
set -euo pipefail
cd "$(dirname "$0")/.."
NLIR=${NLIR:-nlir}
K=${K:-2}
GUIDE=${GUIDE-examples/data/code-review-guide.json}
if [ -n "$GUIDE" ]; then G=(--bind "g=$GUIDE"); PRE='gf_guide=$g.guide; gf_field_guides=$g.fields; '; else G=(); PRE=''; fi
"$NLIR" --config "${NLIR_CONFIG:-config.example.yaml}" ${NLIR_MODEL:+--model "$NLIR_MODEL"} --mode llm --quiet \
  -f lib/gapfill.nlir --bind d=examples/data/code-review-rule.json ${G[@]+"${G[@]}"} \
  -e "$PRE""lists=\$gf_extract%(\$d.spec, \$d.authored, \$d.fields); \$json%{lists=\$lists, document=\$gf_document%(\$d.spec, \$lists, \$d.fields, $K)}"

#!/usr/bin/env bash
# Gap-filled specs, offline: lib/gapfill.nlir's deterministic parts, every output checked.
# A spec implies more points than its authors' prose makes, and leaves some decisions open. Two lists per
# field close the gap — named points (implied, singled out) and additions (not implied) — and the library
# writes each field from the spec plus its lists, trims each draft to what states a listed item, and keeps
# the draft that covers the lists best. With a model, see gapfill-pipeline.sh.
set -euo pipefail
cd "$(dirname "$0")/.."
NLIR=${NLIR:-nlir}
LISTS="lists={MET={points=['tests that exercise the change'], additions=['names the test file']}, UNCERTAIN={points=[], additions=[]}}"
run() { "$NLIR" --config config.example.yaml --mode det --quiet -f lib/gapfill.nlir -e "$LISTS; $1"; }
check() {
  local got; got=$(run "$1")
  if [ "$got" != "$2" ]; then printf 'FAIL  %s\n  got:      %s\n  expected: %s\n' "$1" "$got" "$2"; exit 1; fi
  printf 'ok    %-66s → %s\n' "$1" "$got"
}
contains() {
  local got; got=$(run "$1")
  case "$got" in *"$2"*) printf 'ok    %-66s ∋ %s\n' "$1" "$2" ;; *) printf 'FAIL  %s\n  got: %s\n  missing: %s\n' "$1" "$got" "$2"; exit 1 ;; esac
}
# A field's listed items, points first.
check "_sep=',';\$gf_items%(\$lists, 'MET')"                                        "tests that exercise the change,names the test file"
# Coverage scoring: stated + half for partly, less 0.05 per other clause; out-of-range indices ignored.
check "\$gf_score%({stated=[0,1], partly=[2], other=1}, 4)"                         "0.575"
check "\$gf_score%({stated=[0,5], partly=[0], other=0}, 2)"                         "0.5"
check "\$gf_score%({other=2}, 0)"                                                   "-2"
# The pick: the first of the largest scores (pass the list wrapped: % spreads a bare list).
check "\$gf_argmax%[[0.2, 0.9, 0.5, 0.9]]"                                          "1"
# A field with no listed items is never rewritten.
check "\$gf_trim%(\$lists, 'UNCERTAIN', 'Abstain on generated code.')"              "Abstain on generated code."
# The writer's prompt carries the field's lists; k drafts are k distinct prompts (det mode echoes them).
contains "\$gf_write%({rule='r'}, \$lists, 'MET', 1)"                                "NAMED POINTS:"
contains "\$gf_write%({rule='r'}, \$lists, 'MET', 1)"                                "- names the test file"
check "#(\$gf_drafts%({rule='r'}, \$lists, 'UNCERTAIN', 3))"                        "3"
# A field with no listed items is written from the spec alone, never told to add nothing to empty lists.
contains "\$gf_write%({rule='r'}, \$lists, 'UNCERTAIN', 1)"                          "state concisely what the specification requires"
check "_sep=',';\$contains%(\$gf_write%({rule='r'}, \$lists, 'UNCERTAIN', 1), 'NAMED POINTS')" "false"
# Optional guidance (what the document and its fields mean) is prepended only when set, after loading.
check "_sep=',';\$contains%(\$gf_write%({rule='r'}, \$lists, 'MET', 1), 'GUIDANCE')"   "false"
contains "gf_guide='MET describes a violation.'; gf_field_guides={MET='One sentence.'}; \$gf_write%({rule='r'}, \$lists, 'MET', 1)" "FIELD GUIDANCE (MET):"
# Robustness: a failed or unreadable coverage judgement counts as covering nothing ($try); in det mode the
# echoed prompt cannot be parsed, so this exercises the fallback.
check "\$json%\$gf_cover%(\$lists, 'MET', 'draft')"                                 '{"stated":[],"partly":[],"other":0}'
# Deriving a guide from worked examples is one call that names the fields and carries the examples.
contains "\$gf_guide_prompt%([{spec={rule='r'}, document={MET='m'}}], ['MET'])" "field by field (MET)"
echo "gapfill: all checks passed"

#!/usr/bin/env bash
# Backward passes (lenses), offline: edit the prose a program produced and recover
# the spec edit (or program edit) that would produce it. Every result is checked.
set -euo pipefail
cd "$(dirname "$0")/../site/spec-lab"
NLIR=${NLIR:-nlir}
work=$(mktemp -d "${TMPDIR:-/tmp}/nlir-lens.XXXXXX")
trap 'rm -rf "$work"' EXIT
prog='$render%(($node%"CR V 1.1").profile)'
run() { "$NLIR" --mode det --quiet --bind spec=toy-spec.json -f spec.nlir -f profile.nlir -e "$prog"; }
put() { "$NLIR" put --edited "$1" --bind spec=toy-spec.json -f spec.nlir -f profile.nlir "$prog"; }
field() { python3 -c "import json,sys; r=json.load(sys.stdin); e=r['edits']; assert r['put_get'] is True, r; assert len(e)==1, e; print(e[0]['kind'], e[0]['target'], e[0]['changes'][0]['path'] or e[0].get('ast_path'))"; }

run > "$work/out.md"
# 1. A content edit to the MET criterion → the exact spec field.
python3 - "$work/out.md" "$work/content.md" <<'PY'
import sys
lines = open(sys.argv[1]).read().split("\n")
i = lines.index("> MET:") + 1
lines[i] = lines[i].rstrip(".") + ", or on the strength of the author's assurance alone."
open(sys.argv[2], "w").write("\n".join(lines))
PY
got=$(put "$work/content.md" | field)
[ "$got" = "data spec nodes/CR V 1.1/profile/decision_boundary/1" ] || { echo "FAIL content edit: $got"; exit 1; }
echo "ok    prose edit to MET          → $got"
# 2. A template edit to a heading → the program literal that wrote it.
sed 's/#### `decision_boundary`/#### `decision boundary`/' "$work/out.md" > "$work/template.md"
got=$(put "$work/template.md" | field)
case "$got" in "program statement "*) ;; *) echo "FAIL template edit: $got"; exit 1;; esac
echo "ok    heading edit               → $got"
# 3. No edit → no edits (GetPut).
got=$(put "$work/out.md" | python3 -c "import json,sys; r=json.load(sys.stdin); print(len(r['edits']), r['get_put'], r['put_get'])")
[ "$got" = "0 True True" ] || { echo "FAIL get-put: $got"; exit 1; }
echo "ok    unedited output            → no edits (GetPut, PutGet hold)"
echo "lens: all checks passed"

#!/usr/bin/env bash
# The semantic core and the prelude (needs a configured model; outputs vary by model).
set -euo pipefail
NLIR=${NLIR:-nlir}
show() { printf '\n$ %s\n' "$1"; "$NLIR" --quiet -e "$1"; }
show "=>'name three prime numbers, comma-separated'"                    # obey
show "'lmk if any Qs' :: formal"                                        # recast
show "'the release slipped because QA found a migration bug' :: 'a haiku'"
show "'the planets from the sun' .. 3"                                  # project a position
show "'the deploy failed twice on a flaky integration test' .. 'the cause'"
show "!'the release is on track'"                                       # dual
show "'ship Friday' & 'keep the rollback ready'"                        # product
show "a='Ship on Friday.'; b='Ship on Friday, after the security review.'; [\$a Δ \$b, \$a ▷ (\$a Δ \$b)]"
show "'the server keeps crashing' ~> 'this is urgent'"                  # entails
show "'Ship on Friday.' ≈ 'We release at the end of the week.'"         # similarity
# The prelude: everyday rewrites as named forms over :: and ..
show "(\$gist ∘ \$formal) % 'hey so the thing is the cache keeps evicting stuff we still need'"
show "\$question ↦ ['the build is green', 'the migration is reversible']"

#!/usr/bin/env bash
# Patch forward, routed by the rule model's dependencies (site/spec-lab/patch-route.nlir, patch.nlir), offline.
# An edit to the rule model reaches only the profile fields whose derivation reads what it changed: a new fact only
# UNCERTAIN, a new exception or a changed condition only MET and NOT MET, a testing setting only APPLICABILITY. The
# routing is deterministic and checked here; with a model the routed fields get the smallest consistent edit and
# every other field is returned exactly as written.
set -euo pipefail
cd "$(dirname "$0")/.."
NLIR=${NLIR:-nlir}
route() { "$NLIR" --config config.example.yaml --mode det --quiet --bind model=examples/patch/model.json --bind "after=examples/patch/$1.json" -f site/spec-lab/patch-route.nlir -e "$2"; }
check() {
  local got; got=$(route "$1" "$2" | tr '\n' ' ' | sed 's/ *$//')
  if [ "$got" != "$3" ]; then printf 'FAIL  %s %s\n  got:      %s\n  expected: %s\n' "$1" "$2" "$got" "$3"; exit 1; fi
  printf 'ok    %-10s %-24s → %s\n' "$1" "$2" "$got"
}
check fact      '$route'   'UNCERTAIN'
check exception '$route'   'MET NOT MET'
check condition '$route'   'MET NOT MET'
check setting   '$route'   'APPLICABILITY'
check same      '#$route'  '0'
# A changed condition or exception adds a scope instruction for MET and NOT MET (each its own); a new fact adds none.
check condition "\$contains%(\$gate, 'condition')" 'true'
check exception "\$contains%(\$gate, 'exception')" 'true'
check fact      '#$gate'     '0'
# In NOT MET an added exception is stated as an alternative: only when an exception changed.
check exception "\$contains%(\$nmexc, 'one more alternative')" 'true'
check condition '#$nmexc'    '0'
# The tidy drops an echoed label and a trailing bracket the patch added without an opener — and nothing else.
check same '$tidy%("MET", "MET: Approves unread files.)", "Approves unread files.")' 'Approves unread files.'
check same '$tidy%("MET", "Approves (after a skim) unread files.", "Approves unread files.")' 'Approves (after a skim) unread files.'
check same '$tidy%("NOT MET", "Declines (until read).", "Declines (until read).")' 'Declines (until read).'
# Typed backward (lens-typed.nlir): an edit to a field changes only the model groups that field reads.
typed() { "$NLIR" --config config.example.yaml --mode det --quiet --bind model=examples/patch/model.json --bind after=examples/patch/model.json --bind edits=examples/patch/back-fact.json --bind "part=examples/patch/part-$1.json" -f site/spec-lab/patch-route.nlir -f site/spec-lab/lens-typed.nlir -e "$2"; }
check_typed() {
  local got; got=$(typed "$1" "$2" | tr '\n' ' ' | sed 's/ *$//')
  if [ "$got" != "$3" ]; then printf 'FAIL  typed %s %s\n  got:      %s\n  expected: %s\n' "$1" "$2" "$got" "$3"; exit 1; fi
  printf 'ok    typed %-9s %-26s → %s\n' "$1" "$2" "$got"
}
check_typed UNCERTAIN '$map%({$0.group}, $kept)'    'facts'
check_typed UNCERTAIN '$map%({$0.group}, $dropped)' 'conditions'
check_typed MET       '$map%({$0.group}, $kept)'    'conditions'
# Consolidation (consolidate.nlir): only sentences the edits added can be rewritten; the authors' own are out of reach.
cons() { "$NLIR" --config config.example.yaml --mode det --quiet --bind authored=examples/patch/cons-profile.json --bind profile=examples/patch/cons-profile.json --bind edits=examples/patch/cons-edits.json -f site/spec-lab/consolidate.nlir -e "$1"; }
check_cons() {
  local got; got=$(cons "$1" | tr '\n' ' ' | sed 's/ *$//')
  if [ "$got" != "$2" ]; then printf 'FAIL  consolidate %s\n  got:      %s\n  expected: %s\n' "$1" "$got" "$2"; exit 1; fi
  printf 'ok    consolidate %s\n      → %s\n' "$1" "$got"
}
check_cons "\$added%('Approves unread files. Declines.', 'Approves unread files, unless generated. Declines.')" 'Approves unread files, unless generated.'
check_cons "\$apply%(\$valid%([{old='Two, which is long, unless x.', new='Two unless x.'}, {old='One thing.', new='HACK'}], \$added%('One thing. Three.', 'One thing. Two, which is long, unless x. Three.')), 'One thing. Two, which is long, unless x. Three.')" 'One thing. Two unless x. Three.'
check_cons "\$field%'MET'" 'The assistant approves without reading every modified file.'
# Impact across rules (impact.nlir): does a changed definition reach a rule's model? By the defined term, or by a quoted source.
impact() { "$NLIR" --config config.example.yaml --mode det --quiet --bind model=examples/patch/impact-model.json --bind "definition=examples/patch/$1.json" -f site/spec-lab/impact.nlir; }
for pair in "impact-definition:{\"term\":true,\"quoted\":false}" "impact-other:{\"term\":false,\"quoted\":false}"; do
  def=${pair%%:*}; want=${pair#*:}; got=$(impact "$def" | tr -d '\n ')
  if [ "$got" != "$want" ]; then printf 'FAIL  impact %s\n  got:      %s\n  expected: %s\n' "$def" "$got" "$want"; exit 1; fi
  printf 'ok    impact %-18s → %s\n' "$def" "$got"
done
echo "patch: all checks passed"

#!/usr/bin/env bash
# Deterministic replay: model calls are recorded by content address and replayed.
set -euo pipefail
NLIR=${NLIR:-nlir}
store=$(mktemp -t nlir-store.XXXXXX)
trap 'rm -f "$store"' EXIT
expr="=>'Invent a name for a cat that lives with a lighthouse keeper'"
time "$NLIR" --quiet --cache-file "$store" -e "$expr"      # recorded
time "$NLIR" --quiet --cache-file "$store" -e "$expr"      # replayed: identical, instant
"$NLIR" --quiet --cache-file "$store" --replay strict -e "$expr"
"$NLIR" --quiet --cache-file "$store" -e "_seed=1; $expr"  # a new seed draws a fresh sample
"$NLIR" --quiet --cache-file "$store" -e "_sep=' | '; \$draw%({$expr}, 3)"

#!/usr/bin/env bash
# A rule spec as native data: project each rule's profile to prose and parse it back, exactly.
set -euo pipefail
cd "$(dirname "$0")/../site/spec-lab"
NLIR=${NLIR:-nlir}
lab() { "$NLIR" --mode det --quiet --bind spec=toy-spec.json -f spec.nlir -f profile.nlir -e "$1"; }
echo "rules: $(lab '#$leaves')"
lab "\$render%((\$node%'CR V 2.2').profile)" | head -12
echo "…"
lab "ok={\$json%(\$fields%(\$render%((\$node%\$0).profile))) == \$json%((\$node%\$0).profile)}; #(\$filter%(\$ok, \$leaves)) ++ '/' ++ #\$leaves ++ ' rules round-trip exactly'"

#!/usr/bin/env bash
# The structural core, offline: every line is checked.
set -euo pipefail
cd "$(dirname "$0")/.."
NLIR=${NLIR:-nlir}
run() { "$NLIR" --config config.example.yaml --mode det --quiet -e "$1"; }
check() {
  local got; got=$(run "$1")
  if [ "$got" != "$2" ]; then printf 'FAIL  %s\n  got:      %s\n  expected: %s\n' "$1" "$got" "$2"; exit 1; fi
  printf 'ok    %-58s → %s\n' "$1" "$got"
}
check "_sep=',';{\$0*\$0} ↦ [1,2,3]"                         "1,4,9"           # Functor map
check "{\$0+\$1} ⊘ (1..100)"                                  "5050"            # Foldable fold
check "_sep=',';[1,2] ++ [3]"                                 "1,2,3"           # Monoid: lists
check "_sep=',';{a=1,b=2} ++ {b=3,c=4}"                       "a=1,b=3,c=4"     # Monoid: dicts, right-biased
check "++[a,b,c]"                                             "abc"             # mconcat
check "'ab' _ 3"                                              "ababab"          # Monoid power
check "({\$0+1} _ 3) % 5"                                     "8"               # a form composed with itself
check "inc={\$0+1}; dbl={\$0*2}; (\$dbl ∘ \$inc) % 5"            "12"              # composition
check "#[a,b,c] + #{k=v} + #'abcd'"                           "8"               # length, polymorphic
check "[Mercury,Venus,Earth,Mars].2"                          "Earth"           # lens get
check "orders=[{who=ada,total=12.5},{who=bo,total=40},{who=cy,total=7}];\$join%({\$0.who} ↦ (\$filter%({\$0.total>=10},\$orders)),', ')" "ada, bo"
check "\$if%(3 < 5, yes, no)"                                  "yes"
echo "structure: all checks passed"