pal-code 0.1.0__py3-none-any.whl

pal/chat/services/base.py

@@ -0,0 +1,142 @@
+"""What every third-party service tool shares: how it is described, how it reaches the network, and how its errors read.
+
+A service tool is a function the model may ask for by name. Rules that hold for all of them:
+  * off unless named in `tools.services`, and offered only when the message looks like it needs the tool and its key is set;
+  * the key comes from the environment, is sent in a header where the service allows it, and is never in the tool's arguments,
+    its result, an error message or a log (the OS kernel interface logs a URL without its query string);
+  * every request goes through the OS kernel interface, so private addresses, redirects and sizes are checked there;
+  * the result is plain text for the model, and the tool prompt already says tool results are data, never instructions.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from pal.errors import PalError
+from pal.redact import redact
+from pal.tool_manager.components.base import ToolParam
+
+IMAGE_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif"}
+AUDIO_TYPES = {".wav": "audio/wav", ".mp3": "audio/mpeg", ".flac": "audio/flac", ".ogg": "audio/ogg", ".m4a": "audio/mp4"}
+MEDIA_DIRS = ("uploads/", "generated/")
+_RAPID_HOST = re.compile(r"^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.p\.rapidapi\.com$")
+
+
+@dataclass(frozen=True)
+class ServiceSpec:
+    name: str
+    signature: str                       # as the model is told: name(arg, arg)
+    params: tuple                        # ToolParam, ...
+    run: Callable[..., str]
+    summary: str                         # one line, for the docs and `pal doctor`
+    cue: re.Pattern | None               # does the message look like it needs this tool?
+    key_env: str | None = None           # environment variable holding the key; None = no key needed
+    needs: str = ""                      # "image" or "audio": only offered when the session workspace holds such an upload
+    sends: str = ""                      # who receives what, in one phrase
+
+
+def param(name: str, typ: type, default: Any = ..., ) -> ToolParam:
+    return ToolParam(name, typ) if default is ... else ToolParam(name, typ, required=False, default=default)
+
+
+def clamp(n: Any, lo: int, hi: int) -> int:
+    try:
+        return max(lo, min(hi, int(n)))
+    except (TypeError, ValueError):
+        return lo
+
+
+def clean_text(value: Any, what: str, maxlen: int = 300) -> str:
+    s = re.sub(r"[\x00-\x1f]+", " ", str(value)).strip()
+    s = " ".join(s.split())
+    if not s:
+        raise PalError(f"give {what}")
+    return s[:maxlen]
+
+
+def explain(service: str, status: int, text: str, key_env: str | None = None) -> str:
+    """What an HTTP failure means, in words, without ever echoing a key."""
+    body = redact(" ".join(text.split()))[:200]
+    if status in (401, 403):
+        if "not subscribed" in text.lower():
+            return f"{service}: your key is not subscribed to this RapidAPI listing. Subscribe to it on RapidAPI, or set tools.rapidapi_hosts for a listing you have"
+        return f"{service} rejected the key{f' in {key_env}' if key_env else ''}; check that it is valid and allowed to use this API"
+    if status == 402:
+        return f"{service}: payment is required or the quota is used up"
+    if status == 404:
+        return f"{service}: nothing found, or the API address is no longer valid (HTTP 404)"
+    if status == 410:
+        return f"{service}: this API has been retired (HTTP 410)"
+    if status == 429:
+        return f"rate limit or quota reached for {service}; wait and try again later"
+    if status >= 500:
+        return f"{service} is having problems (HTTP {status}); try again later"
+    return f"{service} refused the request (HTTP {status}): {body}"
+
+
+class ServiceCtx:
+    """What a service tool may use. Built fresh for each call."""
+
+    def __init__(self, env: Mapping[str, str], cfg: Any, os_call: Callable[[str, dict], Any]):
+        self.env, self.cfg, self._os = env, cfg, os_call
+        self.saved: list[str] = []            # workspace files this call made, so the turn can offer them for download
+
+    def key(self, var: str) -> str:
+        value = (self.env.get(var) or "").strip()
+        if not value:
+            raise PalError(f"{var} is not set, so this service cannot be used")
+        return value
+
+    def os(self, op: str, params: dict) -> Any:
+        return self._os(op, params)
+
+    def net(self, url: str, **params: Any) -> dict:
+        return self._os("net_request", {"url": url, **params})
+
+    def fetch_json(self, service: str, url: str, *, key_env: str | None = None, **params: Any) -> Any:
+        r = self.net(url, **params)
+        if r["status"] >= 400:
+            raise PalError(explain(service, r["status"], r.get("text", ""), key_env))
+        try:
+            return json.loads(r["text"])
+        except ValueError as e:
+            raise PalError(f"{service} returned something that is not JSON") from e
+
+    def rapid_host(self, tool: str, default: str) -> str:
+        host = str(self.cfg.rapidapi_hosts.get(tool, default)).strip().lower()
+        if not _RAPID_HOST.match(host):
+            raise PalError(f"tools.rapidapi_hosts[{tool}] must be a RapidAPI host such as {default}")
+        return host
+
+    def hf_model(self, tool: str, default: str) -> str:
+        model = str(self.cfg.hf_models.get(tool, default)).strip()
+        # each part starts with a letter or digit, so ".." can never walk up the address that carries the token
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)?", model):
+            raise PalError(f"tools.hf_models[{tool}] is not a valid model name")
+        return model
+
+    def media(self, kind: str) -> list[str]:
+        exts = IMAGE_TYPES if kind == "image" else AUDIO_TYPES
+        found: list[str] = []
+        for prefix in MEDIA_DIRS:
+            found += [p for p in self._os("file_list", {"prefix": prefix}) if "." in p and "." + p.rsplit(".", 1)[1].lower() in exts]
+        return found
+
+    def media_path(self, path: Any, kind: str) -> tuple[str, str]:
+        """(path, content type) for a media file this session holds. Only uploads and generated files, only the right kind."""
+        p = str(path).strip()
+        exts = IMAGE_TYPES if kind == "image" else AUDIO_TYPES
+        ext = "." + p.rsplit(".", 1)[1].lower() if "." in p else ""
+        if not p.startswith(MEDIA_DIRS) or ext not in exts:
+            have = ", ".join(self.media(kind)) or "none yet"
+            raise PalError(f"give the path of an uploaded or generated {kind} file (for example uploads/name{next(iter(exts))}); available: {have}")
+        return p, exts[ext]
+
+
+# -- when an answer is in a shape that is not recognised, show it trimmed instead of failing --------------------------------------------------
+def excerpt(data: Any, n: int = 700) -> str:
+    text = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+    return text if len(text) <= n else text[:n] + " ..."

pal/chat/services/data.py

@@ -0,0 +1,142 @@
+"""Reference services: currency, words and the moon.
+
+  * currency   Frankfurter (central bank reference rates), no key. The paper's RapidAPI converter needs a key and a listing that may change.
+  * moon phase computed here, no network and no key: the phase of the moon is arithmetic.
+  * WordsAPI   its real RapidAPI address and headers (checked against its own documentation); tools.rapidapi_hosts can name another host.
+"""
+from __future__ import annotations
+
+import math
+import re
+from datetime import datetime, timedelta, timezone
+from urllib.parse import quote
+
+from pal.chat.services.base import (
+    ServiceCtx,
+    ServiceSpec,
+    excerpt,
+    param,
+)
+from pal.errors import PalError
+
+RAPID = "RAPIDAPI_KEY"
+_C = re.I
+
+
+# -- currency (Frankfurter, no key) --------------------------------------------------------------------------------------------------
+def currency_convert(ctx: ServiceCtx, amount: float, from_currency: str, to_currency: str) -> str:
+    try:
+        amount = float(amount)
+    except (TypeError, ValueError) as e:
+        raise PalError("amount must be a number") from e
+    if not math.isfinite(amount) or not 0 < amount <= 1e12:
+        raise PalError("amount must be a positive number")
+    codes = []
+    for c in (from_currency, to_currency):
+        c = str(c).strip().upper()
+        if not re.fullmatch(r"[A-Z]{3}", c):
+            raise PalError(f"{c!r} is not a three-letter currency code such as USD or INR")
+        codes.append(c)
+    base, quote_ = codes
+    if base == quote_:
+        return f"{amount:,.2f} {base} = {amount:,.2f} {quote_}"
+    data = ctx.fetch_json("Frankfurter", f"https://api.frankfurter.dev/v2/rate/{base}/{quote_}")
+    rate = float(data["rate"]) if isinstance(data, dict) and isinstance(data.get("rate"), (int, float)) else None
+    if rate is None:
+        raise PalError("Frankfurter returned no rate for that pair")
+    return (f"{amount:,.2f} {base} = {amount * rate:,.2f} {quote_} (1 {base} = {rate:g} {quote_}, reference rate of "
+            f"{data.get('date', 'today')}; not a bank or card rate)")
+
+
+# -- words (WordsAPI on RapidAPI) -----------------------------------------------------------------------------------------------------
+_WORD_INFO = ("all", "definitions", "synonyms", "antonyms", "rhymes", "examples", "pronunciation", "syllables", "frequency")
+
+
+def words_api(ctx: ServiceCtx, word: str, info: str = "definitions") -> str:
+    w = " ".join(str(word).split())
+    if not re.fullmatch(r"[A-Za-z][A-Za-z' -]{0,39}", w):               # too long is refused, never silently cut short
+        raise PalError("give a single English word or short phrase")
+    info = str(info).strip().lower()
+    if info not in _WORD_INFO:
+        raise PalError(f"info must be one of: {', '.join(_WORD_INFO)}")
+    host = ctx.rapid_host("words_api", "wordsapiv1.p.rapidapi.com")
+    url = f"https://{host}/words/{quote(w.lower())}" + ("" if info == "all" else f"/{info}")
+    d = ctx.fetch_json("WordsAPI", url, key_env=RAPID, headers={"X-RapidAPI-Key": ctx.key(RAPID), "X-RapidAPI-Host": host})
+    if not isinstance(d, dict):
+        return excerpt(d)
+    out: list[str] = []
+    if info in ("definitions", "all"):
+        rows = d.get("definitions") or d.get("results") or []
+        out += [f"({r.get('partOfSpeech', '?')}) {r['definition']}" for r in rows[:6] if isinstance(r, dict) and r.get("definition")]
+    if info in ("synonyms", "antonyms", "examples"):
+        if d.get(info):
+            out.append(f"{info}: " + ", ".join(map(str, d[info][:15])))
+    if info == "rhymes" and isinstance(d.get("rhymes"), dict):
+        out.append("rhymes: " + ", ".join(map(str, (d["rhymes"].get("all") or [])[:15])))
+    if info == "pronunciation" and d.get("pronunciation"):
+        p = d["pronunciation"]
+        out.append("pronunciation: " + (", ".join(f"{k} {v}" for k, v in p.items()) if isinstance(p, dict) else str(p)))
+    if info == "syllables" and isinstance(d.get("syllables"), dict):
+        out.append(f"syllables: {d['syllables'].get('count', '?')} ({'-'.join(d['syllables'].get('list', []))})")
+    if info == "frequency" and d.get("frequency") is not None:
+        out.append(f"frequency: {d['frequency']}")
+    if info == "all":
+        syn = sorted({s for r in (d.get("results") or []) if isinstance(r, dict) for s in (r.get("synonyms") or [])})[:12]
+        if syn:
+            out.append("synonyms: " + ", ".join(syn))
+    if not out:
+        return f"nothing found for {w!r}"
+    return f"{d.get('word', w)}:\n" + "\n".join(out)
+
+
+# -- the moon (computed here) ---------------------------------------------------------------------------------------------------------
+SYNODIC_DAYS = 29.530588853                                   # mean length of a lunation
+_REFERENCE_NEW_MOON = datetime(2000, 1, 6, 18, 14, tzinfo=timezone.utc)
+_PHASES = ((0.0339, "New Moon"), (0.2161, "Waxing Crescent"), (0.2839, "First Quarter"), (0.4661, "Waxing Gibbous"),
+           (0.5339, "Full Moon"), (0.7161, "Waning Gibbous"), (0.7839, "Last Quarter"), (0.9661, "Waning Crescent"), (1.01, "New Moon"))
+
+
+def moon(when: datetime) -> dict:
+    """The moon's phase from the mean lunar cycle. Against eight real new and full moons it was off by 13 hours at worst, so it is
+    right to about half a day; around the exact moment of a phase the name may be one day early or late."""
+    age = ((when - _REFERENCE_NEW_MOON).total_seconds() / 86400) % SYNODIC_DAYS
+    frac = age / SYNODIC_DAYS
+    name = next(n for limit, n in _PHASES if frac < limit)
+    return {"age_days": age, "phase": name, "illumination": (1 - math.cos(2 * math.pi * frac)) / 2,
+            "next_new": when + timedelta(days=SYNODIC_DAYS - age),
+            "next_full": when + timedelta(days=(SYNODIC_DAYS / 2 - age) % SYNODIC_DAYS)}
+
+
+def moon_phase(ctx: ServiceCtx, date: str = "") -> str:
+    text = str(date).strip()
+    if text:
+        try:
+            when = datetime.strptime(text, "%Y-%m-%d").replace(hour=12, tzinfo=timezone.utc)
+        except ValueError as e:
+            raise PalError("give the date as YYYY-MM-DD, or leave it empty for today") from e
+        label = text
+    else:
+        when = datetime.now(timezone.utc)
+        label = when.strftime("%Y-%m-%d")
+    m = moon(when)
+    return (f"Moon on {label} (UTC): {m['phase']}, about {m['illumination'] * 100:.0f}% lit, {m['age_days']:.1f} days into the cycle. "
+            f"Next new moon around {m['next_new']:%Y-%m-%d}, next full moon around {m['next_full']:%Y-%m-%d} "
+            "(a simple model, right to about half a day).")
+
+
+SERVICES = [
+    ServiceSpec("currency_convert", "currency_convert(amount, from_currency, to_currency)",
+                (param("amount", float), param("from_currency", str), param("to_currency", str)), currency_convert,
+                "convert money at central bank reference rates (Frankfurter)",
+                re.compile(r"\bcurrency\b|\bexchange rate\b|\bforex\b|\b(?:usd|eur|inr|gbp|jpy|aud|cad|chf|cny)\b|\b(?:dollars?|euros?|rupees?|pounds?|yen)\b", _C),
+                None, sends="the two currency codes go to Frankfurter"),
+    ServiceSpec("words_api", "words_api(word, info)", (param("word", str), param("info", str, "definitions")), words_api,
+                "definitions, synonyms, antonyms, rhymes, examples (WordsAPI)",
+                re.compile(r"\bsynonyms?\b|\bantonyms?\b|\bdefinition of\b|\bdefine\b|\bmeaning of\b|\brhymes? with\b|\bpronunciation\b|\bsyllables?\b|\bwhat does \w+ mean\b", _C),
+                RAPID, sends="the word goes to WordsAPI"),
+    ServiceSpec("moon_phase", "moon_phase(date)", (param("date", str, ""),), moon_phase,
+                "the moon's phase for a date, computed locally (no key, no network)",
+                re.compile(r"\bmoon\b|\blunar\b|\bfull moon\b|\bnew moon\b", _C), None, sends="nothing leaves this machine"),
+]
+
+__all__ = ["SERVICES", "moon", "SYNODIC_DAYS"]

pal/chat/services/media.py

@@ -0,0 +1,123 @@
+"""Hugging Face media tools: describe an image, answer a question about it, make an image, speak text, transcribe audio.
+
+They call the hf-inference route of Hugging Face Inference Providers (router.huggingface.co) with an HF_TOKEN. Uploaded images and
+audio live in the session workspace; the model sees only their path, never the bytes. Made images and audio are saved to the
+workspace under generated/ and can be downloaded from the page. Which models a route serves changes over time: every tool's model
+can be set in tools.hf_models, and Hugging Face's own error text is passed on when a model is not available. These tools were
+tested against fake servers only, never against Hugging Face.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+
+from pal.chat.services.base import ServiceCtx, ServiceSpec, clean_text, excerpt, explain, param
+from pal.errors import PalError
+
+HF = "HF_TOKEN"
+_C = re.I
+_BASE = "https://router.huggingface.co/hf-inference/models/"
+DEFAULT_MODELS = {
+    "image_caption": "Salesforce/blip-image-captioning-large",
+    "visual_question_answering": "dandelin/vilt-b32-finetuned-vqa",
+    "text_to_image": "black-forest-labs/FLUX.1-schnell",
+    "text_to_audio": "facebook/mms-tts-eng",
+    "speech_to_text": "openai/whisper-large-v3",
+}
+
+
+def _call(ctx: ServiceCtx, tool: str, **params) -> dict:
+    model = ctx.hf_model(tool, DEFAULT_MODELS[tool])
+    headers = {"Authorization": "Bearer " + ctx.key(HF), **params.pop("headers", {})}
+    r = ctx.net(_BASE + model, headers=headers, **params)
+    if r["status"] == 503:
+        raise PalError(f"Hugging Face is loading {model}; try again in a minute" + _hf_detail(r))
+    if r["status"] >= 400:
+        raise PalError(explain(f"Hugging Face ({model})", r["status"], r.get("text", ""), HF))
+    return r
+
+
+def _hf_detail(r: dict) -> str:
+    import json
+    try:
+        d = json.loads(r.get("text", ""))
+        return f" (estimated {d['estimated_time']:.0f}s)" if isinstance(d, dict) and d.get("estimated_time") else ""
+    except (ValueError, TypeError, KeyError):
+        return ""
+
+
+def _json(r: dict, what: str):
+    import json
+    try:
+        return json.loads(r["text"])
+    except ValueError as e:
+        raise PalError(f"Hugging Face returned something that is not {what}") from e
+
+
+def image_caption(ctx: ServiceCtx, path: str) -> str:
+    p, ctype = ctx.media_path(path, "image")
+    r = _call(ctx, "image_caption", method="POST", body_path=p, content_type=ctype)
+    d = _json(r, "JSON")
+    text = d[0].get("generated_text") if isinstance(d, list) and d and isinstance(d[0], dict) else (d.get("generated_text") if isinstance(d, dict) else None)
+    return str(text).strip() if text else "no caption: " + excerpt(d)
+
+
+def visual_question_answering(ctx: ServiceCtx, path: str, question: str) -> str:
+    p, _ = ctx.media_path(path, "image")
+    q = clean_text(question, "a question about the image", 300)
+    b64 = ctx.os("file_read_b64", {"path": p})["b64"]
+    r = _call(ctx, "visual_question_answering", method="POST", json={"inputs": {"image": b64, "question": q}})
+    d = _json(r, "JSON")
+    rows = [x for x in d if isinstance(x, dict) and x.get("answer")] if isinstance(d, list) else []
+    return "; ".join(f"{x['answer']} ({x.get('score', 0):.0%})" for x in rows[:3]) or "no answer: " + excerpt(d)
+
+
+def _saved(prefix: str, seed: str) -> str:
+    return f"generated/{prefix}-{hashlib.sha256(seed.encode()).hexdigest()[:8]}.{{ext}}"
+
+
+def text_to_image(ctx: ServiceCtx, prompt: str) -> str:
+    text = clean_text(prompt, "a description of the image", 500)
+    r = _call(ctx, "text_to_image", method="POST", json={"inputs": text}, save_as=_saved("image", text))
+    if not r.get("saved"):
+        raise PalError("Hugging Face did not return an image: " + (r.get("text") or r.get("content_type", ""))[:200])
+    ctx.saved.append(r["saved"])
+    return f"saved the image as {r['saved']} ({r['bytes']:,} bytes); the user can download it"
+
+
+def text_to_audio(ctx: ServiceCtx, text: str) -> str:
+    t = clean_text(text, "the text to speak", 800)
+    r = _call(ctx, "text_to_audio", method="POST", json={"inputs": t}, save_as=_saved("speech", t))
+    if not r.get("saved"):
+        raise PalError("Hugging Face did not return audio: " + (r.get("text") or r.get("content_type", ""))[:200])
+    ctx.saved.append(r["saved"])
+    return f"saved the audio as {r['saved']} ({r['bytes']:,} bytes); the user can download it"
+
+
+def speech_to_text(ctx: ServiceCtx, path: str) -> str:
+    p, ctype = ctx.media_path(path, "audio")
+    r = _call(ctx, "speech_to_text", method="POST", body_path=p, content_type=ctype)
+    d = _json(r, "JSON")
+    text = d.get("text") if isinstance(d, dict) else None
+    return str(text).strip() if text else "no speech found: " + excerpt(d)
+
+
+SERVICES = [
+    ServiceSpec("image_caption", "image_caption(path)", (param("path", str),), image_caption, "describe an uploaded image in one sentence",
+                re.compile(r"\bimage\b|\bpicture\b|\bphoto\b|\bpng\b|\bjpe?g\b|\bwebp\b|\bgif\b|\bcaption\b|\bdescribe\b|\bwhat(?:'s| is) in\b", _C),
+                HF, needs="image", sends="the image goes to Hugging Face"),
+    ServiceSpec("visual_question_answering", "visual_question_answering(path, question)", (param("path", str), param("question", str)),
+                visual_question_answering, "answer a question about an uploaded image",
+                re.compile(r"\bimage\b|\bpicture\b|\bphoto\b|\bpng\b|\bjpe?g\b|\bwebp\b|\bgif\b|\bin (?:the|this) (?:image|picture|photo)\b", _C),
+                HF, needs="image", sends="the image and your question go to Hugging Face"),
+    ServiceSpec("text_to_image", "text_to_image(prompt)", (param("prompt", str),), text_to_image, "make an image from a description",
+                re.compile(r"\b(?:draw|generate|create|make|paint)\b.{0,30}\b(?:image|picture|photo|illustration|logo)\b|\bimage of\b|\bpicture of\b", _C),
+                HF, sends="your description goes to Hugging Face"),
+    ServiceSpec("text_to_audio", "text_to_audio(text)", (param("text", str),), text_to_audio, "turn text into spoken audio",
+                re.compile(r"\bread (?:this )?aloud\b|\btext[- ]to[- ]speech\b|\bsay this\b|\bspeak\b|\bvoice\b|\baudio of\b|\bnarrat", _C),
+                HF, sends="your text goes to Hugging Face"),
+    ServiceSpec("speech_to_text", "speech_to_text(path)", (param("path", str),), speech_to_text,
+                "transcribe an uploaded audio file (voice activity recognition in the AIOS paper)",
+                re.compile(r"\baudio\b|\brecording\b|\bvoice\b|\btranscri\w+\b|\bspeech\b|\bwav\b|\bmp3\b|\bflac\b|\bogg\b|\bm4a\b", _C),
+                HF, needs="audio", sends="the audio goes to Hugging Face"),
+]

pal/chat/services/web.py

@@ -0,0 +1,60 @@
+"""Search and lookup services: Google results and WolframAlpha.
+
+Google's Custom Search JSON API is closed to new customers and ends on 1 January 2027, so the "Google search" tool reads the results
+page through SerpApi, a third-party results service, which needs its own key and sends your query to it.
+"""
+from __future__ import annotations
+
+import re
+from urllib.parse import urlencode
+
+from pal.chat.services.base import ServiceCtx, ServiceSpec, clamp, clean_text, param
+from pal.errors import PalError
+from pal.redact import redact
+
+SERPAPI = "SERPAPI_API_KEY"
+WOLFRAM = "WOLFRAM_APP_ID"
+
+
+def _serp(ctx: ServiceCtx, query: str, num: int) -> str:
+    q = clean_text(query, "a search query", 300)
+    n = clamp(num, 1, 10)
+    url = "https://serpapi.com/search.json?" + urlencode({"engine": "google", "q": q, "num": n, "api_key": ctx.key(SERPAPI)})
+    data = ctx.fetch_json("SerpApi", url, key_env=SERPAPI)
+    if isinstance(data, dict) and data.get("error"):
+        raise PalError("SerpApi: " + redact(str(data["error"]))[:200])
+    rows = (data.get("organic_results") if isinstance(data, dict) else None) or []
+    lines = []
+    for i, r in enumerate(rows[:n], 1):
+        if isinstance(r, dict) and r.get("title"):
+            snippet = " ".join(str(r.get("snippet", "")).split())[:240]
+            lines.append(f"{i}. {r['title']}" + (f" - {snippet}" if snippet else "") + (f" ({r['link']})" if r.get("link") else ""))
+    return "\n".join(lines) or f"no google results for {q!r}"
+
+
+def google_search(ctx: ServiceCtx, query: str, num: int = 5) -> str:
+    return _serp(ctx, query, num)
+
+
+def wolfram_alpha(ctx: ServiceCtx, query: str) -> str:
+    q = clean_text(query, "a question or calculation in plain words", 300)
+    url = "https://www.wolframalpha.com/api/v1/llm-api?" + urlencode({"input": q, "maxchars": 2000})
+    r = ctx.net(url, headers={"Authorization": "Bearer " + ctx.key(WOLFRAM)})
+    if r["status"] in (400, 501):
+        raise PalError("Wolfram|Alpha did not understand that input; try rephrasing it")
+    if r["status"] >= 400:
+        from pal.chat.services.base import explain
+        raise PalError(explain("Wolfram|Alpha", r["status"], r.get("text", ""), WOLFRAM))
+    return (r.get("text") or "").strip() or "Wolfram|Alpha returned no answer"
+
+
+_C = re.I
+SERVICES = [
+    ServiceSpec("google_search", "google_search(query, num)", (param("query", str), param("num", int, 5)), google_search,
+                "Google results for a query (through SerpApi)", re.compile(r"\bgoogle\b|\bweb search\b|\bsearch (?:the )?(?:web|internet|online)\b|\blatest news\b|\bnews about\b", _C),
+                SERPAPI, sends="your query goes to SerpApi"),
+    ServiceSpec("wolfram_alpha", "wolfram_alpha(query)", (param("query", str),), wolfram_alpha,
+                "computed answers: maths, units, science, facts (Wolfram|Alpha LLM API)",
+                re.compile(r"\bwolfram\b|\bintegral\b|\bderivative\b|\bsolve\b|\bequation\b|\bhow (?:far|tall|heavy|old|big)\b|\bdistance (?:from|between)\b|\bpopulation of\b|\bconvert\b", _C),
+                WOLFRAM, sends="your query goes to Wolfram"),
+]

pal/chat/sessions.py

@@ -0,0 +1,108 @@
+"""Chat sessions: one per browser tab. Bounded (max count, idle TTL) and thread-safe, so a
+long-running server does not leak memory or disk."""
+from __future__ import annotations
+
+import logging
+import re
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from pal.chat.tools import ToolBox
+from pal.context_manager import Turn
+from pal.documents import DocumentIndex
+from pal.errors import UserInputError
+from pal.sdk.pipeline import AgentSDK
+
+log = logging.getLogger(__name__)
+
+_SESSION_ID = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+
+def validate_session_id(value: str) -> str:
+    if not _SESSION_ID.match(value or ""):
+        raise UserInputError("invalid session id (1-64 letters, digits, - or _)")
+    return value
+
+
+@dataclass
+class Session:
+    id: str
+    agent_id: str
+    sdk: AgentSDK
+    docs: DocumentIndex | None
+    toolbox: ToolBox
+    turns: list[Turn] = field(default_factory=list)
+    lock: threading.RLock = field(default_factory=threading.RLock)
+    created: float = field(default_factory=time.time)
+    last_used: float = field(default_factory=time.time)
+    on_close: Callable[[Session], None] | None = None
+
+    def touch(self) -> None:
+        self.last_used = time.time()
+
+    def close(self) -> None:
+        if self.on_close:
+            try:
+                self.on_close(self)
+            except Exception:
+                log.exception("session cleanup failed for %s", self.id[:8])
+
+
+class SessionStore:
+    def __init__(self, factory: Callable[[str], Session], max_sessions: int = 200, ttl_seconds: float = 4 * 3600):
+        self._factory = factory
+        self.max_sessions = max_sessions
+        self.ttl = ttl_seconds
+        self._lock = threading.Lock()
+        self._sessions: OrderedDict[str, Session] = OrderedDict()
+
+    def get_or_create(self, session_id: str) -> Session:
+        validate_session_id(session_id)
+        evicted: list[Session] = []
+        with self._lock:
+            evicted += self._expire_locked()
+            sess = self._sessions.get(session_id)
+            if sess is None:
+                sess = self._factory(session_id)
+                self._sessions[session_id] = sess
+                while len(self._sessions) > self.max_sessions:
+                    _, old = self._sessions.popitem(last=False)
+                    evicted.append(old)
+            self._sessions.move_to_end(session_id)
+            sess.touch()
+        for old in evicted:  # cleanup outside the store lock
+            with old.lock:
+                old.close()
+        return sess
+
+    def _expire_locked(self) -> list[Session]:
+        now = time.time()
+        gone = [k for k, s in self._sessions.items() if now - s.last_used > self.ttl]
+        return [self._sessions.pop(k) for k in gone]
+
+    def remove(self, session_id: str) -> bool:
+        with self._lock:
+            sess = self._sessions.pop(session_id, None)
+        if sess is None:
+            return False
+        with sess.lock:
+            sess.close()
+        return True
+
+    def get(self, session_id: str) -> Session | None:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._sessions)
+
+    def close_all(self) -> None:
+        with self._lock:
+            sessions, self._sessions = list(self._sessions.values()), OrderedDict()
+        for s in sessions:
+            with s.lock:
+                s.close()