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/__init__.py +143 -0
- cairnkit/agents.py +111 -0
- cairnkit/compression.py +973 -0
- cairnkit/curator.py +217 -0
- cairnkit/delegate.py +99 -0
- cairnkit/documents.py +421 -0
- cairnkit/guardrails.py +124 -0
- cairnkit/llm/__init__.py +17 -0
- cairnkit/llm/base.py +34 -0
- cairnkit/llm/errors.py +185 -0
- cairnkit/llm/fallback.py +107 -0
- cairnkit/llm/openai_compat.py +281 -0
- cairnkit/llm/scripted.py +54 -0
- cairnkit/loop.py +310 -0
- cairnkit/memory.py +185 -0
- cairnkit/memory_ops.py +201 -0
- cairnkit/pricing.py +37 -0
- cairnkit/prompt.py +27 -0
- cairnkit/py.typed +0 -0
- cairnkit/review.py +55 -0
- cairnkit/search.py +130 -0
- cairnkit/security.py +215 -0
- cairnkit/skills.py +184 -0
- cairnkit/titles.py +75 -0
- cairnkit/tools.py +175 -0
- cairnkit/types.py +58 -0
- cairnkit-0.5.0.dist-info/METADATA +234 -0
- cairnkit-0.5.0.dist-info/RECORD +31 -0
- cairnkit-0.5.0.dist-info/WHEEL +4 -0
- cairnkit-0.5.0.dist-info/licenses/LICENSE +22 -0
- cairnkit-0.5.0.dist-info/licenses/NOTICE.md +31 -0
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()
|
cairnkit/llm/__init__.py
ADDED
|
@@ -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: ...
|