# Shvydko application cookbooks

Seven original workflows, Python 3.10+ and the standard library only. No package installation is required. Download and unpack the archive, then run commands from its directory.

The fixtures are fictional English business inputs. `author_expectation` describes the author's intended outcome; it is not a model answer. **No synthetic API responses ship in this bundle.** These are application examples, not customer case studies or quality, safety, speed or cost benchmarks. The 0.90 threshold is an illustrative application policy and must be evaluated on your own data.

## Three modes

```sh
# Offline request plan: no key, network, or model answers.
python3 runner.py rag-citations

# Explicit live execution. Set SHVYDKO_API_KEY in your local/server environment first.
# Account quotas and current billing apply. No browser key handling.
python3 runner.py rag-citations --live --output rag-run.json

# Recompute application decisions using your saved responses. No network calls.
python3 runner.py rag-citations --replay rag-run.json
```

The live endpoint is fixed to `https://shvydko.ai/v1/systemone`. Redirects are rejected. Requests use `state` and `questions` with Choice, Score or Noul. The runner performs no external action besides this explicit API call: no messages, purchases, refunds, external tools or source-document fetching.

Reports preserve exact requests and received responses, response usage when available, and measured client round-trip time. Missing usage remains unknown, never zero. Reports are created with mode 0600 on POSIX and never overwrite existing paths. Reserve a writable new path before running. If you replace fixtures with your own data, those data are included in the report: keep it private. Windows file permissions depend on your environment.

Requests are sequential, have a 30-second transport timeout, and are never automatically retried. HTTP/network/validation failures stop further work. A request interrupted or timed out may have been charged: inspect console Usage before sending it again. `--max-requests N` can lower the per-run budget (1–12). A budget limit can leave a workflow incomplete; the report records this.

Replay verifies recipe identity, a fixture hash, exact request content, response shape and request order. It reuses the original elapsed times; it does not present fast local replay time as model latency. A local JSON file is editable, so replay is **not cryptographic proof** that responses came from the service. A failed/partial live report can be inspected and replayed up to the failure without making further calls.

## Workflows

| Recipe | Max API calls | Pipeline and explicit limits |
|---|---:|---|
| `rag-citations` | 1 | Exact quote/source check in code, per-passage relevance/support/instruction flags, citation verdict, then evidence review. No answer generator or full retrieval system. |
| `value-extraction` | 1 | Regex candidate spans, calendar validation, Choice selection, exact source copy and Decimal normalization. Only USD decimal amounts and ISO dates; invalid dates are removed before inference. |
| `hierarchical-routing` | 2 | Parent selection, one conditional child request, parent-level review fallback. The offline plan shows both possible child branches; only one is called. No beam search. |
| `tool-routing` | 1 | Allowlisted tool and order ID, separate mutation-intent gate, fixed read-only local dictionary lookup. No eval, arbitrary tool execution, or real orders. |
| `search-reranking` | 1 | Simple lexical shortlist of three documents, independent Score questions, deterministic sorting and a no-confident-match result. Retrieval recall and ranking quality are not measured. |
| `repeatability-batching` | 12 | Three repetitions of one three-question batch versus three individual calls, alternating order. Raw responses/usage/times, matched choices, planned/attempted/not-run counts. Stops on first error. Agreement is not accuracy, and this small sample does not establish a speed advantage. |
| `moderation` | 3 | Bounded sequential classification of three messages; show/hold/review plus question flag. Local decisions only, no Twitch/messenger integration or content deletion. |

Inspect `runner.py` and `fixtures.json`, then adapt inputs and policy deliberately. For the repeatability recipe, `repetitions` is limited to 2 or 3. Edited fixtures must still respect the API contract and context capacity; read `/v1/models` before expanding to long documents. Each request is limited to 32 questions and 2 MiB by this example runner.

## Expected outputs and tests

Offline plans are included in `plans.json` and contain no model answers. The project repository includes controlled tests for branch selection, review fallbacks, exact spans, invalid replies, replay mismatches, request budgets, unknown usage, and HTTP failure handling. Those injected test answers test application behavior only; they are not a Shvydko quality evaluation. Live model quality must be tested separately on representative data.

Use the console evaluation runner for a labeled JSONL set: https://shvydko.ai/console/evaluations. Public contract: https://shvydko.ai/openapi.json. API guide: https://shvydko.ai/docs/api/systemone.