docs(examples): address cubic review comments on PR #37

[0xvasanth]

Summary

Follow-up to #37 (now merged). Cubic flagged 12 issues; all verified valid and fixed.

(Supersedes #38, which had merge conflicts because it was branched from a stale base. This PR is a clean cherry-pick of the same commit onto current main.)

P1 — CI signal

• obs_evaluation — regression failures now std::process::exit(1) so a CI runner job actually goes red. Was just printing a warning and exiting 0.

P2 — examples that didn't deliver what their scenario claimed

• state_machine — job_done was hardcoded attempt >= 3, so the timeout (gave_up) branch was unreachable. Reshaped into two runs sharing one node_fn: first stub completes on attempt 3 (success path), second stub never returns true (timeout path, gave_up = true). Both branches now exercised.
• models_embedding — FakeEmbeddings produced deterministic-but-not-semantic vectors, so the "keyboard wins the typing query" claim was hollow. Swapped to OllamaEmbeddings("nomic-embed-text"). Real ranking: keyboard 0.705, hiking 0.356, mug 0.334.
• retrieval_rag_pipeline — same FakeEmbeddings issue. Swapped to OllamaEmbeddings. Top-1 retrieval now correctly picks the cognis-rag doc.
• chains_structured_extraction — parser.parse(...) errors were swallowed with eprintln! and the example still exited 0. Now propagates with ?.
• reranking_retriever — score parsing took only the first whitespace token, defaulting to 0.0 when the model wrote prose ("Score: 7.5", "I'd say 8 / 10"). 0.0 catastrophically demotes a doc just because the reranker model padded its reply. Now sweeps the response for the first numeric token in [0.0, 10.0] and falls back to a neutral 5.0.
• docs/mintlify/examples/parsers.mdx — parsers_retry row claimed it "re-runs the entire prompt with stricter guidance"; the implementation loops fixer + parse cycles. Rephrased.

P3 — documentation accuracy

• docs/mintlify/examples/quickstart.mdx — claimed all 8 V2 demos default to local Ollama. 01 and 05 are pure-Rust offline. Fixed.
• semantic_router — scenario said "ends with ?"; code is contains('?'). Fixed scenario text.
• tool_orchestrator — header said "sequential ~240ms"; example runs three 100ms vendor calls so baseline is ~300ms. Fixed.
• structured_parsing_demo — sample output block had compiler dead-code warnings as if they were part of the example output. Stripped + added #[allow(dead_code)] on Sentiment (Debug-printed only).
• error_handling — comment claimed a typed Validation error, but the code emits CognisError::Internal. Updated to match.

Test plan

• All 10 affected examples run end-to-end against COGNIS_PROVIDER=ollama COGNIS_OLLAMA_MODEL=llama3.1 with the intended behavior captured in their headers.
• cargo build -p cognis-examples clean.
• cargo fmt --all --check passes.
• Mintlify / cubic checks will run on the PR.

---

Summary by cubic

Fixes 12 Cubic review findings from PR #37 to make examples behave as described and to surface failures in CI. CI now fails on regressions, and embeddings-based demos use real OllamaEmbeddings for meaningful results.

• Bug Fixes

  • CI: obs_evaluation exits with code 1 when tests regress.
  • Embeddings: replaced fake vectors with OllamaEmbeddings("nomic-embed-text") in models_embedding and retrieval_rag_pipeline so rankings and retrievals are real.
  • State machine: runs both success (finishes on attempt 3) and timeout paths; previously the timeout branch was unreachable.
  • Structured extraction: propagate parser.parse(...) errors with ? so failures aren’t silently ignored.
  • Reranker: robust score parsing (find first number in 0–10 range; fallback to 5.0) to prevent accidental zeroing.

• Documentation

  • Quickstart: clarified which V2 demos are LLM-backed vs offline; parsers.mdx: corrected RetryParser description.
  • Example comments: semantic_router scenario matches contains('?'); tool_orchestrator baseline corrected to ~300ms.
  • Output/sample notes: removed compiler warnings from structured_parsing_demo and added #[allow(dead_code)]; error_handling comment updated to match CognisError::Internal.

^{Written for commit 4e4fe32. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 12 files

_{You’re at about 97% of the daily review limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cognis	🟢 Ready	View Preview	May 8, 2026, 5:27 PM