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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
fastkit/loop.py ADDED
@@ -0,0 +1,149 @@
1
+ """The one-call Fast loop: one model conversation reads, calls tools and writes.
2
+
3
+ Falls back to the read->fetch->answer pipeline when the model produces no
4
+ tool call though tools were offered, calls a tool that does not exist,
5
+ stays silent past ``reading_hedge_s``, or runs out of rounds. Fallback is
6
+ always another model path, never a keyword guess.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import json
12
+ from dataclasses import dataclass, field
13
+ from typing import Any, AsyncIterator, Callable
14
+
15
+ from .tools import FIND_TOOLS, NOTE_TURN, ToolRegistry
16
+ from .types import Message, Model, StreamEvent
17
+
18
+
19
+ DEFAULT_NOTES = {
20
+ "refusal": "I can't help with that one.",
21
+ "safety": "I want to be careful here, so I won't answer that.",
22
+ "out_of_scope": "That's outside what I can answer from the data I have.",
23
+ }
24
+
25
+
26
+ @dataclass
27
+ class FastConfig:
28
+ first_words_s: float = 4.5
29
+ reading_hedge_s: float = 2.5
30
+ max_rounds: int = 3
31
+ # Fall back when the model is silent past reading_hedge_s. Turn this off
32
+ # when the fallback uses the same (or a slower) model: switching then only
33
+ # adds time. A backup must be quicker than what it replaces.
34
+ silence_fallback: bool = True
35
+ notes: dict[str, str] = field(default_factory=dict)
36
+
37
+ def __post_init__(self) -> None:
38
+ self.notes = {**DEFAULT_NOTES, **self.notes}
39
+
40
+
41
+ async def _first_with_timeout(it: AsyncIterator[StreamEvent], timeout: float):
42
+ return await asyncio.wait_for(it.__anext__(), timeout=timeout)
43
+
44
+
45
+ async def fast_answer(model: Model, registry: ToolRegistry, question: str, history: list[Message],
46
+ offered: list[str], *, system_prompt: str,
47
+ fallback: Callable[[], AsyncIterator[StreamEvent]],
48
+ config: FastConfig | None = None,
49
+ trace: dict[str, Any] | None = None) -> AsyncIterator[StreamEvent]:
50
+ cfg = config or FastConfig()
51
+ tr = trace if trace is not None else {}
52
+ tr.update(rows=[], fell_back=None, confirm=None, note=None, rounds=0, tools_called=[],
53
+ data_called=False)
54
+ names = list(dict.fromkeys([*offered, FIND_TOOLS, NOTE_TURN]))
55
+ msgs = [Message(role="system", content=system_prompt), *history,
56
+ Message(role="user", content=question)]
57
+
58
+ async def do_fallback(reason: str):
59
+ tr["fell_back"] = reason
60
+ async for ev in fallback():
61
+ yield ev
62
+
63
+ for rnd in range(cfg.max_rounds):
64
+ tr["rounds"] = rnd + 1
65
+ it = model.stream(msgs, tools=registry.schemas(names)).__aiter__()
66
+ try:
67
+ first = await _first_with_timeout(it, cfg.reading_hedge_s if cfg.silence_fallback else None)
68
+ except (asyncio.TimeoutError, StopAsyncIteration):
69
+ try:
70
+ await it.aclose()
71
+ except Exception:
72
+ pass
73
+ async for ev in do_fallback("silence"):
74
+ yield ev
75
+ return
76
+ # Each round is buffered until it ends: tokens before a tool call are a
77
+ # preamble, not the answer, and nothing shown can ever be taken back.
78
+ # Fast answers are one line per part, so buffering costs little.
79
+ tokens: list[str] = []
80
+ calls = []
81
+ usage = None
82
+ events = [first]
83
+ failed = False
84
+ try:
85
+ async for ev in it:
86
+ events.append(ev)
87
+ except Exception:
88
+ failed = True
89
+ for ev in events:
90
+ if ev.kind == "token":
91
+ tokens.append(ev.text)
92
+ elif ev.kind == "tool_call":
93
+ calls.append(ev.tool_call)
94
+ elif ev.kind == "done":
95
+ usage = ev.usage
96
+ elif ev.kind == "error":
97
+ failed = True
98
+ tr["usage"] = usage
99
+ if failed:
100
+ async for f in do_fallback("model_error"):
101
+ yield f
102
+ return
103
+
104
+ if not calls:
105
+ # An answer must rest on data read this turn, whenever tools exist.
106
+ if offered and not tr["data_called"]:
107
+ reason = "no_tool_call" if rnd == 0 else "no_data"
108
+ async for ev in do_fallback(reason):
109
+ yield ev
110
+ return
111
+ for t in tokens:
112
+ yield StreamEvent(kind="token", text=t)
113
+ yield StreamEvent(kind="done", usage=usage)
114
+ return
115
+
116
+ msgs.append(Message(role="assistant", content="".join(tokens) or None, tool_calls=calls))
117
+ for call in calls:
118
+ tool = registry.get(call.name)
119
+ if tool is None:
120
+ async for ev in do_fallback("unknown_tool"):
121
+ yield ev
122
+ return
123
+ tr["tools_called"].append(call.name)
124
+ if call.name == NOTE_TURN:
125
+ kind = call.arguments.get("kind", "out_of_scope")
126
+ tr["note"] = kind
127
+ yield StreamEvent(kind="token", text=cfg.notes.get(kind, cfg.notes["out_of_scope"]))
128
+ yield StreamEvent(kind="done")
129
+ return
130
+ if call.name == FIND_TOOLS:
131
+ found = registry.find(call.arguments.get("query", ""))
132
+ names = list(dict.fromkeys([*names, *found]))
133
+ result: Any = {"tools": found}
134
+ else:
135
+ tr["data_called"] = True
136
+ try:
137
+ rows = await tool.fn(**call.arguments)
138
+ except TypeError as exc:
139
+ rows = [{"error": f"bad arguments: {exc}"}]
140
+ if tool.kind == "propose" and not any("error" in r for r in rows):
141
+ tr["confirm"] = rows[0].get("confirm") if rows else None
142
+ yield StreamEvent(kind="done")
143
+ return
144
+ tr["rows"].extend(rows)
145
+ result = rows
146
+ msgs.append(Message(role="tool", tool_call_id=call.id, content=json.dumps(result, default=str)))
147
+
148
+ async for ev in do_fallback("max_rounds"):
149
+ yield ev
fastkit/mock.py ADDED
@@ -0,0 +1,32 @@
1
+ """A scripted model for offline tests. Never touches the network."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ from typing import Any, AsyncIterator
6
+
7
+ from .types import Message, StreamEvent
8
+
9
+
10
+ class MockModel:
11
+ def __init__(self, script: list[list[StreamEvent]], delays: list[float] | None = None,
12
+ token_gap: float = 0.0):
13
+ self.script = list(script)
14
+ self.delays = list(delays or [])
15
+ self.token_gap = token_gap
16
+ self.calls: list[list[Message]] = []
17
+
18
+ async def stream(self, messages: list[Message], tools: list[dict] | None = None,
19
+ **kw: Any) -> AsyncIterator[StreamEvent]:
20
+ i = len(self.calls)
21
+ self.calls.append(list(messages))
22
+ if i >= len(self.script):
23
+ raise RuntimeError("MockModel script exhausted")
24
+ if i < len(self.delays) and self.delays[i]:
25
+ await asyncio.sleep(self.delays[i])
26
+ events = self.script[i]
27
+ for n, ev in enumerate(events):
28
+ if n and self.token_gap:
29
+ await asyncio.sleep(self.token_gap)
30
+ yield ev
31
+ if not events or events[-1].kind != "done":
32
+ yield StreamEvent(kind="done", usage={"prompt_tokens": 0, "completion_tokens": 0})
fastkit/modes.py ADDED
@@ -0,0 +1,20 @@
1
+ """Mode gate: keep every Fast-only change behind one switch.
2
+
3
+ Lesson: Fast fixes leaked into the default mode until every Fast change went
4
+ through one gate and a test proved the other modes byte-identical.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ from typing import Literal, TypeVar
9
+
10
+ Mode = Literal["fast", "default", "deep"]
11
+ T = TypeVar("T")
12
+
13
+
14
+ def resolve_mode(requested: str | None) -> Mode:
15
+ m = (requested or "").strip().lower()
16
+ return m if m in ("fast", "default", "deep") else "default" # type: ignore[return-value]
17
+
18
+
19
+ def fast_only(mode: Mode, fast_value: T, other_value: T) -> T:
20
+ return fast_value if mode == "fast" else other_value
fastkit/pipeline.py ADDED
@@ -0,0 +1,56 @@
1
+ """Fallback path: a reader model plans, the server fetches, a writer answers."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import re
6
+ from typing import Any, AsyncIterator
7
+
8
+ from .tools import ToolRegistry
9
+ from .types import Message, Model, StreamEvent
10
+
11
+
12
+ def parse_plan(text: str) -> list[dict[str, Any]]:
13
+ m = re.search(r"\{.*\}", text, re.S)
14
+ if not m:
15
+ return []
16
+ try:
17
+ return list(json.loads(m.group(0)).get("parts") or [])
18
+ except json.JSONDecodeError:
19
+ return []
20
+
21
+
22
+ async def pipeline_answer(reader: Model, writer: Model, registry: ToolRegistry, question: str, *,
23
+ reader_prompt: str, writer_prompt: str,
24
+ trace: dict[str, Any] | None = None) -> AsyncIterator[StreamEvent]:
25
+ tr = trace if trace is not None else {}
26
+ tools = [t.schema() for t in registry.tools.values()]
27
+ plan_text = ""
28
+ async for ev in reader.stream([
29
+ Message(role="system", content=reader_prompt + "\n\nTools:\n" + json.dumps(tools)),
30
+ Message(role="user", content=question),
31
+ ]):
32
+ if ev.kind == "token":
33
+ plan_text += ev.text
34
+ rows: list[dict[str, Any]] = []
35
+ for part in parse_plan(plan_text):
36
+ tool = registry.get(part.get("tool", ""))
37
+ if not (tool and tool.fn):
38
+ continue
39
+ try:
40
+ got = await tool.fn(**(part.get("args") or {}))
41
+ except TypeError:
42
+ continue
43
+ if tool.kind == "propose":
44
+ # A write never becomes a read: show its confirm card and stop.
45
+ if got and "confirm" in got[0]:
46
+ tr["confirm"] = got[0]["confirm"]
47
+ yield StreamEvent(kind="done")
48
+ return
49
+ continue
50
+ rows.extend(got)
51
+ tr.setdefault("rows", []).extend(rows)
52
+ async for ev in writer.stream([
53
+ Message(role="system", content=writer_prompt),
54
+ Message(role="user", content=f"Question: {question}\n\nRows:\n{json.dumps(rows, default=str)}"),
55
+ ]):
56
+ yield ev
fastkit/prompts.py ADDED
@@ -0,0 +1,21 @@
1
+ """Load and fill prompt templates. Raises on any unfilled slot."""
2
+ from __future__ import annotations
3
+
4
+ import re
5
+ import string
6
+ from pathlib import Path
7
+
8
+ TEMPLATE_DIR = Path(__file__).resolve().parent / "templates"
9
+ DEFAULT_LANGUAGE_RULE = ("Reply in the language and script the user wrote in, even when the data "
10
+ "labels are in another language. Write figures with Latin digits.")
11
+
12
+
13
+ def render(name: str, template_dir: Path | None = None, **slots: str) -> str:
14
+ path = (template_dir or TEMPLATE_DIR) / f"{name}.md"
15
+ text = path.read_text(encoding="utf-8")
16
+ slots.setdefault("language_rule", DEFAULT_LANGUAGE_RULE)
17
+ needed = {f for _, f, _, _ in string.Formatter().parse(text) if f}
18
+ missing = needed - slots.keys()
19
+ if missing:
20
+ raise KeyError(f"unfilled slots in {name}: {sorted(missing)}")
21
+ return text.format(**{k: v for k, v in slots.items() if k in needed})
fastkit/py.typed ADDED
File without changes
@@ -0,0 +1,11 @@
1
+ # My Fast mode agent
2
+
3
+ Made with `fastkit init`.
4
+
5
+ 1. Run it offline: `python agent.py "how many widgets in stock?"`
6
+ 2. Replace `tools.py` with reads from your own data. Every figure must come from a tool.
7
+ 3. Set `DOMAIN` in `agent.py` and edit `prompts/` if your domain needs extra rules.
8
+ 4. Write 20+ real questions in `gold.jsonl` with the figures you expect.
9
+ 5. Point it at a model: `export FASTKIT_API_KEY=...` then
10
+ `fastkit check --base-url <url> --model <name>` (one tiny request) and
11
+ `fastkit eval --agent agent.py --gold gold.jsonl --base-url <url> --model <name> --price-in X --price-out Y`.
@@ -0,0 +1,84 @@
1
+ """Your Fast mode agent.
2
+
3
+ python agent.py "how many widgets in stock?" # offline stand-in model
4
+ python agent.py "how many widgets in stock?" \
5
+ --base-url https://openrouter.ai/api/v1 --model google/gemini-2.5-flash # real model
6
+ fastkit eval --agent agent.py --gold gold.jsonl # measure it
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import asyncio
12
+ import json
13
+ import os
14
+ import re
15
+ import time
16
+ from pathlib import Path
17
+
18
+ from fastkit.client import ChatClient
19
+ from fastkit.loop import FastConfig, fast_answer
20
+ from fastkit.pipeline import pipeline_answer
21
+ from fastkit.prompts import render
22
+ from fastkit.types import StreamEvent, ToolCall
23
+
24
+ from tools import STOCK, build_registry
25
+
26
+ DOMAIN = "a small store's stock" # say what your agent knows about
27
+ PROMPTS = Path(__file__).parent / "prompts"
28
+
29
+
30
+ class OfflineModel:
31
+ """Stand-in so the scaffold runs with no key. Swap for ChatClient."""
32
+
33
+ async def stream(self, messages, tools=None, **kw):
34
+ last = messages[-1]
35
+ if last.role == "tool":
36
+ rows = json.loads(last.content)
37
+ yield StreamEvent(kind="token", text=", ".join(f"{r.get('item')}: {r.get('stock')}" for r in rows if "stock" in r) or "Not in the data.")
38
+ elif last.role == "user" and tools:
39
+ words = re.findall(r"[a-z]+", last.content.lower())
40
+ name = next((w for w in words if w.rstrip("s") in STOCK), words[-1] if words else "")
41
+ yield StreamEvent(kind="tool_call", tool_call=ToolCall(id="c1", name="item_stock", arguments={"name": name}))
42
+ else:
43
+ yield StreamEvent(kind="token", text="Not in the data.")
44
+ yield StreamEvent(kind="done")
45
+
46
+
47
+ async def answer(question: str, model) -> dict:
48
+ reg = build_registry()
49
+ tool_list = "\n".join(f"- {t.name}: {t.description}" for t in reg.tools.values())
50
+ trace: dict = {}
51
+
52
+ def fallback():
53
+ return pipeline_answer(model, model, reg, question,
54
+ reader_prompt=render("reader", PROMPTS, domain=DOMAIN),
55
+ writer_prompt=render("writer", PROMPTS, domain=DOMAIN), trace=trace)
56
+
57
+ stream = fast_answer(model, reg, question, [], list(reg.tools),
58
+ system_prompt=render("fast_system", PROMPTS, domain=DOMAIN, tool_list=tool_list),
59
+ fallback=fallback, config=FastConfig(silence_fallback=False), trace=trace)
60
+ t0, first, parts, usage = time.monotonic(), None, [], None
61
+ async for ev in stream:
62
+ if ev.kind == "token":
63
+ first = first or time.monotonic() - t0
64
+ parts.append(ev.text)
65
+ elif ev.kind == "done" and ev.usage:
66
+ usage = ev.usage
67
+ return {"text": "".join(parts), "rows": trace.get("rows", []), "confirm": trace.get("confirm"),
68
+ "fell_back": trace.get("fell_back"), "tools_called": trace.get("tools_called", []),
69
+ "first_token_s": first, "total_s": time.monotonic() - t0, "usage": usage}
70
+
71
+
72
+ def make_model(base_url: str | None, model: str, key_env: str = "FASTKIT_API_KEY"):
73
+ return ChatClient(base_url, os.environ.get(key_env), model) if base_url else OfflineModel()
74
+
75
+
76
+ if __name__ == "__main__":
77
+ ap = argparse.ArgumentParser()
78
+ ap.add_argument("question")
79
+ ap.add_argument("--base-url")
80
+ ap.add_argument("--model", default="")
81
+ a = ap.parse_args()
82
+ out = asyncio.run(answer(a.question, make_model(a.base_url, a.model)))
83
+ print(out["text"] or out["confirm"])
84
+ print(f"\n[first token {out['first_token_s'] or 0:.2f}s, total {out['total_s']:.2f}s, fallback={out['fell_back']}]")
@@ -0,0 +1,3 @@
1
+ {"id":"stock-1","question":"how many widgets in stock?","language":"en","expected_tools":["item_stock"],"expected_figures":["42"]}
2
+ {"id":"stock-2","question":"gadget stock","language":"en","expected_tools":["item_stock"],"expected_figures":["7"]}
3
+ {"id":"stock-3","question":"Do we have any gizmos left?","language":"en","expected_tools":["item_stock"],"expected_figures":["0"]}
@@ -0,0 +1,37 @@
1
+ """Your tools. Replace these with reads from your own data.
2
+
3
+ Rules that keep Fast mode right:
4
+ - Every figure the answer states must come back from a tool.
5
+ - Writes are kind="propose": they return a confirm card, never change data directly.
6
+ - Lookups forgive case, spaces and plurals, and say what exists when nothing matches.
7
+ """
8
+ from fastkit.tools import Tool, ToolRegistry
9
+
10
+ STOCK = {"widget": 42, "gadget": 7, "gizmo": 0}
11
+
12
+
13
+ def _find(name: str) -> str | None:
14
+ key = name.strip().lower().rstrip("s")
15
+ return next((k for k in STOCK if k == key or k in key), None)
16
+
17
+
18
+ async def item_stock(name: str):
19
+ k = _find(name)
20
+ if k is None:
21
+ return [{"missing": name, "known_items": sorted(STOCK)}]
22
+ return [{"item": k, "stock": STOCK[k]}]
23
+
24
+
25
+ async def record_sale(name: str, qty: int):
26
+ return [{"confirm": f"Record a sale of {qty} {name}?", "item": name, "qty": qty}]
27
+
28
+
29
+ def build_registry() -> ToolRegistry:
30
+ reg = ToolRegistry()
31
+ reg.register(Tool("item_stock", "Units in stock for one item",
32
+ {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
33
+ item_stock))
34
+ reg.register(Tool("record_sale", "Record that the user sold some units (asks the user to confirm)",
35
+ {"type": "object", "properties": {"name": {"type": "string"}, "qty": {"type": "integer"}},
36
+ "required": ["name", "qty"]}, record_sale, kind="propose"))
37
+ return reg
@@ -0,0 +1,21 @@
1
+ You are the Fast mode of an assistant for {domain}. Answer only what was asked, from data only.
2
+
3
+ How to work:
4
+ - Call a tool for every figure you state. If no offered tool fits, call find_tools with a short description of what you need.
5
+ - If one answer needs another first (for example, find the top item, then its detail), call both before writing.
6
+ - If the user tells you they did something (bought, sold, booked, changed), call the matching record/propose tool. Do not look up data instead.
7
+ - If the question is a refusal case, unsafe, or outside {domain}, call note_turn and stop.
8
+
9
+ How to write:
10
+ - One line per part the user asked, the exact figure first, then its label and date if the rows have one.
11
+ - Use only figures that appear in the tool results or the question. Never compute a figure the rows do not give.
12
+ - "Highest" and "lowest" range over all values, negatives included. Never add a filter the user did not state.
13
+ - If some rows have no activity, say how many and give the lowest among the active ones.
14
+ - If the data is missing, say so plainly in one line.
15
+ - No greetings, no warmth, no follow-up offers, no suggestions, no extra context.
16
+ - Never mention tools, rows, or how you got the data. Never print labels like "Question type" or "Answer:".
17
+ - {language_rule}
18
+ - Understand misspellings and mixed languages without commenting on them.
19
+
20
+ Tools you can use now:
21
+ {tool_list}
@@ -0,0 +1,9 @@
1
+ # Server-owned lines
2
+
3
+ When the model calls note_turn, the server shows a fixed line instead of
4
+ model text. Keep these short, kind and specific to your domain. Configure
5
+ them with FastConfig(notes={...}).
6
+
7
+ - refusal: a request you will not fulfil.
8
+ - safety: anything that suggests harm; add a pointer to real help.
9
+ - out_of_scope: a question your data cannot answer.
@@ -0,0 +1,7 @@
1
+ Read the user's question for an assistant about {domain} and return ONLY a JSON object:
2
+ {{"parts": [{{"tool": "<tool name>", "args": {{...}}}}]}}
3
+
4
+ - One entry per part the user asked. Never merge two asked parts, never drop one.
5
+ - Use exact names from the question; fix obvious misspellings.
6
+ - If the user reports an action they took, use the record/propose tool for it.
7
+ - If nothing fits, return {{"parts": []}}.
@@ -0,0 +1,5 @@
1
+ Write the answer for an assistant about {domain} from the rows given.
2
+ - One line per asked part, exact figure first. Use only figures in the rows or the question.
3
+ - Zero is an answer; say it. Missing data: say so in one line.
4
+ - No greetings, offers, suggestions or mention of rows or tools.
5
+ - {language_rule}
fastkit/tools.py ADDED
@@ -0,0 +1,65 @@
1
+ """Tool registry with a deterministic ``find_tools`` search.
2
+
3
+ Offer the model a small bundle of likely tools plus ``find_tools``, so the
4
+ prompt stays short while every tool stays reachable in one extra call.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ from dataclasses import dataclass, field
10
+ from typing import Any, Awaitable, Callable, Literal
11
+
12
+ ToolFn = Callable[..., Awaitable[list[dict[str, Any]]]]
13
+
14
+ FIND_TOOLS = "find_tools"
15
+ NOTE_TURN = "note_turn"
16
+
17
+
18
+ @dataclass
19
+ class Tool:
20
+ name: str
21
+ description: str
22
+ parameters: dict[str, Any] = field(default_factory=dict)
23
+ fn: ToolFn | None = None
24
+ kind: Literal["read", "propose"] = "read"
25
+
26
+ def schema(self) -> dict[str, Any]:
27
+ params = self.parameters or {"type": "object", "properties": {}}
28
+ return {"type": "function",
29
+ "function": {"name": self.name, "description": self.description, "parameters": params}}
30
+
31
+
32
+ def _words(text: str) -> set[str]:
33
+ return {w for w in re.findall(r"[a-z0-9]+", text.lower().replace("_", " ")) if len(w) > 2}
34
+
35
+
36
+ class ToolRegistry:
37
+ def __init__(self) -> None:
38
+ self.tools: dict[str, Tool] = {}
39
+ self.meta: dict[str, Tool] = {
40
+ FIND_TOOLS: Tool(FIND_TOOLS, "Search for more tools when none offered fits the question.",
41
+ {"type": "object", "properties": {"query": {"type": "string"}},
42
+ "required": ["query"]}),
43
+ NOTE_TURN: Tool(NOTE_TURN, "Mark a turn you must not answer from data: a refusal, a safety "
44
+ "concern, or a question outside this assistant's scope.",
45
+ {"type": "object", "properties": {"kind": {"type": "string",
46
+ "enum": ["refusal", "safety", "out_of_scope"]}}, "required": ["kind"]}),
47
+ }
48
+
49
+ def register(self, tool: Tool) -> None:
50
+ self.tools[tool.name] = tool
51
+
52
+ def get(self, name: str) -> Tool | None:
53
+ return self.tools.get(name) or self.meta.get(name)
54
+
55
+ def schemas(self, names: list[str]) -> list[dict[str, Any]]:
56
+ return [t.schema() for n in names if (t := self.get(n))]
57
+
58
+ def find(self, query: str, k: int = 5) -> list[str]:
59
+ q = _words(query)
60
+ scored = []
61
+ for t in self.tools.values():
62
+ s = len(q & _words(t.name + " " + t.description))
63
+ if s:
64
+ scored.append((-s, t.name))
65
+ return [n for _, n in sorted(scored)[:k]]
fastkit/types.py ADDED
@@ -0,0 +1,47 @@
1
+ """Shared message and stream types (OpenAI-compatible shapes)."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any, AsyncIterator, Literal, Protocol
5
+
6
+ from pydantic import BaseModel, Field
7
+
8
+
9
+ class ToolCall(BaseModel):
10
+ id: str
11
+ name: str
12
+ arguments: dict[str, Any] = Field(default_factory=dict)
13
+
14
+
15
+ class Message(BaseModel):
16
+ role: str
17
+ content: str | None = None
18
+ tool_calls: list[ToolCall] | None = None
19
+ tool_call_id: str | None = None
20
+
21
+ def to_api(self) -> dict[str, Any]:
22
+ import json
23
+
24
+ out: dict[str, Any] = {"role": self.role, "content": self.content}
25
+ if self.tool_calls:
26
+ out["tool_calls"] = [
27
+ {"id": c.id, "type": "function",
28
+ "function": {"name": c.name, "arguments": json.dumps(c.arguments)}}
29
+ for c in self.tool_calls
30
+ ]
31
+ if self.tool_call_id:
32
+ out["tool_call_id"] = self.tool_call_id
33
+ return out
34
+
35
+
36
+ class StreamEvent(BaseModel):
37
+ kind: Literal["token", "tool_call", "done", "error"]
38
+ text: str = ""
39
+ tool_call: ToolCall | None = None
40
+ usage: dict[str, Any] | None = None
41
+
42
+
43
+ class Model(Protocol):
44
+ """Anything that streams events for a list of messages."""
45
+
46
+ def stream(self, messages: list[Message], tools: list[dict] | None = None,
47
+ **kw: Any) -> AsyncIterator[StreamEvent]: ...