examples: add 11_fallback_showcase.rb — runnable 'aha moment' demo

[justi]

Adds the lowest-friction entry point for evaluating the gem: a runnable showcase that prints the fallback loop end-to-end, with zero API keys.

What it does

ruby examples/11_fallback_showcase.rb runs two contrasting steps in sequence:

Part A — without the contract's validate("not a refusal")
The Test adapter returns in-schema refusal JSON ({"tldr": "I cannot help..."}). Schema passes. The refusal is what parsed_output hands back — demonstrating exactly what happens in production without a contract.

Part B — with the full SummarizeArticle + retry_policy
Test adapter returns [REFUSAL_RESPONSE, GOOD_RESPONSE]. Attempt 1 (gpt-4.1-nano) rejected by validate, attempt 2 (gpt-4.1-mini) succeeds. Output includes the per-attempt trace so the escalation is visible, not described.

Sample output:

======================================================================
A — Without the contract's 'not a refusal' validate:
======================================================================
status:       :ok            # schema passes — no guard
tldr shipped: "I cannot help with that request."
              ^^ this would render into the UI card, apologising to the user

======================================================================
B — With the contract + retry_policy fallback:
======================================================================
status:             :ok
final model:        "gpt-4.1-mini"
total attempts:     2

Per-attempt trace:
  attempt 1  model=gpt-4.1-nano   status=validation_failed
  attempt 2  model=gpt-4.1-mini   status=ok

Why this file, in this location

Real-user feedback: "hard to understand what the gem gives me". The why.md guide (shipped in #21) describes the failure modes; this showcase lets developers see the fallback loop run in 30 seconds before committing to reading docs.

bin/demo is not a Ruby convention (standard is bin/console / bin/setup via bundle gem). This project already has examples/*.rb as runnable showcases — placing the demo there matches the existing pattern.

No version bump

Per instruction: docs + examples only, gem stays at 0.7.2.

[Copilot]

Pull request overview

Adds a runnable “aha moment” fallback demo and aligns docs/output terminology around model fallback (including updated summary output labels and refreshed guides).

Changes:

• Add examples/11_fallback_showcase.rb plus examples index updates to provide a zero-API-key runnable fallback demonstration.
• Rename retry-optimizer / model-comparison terminal labels to “fallback” terminology (and adjust specs accordingly).
• Large documentation refresh across guides (new “Why contracts?” guide, rewrites/edits to Getting Started / Testing / Pipeline / Schema / Optimization, etc.) and bump release metadata to 0.7.2.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
spec/ruby_llm/contract/eval/retry_optimizer_spec.rb	Updates assertions for renamed summary labels.
lib/ruby_llm/contract/version.rb	Bumps gem version to 0.7.2.
lib/ruby_llm/contract/eval/retry_optimizer.rb	Renames summary labels and adds hardest_eval alias.
lib/ruby_llm/contract/eval/model_comparison.rb	Renames production-mode table headers and adjusts column widths.
examples/README.md	Updates examples index and adds fallback showcase entry.
examples/11_fallback_showcase.rb	New runnable fallback/refusal + retry_policy demonstration using Test adapter.
docs/guide/why.md	New “Why contracts?” guide with failure-mode framing and pointers to the showcase.
docs/guide/testing.md	Refines testing guide examples and guidance.
docs/guide/prompt_ast.md	Expands prompt-AST guide with richer narrative/examples.
docs/guide/pipeline.md	Updates pipeline guide to the SummarizeArticle narrative.
docs/guide/output_schema.md	Fixes DSL constraint keyword docs (snake_case) and refines narrative.
docs/guide/optimizing_retry_policy.md	Major rewrite around “cheapest viable fallback list” workflow.
docs/guide/migration.md	Updates migration examples and adds cross-links.
docs/guide/getting_started.md	Rewrites walkthrough using SummarizeArticle consistently.
docs/guide/eval_first.md	Refines eval-first narrative and examples.
docs/guide/best_practices.md	Updates validate patterns and “fallback” terminology.
docs/architecture.md	Updates architecture terminology and module layout docs.
README.md	Adds “Do I need this?” and updates docs index and narrative.
Gemfile.lock	Updates locked gem version to 0.7.2.
CHANGELOG.md	Adds 0.7.2 entry documenting changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

PR description says there is "No version bump" and the gem stays at 0.7.2, but this change bumps VERSION from 0.7.1 to 0.7.2 (and Gemfile.lock / CHANGELOG are updated accordingly). Please reconcile by either updating the PR description to reflect the version bump or dropping the version change if it’s not intended for this PR.

[Copilot]

In the 00_basics step table, “2-arity validates” reads like a verb; for clarity and consistency with the rest of the docs/examples, consider renaming this to “2-arity validate blocks” or “2-arity validations”.

Suggested change

	| 8 | 2-arity validates | Cross-validate output against input |
	| 8 | 2-arity validate blocks | Cross-validate output against input |

[Copilot]

Several sentences use “validates” as a noun (e.g., “score consistency validates”, “2-arity validates”, “cross-field validates”), which is ungrammatical and a bit confusing in a docs index. Suggest changing to “validation”, “validate checks”, or “validate blocks” for each of these phrases.

[Copilot]

The “Running” section says examples 07–10 use the test adapter by default, but 11_fallback_showcase.rb is also test-adapter-only. Also, the comment “Real LLM — requires Ollama or API key” doesn’t match example 04’s stated requirement (provider API key). Please update this section so the adapter requirements are accurate and consistent.

Suggested change

	Examples 00–03, 05, 07–10 use the test adapter by default — no API keys needed.
	Example 04 requires an API key.
	Examples 00–03, 05, 07–11 use the test adapter by default — no API keys needed.
	Example 04 requires Ollama or a provider API key.

[Copilot]

The prompt AST example’s few-shot output: string isn’t valid JSON ([... ] / ...). Since the surrounding text says “Return valid JSON only”, this is easy to copy/paste into a prompt and accidentally teach invalid JSON. Consider making the example output syntactically valid JSON (using real placeholder strings/arrays).

Suggested change

	output: '{"tldr":"...","takeaways":[...],"tone":"analytical"}'
	output: '{"tldr":"Placeholder summary","takeaways":["Placeholder takeaway 1","Placeholder takeaway 2"],"tone":"analytical"}'

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The comment now implies that running the “Real LLM” example always requires a provider API key, but this repo/gem also supports running via Ollama (no API key). Consider adjusting the wording to include Ollama as an option to avoid misleading users.

[Copilot]

Spelling inconsistency: this message uses UK spelling (“apologising”), but the rest of the repo/docs use US spelling (e.g., “behavior”). Consider changing to “apologizing” for consistency.

Suggested change

	puts " ^^ this would render into the UI card, apologising to the user"
	puts " ^^ this would render into the UI card, apologizing to the user"

[Copilot]

REFUSAL_PATTERN is hard to read/modify as a single long regex line. Consider rewriting it using extended regex mode (/x) or composing from an array of prefix patterns so future tweaks (adding phrases/providers) are less error-prone.

Suggested change

	REFUSAL_PATTERN = /\A(i\s+(cannot|can.?t|am unable|apologi[sz]e)|i['\s]?m\s+(unable|sorry)|sorry\b|as an ai)/i.freeze
	REFUSAL_PREFIX_PATTERNS = [
	"i\\s+(?:cannot|can.?t|am unable|apologi[sz]e)",
	"i['\\s]?m\\s+(?:unable|sorry)",
	"sorry\\b",
	"as an ai"
	].freeze
	REFUSAL_PATTERN = /\A(?:#{Regexp.union(REFUSAL_PREFIX_PATTERNS).source})/i.freeze