fast-mode-kit 0.2.0__py3-none-any.whl

fastkit/evals/run.py

@@ -0,0 +1,96 @@
+"""Run a gold set against an agent and print a report.
+
+    python -m fastkit.evals.run --gold fastkit/evals/shop_gold.jsonl            # offline demo model, free
+    python -m fastkit.evals.run --gold fastkit/evals/shop_gold.jsonl \
+        --base-url http://localhost:8080/v1 --model my-model    # your model
+    ... --price-in 0.25 --price-out 1.25 --spend-cap 0.50        # hosted APIs: cap the spend
+
+Run one request per question. Read cost from the response's own usage.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+from typing import Any, Awaitable, Callable
+
+from fastkit.checks import ungrounded_figures
+
+from .report import markdown
+from .schema import GoldItem, Result, grade
+
+Agent = Callable[[str], Awaitable[dict[str, Any]]]
+
+
+def load_gold(path: str) -> list[GoldItem]:
+    with open(path, encoding="utf-8") as f:
+        return [GoldItem.model_validate_json(line) for line in f if line.strip()]
+
+
+async def run_eval(items: list[GoldItem], agent_fn: Agent, *, spend_cap_usd: float,
+                   price_per_mtok: tuple[float, float] | None) -> list[Result]:
+    results: list[Result] = []
+    spent = 0.0
+    for item in items:
+        if price_per_mtok and spend_cap_usd > 0 and spent >= spend_cap_usd:
+            break
+        out = await agent_fn(item.question)
+        u = out.get("usage") or {}
+        cost = 0.0
+        if price_per_mtok:
+            cost = (u.get("prompt_tokens", 0) * price_per_mtok[0]
+                    + u.get("completion_tokens", 0) * price_per_mtok[1]) / 1e6
+        spent += cost
+        results.append(Result(
+            id=item.id, language=item.language, correct=grade(item, out),
+            first_token_s=out.get("first_token_s"), total_s=out.get("total_s", 0.0), cost_usd=cost,
+            fell_back=out.get("fell_back"),
+            ungrounded=ungrounded_figures(out.get("text") or "", out.get("rows") or [], item.question)))
+    return results
+
+
+def mock_agent() -> Agent:
+    from fastkit.examples.shop.agent import make_registry, run
+    from fastkit.examples.shop.demo_model import DemoModel, demo_vocab
+
+    async def agent(q: str) -> dict[str, Any]:
+        reg = make_registry()
+        return await run(q, "fast", DemoModel(reg, vocab=demo_vocab()), registry=reg)
+    return agent
+
+
+def client_agent(base_url: str, model: str, key_env: str, mode: str) -> Agent:
+    from fastkit.examples.shop.agent import make_registry, run
+    from fastkit.client import ChatClient
+
+    async def agent(q: str) -> dict[str, Any]:
+        reg = make_registry()
+        return await run(q, mode, ChatClient(base_url, os.environ.get(key_env), model), registry=reg)
+    return agent
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--gold", default="fastkit/evals/shop_gold.jsonl")
+    ap.add_argument("--mock", action="store_true")
+    ap.add_argument("--base-url")
+    ap.add_argument("--model", default="")
+    ap.add_argument("--api-key-env", default="FASTKIT_API_KEY")
+    ap.add_argument("--mode", default="fast")
+    ap.add_argument("--price-in", type=float, help="USD per million input tokens")
+    ap.add_argument("--price-out", type=float, help="USD per million output tokens")
+    ap.add_argument("--spend-cap", type=float, default=0.50)
+    a = ap.parse_args()
+    items = load_gold(a.gold)
+    if a.base_url and not a.mock:
+        agent = client_agent(a.base_url, a.model, a.api_key_env, a.mode)
+    else:
+        agent = mock_agent()
+    price = (a.price_in, a.price_out) if a.price_in is not None and a.price_out is not None else None
+    if a.base_url and price is None:
+        print("note: no --price-in/--price-out given, so cost is reported as $0 and the cap cannot stop the run")
+    print(markdown(asyncio.run(run_eval(items, agent, spend_cap_usd=a.spend_cap, price_per_mtok=price))))
+
+
+if __name__ == "__main__":
+    main()

fastkit/evals/schema.py

@@ -0,0 +1,50 @@
+"""Gold items, results and grading."""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+_NUM = re.compile(r"-?\d[\d,]*(?:\.\d+)?")
+
+
+class GoldItem(BaseModel):
+    id: str
+    question: str
+    language: str
+    expected_tools: list[str] = Field(default_factory=list)
+    expected_figures: list[str] = Field(default_factory=list)
+    expects_confirm: bool = False
+
+
+class Result(BaseModel):
+    id: str
+    language: str
+    correct: bool
+    first_token_s: float | None
+    total_s: float
+    cost_usd: float
+    fell_back: str | None
+    ungrounded: list[str]
+
+
+def _numbers(text: str) -> list[float]:
+    out = []
+    for m in _NUM.finditer(text):
+        try:
+            out.append(float(m.group(0).replace(",", "")))
+        except ValueError:
+            pass
+    return out
+
+
+def grade(item: GoldItem, out: dict[str, Any]) -> bool:
+    """Correct when every expected figure appears (numerically) and a write
+    gets its confirm card."""
+    if item.expects_confirm and not out.get("confirm"):
+        return False
+    haystack = (out.get("text") or "") + " " + json.dumps(out.get("confirm") or {})
+    have = _numbers(haystack)
+    return all(any(abs(h - float(f)) < 1e-6 for h in have) for f in item.expected_figures)

fastkit/evals/shop_gold.jsonl

@@ -0,0 +1,24 @@
+{"id":"en-01","question":"Which product made the most revenue?","language":"en","expected_tools":["rank_products"],"expected_figures":["84.0"]}
+{"id":"en-02","question":"Top 3 products by units sold","language":"en","expected_tools":["rank_products"],"expected_figures":["15","8","7"]}
+{"id":"en-03","question":"How many notebooks are in stock?","language":"en","expected_tools":["product_stock"],"expected_figures":["120"]}
+{"id":"en-04","question":"Stock of caps?","language":"en","expected_tools":["product_stock"],"expected_figures":["0"]}
+{"id":"en-05","question":"Revenue on 2026-11-05","language":"en","expected_tools":["orders_by_day"],"expected_figures":["-7.5"]}
+{"id":"en-06","question":"What did Chen buy and how much did he spend in total?","language":"en","expected_tools":["customer_orders"],"expected_figures":["35.0","48.0"]}
+{"id":"en-07","question":"Lowest selling product by revenue, and the lamp's stock","language":"en","expected_tools":["rank_products","product_stock"],"expected_figures":["22.5","3"]}
+{"id":"en-08","question":"I sold 3 mugs to Ana","language":"en","expected_tools":["record_sale"],"expected_figures":["3","36.0"],"expects_confirm":true}
+{"id":"es-01","question":"¿Qué producto generó más ingresos?","language":"es","expected_tools":["rank_products"],"expected_figures":["84.0"]}
+{"id":"es-02","question":"Los 3 productos más vendidos por unidades","language":"es","expected_tools":["rank_products"],"expected_figures":["15","8","7"]}
+{"id":"es-03","question":"¿Cuántas velas hay en stock?","language":"es","expected_tools":["product_stock"],"expected_figures":["60"]}
+{"id":"es-04","question":"¿Cuántos pedidos hubo el 2026-11-01?","language":"es","expected_tools":["orders_by_day"],"expected_figures":["2"]}
+{"id":"es-05","question":"Ingresos del 2026-11-03","language":"es","expected_tools":["orders_by_day"],"expected_figures":["81.0"]}
+{"id":"es-06","question":"¿Qué compró Dara?","language":"es","expected_tools":["customer_orders"],"expected_figures":["45.0","22.5"]}
+{"id":"es-07","question":"Precio y stock de la tetera (Teapot)","language":"es","expected_tools":["product_stock"],"expected_figures":["35.0","6"]}
+{"id":"es-08","question":"Vendí 2 lámparas (Lamp)","language":"es","expected_tools":["record_sale"],"expected_figures":["2","96.0"],"expects_confirm":true}
+{"id":"ty-01","question":"wich prodct sold the most unitz","language":"typo","expected_tools":["rank_products"],"expected_figures":["15"]}
+{"id":"ty-02","question":"stok of the scraf","language":"typo","expected_tools":["product_stock"],"expected_figures":["15"]}
+{"id":"ty-03","question":"how much revnue on nov 2 2026","language":"typo","expected_tools":["orders_by_day"],"expected_figures":["80.0"]}
+{"id":"ty-04","question":"bens orders pls","language":"typo","expected_tools":["customer_orders"],"expected_figures":["45.0","36.0","15.0"]}
+{"id":"ty-05","question":"lowest revenue product?? ignore the ones with no sales","language":"typo","expected_tools":["rank_products"],"expected_figures":["22.5"]}
+{"id":"ty-06","question":"top seller y su stock","language":"mixed","expected_tools":["rank_products","product_stock"],"expected_figures":["84.0","40"]}
+{"id":"ty-07","question":"pen set stock porfa","language":"mixed","expected_tools":["product_stock"],"expected_figures":["0"]}
+{"id":"ty-08","question":"just sold 1 tea pot","language":"typo","expected_tools":["record_sale"],"expected_figures":["1","35.0"],"expects_confirm":true}

fastkit/examples/shop/agent.py

@@ -0,0 +1,104 @@
+"""Example shop agent with a Fast mode.
+
+    python -m fastkit.examples.shop.agent "top 3 products by revenue" --mock
+    python -m fastkit.examples.shop.agent "lowest selling product" \
+        --base-url http://localhost:8080/v1 --model my-model
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import time
+from typing import Any
+
+from fastkit.checks import safe_filter
+from fastkit.client import ChatClient
+from fastkit.loop import FastConfig, fast_answer
+from fastkit.modes import resolve_mode
+from fastkit.pipeline import pipeline_answer
+from fastkit.prompts import render
+from fastkit.tools import ToolRegistry
+from fastkit.types import Model
+
+from .data import connect
+from .tools import build_registry
+
+DOMAIN = "a small online shop's products, stock, customers and orders"
+
+
+def make_registry() -> ToolRegistry:
+    return build_registry(connect())
+
+
+async def run(question: str, mode: str, model: Model, reader: Model | None = None,
+              writer: Model | None = None, registry: ToolRegistry | None = None,
+              config: FastConfig | None = None) -> dict[str, Any]:
+    reg = registry or make_registry()
+    tool_list = "\n".join(f"- {t.name}: {t.description}" for t in reg.tools.values())
+    trace: dict[str, Any] = {}
+    reader, writer = reader or model, writer or model
+
+    def fallback():
+        return pipeline_answer(reader, writer, reg, question,
+                               reader_prompt=render("reader", domain=DOMAIN),
+                               writer_prompt=render("writer", domain=DOMAIN), trace=trace)
+
+    if config is None:
+        # Only give up on a silent model if the backup uses a different one.
+        config = FastConfig(silence_fallback=reader is not model)
+    if resolve_mode(mode) == "fast":
+        # Small registry: offer every tool. Large one: offer a likely bundle and
+        # let the model reach the rest through find_tools.
+        offered = list(reg.tools) if len(reg.tools) <= 8 else reg.find(question, k=5)
+        stream = fast_answer(model, reg, question, [], offered,
+                             system_prompt=render("fast_system", domain=DOMAIN, tool_list=tool_list),
+                             fallback=fallback, config=config, trace=trace)
+    else:
+        trace["fell_back"] = None
+        stream = fallback()
+
+    t0 = time.monotonic()
+    first = None
+    parts: list[str] = []
+    usage = None
+    async for ev in stream:
+        if ev.kind == "token":
+            first = first or time.monotonic() - t0
+            parts.append(ev.text)
+        elif ev.kind == "done" and ev.usage:
+            usage = ev.usage
+    if first is None and (parts or trace.get("confirm")):
+        first = time.monotonic() - t0
+    rows = trace.get("rows", [])
+    tools_called = trace.get("tools_called", [])
+    text = "".join(parts)
+    return {"text": safe_filter(text, rows, question) if text else text, "rows": rows,
+            "confirm": trace.get("confirm"), "fell_back": trace.get("fell_back"),
+            "note": trace.get("note"), "tools_called": tools_called, "first_token_s": first, "total_s": time.monotonic() - t0,
+            "usage": usage or trace.get("usage")}
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("question")
+    ap.add_argument("--mode", default="fast")
+    ap.add_argument("--mock", action="store_true", help="offline fake model (default if no --base-url)")
+    ap.add_argument("--base-url")
+    ap.add_argument("--model", default="")
+    ap.add_argument("--api-key-env", default="FASTKIT_API_KEY")
+    a = ap.parse_args()
+    reg = make_registry()
+    if a.base_url and not a.mock:
+        model: Model = ChatClient(a.base_url, os.environ.get(a.api_key_env), a.model)
+    else:
+        from .demo_model import DemoModel, demo_vocab
+        model = DemoModel(reg, vocab=demo_vocab())
+    out = asyncio.run(run(a.question, a.mode, model, registry=reg))
+    print(out["text"] or out["confirm"])
+    print(f"\n[first token {out['first_token_s'] or 0:.2f}s, total {out['total_s']:.2f}s, "
+          f"fallback={out['fell_back']}]")
+
+
+if __name__ == "__main__":
+    main()

fastkit/examples/shop/data.py

@@ -0,0 +1,32 @@
+"""A tiny in-memory shop: products, customers, orders. Toy data only."""
+import sqlite3
+
+PRODUCTS = [
+    ("SKU-1001", "Mug", "kitchen", 12.0, 40), ("SKU-1002", "Teapot", "kitchen", 35.0, 6),
+    ("SKU-1003", "Cap", "apparel", 18.0, 0), ("SKU-1004", "Scarf", "apparel", 22.5, 15),
+    ("SKU-1005", "Notebook", "stationery", 4.5, 120), ("SKU-1006", "Pen set", "stationery", 9.0, 0),
+    ("SKU-1007", "Lamp", "home", 48.0, 3), ("SKU-1008", "Candle", "home", 7.5, 60),
+]
+CUSTOMERS = [(1, "Ana"), (2, "Ben"), (3, "Chen"), (4, "Dara")]
+# (order_id, day, customer_id, sku, qty); negative qty = a return
+ORDERS = [
+    (1, "2026-11-01", 1, "SKU-1001", 4), (2, "2026-11-01", 2, "SKU-1005", 10),
+    (3, "2026-11-02", 3, "SKU-1002", 1), (4, "2026-11-02", 1, "SKU-1008", 6),
+    (5, "2026-11-03", 4, "SKU-1004", 2), (6, "2026-11-03", 2, "SKU-1001", 3),
+    (7, "2026-11-04", 3, "SKU-1007", 1), (8, "2026-11-04", 4, "SKU-1005", 5),
+    (9, "2026-11-05", 1, "SKU-1004", -1), (10, "2026-11-05", 2, "SKU-1008", 2),
+]
+
+
+def connect() -> sqlite3.Connection:
+    conn = sqlite3.connect(":memory:")
+    conn.row_factory = sqlite3.Row
+    conn.executescript("""
+        create table products(sku text primary key, name text, category text, price real, stock int);
+        create table customers(id int primary key, name text);
+        create table orders(id int primary key, day text, customer_id int, sku text, qty int);
+    """)
+    conn.executemany("insert into products values (?,?,?,?,?)", PRODUCTS)
+    conn.executemany("insert into customers values (?,?)", CUSTOMERS)
+    conn.executemany("insert into orders values (?,?,?,?,?)", ORDERS)
+    return conn

fastkit/examples/shop/demo_model.py

@@ -0,0 +1,69 @@
+"""A fake model so the example runs offline with no key. It is NOT smart:
+it picks the best-matching tool and prints the first rows. Swap in a real
+model with --base-url to see real answers."""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, AsyncIterator
+
+from fastkit.tools import ToolRegistry
+from fastkit.types import Message, StreamEvent, ToolCall
+
+
+class DemoModel:
+    """vocab: names the fake model may spot in a question (products, customers)."""
+
+    def __init__(self, registry: ToolRegistry, vocab: list[str] | None = None):
+        self.registry = registry
+        self.vocab = vocab or []
+
+    def _args(self, tool_name: str, q: str) -> dict:
+        tool = self.registry.get(tool_name)
+        props = (tool.parameters or {}).get("properties", {}) if tool else {}
+        ql = q.lower().replace(" ", "")
+        names = [v for v in self.vocab if v.lower().replace(" ", "") in ql]
+        nums = [int(n) for n in re.findall(r"(?<![\d-])\d{1,3}(?![\d-])", q)]
+        date = re.search(r"\d{4}-\d{2}-\d{2}", q)
+        args: dict = {}
+        for p in props:
+            if p in ("name", "product", "customer") and names:
+                args[p] = names[0]
+            elif p in ("qty", "n") and nums:
+                args[p] = nums[0]
+            elif p == "day" and date:
+                args[p] = date.group(0)
+        return args
+
+    async def stream(self, messages: list[Message], tools: list[dict] | None = None,
+                     **kw: Any) -> AsyncIterator[StreamEvent]:
+        last = messages[-1]
+        if last.role == "user" and tools:
+            q = last.content or ""
+            found = self.registry.find(q) or ["rank_products"]
+            yield StreamEvent(kind="tool_call",
+                              tool_call=ToolCall(id="demo", name=found[0], arguments=self._args(found[0], q)))
+        elif last.role == "user" and (last.content or "").startswith("Question:"):
+            rows = json.loads(last.content.split("Rows:\n", 1)[1] or "[]")
+            yield StreamEvent(kind="token", text=self._lines(rows))
+        elif last.role == "user":
+            found = self.registry.find(last.content or "") or ["rank_products"]
+            yield StreamEvent(kind="token", text=json.dumps({"parts": [{"tool": found[0], "args": {}}]}))
+        else:
+            result = json.loads(last.content or "[]")
+            if any("error" in r for r in result if isinstance(r, dict)):
+                yield StreamEvent(kind="token", text="I need a bit more detail for that one.")
+            else:
+                yield StreamEvent(kind="token", text=self._lines(result))
+        yield StreamEvent(kind="done", usage={"prompt_tokens": 0, "completion_tokens": 0})
+
+    @staticmethod
+    def _lines(rows: list[dict]) -> str:
+        if not rows:
+            return "No data for that."
+        return "\n".join(", ".join(f"{k}: {v}" for k, v in r.items()) for r in rows[:3])
+
+
+def demo_vocab() -> list[str]:
+    from .data import CUSTOMERS, PRODUCTS
+    return [p[1] for p in PRODUCTS] + [c[1] for c in CUSTOMERS]

fastkit/examples/shop/tools.py

@@ -0,0 +1,73 @@
+"""Shop tools. Each returns rows with every derived figure computed server-side,
+so the model never has to do arithmetic."""
+from __future__ import annotations
+
+import sqlite3
+
+from fastkit.tools import Tool, ToolRegistry
+
+OBJ = lambda props, req=(): {"type": "object", "properties": props, "required": list(req)}
+
+
+def build_registry(conn: sqlite3.Connection) -> ToolRegistry:
+    q = lambda sql, *a: [dict(r) for r in conn.execute(sql, a).fetchall()]
+
+    async def rank_products(n: int = 3, by: str = "revenue", order: str = "desc"):
+        col = {"revenue": "revenue", "units": "units"}.get(by, "revenue")
+        rows = q(f"""select p.sku, p.name, coalesce(sum(o.qty),0) units,
+                     round(coalesce(sum(o.qty*p.price),0),2) revenue
+                     from products p left join orders o on o.sku=p.sku group by p.sku""")
+        active = [r for r in rows if r["units"] != 0]
+        inactive = len(rows) - len(active)
+        active.sort(key=lambda r: r[col], reverse=(order != "asc"))
+        out = [dict(r, rank=i + 1, measure=col) for i, r in enumerate(active[:n])]
+        if order == "asc" and inactive:
+            out.append({"inactive_count": inactive, "note": "products with no sales, left out of the ranking"})
+        return out
+
+    def find_product(name: str) -> list[dict]:
+        # Forgiving lookup: case, spaces and a plural "s" never hide a product.
+        key = name.strip().lower()
+        rows = q("select sku, name, stock, price from products")
+        for cand in (key, key[:-1] if key.endswith("s") else key):
+            hit = [r for r in rows if r["name"].lower() == cand or r["sku"].lower() == cand
+                   or r["name"].lower().replace(" ", "") == cand.replace(" ", "")]
+            if hit:
+                return hit
+        return [r for r in rows if key.rstrip("s") in r["name"].lower()]
+
+    async def product_stock(name: str):
+        return find_product(name) or [{"missing": name, "known_products": [r["name"] for r in q("select name from products")]}]
+
+    async def orders_by_day(day: str | None = None):
+        sql = """select o.day, count(*) orders, sum(o.qty) units, round(sum(o.qty*p.price),2) revenue
+                 from orders o join products p on p.sku=o.sku {} group by o.day order by o.day"""
+        return q(sql.format("where o.day=?"), day) if day else q(sql.format(""))
+
+    async def customer_orders(customer: str):
+        return q("""select c.name customer, o.day, p.name product, o.qty, round(o.qty*p.price,2) amount
+                    from orders o join customers c on c.id=o.customer_id join products p on p.sku=o.sku
+                    where lower(c.name)=lower(?) order by o.day""", customer) or [{"missing": customer}]
+
+    async def record_sale(product: str, qty: int, customer: str | None = None):
+        found = find_product(product)
+        if not found:
+            return [{"missing": product}]
+        p = found[0]
+        return [{"confirm": {"action": "record_sale", "sku": p["sku"], "product": p["name"], "qty": qty,
+                             "customer": customer, "amount": round(qty * p["price"], 2)}}]
+
+    r = ToolRegistry()
+    r.register(Tool("rank_products", "rank products by revenue or units sold, highest or lowest first",
+                    OBJ({"n": {"type": "integer"}, "by": {"type": "string", "enum": ["revenue", "units"]},
+                         "order": {"type": "string", "enum": ["desc", "asc"]}}), rank_products))
+    r.register(Tool("product_stock", "current stock level and price of one product",
+                    OBJ({"name": {"type": "string"}}, ["name"]), product_stock))
+    r.register(Tool("orders_by_day", "order count, units and revenue per day",
+                    OBJ({"day": {"type": "string", "description": "YYYY-MM-DD"}}), orders_by_day))
+    r.register(Tool("customer_orders", "every order a customer placed with amounts",
+                    OBJ({"customer": {"type": "string"}}, ["customer"]), customer_orders))
+    r.register(Tool("record_sale", "record a sale the user reports (sold, selling); shows a confirm card first",
+                    OBJ({"product": {"type": "string"}, "qty": {"type": "integer"},
+                         "customer": {"type": "string"}}, ["product", "qty"]), record_sale, kind="propose"))
+    return r

fastkit/hedge.py

@@ -0,0 +1,84 @@
+"""Hedged streaming across routes.
+
+Lesson: when the primary route is silent, start the SAME model on another
+route rather than falling to a weaker model. The first leg to speak wins.
+A leg that has already started streaming is never cut by a timer.
+
+``silence_drop_s`` is a TOTAL budget from the start of the call, shared by
+all legs: with hedge 5 s and drop 15 s, a third leg gets 5 s. Keep
+``hedge_after_s * (len(legs) - 1) < silence_drop_s`` or later legs never start.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator
+
+from .types import Message, Model, StreamEvent
+
+
+class AllLegsSilent(RuntimeError):
+    pass
+
+
+async def hedged_stream(legs: list[Model], messages: list[Message], *, hedge_after_s: float,
+                        silence_drop_s: float, tools: list[dict] | None = None,
+                        **kw: Any) -> AsyncIterator[StreamEvent]:
+    if not legs:
+        raise ValueError("no legs")
+    queue: asyncio.Queue = asyncio.Queue()
+    tasks: list[asyncio.Task] = []
+
+    async def pump(i: int, leg: Model) -> None:
+        try:
+            async for ev in leg.stream(messages, tools=tools, **kw):
+                await queue.put((i, ev))
+        except Exception as exc:  # a failed leg is just a silent leg
+            await queue.put((i, StreamEvent(kind="error", text=str(exc))))
+        await queue.put((i, None))
+
+    def start(i: int) -> None:
+        tasks.append(asyncio.create_task(pump(i, legs[i])))
+
+    loop = asyncio.get_running_loop()
+    t0 = loop.time()
+    start(0)
+    winner: int | None = None
+    finished: set[int] = set()
+    try:
+        while True:
+            if winner is None:
+                now = loop.time()
+                if now - t0 >= silence_drop_s:
+                    raise AllLegsSilent(f"no leg spoke within {silence_drop_s}s")
+                next_hedge = t0 + hedge_after_s * len(tasks)
+                deadline = min(t0 + silence_drop_s,
+                               next_hedge if len(tasks) < len(legs) else float("inf"))
+                try:
+                    i, ev = await asyncio.wait_for(queue.get(), timeout=max(0.0, deadline - now))
+                except asyncio.TimeoutError:
+                    if len(tasks) < len(legs) and loop.time() >= next_hedge:
+                        start(len(tasks))
+                    continue
+            else:
+                i, ev = await queue.get()
+            if ev is None:
+                finished.add(i)
+                if winner == i:
+                    return
+                if winner is None and len(finished) == len(legs):
+                    raise AllLegsSilent("every leg ended without output")
+                if winner is None and len(tasks) < len(legs):
+                    start(len(tasks))
+                continue
+            if winner is None:
+                if ev.kind == "error":
+                    continue
+                winner = i
+                for j, t in enumerate(tasks):
+                    if j != i:
+                        t.cancel()
+            if i == winner:
+                yield ev
+    finally:
+        for t in tasks:
+            t.cancel()