fast-mode-kit 0.2.0__tar.gz

fast_mode_kit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fast-mode-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fast_mode_kit-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: fast-mode-kit
+Version: 0.2.0
+Summary: Starter kit for adding a fast, data-only answer mode to any chat agent
+License: MIT
+Keywords: llm,agents,latency,tool-calling,evals
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# fast-mode-kit
+
+A starter kit for adding a **Fast mode** to any chat agent. Fast mode answers exactly what was asked, from your data, right the first time, in a few seconds.
+
+It comes from shipping Fast mode in a live product. Every rule here traces back to a measured result or a real failure, and the [failure catalogue](docs/08-failure-catalogue.md) lists them.
+
+It works with **frontier APIs** (any OpenAI-compatible endpoint) and with **models you host yourself** (mlx, vLLM, Ollama, llama.cpp).
+
+## Quick start (offline, no key, no cost)
+
+```bash
+pip install fast-mode-kit
+
+fastkit demo "rank products by revenue"     # the example shop agent, offline
+fastkit eval                                # accuracy, latency, cost and fallback report
+fastkit init my-agent                       # your own Fast mode project
+cd my-agent && python agent.py "how many widgets in stock?"
+```
+
+The offline stand-in model picks tools by word overlap and has no understanding, so the example scores about 40% on `fastkit eval`. That is expected: it shows what keyword routing gets you. A real model fills the gap.
+
+## With a real model
+
+```bash
+export FASTKIT_API_KEY=...          # leave unset for local servers (Ollama, vLLM, mlx, llama.cpp)
+
+# 1. One tiny request: is this model fast enough, and does it call tools?
+fastkit check --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash
+
+# 2. Measure your agent on your questions, with a spend cap
+fastkit eval --agent agent.py --gold gold.jsonl \
+    --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash \
+    --price-in 0.30 --price-out 2.50 --spend-cap 0.50
+```
+
+`fastkit check` prints PASS, SLOW or FAIL against the 4.5 s first-words budget and tells you whether the model called the tool. A model that answers without calling it can't run the one-call loop.
+
+`fastkit.checks.safe_filter` runs after the answer has finished. Use it in evals and logs, or buffer the output if you want to filter before the user sees it.
+
+## Develop
+
+```bash
+git clone <this repo> && cd fast-mode-kit
+pip install -e ".[dev]" && pytest -q        # every test runs against a mock model
+```
+
+## What's inside
+
+| Path | What it is |
+|---|---|
+| `docs/` | the guide, chapters 1-9: what Fast is, architecture, deadlines, prompts, checks, model choice, self-hosting, failure catalogue, measuring |
+| `fastkit/templates/` | prompt templates: Fast system, reader, writer, server-owned lines |
+| `fastkit/client.py` | streaming client for any OpenAI-compatible server |
+| `fastkit/loop.py` | the one-call loop: read, call tools and write in one conversation, with a fallback |
+| `fastkit/pipeline.py` | the fallback: a reader plans, the server fetches, a writer answers |
+| `fastkit/hedge.py` | hedged routes; a stream that has started is never cut |
+| `fastkit/tools.py` | tool registry, `find_tools`, `note_turn`, propose/confirm writes |
+| `fastkit/checks.py` | do-no-harm figure checks |
+| `fastkit/modes.py` | Fast-only gate |
+| `fastkit/mock.py` | scripted model for offline tests |
+| `fastkit/examples/shop/` | a complete agent over a toy shop database |
+| `fastkit/evals/` | gold-set runner, report and spend cap |
+| `fastkit/cli.py` | the `fastkit` command: demo, init, check, eval |
+| `fastkit/scaffold/` | the starter project `fastkit init` writes |
+
+## Adapt it to your domain in 5 steps
+
+1. **Tools:** write read tools that return rows with every derived figure already computed (totals, ranks, percentages), plus propose tools for writes. See `fastkit/examples/shop/tools.py`.
+2. **Prompt:** render `fastkit/templates/fast_system.md` with your domain and tool list.
+3. **Loop:** call `fast_answer(...)` with your model and a pipeline fallback. See `fastkit/examples/shop/agent.py`.
+4. **Gold set:** write 40-60 real questions with their expected figures, across the languages your users write in.
+5. **Measure:** run `fastkit eval` on two or three models and pick by tail latency and per-language accuracy, not by the median.
+
+## The rules in one screen
+
+- No second chance in Fast, so the first answer must be right.
+- One line per asked part, figure first, data only.
+- The server computes every figure. The model copies.
+- Fall back to another model path, never to keyword guesses.
+- A deadline never cuts an answer that has started streaming.
+- A check that edits a correct line is a bug in the check.
+- Keep Fast changes behind one gate, and prove the other modes unchanged.
+- Never judge a reading model with thinking switched off.
+
+## License
+
+MIT

fast_mode_kit-0.2.0/README.md

@@ -0,0 +1,87 @@
+# fast-mode-kit
+
+A starter kit for adding a **Fast mode** to any chat agent. Fast mode answers exactly what was asked, from your data, right the first time, in a few seconds.
+
+It comes from shipping Fast mode in a live product. Every rule here traces back to a measured result or a real failure, and the [failure catalogue](docs/08-failure-catalogue.md) lists them.
+
+It works with **frontier APIs** (any OpenAI-compatible endpoint) and with **models you host yourself** (mlx, vLLM, Ollama, llama.cpp).
+
+## Quick start (offline, no key, no cost)
+
+```bash
+pip install fast-mode-kit
+
+fastkit demo "rank products by revenue"     # the example shop agent, offline
+fastkit eval                                # accuracy, latency, cost and fallback report
+fastkit init my-agent                       # your own Fast mode project
+cd my-agent && python agent.py "how many widgets in stock?"
+```
+
+The offline stand-in model picks tools by word overlap and has no understanding, so the example scores about 40% on `fastkit eval`. That is expected: it shows what keyword routing gets you. A real model fills the gap.
+
+## With a real model
+
+```bash
+export FASTKIT_API_KEY=...          # leave unset for local servers (Ollama, vLLM, mlx, llama.cpp)
+
+# 1. One tiny request: is this model fast enough, and does it call tools?
+fastkit check --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash
+
+# 2. Measure your agent on your questions, with a spend cap
+fastkit eval --agent agent.py --gold gold.jsonl \
+    --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash \
+    --price-in 0.30 --price-out 2.50 --spend-cap 0.50
+```
+
+`fastkit check` prints PASS, SLOW or FAIL against the 4.5 s first-words budget and tells you whether the model called the tool. A model that answers without calling it can't run the one-call loop.
+
+`fastkit.checks.safe_filter` runs after the answer has finished. Use it in evals and logs, or buffer the output if you want to filter before the user sees it.
+
+## Develop
+
+```bash
+git clone <this repo> && cd fast-mode-kit
+pip install -e ".[dev]" && pytest -q        # every test runs against a mock model
+```
+
+## What's inside
+
+| Path | What it is |
+|---|---|
+| `docs/` | the guide, chapters 1-9: what Fast is, architecture, deadlines, prompts, checks, model choice, self-hosting, failure catalogue, measuring |
+| `fastkit/templates/` | prompt templates: Fast system, reader, writer, server-owned lines |
+| `fastkit/client.py` | streaming client for any OpenAI-compatible server |
+| `fastkit/loop.py` | the one-call loop: read, call tools and write in one conversation, with a fallback |
+| `fastkit/pipeline.py` | the fallback: a reader plans, the server fetches, a writer answers |
+| `fastkit/hedge.py` | hedged routes; a stream that has started is never cut |
+| `fastkit/tools.py` | tool registry, `find_tools`, `note_turn`, propose/confirm writes |
+| `fastkit/checks.py` | do-no-harm figure checks |
+| `fastkit/modes.py` | Fast-only gate |
+| `fastkit/mock.py` | scripted model for offline tests |
+| `fastkit/examples/shop/` | a complete agent over a toy shop database |
+| `fastkit/evals/` | gold-set runner, report and spend cap |
+| `fastkit/cli.py` | the `fastkit` command: demo, init, check, eval |
+| `fastkit/scaffold/` | the starter project `fastkit init` writes |
+
+## Adapt it to your domain in 5 steps
+
+1. **Tools:** write read tools that return rows with every derived figure already computed (totals, ranks, percentages), plus propose tools for writes. See `fastkit/examples/shop/tools.py`.
+2. **Prompt:** render `fastkit/templates/fast_system.md` with your domain and tool list.
+3. **Loop:** call `fast_answer(...)` with your model and a pipeline fallback. See `fastkit/examples/shop/agent.py`.
+4. **Gold set:** write 40-60 real questions with their expected figures, across the languages your users write in.
+5. **Measure:** run `fastkit eval` on two or three models and pick by tail latency and per-language accuracy, not by the median.
+
+## The rules in one screen
+
+- No second chance in Fast, so the first answer must be right.
+- One line per asked part, figure first, data only.
+- The server computes every figure. The model copies.
+- Fall back to another model path, never to keyword guesses.
+- A deadline never cuts an answer that has started streaming.
+- A check that edits a correct line is a bug in the check.
+- Keep Fast changes behind one gate, and prove the other modes unchanged.
+- Never judge a reading model with thinking switched off.
+
+## License
+
+MIT

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: fast-mode-kit
+Version: 0.2.0
+Summary: Starter kit for adding a fast, data-only answer mode to any chat agent
+License: MIT
+Keywords: llm,agents,latency,tool-calling,evals
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# fast-mode-kit
+
+A starter kit for adding a **Fast mode** to any chat agent. Fast mode answers exactly what was asked, from your data, right the first time, in a few seconds.
+
+It comes from shipping Fast mode in a live product. Every rule here traces back to a measured result or a real failure, and the [failure catalogue](docs/08-failure-catalogue.md) lists them.
+
+It works with **frontier APIs** (any OpenAI-compatible endpoint) and with **models you host yourself** (mlx, vLLM, Ollama, llama.cpp).
+
+## Quick start (offline, no key, no cost)
+
+```bash
+pip install fast-mode-kit
+
+fastkit demo "rank products by revenue"     # the example shop agent, offline
+fastkit eval                                # accuracy, latency, cost and fallback report
+fastkit init my-agent                       # your own Fast mode project
+cd my-agent && python agent.py "how many widgets in stock?"
+```
+
+The offline stand-in model picks tools by word overlap and has no understanding, so the example scores about 40% on `fastkit eval`. That is expected: it shows what keyword routing gets you. A real model fills the gap.
+
+## With a real model
+
+```bash
+export FASTKIT_API_KEY=...          # leave unset for local servers (Ollama, vLLM, mlx, llama.cpp)
+
+# 1. One tiny request: is this model fast enough, and does it call tools?
+fastkit check --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash
+
+# 2. Measure your agent on your questions, with a spend cap
+fastkit eval --agent agent.py --gold gold.jsonl \
+    --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash \
+    --price-in 0.30 --price-out 2.50 --spend-cap 0.50
+```
+
+`fastkit check` prints PASS, SLOW or FAIL against the 4.5 s first-words budget and tells you whether the model called the tool. A model that answers without calling it can't run the one-call loop.
+
+`fastkit.checks.safe_filter` runs after the answer has finished. Use it in evals and logs, or buffer the output if you want to filter before the user sees it.
+
+## Develop
+
+```bash
+git clone <this repo> && cd fast-mode-kit
+pip install -e ".[dev]" && pytest -q        # every test runs against a mock model
+```
+
+## What's inside
+
+| Path | What it is |
+|---|---|
+| `docs/` | the guide, chapters 1-9: what Fast is, architecture, deadlines, prompts, checks, model choice, self-hosting, failure catalogue, measuring |
+| `fastkit/templates/` | prompt templates: Fast system, reader, writer, server-owned lines |
+| `fastkit/client.py` | streaming client for any OpenAI-compatible server |
+| `fastkit/loop.py` | the one-call loop: read, call tools and write in one conversation, with a fallback |
+| `fastkit/pipeline.py` | the fallback: a reader plans, the server fetches, a writer answers |
+| `fastkit/hedge.py` | hedged routes; a stream that has started is never cut |
+| `fastkit/tools.py` | tool registry, `find_tools`, `note_turn`, propose/confirm writes |
+| `fastkit/checks.py` | do-no-harm figure checks |
+| `fastkit/modes.py` | Fast-only gate |
+| `fastkit/mock.py` | scripted model for offline tests |
+| `fastkit/examples/shop/` | a complete agent over a toy shop database |
+| `fastkit/evals/` | gold-set runner, report and spend cap |
+| `fastkit/cli.py` | the `fastkit` command: demo, init, check, eval |
+| `fastkit/scaffold/` | the starter project `fastkit init` writes |
+
+## Adapt it to your domain in 5 steps
+
+1. **Tools:** write read tools that return rows with every derived figure already computed (totals, ranks, percentages), plus propose tools for writes. See `fastkit/examples/shop/tools.py`.
+2. **Prompt:** render `fastkit/templates/fast_system.md` with your domain and tool list.
+3. **Loop:** call `fast_answer(...)` with your model and a pipeline fallback. See `fastkit/examples/shop/agent.py`.
+4. **Gold set:** write 40-60 real questions with their expected figures, across the languages your users write in.
+5. **Measure:** run `fastkit eval` on two or three models and pick by tail latency and per-language accuracy, not by the median.
+
+## The rules in one screen
+
+- No second chance in Fast, so the first answer must be right.
+- One line per asked part, figure first, data only.
+- The server computes every figure. The model copies.
+- Fall back to another model path, never to keyword guesses.
+- A deadline never cuts an answer that has started streaming.
+- A check that edits a correct line is a bug in the check.
+- Keep Fast changes behind one gate, and prove the other modes unchanged.
+- Never judge a reading model with thinking switched off.
+
+## License
+
+MIT

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/SOURCES.txt

@@ -0,0 +1,53 @@
+LICENSE
+README.md
+pyproject.toml
+fast_mode_kit.egg-info/PKG-INFO
+fast_mode_kit.egg-info/SOURCES.txt
+fast_mode_kit.egg-info/dependency_links.txt
+fast_mode_kit.egg-info/entry_points.txt
+fast_mode_kit.egg-info/requires.txt
+fast_mode_kit.egg-info/top_level.txt
+fastkit/__init__.py
+fastkit/__main__.py
+fastkit/checks.py
+fastkit/cli.py
+fastkit/client.py
+fastkit/hedge.py
+fastkit/loop.py
+fastkit/mock.py
+fastkit/modes.py
+fastkit/pipeline.py
+fastkit/prompts.py
+fastkit/py.typed
+fastkit/tools.py
+fastkit/types.py
+fastkit/evals/__init__.py
+fastkit/evals/report.py
+fastkit/evals/run.py
+fastkit/evals/schema.py
+fastkit/evals/shop_gold.jsonl
+fastkit/examples/__init__.py
+fastkit/examples/shop/__init__.py
+fastkit/examples/shop/agent.py
+fastkit/examples/shop/data.py
+fastkit/examples/shop/demo_model.py
+fastkit/examples/shop/tools.py
+fastkit/scaffold/README.md
+fastkit/scaffold/agent.py
+fastkit/scaffold/gold.jsonl
+fastkit/scaffold/tools.py
+fastkit/templates/fast_system.md
+fastkit/templates/notes.md
+fastkit/templates/reader.md
+fastkit/templates/writer.md
+tests/test_checks.py
+tests/test_cli.py
+tests/test_client.py
+tests/test_evals.py
+tests/test_example_agent.py
+tests/test_hedge.py
+tests/test_loop.py
+tests/test_mock.py
+tests/test_modes.py
+tests/test_prompts.py
+tests/test_tools.py

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastkit = fastkit.cli:main

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27
+pydantic>=2.6
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23

fast_mode_kit-0.2.0/fast_mode_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastkit

fast_mode_kit-0.2.0/fastkit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

fast_mode_kit-0.2.0/fastkit/checks.py

@@ -0,0 +1,131 @@
+"""Do-no-harm figure checks.
+
+Rules learned the hard way:
+- an identifier that appears in the rows is sourced, even if it has digits;
+- a zero or negative that answers the question is said, never trimmed;
+- a sentence is dropped only when it has an unsourced figure AND no sourced
+  one; a check never leaves an empty answer or a fragment.
+Every edit a check makes to a correct line is a bug in the check.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Iterable
+
+log = logging.getLogger(__name__)
+
+_NUM = re.compile(r"(?<![\w.])-?\d[\d,]*(?:\.\d+)?%?")
+_RANGE_DASH = re.compile(r"(?<=\d)-(?=\d)")
+_LIST_MARK = re.compile(r"^\s*\d+[.)]\s+")
+_TOKEN = re.compile(r"[A-Za-z0-9][A-Za-z0-9_\-./]*[A-Za-z0-9]|[A-Za-z0-9]")
+_SENT = re.compile(r"(?<=[.!?])\s+")
+
+
+def _walk(obj: Any) -> Iterable[Any]:
+    if isinstance(obj, dict):
+        for v in obj.values():
+            yield from _walk(v)
+    elif isinstance(obj, (list, tuple)):
+        for v in obj:
+            yield from _walk(v)
+    else:
+        yield obj
+
+
+def _row_facts(rows: list[dict], question: str) -> tuple[list[float], set[str]]:
+    nums: list[float] = []
+    strings: set[str] = set()
+    for v in _walk(rows):
+        if isinstance(v, bool):
+            continue
+        if isinstance(v, (int, float)):
+            nums.append(float(v))
+        elif isinstance(v, str):
+            strings.add(v.lower())
+            try:
+                nums.append(float(v.replace(",", "")))
+            except ValueError:
+                pass
+    for m in _NUM.finditer(question):
+        nums.append(float(m.group(0).rstrip("%").replace(",", "")))
+    strings.add(question.lower())
+    return nums, strings
+
+
+def _matches(text: str, nums: list[float]) -> bool:
+    pct = text.endswith("%")
+    raw = text.rstrip("%").replace(",", "")
+    try:
+        val = float(raw)
+    except ValueError:
+        return False
+    decimals = len(raw.split(".")[1]) if "." in raw else 0
+    for n in nums:
+        for cand in ((n, n * 100) if pct else (n,)):
+            for c in (cand, abs(cand)) if val >= 0 else (cand,):
+                # "fell 3.2%" states -3.2 without its sign
+                if round(c, decimals) == val or c == val:
+                    return True
+                if decimals == 0 and abs(c) >= 1 and round(c) == val:
+                    return True
+    return False
+
+
+def _figures(answer: str) -> list[tuple[str, bool]]:
+    """(figure, is_identifier) pairs found in the answer."""
+    out = []
+    spans = []
+    for tok in _TOKEN.finditer(answer):
+        t = tok.group(0)
+        if not any(c.isdigit() for c in t):
+            continue
+        # codes (SKU-1042), dates (2026-11-01), versions: identifiers, not quantities
+        if re.fullmatch(r"\d+(?:\.\d+)?-\d+(?:\.\d+)?", t):
+            continue  # a range like 10-20: two plain numbers, handled below
+        if any(c.isalpha() for c in t) or "-" in t.lstrip("-") or t.count(".") > 1 or "/" in t:
+            out.append((t, True))
+            spans.append(tok.span())
+    for m in _NUM.finditer(_RANGE_DASH.sub(" ", answer)):
+        if any(a <= m.start() < b for a, b in spans):
+            continue
+        out.append((m.group(0).rstrip(".,"), False))
+    return out
+
+
+def ungrounded_figures(answer: str, rows: list[dict], question: str = "") -> list[str]:
+    nums, strings = _row_facts(rows, question)
+    bad = []
+    for fig, ident in _figures(answer):
+        if ident:
+            if not any(fig.lower() in s for s in strings):
+                bad.append(fig)
+        elif not _matches(fig, nums):
+            bad.append(fig)
+    return bad
+
+
+def safe_filter(answer: str, rows: list[dict], question: str = "") -> str:
+    """Drop a sentence only when every figure in it is unsourced. Lines and
+    list markers are kept as written; never returns an empty answer."""
+    out_lines = []
+    dropped = False
+    for line in answer.split("\n"):
+        mark = _LIST_MARK.match(line)
+        prefix, body = (line[:mark.end()], line[mark.end():]) if mark else ("", line)
+        kept = []
+        for sent in _SENT.split(body):
+            figs = [f for f, _ in _figures(sent)]
+            bad = ungrounded_figures(sent, rows, question)
+            if bad and len(bad) == len(figs):
+                log.info("dropped unsourced sentence: %r", sent)
+                dropped = True
+                continue
+            kept.append(sent)
+        if kept or not body.strip():
+            out_lines.append(prefix + " ".join(kept))
+    result = "\n".join(out_lines).strip()
+    if not result:
+        log.warning("check would empty the answer; keeping original")
+        return answer
+    return result if dropped else answer