Knowledge, notes, memory and skills, and a harness to make them used
Four places a model can reach for, differing in who writes a record and how it gets in front of the model. **Knowledge** is uploaded by a person and searched by the model. It goes through `services/files.py:prepare` — the same pipeline as a chat attachment — so the same PDF produces the same text whichever way it arrived, and `Document` carries the same content columns as `Attachment` for the same reason. **Notes** are written by the model and edited by you. Too long to inject, so they are searched. **Memory** is short facts, and every one of them goes into every request. That single decision is where the rest of its design comes from: records are capped short, the block has a budget, there is no search tool because the model is already looking at them, and they are not shareable — a record about a person is not content to hand round. **Skills** are saved procedures. Only the name and description are injected; the body is fetched when the model decides one applies, which is what makes a hundred skills affordable. A model may write and revise its own — the safety story is not a gate but a record: every revision is kept, attributed and revertible. A model that has just read a hostile page can save a skill that outlives the conversation, and the honest mitigation is that it is visible and undoable rather than that it was prevented. **The harness** is why any of it gets used. A model handed a tools array ignores it and answers from recall, because nothing in the request suggests otherwise. `services/harness.py` assembles a preamble from what this chat actually has: when to reach for each tool, the memories, the skill index. This is an exception to "system prompts are precedence, not concatenation", and a deliberate one. That rule governs the three *authored* layers and is untouched — exactly one still wins. The harness is a different axis: it describes the machinery rather than the behaviour, nobody authored it, and there is nothing for it to disagree with. It is prepended to whichever authored prompt won, in one system message, since several endpoints reject a second. Supporting changes: - **Sharing**, in one helper. `visible_to()` is the only definition of who can see a library item and every listing and tool goes through it. Sharing grants *reading*; two people editing one note with no history and no merge is worse than copying it. **Administrators do not bypass this** — they bypass permissions elsewhere because an admin can grant themselves those anyway, but reading somebody's private notes is a different act. - **FTS5**, created by `db/migrations.py:ensure_fts` with the triggers an external-content index needs. Idempotent, like the column sync beside it. Terms are ANDed and then ORed: the caller is usually a model writing a whole question, and requiring every word loses the match on one absent term. - **The attach button is a menu** — file, image, a web page, or a document from the library. Attaching a document copies it, because history must not change when a document is edited later. - **A URL fetcher with an SSRF guard.** This server can reach the router, the other services on the box and LLeMbas itself, and the address can come from a model. Private ranges are refused *after resolution* and redirects are followed by hand so every hop is checked. An admin can open it deliberately. - **Model capabilities split** into protocol support and a toggle per built-in tool. Rows predating the split have no `tool_*` keys, and absent counts as on when `tools` is on — otherwise an upgrade silently takes web search away from every model already configured for it. Also fixes the test fixture, which built the schema with `create_all` and so ran against a database without the FTS tables production has; it now runs `sync_schema`, the same path startup takes. 430 tests, ruff clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jaroslav Beneš
@@ -156,15 +156,22 @@ def effective_system_prompt(db: DBSession, chat: Chat) -> str:
|
||||
|
||||
|
||||
def build_messages(
|
||||
db: DBSession, chat: Chat, *, upto: Message | None = None, vision: bool = False
|
||||
db: DBSession,
|
||||
chat: Chat,
|
||||
*,
|
||||
upto: Message | None = None,
|
||||
vision: bool = False,
|
||||
system_prompt: str | None = None,
|
||||
) -> list[dict]:
|
||||
"""Assemble the message list to send upstream.
|
||||
|
||||
`upto` excludes the placeholder assistant row being generated into, and
|
||||
everything after it.
|
||||
everything after it. `system_prompt` overrides what would otherwise be
|
||||
resolved, which is how the harness gets in front of the authored prompt
|
||||
without this function knowing anything about tools.
|
||||
"""
|
||||
payload: list[dict[str, Any]] = []
|
||||
system = effective_system_prompt(db, chat)
|
||||
system = effective_system_prompt(db, chat) if system_prompt is None else system_prompt
|
||||
if system:
|
||||
payload.append({"role": ROLE_SYSTEM, "content": system})
|
||||
|
||||
@@ -186,15 +193,40 @@ def build_messages(
|
||||
return payload
|
||||
|
||||
|
||||
def model_supports(db: DBSession, chat: Chat, capability: str) -> bool:
|
||||
"""Whether the chat's current model is marked as having a capability."""
|
||||
model = db.scalar(
|
||||
def model_for(db: DBSession, chat: Chat) -> Model | None:
|
||||
"""The Model row a chat is using, or None if it has gone.
|
||||
|
||||
Looked up by id rather than held as a foreign key, for the same reason
|
||||
resolve_endpoint does: chats store the model as text so history survives an
|
||||
administrator deleting a connection.
|
||||
"""
|
||||
return db.scalar(
|
||||
select(Model).where(Model.model_id == chat.model_id).order_by(Model.position)
|
||||
)
|
||||
|
||||
|
||||
def model_supports(db: DBSession, chat: Chat, capability: str) -> bool:
|
||||
"""Whether the chat's current model is marked as having a capability."""
|
||||
model = model_for(db, chat)
|
||||
return bool(model and (model.capabilities_json or {}).get(capability))
|
||||
|
||||
|
||||
def build_request(db: DBSession, chat: Chat, *, upto: Message | None = None) -> dict[str, Any]:
|
||||
def build_request(
|
||||
db: DBSession,
|
||||
chat: Chat,
|
||||
*,
|
||||
upto: Message | None = None,
|
||||
tools: list[dict[str, Any]] | None = None,
|
||||
user=None,
|
||||
) -> dict[str, Any]:
|
||||
"""The whole request body, tools and harness included.
|
||||
|
||||
Composed here rather than in the generation loop so that "what gets sent"
|
||||
has one answer, and so the harness cannot be forgotten by a future caller
|
||||
that offers tools.
|
||||
"""
|
||||
from lembas.services import harness as harness_service
|
||||
|
||||
params = {
|
||||
key: value
|
||||
for key, value in (chat.params_json or {}).items()
|
||||
@@ -204,11 +236,29 @@ def build_request(db: DBSession, chat: Chat, *, upto: Message | None = None) ->
|
||||
# vision. Sending them to one that has not is not a graceful degradation:
|
||||
# most endpoints reject the whole request.
|
||||
vision = model_supports(db, chat, "vision")
|
||||
return {
|
||||
|
||||
if user is None:
|
||||
from lembas.db.models import User
|
||||
|
||||
user = db.get(User, chat.user_id)
|
||||
|
||||
# The harness describes the tools; the authored prompt describes the
|
||||
# behaviour. See services/harness.py for why these are joined rather than
|
||||
# being two competing layers.
|
||||
system = harness_service.join(
|
||||
harness_service.compose(db, user, tools), effective_system_prompt(db, chat)
|
||||
)
|
||||
|
||||
body: dict[str, Any] = {
|
||||
"model": chat.model_id,
|
||||
"messages": build_messages(db, chat, upto=upto, vision=vision),
|
||||
"messages": build_messages(
|
||||
db, chat, upto=upto, vision=vision, system_prompt=system
|
||||
),
|
||||
**params,
|
||||
}
|
||||
if tools:
|
||||
body["tools"] = tools
|
||||
return body
|
||||
|
||||
|
||||
def default_model(db: DBSession, user=None) -> tuple[str, str] | None:
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
"""Fetching a web page so it can be kept, or read to a model.
|
||||
|
||||
Two things this deliberately does not do.
|
||||
|
||||
**It does not try to be clever about extraction.** No readability heuristics, no
|
||||
main-column detection: script and style go, tags are dropped, whitespace is
|
||||
collapsed. A clever extractor that silently discards the part somebody wanted is
|
||||
worse than a plain one that keeps everything, and it would be a dependency.
|
||||
|
||||
**It does not trust the URL.** This runs on a server that can very likely reach
|
||||
a router's admin page, a metadata endpoint, and every other service on the same
|
||||
machine -- LLeMbas itself included. A fetcher that takes a URL from a user, or
|
||||
worse from a model, is a request-forgery hole unless something stops it, so
|
||||
addresses are checked after resolution and redirects are followed by hand.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import ipaddress
|
||||
import logging
|
||||
import re
|
||||
import socket
|
||||
from dataclasses import dataclass
|
||||
from urllib.parse import urlparse, urlunparse
|
||||
|
||||
import httpx
|
||||
import nh3
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# Pages are kept as text, so the ceiling is about what is worth reading rather
|
||||
# than what will fit on disk.
|
||||
MAX_PAGE_BYTES = 5 * 1024 * 1024
|
||||
MAX_TEXT_CHARS = 120_000
|
||||
MAX_REDIRECTS = 5
|
||||
TIMEOUT = 20.0
|
||||
|
||||
# Sent because a plain httpx user agent is blocked by a good number of sites,
|
||||
# and being honest about what this is beats impersonating a browser.
|
||||
USER_AGENT = "Mozilla/5.0 (compatible; LLeMbas/1.0; +https://github.com/homer/LLeMbas)"
|
||||
|
||||
# <head> goes wholesale, which takes script, style and the title with it. The
|
||||
# title is pulled out of the raw HTML first, so removing it here is what stops
|
||||
# it appearing again as the opening line of the body.
|
||||
_DROPPED = re.compile(
|
||||
r"<(head|script|style|noscript|template|svg)\b[^>]*>.*?</\1>",
|
||||
re.IGNORECASE | re.DOTALL,
|
||||
)
|
||||
_TITLE = re.compile(r"<title[^>]*>(.*?)</title>", re.IGNORECASE | re.DOTALL)
|
||||
# Tags that end a line of prose. Turning them into newlines before the tags are
|
||||
# stripped is the difference between readable text and one enormous paragraph.
|
||||
_BREAKS = re.compile(
|
||||
r"</(p|div|section|article|li|tr|h[1-6]|blockquote|pre)\s*>|<br\s*/?>",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
class FetchError(Exception):
|
||||
"""A refused or failed fetch, with a message fit to show a user."""
|
||||
|
||||
def __init__(self, message: str) -> None:
|
||||
super().__init__(message)
|
||||
self.message = message
|
||||
|
||||
|
||||
@dataclass
|
||||
class Fetched:
|
||||
url: str
|
||||
title: str
|
||||
text: str
|
||||
truncated: bool = False
|
||||
|
||||
|
||||
def _is_public(address: str) -> bool:
|
||||
"""Whether an IP is one this server should be willing to fetch from.
|
||||
|
||||
Loopback reaches LLeMbas and every other local service. Private ranges reach
|
||||
the rest of the network the server sits on. Link-local covers cloud metadata
|
||||
endpoints, which is where credentials live.
|
||||
"""
|
||||
try:
|
||||
ip = ipaddress.ip_address(address)
|
||||
except ValueError:
|
||||
return False
|
||||
return not (
|
||||
ip.is_private
|
||||
or ip.is_loopback
|
||||
or ip.is_link_local
|
||||
or ip.is_multicast
|
||||
or ip.is_reserved
|
||||
or ip.is_unspecified
|
||||
)
|
||||
|
||||
|
||||
def check_url(url: str, *, allow_private: bool = False) -> str:
|
||||
"""Validate a URL and return it normalised. Raises FetchError if refused."""
|
||||
try:
|
||||
parsed = urlparse(url.strip())
|
||||
except ValueError as exc:
|
||||
raise FetchError("That does not look like a URL.") from exc
|
||||
|
||||
if parsed.scheme not in ("http", "https"):
|
||||
raise FetchError("Only http and https addresses can be fetched.")
|
||||
if not parsed.hostname:
|
||||
raise FetchError("That URL has no host.")
|
||||
|
||||
if not allow_private:
|
||||
try:
|
||||
# Resolved, not parsed: a hostname pointing at 127.0.0.1 is the
|
||||
# obvious way past a check that only looks at the text of the URL.
|
||||
resolved = socket.getaddrinfo(parsed.hostname, None)
|
||||
except socket.gaierror as exc:
|
||||
raise FetchError(f"Could not resolve {parsed.hostname}.") from exc
|
||||
|
||||
addresses = {info[4][0] for info in resolved}
|
||||
# Every address, not any: a name resolving to one public and one private
|
||||
# address must not be usable to reach the private one.
|
||||
if not addresses or not all(_is_public(address) for address in addresses):
|
||||
raise FetchError(
|
||||
f"{parsed.hostname} resolves to a private or local address. "
|
||||
"An administrator can allow this under Admin → Web search if "
|
||||
"fetching from this network is intended."
|
||||
)
|
||||
|
||||
return urlunparse(parsed)
|
||||
|
||||
|
||||
def html_to_text(html: str) -> tuple[str, str]:
|
||||
"""Reduce a page to (title, text)."""
|
||||
title_match = _TITLE.search(html)
|
||||
title = ""
|
||||
if title_match:
|
||||
title = " ".join(nh3.clean(title_match.group(1), tags=set()).split())
|
||||
|
||||
body = _DROPPED.sub(" ", html)
|
||||
body = _BREAKS.sub("\n", body)
|
||||
# nh3 with no allowed tags leaves the text and escapes nothing structural;
|
||||
# it is the same sanitiser the rest of the application trusts.
|
||||
body = nh3.clean(body, tags=set(), attributes={})
|
||||
|
||||
import html as html_module
|
||||
|
||||
body = html_module.unescape(body)
|
||||
lines = [" ".join(line.split()) for line in body.splitlines()]
|
||||
# Collapse runs of blank lines, which a stripped page is mostly made of.
|
||||
text, blank = [], False
|
||||
for line in lines:
|
||||
if line:
|
||||
text.append(line)
|
||||
blank = False
|
||||
elif not blank:
|
||||
text.append("")
|
||||
blank = True
|
||||
|
||||
return title, "\n".join(text).strip()
|
||||
|
||||
|
||||
async def fetch(url: str, *, allow_private: bool = False) -> Fetched:
|
||||
"""Retrieve a page and reduce it to text.
|
||||
|
||||
Redirects are followed by hand so every hop can be checked. httpx's own
|
||||
following would validate the first address and then happily land on
|
||||
localhost.
|
||||
"""
|
||||
current = check_url(url, allow_private=allow_private)
|
||||
|
||||
try:
|
||||
async with httpx.AsyncClient(
|
||||
timeout=TIMEOUT, follow_redirects=False, headers={"User-Agent": USER_AGENT}
|
||||
) as client:
|
||||
for _ in range(MAX_REDIRECTS + 1):
|
||||
response = await client.get(current)
|
||||
|
||||
if response.is_redirect:
|
||||
location = response.headers.get("location", "")
|
||||
if not location:
|
||||
raise FetchError("That page redirected to nowhere.")
|
||||
current = check_url(
|
||||
str(response.url.join(location)), allow_private=allow_private
|
||||
)
|
||||
continue
|
||||
|
||||
if response.status_code >= 400:
|
||||
raise FetchError(
|
||||
f"{current} returned HTTP {response.status_code}."
|
||||
)
|
||||
break
|
||||
else:
|
||||
raise FetchError("That page redirected too many times.")
|
||||
except httpx.RequestError as exc:
|
||||
raise FetchError(f"Could not reach {current}: {exc}") from exc
|
||||
|
||||
payload = response.content[:MAX_PAGE_BYTES]
|
||||
content_type = response.headers.get("content-type", "")
|
||||
|
||||
if "html" in content_type or payload[:512].lstrip()[:1] == b"<":
|
||||
title, text = html_to_text(payload.decode(response.encoding or "utf-8", "replace"))
|
||||
elif content_type.startswith("text/") or not content_type:
|
||||
title, text = "", payload.decode(response.encoding or "utf-8", "replace")
|
||||
else:
|
||||
raise FetchError(
|
||||
f"That address is {content_type or 'not text'}, which cannot be saved "
|
||||
"as a page. Attach it as a file instead."
|
||||
)
|
||||
|
||||
truncated = len(text) > MAX_TEXT_CHARS
|
||||
if not text.strip():
|
||||
raise FetchError(
|
||||
"Nothing readable was found at that address. It may be a page that "
|
||||
"builds itself with JavaScript, which this cannot run."
|
||||
)
|
||||
|
||||
return Fetched(
|
||||
url=current,
|
||||
title=title or urlparse(current).netloc or current,
|
||||
text=text[:MAX_TEXT_CHARS],
|
||||
truncated=truncated,
|
||||
)
|
||||
|
||||
|
||||
__all__ = ["FetchError", "Fetched", "check_url", "fetch", "html_to_text"]
|
||||
@@ -325,6 +325,84 @@ def store(
|
||||
return attachment
|
||||
|
||||
|
||||
def store_text(
|
||||
db: DBSession,
|
||||
*,
|
||||
user_id: str,
|
||||
chat_id: str | None,
|
||||
filename: str,
|
||||
text: str,
|
||||
truncated: bool = False,
|
||||
source_note: str = "",
|
||||
) -> Attachment:
|
||||
"""Attach text that did not arrive as a file -- a fetched web page.
|
||||
|
||||
Written to disk like any other attachment so it can be downloaded and so
|
||||
there is one cleanup path, rather than a second kind of attachment that
|
||||
exists only in the database.
|
||||
"""
|
||||
body = text[:MAX_EXTRACTED_CHARS]
|
||||
payload = body.encode("utf-8")
|
||||
|
||||
stored_name = f"{secrets.token_hex(16)}.txt"
|
||||
(attachments_dir() / stored_name).write_bytes(payload)
|
||||
|
||||
attachment = Attachment(
|
||||
user_id=user_id,
|
||||
chat_id=chat_id,
|
||||
filename=safe_display_name(filename),
|
||||
stored_name=stored_name,
|
||||
media_type="text/plain",
|
||||
size_bytes=len(payload),
|
||||
kind=KIND_TEXT,
|
||||
# The URL leads the text so the model can cite it, and so the reader
|
||||
# can see where an attachment called "Some Page.txt" came from.
|
||||
extracted_text=f"Source: {source_note}\n\n{body}" if source_note else body,
|
||||
truncated=truncated,
|
||||
)
|
||||
db.add(attachment)
|
||||
db.commit()
|
||||
return attachment
|
||||
|
||||
|
||||
def copy_document(
|
||||
db: DBSession, *, user_id: str, chat_id: str | None, document
|
||||
) -> Attachment:
|
||||
"""Copy a library document into a message being composed.
|
||||
|
||||
A copy rather than a reference. History must not change under a conversation
|
||||
because a document was edited or deleted afterwards -- the same reason text
|
||||
is extracted once at upload instead of per request. The bytes are duplicated
|
||||
too, so deleting the document cannot leave a message pointing at nothing.
|
||||
"""
|
||||
from lembas.services.library import documents as documents_service
|
||||
|
||||
stored_name = ""
|
||||
source = documents_service.stored_path(document.stored_name)
|
||||
if source is not None:
|
||||
stored_name = f"{secrets.token_hex(16)}{Path(source.name).suffix}"
|
||||
(attachments_dir() / stored_name).write_bytes(source.read_bytes())
|
||||
|
||||
attachment = Attachment(
|
||||
user_id=user_id,
|
||||
chat_id=chat_id,
|
||||
filename=document.filename or f"{document.title}.txt",
|
||||
stored_name=stored_name,
|
||||
media_type=document.media_type,
|
||||
size_bytes=document.size_bytes,
|
||||
kind=document.kind,
|
||||
width=document.width,
|
||||
height=document.height,
|
||||
extracted_text=document.extracted_text,
|
||||
pages=document.pages,
|
||||
truncated=document.truncated,
|
||||
extraction_error=document.extraction_error,
|
||||
)
|
||||
db.add(attachment)
|
||||
db.commit()
|
||||
return attachment
|
||||
|
||||
|
||||
def delete(db: DBSession, attachment: Attachment) -> None:
|
||||
path = stored_path(attachment.stored_name)
|
||||
if path is not None:
|
||||
|
||||
@@ -25,7 +25,6 @@ from datetime import UTC, datetime, timedelta
|
||||
from lembas.db.models import ROLE_ASSISTANT, ROLE_USER, Chat, Message, User
|
||||
from lembas.db.session import session_scope
|
||||
from lembas.services import chat as chat_service
|
||||
from lembas.services import settings_store
|
||||
from lembas.services import tools as tools_service
|
||||
from lembas.services.llm.openai_client import (
|
||||
LLMError,
|
||||
@@ -167,16 +166,16 @@ async def _run(generation: Generation) -> None:
|
||||
return
|
||||
|
||||
endpoint, model_id = chat_service.resolve_endpoint(db, chat)
|
||||
payload = chat_service.build_request(db, chat, upto=message)
|
||||
question = _question_from(payload)
|
||||
needs_title = not chat.title_generated
|
||||
owner = db.get(User, chat.user_id)
|
||||
|
||||
# Read while the session is open: everything below outlives it.
|
||||
offered = tools_service.enabled_tools(db, chat, db.get(User, chat.user_id))
|
||||
search_config = settings_store.search(db) if offered else {}
|
||||
|
||||
if offered:
|
||||
payload = {**payload, "tools": offered}
|
||||
offered = tools_service.enabled_tools(db, chat, owner)
|
||||
payload = chat_service.build_request(
|
||||
db, chat, upto=message, tools=offered, user=owner
|
||||
)
|
||||
question = _question_from(payload)
|
||||
needs_title = not chat.title_generated
|
||||
tool_context = tools_service.context_for(db, owner)
|
||||
|
||||
for round_number in range(tools_service.MAX_ROUNDS + 1):
|
||||
accumulator = tools_service.ToolCallAccumulator()
|
||||
@@ -247,7 +246,7 @@ async def _run(generation: Generation) -> None:
|
||||
]
|
||||
for call in calls:
|
||||
outcome = await tools_service.run_tool(
|
||||
search_config, call["name"], call["arguments"]
|
||||
tool_context, call["name"], call["arguments"]
|
||||
)
|
||||
generation.tool_events.append(outcome.event)
|
||||
generation.touch()
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
"""Telling the model how to use what it has been given.
|
||||
|
||||
A model handed a `tools` array will often ignore it. It answers from recall
|
||||
because that is what it was trained to do, and nothing in the request suggests
|
||||
otherwise. The harness is the part of the prompt that says otherwise: one line
|
||||
per tool about *when* to reach for it, the memories, and the list of skills
|
||||
available.
|
||||
|
||||
**On the "system prompts are precedence, not concatenation" rule.** That rule
|
||||
governs the three authored layers -- instance, model, chat -- and it is
|
||||
untouched here: exactly one of them still wins, and
|
||||
``chat.effective_system_prompt`` still decides which. This is a different axis.
|
||||
It describes the machinery rather than the behaviour, nobody authored it, and
|
||||
there is nothing for it to disagree with. So it is prepended to whichever
|
||||
authored prompt won, inside one system message, under a heading that makes the
|
||||
seam obvious.
|
||||
|
||||
One system message rather than two because several endpoints reject a second
|
||||
one. The authored prompt goes last, where it is closest to the conversation.
|
||||
|
||||
Nothing is emitted for a model with no tools and no memories: an empty harness
|
||||
is worse than none, being tokens that say only that there is nothing to say.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import User
|
||||
from lembas.services.library import memories as memories_service
|
||||
from lembas.services.library import skills as skills_service
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# Keyed by tool family, so a family that is off contributes nothing. Written as
|
||||
# guidance rather than rules: a model told "you MUST search" searches for the
|
||||
# capital of France.
|
||||
GUIDANCE: dict[str, str] = {
|
||||
"web_search": (
|
||||
"- Look things up rather than trusting your recall, whenever the answer "
|
||||
"depends on current facts, on details you are not certain of, or on "
|
||||
"anything that may have changed. If the first results are thin or "
|
||||
"beside the point, search again with different words instead of "
|
||||
"answering from them — two or three searches are normal. Say where an "
|
||||
"answer came from."
|
||||
),
|
||||
"knowledge": (
|
||||
"- The user has a library of their own documents. When a question is "
|
||||
"about their material — their files, their notes on paper, a page they "
|
||||
"saved — search that before searching the web."
|
||||
),
|
||||
"notes": (
|
||||
"- You keep notes across conversations. Search them when a task sounds "
|
||||
"like one you have done before. Write one when you work something out "
|
||||
"that would be tedious to work out again: a procedure, a decision and "
|
||||
"its reasons, a summary of a long document."
|
||||
),
|
||||
# Two variants: the first refers to a heading that only exists when there
|
||||
# is something under it, and telling a model to consult an absent section
|
||||
# is a good way to make it invent one.
|
||||
"memory": (
|
||||
"- You can remember durable facts about this person — a preference, a "
|
||||
"constraint, a name — but not the details of one task, and never "
|
||||
"anything secret."
|
||||
),
|
||||
"memory_with_records": (
|
||||
"- What is listed under “What you know about this person” below was "
|
||||
"remembered earlier and still applies. Add to it only for durable facts "
|
||||
"— a preference, a constraint, a name — never for the details of one "
|
||||
"task, and never for anything secret."
|
||||
),
|
||||
"skills": (
|
||||
"- Skills are procedures you have saved. The list below gives only each "
|
||||
"one's name and when to use it; read the full instructions with "
|
||||
"skill_get before following one. If you work out a repeatable way to do "
|
||||
"something, save it as a new skill."
|
||||
),
|
||||
}
|
||||
|
||||
HEADING = "## How to work"
|
||||
|
||||
# A ceiling on the whole block, so that a large library cannot quietly eat the
|
||||
# context window. Memory and skills have their own caps below this one.
|
||||
MAX_HARNESS_CHARS = 8000
|
||||
|
||||
|
||||
def _families(tools: list[dict[str, Any]]) -> list[str]:
|
||||
"""Which families are represented in an offered tool list, in a fixed order."""
|
||||
from lembas.services.tools import FAMILIES, REGISTRY
|
||||
|
||||
offered = {
|
||||
REGISTRY[name].family
|
||||
for tool in tools
|
||||
if (name := (tool.get("function") or {}).get("name")) in REGISTRY
|
||||
}
|
||||
return [family for family in FAMILIES if family in offered]
|
||||
|
||||
|
||||
def compose(
|
||||
db: DBSession,
|
||||
user: User | None,
|
||||
tools: list[dict[str, Any]] | None,
|
||||
) -> str:
|
||||
"""The operational preamble for this request, or "" when there is nothing to say."""
|
||||
families = _families(tools or [])
|
||||
if not families:
|
||||
return ""
|
||||
|
||||
parts: list[str] = [
|
||||
HEADING,
|
||||
"",
|
||||
"You have tools. Use them rather than guessing; a wrong answer given "
|
||||
"confidently is worse than a slower one that was checked.",
|
||||
"",
|
||||
]
|
||||
# Read before the guidance is assembled, because whether there are any
|
||||
# memories decides which wording the memory line gets.
|
||||
block = memories_service.block(db, user) if "memory" in families else ""
|
||||
|
||||
for family in families:
|
||||
if family == "memory" and block:
|
||||
parts.append(GUIDANCE["memory_with_records"])
|
||||
elif family in GUIDANCE:
|
||||
parts.append(GUIDANCE[family])
|
||||
|
||||
if block:
|
||||
parts += ["", "### What you know about this person", "", block]
|
||||
|
||||
if "skills" in families:
|
||||
index = skills_service.index_block(db, user)
|
||||
if index:
|
||||
parts += [
|
||||
"",
|
||||
"### Skills available",
|
||||
"",
|
||||
index,
|
||||
"",
|
||||
"Read one with skill_get before following it.",
|
||||
]
|
||||
|
||||
text = "\n".join(parts).strip()
|
||||
if len(text) > MAX_HARNESS_CHARS:
|
||||
text = text[:MAX_HARNESS_CHARS].rstrip() + "\n…"
|
||||
return text
|
||||
|
||||
|
||||
def join(harness: str, authored: str) -> str:
|
||||
"""Put the harness in front of whichever authored prompt won.
|
||||
|
||||
Separated from `compose` so the precedence between instance, model and chat
|
||||
stays testable on its own -- this function is the only place the two axes
|
||||
meet.
|
||||
"""
|
||||
if not harness:
|
||||
return authored
|
||||
if not authored:
|
||||
return harness
|
||||
return f"{harness}\n\n---\n\n{authored}"
|
||||
@@ -0,0 +1,18 @@
|
||||
"""The four stores the model can reach for.
|
||||
|
||||
Knowledge, notes and skills are searched; memory is small enough to be handed
|
||||
over whole. Everything here answers to one visibility rule -- see
|
||||
``services.sharing`` -- and nothing here queries a table without it.
|
||||
"""
|
||||
|
||||
from lembas.services.library.fts import SearchHit, fts_query, search_ids
|
||||
from lembas.services.library.memories import MAX_MEMORY_CHARS
|
||||
from lembas.services.library.skills import SKILL_NAME_PATTERN
|
||||
|
||||
__all__ = [
|
||||
"MAX_MEMORY_CHARS",
|
||||
"SKILL_NAME_PATTERN",
|
||||
"SearchHit",
|
||||
"fts_query",
|
||||
"search_ids",
|
||||
]
|
||||
@@ -0,0 +1,166 @@
|
||||
"""The knowledge library: documents a person has collected.
|
||||
|
||||
Ingestion is deliberately **not** written here. A knowledge document and a chat
|
||||
attachment are the same processing problem -- sniff the bytes, downscale the
|
||||
image, extract the PDF once -- so both go through
|
||||
``services.files.prepare``. Keeping one pipeline is what guarantees the same
|
||||
PDF produces the same text whichever way it arrived, and it is why `Document`
|
||||
carries the same content columns as `Attachment`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import secrets
|
||||
from pathlib import Path
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.config import settings
|
||||
from lembas.db.models import SOURCE_LINK, SOURCE_UPLOAD, Document, User
|
||||
from lembas.services import files as files_service
|
||||
from lembas.services import sharing
|
||||
from lembas.services.fetch import Fetched
|
||||
from lembas.services.library.fts import search_ids
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
INDEX = "documents_fts"
|
||||
|
||||
# How much of a document's text a search result carries back to the model. A
|
||||
# whole 100-page extract would swallow the context window; this is enough to
|
||||
# judge relevance and to answer from, and `knowledge_get` fetches the rest.
|
||||
SNIPPET_CHARS = 1200
|
||||
|
||||
|
||||
def library_dir() -> Path:
|
||||
"""Where library files live, beside but separate from chat attachments."""
|
||||
path = settings.uploads_dir / "library"
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def stored_path(stored_name: str) -> Path | None:
|
||||
"""Resolve a stored name, refusing anything outside the library directory.
|
||||
|
||||
The same check as ``services.files.stored_path``, against a different root.
|
||||
"""
|
||||
if not stored_name or "/" in stored_name or "\\" in stored_name or stored_name.startswith("."):
|
||||
return None
|
||||
base = library_dir().resolve()
|
||||
path = (base / stored_name).resolve()
|
||||
try:
|
||||
path.relative_to(base)
|
||||
except ValueError:
|
||||
return None
|
||||
return path if path.is_file() else None
|
||||
|
||||
|
||||
# --- Creating ----------------------------------------------------------------
|
||||
def store_upload(
|
||||
db: DBSession, *, owner: User, payload: bytes, filename: str, title: str = ""
|
||||
) -> Document:
|
||||
"""Add an uploaded file to the library. Raises files.FileError if unusable."""
|
||||
prepared = files_service.prepare(payload, filename)
|
||||
|
||||
stored_name = f"{secrets.token_hex(16)}{prepared.extension}"
|
||||
(library_dir() / stored_name).write_bytes(prepared.payload)
|
||||
|
||||
display = files_service.safe_display_name(filename)
|
||||
document = Document(
|
||||
owner_id=owner.id,
|
||||
title=(title.strip() or display)[:300],
|
||||
source=SOURCE_UPLOAD,
|
||||
filename=display,
|
||||
stored_name=stored_name,
|
||||
media_type=prepared.media_type,
|
||||
size_bytes=len(prepared.payload),
|
||||
kind=prepared.kind,
|
||||
width=prepared.width,
|
||||
height=prepared.height,
|
||||
extracted_text=prepared.extracted_text,
|
||||
pages=prepared.pages,
|
||||
truncated=prepared.truncated,
|
||||
extraction_error=prepared.extraction_error,
|
||||
)
|
||||
db.add(document)
|
||||
db.commit()
|
||||
log.info("library: stored %r (%s) for %s", document.title, document.kind, owner.email)
|
||||
return document
|
||||
|
||||
|
||||
def store_page(db: DBSession, *, owner: User, page: Fetched) -> Document:
|
||||
"""Add a fetched web page to the library.
|
||||
|
||||
Saved as text rather than as the original HTML: the point of keeping it is
|
||||
what it said, and the markup would have to be reduced again on every read.
|
||||
"""
|
||||
document = Document(
|
||||
owner_id=owner.id,
|
||||
title=page.title[:300] or page.url[:300],
|
||||
source=SOURCE_LINK,
|
||||
source_url=page.url,
|
||||
filename="",
|
||||
media_type="text/plain",
|
||||
size_bytes=len(page.text.encode("utf-8")),
|
||||
kind="text",
|
||||
extracted_text=page.text,
|
||||
truncated=page.truncated,
|
||||
)
|
||||
db.add(document)
|
||||
db.commit()
|
||||
log.info("library: saved page %r for %s", document.title, owner.email)
|
||||
return document
|
||||
|
||||
|
||||
# --- Reading -----------------------------------------------------------------
|
||||
def visible(db: DBSession, user: User | None):
|
||||
return select(Document).where(sharing.visible_to(Document, user))
|
||||
|
||||
|
||||
def get(db: DBSession, document_id: str, user: User | None) -> Document | None:
|
||||
document = db.get(Document, document_id)
|
||||
if document is None or not sharing.can_read(db, document, user):
|
||||
return None
|
||||
return document
|
||||
|
||||
|
||||
def search(
|
||||
db: DBSession, user: User | None, needle: str, *, limit: int = 10
|
||||
) -> list[Document]:
|
||||
"""Documents matching `needle` that this user may see, best match first.
|
||||
|
||||
The index is searched first and the visibility filter applied to the rows
|
||||
it returned. That order matters: filtering afterwards is what makes it
|
||||
impossible for a hit on somebody else's document to leak, even as a count.
|
||||
"""
|
||||
hits = search_ids(db, INDEX, needle, limit=limit * 4)
|
||||
if not hits:
|
||||
return []
|
||||
|
||||
order = {hit.id: position for position, hit in enumerate(hits)}
|
||||
rows = list(
|
||||
db.scalars(visible(db, user).where(Document.id.in_(list(order))))
|
||||
)
|
||||
rows.sort(key=lambda document: order.get(document.id, len(order)))
|
||||
return rows[:limit]
|
||||
|
||||
|
||||
def snippet(document: Document) -> str:
|
||||
"""The part of a document a search result carries."""
|
||||
text = (document.extracted_text or "").strip()
|
||||
if len(text) <= SNIPPET_CHARS:
|
||||
return text
|
||||
return text[:SNIPPET_CHARS].rstrip() + "…"
|
||||
|
||||
|
||||
# --- Removing ----------------------------------------------------------------
|
||||
def delete(db: DBSession, document: Document) -> None:
|
||||
path = stored_path(document.stored_name)
|
||||
if path is not None:
|
||||
path.unlink(missing_ok=True)
|
||||
# Shares carry no foreign key to their resource, so nothing cascades.
|
||||
sharing.forget_resource(db, document)
|
||||
db.delete(document)
|
||||
db.commit()
|
||||
@@ -0,0 +1,95 @@
|
||||
"""Querying the full-text indexes.
|
||||
|
||||
One helper for all three stores. The interesting part is turning what somebody
|
||||
typed into something FTS5 will accept: its MATCH syntax has operators (`AND`,
|
||||
`NEAR`, `*`, `^`, `:`) and a quoting rule, so a bare question mark or an
|
||||
unbalanced quote is a syntax error rather than a search that finds nothing.
|
||||
|
||||
Every token is therefore quoted and the operators are dropped. That costs the
|
||||
ability to type an FTS expression on purpose, which nobody was going to do, and
|
||||
buys a search box that cannot be made to throw.
|
||||
|
||||
Search returns ids and leaves loading to the caller, which is what keeps the
|
||||
visibility filter in one place: `services.sharing.visible_to` is applied to the
|
||||
row query, not here.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
|
||||
from sqlalchemy import text
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# Anything that is not a word character or an apostrophe is a separator. Keeps
|
||||
# accented letters (\w is Unicode-aware here) and loses the operators.
|
||||
_TOKENS = re.compile(r"[^\W_]+(?:'[^\W_]+)*", re.UNICODE)
|
||||
|
||||
MAX_TERMS = 24
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SearchHit:
|
||||
id: str
|
||||
rank: float
|
||||
|
||||
|
||||
def _terms(needle: str) -> list[str]:
|
||||
tokens = _TOKENS.findall(needle or "")[:MAX_TERMS]
|
||||
# Doubling any embedded quote is the FTS5 escape; tokens cannot contain one
|
||||
# after the regex above, but the rule is written out so it stays true if the
|
||||
# pattern is ever loosened.
|
||||
return ['"' + token.replace('"', '""') + '"' for token in tokens]
|
||||
|
||||
|
||||
def fts_query(needle: str, *, operator: str = "AND") -> str:
|
||||
"""Turn typed text into a safe FTS5 MATCH expression."""
|
||||
terms = _terms(needle)
|
||||
return f" {operator} ".join(terms) if terms else ""
|
||||
|
||||
|
||||
def search_ids(
|
||||
db: DBSession, index: str, needle: str, *, limit: int = 20
|
||||
) -> list[SearchHit]:
|
||||
"""Ids matching `needle`, best first.
|
||||
|
||||
`index` is a table name from db.migrations.FTS_INDEXES and never comes from
|
||||
a request -- it is interpolated because SQLite cannot parameterise an
|
||||
identifier, so it must stay that way.
|
||||
|
||||
Every term is required first, then any of them. AND alone is right for a
|
||||
search box, where more words should narrow the result -- but the caller here
|
||||
is usually a *model*, which writes "who built the west gate of Moria and
|
||||
what is its password" rather than "moria gate". One word absent from the
|
||||
document then loses the match entirely. Falling back to OR keeps precision
|
||||
where it works and recall where it does not, and bm25 sorts the difference
|
||||
out: documents matching more terms rank higher anyway.
|
||||
"""
|
||||
if not fts_query(needle):
|
||||
return []
|
||||
|
||||
def run(query: str) -> list[SearchHit]:
|
||||
try:
|
||||
rows = db.execute(
|
||||
text(
|
||||
f"SELECT id, bm25({index}) AS rank FROM {index} " # noqa: S608 - see above
|
||||
f"WHERE {index} MATCH :q ORDER BY rank LIMIT :limit"
|
||||
),
|
||||
{"q": query, "limit": max(1, min(limit, 100))},
|
||||
).fetchall()
|
||||
except Exception: # noqa: BLE001 - a broken index must not break the page
|
||||
log.exception("full-text search failed on %s", index)
|
||||
# Rolled back because a failed statement leaves the session
|
||||
# unusable: without this, one broken search turns into every later
|
||||
# query in the same request failing too, which looks nothing like a
|
||||
# search problem.
|
||||
db.rollback()
|
||||
return []
|
||||
# bm25 returns a negative number, better matches being more negative.
|
||||
return [SearchHit(id=row[0], rank=float(row[1])) for row in rows]
|
||||
|
||||
return run(fts_query(needle)) or run(fts_query(needle, operator="OR"))
|
||||
@@ -0,0 +1,119 @@
|
||||
"""Memory: short facts, in front of the model on every turn.
|
||||
|
||||
The whole design follows from being injected rather than searched.
|
||||
|
||||
* Each record is **capped short**, because every one of them costs tokens on
|
||||
every request forever. A tool that writes an essay gets it trimmed and is
|
||||
told so, rather than the write failing -- the model can then decide to put
|
||||
the long version in a note.
|
||||
* There is a **budget** for the block as a whole. Past it the oldest are left
|
||||
out rather than the request growing without limit; the user can see the whole
|
||||
list in their settings and prune it.
|
||||
* There is **no search tool**. Searching something the model is already looking
|
||||
at is a round trip for nothing.
|
||||
* They are **not shareable**. A record about a person is not content to hand
|
||||
round, and nobody asked to share their memories with a group.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
from sqlalchemy import func, select
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import AUTHOR_MODEL, AUTHOR_USER, Memory, User
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# One fact, not a paragraph. Long enough for "prefers metric units and a 24-hour
|
||||
# clock", short enough that fifty of them are still affordable.
|
||||
MAX_MEMORY_CHARS = 400
|
||||
|
||||
# Ceiling on the injected block. Reached, the oldest records drop out of the
|
||||
# prompt -- they are still listed in settings, so nothing disappears silently.
|
||||
MAX_TOTAL_CHARS = 4000
|
||||
|
||||
# A hard stop on how many can exist, so an enthusiastic model cannot fill a
|
||||
# database with variations on one fact.
|
||||
MAX_RECORDS = 200
|
||||
|
||||
|
||||
def all_for(db: DBSession, user: User | None) -> list[Memory]:
|
||||
if user is None:
|
||||
return []
|
||||
return list(
|
||||
db.scalars(
|
||||
select(Memory).where(Memory.owner_id == user.id).order_by(Memory.created_at)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def get(db: DBSession, memory_id: str, user: User | None) -> Memory | None:
|
||||
memory = db.get(Memory, memory_id)
|
||||
if memory is None or user is None or memory.owner_id != user.id:
|
||||
return None
|
||||
return memory
|
||||
|
||||
|
||||
def add(db: DBSession, *, owner: User, content: str, author: str = AUTHOR_MODEL) -> Memory:
|
||||
"""Record a fact. Raises ValueError when there is no room or nothing to say."""
|
||||
content = " ".join((content or "").split())
|
||||
if not content:
|
||||
raise ValueError("A memory cannot be empty.")
|
||||
|
||||
count = db.scalar(
|
||||
select(func.count()).select_from(Memory).where(Memory.owner_id == owner.id)
|
||||
)
|
||||
if (count or 0) >= MAX_RECORDS:
|
||||
raise ValueError(
|
||||
f"There are already {MAX_RECORDS} memories. Remove one first, or put "
|
||||
f"this in a note instead."
|
||||
)
|
||||
|
||||
memory = Memory(
|
||||
owner_id=owner.id,
|
||||
content=content[:MAX_MEMORY_CHARS],
|
||||
author=author if author in (AUTHOR_USER, AUTHOR_MODEL) else AUTHOR_MODEL,
|
||||
)
|
||||
db.add(memory)
|
||||
db.commit()
|
||||
return memory
|
||||
|
||||
|
||||
def update(db: DBSession, memory: Memory, content: str) -> Memory:
|
||||
content = " ".join((content or "").split())
|
||||
if not content:
|
||||
raise ValueError("A memory cannot be empty.")
|
||||
memory.content = content[:MAX_MEMORY_CHARS]
|
||||
db.commit()
|
||||
return memory
|
||||
|
||||
|
||||
def delete(db: DBSession, memory: Memory) -> None:
|
||||
db.delete(memory)
|
||||
db.commit()
|
||||
|
||||
|
||||
def block(db: DBSession, user: User | None) -> str:
|
||||
"""The memories as they appear in the prompt, within the budget.
|
||||
|
||||
Oldest first, and truncation drops the *newest* -- a fact that has survived
|
||||
a long time is more likely to be a standing preference than something said
|
||||
once this morning.
|
||||
"""
|
||||
records = all_for(db, user)
|
||||
if not records:
|
||||
return ""
|
||||
|
||||
lines: list[str] = []
|
||||
total = 0
|
||||
for memory in records:
|
||||
line = f"- {memory.content}"
|
||||
if total + len(line) > MAX_TOTAL_CHARS:
|
||||
lines.append(f"- (…{len(records) - len(lines)} more, see your settings)")
|
||||
break
|
||||
lines.append(line)
|
||||
total += len(line)
|
||||
|
||||
return "\n".join(lines)
|
||||
@@ -0,0 +1,92 @@
|
||||
"""Notes: what the model wrote down, and what a person wrote for it.
|
||||
|
||||
Longer and more specific than a memory, and not injected. A dozen notes would
|
||||
fill a context window on their own, so the model searches for the one it needs
|
||||
-- which is also why a note has a title worth reading: it is what a search
|
||||
result shows.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import AUTHOR_MODEL, AUTHOR_USER, Note, User
|
||||
from lembas.services import sharing
|
||||
from lembas.services.library.fts import search_ids
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
INDEX = "notes_fts"
|
||||
|
||||
MAX_TITLE_CHARS = 300
|
||||
MAX_BODY_CHARS = 40_000
|
||||
SNIPPET_CHARS = 800
|
||||
|
||||
|
||||
def visible(db: DBSession, user: User | None):
|
||||
return select(Note).where(sharing.visible_to(Note, user))
|
||||
|
||||
|
||||
def get(db: DBSession, note_id: str, user: User | None) -> Note | None:
|
||||
note = db.get(Note, note_id)
|
||||
if note is None or not sharing.can_read(db, note, user):
|
||||
return None
|
||||
return note
|
||||
|
||||
|
||||
def recent(db: DBSession, user: User | None, *, limit: int = 20) -> list[Note]:
|
||||
return list(
|
||||
db.scalars(visible(db, user).order_by(Note.updated_at.desc()).limit(limit))
|
||||
)
|
||||
|
||||
|
||||
def search(db: DBSession, user: User | None, needle: str, *, limit: int = 10) -> list[Note]:
|
||||
"""Notes matching `needle` that this user may see, best match first."""
|
||||
hits = search_ids(db, INDEX, needle, limit=limit * 4)
|
||||
if not hits:
|
||||
return []
|
||||
order = {hit.id: position for position, hit in enumerate(hits)}
|
||||
rows = list(db.scalars(visible(db, user).where(Note.id.in_(list(order)))))
|
||||
rows.sort(key=lambda note: order.get(note.id, len(order)))
|
||||
return rows[:limit]
|
||||
|
||||
|
||||
def create(
|
||||
db: DBSession, *, owner: User, title: str, body: str, author: str = AUTHOR_USER
|
||||
) -> Note:
|
||||
note = Note(
|
||||
owner_id=owner.id,
|
||||
title=(title.strip() or "Untitled")[:MAX_TITLE_CHARS],
|
||||
body=body.strip()[:MAX_BODY_CHARS],
|
||||
author=author if author in (AUTHOR_USER, AUTHOR_MODEL) else AUTHOR_USER,
|
||||
)
|
||||
db.add(note)
|
||||
db.commit()
|
||||
return note
|
||||
|
||||
|
||||
def update(db: DBSession, note: Note, *, title: str | None = None, body: str | None = None) -> Note:
|
||||
"""Change a note. Absent arguments are left alone, which is what lets a tool
|
||||
edit only the body without having to send the title back."""
|
||||
if title is not None and title.strip():
|
||||
note.title = title.strip()[:MAX_TITLE_CHARS]
|
||||
if body is not None:
|
||||
note.body = body.strip()[:MAX_BODY_CHARS]
|
||||
db.commit()
|
||||
return note
|
||||
|
||||
|
||||
def delete(db: DBSession, note: Note) -> None:
|
||||
sharing.forget_resource(db, note)
|
||||
db.delete(note)
|
||||
db.commit()
|
||||
|
||||
|
||||
def snippet(note: Note) -> str:
|
||||
text = (note.body or "").strip()
|
||||
if len(text) <= SNIPPET_CHARS:
|
||||
return text
|
||||
return text[:SNIPPET_CHARS].rstrip() + "…"
|
||||
@@ -0,0 +1,207 @@
|
||||
"""Skills: named instructions the model can choose to follow.
|
||||
|
||||
Two fields carry the design.
|
||||
|
||||
`description` is what gets injected -- one line per skill, for every skill --
|
||||
and is therefore the only thing the model has to go on when deciding whether a
|
||||
skill is relevant. A description that does not say *when* to use the skill makes
|
||||
it invisible in practice.
|
||||
|
||||
`body` is fetched only when the model decides to use it. That split is what
|
||||
makes a hundred skills affordable: the index costs a line each, the instructions
|
||||
cost nothing until wanted.
|
||||
|
||||
**A model may rewrite its own skills**, which is the point -- it is how it
|
||||
learns a procedure once instead of being told every time. The safety story is
|
||||
not a gate but a record: every write snapshots what was there first, so a change
|
||||
can be read and undone. A skill written after reading a hostile web page is a
|
||||
real risk, and the honest mitigation is that it is visible, attributed and
|
||||
revertible rather than that it was somehow prevented.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import re
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import AUTHOR_MODEL, AUTHOR_USER, Skill, SkillRevision, User
|
||||
from lembas.services import sharing
|
||||
from lembas.services.library.fts import search_ids
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
INDEX = "skills_fts"
|
||||
|
||||
# A name the model can quote back without getting it wrong.
|
||||
SKILL_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{1,60}$")
|
||||
|
||||
MAX_DESCRIPTION_CHARS = 400
|
||||
MAX_BODY_CHARS = 20_000
|
||||
|
||||
# The index goes into every request, so it has a ceiling like memory does.
|
||||
MAX_INDEX_SKILLS = 60
|
||||
|
||||
|
||||
class SkillError(Exception):
|
||||
"""A rejected skill write, with a message fit for the model or the user."""
|
||||
|
||||
|
||||
def slugify(name: str) -> str:
|
||||
cleaned = re.sub(r"[^a-z0-9]+", "-", (name or "").strip().lower()).strip("-")
|
||||
return cleaned[:60]
|
||||
|
||||
|
||||
def visible(db: DBSession, user: User | None):
|
||||
return select(Skill).where(sharing.visible_to(Skill, user))
|
||||
|
||||
|
||||
def get(db: DBSession, skill_id: str, user: User | None) -> Skill | None:
|
||||
skill = db.get(Skill, skill_id)
|
||||
if skill is None or not sharing.can_read(db, skill, user):
|
||||
return None
|
||||
return skill
|
||||
|
||||
|
||||
def by_name(db: DBSession, name: str, user: User | None) -> Skill | None:
|
||||
"""Look one up the way the model refers to it."""
|
||||
if user is None:
|
||||
return None
|
||||
return db.scalar(visible(db, user).where(Skill.name == slugify(name)))
|
||||
|
||||
|
||||
def enabled_for(db: DBSession, user: User | None) -> list[Skill]:
|
||||
"""Skills that should appear in the index, oldest first for a stable order."""
|
||||
if user is None:
|
||||
return []
|
||||
return list(
|
||||
db.scalars(
|
||||
visible(db, user)
|
||||
.where(Skill.enabled.is_(True))
|
||||
.order_by(Skill.name)
|
||||
.limit(MAX_INDEX_SKILLS)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def search(db: DBSession, user: User | None, needle: str, *, limit: int = 10) -> list[Skill]:
|
||||
hits = search_ids(db, INDEX, needle, limit=limit * 4)
|
||||
if not hits:
|
||||
return []
|
||||
order = {hit.id: position for position, hit in enumerate(hits)}
|
||||
rows = list(db.scalars(visible(db, user).where(Skill.id.in_(list(order)))))
|
||||
rows.sort(key=lambda skill: order.get(skill.id, len(order)))
|
||||
return rows[:limit]
|
||||
|
||||
|
||||
def snapshot(db: DBSession, skill: Skill, *, author: str, note: str = "") -> SkillRevision:
|
||||
"""Record what a skill looked like before it is changed."""
|
||||
revision = SkillRevision(
|
||||
skill_id=skill.id,
|
||||
description=skill.description,
|
||||
body=skill.body,
|
||||
author=author,
|
||||
note=note[:200],
|
||||
)
|
||||
db.add(revision)
|
||||
return revision
|
||||
|
||||
|
||||
def create(
|
||||
db: DBSession,
|
||||
*,
|
||||
owner: User,
|
||||
name: str,
|
||||
description: str,
|
||||
body: str,
|
||||
author: str = AUTHOR_USER,
|
||||
) -> Skill:
|
||||
slug = slugify(name)
|
||||
if not SKILL_NAME_PATTERN.match(slug):
|
||||
raise SkillError(
|
||||
"A skill name must be two or more letters, numbers or hyphens, "
|
||||
"such as 'weekly-report'."
|
||||
)
|
||||
if by_name(db, slug, owner) is not None:
|
||||
raise SkillError(f"A skill called {slug!r} already exists. Edit it instead.")
|
||||
if not description.strip():
|
||||
raise SkillError(
|
||||
"A skill needs a description saying when to use it — it is the only "
|
||||
"thing shown until the skill is opened."
|
||||
)
|
||||
|
||||
skill = Skill(
|
||||
owner_id=owner.id,
|
||||
name=slug,
|
||||
description=description.strip()[:MAX_DESCRIPTION_CHARS],
|
||||
body=body.strip()[:MAX_BODY_CHARS],
|
||||
author=author if author in (AUTHOR_USER, AUTHOR_MODEL) else AUTHOR_USER,
|
||||
)
|
||||
db.add(skill)
|
||||
db.commit()
|
||||
log.info("skill %r created by %s", slug, author)
|
||||
return skill
|
||||
|
||||
|
||||
def update(
|
||||
db: DBSession,
|
||||
skill: Skill,
|
||||
*,
|
||||
description: str | None = None,
|
||||
body: str | None = None,
|
||||
enabled: bool | None = None,
|
||||
author: str = AUTHOR_USER,
|
||||
note: str = "",
|
||||
) -> Skill:
|
||||
"""Change a skill, keeping what it was.
|
||||
|
||||
The snapshot happens before the change and in the same transaction, so
|
||||
there is no window where a skill has been rewritten with no record of what
|
||||
it used to say.
|
||||
"""
|
||||
changing = (description is not None and description.strip() != skill.description) or (
|
||||
body is not None and body.strip() != skill.body
|
||||
)
|
||||
if changing:
|
||||
snapshot(db, skill, author=author, note=note)
|
||||
|
||||
if description is not None and description.strip():
|
||||
skill.description = description.strip()[:MAX_DESCRIPTION_CHARS]
|
||||
if body is not None:
|
||||
skill.body = body.strip()[:MAX_BODY_CHARS]
|
||||
if enabled is not None:
|
||||
skill.enabled = enabled
|
||||
if changing:
|
||||
skill.author = author if author in (AUTHOR_USER, AUTHOR_MODEL) else skill.author
|
||||
|
||||
db.commit()
|
||||
return skill
|
||||
|
||||
|
||||
def revert(db: DBSession, skill: Skill, revision: SkillRevision, *, author: str) -> Skill:
|
||||
"""Put a skill back to an earlier revision.
|
||||
|
||||
The revert is itself a change, so the current state is snapshotted first --
|
||||
going back is undoable too.
|
||||
"""
|
||||
snapshot(db, skill, author=author, note="before revert")
|
||||
skill.description = revision.description
|
||||
skill.body = revision.body
|
||||
db.commit()
|
||||
return skill
|
||||
|
||||
|
||||
def delete(db: DBSession, skill: Skill) -> None:
|
||||
sharing.forget_resource(db, skill)
|
||||
db.delete(skill)
|
||||
db.commit()
|
||||
|
||||
|
||||
def index_block(db: DBSession, user: User | None) -> str:
|
||||
"""The one-line-per-skill listing that goes into the prompt."""
|
||||
skills = enabled_for(db, user)
|
||||
if not skills:
|
||||
return ""
|
||||
return "\n".join(f"- {skill.name}: {skill.description}" for skill in skills)
|
||||
@@ -76,6 +76,11 @@ def _search_defaults() -> dict[str, Any]:
|
||||
"firecrawl_base_url": "https://api.firecrawl.dev",
|
||||
"firecrawl_api_key_encrypted": "",
|
||||
"timeout": 20.0,
|
||||
# Whether saving a link may reach addresses on this machine or this
|
||||
# network. Off, because a server that fetches any URL it is handed can
|
||||
# be pointed at a router's admin page or at LLeMbas itself, and the URL
|
||||
# can come from a model. See services/fetch.py.
|
||||
"allow_private_fetch": False,
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,205 @@
|
||||
"""Who may see a document, a note or a skill.
|
||||
|
||||
One rule, in one place, for all three: you can see a resource if you own it, if
|
||||
it was shared with you by name, or if it was shared with a group you are in.
|
||||
|
||||
Everything that lists or searches a library store goes through `visible_to`.
|
||||
Writing the same condition into each query would work right up until one of
|
||||
them was written slightly differently, and the way that failure shows up is
|
||||
somebody reading somebody else's notes.
|
||||
|
||||
**Administrators are not exempt.** They are elsewhere in this codebase --
|
||||
`security.permissions.resolve` hands an admin every permission -- and that is
|
||||
right for configuration, because an admin can grant themselves those two clicks
|
||||
away. This is a different thing. Nobody made these records available to anyone,
|
||||
and being able to reach a database is not the same as being invited.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy import ColumnElement, delete, or_, select
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import (
|
||||
PRINCIPAL_GROUP,
|
||||
PRINCIPAL_USER,
|
||||
RESOURCE_DOCUMENT,
|
||||
RESOURCE_NOTE,
|
||||
RESOURCE_SKILL,
|
||||
Document,
|
||||
Note,
|
||||
Share,
|
||||
Skill,
|
||||
User,
|
||||
)
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
# The mapping between a model class and the string stored in Share. Kept here
|
||||
# so no caller has to remember which literal goes with which table.
|
||||
RESOURCE_TYPES: dict[Any, str] = {
|
||||
Document: RESOURCE_DOCUMENT,
|
||||
Note: RESOURCE_NOTE,
|
||||
Skill: RESOURCE_SKILL,
|
||||
}
|
||||
|
||||
|
||||
def resource_type(model: Any) -> str:
|
||||
kind = RESOURCE_TYPES.get(model if isinstance(model, type) else type(model))
|
||||
if kind is None:
|
||||
raise ValueError(f"{model!r} is not a shareable resource")
|
||||
return kind
|
||||
|
||||
|
||||
def principal_ids(user: User | None) -> tuple[list[str], list[str]]:
|
||||
"""The ids a share could name to reach this user: themselves, their groups."""
|
||||
if user is None:
|
||||
return [], []
|
||||
return [user.id], [group.id for group in user.groups]
|
||||
|
||||
|
||||
def visible_to(model: Any, user: User | None) -> ColumnElement[bool]:
|
||||
"""A WHERE clause selecting the rows of `model` this user may see.
|
||||
|
||||
Returned as a condition rather than a query so callers can add their own
|
||||
filtering, ordering and pagination without this module knowing about any of
|
||||
it.
|
||||
"""
|
||||
if user is None:
|
||||
# Signed out sees nothing. Not an empty library -- no library.
|
||||
return model.id.is_(None)
|
||||
|
||||
users, groups = principal_ids(user)
|
||||
shared = select(Share.resource_id).where(
|
||||
Share.resource_type == resource_type(model),
|
||||
or_(
|
||||
(Share.principal_type == PRINCIPAL_USER) & Share.principal_id.in_(users),
|
||||
(Share.principal_type == PRINCIPAL_GROUP) & Share.principal_id.in_(groups or [""]),
|
||||
),
|
||||
)
|
||||
return or_(model.owner_id == user.id, model.id.in_(shared))
|
||||
|
||||
|
||||
def owned_by(model: Any, user: User | None) -> ColumnElement[bool]:
|
||||
"""Rows this user may *change*.
|
||||
|
||||
Sharing grants reading, never writing. Two people editing one note with no
|
||||
history and no merge is worse than the inconvenience of copying it.
|
||||
"""
|
||||
if user is None:
|
||||
return model.id.is_(None)
|
||||
return model.owner_id == user.id
|
||||
|
||||
|
||||
def can_read(db: DBSession, resource: Any, user: User | None) -> bool:
|
||||
if user is None or resource is None:
|
||||
return False
|
||||
if resource.owner_id == user.id:
|
||||
return True
|
||||
users, groups = principal_ids(user)
|
||||
found = db.scalar(
|
||||
select(Share.id).where(
|
||||
Share.resource_type == resource_type(resource),
|
||||
Share.resource_id == resource.id,
|
||||
or_(
|
||||
(Share.principal_type == PRINCIPAL_USER) & Share.principal_id.in_(users),
|
||||
(Share.principal_type == PRINCIPAL_GROUP)
|
||||
& Share.principal_id.in_(groups or [""]),
|
||||
),
|
||||
)
|
||||
)
|
||||
return found is not None
|
||||
|
||||
|
||||
def can_write(resource: Any, user: User | None) -> bool:
|
||||
return user is not None and resource is not None and resource.owner_id == user.id
|
||||
|
||||
|
||||
# --- Managing grants ---------------------------------------------------------
|
||||
def grants_for(db: DBSession, resource: Any) -> list[Share]:
|
||||
return list(
|
||||
db.scalars(
|
||||
select(Share).where(
|
||||
Share.resource_type == resource_type(resource),
|
||||
Share.resource_id == resource.id,
|
||||
)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def set_grants(
|
||||
db: DBSession,
|
||||
resource: Any,
|
||||
*,
|
||||
user_ids: list[str],
|
||||
group_ids: list[str],
|
||||
) -> None:
|
||||
"""Replace a resource's shares with exactly these principals."""
|
||||
kind = resource_type(resource)
|
||||
db.execute(
|
||||
delete(Share).where(Share.resource_type == kind, Share.resource_id == resource.id)
|
||||
)
|
||||
|
||||
wanted = [(PRINCIPAL_USER, i) for i in dict.fromkeys(user_ids) if i] + [
|
||||
(PRINCIPAL_GROUP, i) for i in dict.fromkeys(group_ids) if i
|
||||
]
|
||||
for principal_type, principal_id in wanted:
|
||||
# Sharing with yourself is not wrong, just meaningless -- you own it.
|
||||
if principal_type == PRINCIPAL_USER and principal_id == resource.owner_id:
|
||||
continue
|
||||
db.add(
|
||||
Share(
|
||||
resource_type=kind,
|
||||
resource_id=resource.id,
|
||||
principal_type=principal_type,
|
||||
principal_id=principal_id,
|
||||
)
|
||||
)
|
||||
db.commit()
|
||||
|
||||
|
||||
def forget_resource(db: DBSession, resource: Any) -> None:
|
||||
"""Drop every share of a resource that is being deleted.
|
||||
|
||||
Shares carry no foreign key to their resource -- one column pointing at
|
||||
three tables cannot have one -- so nothing cascades and this has to be
|
||||
called explicitly.
|
||||
"""
|
||||
db.execute(
|
||||
delete(Share).where(
|
||||
Share.resource_type == resource_type(resource),
|
||||
Share.resource_id == resource.id,
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def forget_principal(db: DBSession, principal_type: str, principal_id: str) -> int:
|
||||
"""Drop every share naming a user or group that has been deleted.
|
||||
|
||||
Same reason as above: no foreign key, so nothing cascades. Called when an
|
||||
account or a group goes; a stale row would otherwise grant access to
|
||||
whoever next received that id, which is not a risk worth carrying for the
|
||||
sake of a tidy delete.
|
||||
"""
|
||||
result = db.execute(
|
||||
delete(Share).where(
|
||||
Share.principal_type == principal_type, Share.principal_id == principal_id
|
||||
)
|
||||
)
|
||||
return result.rowcount or 0
|
||||
|
||||
|
||||
__all__ = [
|
||||
"can_read",
|
||||
"can_write",
|
||||
"forget_principal",
|
||||
"forget_resource",
|
||||
"grants_for",
|
||||
"owned_by",
|
||||
"resource_type",
|
||||
"set_grants",
|
||||
"visible_to",
|
||||
]
|
||||
+647
-90
@@ -1,19 +1,24 @@
|
||||
"""Tools a model may call while it answers.
|
||||
|
||||
One tool so far -- web search -- but the shape is the point: a registry of
|
||||
named callables with a JSON schema each, offered to the endpoint and executed
|
||||
here when it asks. Built-in tools, MCP servers and agentic execution all plug
|
||||
in at the same place.
|
||||
A registry of named callables with a JSON schema each: offered to the endpoint,
|
||||
executed here when it asks. MCP servers and agentic execution plug in at the
|
||||
same place, which is why the registry is keyed and grouped rather than being a
|
||||
handful of if-statements.
|
||||
|
||||
Two things gate whether a tool is offered at all:
|
||||
Three things gate whether a tool is offered:
|
||||
|
||||
* the administrator has configured and enabled it, and
|
||||
* the chat's model is marked as supporting tools.
|
||||
* the instance is configured for it (web search has a provider, and so on),
|
||||
* the reader has the permission, and
|
||||
* the chat's model is marked as having that tool.
|
||||
|
||||
The second is not optional politeness. Sending a ``tools`` array to an endpoint
|
||||
The last is not optional politeness. Sending a ``tools`` array to an endpoint
|
||||
that does not implement tool calling fails the entire request, exactly the way
|
||||
sending image parts to a model without vision does -- and for the same reason,
|
||||
the capability flag on the model is what decides.
|
||||
sending image parts to a model without vision does.
|
||||
|
||||
Tools that *write* -- notes, memories, skills -- need a database session and a
|
||||
user, and they run inside a background generation that outlives the request. So
|
||||
they are handed a `ToolContext` carrying an owner id rather than a live session,
|
||||
and open their own scope, the same way `services.generation` does.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -26,9 +31,14 @@ from typing import Any
|
||||
|
||||
from sqlalchemy.orm import Session as DBSession
|
||||
|
||||
from lembas.db.models import Chat, User
|
||||
from lembas.db.models import AUTHOR_MODEL, Chat, User
|
||||
from lembas.db.session import session_scope
|
||||
from lembas.services import search as search_service
|
||||
from lembas.services import settings_store
|
||||
from lembas.services.library import documents as documents_service
|
||||
from lembas.services.library import memories as memories_service
|
||||
from lembas.services.library import notes as notes_service
|
||||
from lembas.services.library import skills as skills_service
|
||||
from lembas.services.search.base import SearchError
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
@@ -39,34 +49,30 @@ log = logging.getLogger(__name__)
|
||||
# out, and each round costs a full request.
|
||||
MAX_ROUNDS = 3
|
||||
|
||||
WEB_SEARCH = "web_search"
|
||||
# Tool families, matching the per-model capability flags and the permission
|
||||
# keys. The three names differ by prefix only, which is deliberate: adding a
|
||||
# family means adding one entry here and one permission.
|
||||
FAMILY_SEARCH = "web_search"
|
||||
FAMILY_KNOWLEDGE = "knowledge"
|
||||
FAMILY_NOTES = "notes"
|
||||
FAMILY_MEMORY = "memory"
|
||||
FAMILY_SKILLS = "skills"
|
||||
|
||||
WEB_SEARCH_SCHEMA: dict[str, Any] = {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": WEB_SEARCH,
|
||||
"description": (
|
||||
"Search the web for current information. Use this when the answer "
|
||||
"depends on recent events, on facts you are unsure of, or on "
|
||||
"anything that may have changed since your training data. Returns "
|
||||
"a numbered list of results with titles, URLs and short extracts."
|
||||
),
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "string",
|
||||
"description": "The search terms. Keep them short and specific.",
|
||||
},
|
||||
"max_results": {
|
||||
"type": "integer",
|
||||
"description": "How many results to return. Defaults to the site setting.",
|
||||
},
|
||||
},
|
||||
"required": ["query"],
|
||||
},
|
||||
},
|
||||
}
|
||||
FAMILIES = (FAMILY_SEARCH, FAMILY_KNOWLEDGE, FAMILY_NOTES, FAMILY_MEMORY, FAMILY_SKILLS)
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolContext:
|
||||
"""What a tool needs to do its work, without holding a session open.
|
||||
|
||||
`owner_id` rather than a User for the same reason `Endpoint` is a frozen
|
||||
snapshot rather than a Connection: a generation outlives the request that
|
||||
started it, and a detached SQLAlchemy instance is a trap.
|
||||
"""
|
||||
|
||||
owner_id: str
|
||||
search_config: dict[str, Any] = field(default_factory=dict)
|
||||
allow_private_fetch: bool = False
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -74,7 +80,7 @@ class ToolOutcome:
|
||||
"""What running a tool produced, for the model and for the reader.
|
||||
|
||||
The two are deliberately different. `content` is the flat text the model
|
||||
reads back; `event` is what the transcript shows, and keeps the results
|
||||
reads back; `event` is what the transcript shows, and keeps results
|
||||
structured so they can be rendered as links rather than as a wall of URLs.
|
||||
"""
|
||||
|
||||
@@ -82,72 +88,62 @@ class ToolOutcome:
|
||||
event: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
def enabled_tools(db: DBSession, chat: Chat, user: User | None) -> list[dict[str, Any]]:
|
||||
"""The tool schemas to offer for this chat, which is usually none."""
|
||||
from lembas.security import permissions
|
||||
from lembas.services import chat as chat_service
|
||||
|
||||
config = settings_store.search(db)
|
||||
if not config.get("enabled"):
|
||||
return []
|
||||
if not permissions.has(db, user, "tools.web_search"):
|
||||
return []
|
||||
if not chat_service.model_supports(db, chat, "tools"):
|
||||
return []
|
||||
if search_service.availability(str(config.get("provider") or "ddgs")):
|
||||
# Configured but unusable -- offering a tool that will fail on every
|
||||
# call is worse than not offering it.
|
||||
return []
|
||||
return [WEB_SEARCH_SCHEMA]
|
||||
Runner = Callable[[ToolContext, dict[str, Any]], Awaitable[ToolOutcome]]
|
||||
|
||||
|
||||
async def run_tool(config: dict[str, Any], name: str, arguments: str) -> ToolOutcome:
|
||||
"""Execute one tool call.
|
||||
@dataclass(frozen=True)
|
||||
class ToolDef:
|
||||
name: str
|
||||
family: str
|
||||
description: str
|
||||
parameters: dict[str, Any]
|
||||
run: Runner
|
||||
|
||||
Never raises. A tool that fails hands the model an explanation and lets it
|
||||
carry on -- a failed search should produce "I could not look that up"
|
||||
rather than killing the whole reply.
|
||||
"""
|
||||
if name != WEB_SEARCH:
|
||||
return ToolOutcome(
|
||||
content=f"There is no tool called {name!r}.",
|
||||
event={"name": name, "status": "error", "error": "Unknown tool."},
|
||||
)
|
||||
@property
|
||||
def schema(self) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": self.name,
|
||||
"description": self.description,
|
||||
"parameters": self.parameters,
|
||||
},
|
||||
}
|
||||
|
||||
try:
|
||||
parsed = json.loads(arguments) if arguments.strip() else {}
|
||||
except json.JSONDecodeError:
|
||||
# Small models emit malformed argument JSON often enough that this is a
|
||||
# normal path, not an exceptional one. Treat the whole string as the
|
||||
# query rather than giving up.
|
||||
parsed = {"query": arguments.strip()}
|
||||
if not isinstance(parsed, dict):
|
||||
parsed = {"query": str(parsed)}
|
||||
|
||||
query = str(parsed.get("query") or "").strip()
|
||||
def _object(properties: dict[str, Any], required: list[str]) -> dict[str, Any]:
|
||||
return {"type": "object", "properties": properties, "required": required}
|
||||
|
||||
|
||||
_STRING = {"type": "string"}
|
||||
|
||||
|
||||
# --- Web search --------------------------------------------------------------
|
||||
async def _run_web_search(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
query = str(args.get("query") or "").strip()
|
||||
if not query:
|
||||
return ToolOutcome(
|
||||
content="No search query was given.",
|
||||
event={"name": name, "status": "error", "error": "No query was given."},
|
||||
"No search query was given.",
|
||||
{"name": "web_search", "status": "error", "error": "No query was given."},
|
||||
)
|
||||
|
||||
limit = parsed.get("max_results")
|
||||
limit = args.get("max_results")
|
||||
try:
|
||||
limit = int(limit) if limit is not None else None
|
||||
except (TypeError, ValueError):
|
||||
limit = None
|
||||
|
||||
try:
|
||||
results = await search_service.run(config, query, limit=limit)
|
||||
results = await search_service.run(context.search_config, query, limit=limit)
|
||||
except SearchError as exc:
|
||||
log.info("web search failed for %r: %s", query[:60], exc.message)
|
||||
return ToolOutcome(
|
||||
content=f"The search failed: {exc.message}",
|
||||
event={"name": name, "query": query, "status": "error", "error": exc.message},
|
||||
f"The search failed: {exc.message}",
|
||||
{"name": "web_search", "query": query, "status": "error", "error": exc.message},
|
||||
)
|
||||
|
||||
event = {
|
||||
"name": name,
|
||||
"name": "web_search",
|
||||
"query": query,
|
||||
"status": "ok",
|
||||
"results": [
|
||||
@@ -155,14 +151,573 @@ async def run_tool(config: dict[str, Any], name: str, arguments: str) -> ToolOut
|
||||
for r in results
|
||||
],
|
||||
}
|
||||
|
||||
if not results:
|
||||
return ToolOutcome(content=f"No results were found for {query!r}.", event=event)
|
||||
return ToolOutcome(f"No results were found for {query!r}.", event)
|
||||
|
||||
lines = [f"Search results for {query!r}:"]
|
||||
for index, result in enumerate(results, start=1):
|
||||
lines.append(f"\n[{index}] {result.title}\n{result.url}\n{result.snippet}")
|
||||
return ToolOutcome(content="\n".join(lines), event=event)
|
||||
return ToolOutcome("\n".join(lines), event)
|
||||
|
||||
|
||||
# --- Knowledge ---------------------------------------------------------------
|
||||
async def _run_knowledge_search(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
query = str(args.get("query") or "").strip()
|
||||
if not query:
|
||||
return ToolOutcome(
|
||||
"No search terms were given.",
|
||||
{"name": "knowledge_search", "status": "error", "error": "No query."},
|
||||
)
|
||||
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
found = documents_service.search(db, user, query, limit=6)
|
||||
event = {
|
||||
"name": "knowledge_search",
|
||||
"query": query,
|
||||
"status": "ok",
|
||||
"results": [
|
||||
{"title": d.title, "id": d.id, "kind": d.kind, "host": d.source_url}
|
||||
for d in found
|
||||
],
|
||||
}
|
||||
if not found:
|
||||
return ToolOutcome(
|
||||
f"Nothing in the knowledge library matches {query!r}.", event
|
||||
)
|
||||
|
||||
lines = [f"Knowledge library matches for {query!r}:"]
|
||||
for document in found:
|
||||
lines.append(
|
||||
f"\n[{document.id}] {document.title}\n"
|
||||
f"{documents_service.snippet(document)}"
|
||||
)
|
||||
lines.append(
|
||||
"\nUse knowledge_get with an id in brackets to read a document in full."
|
||||
)
|
||||
return ToolOutcome("\n".join(lines), event)
|
||||
|
||||
|
||||
async def _run_knowledge_get(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
document_id = str(args.get("id") or "").strip()
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
document = documents_service.get(db, document_id, user)
|
||||
if document is None:
|
||||
return ToolOutcome(
|
||||
"There is no such document, or it is not available to you.",
|
||||
{"name": "knowledge_get", "status": "error", "error": "Not found."},
|
||||
)
|
||||
event = {
|
||||
"name": "knowledge_get",
|
||||
"query": document.title,
|
||||
"status": "ok",
|
||||
"results": [{"title": document.title, "id": document.id}],
|
||||
}
|
||||
body = document.extracted_text or document.extraction_error or "(no text)"
|
||||
return ToolOutcome(f"{document.title}\n\n{body}", event)
|
||||
|
||||
|
||||
# --- Notes -------------------------------------------------------------------
|
||||
async def _run_notes_search(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
query = str(args.get("query") or "").strip()
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
found = (
|
||||
notes_service.search(db, user, query, limit=8)
|
||||
if query
|
||||
else notes_service.recent(db, user, limit=8)
|
||||
)
|
||||
event = {
|
||||
"name": "notes_search",
|
||||
"query": query,
|
||||
"status": "ok",
|
||||
"results": [{"title": n.title, "id": n.id} for n in found],
|
||||
}
|
||||
if not found:
|
||||
return ToolOutcome("There are no notes matching that.", event)
|
||||
lines = ["Notes:"]
|
||||
for note in found:
|
||||
lines.append(f"\n[{note.id}] {note.title}\n{notes_service.snippet(note)}")
|
||||
lines.append("\nUse notes_get with an id to read one in full.")
|
||||
return ToolOutcome("\n".join(lines), event)
|
||||
|
||||
|
||||
async def _run_notes_get(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
note = notes_service.get(db, str(args.get("id") or ""), user)
|
||||
if note is None:
|
||||
return ToolOutcome(
|
||||
"There is no such note, or it is not available to you.",
|
||||
{"name": "notes_get", "status": "error", "error": "Not found."},
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"{note.title}\n\n{note.body}",
|
||||
{
|
||||
"name": "notes_get",
|
||||
"query": note.title,
|
||||
"status": "ok",
|
||||
"results": [{"title": note.title, "id": note.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_notes_create(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
title = str(args.get("title") or "").strip()
|
||||
body = str(args.get("body") or "").strip()
|
||||
if not body:
|
||||
return ToolOutcome(
|
||||
"A note needs a body.",
|
||||
{"name": "notes_create", "status": "error", "error": "Empty body."},
|
||||
)
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
note = notes_service.create(
|
||||
db, owner=user, title=title, body=body, author=AUTHOR_MODEL
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Saved note {note.id} — {note.title!r}.",
|
||||
{
|
||||
"name": "notes_create",
|
||||
"query": note.title,
|
||||
"status": "ok",
|
||||
"results": [{"title": note.title, "id": note.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_notes_edit(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
note = notes_service.get(db, str(args.get("id") or ""), user)
|
||||
if note is None or note.owner_id != context.owner_id:
|
||||
return ToolOutcome(
|
||||
"There is no such note, or it belongs to someone else. A note "
|
||||
"shared with you can be read but not changed.",
|
||||
{"name": "notes_edit", "status": "error", "error": "Not writable."},
|
||||
)
|
||||
notes_service.update(
|
||||
db,
|
||||
note,
|
||||
title=args.get("title"),
|
||||
body=args.get("body"),
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Updated note {note.id}.",
|
||||
{
|
||||
"name": "notes_edit",
|
||||
"query": note.title,
|
||||
"status": "ok",
|
||||
"results": [{"title": note.title, "id": note.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_notes_delete(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
note = notes_service.get(db, str(args.get("id") or ""), user)
|
||||
if note is None or note.owner_id != context.owner_id:
|
||||
return ToolOutcome(
|
||||
"There is no such note, or it belongs to someone else.",
|
||||
{"name": "notes_delete", "status": "error", "error": "Not writable."},
|
||||
)
|
||||
title = note.title
|
||||
notes_service.delete(db, note)
|
||||
return ToolOutcome(
|
||||
f"Deleted note {title!r}.",
|
||||
{"name": "notes_delete", "query": title, "status": "ok", "results": []},
|
||||
)
|
||||
|
||||
|
||||
# --- Memory ------------------------------------------------------------------
|
||||
async def _run_memory_add(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
content = str(args.get("content") or "").strip()
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
try:
|
||||
memory = memories_service.add(
|
||||
db, owner=user, content=content, author=AUTHOR_MODEL
|
||||
)
|
||||
except ValueError as exc:
|
||||
return ToolOutcome(
|
||||
str(exc), {"name": "memory_add", "status": "error", "error": str(exc)}
|
||||
)
|
||||
|
||||
note = ""
|
||||
if len(content) > memories_service.MAX_MEMORY_CHARS:
|
||||
# Trimmed rather than refused, with the model told so -- it can then
|
||||
# decide to put the long version in a note.
|
||||
note = (
|
||||
f" It was shortened to {memories_service.MAX_MEMORY_CHARS} characters; "
|
||||
f"use notes for anything longer."
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Remembered: {memory.content}{note}",
|
||||
{
|
||||
"name": "memory_add",
|
||||
"query": memory.content,
|
||||
"status": "ok",
|
||||
"results": [],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_memory_forget(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
wanted = str(args.get("content") or "").strip().lower()
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
records = memories_service.all_for(db, user)
|
||||
match = next((m for m in records if wanted and wanted in m.content.lower()), None)
|
||||
if match is None:
|
||||
return ToolOutcome(
|
||||
"No memory matches that. The full list is in the prompt already.",
|
||||
{"name": "memory_forget", "status": "error", "error": "No match."},
|
||||
)
|
||||
content = match.content
|
||||
memories_service.delete(db, match)
|
||||
return ToolOutcome(
|
||||
f"Forgotten: {content}",
|
||||
{"name": "memory_forget", "query": content, "status": "ok", "results": []},
|
||||
)
|
||||
|
||||
|
||||
# --- Skills ------------------------------------------------------------------
|
||||
async def _run_skill_get(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
name = str(args.get("name") or "").strip()
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
skill = skills_service.by_name(db, name, user)
|
||||
if skill is None:
|
||||
return ToolOutcome(
|
||||
f"There is no skill called {name!r}.",
|
||||
{"name": "skill_get", "status": "error", "error": "Not found."},
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Skill {skill.name}: {skill.description}\n\n{skill.body}",
|
||||
{
|
||||
"name": "skill_get",
|
||||
"query": skill.name,
|
||||
"status": "ok",
|
||||
"results": [{"title": skill.name, "id": skill.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_skill_create(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
try:
|
||||
skill = skills_service.create(
|
||||
db,
|
||||
owner=user,
|
||||
name=str(args.get("name") or ""),
|
||||
description=str(args.get("description") or ""),
|
||||
body=str(args.get("body") or ""),
|
||||
author=AUTHOR_MODEL,
|
||||
)
|
||||
except skills_service.SkillError as exc:
|
||||
return ToolOutcome(
|
||||
str(exc), {"name": "skill_create", "status": "error", "error": str(exc)}
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Created skill {skill.name!r}.",
|
||||
{
|
||||
"name": "skill_create",
|
||||
"query": skill.name,
|
||||
"status": "ok",
|
||||
"results": [{"title": skill.name, "id": skill.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
async def _run_skill_edit(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
|
||||
with session_scope() as db:
|
||||
user = db.get(User, context.owner_id)
|
||||
skill = skills_service.by_name(db, str(args.get("name") or ""), user)
|
||||
if skill is None or skill.owner_id != context.owner_id:
|
||||
return ToolOutcome(
|
||||
"There is no such skill, or it belongs to someone else.",
|
||||
{"name": "skill_edit", "status": "error", "error": "Not writable."},
|
||||
)
|
||||
skills_service.update(
|
||||
db,
|
||||
skill,
|
||||
description=args.get("description"),
|
||||
body=args.get("body"),
|
||||
author=AUTHOR_MODEL,
|
||||
note=str(args.get("reason") or "")[:200],
|
||||
)
|
||||
return ToolOutcome(
|
||||
f"Updated skill {skill.name!r}. The previous version was kept and can "
|
||||
f"be restored.",
|
||||
{
|
||||
"name": "skill_edit",
|
||||
"query": skill.name,
|
||||
"status": "ok",
|
||||
"results": [{"title": skill.name, "id": skill.id}],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
# --- The registry ------------------------------------------------------------
|
||||
REGISTRY: dict[str, ToolDef] = {
|
||||
tool.name: tool
|
||||
for tool in (
|
||||
ToolDef(
|
||||
name="web_search",
|
||||
family=FAMILY_SEARCH,
|
||||
description=(
|
||||
"Search the web for current information. Use this when the answer "
|
||||
"depends on recent events, on facts you are unsure of, or on "
|
||||
"anything that may have changed since your training data. Returns "
|
||||
"a numbered list of results with titles, URLs and short extracts."
|
||||
),
|
||||
parameters=_object(
|
||||
{
|
||||
"query": {
|
||||
"type": "string",
|
||||
"description": "The search terms. Keep them short and specific.",
|
||||
},
|
||||
"max_results": {
|
||||
"type": "integer",
|
||||
"description": "How many results to return.",
|
||||
},
|
||||
},
|
||||
["query"],
|
||||
),
|
||||
run=_run_web_search,
|
||||
),
|
||||
ToolDef(
|
||||
name="knowledge_search",
|
||||
family=FAMILY_KNOWLEDGE,
|
||||
description=(
|
||||
"Search the user's own collected documents, files and saved web "
|
||||
"pages. Use this before searching the web when the question is "
|
||||
"about their material rather than about the world."
|
||||
),
|
||||
parameters=_object(
|
||||
{"query": {**_STRING, "description": "Words likely to appear in the document."}},
|
||||
["query"],
|
||||
),
|
||||
run=_run_knowledge_search,
|
||||
),
|
||||
ToolDef(
|
||||
name="knowledge_get",
|
||||
family=FAMILY_KNOWLEDGE,
|
||||
description="Read one knowledge document in full, by the id a search returned.",
|
||||
parameters=_object({"id": _STRING}, ["id"]),
|
||||
run=_run_knowledge_get,
|
||||
),
|
||||
ToolDef(
|
||||
name="notes_search",
|
||||
family=FAMILY_NOTES,
|
||||
description=(
|
||||
"Search your notes. These are things you or the user wrote down in "
|
||||
"earlier conversations. With no query, returns the most recent."
|
||||
),
|
||||
parameters=_object({"query": _STRING}, []),
|
||||
run=_run_notes_search,
|
||||
),
|
||||
ToolDef(
|
||||
name="notes_get",
|
||||
family=FAMILY_NOTES,
|
||||
description="Read one note in full, by the id a search returned.",
|
||||
parameters=_object({"id": _STRING}, ["id"]),
|
||||
run=_run_notes_get,
|
||||
),
|
||||
ToolDef(
|
||||
name="notes_create",
|
||||
family=FAMILY_NOTES,
|
||||
description=(
|
||||
"Write a note. Use this for something worth having in a later "
|
||||
"conversation that is too long or too detailed for a memory: a "
|
||||
"procedure, a summary, a set of preferences with reasons."
|
||||
),
|
||||
parameters=_object(
|
||||
{"title": _STRING, "body": {**_STRING, "description": "Markdown."}},
|
||||
["title", "body"],
|
||||
),
|
||||
run=_run_notes_create,
|
||||
),
|
||||
ToolDef(
|
||||
name="notes_edit",
|
||||
family=FAMILY_NOTES,
|
||||
description="Change a note you can write to. Omit a field to leave it alone.",
|
||||
parameters=_object({"id": _STRING, "title": _STRING, "body": _STRING}, ["id"]),
|
||||
run=_run_notes_edit,
|
||||
),
|
||||
ToolDef(
|
||||
name="notes_delete",
|
||||
family=FAMILY_NOTES,
|
||||
description="Delete a note that is no longer true or useful.",
|
||||
parameters=_object({"id": _STRING}, ["id"]),
|
||||
run=_run_notes_delete,
|
||||
),
|
||||
ToolDef(
|
||||
name="memory_add",
|
||||
family=FAMILY_MEMORY,
|
||||
description=(
|
||||
"Remember one short, durable fact about the user — a preference, a "
|
||||
"constraint, how they like to be addressed. You are shown every "
|
||||
"memory on every turn, so keep them few and short, and never store "
|
||||
"passwords, keys or anything else secret."
|
||||
),
|
||||
parameters=_object(
|
||||
{"content": {**_STRING, "description": "One fact, in one sentence."}},
|
||||
["content"],
|
||||
),
|
||||
run=_run_memory_add,
|
||||
),
|
||||
ToolDef(
|
||||
name="memory_forget",
|
||||
family=FAMILY_MEMORY,
|
||||
description=(
|
||||
"Remove a memory that has become wrong. Give enough of its text to "
|
||||
"identify it."
|
||||
),
|
||||
parameters=_object({"content": _STRING}, ["content"]),
|
||||
run=_run_memory_forget,
|
||||
),
|
||||
ToolDef(
|
||||
name="skill_get",
|
||||
family=FAMILY_SKILLS,
|
||||
description=(
|
||||
"Read the full instructions for one of the skills listed in your "
|
||||
"prompt. Do this before following a skill — the list gives only its "
|
||||
"name and what it is for."
|
||||
),
|
||||
parameters=_object({"name": _STRING}, ["name"]),
|
||||
run=_run_skill_get,
|
||||
),
|
||||
ToolDef(
|
||||
name="skill_create",
|
||||
family=FAMILY_SKILLS,
|
||||
description=(
|
||||
"Write a new skill: a reusable procedure for a task you expect to be "
|
||||
"asked again. The description must say when to use it, since that is "
|
||||
"all you will see next time."
|
||||
),
|
||||
parameters=_object(
|
||||
{
|
||||
"name": {**_STRING, "description": "Short slug, e.g. 'weekly-report'."},
|
||||
"description": {**_STRING, "description": "When to use this skill."},
|
||||
"body": {**_STRING, "description": "The instructions, in Markdown."},
|
||||
},
|
||||
["name", "description", "body"],
|
||||
),
|
||||
run=_run_skill_create,
|
||||
),
|
||||
ToolDef(
|
||||
name="skill_edit",
|
||||
family=FAMILY_SKILLS,
|
||||
description=(
|
||||
"Improve one of your skills. The previous version is kept and can be "
|
||||
"restored, so say why you changed it."
|
||||
),
|
||||
parameters=_object(
|
||||
{
|
||||
"name": _STRING,
|
||||
"description": _STRING,
|
||||
"body": _STRING,
|
||||
"reason": {**_STRING, "description": "Why the change was made."},
|
||||
},
|
||||
["name"],
|
||||
),
|
||||
run=_run_skill_edit,
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
def _family_allowed(
|
||||
family: str, *, config: dict, capabilities: dict, allowed: dict
|
||||
) -> bool:
|
||||
"""Whether one family is on for this chat.
|
||||
|
||||
A model configured before the per-tool flags existed has no `tool_*` keys.
|
||||
Absent counts as on when `tools` is on, so an upgrade does not silently take
|
||||
web search away from every model already set up for it.
|
||||
"""
|
||||
default = bool(capabilities.get("tools"))
|
||||
if not capabilities.get(f"tool_{family}", default):
|
||||
return False
|
||||
|
||||
if family == FAMILY_SEARCH:
|
||||
return bool(
|
||||
allowed.get("tools.web_search")
|
||||
and config.get("enabled")
|
||||
and not search_service.availability(str(config.get("provider") or "ddgs"))
|
||||
)
|
||||
return bool(allowed.get(f"tools.{family}") and allowed.get("library.use"))
|
||||
|
||||
|
||||
def enabled_tools(db: DBSession, chat: Chat, user: User | None) -> list[dict[str, Any]]:
|
||||
"""The tool schemas to offer for this chat."""
|
||||
from lembas.security import permissions
|
||||
from lembas.services import chat as chat_service
|
||||
|
||||
capabilities = {}
|
||||
model = chat_service.model_for(db, chat)
|
||||
if model is not None:
|
||||
capabilities = model.capabilities_json or {}
|
||||
|
||||
if not capabilities.get("tools"):
|
||||
return []
|
||||
|
||||
allowed = permissions.resolve(db, user)
|
||||
config = settings_store.search(db)
|
||||
|
||||
families = {
|
||||
family
|
||||
for family in FAMILIES
|
||||
if _family_allowed(family, config=config, capabilities=capabilities, allowed=allowed)
|
||||
}
|
||||
return [tool.schema for tool in REGISTRY.values() if tool.family in families]
|
||||
|
||||
|
||||
def context_for(db: DBSession, user: User | None) -> ToolContext:
|
||||
"""The snapshot a running tool needs, taken while the session is open."""
|
||||
return ToolContext(
|
||||
owner_id=user.id if user else "",
|
||||
search_config=settings_store.search(db),
|
||||
)
|
||||
|
||||
|
||||
async def run_tool(context: ToolContext, name: str, arguments: str) -> ToolOutcome:
|
||||
"""Execute one tool call.
|
||||
|
||||
Never raises. A tool that fails hands the model an explanation and lets it
|
||||
carry on -- a failed lookup should produce "I could not find that" rather
|
||||
than killing the whole reply.
|
||||
"""
|
||||
tool = REGISTRY.get(name)
|
||||
if tool is None:
|
||||
return ToolOutcome(
|
||||
f"There is no tool called {name!r}.",
|
||||
{"name": name, "status": "error", "error": "Unknown tool."},
|
||||
)
|
||||
|
||||
try:
|
||||
parsed = json.loads(arguments) if arguments.strip() else {}
|
||||
except json.JSONDecodeError:
|
||||
# Small models emit malformed argument JSON often enough that this is a
|
||||
# normal path, not an exceptional one. Treat the whole string as the
|
||||
# first required argument rather than giving up.
|
||||
required = tool.parameters.get("required") or ["query"]
|
||||
parsed = {required[0]: arguments.strip()}
|
||||
if not isinstance(parsed, dict):
|
||||
parsed = {"query": str(parsed)}
|
||||
|
||||
try:
|
||||
return await tool.run(context, parsed)
|
||||
except Exception as exc: # noqa: BLE001 - a tool must never kill the reply
|
||||
log.exception("tool %s failed", name)
|
||||
return ToolOutcome(
|
||||
f"The {name} tool failed: {exc}",
|
||||
{"name": name, "status": "error", "error": str(exc)[:200]},
|
||||
)
|
||||
|
||||
|
||||
class ToolCallAccumulator:
|
||||
@@ -247,14 +802,16 @@ def tool_turn(call: dict[str, Any], content: str) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
ToolRunner = Callable[..., Awaitable[ToolOutcome]]
|
||||
|
||||
__all__ = [
|
||||
"FAMILIES",
|
||||
"MAX_ROUNDS",
|
||||
"WEB_SEARCH",
|
||||
"REGISTRY",
|
||||
"ToolCallAccumulator",
|
||||
"ToolContext",
|
||||
"ToolDef",
|
||||
"ToolOutcome",
|
||||
"assistant_turn",
|
||||
"context_for",
|
||||
"enabled_tools",
|
||||
"run_tool",
|
||||
"tool_turn",
|
||||
|
||||
Reference in New Issue
Block a user