cairnkit 0.5.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.
cairnkit/documents.py ADDED
@@ -0,0 +1,421 @@
1
+ """Turn uploaded documents into Markdown text a model can read.
2
+
3
+ Optional module: ``pip install "cairnkit[documents]"`` adds pypdf (PDF) and openpyxl
4
+ (Excel). Word (.docx) and plain text need only the standard library.
5
+
6
+ from cairnkit.documents import DocumentError, extract_text
7
+
8
+ try:
9
+ doc = extract_text(data, "price-list.xlsx")
10
+ except DocumentError as exc:
11
+ show(exc.code) # stable code for the host to translate
12
+ else:
13
+ use(doc.text)
14
+
15
+ The text is untrusted data. Hosts must keep it out of system prompts and tell the model
16
+ that instructions inside a document are not instructions to it.
17
+
18
+ Backends are replaceable: ``register_extractor("pdf", my_pdf_reader)`` swaps in, for
19
+ example, MarkItDown or an OCR service for one format without changing callers.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import io
25
+ import re
26
+ import zipfile
27
+ from collections.abc import Callable
28
+ from dataclasses import dataclass, field
29
+ from datetime import date, datetime, time
30
+ from xml.etree import ElementTree
31
+
32
+ __all__ = [
33
+ "SUPPORTED_EXTENSIONS",
34
+ "Document",
35
+ "DocumentError",
36
+ "Limits",
37
+ "Extracted",
38
+ "detect_kind",
39
+ "extract_text",
40
+ "register_extractor",
41
+ ]
42
+
43
+ SUPPORTED_EXTENSIONS = (".pdf", ".docx", ".xlsx", ".txt", ".md", ".csv", ".tsv")
44
+ _TEXT_EXTENSIONS = (".txt", ".md", ".markdown", ".csv", ".tsv", ".text")
45
+
46
+
47
+ class DocumentError(Exception):
48
+ """A document that cannot be turned into text. ``code`` is stable; ``str()`` is English.
49
+
50
+ Codes: ``too_large``, ``empty``, ``unsupported``, ``old_format`` (.doc/.xls/.ppt),
51
+ ``image`` (needs a vision model), ``encrypted``, ``no_text`` (scanned PDF),
52
+ ``unreadable`` (damaged or not what it claims), ``needs_extra`` (missing optional
53
+ dependency).
54
+ """
55
+
56
+ def __init__(self, code: str, message: str):
57
+ super().__init__(message)
58
+ self.code = code
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class Limits:
63
+ max_bytes: int = 20 * 1024 * 1024 # the upload itself
64
+ max_unzipped_bytes: int = 200 * 1024 * 1024 # .docx/.xlsx are zip files: no zip bombs
65
+ max_zip_members: int = 10_000
66
+ max_pages: int = 300 # PDF pages read
67
+ max_sheet_rows: int = 5_000 # rows per Excel sheet
68
+ max_chars: int = 200_000 # the Markdown handed back
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class Extracted:
73
+ """What an extractor returns; ``extract_text`` adds the common clean-up and limits."""
74
+
75
+ text: str
76
+ parts: int | None = None # PDF pages or Excel sheets read
77
+ warnings: list[str] = field(default_factory=list)
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class Document:
82
+ text: str # Markdown
83
+ kind: str # "pdf" | "docx" | "xlsx" | "text"
84
+ parts: int | None # PDF pages / Excel sheets, when meaningful
85
+ truncated: bool
86
+ warnings: tuple[str, ...]
87
+
88
+ @property
89
+ def chars(self) -> int:
90
+ return len(self.text)
91
+
92
+
93
+ Extractor = Callable[[bytes, Limits], Extracted]
94
+ _EXTRACTORS: dict[str, Extractor] = {}
95
+
96
+
97
+ def register_extractor(kind: str, extractor: Extractor) -> Extractor | None:
98
+ """Use ``extractor`` for ``kind`` ("pdf", "docx", "xlsx", "text"); returns the old one."""
99
+ previous = _EXTRACTORS.get(kind)
100
+ _EXTRACTORS[kind] = extractor
101
+ return previous
102
+
103
+
104
+ # ── detection ────────────────────────────────────────────────────────────────
105
+
106
+ _IMAGE_MAGIC = (b"\x89PNG", b"\xff\xd8\xff", b"GIF8", b"BM")
107
+
108
+
109
+ def detect_kind(data: bytes, filename: str = "") -> str:
110
+ """The document kind, judged by content first and the file name second."""
111
+ name = filename.lower()
112
+ head = data[:2048]
113
+ if b"%PDF-" in head[:1024]:
114
+ return "pdf"
115
+ if head.startswith(b"\xd0\xcf\x11\xe0"):
116
+ raise DocumentError(
117
+ "old_format",
118
+ "This is an old Office file (.doc/.xls/.ppt). Save it as .docx or .xlsx and retry.",
119
+ )
120
+ if head.startswith(_IMAGE_MAGIC) or (head[:4] == b"RIFF" and head[8:12] == b"WEBP"):
121
+ raise DocumentError("image", "This is a picture, not a document.")
122
+ if head.startswith(b"PK\x03\x04"):
123
+ try:
124
+ names = set(zipfile.ZipFile(io.BytesIO(data)).namelist())
125
+ except zipfile.BadZipFile as exc:
126
+ raise DocumentError("unreadable", "The file is damaged.") from exc
127
+ if "word/document.xml" in names:
128
+ return "docx"
129
+ if "xl/workbook.xml" in names:
130
+ return "xlsx"
131
+ raise DocumentError("unsupported", "Only PDF, Word (.docx), Excel (.xlsx) and text.")
132
+ if name.endswith(_TEXT_EXTENSIONS) or _looks_like_text(head):
133
+ return "text"
134
+ raise DocumentError("unsupported", "Only PDF, Word (.docx), Excel (.xlsx) and text.")
135
+
136
+
137
+ def _looks_like_text(head: bytes) -> bool:
138
+ if b"\x00" in head:
139
+ return False
140
+ try:
141
+ head.decode("utf-8")
142
+ except UnicodeDecodeError as exc:
143
+ return exc.start >= len(head) - 3 # a character cut at the end of the sample
144
+ return True
145
+
146
+
147
+ # ── entry point ──────────────────────────────────────────────────────────────
148
+
149
+
150
+ def extract_text(data: bytes, filename: str = "", *, limits: Limits | None = None) -> Document:
151
+ """Markdown text of a PDF, Word, Excel or text file. Raises :class:`DocumentError`."""
152
+ limits = limits or Limits()
153
+ if len(data) > limits.max_bytes:
154
+ raise DocumentError("too_large", f"Files can be at most {limits.max_bytes // 2**20} MB.")
155
+ if not data:
156
+ raise DocumentError("empty", "The file is empty.")
157
+ kind = detect_kind(data, filename)
158
+ if kind in ("docx", "xlsx"):
159
+ _check_zip(data, limits)
160
+ try:
161
+ result = _EXTRACTORS[kind](data, limits)
162
+ except DocumentError:
163
+ raise
164
+ except Exception as exc: # parsers raise many kinds of errors on damaged files
165
+ raise DocumentError("unreadable", "The file could not be read.") from exc
166
+ text = _tidy(result.text)
167
+ if not text:
168
+ raise DocumentError("no_text", "No text was found in this file.")
169
+ warnings = list(result.warnings)
170
+ truncated = len(text) > limits.max_chars
171
+ if truncated:
172
+ cut = text.rfind("\n", 0, limits.max_chars)
173
+ text = text[: cut if cut > limits.max_chars // 2 else limits.max_chars].rstrip()
174
+ warnings.append(f"Only the first {limits.max_chars:,} characters were kept.")
175
+ return Document(text, kind, result.parts, truncated, tuple(warnings))
176
+
177
+
178
+ def _check_zip(data: bytes, limits: Limits) -> None:
179
+ infos = zipfile.ZipFile(io.BytesIO(data)).infolist()
180
+ if len(infos) > limits.max_zip_members or (
181
+ sum(i.file_size for i in infos) > limits.max_unzipped_bytes
182
+ ):
183
+ raise DocumentError("too_large", "The file expands to too much data to read safely.")
184
+
185
+
186
+ _CONTROL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
187
+ _BLANK_RUNS = re.compile(r"\n{3,}")
188
+
189
+
190
+ def _tidy(text: str) -> str:
191
+ text = _CONTROL.sub("", text.replace("\r\n", "\n").replace("\r", "\n"))
192
+ text = "\n".join(line.rstrip() for line in text.split("\n"))
193
+ return _BLANK_RUNS.sub("\n\n", text).strip()
194
+
195
+
196
+ # ── plain text ───────────────────────────────────────────────────────────────
197
+
198
+
199
+ def _text(data: bytes, limits: Limits) -> Extracted:
200
+ if data[:2] in (b"\xff\xfe", b"\xfe\xff"):
201
+ return Extracted(data.decode("utf-16", errors="replace"))
202
+ try:
203
+ return Extracted(data.decode("utf-8-sig"))
204
+ except UnicodeDecodeError:
205
+ pass
206
+ if _looks_like_gb2312(data):
207
+ # Simplified Chinese saved by older Windows tools (GBK / GB18030).
208
+ return Extracted(
209
+ data.decode("gb18030", errors="replace"),
210
+ warnings=["The text was not UTF-8; it was read as Chinese (GB18030)."],
211
+ )
212
+ # Windows-1252 decodes almost anything; say so, as some characters may be off.
213
+ return Extracted(data.decode("cp1252", errors="replace"), warnings=["The text was not UTF-8."])
214
+
215
+
216
+ def _looks_like_gb2312(data: bytes) -> bool:
217
+ """Every non-ASCII byte comes in a pair inside the GB2312 range (0xA1-0xFE twice).
218
+
219
+ Western legacy text fails this at once: an accented letter is one high byte followed by
220
+ an ASCII letter or space.
221
+ """
222
+ i, pairs = 0, 0
223
+ while i < len(data):
224
+ byte = data[i]
225
+ if byte < 0x80:
226
+ i += 1
227
+ continue
228
+ if not (0xA1 <= byte <= 0xFE and i + 1 < len(data) and 0xA1 <= data[i + 1] <= 0xFE):
229
+ return False
230
+ pairs += 1
231
+ i += 2
232
+ return pairs > 0
233
+
234
+
235
+ # ── PDF (pypdf) ──────────────────────────────────────────────────────────────
236
+
237
+
238
+ def _pdf(data: bytes, limits: Limits) -> Extracted:
239
+ try:
240
+ from pypdf import PdfReader
241
+ except ImportError as exc:
242
+ raise DocumentError(
243
+ "needs_extra", 'Reading PDF needs: pip install "cairnkit[documents]"'
244
+ ) from exc
245
+ reader = PdfReader(io.BytesIO(data))
246
+ if reader.is_encrypted:
247
+ try:
248
+ opened = reader.decrypt("") # many PDFs only restrict printing or copying
249
+ except Exception as exc:
250
+ raise DocumentError("encrypted", "This PDF is password protected.") from exc
251
+ if not opened:
252
+ raise DocumentError("encrypted", "This PDF is password protected.")
253
+ total = len(reader.pages)
254
+ pages, blank = [], 0
255
+ for number, page in enumerate(reader.pages[: limits.max_pages], start=1):
256
+ text = (page.extract_text() or "").strip()
257
+ if not text:
258
+ blank += 1
259
+ continue
260
+ pages.append(f"[Page {number}]\n{text}")
261
+ warnings = []
262
+ read = min(total, limits.max_pages)
263
+ if not pages:
264
+ raise DocumentError(
265
+ "no_text", "This PDF has no selectable text; it is probably a scan or photos."
266
+ )
267
+ if blank:
268
+ warnings.append(f"{blank} of {read} pages had no text (scanned pages are skipped).")
269
+ if total > limits.max_pages:
270
+ warnings.append(f"Only the first {limits.max_pages} of {total} pages were read.")
271
+ return Extracted("\n\n".join(pages), read, warnings)
272
+
273
+
274
+ # ── Word (.docx, standard library) ───────────────────────────────────────────
275
+
276
+ _W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
277
+
278
+
279
+ def _docx(data: bytes, limits: Limits) -> Extracted:
280
+ archive = zipfile.ZipFile(io.BytesIO(data))
281
+ body = ElementTree.fromstring(archive.read("word/document.xml")).find(f"{_W}body")
282
+ headings = _heading_levels(archive)
283
+ out: list[str] = []
284
+ for block in [] if body is None else list(body):
285
+ if block.tag == f"{_W}p":
286
+ line = _paragraph(block, headings)
287
+ if line.startswith("- ") and out and out[-1].startswith("- "):
288
+ out[-1] += "\n" + line # keep a list together
289
+ elif line:
290
+ out.append(line)
291
+ elif block.tag == f"{_W}tbl":
292
+ out.append(_word_table(block))
293
+ return Extracted("\n\n".join(out))
294
+
295
+
296
+ def _heading_levels(archive: zipfile.ZipFile) -> dict[str, int]:
297
+ """Style id -> heading level. Ids are localized ("Heading1", "1", "Ueberschrift1"),
298
+ so the style's own name ("heading 1", "Title") decides."""
299
+ try:
300
+ styles = ElementTree.fromstring(archive.read("word/styles.xml"))
301
+ except KeyError:
302
+ return {}
303
+ levels = {}
304
+ for style in styles.iter(f"{_W}style"):
305
+ name_el = style.find(f"{_W}name")
306
+ name = (name_el.get(f"{_W}val") or "").lower() if name_el is not None else ""
307
+ if name == "title":
308
+ levels[style.get(f"{_W}styleId", "")] = 1
309
+ elif m := re.fullmatch(r"heading ([1-6])", name):
310
+ levels[style.get(f"{_W}styleId", "")] = int(m.group(1))
311
+ return levels
312
+
313
+
314
+ def _runs_text(element) -> str:
315
+ parts = []
316
+ for node in element.iter():
317
+ if node.tag == f"{_W}t":
318
+ parts.append(node.text or "")
319
+ elif node.tag == f"{_W}tab":
320
+ parts.append("\t")
321
+ elif node.tag in (f"{_W}br", f"{_W}cr"):
322
+ parts.append("\n")
323
+ return "".join(parts)
324
+
325
+
326
+ def _paragraph(p, headings: dict[str, int]) -> str:
327
+ text = _runs_text(p).strip()
328
+ if not text:
329
+ return ""
330
+ props = p.find(f"{_W}pPr")
331
+ style = props.find(f"{_W}pStyle") if props is not None else None
332
+ level = headings.get(style.get(f"{_W}val", "")) if style is not None else None
333
+ if level:
334
+ return f"{'#' * level} {' '.join(text.split())}"
335
+ if props is not None and props.find(f"{_W}numPr") is not None:
336
+ return f"- {text}"
337
+ return text
338
+
339
+
340
+ def _word_table(tbl) -> str:
341
+ rows = []
342
+ for tr in tbl.iter(f"{_W}tr"):
343
+ cells = [" ".join(_runs_text(tc).split()) for tc in tr.findall(f"{_W}tc")]
344
+ if any(cells):
345
+ rows.append(cells)
346
+ return _markdown_table(rows)
347
+
348
+
349
+ # ── Excel (.xlsx, openpyxl) ──────────────────────────────────────────────────
350
+
351
+
352
+ def _xlsx(data: bytes, limits: Limits) -> Extracted:
353
+ try:
354
+ from openpyxl import load_workbook
355
+ except ImportError as exc:
356
+ raise DocumentError(
357
+ "needs_extra", 'Reading Excel needs: pip install "cairnkit[documents]"'
358
+ ) from exc
359
+ book = load_workbook(io.BytesIO(data), read_only=True, data_only=True)
360
+ out, warnings, read = [], [], 0
361
+ try:
362
+ for sheet in book.worksheets:
363
+ if sheet.sheet_state != "visible":
364
+ warnings.append(f"Hidden sheet skipped: {sheet.title}")
365
+ continue
366
+ rows, cut = [], False
367
+ for values in sheet.iter_rows(values_only=True):
368
+ cells = [_cell(v) for v in values]
369
+ if not any(cells):
370
+ continue
371
+ if len(rows) >= limits.max_sheet_rows:
372
+ cut = True
373
+ break
374
+ rows.append(cells)
375
+ read += 1
376
+ if not rows:
377
+ continue
378
+ if cut:
379
+ warnings.append(
380
+ f"Sheet {sheet.title}: only the first {limits.max_sheet_rows:,} rows were read."
381
+ )
382
+ out.append(f"## {sheet.title}\n\n{_markdown_table(rows)}")
383
+ finally:
384
+ book.close()
385
+ return Extracted("\n\n".join(out), read, warnings)
386
+
387
+
388
+ def _cell(value) -> str:
389
+ if value is None:
390
+ return ""
391
+ if isinstance(value, datetime):
392
+ return value.date().isoformat() if value.time() == time() else value.isoformat(" ")
393
+ if isinstance(value, date | time):
394
+ return value.isoformat()
395
+ if isinstance(value, float) and value.is_integer():
396
+ return str(int(value))
397
+ if isinstance(value, bool):
398
+ return "TRUE" if value else "FALSE"
399
+ return " ".join(str(value).split())
400
+
401
+
402
+ # ── shared ───────────────────────────────────────────────────────────────────
403
+
404
+
405
+ def _markdown_table(rows: list[list[str]]) -> str:
406
+ width = max((max((i + 1 for i, c in enumerate(r) if c), default=0) for r in rows), default=0)
407
+ if not width:
408
+ return ""
409
+ lines = []
410
+ for index, row in enumerate(rows):
411
+ cells = [c.replace("|", "\\|") for c in (row + [""] * width)[:width]]
412
+ lines.append("| " + " | ".join(cells) + " |")
413
+ if index == 0:
414
+ lines.append("|" + " --- |" * width)
415
+ return "\n".join(lines)
416
+
417
+
418
+ register_extractor("text", _text)
419
+ register_extractor("pdf", _pdf)
420
+ register_extractor("docx", _docx)
421
+ register_extractor("xlsx", _xlsx)
cairnkit/guardrails.py ADDED
@@ -0,0 +1,124 @@
1
+ # Adapted from hermes-agent v0.23.0 (2bd378e): agent/tool_guardrails.py and
2
+ # agent/tool_result_classification.py
3
+ # Copyright (c) 2025 Nous Research. MIT License. Condensed to the per-turn loop detectors.
4
+ """Per-turn tool loop detection. Side-effect free: returns decisions, the loop acts on them."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import hashlib
9
+ import json
10
+ import re
11
+ from collections import Counter
12
+ from dataclasses import dataclass
13
+ from typing import Any, Literal
14
+
15
+ Action = Literal["allow", "warn", "block", "halt"]
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class GuardrailConfig:
20
+ exact_failure_warn_after: int = 2
21
+ exact_failure_block_after: int = 3
22
+ same_tool_failure_halt_after: int = 5
23
+ identical_result_halt_after: int = 3
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class Decision:
28
+ action: Action = "allow"
29
+ code: str = "allow"
30
+ message: str = ""
31
+
32
+ @property
33
+ def allows_execution(self) -> bool:
34
+ return self.action in ("allow", "warn")
35
+
36
+
37
+ _RATE_LIMIT = re.compile(r"rate[\s_-]?limit|too many requests|\b429\b", re.IGNORECASE)
38
+ _RETRY_AFTER_KEYS = ("retry_after", "retryAfter", "retry_after_seconds", "retry_after_ms")
39
+
40
+
41
+ def is_rate_limited(result: str) -> bool:
42
+ """True when a FAILED result says the backend throttled the call: a ``retry_after`` field,
43
+ a 429 status, or rate-limit wording in its error. Only meaningful for failed results."""
44
+ try:
45
+ data = json.loads(result.strip())
46
+ except ValueError:
47
+ return bool(_RATE_LIMIT.search(result[:500]))
48
+ if not isinstance(data, dict):
49
+ return False
50
+ if any(data.get(k) for k in _RETRY_AFTER_KEYS) or 429 in (
51
+ data.get("status"),
52
+ data.get("status_code"),
53
+ data.get("code"),
54
+ ):
55
+ return True
56
+ error = data.get("error")
57
+ text = error.get("message") or error.get("code") if isinstance(error, dict) else error
58
+ return isinstance(text, str) and bool(_RATE_LIMIT.search(text))
59
+
60
+
61
+ def signature(tool_name: str, arguments: dict[str, Any]) -> str:
62
+ canonical = json.dumps(
63
+ arguments, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str
64
+ )
65
+ return f"{tool_name}:{hashlib.sha256(canonical.encode()).hexdigest()[:16]}"
66
+
67
+
68
+ class GuardrailController:
69
+ def __init__(self, config: GuardrailConfig | None = None):
70
+ self.config = config or GuardrailConfig()
71
+ self._exact_failures: Counter[str] = Counter()
72
+ self._tool_failures: Counter[str] = Counter()
73
+ self._last: tuple[str, str] | None = None
74
+ self._identical_streak = 0
75
+
76
+ def before_call(self, tool_name: str, arguments: dict[str, Any]) -> Decision:
77
+ count = self._exact_failures[signature(tool_name, arguments)]
78
+ if count >= self.config.exact_failure_block_after:
79
+ return Decision(
80
+ "block",
81
+ "repeated_exact_failure_block",
82
+ f"Blocked {tool_name}: the same call failed {count} times with identical "
83
+ "arguments. Stop retrying it unchanged; change strategy or explain the blocker.",
84
+ )
85
+ return Decision()
86
+
87
+ def after_call(
88
+ self, tool_name: str, arguments: dict[str, Any], result: str, failed: bool
89
+ ) -> Decision:
90
+ sig = signature(tool_name, arguments)
91
+ if failed:
92
+ # A throttled call retried after its cooldown is the right move, not a replay: keep
93
+ # it out of the identical-arguments streak. It still counts per tool, so a dead
94
+ # endpoint is bounded by the halt below.
95
+ throttled = is_rate_limited(result)
96
+ if not throttled:
97
+ self._exact_failures[sig] += 1
98
+ self._tool_failures[tool_name] += 1
99
+ if self._tool_failures[tool_name] >= self.config.same_tool_failure_halt_after:
100
+ return Decision(
101
+ "halt",
102
+ "same_tool_failure_halt",
103
+ f"Stopped {tool_name}: it failed {self._tool_failures[tool_name]} times this "
104
+ "turn. Choose a different approach.",
105
+ )
106
+ if not throttled and self._exact_failures[sig] >= self.config.exact_failure_warn_after:
107
+ return Decision(
108
+ "warn",
109
+ "repeated_exact_failure_warning",
110
+ f"{tool_name} has failed {self._exact_failures[sig]} times with identical "
111
+ "arguments. Inspect the error and change strategy.",
112
+ )
113
+ return Decision()
114
+ current = (sig, hashlib.sha256(result.encode()).hexdigest())
115
+ self._identical_streak = self._identical_streak + 1 if current == self._last else 1
116
+ self._last = current
117
+ if self._identical_streak >= self.config.identical_result_halt_after:
118
+ return Decision(
119
+ "halt",
120
+ "identical_call_streak_halt",
121
+ f"Stopped {tool_name}: the same call returned the same result "
122
+ f"{self._identical_streak} times in a row. Use the result already provided.",
123
+ )
124
+ return Decision()
@@ -0,0 +1,17 @@
1
+ from cairnkit.llm.base import ChatModel
2
+ from cairnkit.llm.errors import ClassifiedError, FailoverReason, ModelAPIError, classify_error
3
+ from cairnkit.llm.fallback import FallbackModel
4
+ from cairnkit.llm.openai_compat import OpenAICompatModel, openrouter
5
+ from cairnkit.llm.scripted import ScriptedModel
6
+
7
+ __all__ = [
8
+ "ChatModel",
9
+ "ClassifiedError",
10
+ "FailoverReason",
11
+ "FallbackModel",
12
+ "ModelAPIError",
13
+ "OpenAICompatModel",
14
+ "ScriptedModel",
15
+ "classify_error",
16
+ "openrouter",
17
+ ]
cairnkit/llm/base.py ADDED
@@ -0,0 +1,34 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Awaitable, Callable
4
+ from typing import Any, Protocol, runtime_checkable
5
+
6
+ from cairnkit.types import Message, ModelResponse
7
+
8
+ DeltaHandler = Callable[[str], Awaitable[None] | None]
9
+ """Receives visible answer text as it streams. Tool calls are only returned at the end."""
10
+
11
+
12
+ async def emit_delta(handler: DeltaHandler | None, text: str) -> None:
13
+ if handler is None or not text:
14
+ return
15
+ value = handler(text)
16
+ if value is not None:
17
+ await value
18
+
19
+
20
+ @runtime_checkable
21
+ class ChatModel(Protocol):
22
+ """Anything that can answer a chat request, optionally with tool calls."""
23
+
24
+ name: str
25
+
26
+ async def complete(
27
+ self,
28
+ messages: list[Message],
29
+ *,
30
+ tools: list[dict[str, Any]] | None = None,
31
+ temperature: float | None = None,
32
+ max_tokens: int | None = None,
33
+ on_delta: DeltaHandler | None = None,
34
+ ) -> ModelResponse: ...