feat(recipes): add explainable-routing recipe and example (#115)

[linfangw]

Closes #115. Advances the explainable-routing sub-task of #65.

What

A recipe that makes a transparent, cost-aware capability choice — the QVeris differentiator in practice. Instead of blindly taking the first result, the agent compares candidates on the routing signals QVeris returns (why_recommended, expected_cost, success rate, latency), selects one, and explains the decision before spending credits.

Contents

• recipes/explainable-routing/ — README.md (CLI + Python SDK paths) and a qveris.manifest.json (validated by scripts/validate-ecosystem-manifests.mjs, 6/6 ok).
• packages/python-sdk/examples/explainable_routing.py — prints a candidate comparison table, then applies two bounded overrides on top of the backend ranking:
  1. Cost saving — a much cheaper candidate (≤50% cost) that is no less reliable.
  2. Reliability upgrade — a candidate that costs no more but is meaningfully more reliable (≥5 pts higher success).
     It never trades a large cost increase for reliability. The choose(...) helper is copy-pasteable into a real agent loop.
• Indexed in recipes/README.md and the python-sdk examples tables (en-US / zh-CN / cn/zh-CN) + package README.

Verification

Ran live against production (discovery only, no credits spent):

Selected: Quote
Reason:   chose a more reliable capability at no extra cost — 73.1% vs 59.2% success for the same ~1 credits.

• python -m compileall qveris examples clean (matches the publish workflow step)
• node scripts/validate-ecosystem-manifests.mjs — 6/6 ok
• CLI path verified: qveris discover --json passes through why_recommended / expected_cost / stats for the jq comparison

Compatibility

Requires the routing fields shipped in #102: python_sdk >=0.2.1, cli >=0.6.0, mcp >=0.7.0 (declared in the manifest).

[gemini-code-assist]

Code Review

This pull request introduces an 'Explainable Routing' recipe and a runnable Python example (explainable_routing.py) that demonstrates how to discover, compare, and select candidate capabilities based on cost and reliability signals. It also updates the relevant documentation across multiple languages to include this new recipe. The review feedback highlights two important issues in the selection logic: first, the choose function should gracefully handle empty lists to prevent an IndexError; second, defaulting missing success rates to 0.0 can lead to incorrect routing decisions, so the algorithm should skip overrides when quality statistics are missing.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The choose function assumes that the tools list is non-empty. If an empty list is passed, it will raise an IndexError at top = tools[0]. Since this helper is designed to be copy-pasteable into real agent loops, it should handle the empty list case gracefully (e.g., by raising a clear ValueError or returning a default value).

Suggested change

	top = tools[0]
	if not tools:
	raise ValueError("The tools list cannot be empty.")
	top = tools[0]

[linfangw]

Addressed the /review findings (commit 42120eb):

1. [CRITICAL] Python 3.8 import break — the list[ToolInfo] / tuple[...] annotations are evaluated at def-time and would raise TypeError: 'type' object is not subscriptable on 3.8/3.9 (PEP 585 is 3.9+), which compileall (syntax-only) and the 3.10–3.12 CI matrix both miss. Added from __future__ import annotations (matching the stock_debate.py precedent) — annotations are now lazy strings, safe on the declared >=3.8 floor.
2. [IMPORTANT] success_rate or 0.0 collapsed unknown→0.0 — the reason string could claim "0.0% success" for a tool the comparison table shows as "n/a", and an unknown top reliability could trip a false "reliability upgrade". choose() now keeps None distinct and skips the cost/reliability comparison when either side's success is unknown, falling back to the backend pick.
3. [IMPORTANT] qveris usage --summary is a no-op (summary is the default; the flag is silently ignored) — dropped it.
4. [SUGGESTION] --search-id on inspect/call is a deprecated alias — switched the CLI examples to the canonical --discovery-id (value still comes from discover's search_id).

Re-verified: compileall clean, validate-ecosystem-manifests 6/6, and a live production run still produces the correct explanation (73.1% vs 59.2% success for the same ~1 credits) with real percentages — no None contradiction.