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.
- fast_mode_kit-0.2.0.dist-info/METADATA +106 -0
- fast_mode_kit-0.2.0.dist-info/RECORD +39 -0
- fast_mode_kit-0.2.0.dist-info/WHEEL +5 -0
- fast_mode_kit-0.2.0.dist-info/entry_points.txt +2 -0
- fast_mode_kit-0.2.0.dist-info/licenses/LICENSE +21 -0
- fast_mode_kit-0.2.0.dist-info/top_level.txt +1 -0
- fastkit/__init__.py +0 -0
- fastkit/__main__.py +5 -0
- fastkit/checks.py +131 -0
- fastkit/cli.py +190 -0
- fastkit/client.py +77 -0
- fastkit/evals/__init__.py +0 -0
- fastkit/evals/report.py +48 -0
- fastkit/evals/run.py +96 -0
- fastkit/evals/schema.py +50 -0
- fastkit/evals/shop_gold.jsonl +24 -0
- fastkit/examples/__init__.py +0 -0
- fastkit/examples/shop/__init__.py +0 -0
- fastkit/examples/shop/agent.py +104 -0
- fastkit/examples/shop/data.py +32 -0
- fastkit/examples/shop/demo_model.py +69 -0
- fastkit/examples/shop/tools.py +73 -0
- fastkit/hedge.py +84 -0
- fastkit/loop.py +149 -0
- fastkit/mock.py +32 -0
- fastkit/modes.py +20 -0
- fastkit/pipeline.py +56 -0
- fastkit/prompts.py +21 -0
- fastkit/py.typed +0 -0
- fastkit/scaffold/README.md +11 -0
- fastkit/scaffold/agent.py +84 -0
- fastkit/scaffold/gold.jsonl +3 -0
- fastkit/scaffold/tools.py +37 -0
- fastkit/templates/fast_system.md +21 -0
- fastkit/templates/notes.md +9 -0
- fastkit/templates/reader.md +7 -0
- fastkit/templates/writer.md +5 -0
- fastkit/tools.py +65 -0
- fastkit/types.py +47 -0
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]: ...
|