cfabric-browser 0.1.0__py3-none-any.whl

cfabric_browser/__init__.py

@@ -0,0 +1,3 @@
+"""CACCHT Explorer, the Context-Fabric browser."""
+
+__version__ = "0.1.0"

cfabric_browser/__main__.py

@@ -0,0 +1,12 @@
+"""`python -m cfabric_browser`, and the entry point of the standalone program."""
+
+import multiprocessing
+import sys
+
+from cfabric_browser.cli import main
+
+if __name__ == "__main__":
+    # In a frozen program (PyInstaller), each search worker starts the program
+    # again; this turns that start into the worker instead of a second server.
+    multiprocessing.freeze_support()
+    sys.exit(main())

cfabric_browser/app.py

@@ -0,0 +1,178 @@
+"""The browser's web application: the JSON API plus the single-page interface."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from importlib import metadata
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from mcp.server.fastmcp.server import StreamableHTTPASGIApp
+from starlette.routing import Route
+
+from cfabric_browser import __version__
+from cfabric_browser.assistant.mcp import build_server as build_mcp
+from cfabric_browser.assistant.mcp import local
+from cfabric_browser.assistant.tools import Tools
+from cfabric_browser.corpora import CorpusService
+from cfabric_browser.dictionaries.manage import DictionaryJobs
+from cfabric_browser.downloads import DownloadJobs
+from cfabric_browser.guard import Guard
+from cfabric_browser.routes import build_router
+from cfabric_browser.translations.manage import Jobs
+from cfabric_browser.workers import SearchPool
+
+STATIC = Path(__file__).parent / "static"
+
+NOT_BUILT = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>CACCHT Explorer</title></head>
+<body style="font-family: system-ui; max-width: 40rem; margin: 4rem auto">
+<h1>CACCHT Explorer</h1>
+<p>The server is running, but the interface has not been built.</p>
+<p>Build it with <code>npm install</code> and <code>npm run build</code> in
+<code>libs/explorer/frontend</code>, or use the API at <a href="/docs">/docs</a>.</p>
+</body></html>
+"""
+
+
+def create_app(
+    service: CorpusService,
+    pool: SearchPool,
+    static_dir: Path = STATIC,
+    manage_pool: bool = True,
+    library: bool = True,
+    ui: str = "classic",
+    hidden_uis: list[str] | None = None,
+    translations: Jobs | None = None,
+    downloads: DownloadJobs | None = None,
+    ask_downloads: bool = False,
+    dictionaries: DictionaryJobs | None = None,
+    assistant: Tools | None = None,
+    hosts: list[str] | None = None,
+) -> FastAPI:
+    """Build the application.
+
+    Parameters
+    ----------
+    service: CorpusService
+        The corpora to serve.
+    pool: SearchPool
+        The search workers.
+    static_dir: Path
+        Directory with the built interface (`index.html` and `assets/`).
+    manage_pool: bool
+        Start the pool when the app starts and stop it when it stops.
+    library: bool
+        Let people open other corpora found on this computer. Switch this off
+        when the browser is reachable by others.
+    ui: str
+        The interface to start in when the user has not chosen one yet:
+        `classic` (panes), `parallel`, `reader`, `interlinear` or
+        `concordance` (see `cfabric_browser.interfaces`).
+    hidden_uis: list[str] | None
+        Interfaces to leave out of the menu until the user chooses otherwise.
+    translations: Jobs | None
+        Where translations are built and how (`cfabric_browser.translations`);
+        by default into the first place the library looks.
+    downloads: DownloadJobs | None
+        Where corpora are downloaded to (`cfabric_browser.downloads`); by
+        default the first place the library looks.
+    ask_downloads: bool
+        At the start, offer to download the corpora that can be downloaded and
+        are missing (the standalone program).
+    dictionaries: DictionaryJobs | None
+        Where dictionaries (BDB) are kept (`cfabric_browser.dictionaries`); by
+        default `~/.cfabric/dictionaries`.
+    assistant: Tools | None
+        The tools of searching in plain language and their proposals
+        (`cfabric_browser.assistant`); by default on these corpora and pool.
+    hosts: list[str] | None
+        The host names the server answers to (`cfabric_browser.guard`), such
+        as `guard.LOCAL_HOSTS` when it listens only on this computer; `None`
+        for any. Requests from other web sites are refused either way.
+    """
+
+    # searching in plain language: the tools, also as an MCP server at /mcp
+    tools = assistant if assistant is not None else Tools(service, pool)
+    mcpServer = build_mcp(local(tools))
+    mcpServer.streamable_http_app()  # makes its session manager
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        if manage_pool:
+            pool.start(wait=False)
+        try:
+            async with mcpServer.session_manager.run():
+                yield
+        finally:
+            if manage_pool:
+                pool.shutdown()
+
+    app = FastAPI(
+        title="CACCHT Explorer",
+        version=__version__,
+        lifespan=lifespan,
+    )
+    app.add_middleware(Guard, hosts=hosts)
+    app.include_router(
+        build_router(
+            service,
+            pool,
+            library=library,
+            translations=translations,
+            downloads=downloads,
+            dictionaries=dictionaries,
+            assistant=tools,
+        )
+    )
+    # before the interface's catch-all route
+    app.router.routes.insert(
+        0, Route("/mcp", endpoint=StreamableHTTPASGIApp(mcpServer.session_manager))
+    )
+
+    try:
+        coreVersion = metadata.version("context-fabric")
+    except metadata.PackageNotFoundError:
+        coreVersion = None
+
+    @app.get("/api/health")
+    def health() -> dict:
+        return {
+            "ok": True,
+            "searchReady": pool.ready,
+            "version": __version__,
+            "coreVersion": coreVersion,
+            "ui": ui,
+            "hiddenUis": list(hidden_uis or []),
+            # offer the missing corpora at the start (/api/downloads)
+            "askDownloads": ask_downloads and library,
+        }
+
+    index = static_dir / "index.html"
+    assets = static_dir / "assets"
+    if assets.is_dir():
+        app.mount("/assets", StaticFiles(directory=assets), name="assets")
+
+    @app.get("/{path:path}", include_in_schema=False)
+    def spa(path: str):
+        # the interface does its own routing: every non-API path gets the page
+        if path.startswith("api/"):
+            raise HTTPException(404, "Not found")
+        candidate = (static_dir / path).resolve()
+        inside = bool(path) and candidate.is_relative_to(static_dir.resolve())
+        if inside and candidate.is_file():
+            return FileResponse(candidate)
+        # a folder of pages (the guide, /guide/): its index.html, at an address
+        # ending in / so that the pages' relative links work
+        if inside and (candidate / "index.html").is_file():
+            if not path.endswith("/"):
+                return RedirectResponse(f"/{path}/")
+            return FileResponse(candidate / "index.html")
+        if index.is_file():
+            return FileResponse(index)
+        return HTMLResponse(NOT_BUILT)
+
+    return app

cfabric_browser/assistant/__init__.py

@@ -0,0 +1,8 @@
+"""Searching in plain language: the tools a language model gets to turn a
+request ("all cases of >LHJM/ in the BHSA") into a search template that the
+browser shows and runs.
+
+`tools.py` has the tools; the model reaches them through MCP (the user's own
+AI app, with their own subscription). The results always come from the
+browser's search, never from the model's text.
+"""

cfabric_browser/assistant/guides/bhsa.md

@@ -0,0 +1,123 @@
+# Searching the BHSA
+
+The BHSA (Biblia Hebraica Stuttgartensia Amstelodamensis, ETCBC, version 2021) is the Hebrew Bible with linguistic annotations on words, phrases, clauses and sentences. A search template describes objects, one per line; indentation means "inside". The browser runs it; you only write it.
+
+## Object types (how many), from large to small
+
+book (39) > chapter (929) > verse (23,213) > half_verse (45,179) > sentence (63,717) > clause (88,131) > phrase (253,203) > word (426,590).
+
+Also: `sentence_atom`, `clause_atom`, `phrase_atom`, `subphrase` (finer divisions), and `lex` (9,230 lexemes). A `lex` node contains all the words of that lexeme, so `lex gloss=create` with `word` indented under it finds the words of lexemes glossed "create".
+
+## The main features
+
+**Words** (`word`):
+
+- `lex`: the lexeme in ETCBC transliteration (see *Conventions*): `>LHJM/`, `HLK[`, `JHWH/`.
+- `sp`: part of speech: `subs` noun, `verb`, `prep` preposition, `conj` conjunction, `nmpr` proper noun, `art` article, `adjv` adjective, `nega` negation, `prps` personal pronoun, `advb` adverb, `prde` demonstrative pronoun, `intj` interjection, `inrg` interrogative particle, `prin` interrogative pronoun.
+- `vs`: verbal stem: `qal`, `nif` niphal, `piel`, `pual`, `hit` hitpael, `hif` hiphil, `hof` hophal, and rarer ones (`hsht`, `poel`, ...); Aramaic `peal`, `pael`, `haf`, `afel`, `peil`, `htpe`, `htpa`, ... `NA` for words that aren't verbs.
+- `vt`: verbal tense: `perf` perfect (qatal), `impf` imperfect (yiqtol), `wayq` wayyiqtol, `impv` imperative, `infc` infinitive construct, `infa` infinitive absolute, `ptca` active participle, `ptcp` passive participle.
+- `ps` person (`p1`, `p2`, `p3`), `gn` gender (`m`, `f`), `nu` number (`sg`, `pl`, `du`); `unknown` where it can't be told (common gender, for instance), `NA` where it doesn't apply.
+- `st`: state: `a` absolute, `c` construct, `e` emphatic (Aramaic).
+- Pronominal suffix: `prs` its consonants (`W`, `K`, `HM`, ...; `absent` without one), with `prs_ps`, `prs_gn`, `prs_nu`.
+- `language`: `Hebrew` or `Aramaic` (6,106 Aramaic words, in Daniel, Ezra and a few verses elsewhere).
+- `nametype` of proper nouns: `pers` person, `topo` place, `gens` people, `ppde`, `mens`, and combinations such as `pers,gens,topo`: use `nametype~topo` to include those.
+- `ls`: lexical set: `card` cardinal, `ordn` ordinal, `gntl` gentilic, `quot` quotation verb (אמר), `ques`, `nmdi` distributive noun, ...
+- Text: `g_cons` (consonants in transliteration, without vowels: `>LHJM`), `g_word_utf8` (the word in Hebrew with vowels), `g_lex_utf8`.
+- `gloss` (English) is on `lex` nodes, not on words.
+
+**Phrases** (`phrase`):
+
+- `function`: what the phrase does in its clause: `Pred` predicate, `Subj` subject, `Objc` object, `Cmpl` complement, `Adju` adjunct, `Time`, `Loca` location, `Modi` modifier, `Conj` conjunction, `Nega` negation, `Ques` question, `Rela` relative, `Voct` vocative, `Intj`, `PreC` predicate complement, `PreO` predicate with object suffix, `PreS` predicate with subject suffix, `Frnt` fronted element, `Supp` supplementary constituent, ...
+- `typ`: phrase type: `VP` verbal, `NP` nominal, `PP` prepositional, `CP` conjunctive, `PrNP` proper-noun phrase, `AdvP`, `NegP`, `InrP`, `AdjP`, `PPrP` personal pronoun, `DPrP` demonstrative pronoun, ...
+- `det`: determination: `det`, `und` (undetermined).
+
+**Clauses** (`clause`):
+
+- `typ`: clause type, by the form of its verb and what comes before it: `Way0` wayyiqtol first, `WayX` wayyiqtol after something, `WQt0` weqatal first, `xQt0` qatal after a word, `xQtX` qatal after a constituent, `XQtl` qatal after a non-subject, `ZQt0`, `ZYq0` (no conjunction), `xYq0`, `WYq0` (yiqtol), `ZIm0` imperative, `NmCl` nominal clause, `AjCl` adjectival, `InfC` infinitive construct clause, `Ptcp` participle clause, `Ellp` ellipsis, `Voct`, `Defc` defective, `CPen` casus pendens, `MSyn` macrosyntactic sign, ...
+- `rela`: relation to another clause: `Objc` object clause, `Subj` subject clause, `Attr` attributive (relative), `Adju` adjunct, `Cmpl`, `PreC`, `RgRc` regens/rectum, `Resu` resumptive, `Coor` coordinated, `Spec`, `Appo`, `Link`, ...; `NA` for main clauses.
+- `kind`: `VC` verbal clause, `NC` nominal clause, `WP` without predicate.
+- `domain`: `N` narrative, `Q` quotation (direct speech), `D` discursive, `?` unknown.
+- `txt`: text type by levels of embedding (`N`, `Q`, `NQ`, `NQQ`, ...).
+
+**Sections**: `book book=Genesis`, `chapter chapter=1`, `verse verse=3`, indented in that order.
+
+## Conventions
+
+- **Lexemes** are written in ETCBC transliteration: `>` א, `B` ב, `G` ג, `D` ד, `H` ה, `W` ו, `Z` ז, `X` ח, `V` ט, `J` י, `K` כ, `L` ל, `M` מ, `N` נ, `S` ס, `<` ע, `P` פ, `Y` צ, `Q` ק, `R` ר, `F` שׂ, `C` שׁ, `T` ת (final forms the same).
+- A verb's lexeme ends in `[` (`HLK[` to go, `BR>[` to create), a noun's or adjective's in `/` (`>LHJM/` god(s), `MLK/` king, `VWB/` good), particles have neither (`L` to, `>CR` which, `KJ` that, `W` and, `H` the article, `H=` the interrogative he).
+- `=` marks homonyms: `DBR[` speak and `DBR/` word; `>MR[` say; `H` the article but `H=` the interrogative; `QW=/`, `<RB===/`. When a lexeme seems to give too few results, check its homonyms with `describe_feature` on `lex`, or look for its gloss: `lex gloss=word`.
+- **Book names** in the `book` feature are Latin, with Roman numerals after the name: Genesis, Exodus, Leviticus, Numeri, Deuteronomium, Josua, Judices, Samuel_I, Samuel_II, Reges_I, Reges_II, Jesaia, Jeremia, Ezechiel, Hosea, Joel, Amos, Obadia, Jona, Micha, Nahum, Habakuk, Zephania, Haggai, Sacharia, Maleachi, Psalmi, Iob, Proverbia, Ruth, Canticum, Ecclesiastes, Threni, Esther, Daniel, Esra, Nehemia, Chronica_I, Chronica_II. So Psalms is `book book=Psalmi`, 1 Kings is `book book=Reges_I`.
+- Values are exact: `vt=infc`, not `vt=inf` or `vt=infinitive`. Several values with `|`: `prs_ps=p1|p2`. Not a value with `#`: `prs#absent` (with a suffix). A pattern with `~`: `nametype~topo`, `gloss~^king` (starting with "king").
+- Hebrew and Aramaic words have the same features; add `language=Aramaic` (or `Hebrew`) to keep to one.
+
+## Templates in short
+
+- One object per line; an indented line lies inside the object above it.
+- Features after the type: `word sp=verb vs=hif`.
+- Two objects at the same level in no particular order, unless related: name them and add a relation on a line of its own: `p1:phrase function=Pred`, `p2:phrase function=Subj`, then `p1 < p2` (p1 before p2). `<:` means "right before" (adjacent).
+- Quantifiers, each closed with `/-/`: `/with/` (has this inside), `/without/` (none of these inside), `/where/ … /have/` (every object of the `/where/` part also fits the `/have/` part). In `/have/`, name the object of `/where/` and refer to it: `w:word` under `/where/`, `w sp=nmpr` under `/have/`. A new line such as `word sp=nmpr` under `/have/` is another object, so it only asks that there is one. `/where/` also lets through what has no such object at all; "only proper names" is shorter as `/without/` with `word sp#nmpr`.
+- Results are tuples, one node per line of the template; the count is the number of tuples. Ask for the object the user wants counted at the top, or as the only line.
+
+## Worked examples (with their number of results in the BHSA)
+
+| Request | Template | Results |
+|---|---|---|
+| all cases of >LHJM/ | `word lex=>LHJM/` | 2,601 |
+| the verb HLK[ in all its forms | `word lex=HLK[` | 1,554 |
+| HLK[ in the qal | `word lex=HLK[ vs=qal` | 1,412 |
+| infinitives construct of HLK[ | `word lex=HLK[ vt=infc` | 144 |
+| active participles of >MR[ | `word lex=>MR[ vt=ptca` | 138 |
+| the niphal of DBR[ | `word lex=DBR[ vs=nif` | 4 |
+| hiphil imperfects | `word vs=hif vt=impf` | 2,264 |
+| perfects, second person feminine singular | `word vt=perf ps=p2 gn=f nu=sg` | 222 |
+| the name YHWH | `word lex=JHWH/` | 6,828 |
+| Aramaic words | `word language=Aramaic` | 6,106 |
+| place names | `word sp=nmpr nametype=topo` | 6,371 |
+| place names, also those that are also personal names | `word sp=nmpr nametype~topo` | 10,916 |
+| feminine plural nouns | `word sp=subs gn=f nu=pl` | 5,992 |
+| nouns in the construct state | `word sp=subs st=c` | 36,679 |
+| verbs with a suffix of the first person | `word sp=verb prs_ps=p1` | 1,649 |
+| the interrogative he | `word lex=H=` | 743 |
+| words with the consonants >LHJM, of any lexeme | `word g_cons=>LHJM` | 1,177 |
+| the words of lexemes glossed "create" | `lex gloss=create` / `  word` | 54 |
+| the words of lexemes whose gloss starts with "king" | `lex gloss~^king` / `  word` | 3,001 |
+| wayyiqtol forms in Genesis | `book book=Genesis` / `  word vt=wayq` | 2,106 |
+| imperatives in the Psalms | `book book=Psalmi` / `  word vt=impv` | 701 |
+| >LHJM/ in Genesis 1 | `book book=Genesis` / `  chapter chapter=1` / `    word lex=>LHJM/` | 32 |
+| phrases that are the subject | `phrase function=Subj` | 31,979 |
+| determined noun phrases | `phrase typ=NP det=det` | 20,476 |
+| clauses with a predicate and a subject | `clause` / `  phrase function=Pred` / `  phrase function=Subj` | 18,966 |
+| clauses with the predicate before the subject | `clause` / `  p1:phrase function=Pred` / `  p2:phrase function=Subj` / `p1 < p2` | 13,938 |
+| clauses with the subject before the predicate | `clause` / `  p1:phrase function=Subj` / `  p2:phrase function=Pred` / `p1 < p2` | 5,028 |
+| clauses whose subject is >LHJM/, with a verb as predicate | `clause` / `  phrase function=Pred` / `    word sp=verb` / `  phrase function=Subj` / `    word lex=>LHJM/` | 614 |
+| clauses where >LHJM/ is the subject of >MR[ | `clause` / `  phrase function=Pred` / `    word lex=>MR[` / `  phrase function=Subj` / `    word lex=>LHJM/` | 147 |
+| clauses with HJH[ as predicate | `clause` / `  phrase function=Pred` / `    word lex=HJH[` | 3,521 |
+| nominal clauses | `clause typ=NmCl` | 11,377 |
+| wayyiqtol clauses with nothing before the verb | `clause typ=Way0` | 9,038 |
+| qatal after a constituent (x-qatal-X) | `clause typ=xQtX` | 2,797 |
+| object clauses | `clause rela=Objc` | 1,327 |
+| relative clauses with >CR | `clause` / `  phrase function=Rela` / `    word lex=>CR` | 4,738 |
+| negated clauses | `clause` / `  phrase function=Nega` | 6,044 |
+| clauses in direct speech | `clause domain=Q` | 52,937 |
+| an infinitive construct right after the preposition L | `phrase` / `  w1:word lex=L` / `  w2:word vt=infc` / `w1 <: w2` | 4,572 |
+| a noun followed right away by an adjective | `phrase typ=NP` / `  w1:word sp=subs` / `  w2:word sp=adjv` / `w1 <: w2` | 1,579 |
+| >MR[ followed in its clause by L with a suffix | `clause` / `  w1:word lex=>MR[` / `  w2:word lex=L prs#absent` / `w1 < w2` | 347 |
+| verses with both >LHJM/ and BR>[ (21 combinations of a verse and the two words, in 12 verses) | `verse` / `  word lex=>LHJM/` / `  word lex=BR>[` | 21 |
+| verses without a verb | `verse` / `/without/` / `  word sp=verb` / `/-/` | 1,607 |
+| subjects that are only proper names | `phrase function=Subj` / `/where/` / `  w:word` / `/have/` / `  w sp=nmpr` / `/-/` | 5,893 |
+| the same, shorter | `phrase function=Subj` / `/without/` / `  word sp#nmpr` / `/-/` | 5,893 |
+| subjects with at least one proper name | `phrase function=Subj` / `/with/` / `  word sp=nmpr` / `/-/` | 10,484 |
+| verses with both >HB[ and JHWH/, each verse once | `verse` / `/with/` / `  word lex=>HB[` / `/-/` / `/with/` / `  word lex=JHWH/` / `/-/` | 60 |
+
+(`/` separates the lines of a template here; write each on its own line, with the indentation shown.)
+
+## Common mistakes
+
+- English or Hebrew values: `sp=noun`, `vt=infinitive`, `vs=hiphil` find nothing; use the codes above (`subs`, `infc`, `hif`).
+- A lexeme without its ending: `lex=HLK` finds nothing; it is `HLK[`. `try_search` names a value that a feature never has.
+- English book names: `book=Psalms` finds nothing; it is `Psalmi`.
+- `gloss` on a word: it is on `lex` nodes (`lex gloss=create`, with `word` under it).
+- `function` on a word or a clause: it is a feature of phrases.
+- The article `H` for the interrogative `H=`, `DBR[` (speak) for `DBR/` (word).
+- `/where/` with a new object under `/have/` (`/where/` / `  word` / `/have/` / `  word sp=nmpr`): that finds subjects with at least one proper name (10,484), not subjects of proper names only (5,893). Name the object and refer to it, or use `/without/`.
+- Counting: `verse` with two words under it gives a result for every pair of matching words in the verse, not one per verse. To count verses, keep the verse alone with its conditions inside a quantifier, or tell the user that the count is of combinations.

cfabric_browser/assistant/mcp.py

@@ -0,0 +1,225 @@
+"""The tools as an MCP server, for the user's own AI app (Claude Code,
+Claude Desktop, the ChatGPT desktop app, Codex, ...).
+
+They are served at `/mcp` on the browser (Streamable HTTP, stateless, with
+JSON answers), for apps that reach a local HTTP server (Claude Code, Codex). It
+accepts only 127.0.0.1/localhost as host and no web page as origin, so
+another tab in a web browser can't use it. Apps that start their own server
+over stdio (Claude Desktop, the ChatGPT desktop app) go through a small proxy that passes each message
+on to `/mcp`: `cfabric-browser mcp` (`stdio.py`), or the Desktop Extension's
+own (`packaging/mcpb/`).
+
+All tools but `propose_search` are marked read-only, so that apps which ask
+before each tool that changes something (Codex) ask only for the proposal.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from anyio import to_thread
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.types import ToolAnnotations
+
+# calls a tool by name with its arguments; returns what the tool returns
+Call = Callable[[str, dict[str, Any]], Awaitable[Any]]
+
+INSTRUCTIONS = """\
+You are helping a user search corpora (the Hebrew Bible as the BHSA, and
+others) that are open in CACCHT Explorer. The user says in their
+own words what they want to find; you write a search template for it.
+
+The results always come from the browser's search, never from your own
+knowledge: don't answer with counts or lists of passages yourself.
+
+1. list_corpora, then corpus_guide for the corpus (it explains the features
+   and conventions, with examples); describe_corpus, list_features and
+   describe_feature for more.
+2. Write a template (search_syntax_guide explains the language) and check it
+   with check_template.
+3. Run it as a trial with try_search: look at the count and the examples. If
+   there are 0 results, read the hints; if far too many, narrow it. Repeat.
+4. propose_search with the template, the user's request in their own words
+   and a short explanation of each line. The browser shows it to the user,
+   who runs it with Run. Tell the user it is there, with the trial's count.
+"""
+
+# the header in which `cfabric-browser mcp` passes on the app's name, from
+# its `initialize` (`/mcp` is stateless, so it never sees that itself)
+CLIENT_HEADER = "X-Cfabric-Client"
+
+# the names apps give themselves (`clientInfo.name`, or in their User-Agent),
+# as the user knows them; the first that occurs in it
+CLIENTS = (
+    ("chatgpt", "ChatGPT"),
+    ("codex", "Codex"),
+    ("claude", "Claude"),
+    ("antigravity", "Gemini"),
+    ("gemini", "Gemini"),
+)
+
+READS = ToolAnnotations(readOnlyHint=True, openWorldHint=False)
+# it shows something in the browser, and changes nothing else
+PROPOSES = ToolAnnotations(
+    readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=False
+)
+
+# the tools, by name
+TOOLS = (
+    "list_corpora",
+    "corpus_guide",
+    "describe_corpus",
+    "list_features",
+    "describe_feature",
+    "search_syntax_guide",
+    "check_template",
+    "try_search",
+    "propose_search",
+)
+
+
+def build_server(call: Call, name: str = "CACCHT Explorer") -> FastMCP:
+    server = FastMCP(
+        name,
+        instructions=INSTRUCTIONS,
+        stateless_http=True,
+        json_response=True,
+        streamable_http_path="/mcp",
+        transport_security=TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"],
+            # no web page may call it, not even the browser's own
+            allowed_origins=[],
+        ),
+    )
+
+    @server.tool(annotations=READS)
+    async def list_corpora() -> dict[str, Any]:
+        """The corpora open in the browser: their names (to pass to the other
+        tools), titles, ids, and section types (book, chapter, verse)."""
+        return await call("list_corpora", {})
+
+    @server.tool(annotations=READS)
+    async def corpus_guide(corpus: str) -> dict[str, Any]:
+        """A guide to searching this corpus: its object types, its main
+        features in plain words, conventions (such as how lexemes are
+        written), worked examples and common mistakes. Read it first."""
+        return await call("corpus_guide", {"corpus": corpus})
+
+    @server.tool(annotations=READS)
+    async def describe_corpus(corpus: str) -> dict[str, Any]:
+        """The corpus' object types (word, phrase, clause, verse, ...) with
+        their numbers, and its sections."""
+        return await call("describe_corpus", {"corpus": corpus})
+
+    @server.tool(annotations=READS)
+    async def list_features(
+        corpus: str, node_types: list[str] | None = None
+    ) -> dict[str, Any]:
+        """The features of the corpus, with descriptions; only those of
+        `node_types` (such as ["word"]) if given."""
+        return await call("list_features", {"corpus": corpus, "node_types": node_types})
+
+    @server.tool(annotations=READS)
+    async def describe_feature(corpus: str, features: list[str]) -> dict[str, Any]:
+        """Features in detail: their most frequent values with counts, so
+        that a template uses values the corpus has."""
+        return await call("describe_feature", {"corpus": corpus, "features": features})
+
+    @server.tool(annotations=READS)
+    async def search_syntax_guide(section: str | None = None) -> dict[str, Any]:
+        """The search template language: objects on lines, indentation for
+        what lies inside what, features, relations and quantifiers. Without
+        `section`, an overview with the sections there are."""
+        return await call("search_syntax_guide", {"section": section})
+
+    @server.tool(annotations=READS)
+    async def check_template(corpus: str, template: str) -> dict[str, Any]:
+        """Check a template without searching: its problems (syntax, unknown
+        object types or features), each with its line; `ok` when none."""
+        return await call("check_template", {"corpus": corpus, "template": template})
+
+    @server.tool(annotations=READS)
+    async def try_search(
+        corpus: str, template: str, examples: int = 5
+    ) -> dict[str, Any]:
+        """Run a template as a trial: the number of results (`atLeast` when
+        there are more than the trial counts), a few examples with their
+        passage and text, and for 0 results hints such as a value a feature
+        never has. For checking your template, not as the answer."""
+        return await call(
+            "try_search", {"corpus": corpus, "template": template, "examples": examples}
+        )
+
+    @server.tool(annotations=PROPOSES)
+    async def propose_search(
+        corpus: str,
+        template: str,
+        request: str,
+        explanation: str,
+        model: str | None = None,
+        ctx: Context | None = None,
+    ) -> dict[str, Any]:
+        """Show the search in the user's browser, where they run it with Run,
+        edit it, or dismiss it. `request`: what the user asked, in their own
+        words; `explanation`: what each line of the template does, briefly;
+        `model`: the name of the AI app or model, as the user should see it
+        (such as "Claude" or "ChatGPT").
+        A template with problems is not shown: they come back to be fixed."""
+        return await call(
+            "propose_search",
+            {
+                "corpus": corpus,
+                "template": template,
+                "request": request,
+                "explanation": explanation,
+                "model": model or client_name(ctx),
+            },
+        )
+
+    return server
+
+
+def readable(name: str) -> str | None:
+    """The name of an app as the user knows it ("codex-mcp-client" is
+    Codex), None for one we don't know."""
+    lowered = name.lower()
+    for part, known in CLIENTS:
+        if part in lowered:
+            return known
+    return None
+
+
+def client_name(ctx: Context | None) -> str | None:
+    """The name of the app that called, for a proposal without `model`: from
+    the stdio helper's header, else the User-Agent."""
+    try:
+        request = ctx.request_context.request if ctx is not None else None
+    except ValueError:  # not in a request
+        return None
+    if request is None:
+        return None
+    headers = request.headers
+    return readable(headers.get(CLIENT_HEADER) or headers.get("user-agent") or "")
+
+
+def local(tools: Any) -> Call:
+    """Calls on the browser's own tools (for `/mcp`), in a thread: a trial
+    search waits for the pool."""
+    from cfabric_browser.assistant.tools import ToolError
+
+    async def call(name: str, args: dict[str, Any]) -> Any:
+        if name not in TOOLS:
+            raise ValueError(f"No tool {name}")
+
+        def run() -> Any:
+            try:
+                return getattr(tools, name)(**args)
+            except ToolError as e:
+                return {"ok": False, "error": str(e)}
+
+        return await to_thread.run_sync(run)
+
+    return call

cfabric_browser/assistant/proposals.py

@@ -0,0 +1,99 @@
+"""Searches proposed by a language model, kept until the user runs or
+dismisses them.
+
+A proposal has the user's request in their own words, the template, the
+model's explanation, which model made it and when, and the trial's count.
+The open page follows the proposals live (`/api/proposals/events`); nothing
+runs until the user presses *Run*.
+"""
+
+from __future__ import annotations
+
+import datetime
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+NEW = "new"
+RUN = "run"
+DISMISSED = "dismissed"
+STATES = (NEW, RUN, DISMISSED)
+KEEP = 50  # proposals kept, the newest
+
+
+@dataclass
+class Proposal:
+    id: str
+    corpus: str
+    template: str
+    request: str
+    explanation: str
+    model: str | None
+    created: str
+    # the trial before proposing: its count, and whether that is a lower bound
+    count: int | None = None
+    atLeast: bool = False
+    state: str = NEW
+
+
+@dataclass
+class ProposalStore:
+    proposals: list[Proposal] = field(default_factory=list)
+    version: int = 0
+    _cond: threading.Condition = field(default_factory=threading.Condition, repr=False)
+
+    def add(
+        self,
+        corpus: str,
+        template: str,
+        request: str,
+        explanation: str,
+        model: str | None = None,
+        count: int | None = None,
+        atLeast: bool = False,
+    ) -> dict[str, Any]:
+        proposal = Proposal(
+            id=uuid.uuid4().hex[:12],
+            corpus=corpus,
+            template=template,
+            request=request,
+            explanation=explanation,
+            model=model,
+            created=datetime.datetime.now(datetime.UTC).isoformat(timespec="seconds"),
+            count=count,
+            atLeast=atLeast,
+        )
+        with self._cond:
+            self.proposals.append(proposal)
+            del self.proposals[:-KEEP]
+            self.version += 1
+            self._cond.notify_all()
+        return asdict(proposal)
+
+    def set_state(self, pid: str, state: str) -> dict[str, Any] | None:
+        if state not in STATES:
+            raise ValueError(f"Unknown state {state!r}")
+        with self._cond:
+            for p in self.proposals:
+                if p.id == pid:
+                    p.state = state
+                    self.version += 1
+                    self._cond.notify_all()
+                    return asdict(p)
+        return None
+
+    def snapshot(self) -> dict[str, Any]:
+        """All proposals, the newest first, and the version they are at."""
+        with self._cond:
+            return {
+                "version": self.version,
+                "proposals": [asdict(p) for p in reversed(self.proposals)],
+            }
+
+    def wait_change(self, version: int, timeout: float) -> int:
+        """Block until the proposals change after `version`, or the timeout."""
+        with self._cond:
+            if self.version == version:
+                self._cond.wait(timeout)
+            return self.version