Skip to content

armgit / janas

Public Imported from GitHub
0

37 tok/s from Qwen3-Next-80B (48 GB) on a 32 GB laptop, 24 without drafts vs 2.8 for llama.cpp; reading 62 vs 16 tok/s. Faster than llama.cpp on all 13 models compared in Q4_K_M. LLMs bigger than your RAM, pure C, CPU or GPU.

Release 2026-10-01: janas-wiki, the services' tools given when needed, the system message read ahead

camauri450b548e585d
diff --git a/ChangeLog.md b/ChangeLog.md
index 20c32f6..af3a1ce 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -2,6 +2,18 @@
> Curated, user-facing summary of completed work, newest first.
+## [2026-10-01] - janas-wiki, and the services together
+
+- **The services' tools are given when a question needs them.** The system message holds a catalog of Janas's services, a line each, and one tool, `janas__open_service`: the model opens a service, gets its instructions and tools as the call's answer, and calls them from then on; the next reply is held to be a call, since Qwen3.5-0.8B, told to call one, made the weather up instead. In the library, `janas_llm_chat_tools_add` (also in `llm.bi`): tools the model may call that are not written into the system message. With Qwen3.6-35B-A3B the system message went from 4,057 tokens to 616 (11 s the first time instead of 74), and opening the weather costs 1,048 tokens once in a conversation; one session asked the weather, a page of Wikipedia and the aircraft over the Tyrrhenian, opening each service when it came to it. `--all-tools` writes them all as before.
+- **Shorter tools and instructions.** The services' descriptions, parameters and instructions say the same in fewer words: flights 40% shorter, weather 33%, Wikipedia 16%.
+- **The system message is read ahead, and kept on the disk.** With the three services' tools it is about 4,000 tokens, and on Qwen3.6-35B-A3B the first reply sat on "reading" for 72-84 s. `janas-chat` now reads it as soon as it starts, while the user writes, on a thread of its own, and shows it: a line in the conversation, and the share read in the status line, in the part kept longest; a message sent earlier waits in plain sight. Once read it goes to `~/.cache/janas`, and the next chat on the model finds it there and starts at once. In the library, `janas_llm_chat_prepare` (and in `llm.bi`): checked on Qwen3-0.6B and Qwen3.5-0.8B (the same reply with it and without, the first message finding the 2,000 tokens computed, a new chat finding them on the disk, a new system message dropping them) and in `janas-chat` with the 35B, twice: the second chat found its 4,057 tokens on the disk.
+
+- **janas-wiki**, Wikipedia as an MCP service, with no key, used when the user asks for it: its search, best first, a title and a line each (`wiki_search`); a page shown to the user as it is, a short one whole, a long one as its introduction and then the section asked for, while the model gets a note of it - its address and its sections - and not its text (`wiki_page`); and the pages about what lies around a place, nearest first, with how far and which way (`wiki_nearby`; with no place, where the user is). Titles that lead elsewhere are followed and disambiguation pages listed. Otherwise the model answers from what it knows. `janas-chat` starts it by itself; [docs/services/wiki.md](docs/services/wiki.md).
+- **A tool's answer can be for the user alone.** MCP marks the parts of an answer with their audience; `libjanas_mcp` now keeps those meant for the user alone apart from the model's text (`janas_mcp_result_user`, also in `mcp.bi`), and `janas-chat` shows them as they are. A page of Wikipedia read by the model cost thousands of tokens and over a minute of a large model, and a few filled its context: Qwen3-Next-80B, asked about Franco Zeffirelli, read pages and then asked for the weather and the flights of Florence, and reached 13,429 tokens without answering. With the 35B, "show me his page" now costs a note of 174 tokens, 3 s.
+- **The services do not call each other's tools unasked.** Each one's instructions say so: no weather or flights for a person's home town unless the user asks.
+- **A place named in English finds the right town.** "Milan" gave the weather of Milan, Tennessee, and the model told it as Milan's; "Florence" and "Venice" went to Alabama and to Dayton, Ohio. Of the places the geocoding finds, the one taken is now the most people weighed by the place's rank (a capital, a region's seat): eighteen names out of eighteen tried, Italian and foreign.
+- **A web search was tried and left out.** Of eight engines, on 1 October: DuckDuckGo's HTML page answered well and blocked the fifth request a second apart, for minutes; Brave's API has had no free plan since February; Marginalia's shared key was always spent; Stract's API is gone; Mojeek and Qwant answer with a captcha; Mwmbl's index is small and old.
+
## [2026-10-01] - janas-weather, and "here" for the services
- **janas-weather**, the weather as an MCP service, from free sources with no key: the weather now (`weather_now`: Open-Meteo's model, and what the nearest airport's station measured, with when and how far; when the two disagree, the answer says so), the forecast day by day and hour by hour (`weather_forecast`), the sea at points across it or off a place, with the waves' names (`weather_sea`), and the warnings in force from MeteoAlarm, with the Civil Protection's levels in Italy (`weather_alerts`). MET Norway answers when Open-Meteo does not. `janas-chat` starts it by itself; [docs/services/weather.md](docs/services/weather.md).
diff --git a/README.md b/README.md
index 3ec987a..ad486e6 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ Designed and written by **Maurizio "camauri" Cammalleri**.
|---|---|
| **Stage** | Early development. Formats, file layouts, the public API and the command line **change without notice**, and have changed several times a week. |
| **Stability** | **Not verified.** The engine is deliberately hard on the machine: it fills the free memory with its expert cache and reads the disk at full speed with `O_DIRECT`. On a machine with less headroom than it reckons, the desktop can be pushed into swap and become slow or unresponsive. Using a GPU has, once, caused a driver reset that took the desktop with it. |
-| **Data** | It writes only in `~/.cache/janas` (what it learns about your machine) and where you tell it to put a converted model. It does not touch the model files it reads. |
+| **Data** | It writes only in `~/.cache/janas` (what it learns about your machine, and the system messages it has read, so as not to read them again) and where you tell it to put a converted model. It does not touch the model files it reads. |
| **Hardware** | Developed and run on **one** machine (below). On anything else it is untested: it may be slower, it may refuse the model, it may misbehave. |
If something goes wrong, `Ctrl-C` stops a reply and `Ctrl-D` leaves the chat; `--cache <GiB>` puts a hard limit on the memory it takes, and `JANAS_GPU=0` keeps it off the GPU entirely.
@@ -54,6 +54,7 @@ Everything the engine does is chosen from what it measures, so another machine w
- **`janas-mcp`:** the other way round, the model offered as tools to MCP clients - a question to it, the embedding of a text ([below](#janas-as-an-mcp-server)).
- **`janas-flights`:** where a flight is and what flies over a sea or a place, as MCP tools, from the ADS-B receivers of the community, and today's schedules with a free AviationStack key: the first of Janas's services ([docs/services](docs/services/README.md)).
- **`janas-weather`:** the weather now, with what the nearest station measured, the forecast, the sea and its waves, and the warnings in force (in Italy the Civil Protection's levels), from free sources with no key ([docs/services/weather.md](docs/services/weather.md)).
+- **`janas-wiki`:** Wikipedia when you ask for it: its search, a page shown to you as it is (the introduction, then the section asked for) while the model reads only a note of it, and the pages about what lies around a place ([docs/services/wiki.md](docs/services/wiki.md)).
- **`janas-server`:** the model behind an HTTP API that follows OpenAI's, so that clients written for it can use a model running on this machine: chat and completions with tools, JSON output held to a schema and log-probabilities, the Responses API with its conversations, embeddings and moderations, a chat page of its own to try it from a browser ([below](#using-it-over-http)), and code completion for VSCodium and VS Code ([docs/code-completion.md](docs/code-completion.md)).
- **`janas-bench`:** measures the machine, fills its profile and writes a report.
- **Faster replies** from drafts the model verifies, so the text is exactly the one it would have written: from the model's own multi-token prediction block where it has one, from the conversation where it does not, or from a small model of the same family given with `--draft`.
@@ -87,7 +88,7 @@ For a point of reference, llama.cpp (build `2b18470` of 18 September 2026) on th
- [ChangeLog.md](ChangeLog.md) — what changed, newest first
- [MODELS.md](MODELS.md) — what a converted model's licence is, and what may be redistributed
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to help, and the sign-off
-- [docs/services](docs/services/README.md) — Janas's services (flights, weather), in `janas-chat` and in other MCP clients
+- [docs/services](docs/services/README.md) — Janas's services (flights, weather, Wikipedia), in `janas-chat` and in other MCP clients
- [docs/code-completion.md](docs/code-completion.md) — code completion in VSCodium and VS Code, through `janas-server`
- [AUTHORS](AUTHORS) — who wrote it, and what it owes to others
- [LICENSE](LICENSE) — GNU GPL, version 3 or later
@@ -293,7 +294,11 @@ printf 'Explain mixture of experts in one paragraph.\n/quit\n' \
### Janas's services
-The chat starts by itself the services of Janas it finds beside it - `janas-flights` and `janas-weather` - and the model uses their tools when a question needs them, without being told: ask "which flights are over the Tyrrhenian Sea now?" or "what's the weather like?" (with no place, where you are: `JANAS_LOCATION`, or a guess from the internet connection). `--no-services` starts none. How they work, their keys, and how to use them in Claude Code and other clients: [docs/services](docs/services/README.md).
+The chat starts by itself the services of Janas it finds beside it - `janas-flights`, `janas-weather` and `janas-wiki` - and the model uses their tools when a question needs them, without being told: ask "which flights are over the Tyrrhenian Sea now?", "what's the weather like?" or "show me Wikipedia's page on Zeffirelli" (with no place, where you are: `JANAS_LOCATION`, or a guess from the internet connection). `--no-services` starts none. How they work, their keys, and how to use them in Claude Code and other clients: [docs/services](docs/services/README.md).
+
+**The services' tools are given when they are needed.** Written into the system message, the tools of three services made it four thousand tokens, over a minute of a large model before the first message, and every service more made it longer. The system message now holds a catalog, a line a service, and the model opens a service when a question needs it: that service's instructions and tools come back as the answer of the call, its tools can be called from then on, and the next reply is held to be a call (a small model told to call one made the answer up instead). With Qwen3.6-35B-A3B the system message went from 4,057 tokens to 616, and opening the weather costs about a thousand tokens, once in a conversation, when the first question about the weather comes. `--all-tools` writes them all into the system message as before.
+
+**The system message is read ahead.** It used to be four thousand tokens with the services' tools, and the first reply waited for all of it. `janas-chat` now reads it as soon as it starts, while you write, and says so: a line in the conversation when it begins, and "reading the tools ahead" with how far it is in the status line, where it is the last thing to be dropped on a narrow window; a message sent before the end waits for it, with "waiting for the tools" and the share, and Ctrl-C leaves the rest to the reply. Once read it is kept in `~/.cache/janas` (2 GiB at most for these files), and the next chat on the same model finds it there: "System message and tools ready". Changing the system message or the tools reads them again.
### Tools from MCP servers
@@ -353,7 +358,7 @@ while (janas_llm_chat_next(chat, piece, sizeof(piece), &len) == JANAS_LLM_OK)
cc yours.c -Iinclude -Lbin/x86_64-linux -ljanas_llm -o yours
```
-A program that keeps the conversation itself - an HTTP client does, and sends it whole every time - hands it over with `janas_llm_chat_load`: the messages with their roles, the last one the user's. Whatever the new conversation shares with the one already computed is not read again, so the same messages plus a new one cost only the new one. `janas_llm_chat_prompt` continues raw text, with no chat format around it, and `janas_llm_default_system` gives the system message Janas's own programs use. `janas_llm_chat_stats` says why a reply ended and how much of its prompt was already computed. `janas_llm_chat_keep` keeps a few conversations computed besides the current one, for a program that switches between them: the one that shares most of the next request is copied back instead of being read again.
+A program that keeps the conversation itself - an HTTP client does, and sends it whole every time - hands it over with `janas_llm_chat_load`: the messages with their roles, the last one the user's. Whatever the new conversation shares with the one already computed is not read again, so the same messages plus a new one cost only the new one. `janas_llm_chat_prompt` continues raw text, with no chat format around it, and `janas_llm_default_system` gives the system message Janas's own programs use. `janas_llm_chat_stats` says why a reply ended and how much of its prompt was already computed. `janas_llm_chat_keep` keeps a few conversations computed besides the current one, for a program that switches between them: the one that shares most of the next request is copied back instead of being read again. `janas_llm_chat_prepare` reads the system message and the tools before the first message, a block at a time, so that a program can read them while its user writes; with `janas_llm_chat_keep_disk` a system message read once on a model is found on the disk by the next chat.
### From FreeBASIC and BASIC MODERN
@@ -590,6 +595,7 @@ It stands on the work of others, and says so:
- **GNU libmicrohttpd, yyjson and Mbed TLS** are compiled into the programs named below.
- **`janas-flights`** reads the positions of aircraft from [adsb.lol](https://adsb.lol) (data under the Open Database License) and [adsb.fi](https://adsb.fi), routes from [adsbdb.com](https://www.adsbdb.com) and, with a key of the user's, schedules from [AviationStack](https://aviationstack.com); its tables of places are built from [OurAirports](https://ourairports.com) (public domain), [GeoNames](https://www.geonames.org) (CC BY 4.0) and [Natural Earth](https://www.naturalearthdata.com) (public domain).
- **`janas-weather`** reads forecasts and the sea from [Open-Meteo](https://open-meteo.com) (CC BY 4.0) and [MET Norway](https://api.met.no) (CC BY 4.0), the stations' reports from [aviationweather.gov](https://aviationweather.gov) (NOAA), warnings from [MeteoAlarm](https://meteoalarm.org) (EUMETNET) and the Italian alert levels from the [Dipartimento della Protezione Civile](https://github.com/pcm-dpc/DPC-Bollettini-Criticita-Idrogeologica-Idraulica) (CC BY 4.0). With no place named, the services ask [GeoJS](https://www.geojs.io) or [ipwho.is](https://ipwho.is) where the internet connection is.
+- **`janas-wiki`** reads [Wikipedia](https://www.wikipedia.org) through its API; the text is Wikipedia's, under CC BY-SA 4.0, and every answer gives the page's address.
- **The people who tried it on their own machines** and reported what they saw, in the issues of this repository: their reports changed the engine more than once (the threads it picks, the prompt's progress, the GPU's diagnosis).
## Licence
diff --git a/docs/services/README.md b/docs/services/README.md
index a201801..e3d1409 100644
--- a/docs/services/README.md
+++ b/docs/services/README.md
@@ -1,11 +1,12 @@
# Janas's services
-A service of Janas is a program that brings data of the world - flights, the weather - to a model, as tools of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Each one is an MCP server of its own, over its standard input and output, so that any MCP client can use it: `janas-chat`, and the assistants of others.
+A service of Janas is a program that brings data of the world - flights, the weather, an encyclopedia - to a model, as tools of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Each one is an MCP server of its own, over its standard input and output, so that any MCP client can use it: `janas-chat`, and the assistants of others.
| Service | What it answers | Key |
|---|---|---|
| [`janas-flights`](flights.md) | where a flight is and what it is doing, its times, the flights of a route, what flies over a sea or near a place | none for live data; a free one of your own for schedules |
| [`janas-weather`](weather.md) | the weather now (a model's and a station's), the forecast, the sea and its waves, the warnings in force | none |
+| [`janas-wiki`](wiki.md) | Wikipedia's search, its pages as text, the pages about what lies around a place | none |
What every service does the same way:
@@ -13,11 +14,13 @@ What every service does the same way:
- **Open data first.** Questions about an area or a list are answered from open sources only; a source with a small quota (a key of yours) is kept for questions about one thing.
- **It says when to use it.** A service tells the client's model when its tools apply: a question on the subject is enough, the tools need not be named, and the model is told not to name them in its answers.
- **Keys stay put.** A key is read from the service's file under `~/.config/janas/` or from a variable of its environment, and never printed, not even in an error.
+- **Only what was asked.** A service's tools are used for its subject when the user asks about it, and never because of another's answer: no weather or flights for the town a page names, unless the user asks for them.
+- **What is the user's goes to the user.** A page of Wikipedia is shown as it is, and the model reads only a note of it: MCP marks each part of an answer with its audience, and `janas-chat` shows the parts meant for the user alone instead of giving them to the model. A client that does not heed the audience gives the model both.
- **Here, when no place is named.** A question about "here" takes where the user is: `JANAS_LOCATION` when set (a city, `lat,lon`, or `off`), else the internet connection's position (GeoJS, ipwho.is), else the city of the computer's time zone; the answer says which, so the model can say it is a guess ([details](weather.md#when-no-place-is-named)).
## In janas-chat
-`janas-chat` starts by itself the services it finds beside it (in the same directory as the program), gives their tools to the model with what each says of when to use them, and runs their calls without asking: they read public data and change nothing. A call shows as a dimmed line. Nothing to configure, nothing to name: ask your question.
+`janas-chat` starts by itself the services it finds beside it (in the same directory as the program) and runs their calls without asking: they read public data and change nothing. Their tools are not written into the system message: it holds a catalog, a line a service, and the model opens a service when a question needs it, getting its instructions and tools then (`--all-tools` writes them all at the start instead). A call shows as a dimmed line. Nothing to configure, nothing to name: ask your question.
- `/mcp` lists the servers running, the services marked as Janas's.
- `--no-services` starts none of them; `--no-mcp` no server at all.
diff --git a/docs/services/wiki.md b/docs/services/wiki.md
new file mode 100644
index 0000000..100f81a
--- /dev/null
+++ b/docs/services/wiki.md
@@ -0,0 +1,52 @@
+# janas-wiki
+
+Wikipedia for `janas-chat` or any other MCP client (see [the services](README.md)), when the user asks for it: its search, a page shown as it is, and the pages about what lies around a place. Wikipedia's own API: no key, no account.
+
+## The tools
+
+- **`wiki_search`** - the pages that match some words, best first: their titles, each with what it is about in a line (Wikidata's description).
+- **`wiki_page`** - shows the user a page as it is: a short page whole, a long one its introduction and the names of its sections, or the section asked for, by its name or the start of it (a section longer than 10,000 characters is cut at a paragraph, and the answer names its parts). A title that leads to another page is followed and said; a disambiguation page comes as the list of the pages it leads to. The model gets a note of it, not its text: the page's address, how many words were shown, its sections.
+- **`wiki_nearby`** - the pages about what lies around a place, nearest first, with how far and which way ("Palazzo D'Alì: 170 m NW"), within up to 10 km. The place is a page's title (its point is the page's), `lat,lon`, or none: then where the user is, as for the weather ([details](weather.md#when-no-place-is-named)).
+
+Every tool takes `language`, the Wikipedia to ask: the model gives the user's (`it`, `en`, `fr`...), and the English one when the first has nothing; when it gives none, the computer's language is taken (`LANG=it_IT.UTF-8`: `it`), else English.
+
+## The page is yours, not the model's
+
+A page is thousands of tokens, which a model reads before it can say a word - over a minute of a large model on a laptop for one page - and a few pages fill its context. And a page asked for is meant to be read, not retold. So the page goes to the user as it is, and the model answers from what it knows: it is told to use Wikipedia only when the user asks for it, or asks what there is around a place, and never to ask the other services for the weather or the flights of a place a page names.
+
+The answer of `wiki_page` has two parts, each marked with its audience as MCP provides: a note for the model, and the page for the user. `janas-chat` shows the user's part as it is and gives the model only the note; a client that does not heed the audience gives the model both.
+
+## Where the data comes from
+
+| Data | Source | Key |
+|---|---|---|
+| search, pages, places | the [MediaWiki Action API](https://www.mediawiki.org/wiki/API:Main_page) of each Wikipedia (TextExtracts, GeoData) | none |
+| where the user is | [GeoJS](https://www.geojs.io), [ipwho.is](https://ipwho.is) | none |
+
+- **The text** is Wikipedia's, under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/): every answer gives the page's address, and the model is told to give it as the source.
+- **It is plain text**: the tables and the boxes beside the text (the infobox's population, dates) are not in it.
+- **Requests carry a User-Agent** naming the program and where it lives, as [Wikimedia's policy](https://meta.wikimedia.org/wiki/User-Agent_policy) asks: `janas-wiki/<version> (https://github.com/prabanta-dev/janas)`. One request at a time, and the answers are kept for an hour, so that a page read and then a section of it cost one request.
+- **Wikipedia is not news**: the model is told to say so when a question is about today.
+
+## Running it
+
+```sh
+janas-wiki
+```
+
+It speaks MCP over its standard input and output and writes what it does on its standard error. In other clients:
+
+```sh
+claude mcp add wiki -- /path/to/janas-wiki
+```
+
+```json
+{"mcpServers": {"wiki": {"command": "/path/to/janas-wiki"}}}
+```
+
+## What has been run
+
+1 October 2026:
+
+- Over the protocol, every tool, in the release and AddressSanitizer builds, the note for the model and the page for the user apart: a search for "promessi sposi" on the Italian Wikipedia; "Manzoni", which leads to "Alessandro Manzoni", its introduction and the names of its sections, then its section "Biografia", cut and with its parts named; "Mercurio", a disambiguation page; a page that does not exist; the pages around Trapani (the castle 200 m NNW, the town hall 170 m NW), around the Colosseum on the English Wikipedia, and around "here", placed in Palermo by GeoJS; a language that is not one, taken as the computer's (Italian).
+- `janas-chat` with Qwen3.6-35B-A3B, in Italian, with the page shown to the user: "Who was Franco Zeffirelli? Briefly." was answered from the model's memory with no tool, in 6.6 s - and with a mistake, the cast of another *Romeo and Juliet*; "show me his page on Wikipedia" showed the page's introduction and sections as they are, the model reading a note of 174 tokens in 3 s; "and what's the weather in Florence today?" asked for the weather, as asked. Before, with the page given to the model: "what is there to see nearby, and what's the weather?" gave the pages around where the user is and the weather there.
diff --git a/include/janas/llm.bi b/include/janas/llm.bi
index 4f4bd5a..8e400ef 100644
--- a/include/janas/llm.bi
+++ b/include/janas/llm.bi
@@ -243,6 +243,13 @@ declare function janas_llm_chat_set_params(byval c as janas_llm_chat ptr, _
declare function janas_llm_chat_system(byval c as janas_llm_chat ptr, _
byval text as const zstring ptr, _
byval length as long) as long
+'' Reads the system message and the tools now, a block at a time, before
+'' the first message: 1 while more is left, 0 when read, or an error; done
+'' and total (may be NULL) count their tokens. With _keep and _keep_disk,
+'' one read before on the same model is taken as it was.
+declare function janas_llm_chat_prepare(byval c as janas_llm_chat ptr, _
+ byval done as long ptr, _
+ byval total as long ptr) as long
declare function janas_llm_chat_send(byval c as janas_llm_chat ptr, _
byval text as const zstring ptr, _
byval length as long) as long
@@ -317,6 +324,12 @@ declare function janas_llm_chat_kept_disk(byval c as const janas_llm_chat ptr, _
declare function janas_llm_chat_tools(byval c as janas_llm_chat ptr, _
byval json as const zstring ptr, _
byval length as long) as long
+'' More tools the model may call, not written into the system message (their
+'' definitions reach the model another way): from the next reply on; each
+'' call replaces the last one's; NULL or 0: none.
+declare function janas_llm_chat_tools_add(byval c as janas_llm_chat ptr, _
+ byval json as const zstring ptr, _
+ byval length as long) as long
declare function janas_llm_chat_tool_choice(byval c as janas_llm_chat ptr, _
byval choice as long, _
byval name_ as const zstring ptr, _
diff --git a/include/janas/llm.h b/include/janas/llm.h
index 7a3197c..2d4ac7a 100644
--- a/include/janas/llm.h
+++ b/include/janas/llm.h
@@ -301,6 +301,22 @@ JANAS_LLM_API int32_t janas_llm_chat_set_params(
JANAS_LLM_API int32_t janas_llm_chat_system(janas_llm_chat *c, const char *text,
int32_t len);
+/*
+ * Reads the system message and the tools now, before the first message, a
+ * block at a time: 1 while more is left, 0 when they are read (or there is
+ * nothing to read, or the conversation has started), or an error. done and
+ * total (either may be NULL) say how many of their tokens are read. With
+ * many tools the system message is thousands of tokens, tens of seconds of
+ * a large model: a program reads it while its user writes, and the first
+ * message finds it read. With janas_llm_chat_keep and _keep_disk on, a
+ * system message read before - in this chat, or in one before it on the
+ * same model - is taken as it was, and the one read here is kept for the
+ * next. Setting the system message or the tools afterwards drops what was
+ * read; janas_llm_chat_send, _send_results and _load are as without it.
+ */
+JANAS_LLM_API int32_t janas_llm_chat_prepare(janas_llm_chat *c, int32_t *done,
+ int32_t *total);
+
/*
* Sends a user message; the reply follows through janas_llm_chat_next. A
* reply still being read is cut where it is and closed first.
@@ -452,6 +468,19 @@ JANAS_LLM_API int32_t janas_llm_chat_kept_disk(const janas_llm_chat *c,
JANAS_LLM_API int32_t janas_llm_chat_tools(janas_llm_chat *c, const char *json,
int32_t len);
+/*
+ * More tools the model may call, not written into the system message: the
+ * program gives the model their definitions some other way - in a tool's
+ * answer, as janas-chat does when the model opens one of Janas's services -
+ * so that a long list need not be read before the first message. Their
+ * calls are held to their grammar like the others'. Takes effect from the
+ * next reply, at any point of the conversation; each call replaces what
+ * the last one added (NULL or a length of 0: none). janas_llm_chat_tools
+ * drops them.
+ */
+JANAS_LLM_API int32_t janas_llm_chat_tools_add(janas_llm_chat *c,
+ const char *json, int32_t len);
+
/* Whether the model calls a tool, from the next reply on: as it judges
(AUTO, default), never (NONE), at least one (REQUIRED), or the function
named (FUNCTION, name of len bytes). parallel 0 allows one call at most
diff --git a/include/janas/mcp.bi b/include/janas/mcp.bi
index da4d69d..3ad0292 100644
--- a/include/janas/mcp.bi
+++ b/include/janas/mcp.bi
@@ -112,6 +112,12 @@ declare function janas_mcp_result(byval m as const janas_mcp ptr, _
byval cap as long, _
byval length as long ptr) as long
declare function janas_mcp_result_error(byval m as const janas_mcp ptr) as long
+'' The answer's parts for the user alone (audience "user"), to be shown as
+'' they are; janas_mcp_result leaves them out. length 0: none.
+declare function janas_mcp_result_user(byval m as const janas_mcp ptr, _
+ byval buf as zstring ptr, _
+ byval cap as long, _
+ byval length as long ptr) as long
declare sub janas_mcp_cancel(byval m as janas_mcp ptr)
end extern
diff --git a/include/janas/mcp.h b/include/janas/mcp.h
index 68891d2..a184815 100644
--- a/include/janas/mcp.h
+++ b/include/janas/mcp.h
@@ -175,6 +175,14 @@ JANAS_MCP_API int32_t janas_mcp_call(janas_mcp *m, const char *name,
JANAS_MCP_API int32_t janas_mcp_result(const janas_mcp *m, char *buf,
int32_t cap, int32_t *len);
JANAS_MCP_API int32_t janas_mcp_result_error(const janas_mcp *m);
+/*
+ * What the answer gives to the user alone - its parts annotated with an
+ * audience of "user" without "assistant": a page, a long listing, to be
+ * shown as it is rather than read by the model. janas_mcp_result leaves
+ * them out. *len 0: none.
+ */
+JANAS_MCP_API int32_t janas_mcp_result_user(const janas_mcp *m, char *buf,
+ int32_t cap, int32_t *len);
/* Stops the call in progress on m, which then returns an error; the server
is told (notifications/cancelled). */
diff --git a/src/chat/main.c b/src/chat/main.c
index ca5f591..dccfb23 100644
--- a/src/chat/main.c
+++ b/src/chat/main.c
@@ -17,12 +17,15 @@
#define _XOPEN_SOURCE 700 /* wcwidth, for the width of what is printed */
#include <errno.h>
#include <locale.h>
+#include <pthread.h>
+#include <stdatomic.h>
#include <sys/stat.h>
#include <signal.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
+#include <time.h>
#include <unistd.h>
#include "common/sysinfo.h"
@@ -84,6 +87,27 @@ static void foot_add(struct foot *p, int *np, int keep, const char *fmt, ...)
(*np)++;
}
+/*
+ * The system message and the tools, read ahead (janas_llm_chat_prepare)
+ * while the user writes the first message: with Janas's services they are
+ * some four thousand tokens, over a minute of a large model the first time
+ * on it, and the first reply used to sit on "reading" all that while. On a
+ * thread of its own, said on the terminal when it starts, and in the
+ * footer, in the part kept longest, until it ends; a message sent before
+ * then waits for it in plain sight.
+ */
+static struct {
+ pthread_t th;
+ int on; /* started, not joined */
+ atomic_int busy, stop, done, total;
+} prep;
+
+static int prep_pct(void)
+{
+ int t = atomic_load(&prep.total), d = atomic_load(&prep.done);
+ return t > 0 ? (int)(100LL * d / t) : 0;
+}
+
/* The line at the bottom: what is worth having under the eye while the
conversation scrolls above it. */
/* what main asked for, read by the footer: the address of its own, so a
@@ -98,10 +122,15 @@ static void footer(const janas_llm *llm, const janas_llm_chat *c,
char name[96] = "";
int32_t len;
janas_llm_name(llm, name, sizeof(name), &len);
+ /* while the system message is read ahead, the chat and the engine's
+ settings are the reading thread's: only the cache's filling, which
+ is made to be watched from aside, is asked */
+ int reading = atomic_load(&prep.busy);
struct janas_llm_chat_stats s = {.size = sizeof(s)};
- int have = c && janas_llm_chat_stats(c, &s) == JANAS_LLM_OK;
+ int have = c && !reading && janas_llm_chat_stats(c, &s) == JANAS_LLM_OK;
int32_t used = 0, most = 0;
- janas_llm_experts(llm, &used, &most);
+ if (!reading)
+ janas_llm_experts(llm, &used, &most);
int64_t done = 0, total = 0;
janas_llm_preload(llm, &done, &total);
@@ -109,8 +138,11 @@ static void footer(const janas_llm *llm, const janas_llm_chat *c,
int np = 0;
if (name[0])
foot_add(part, &np, 3, "%s", name);
- foot_add(part, &np, 2, "%d bit", janas_llm_expert_bits(llm));
- foot_add(part, &np, 2, "%d/%d experts", used, most);
+ if (!reading) {
+ foot_add(part, &np, 2, "%d bit", janas_llm_expert_bits(llm));
+ foot_add(part, &np, 2, "%d/%d experts", used, most);
+ } else if (!state) /* kept longest: it is what holds the reply back */
+ foot_add(part, &np, 9, "reading the tools ahead %d%%", prep_pct());
if (have && s.context_size)
foot_add(part, &np, 4, "context %u/%u", s.context_used, s.context_size);
/* only where it is on, and only where it means something: it is the one
@@ -126,7 +158,7 @@ static void footer(const janas_llm *llm, const janas_llm_chat *c,
foot_add(part, &np, 1, "cache %d%%",
(int)(100 * done / (total ? total : 1)));
if (state && *state)
- foot_add(part, &np, 5, "%s", state);
+ foot_add(part, &np, reading ? 9 : 5, "%s", state);
/* drop the least worth keeping until what is left fits, and never the
last one standing: one part cut off says more than an empty line */
@@ -180,6 +212,8 @@ static int footer_idle(void)
int64_t done = 0, total = 0;
janas_llm_preload(idle_llm, &done, &total);
int pct = total > done ? (int)(100 * done / total) : -1;
+ /* and the reading ahead's share, while it goes */
+ pct = pct * 1000 + (atomic_load(&prep.busy) ? prep_pct() : 999);
if (pct == shown)
return 0;
shown = pct;
@@ -249,6 +283,9 @@ static void usage(void)
" --no-services start none of Janas's own services (janas-flights\n"
" and the others beside janas-chat, started by\n"
" default: their tools run without asking)\n"
+ " --all-tools write all the services' tools into the system\n"
+ " message, instead of a catalog the model opens a\n"
+ " service from when a question needs it\n"
" --progress <s> a line on stderr every s seconds while a long\n"
" prompt is read, and one after each reply\n"
" --mcp-instructions\n"
@@ -504,9 +541,115 @@ static int32_t set_system(janas_llm_chat *c, const char *system)
return rc;
}
+/* What the reading ahead says, where the user sees it: in the
+ conversation, or on stderr when the output is a pipe. */
+static void prep_say(const char *colour, const char *fmt, ...)
+ __attribute__((format(printf, 2, 3)));
+static void prep_say(const char *colour, const char *fmt, ...)
+{
+ char text[512];
+ va_list ap;
+ va_start(ap, fmt);
+ vsnprintf(text, sizeof(text), fmt, ap);
+ va_end(ap);
+ if (term.tty) /* a blank line after it: the prompt is not glued to it */
+ term_printf(&term, "%s%s%s\n\n", colour, text, T_RESET(&term));
+ else
+ fprintf(stderr, "%s\n", text);
+}
+
+static double now_ms(void)
+{
+ struct timespec ts;
+ clock_gettime(CLOCK_MONOTONIC, &ts);
+ return (double)ts.tv_sec * 1e3 + (double)ts.tv_nsec / 1e6;
+}
+
+static void *prep_main(void *arg)
+{
+ janas_llm_chat *c = arg;
+ int32_t d = 0, t = 0;
+ while (!atomic_load(&prep.stop) && janas_llm_chat_prepare(c, &d, &t) == 1) {
+ atomic_store(&prep.done, d);
+ atomic_store(&prep.total, t);
+ }
+ atomic_store(&prep.busy, 0);
+ return NULL;
+}
+
+/* The reading ahead of the system message, begun: its first block here,
+ which says how long it is, the rest on the thread. */
+static void prep_start(janas_llm_chat *c)
+{
+ if (prep.on)
+ return;
+ int32_t d = 0, t = 0;
+ double t0 = now_ms();
+ int r = janas_llm_chat_prepare(c, &d, &t);
+ if (r < 0) {
+ prep_say(T_WARN(&term),
+ "the system message could not be read "
+ "ahead: %s",
+ janas_llm_last_error());
+ return;
+ }
+ if (r == 0) {
+ if (t >= 1024 && now_ms() - t0 < 2000)
+ prep_say(T_OK(&term),
+ "System message and tools ready: %d tokens, as read "
+ "in an earlier chat.",
+ (int)t);
+ return;
+ }
+ atomic_store(&prep.done, d);
+ atomic_store(&prep.total, t);
+ atomic_store(&prep.stop, 0);
+ atomic_store(&prep.busy, 1);
+ if (pthread_create(&prep.th, NULL, prep_main, c) != 0) {
+ atomic_store(&prep.busy, 0); /* the first reply reads it */
+ return;
+ }
+ prep.on = 1;
+ prep_say(T_USER(&term),
+ "Reading the system message and the tools ahead: %d tokens, "
+ "the first time on this model (later chats find them "
+ "read). Write meanwhile: the status line shows how far it "
+ "is, and the first reply starts when it is done; Ctrl-C "
+ "while it waits leaves the rest to the reply.",
+ (int)t);
+}
+
+/* The reading ahead, waited for in plain sight (the chat is the thread's
+ until then); stop: the rest is left to the first reply. */
+static void prep_wait(const janas_llm *llm, int stop)
+{
+ if (!prep.on)
+ return;
+ if (stop)
+ atomic_store(&prep.stop, 1);
+ while (atomic_load(&prep.busy)) {
+ if (interrupted) {
+ atomic_store(&prep.stop, 1);
+ interrupted = 0;
+ }
+ char st[64];
+ snprintf(st, sizeof(st), "%s the tools %d%%",
+ atomic_load(&prep.stop) ? "stopping the reading of"
+ : "waiting for",
+ prep_pct());
+ footer(llm, NULL, st);
+ struct timespec ts = {0, 200 * 1000 * 1000};
+ nanosleep(&ts, NULL);
+ }
+ pthread_join(prep.th, NULL);
+ prep.on = 0;
+}
+
static void restart(janas_llm_chat *c, const char *system)
{
janas_llm_chat_reset(c);
+ mcpc_close_services(); /* a new conversation opens them anew */
+ janas_llm_chat_tools_add(c, NULL, 0);
if (set_system(c, system) != JANAS_LLM_OK)
term_printf(&term, "%s\n", janas_llm_last_error());
}
@@ -599,6 +742,7 @@ struct chat_opts { /* where the words land: main keeps them, this names them */
int *mcp, *mcp_auto, *mcp_instructions, *services;
int *no_mtp;
const char *mtp_found; /* the MTP file found, not asked for: unsaved */
+ int *all_tools;
};
static int take_options(int n, char **w, struct chat_opts *o)
@@ -641,6 +785,10 @@ static int take_options(int n, char **w, struct chat_opts *o)
*o->services = 0;
continue;
}
+ if (strcmp(a, "--all-tools") == 0) {
+ *o->all_tools = 1;
+ continue;
+ }
if (strcmp(a, "--mcp-auto") == 0) {
*o->mcp_auto = 1;
continue;
@@ -857,6 +1005,8 @@ static void conf_write(const char *path, const struct chat_opts *o)
fprintf(f, "--no-mcp\n");
if (!*o->services)
fprintf(f, "--no-services\n");
+ if (*o->all_tools)
+ fprintf(f, "--all-tools\n");
if (*o->mcp_auto)
fprintf(f, "--mcp-auto\n");
if (*o->mcp_instructions)
@@ -971,6 +1121,8 @@ static int failed_before(const char *key)
there is nothing more to do, -1 when the exchange stops here. */
static int run_calls(janas_llm_chat *c, int autorun)
{
+ /* a reply held to a call (below) holds only that one */
+ janas_llm_chat_tool_choice(c, JANAS_LLM_TOOLS_AUTO, NULL, 0, 1);
int32_t n = janas_llm_chat_calls(c);
if (n <= 0 || !mcpc_count())
return 0;
@@ -1017,7 +1169,19 @@ static int run_calls(janas_llm_chat *c, int autorun)
}
if (go) {
footer(idle_llm, c, "running a tool");
- int rc = mcpc_call(name, args, &texts[i]);
+ char *shown = NULL;
+ unsigned gen = mcpc_opened();
+ int rc = mcpc_call(name, args, &texts[i], &shown);
+ if (mcpc_opened() != gen) { /* a service opened: its tools */
+ char *more = mcpc_opened_tools();
+ if (janas_llm_chat_tools_add(c, more, -1) != JANAS_LLM_OK)
+ term_printf(&term, "%s\n", janas_llm_last_error());
+ free(more);
+ /* and the next reply is a call: told to call one, a small
+ model (Qwen3.5-0.8B) still made up the weather instead */
+ janas_llm_chat_tool_choice(c, JANAS_LLM_TOOLS_REQUIRED, NULL, 0,
+ 1);
+ }
if (rc != 0 && key && failed.n < FAILED_MAX) {
failed.call[failed.n++] = key;
key = NULL;
@@ -1028,6 +1192,13 @@ static int run_calls(janas_llm_chat *c, int autorun)
&term, "%s%s%.*s%s%s\n", rc ? T_WARN(&term) : T_DIM(&term),
rc > 0 ? "tool error: " : "", (int)(line < 200 ? line : 200), t,
line < strlen(t) || line > 200 ? " ..." : "", T_RESET(&term));
+ if (shown && *shown) {
+ /* the user's, as the tool wrote it (a page): the model
+ has only a note of it */
+ term_gap(&term);
+ term_printf(&term, "%s\n", shown);
+ }
+ free(shown);
} else if (!texts[i]) {
texts[i] = strdup("The user did not allow this call: it was "
"not run.");
@@ -1192,11 +1363,12 @@ int main(int argc, char **argv)
int gpu = 1; /* the GPU may be given work, if there is one */
const char *mcp_config = NULL; /* NULL: the default file */
int mcp = 1, mcp_auto = 0, mcp_instructions = 0, services = 1, no_mtp = 0;
+ int all_tools = 0;
static char mtp_found[4096];
struct chat_opts o = {
&mp, &cp, &system_arg, &stats, &markdown,
&gpu, &mcp_config, &mcp, &mcp_auto, &mcp_instructions,
- &services, &no_mtp, mtp_found};
+ &services, &no_mtp, mtp_found, &all_tools};
/* the file first, the command line after it: what is typed wins */
char cpath[1024];
char *conf_text = NULL;
@@ -1254,6 +1426,7 @@ int main(int argc, char **argv)
/* the tools of the MCP servers configured and of Janas's own services
beside the program, given to the model */
if (mcp) {
+ mcpc_defer(!all_tools);
mcpc_start(mcp_config);
if (services)
mcpc_start_services();
@@ -1268,6 +1441,12 @@ int main(int argc, char **argv)
if (mcpc_count() && (mcp_extra = mcpc_instructions(mcp_instructions)) &&
set_system(c, system) != JANAS_LLM_OK)
fprintf(stderr, "janas-chat: %s\n", janas_llm_last_error());
+ /* the system message once read is kept, in memory and on the disk
+ (~/.cache/janas), so that a /reset or the next chat on this model
+ does not read it again */
+ if (janas_llm_chat_keep(c, 2, 0) != JANAS_LLM_OK ||
+ janas_llm_chat_keep_disk(c, (uint64_t)2 << 30) != JANAS_LLM_OK)
+ fprintf(stderr, "janas-chat: %s\n", janas_llm_last_error());
char desc[512];
int32_t dl;
janas_llm_describe(llm, desc, sizeof(desc), &dl);
@@ -1292,6 +1471,7 @@ int main(int argc, char **argv)
line_idle = footer_idle;
} else
fprintf(stderr, "%s\n/help for the commands\n", desc);
+ prep_start(c);
struct sigaction sa = {.sa_handler = on_sigint};
sigemptyset(&sa.sa_mask);
@@ -1306,6 +1486,11 @@ int main(int argc, char **argv)
while ((n = read_message(&msg, &cap, tty)) >= 0) {
if (n == 0)
continue;
+ /* the chat is the reading thread's until it ends: but for the
+ pages, which do not touch it, everything waits for it */
+ if (strcmp(msg, "/help") != 0 && strcmp(msg, "/about") != 0)
+ prep_wait(llm,
+ strcmp(msg, "/quit") == 0 || strcmp(msg, "/exit") == 0);
if (msg[0] == '/') {
term_gap(&term); /* what a command answers is one block */
char *arg = strchr(msg, ' ');
@@ -1418,6 +1603,7 @@ int main(int argc, char **argv)
footer(llm, c, NULL);
} else
term_printf(&term, "new conversation\n");
+ prep_start(c);
} else if (strcmp(msg, "/system") == 0) {
if (!*arg) {
term_printf(&term, "%s\n",
@@ -1430,6 +1616,7 @@ int main(int argc, char **argv)
term_printf(&term, "new conversation %s\n",
system ? "with this system message"
: "with no system message");
+ prep_start(c);
} else if (strcmp(msg, "/experts") == 0) {
int32_t used = 0, most = 0;
if (*arg &&
@@ -1490,6 +1677,7 @@ int main(int argc, char **argv)
break;
footer(llm, c, NULL);
}
+ prep_wait(llm, 1);
failed_clear();
free(msg);
free(system);
diff --git a/src/chat/mcp_chat.c b/src/chat/mcp_chat.c
index 87804fd..9b11c71 100644
--- a/src/chat/mcp_chat.c
+++ b/src/chat/mcp_chat.c
@@ -13,6 +13,8 @@
#include <sys/stat.h>
#include <unistd.h>
+#include "llm/json.h"
+
/* An answer longer than this is cut: the context is the model's memory of
the whole conversation, and a file listing can fill it at one go. */
#define RESULT_MAX 24000
@@ -21,14 +23,39 @@ struct server {
char *name; /* as configured */
char *prefix; /* name__, with what a tool name cannot hold made _ */
janas_mcp *m;
- int own; /* a service of Janas's own, found beside janas-chat */
+ int own; /* a service of Janas's own, found beside janas-chat */
+ int opened; /* its tools given to the model (mcpc_call of OPEN_TOOL) */
};
/* The services of Janas that janas-chat starts by itself when they are
beside it: janas-<name>. They read public data and change nothing, so
their tools run without asking, and what they say of their tools goes
to the model. */
-static const char *const SERVICES[] = {"flights", "weather"};
+static const struct {
+ const char *name, *about; /* for the catalog */
+} SERVICES[] = {
+ {"flights", "flights and aircraft: where a flight is and what it is "
+ "doing, today's flights of a route, what flies over a sea "
+ "or near a place"},
+ {"weather", "the weather now and the forecast, the sea and its waves, "
+ "weather warnings"},
+ {"wiki", "Wikipedia, when the user asks for it: a page shown to the "
+ "user; what there is to see around a place"},
+};
+
+/*
+ * The tools of Janas's services are not written into the system message:
+ * with three services they made it four thousand tokens, over a minute of
+ * a large model on a laptop before the first message, and every service
+ * more made it longer. The system message holds a catalog instead, a line
+ * a service, and one tool, with which the model opens a service when a
+ * question needs it: the service's instructions and tools come back as
+ * that call's answer, and its tools are added to those the model may call
+ * (janas_llm_chat_tools_add). --all-tools writes them all as before.
+ */
+#define OPEN_TOOL "janas__open_service"
+static int deferred = 1;
+static unsigned opened_gen; /* changes when a service is opened or all closed */
static struct server *servers;
static size_t n_servers;
@@ -84,7 +111,12 @@ static void join_tools(void)
if (!all)
return;
all[0] = '[';
+ int own = 0;
for (size_t i = 0; i < n_servers; i++) {
+ if (deferred && servers[i].own) {
+ own = 1;
+ continue;
+ }
int32_t len = 0;
janas_mcp_tools(servers[i].m, servers[i].prefix, -1, NULL, 0, &len);
char *t = malloc((size_t)len + 1);
@@ -112,6 +144,32 @@ static void join_tools(void)
used += (size_t)len - 2;
free(t);
}
+ if (own) { /* the one that opens them */
+ struct janas_buf o = {0};
+ janas_buf_puts(&o, "{\"type\": \"function\", \"function\": {\"name\": "
+ "\"" OPEN_TOOL "\", \"description\": \"Gives you "
+ "the instructions and the tools of one of "
+ "Janas's services, listed in the system message. "
+ "Once a service is open, call its tools.\", "
+ "\"parameters\": {\"type\": \"object\", "
+ "\"properties\": {\"service\": {\"type\": "
+ "\"string\", \"enum\": [");
+ int k = 0;
+ for (size_t i = 0; i < n_servers; i++)
+ if (servers[i].own)
+ janas_buf_printf(&o, "%s\"%s\"", k++ ? ", " : "",
+ servers[i].name);
+ janas_buf_puts(&o, "]}}, \"required\": [\"service\"]}}}");
+ char *g = o.oom ? NULL : realloc(all, used + o.n + 4);
+ if (g) {
+ all = g;
+ if (used > 1)
+ all[used++] = ',', all[used++] = ' ';
+ memcpy(all + used, o.p, o.n);
+ used += o.n;
+ }
+ janas_buf_free(&o);
+ }
if (used == 1) {
free(all);
return;
@@ -121,6 +179,132 @@ static void join_tools(void)
tools_json = all;
}
+void mcpc_defer(int on)
+{
+ deferred = on != 0;
+}
+
+/* The catalog of the services, for the system message. */
+static void catalog(FILE *f)
+{
+ fputs("Janas's services bring data of the world. Their tools are not "
+ "listed here: to use a service, call " OPEN_TOOL " with its name, "
+ "by yourself whenever a question is on its subject (the user need "
+ "not name it), then call the tools it gives you; an open service "
+ "stays open for the conversation. Never name the services or the "
+ "tools in your reply. The services:\n",
+ f);
+ for (size_t i = 0; i < n_servers; i++) {
+ if (!servers[i].own)
+ continue;
+ const char *about = "";
+ for (size_t k = 0; k < sizeof SERVICES / sizeof *SERVICES; k++)
+ if (strcmp(SERVICES[k].name, servers[i].name) == 0)
+ about = SERVICES[k].about;
+ fprintf(f, "- %s: %s\n", servers[i].name, about);
+ }
+}
+
+/* The call of OPEN_TOOL: the service's instructions and tools. */
+static int open_service(const char *args, char **text)
+{
+ char want[64] = "";
+ struct janas_json_doc *d = janas_json_parse(args, strlen(args), NULL, 0);
+ const char *v =
+ d ? janas_json_str(janas_json_get(janas_json_root(d), "service"))
+ : NULL;
+ snprintf(want, sizeof want, "%s", v ? v : "");
+ janas_json_free(d);
+ struct server *s = NULL;
+ for (size_t i = 0; i < n_servers && !s; i++)
+ if (servers[i].own && strcmp(servers[i].name, want) == 0)
+ s = &servers[i];
+ struct janas_buf o = {0};
+ if (!s) {
+ janas_buf_printf(&o, "There is no service \"%s\". The services:", want);
+ for (size_t i = 0; i < n_servers; i++)
+ if (servers[i].own)
+ janas_buf_printf(&o, " %s", servers[i].name);
+ janas_buf_puts(&o, ".");
+ *text = o.oom ? NULL : o.p;
+ return 1;
+ }
+ if (s->opened) {
+ janas_buf_printf(&o,
+ "The service %s is open already: call its tools "
+ "(their names begin with %s).",
+ s->name, s->prefix);
+ *text = o.oom ? NULL : o.p;
+ return 0;
+ }
+ int32_t len = 0;
+ janas_mcp_instructions(s->m, NULL, 0, &len);
+ char *ins = len > 0 ? malloc((size_t)len + 1) : NULL;
+ if (ins && janas_mcp_instructions(s->m, ins, len + 1, &len) == JANAS_MCP_OK)
+ janas_buf_printf(&o, "%s\n\n", ins);
+ free(ins);
+ len = 0;
+ janas_mcp_tools(s->m, s->prefix, -1, NULL, 0, &len);
+ char *t = malloc((size_t)len + 1);
+ if (t &&
+ janas_mcp_tools(s->m, s->prefix, -1, t, len + 1, &len) == JANAS_MCP_OK)
+ janas_buf_printf(&o,
+ "The service %s is open. Its tools, to call as "
+ "any other:\n%s\n\nNow call the one that "
+ "answers the user's question: do not answer "
+ "before it has, and never make up what it "
+ "would say.",
+ s->name, t);
+ free(t);
+ s->opened = 1;
+ opened_gen++;
+ *text = o.oom ? NULL : o.p;
+ if (o.oom)
+ janas_buf_free(&o);
+ return 0;
+}
+
+unsigned mcpc_opened(void)
+{
+ return opened_gen;
+}
+
+char *mcpc_opened_tools(void)
+{
+ struct janas_buf o = {0};
+ janas_buf_puts(&o, "[");
+ int any = 0;
+ for (size_t i = 0; i < n_servers; i++) {
+ if (!servers[i].opened)
+ continue;
+ int32_t len = 0;
+ janas_mcp_tools(servers[i].m, servers[i].prefix, -1, NULL, 0, &len);
+ char *t = malloc((size_t)len + 1);
+ if (t &&
+ janas_mcp_tools(servers[i].m, servers[i].prefix, -1, t, len + 1,
+ &len) == JANAS_MCP_OK &&
+ len > 2) {
+ janas_buf_puts(&o, any ? ", " : "");
+ janas_buf_put(&o, t + 1, (size_t)len - 2);
+ any = 1;
+ }
+ free(t);
+ }
+ janas_buf_puts(&o, "]");
+ if (!any || o.oom) {
+ janas_buf_free(&o);
+ return NULL;
+ }
+ return o.p;
+}
+
+void mcpc_close_services(void)
+{
+ for (size_t i = 0; i < n_servers; i++)
+ servers[i].opened = 0;
+ opened_gen++;
+}
+
static int add_server(const char *line, janas_mcp *m, int own)
{
struct server *g = realloc(servers, (n_servers + 1) * sizeof(*g));
@@ -195,21 +379,22 @@ int mcpc_start_services(void)
for (size_t i = 0; i < sizeof SERVICES / sizeof *SERVICES; i++) {
int taken = 0; /* a server of that name configured by the user */
for (size_t k = 0; k < n_servers; k++)
- taken |= strcmp(servers[k].name, SERVICES[i]) == 0;
+ taken |= strcmp(servers[k].name, SERVICES[i].name) == 0;
char path[4200];
- snprintf(path, sizeof path, "%s/janas-%s%s", self, SERVICES[i], suffix);
+ snprintf(path, sizeof path, "%s/janas-%s%s", self, SERVICES[i].name,
+ suffix);
struct stat st;
if (taken || stat(path, &st) != 0 || !(st.st_mode & S_IXUSR))
continue;
const char *argv[] = {path};
janas_mcp *m = NULL;
- if (janas_mcp_open_command(SERVICES[i], 1, argv, 0, NULL, 20, &m) !=
- JANAS_MCP_OK) {
- fprintf(stderr, "janas-%s: %s\n", SERVICES[i],
+ if (janas_mcp_open_command(SERVICES[i].name, 1, argv, 0, NULL, 20,
+ &m) != JANAS_MCP_OK) {
+ fprintf(stderr, "janas-%s: %s\n", SERVICES[i].name,
janas_mcp_last_error());
continue;
}
- if (add_server(SERVICES[i], m, 1) != 0)
+ if (add_server(SERVICES[i].name, m, 1) != 0)
break;
started++;
}
@@ -219,6 +404,8 @@ int mcpc_start_services(void)
int mcpc_own(const char *tool)
{
+ if (strcmp(tool, OPEN_TOOL) == 0)
+ return 1;
for (size_t i = 0; i < n_servers; i++)
if (strncmp(tool, servers[i].prefix, strlen(servers[i].prefix)) == 0)
return servers[i].own;
@@ -259,8 +446,14 @@ char *mcpc_instructions(int others)
if (!f)
return NULL;
int any = 0;
- /* Janas's own services first, as part of the chat itself */
- for (size_t i = 0; i < n_servers; i++) {
+ /* Janas's own services first, as part of the chat itself: their
+ catalog, or what they say when they are all written */
+ for (size_t i = 0; deferred && i < n_servers && !any; i++)
+ if (servers[i].own) {
+ catalog(f);
+ any = 1;
+ }
+ for (size_t i = 0; !deferred && i < n_servers; i++) {
if (!servers[i].own)
continue;
int32_t len = 0;
@@ -346,9 +539,12 @@ static char *say(const char *fmt, const char *a, const char *b)
return s;
}
-int mcpc_call(const char *name, const char *args, char **text)
+int mcpc_call(const char *name, const char *args, char **text, char **shown)
{
*text = NULL;
+ *shown = NULL;
+ if (strcmp(name, OPEN_TOOL) == 0)
+ return open_service(args, text);
const struct server *s = NULL;
for (size_t i = 0; i < n_servers && !s; i++)
if (strncmp(name, servers[i].prefix, strlen(servers[i].prefix)) == 0)
@@ -382,5 +578,12 @@ int mcpc_call(const char *name, const char *args, char **text)
(size_t)len - keep);
}
*text = t;
+ int32_t ul = 0;
+ janas_mcp_result_user(s->m, NULL, 0, &ul);
+ if (ul > 0 && (*shown = malloc((size_t)ul + 1)) != NULL &&
+ janas_mcp_result_user(s->m, *shown, ul + 1, &ul) != JANAS_MCP_OK) {
+ free(*shown);
+ *shown = NULL;
+ }
return janas_mcp_result_error(s->m) ? 1 : 0;
}
diff --git a/src/chat/mcp_chat.h b/src/chat/mcp_chat.h
index 5f4e963..de07f9c 100644
--- a/src/chat/mcp_chat.h
+++ b/src/chat/mcp_chat.h
@@ -26,6 +26,17 @@ int mcpc_own(const char *tool);
int mcpc_is_own(size_t i);
void mcpc_stop(void);
+/* Janas's services as a catalog in the system message, opened by the model
+ when a question needs one (the default), or, off, all their tools
+ written into it as before. Before mcpc_start_services. */
+void mcpc_defer(int on);
+/* Changes each time a service is opened, or all are closed: then the tools
+ of those open (mcpc_opened_tools, malloc'd JSON array, NULL: none) go
+ to janas_llm_chat_tools_add. mcpc_close_services: a new conversation. */
+unsigned mcpc_opened(void);
+char *mcpc_opened_tools(void);
+void mcpc_close_services(void);
+
/* The tools of all the servers as one JSON array for janas_llm_chat_tools
(NULL: none). */
const char *mcpc_tools(void);
@@ -47,10 +58,12 @@ void mcpc_set_always(const char *name);
/*
* Runs the call name (server__tool) with args, into *text (malloc'd), the
* answer for the model: the tool's text, cut when it is very long, or the
- * reason it could not run. Returns 0 when the tool answered, 1 when it said
- * it failed, -1 when it could not be run at all.
+ * reason it could not run; and into *shown (malloc'd, NULL: none) what the
+ * answer gives to the user alone, to be shown as it is (a page). Returns 0
+ * when the tool answered, 1 when it said it failed, -1 when it could not
+ * be run at all.
*/
-int mcpc_call(const char *name, const char *args, char **text);
+int mcpc_call(const char *name, const char *args, char **text, char **shown);
/* Stops the call running; safe in a signal handler. */
void mcpc_cancel(void);
diff --git a/src/common/mcp_client.c b/src/common/mcp_client.c
index cd66996..dc65bf7 100644
--- a/src/common/mcp_client.c
+++ b/src/common/mcp_client.c
@@ -469,6 +469,7 @@ void janas_mcp_close(janas_mcp *m)
free(m->server_version);
free(m->instructions);
janas_buf_free(&m->result);
+ janas_buf_free(&m->shown);
free(m);
}
@@ -745,6 +746,7 @@ int32_t janas_mcp_call(janas_mcp *m, const char *name, int32_t name_len,
return janas_mcp_fail(JANAS_MCP_EINVAL, "invalid argument");
__atomic_store_n(&m->cancel, 0, __ATOMIC_RELAXED);
m->result.n = 0;
+ m->shown.n = 0;
m->result_error = 0;
size_t nn = name_len < 0 ? strlen(name) : (size_t)name_len;
size_t an = !args ? 0 : args_len < 0 ? strlen(args) : (size_t)args_len;
@@ -825,7 +827,7 @@ int32_t janas_mcp_call(janas_mcp *m, const char *name, int32_t name_len,
else
janas_mcp_take_result(m, a.result);
janas_rpc_free(&a);
- if (rc == JANAS_MCP_OK && m->result.oom)
+ if (rc == JANAS_MCP_OK && (m->result.oom || m->shown.oom))
rc = janas_mcp_fail(JANAS_MCP_ENOMEM, "out of memory");
return rc;
}
@@ -838,6 +840,14 @@ int32_t janas_mcp_result(const janas_mcp *m, char *buf, int32_t cap,
return copy_out(m->result.p ? m->result.p : "", m->result.n, buf, cap, len);
}
+int32_t janas_mcp_result_user(const janas_mcp *m, char *buf, int32_t cap,
+ int32_t *len)
+{
+ if (!m)
+ return janas_mcp_fail(JANAS_MCP_EINVAL, "invalid argument");
+ return copy_out(m->shown.p ? m->shown.p : "", m->shown.n, buf, cap, len);
+}
+
int32_t janas_mcp_result_error(const janas_mcp *m)
{
return m ? m->result_error : 0;
diff --git a/src/common/mcp_client.h b/src/common/mcp_client.h
index 7b2df58..81d5a27 100644
--- a/src/common/mcp_client.h
+++ b/src/common/mcp_client.h
@@ -55,6 +55,7 @@ struct janas_mcp {
struct janas_mcp_tool *tools;
size_t n_tools;
struct janas_buf result; /* the last call's answer, as text */
+ struct janas_buf shown; /* its parts for the user alone (audience) */
int result_error;
volatile sig_atomic_t cancel;
int http_status; /* the last HTTP answer's */
@@ -92,7 +93,8 @@ int32_t janas_mcp_fail(int32_t code, const char *fmt, ...)
__attribute__((format(printf, 2, 3)));
/* mcp_content.c: the tools of a tools/list page added to m (0, or -1 on
- memory); the content of a tools/call result as text into m->result. */
+ memory); the content of a tools/call result as text into m->result,
+ the parts meant for the user alone into m->shown. */
int janas_mcp_take_tools(struct janas_mcp *m, const struct janas_json *list);
void janas_mcp_take_result(struct janas_mcp *m, const struct janas_json *res);
void janas_mcp_free_tools(struct janas_mcp *m);
diff --git a/src/common/mcp_content.c b/src/common/mcp_content.c
index 10c6a50..b7bee56 100644
--- a/src/common/mcp_content.c
+++ b/src/common/mcp_content.c
@@ -148,16 +148,40 @@ static void content_item(struct janas_buf *b, const struct janas_json *c)
}
}
+/* Whether an item is for the model: its annotations' audience names the
+ assistant, or names no one. An item for the user alone ("audience":
+ ["user"]) is the user's to read as it is - a page, a long listing - and
+ not the model's. */
+static int for_model(const struct janas_json *c)
+{
+ const struct janas_json *a =
+ janas_json_get(janas_json_get(c, "annotations"), "audience");
+ if (!a || a->type != JANAS_JSON_ARRAY || !a->child)
+ return 1;
+ for (const struct janas_json *w = a->child; w; w = w->next)
+ if (janas_json_is(w, "assistant"))
+ return 1;
+ return 0;
+}
+
void janas_mcp_take_result(struct janas_mcp *m, const struct janas_json *res)
{
m->result.n = 0;
m->result.oom = 0;
+ m->shown.n = 0;
+ m->shown.oom = 0;
m->result_error = janas_json_get(res, "isError") &&
janas_json_get(res, "isError")->type == JANAS_JSON_TRUE;
const struct janas_json *content = janas_json_get(res, "content");
- int any = 0;
+ int any = 0, shown = 0;
if (content && content->type == JANAS_JSON_ARRAY)
for (const struct janas_json *c = content->child; c; c = c->next) {
+ if (!for_model(c)) {
+ if (shown++)
+ janas_buf_put(&m->shown, "\n", 1);
+ content_item(&m->shown, c);
+ continue;
+ }
if (any)
janas_buf_put(&m->result, "\n", 1);
content_item(&m->result, c);
@@ -166,6 +190,12 @@ void janas_mcp_take_result(struct janas_mcp *m, const struct janas_json *res)
const struct janas_json *sc = janas_json_get(res, "structuredContent");
if (!any && sc)
janas_json_write(&m->result, sc);
+ else if (!any && shown)
+ janas_buf_puts(&m->result, "(The answer was shown to the user as "
+ "it is.)");
+ janas_buf_put(&m->shown, "", 1);
+ if (m->shown.n)
+ m->shown.n--;
janas_buf_put(&m->result, "", 1); /* NUL-terminated, not counted */
if (m->result.n)
m->result.n--;
diff --git a/src/common/mcp_server.c b/src/common/mcp_server.c
index c9768ee..5d816e1 100644
--- a/src/common/mcp_server.c
+++ b/src/common/mcp_server.c
@@ -71,6 +71,18 @@ void janas_mcps_text_result(struct janas_buf *b, const char *t, size_t n,
janas_buf_printf(b, "}], \"isError\": %s", is_error ? "true" : "false");
}
+void janas_mcps_split_result(struct janas_buf *b, const char *model,
+ size_t model_n, const char *user, size_t user_n)
+{
+ janas_buf_puts(b, "\"content\": [{\"type\": \"text\", \"text\": ");
+ janas_json_write_str(b, model, model_n);
+ janas_buf_puts(b, ", \"annotations\": {\"audience\": [\"assistant\"]}}, "
+ "{\"type\": \"text\", \"text\": ");
+ janas_json_write_str(b, user, user_n);
+ janas_buf_puts(b, ", \"annotations\": {\"audience\": [\"user\"]}}], "
+ "\"isError\": false");
+}
+
/* Two ids the same: of the same type, and written the same. */
static int same_id(const struct janas_json *a, const struct janas_json *b)
{
diff --git a/src/common/mcp_server.h b/src/common/mcp_server.h
index e337cf6..0ee121c 100644
--- a/src/common/mcp_server.h
+++ b/src/common/mcp_server.h
@@ -67,4 +67,11 @@ int janas_mcps_poll(struct janas_mcps *s);
void janas_mcps_text_result(struct janas_buf *b, const char *t, size_t n,
int is_error);
+/* A result of two text items: one for the model alone, one for the user
+ alone (their annotations' audience), for a client that shows the user's
+ as it is and gives the model only the first; a client that heeds no
+ audience gives the model both. */
+void janas_mcps_split_result(struct janas_buf *b, const char *model,
+ size_t model_n, const char *user, size_t user_n);
+
#endif
diff --git a/src/flights/main.c b/src/flights/main.c
index 7170e39..4b74622 100644
--- a/src/flights/main.c
+++ b/src/flights/main.c
@@ -25,25 +25,17 @@
#endif
static const char INSTRUCTIONS[] =
- "Use these tools by yourself whenever the user asks about flights, "
- "aircraft, airports, departures and arrivals, or what is flying "
- "somewhere: the user does not need to name them or ask for them. In "
- "your reply never name the tools, the server or the service: just give "
- "the answer, with the data's sources when the tool lists them. "
- "Flight information: today's schedules (scheduled, estimated and actual "
- "times, gates, delays) when the server has an AviationStack key, and "
- "live positions from the ADS-B receivers of the community: where an "
- "aircraft is, how high and how fast, whether it is on the ground, "
- "taxiing, on the runway or in the air, where that is in words. Tell the "
- "user what the tools return, in the user's language, without adding "
- "figures of your own: the tools already give distances, places and "
- "times in the airports' local time. Never invent a time the tools did "
- "not give. Routes marked as probably wrong must not be stated. For an "
- "area - a sea, the sky around a place - use flights_over or "
- "flights_nearby, which use open data only; never call flight_status "
- "or flights_between for each aircraft of a list: the schedules have a "
- "small monthly quota, kept for questions about one flight or one "
- "route.";
+ "Use these tools by yourself for questions on flights, aircraft, "
+ "airports, departures and arrivals, or what is flying somewhere; the "
+ "user need not name them, and you never name them. Schedules (times, "
+ "gates, delays) come from AviationStack when the server has a key, "
+ "positions from the community's ADS-B receivers. Tell what they "
+ "return in the user's language, adding no figures or times of your "
+ "own; never state a route marked as probably wrong. For an area - a "
+ "sea, around a place - use flights_over or flights_nearby, and never "
+ "call flight_status or flights_between for each aircraft of a list: "
+ "their quota is small. Never ask for flights the user did not ask "
+ "for.";
static void usage(void)
{
diff --git a/src/flights/tools.c b/src/flights/tools.c
index f9f44a2..d5d0740 100644
--- a/src/flights/tools.c
+++ b/src/flights/tools.c
@@ -44,79 +44,57 @@ static void schema_str(struct janas_buf *b, const char *name, const char *what)
janas_buf_puts(b, "}");
}
+/* The model reads all of it before it can use a tool: every word costs. */
void fl_tools_list(void *ctx, struct janas_buf *b)
{
(void)ctx;
janas_buf_puts(
b, "\"tools\": [{\"name\": \"flight_status\", \"title\": \"Status "
- "of a flight\", \"description\": \"A flight's status: its "
- "scheduled, estimated and actual departure and arrival times, "
- "gates and delay (today's flights, when the server has an "
- "AviationStack key), and where it is now from the ADS-B receivers "
- "of the community: on the ground (parked, taxiing, on the runway) "
- "or in the air (altitude, speed, climbing or descending), where "
- "it is in words (sea, region, nearest city) and an arrival time "
- "estimated from its speed. Give the flight number (FR1234, "
- "AZ1631) or the callsign (RYR1234, VLG1595).\", "
- "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
- schema_str(b, "flight",
- "Flight number (IATA airline code and number, e.g. VY1595) or "
- "callsign (e.g. VLG1595).");
+ "of a flight\", \"description\": \"A flight's times, gate and "
+ "delay today (with an AviationStack key), and where it is now "
+ "(ADS-B): on the ground or in the air, where in words, an "
+ "arrival estimate.\", \"inputSchema\": {\"type\": \"object\", "
+ "\"properties\": {");
+ schema_str(b, "flight", "Flight number (AZ1631) or callsign (VLG1595).");
janas_buf_puts(
b, "}, \"required\": [\"flight\"], \"additionalProperties\": false}}, "
"{\"name\": \"flights_between\", \"title\": \"Flights of a "
"route\", \"description\": \"Today's flights from one airport to "
- "another (and the latest ones), with their status and scheduled, "
- "estimated and actual times, and where those in the air are now. "
- "Needs an AviationStack key on the server. Give the two airports "
- "as IATA or ICAO codes or as city names in English (Turin, "
- "Trapani).\", \"inputSchema\": {\"type\": \"object\", "
+ "another, with their times and where those flying are (needs an "
+ "AviationStack key).\", \"inputSchema\": {\"type\": \"object\", "
"\"properties\": {");
- schema_str(b, "from", "Departure airport: code (TRN) or city.");
+ schema_str(b, "from", "Airport code (TRN) or city in English.");
janas_buf_puts(b, ", ");
- schema_str(b, "to", "Arrival airport: code (TPS) or city.");
+ schema_str(b, "to", "Airport code (TPS) or city in English.");
janas_buf_puts(
b, "}, \"required\": [\"from\", \"to\"], \"additionalProperties\": "
"false}}, "
"{\"name\": \"flights_over\", \"title\": \"Flights over a "
- "sea\", \"description\": \"How many and which aircraft are "
- "flying now over a sea (the Tyrrhenian, the Adriatic, the North "
- "Sea...), from the ADS-B receivers of the community, open data "
- "only: for each its callsign, aircraft, altitude, speed, heading, "
- "where it is in words and its route when one is on record. Use "
- "this for questions about a sea; do not call flight_status for "
- "each aircraft found.\", \"inputSchema\": {\"type\": "
- "\"object\", \"properties\": {");
- schema_str(b, "area",
- "A sea's name in English (Tyrrhenian Sea, Adriatic Sea, "
- "Ligurian Sea, Ionian Sea, North Sea).");
+ "sea\", \"description\": \"The aircraft flying now over a sea "
+ "(ADS-B, open data), with where each is and its route.\", "
+ "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
+ schema_str(b, "area", "A sea in English (Tyrrhenian Sea, North Sea).");
janas_buf_puts(
b, ", \"limit\": {\"type\": \"integer\", \"minimum\": 1, "
"\"maximum\": 80, \"description\": \"At most this many listed "
- "(default 40); the count is of all.\"}}, \"required\": "
- "[\"area\"], \"additionalProperties\": false}}, "
+ "(default 40).\"}}, \"required\": [\"area\"], "
+ "\"additionalProperties\": false}}, "
"{\"name\": \"flights_nearby\", \"title\": \"Flights near a "
"place\", \"description\": \"The aircraft flying now near an "
- "airport, a city or a point, from the ADS-B receivers of the "
- "community: for each its callsign, state, altitude and speed, "
- "where it is in words and its route when known. Give a place "
- "(an airport's IATA or ICAO code, or a city's name in English: "
- "Turin, Milan, Rome) or a latitude and longitude.\", "
+ "airport, a city or a point (ADS-B, open data).\", "
"\"inputSchema\": {\"type\": \"object\", \"properties\": {");
schema_str(b, "place",
- "An airport code (TRN, LIMF) or a city name in English. "
- "Leave out place and coordinates only when the user names "
- "no place: then where the user is (as set on the computer, "
- "or estimated from the internet connection).");
+ "Airport code (TRN) or city in English. Leave out place and "
+ "coordinates only when the user names no place: then where "
+ "the user is.");
janas_buf_puts(
b, ", \"latitude\": {\"type\": \"number\", \"minimum\": -90, "
"\"maximum\": 90}, \"longitude\": {\"type\": \"number\", "
"\"minimum\": -180, \"maximum\": 180}, \"radius_km\": {\"type\": "
"\"number\", \"minimum\": 1, \"maximum\": 460, \"description\": "
- "\"How far around the place (default 50).\"}, \"limit\": "
- "{\"type\": \"integer\", \"minimum\": 1, \"maximum\": 40, "
- "\"description\": \"At most this many, the nearest first "
- "(default 15).\"}}, \"additionalProperties\": false}}]");
+ "\"Default 50.\"}, \"limit\": {\"type\": \"integer\", "
+ "\"minimum\": 1, \"maximum\": 40, \"description\": \"Nearest "
+ "first (default 15).\"}}, \"additionalProperties\": false}}]");
}
/* ---- words ---- */
diff --git a/src/llm/api_chat.c b/src/llm/api_chat.c
index 762a6a9..91b05c2 100644
--- a/src/llm/api_chat.c
+++ b/src/llm/api_chat.c
@@ -154,6 +154,7 @@ int32_t janas_llm_chat_system(janas_llm_chat *c, const char *text, int32_t len)
{
if (!c || !text)
return janas_api_fail(JANAS_LLM_EINVAL, "invalid argument");
+ janas_api_unprepare(c);
if (janas_llm_session_length(c->s) > 0)
return janas_api_fail(JANAS_LLM_EINVAL,
"the conversation has started: reset it first");
@@ -177,6 +178,7 @@ int32_t janas_llm_chat_reset(janas_llm_chat *c)
c->system = NULL;
c->n_turn = 0;
c->sys_tokens = 0;
+ c->prepared = 0;
c->tools_tokens = 0;
c->dropped = 0;
c->replying = c->closed = c->ended = 0;
@@ -364,12 +366,12 @@ int janas_api_add_system(janas_llm_chat *c, const char *sys, size_t n)
/* a system turn only when there is something to say: the message,
or <|think|> at its top when reasoning is asked for */
int think = llm->thinker && c->p.thinking != 0;
- int tools = c->tools && llm->tools == JANAS_TOOLS_GEMMA;
+ int tools = c->tools_sys && llm->tools == JANAS_TOOLS_GEMMA;
if (!think && !tools && (!sys || n == 0))
return 0;
struct janas_buf b = {0};
janas_tools_system(&b, tools ? JANAS_TOOLS_GEMMA : JANAS_TOOLS_NONE,
- c->tools, sys, n);
+ c->tools_sys, sys, n);
int err = b.oom || janas_api_add_special(c, llm->im_start) ||
janas_api_add_text(c, "system\n", 7) ||
(think && (janas_api_add_special(c, llm->think_on) ||
@@ -380,7 +382,7 @@ int janas_api_add_system(janas_llm_chat *c, const char *sys, size_t n)
janas_buf_free(&b);
return err ? -1 : 0;
}
- if (!c->tools || llm->tools == JANAS_TOOLS_NONE)
+ if (!c->tools_sys || llm->tools == JANAS_TOOLS_NONE)
return janas_api_add_message(c, "system", sys ? sys : "", n);
/* how many of its tokens the tools take: the message without them is
built and taken back, for the count alone */
@@ -394,7 +396,7 @@ int janas_api_add_system(janas_llm_chat *c, const char *sys, size_t n)
size_t plain = c->n_ids - ids0;
c->n_ids = ids0;
struct janas_buf b = {0};
- janas_tools_system(&b, llm->tools, c->tools, sys, n);
+ janas_tools_system(&b, llm->tools, c->tools_sys, sys, n);
int err = b.oom || janas_api_add_special(c, llm->im_start) ||
janas_api_add_text(c, "system\n", 7) ||
janas_api_add_markup(c, b.p, b.n) ||
@@ -522,6 +524,80 @@ int janas_api_note_turn(janas_llm_chat *c, uint32_t at)
return 0;
}
+void janas_api_unprepare(janas_llm_chat *c)
+{
+ if (!c->prepared)
+ return;
+ janas_llm_session_reset(c->s);
+ c->prepared = 0;
+ c->sys_tokens = 0;
+}
+
+int32_t janas_llm_chat_prepare(janas_llm_chat *c, int32_t *done, int32_t *total)
+{
+ if (done)
+ *done = 0;
+ if (total)
+ *total = 0;
+ if (!c)
+ return janas_api_fail(JANAS_LLM_EINVAL, "no chat");
+ if (!c->prepared) {
+ if (janas_llm_session_length(c->s) > 0 || c->replying)
+ return 0; /* the conversation has started */
+ c->n_ids = c->n_text = 0;
+ int err = janas_api_begin_sequence(c);
+ if (c->system || c->tools_sys || c->llm->format == FORMAT_GEMMA)
+ err |= janas_api_add_system(c, c->system,
+ c->system ? strlen(c->system) : 0);
+ err |= janas_api_flush_text(c);
+ if (err)
+ return janas_api_fail(JANAS_LLM_ENOMEM, "out of memory");
+ if (c->n_ids < 2)
+ return 0; /* nothing worth reading ahead */
+ c->sys_tokens = (uint32_t)c->n_ids;
+ /* read before, in memory or on the disk: taken as it was */
+ janas_api_keep_pick(c);
+ const int32_t *h;
+ uint32_t hn = janas_llm_session_tokens(c->s, &h), same = 0;
+ while (same < hn && same < c->n_ids && h[same] == c->ids[same])
+ same++;
+ if (janas_llm_session_truncate(c->s, same) != 0) {
+ janas_llm_session_reset(c->s); /* a recurrent state */
+ same = 0;
+ }
+ if (janas_llm_session_append(c->s, c->ids + same,
+ (uint32_t)c->n_ids - same) != 0) {
+ janas_llm_session_reset(c->s);
+ return janas_api_fail(JANAS_LLM_EFULL,
+ "the system message does not fit in the "
+ "context (%u tokens)",
+ c->llm->n_ctx);
+ }
+ c->prepared = 1;
+ }
+ int r = 0;
+ if (c->prepared == 1) {
+ r = janas_llm_session_prefill_step(c->s);
+ if (r < 0) {
+ janas_api_unprepare(c);
+ return janas_api_fail(JANAS_LLM_EFAIL,
+ "the system message could not be read");
+ }
+ if (r == 0) {
+ c->prepared = 2;
+ janas_api_keep_prefix(c);
+ }
+ }
+ /* all but the last token: the first message's pass reads it */
+ uint32_t len = (uint32_t)janas_llm_session_length(c->s);
+ uint32_t got = janas_llm_session_computed(c->s);
+ if (done)
+ *done = (int32_t)(got + 1 >= len ? len : got);
+ if (total)
+ *total = (int32_t)len;
+ return r > 0 ? 1 : 0;
+}
+
void janas_api_prep_start(janas_llm_chat *c)
{
c->t_prep0 = janas_api_now();
@@ -701,6 +777,10 @@ static int32_t send_turn(janas_llm_chat *c, const char *text, size_t n,
if (gemma_answers) {
err |= janas_api_add_markup(c, ans.p, ans.n);
c->in_turn = 1;
+ } else if (c->prepared) {
+ /* the system message, read ahead: the session holds it (the rest
+ of it, when it was not read to the end, the reply reads) */
+ c->prepared = 0;
} else if (janas_llm_session_length(c->s) > 0) {
/* close the previous reply: its stop token is in the sequence, or
it was cut and gets one now; then the newline after it */
@@ -710,7 +790,7 @@ static int32_t send_turn(janas_llm_chat *c, const char *text, size_t n,
} else {
/* the start: <bos> where the format has one, the system message */
err |= janas_api_begin_sequence(c);
- if (c->system || c->tools || c->llm->format == FORMAT_GEMMA)
+ if (c->system || c->tools_sys || c->llm->format == FORMAT_GEMMA)
err |= janas_api_add_system(c, c->system,
c->system ? strlen(c->system) : 0);
c->sys_tokens = (uint32_t)c->n_ids;
diff --git a/src/llm/api_keep.c b/src/llm/api_keep.c
index c4680a1..acc5251 100644
--- a/src/llm/api_keep.c
+++ b/src/llm/api_keep.c
@@ -209,6 +209,20 @@ void janas_api_keep_prompt(janas_llm_chat *c)
evict(c);
}
+/*
+ * The system message read ahead (janas_llm_chat_prepare), kept like the
+ * one janas_api_keep_system reads: a start that the conversations growing
+ * from it do not drop. With a disk it goes there when the chat ends, and
+ * the next chat on the same model starts from it.
+ */
+void janas_api_keep_prefix(janas_llm_chat *c)
+{
+ if (c->keep_max <= 0)
+ return;
+ keep_current(c, 1);
+ evict(c);
+}
+
void janas_api_keep_free(janas_llm_chat *c)
{
/* with a disk, what is kept goes there, and the conversation too */
diff --git a/src/llm/api_load.c b/src/llm/api_load.c
index 2ee2068..35e9238 100644
--- a/src/llm/api_load.c
+++ b/src/llm/api_load.c
@@ -210,10 +210,10 @@ static int render(janas_llm_chat *c, uint32_t *reply_off)
if (c->msgs[i].role == JANAS_LLM_ROLE_USER)
last_q = i;
int err = janas_api_begin_sequence(c);
- if (llm->format == FORMAT_GEMMA && !c->tools &&
+ if (llm->format == FORMAT_GEMMA && !c->tools_sys &&
c->msgs[0].role != JANAS_LLM_ROLE_SYSTEM)
err |= janas_api_add_system(c, NULL, 0); /* <|think|>, if asked */
- if (c->tools && c->msgs[0].role != JANAS_LLM_ROLE_SYSTEM) {
+ if (c->tools_sys && c->msgs[0].role != JANAS_LLM_ROLE_SYSTEM) {
/* with tools there is a system message whatever the caller says */
err |= janas_api_add_system(c, NULL, 0);
err |= janas_api_flush_text(c);
@@ -296,6 +296,7 @@ static int32_t load_ids(janas_llm_chat *c, uint32_t reply_off)
{
if (janas_api_flush_text(c) != 0)
return janas_api_fail(JANAS_LLM_ENOMEM, "out of memory");
+ c->prepared = 0; /* what it read is reused below like any other start */
uint32_t reserve = c->p.max_reply > 0 && c->p.max_reply < 1024
? (uint32_t)c->p.max_reply
: 1024;
diff --git a/src/llm/api_tools.c b/src/llm/api_tools.c
index bb7c75f..543b59e 100644
--- a/src/llm/api_tools.c
+++ b/src/llm/api_tools.c
@@ -11,26 +11,54 @@
#include "llm/chat.h"
#include "llm/schema.h"
-int32_t janas_llm_chat_tools(janas_llm_chat *c, const char *json, int32_t len)
+/* An array's items, without its brackets ("" when empty). */
+static void items_of(const char *json, const char **p, size_t *n)
{
- if (!c)
- return janas_api_fail(JANAS_LLM_EINVAL, "no chat");
- size_t n = json ? janas_api_text_len(json, len) : 0;
- if (n == 0) {
- janas_toolset_free(c->tools);
- c->tools = NULL;
- return JANAS_LLM_OK;
+ const char *a = json ? strchr(json, '[') : NULL;
+ const char *b = json ? strrchr(json, ']') : NULL;
+ if (!a || !b || b <= a) {
+ *p = "";
+ *n = 0;
+ return;
}
- if (c->llm->tools == JANAS_TOOLS_NONE)
- return janas_api_fail(JANAS_LLM_EMODEL,
- "this model's chat template has no tools");
- char err[200];
- struct janas_toolset *t = janas_toolset_parse(json, n, err, sizeof(err));
- if (!t)
- return janas_api_fail(JANAS_LLM_EINVAL, "tools: %s", err);
- if (janas_toolset_count(t) == 0) {
- janas_toolset_free(t);
- t = NULL;
+ a++;
+ while (a < b && (*a == ' ' || *a == '\n' || *a == '\t' || *a == '\r'))
+ a++;
+ *p = a;
+ *n = (size_t)(b - a);
+}
+
+/* The tools the model may call: those of the system message and those
+ added, made one set again. */
+static int32_t make_tools(janas_llm_chat *c)
+{
+ const char *a, *b;
+ size_t an, bn;
+ items_of(c->tools_json, &a, &an);
+ items_of(c->more_json, &b, &bn);
+ struct janas_toolset *t = NULL;
+ if (an || bn) {
+ char *all = malloc(an + bn + 4);
+ if (!all)
+ return janas_api_fail(JANAS_LLM_ENOMEM, "out of memory");
+ size_t k = 0;
+ all[k++] = '[';
+ memcpy(all + k, a, an);
+ k += an;
+ if (an && bn)
+ all[k++] = ',';
+ memcpy(all + k, b, bn);
+ k += bn;
+ all[k++] = ']';
+ char err[200];
+ t = janas_toolset_parse(all, k, err, sizeof(err));
+ free(all);
+ if (!t)
+ return janas_api_fail(JANAS_LLM_EINVAL, "tools: %s", err);
+ if (janas_toolset_count(t) == 0) {
+ janas_toolset_free(t);
+ t = NULL;
+ }
}
janas_toolset_free(c->tools);
c->tools = t;
@@ -39,6 +67,63 @@ int32_t janas_llm_chat_tools(janas_llm_chat *c, const char *json, int32_t len)
return JANAS_LLM_OK;
}
+/* json (n bytes, 0: none) checked and kept in *keep, its set in *set. */
+static int32_t take_json(janas_llm_chat *c, const char *json, size_t n,
+ char **keep, struct janas_toolset **set)
+{
+ struct janas_toolset *t = NULL;
+ char *copy = NULL;
+ if (n) {
+ if (c->llm->tools == JANAS_TOOLS_NONE)
+ return janas_api_fail(JANAS_LLM_EMODEL,
+ "this model's chat template has no tools");
+ char err[200];
+ t = janas_toolset_parse(json, n, err, sizeof(err));
+ if (!t)
+ return janas_api_fail(JANAS_LLM_EINVAL, "tools: %s", err);
+ copy = malloc(n + 1);
+ if (!copy) {
+ janas_toolset_free(t);
+ return janas_api_fail(JANAS_LLM_ENOMEM, "out of memory");
+ }
+ memcpy(copy, json, n);
+ copy[n] = 0;
+ if (janas_toolset_count(t) == 0) {
+ janas_toolset_free(t);
+ t = NULL;
+ }
+ }
+ free(*keep);
+ *keep = copy;
+ if (set) {
+ janas_toolset_free(*set);
+ *set = t;
+ } else {
+ janas_toolset_free(t);
+ }
+ return make_tools(c);
+}
+
+int32_t janas_llm_chat_tools(janas_llm_chat *c, const char *json, int32_t len)
+{
+ if (!c)
+ return janas_api_fail(JANAS_LLM_EINVAL, "no chat");
+ janas_api_unprepare(c);
+ size_t n = json ? janas_api_text_len(json, len) : 0;
+ free(c->more_json); /* a new set: what was added goes */
+ c->more_json = NULL;
+ return take_json(c, json, n, &c->tools_json, &c->tools_sys);
+}
+
+int32_t janas_llm_chat_tools_add(janas_llm_chat *c, const char *json,
+ int32_t len)
+{
+ if (!c)
+ return janas_api_fail(JANAS_LLM_EINVAL, "no chat");
+ size_t n = json ? janas_api_text_len(json, len) : 0;
+ return take_json(c, json, n, &c->more_json, NULL);
+}
+
int32_t janas_llm_chat_tool_choice(janas_llm_chat *c, int32_t choice,
const char *name, int32_t len,
int32_t parallel)
@@ -232,6 +317,11 @@ void janas_api_tools_free(janas_llm_chat *c)
janas_api_reply_clear(c);
janas_toolset_free(c->tools);
c->tools = NULL;
+ janas_toolset_free(c->tools_sys);
+ c->tools_sys = NULL;
+ free(c->tools_json);
+ free(c->more_json);
+ c->tools_json = c->more_json = NULL;
janas_json_free(c->schema);
c->schema = NULL;
free(c->calls);
diff --git a/src/llm/chat.h b/src/llm/chat.h
index 915d632..c967e5e 100644
--- a/src/llm/chat.h
+++ b/src/llm/chat.h
@@ -89,6 +89,9 @@ struct janas_llm_chat {
uint32_t *turn;
size_t n_turn, cap_turn;
uint32_t sys_tokens;
+ /* the session holds the system message alone, read ahead
+ (janas_llm_chat_prepare): 1 while being read, 2 once read */
+ int prepared;
uint64_t dropped; /* tokens forgotten in this conversation */
/* the message being built: ids, and plain text not yet tokenized */
int32_t *ids;
@@ -150,8 +153,12 @@ struct janas_llm_chat {
} *msgs;
size_t n_msgs, cap_msgs;
- /* tools, and the form of the answer (api_tools.c) */
- struct janas_toolset *tools;
+ /* tools, and the form of the answer (api_tools.c): those the model
+ may call (the grammar's), and of them those written into the system
+ message; the rest were added later (janas_llm_chat_tools_add), as
+ JSON kept to make the whole again */
+ struct janas_toolset *tools, *tools_sys;
+ char *tools_json, *more_json;
int32_t tool_choice, tool_only, parallel;
int32_t format;
struct janas_json_doc *schema;
@@ -242,6 +249,9 @@ int janas_api_begin_reply(janas_llm_chat *c, uint32_t reply_at, uint32_t total,
uint32_t cached);
/* Building a prompt begins (its time is prepare_seconds). */
void janas_api_prep_start(janas_llm_chat *c);
+/* What janas_llm_chat_prepare read, dropped: the system message or the
+ tools change. */
+void janas_api_unprepare(janas_llm_chat *c);
/* A prompt of total tokens against max_input: 0, or JANAS_LLM_ELIMIT with
its size and parts in the stats and said. last_at is set. */
int32_t janas_api_check_input(janas_llm_chat *c, uint32_t total);
@@ -278,6 +288,8 @@ void janas_api_keep_pick(janas_llm_chat *c);
/* api_keep.c: after it is loaded, the prompt of a model with a recurrent
state is computed and kept, for a second reply to it. */
void janas_api_keep_prompt(janas_llm_chat *c);
+/* The system message read ahead, kept as a start of conversations. */
+void janas_api_keep_prefix(janas_llm_chat *c);
/* api_keep.c: on a model with a recurrent state, the system message of a
conversation about to be read from `from` is computed first and kept;
returns where the rest is to be read from. */
diff --git a/src/weather/main.c b/src/weather/main.c
index a2a4c5f..0e82c8c 100644
--- a/src/weather/main.c
+++ b/src/weather/main.c
@@ -17,20 +17,17 @@
#endif
static const char INSTRUCTIONS[] =
- "Use these tools by yourself whenever the user asks about the weather, "
- "the temperature, rain, wind, the sea and its waves, or weather "
- "warnings, now or in the next days: the user does not need to name "
- "them or ask for them. In your reply never name the tools, the server "
- "or the service: just give the answer, with the sources the tool "
- "lists. Tell the user what the tools return, in the user's language, "
- "without adding figures of your own: they already give the times in "
- "the place's local time and the wind and the sea in words. A forecast "
- "is a model's value and a station's is a measure: say which is which "
- "when both are given, and when they disagree say so. For a sea as a "
- "whole use weather_sea with its name; for warnings use weather_alerts, "
- "and say plainly when there is none. When the user names no place, "
- "give none: the tools take where the user is and say how they know "
- "it; tell the user which place that is, and that it may be off.";
+ "Use these tools by yourself for any question on the weather, rain, "
+ "wind, the sea and its waves, or weather warnings; the user need not "
+ "name them, and you never name them. Tell what they return in the "
+ "user's language, adding no figures of your own: times are local "
+ "already, wind and sea in words. A forecast is a model's value and a "
+ "station's report a measure: say which, and say when they disagree. "
+ "For a whole sea use weather_sea with its name; for warnings "
+ "weather_alerts, and say plainly when there are none. With no place "
+ "named, give none: the tool takes where the user is and says how it "
+ "knows; tell the user that place, and that it may be off. Never ask "
+ "for weather the user did not ask for.";
static void usage(void)
{
diff --git a/src/weather/place.c b/src/weather/place.c
index e97bc75..127c4e2 100644
--- a/src/weather/place.c
+++ b/src/weather/place.c
@@ -172,9 +172,26 @@ static int contains(const char *hay, const char *needle)
return hay && needle && *needle && strcasestr(hay, needle) != NULL;
}
+/* GeoNames' feature code as a weight: a capital, a region's, a
+ province's or county's, a municipality's seat, a place. */
+static double rank_weight(const char *code)
+{
+ static const struct {
+ const char *code;
+ double w;
+ } w[] = {{"PPLC", 20}, {"PPLA", 10}, {"PPLA2", 3}, {"PPLA3", 2}};
+ for (size_t i = 0; code && i < sizeof w / sizeof *w; i++)
+ if (strcmp(code, w[i].code) == 0)
+ return w[i].w;
+ return 1;
+}
+
/* The geocoding's place of that name: the nearest to (near_lat, near_lon)
when given (the name of a point's city: Turin, not Turin in Georgia),
- else the name itself first, then the most people. */
+ else the most people, weighed by the place's rank: Trapani the town,
+ not a hamlet called so; "Milan" Milano, not Milan in Tennessee;
+ "Venice" Venezia (51,000 people in its old town, a regional capital),
+ not Dayton in Ohio, which the geocoding gives first. */
static int find_named(const char *query, double near_lat, double near_lon,
struct wx_place *p, char *err, size_t err_len)
{
@@ -211,12 +228,11 @@ static int find_named(const char *query, double near_lat, double near_lon,
const struct janas_json *res =
d ? janas_json_get(janas_json_root(d), "results") : NULL;
const struct janas_json *best = NULL;
- double best_pop = -1, best_km = 1e30;
- int best_exact = 0, near = !isnan(near_lat) && !isnan(near_lon);
+ double best_score = -1, best_km = 1e30;
+ int near = !isnan(near_lat) && !isnan(near_lon);
for (const struct janas_json *r =
res && res->type == JANAS_JSON_ARRAY ? res->child : NULL;
r; r = r->next) {
- const char *rn = janas_json_str(janas_json_get(r, "name"));
const char *a1 = janas_json_str(janas_json_get(r, "admin1"));
const char *a2 = janas_json_str(janas_json_get(r, "admin2"));
const char *co = janas_json_str(janas_json_get(r, "country"));
@@ -235,15 +251,14 @@ static int find_named(const char *query, double near_lat, double near_lon,
}
continue;
}
- int exact = same_name(rn, name);
double pop = janas_json_num(janas_json_get(r, "population"), 0);
- /* the name itself before a longer one holding it, then the most
- people: Trapani the town, not a hamlet called so */
- if (!best || exact > best_exact ||
- (exact == best_exact && pop > best_pop)) {
+ /* + 1: places of no known population still count */
+ double score =
+ (pop + 1) *
+ rank_weight(janas_json_str(janas_json_get(r, "feature_code")));
+ if (!best || score > best_score) {
best = r;
- best_pop = pop;
- best_exact = exact;
+ best_score = score;
}
}
int ok = 0;
diff --git a/src/weather/tools.c b/src/weather/tools.c
index 7c29703..302f6b0 100644
--- a/src/weather/tools.c
+++ b/src/weather/tools.c
@@ -25,15 +25,15 @@ static void schema_str(struct janas_buf *b, const char *name, const char *what)
janas_buf_puts(b, "}");
}
+/* The model reads all of it before it can use a tool: every word costs
+ (with Qwen3.6-35B-A3B on a laptop, about a second for fifty tokens). */
static void place_props(struct janas_buf *b)
{
schema_str(b, "place",
- "A place's name, in Italian or English (Trapani, Firenze, "
- "Florence, Milano); \"name, region\" or \"name, country\" "
- "when several places share it; or an airport's code. "
- "Leave out place and coordinates only when the user names "
- "no place: then where the user is (as set on the computer, "
- "or estimated from the internet connection).");
+ "A place in Italian or English (Firenze, Florence), "
+ "\"name, region\" when several share it, or an airport "
+ "code. Leave out place and coordinates only when the user "
+ "names no place: then where the user is.");
janas_buf_puts(b,
", \"latitude\": {\"type\": \"number\", \"minimum\": -90, "
"\"maximum\": 90}, \"longitude\": {\"type\": \"number\", "
@@ -45,60 +45,45 @@ void wx_tools_list(void *ctx, struct janas_buf *b)
(void)ctx;
janas_buf_puts(
b, "\"tools\": [{\"name\": \"weather_now\", \"title\": \"The "
- "weather now\", \"description\": \"The weather now at a place: "
- "sky, temperature and how it feels, humidity, wind and gusts, "
- "rain, pressure, today's lowest and highest and sunrise and "
- "sunset, from a forecast model; and what the nearest weather "
- "station (an airport's) measured, with when and how far away. "
- "Give a place's name, or a latitude and longitude.\", "
- "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
+ "weather now\", \"description\": \"The weather now at a place, "
+ "from a forecast model, and what the nearest airport station "
+ "measured.\", \"inputSchema\": {\"type\": \"object\", "
+ "\"properties\": {");
place_props(b);
janas_buf_puts(
b, "}, \"additionalProperties\": false}}, "
"{\"name\": \"weather_forecast\", \"title\": \"Weather "
- "forecast\", \"description\": \"The forecast for a place, day "
- "by day (sky, lowest and highest temperature, rain and its "
- "chance, wind and gusts, sunrise and sunset) and the next hours "
- "(every three hours, or every hour when asked).\", "
- "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
+ "forecast\", \"description\": \"The forecast by the day, and "
+ "for the next hours.\", \"inputSchema\": {\"type\": \"object\", "
+ "\"properties\": {");
place_props(b);
janas_buf_puts(
b, ", \"days\": {\"type\": \"integer\", \"minimum\": 1, "
- "\"maximum\": 16, \"description\": \"How many days, today "
- "included (default 3).\"}, \"hourly\": {\"type\": \"boolean\", "
- "\"description\": \"Every hour of the next two days, instead "
- "of every three hours of the next one.\"}}, "
- "\"additionalProperties\": false}}, "
+ "\"maximum\": 16, \"description\": \"Days, today included "
+ "(default 3).\"}, \"hourly\": {\"type\": \"boolean\", "
+ "\"description\": \"Every hour of two days, not every three of "
+ "one.\"}}, \"additionalProperties\": false}}, "
"{\"name\": \"weather_sea\", \"title\": \"The sea\", "
- "\"description\": \"The state of the sea, now and in the next "
- "days: wave height (with its name: calm, slight, moderate, "
- "rough...), direction and period, wind waves and swell, the "
- "water's temperature and the wind. For a whole sea by its name "
- "(Tyrrhenian Sea, Tirreno, Adriatico, mar Ligure), at several "
- "points across it, or for the sea off a coastal place.\", "
- "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
- schema_str(b, "area",
- "A sea's name, in English or Italian (Tyrrhenian Sea, "
- "Tirreno, Adriatic, mar Ligure, Ionio).");
+ "\"description\": \"Waves, swell, the water's temperature and "
+ "the wind, now and in the next days: across a sea named, or "
+ "off a coastal place.\", \"inputSchema\": {\"type\": "
+ "\"object\", \"properties\": {");
+ schema_str(b, "area", "A sea (Tyrrhenian Sea, Tirreno, Adriatico).");
janas_buf_puts(b, ", ");
place_props(b);
janas_buf_puts(
b, ", \"days\": {\"type\": \"integer\", \"minimum\": 1, "
- "\"maximum\": 8, \"description\": \"How many days, today "
- "included (default 2).\"}}, \"additionalProperties\": false}}, "
+ "\"maximum\": 8, \"description\": \"Days, today included "
+ "(default 2).\"}}, \"additionalProperties\": false}}, "
"{\"name\": \"weather_alerts\", \"title\": \"Weather "
"warnings\", \"description\": \"The weather warnings in force "
- "for a place: those of the national weather services gathered "
- "by MeteoAlarm (wind, thunderstorms, heat, snow, by level: "
- "yellow, orange, red), the place's region first; and in Italy "
- "the Civil Protection's official alert levels for its zone, for "
- "floods, landslides and thunderstorms, today and tomorrow.\", "
- "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
+ "for a place (MeteoAlarm), and in Italy the Civil Protection's "
+ "alert levels for today and tomorrow.\", \"inputSchema\": "
+ "{\"type\": \"object\", \"properties\": {");
place_props(b);
janas_buf_puts(b, ", ");
schema_str(b, "language",
- "The language of the warnings' texts when given in it: it, "
- "en, fr, de, es (default en).");
+ "The warnings' language: it, en, fr, de, es (default en).");
janas_buf_puts(b, "}, \"additionalProperties\": false}}]");
}
diff --git a/src/wiki/fetch.c b/src/wiki/fetch.c
new file mode 100644
index 0000000..246d798
--- /dev/null
+++ b/src/wiki/fetch.c
@@ -0,0 +1,77 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * fetch.c - janas-wiki asks Wikipedia (see wiki.h): a GET over HTTPS, the
+ * answers kept a while. A conversation reads a page, then a section of it,
+ * then comes back to it: one request serves them all.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#include "common/https_get.h"
+#include "wiki.h"
+
+#ifndef JANAS_VERSION
+#define JANAS_VERSION "unknown"
+#endif
+
+#define N_KEPT 32
+
+static struct {
+ char *url;
+ time_t at;
+ int keep_s;
+ struct janas_buf body;
+} kept[N_KEPT];
+
+int wiki_fetch(const char *url, int keep_s, struct janas_buf *out, char *err,
+ size_t err_len)
+{
+ time_t now = time(NULL);
+ int slot = 0;
+ for (int i = 0; i < N_KEPT; i++) {
+ if (kept[i].url && strcmp(kept[i].url, url) == 0 &&
+ now - kept[i].at < kept[i].keep_s) {
+ out->n = 0;
+ janas_buf_put(out, kept[i].body.p, kept[i].body.n);
+ janas_buf_put(out, "", 1);
+ out->n--;
+ return out->oom ? -1 : 200;
+ }
+ if (kept[i].at < kept[slot].at)
+ slot = i;
+ }
+ /* Wikimedia's policy: a User-Agent naming the program and a way to
+ reach its authors; requests without one may be refused */
+ static const char *const agent[] = {
+ "User-Agent: janas-wiki/" JANAS_VERSION
+ " (https://github.com/prabanta-dev/janas)"};
+ int status = janas_https_get(url, agent, 1, out, err, err_len);
+ if (status == 200 && keep_s > 0 && !out->oom) {
+ free(kept[slot].url);
+ janas_buf_free(&kept[slot].body);
+ kept[slot].url = strdup(url);
+ kept[slot].at = now;
+ kept[slot].keep_s = keep_s;
+ kept[slot].body = (struct janas_buf){0};
+ janas_buf_put(&kept[slot].body, out->p, out->n);
+ if (!kept[slot].url || kept[slot].body.oom) {
+ free(kept[slot].url);
+ janas_buf_free(&kept[slot].body);
+ kept[slot].url = NULL;
+ kept[slot].at = 0;
+ }
+ }
+ return status;
+}
+
+void wiki_fetch_free(void)
+{
+ for (int i = 0; i < N_KEPT; i++) {
+ free(kept[i].url);
+ janas_buf_free(&kept[i].body);
+ }
+ memset(kept, 0, sizeof kept);
+}
diff --git a/src/wiki/main.c b/src/wiki/main.c
new file mode 100644
index 0000000..5be5032
--- /dev/null
+++ b/src/wiki/main.c
@@ -0,0 +1,73 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * main.c - janas-wiki: Wikipedia as an MCP server over stdio, for
+ * janas-chat (which starts it by itself) and any other MCP client: its
+ * search, its pages as text, and the pages about what lies around a
+ * place. Wikipedia's own API, free and without a key.
+ */
+#include <stdio.h>
+#include <string.h>
+
+#include "common/mcp_server.h"
+#include "wiki.h"
+
+#ifndef JANAS_VERSION
+#define JANAS_VERSION "unknown"
+#endif
+
+static const char INSTRUCTIONS[] =
+ "Answer from what you know. Use these tools only when the user asks "
+ "for Wikipedia - to look something up, to see a page or a part of it "
+ "- or what there is to see around a place. A page is shown to the "
+ "user as it is: you get a note, not its text; do not repeat or "
+ "summarize it unless asked, and tell the user in a line that it is "
+ "above, with its address. Search first unless you know the exact "
+ "title; for a part of a long page, ask for its section by the name "
+ "the note lists. Use the Wikipedia of the user's language, else the "
+ "English one. Never name the tools. With no place named for what is "
+ "around, give none: the tool takes where the user is; tell the user "
+ "which place, and that it may be off. Never ask the other services "
+ "for anything because of a page.";
+
+static void usage(void)
+{
+ fprintf(stderr,
+ "usage: janas-wiki\n"
+ "An MCP server over stdio: a client starts it and calls its\n"
+ "tools - wiki_search (the pages that match some words),\n"
+ "wiki_page (a page as text: whole, or its introduction and\n"
+ "then a section) and wiki_nearby (the pages about what lies\n"
+ "around a place, nearest first).\n"
+ "Data: Wikipedia's API, free and without a key; the text is\n"
+ "Wikipedia's, under CC BY-SA 4.0.\n"
+ "janas-chat starts it by itself when it is beside it.\n"
+ "Configured in a client as, for instance:\n"
+ " {\"mcpServers\": {\"wiki\": {\"command\": "
+ "\"janas-wiki\"}}}\n");
+}
+
+int main(int argc, char **argv)
+{
+ for (int i = 1; i < argc; i++) {
+ usage();
+ return strcmp(argv[i], "-h") == 0 || strcmp(argv[i], "--help") == 0 ? 0
+ : 2;
+ }
+ struct janas_mcps srv = {.name = "janas-wiki",
+ .version = JANAS_VERSION,
+ .instructions = INSTRUCTIONS,
+ .tools_list = wiki_tools_list,
+ .tools_call = wiki_tools_call};
+ if (janas_mcps_open(&srv) != 0) {
+ fprintf(stderr, "janas-wiki: cannot set its output aside\n");
+ return 1;
+ }
+ fprintf(stderr,
+ "janas-wiki %s: ready, 3 tools (wiki_search, wiki_page, "
+ "wiki_nearby)\n",
+ JANAS_VERSION);
+ janas_mcps_run(&srv);
+ wiki_fetch_free();
+ return 0;
+}
diff --git a/src/wiki/read.c b/src/wiki/read.c
new file mode 100644
index 0000000..0ffb215
--- /dev/null
+++ b/src/wiki/read.c
@@ -0,0 +1,345 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * read.c - Wikipedia's answers read (see wiki.h): the pages of a search or
+ * of the places around a point, a page with its plain text, and the text
+ * cut by its headings. The API's plain text (TextExtracts, explaintext)
+ * marks a heading as a line "== Name ==", more signs a level deeper; the
+ * tables and the boxes are left out of it.
+ */
+#define _GNU_SOURCE /* strcasestr */
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+
+#include "wiki.h"
+
+static void copy(char *to, size_t cap, const char *s)
+{
+ snprintf(to, cap, "%s", s ? s : "");
+}
+
+/* The API's error, when it gave one ({"error": {"code", "info"}}). */
+static int api_error(const struct janas_json *root, char *err, size_t err_len)
+{
+ const struct janas_json *e = janas_json_get(root, "error");
+ if (!e)
+ return 0;
+ const char *info = janas_json_str(janas_json_get(e, "info"));
+ const char *code = janas_json_str(janas_json_get(e, "code"));
+ snprintf(err, err_len, "Wikipedia said: %s",
+ info ? info
+ : code ? code
+ : "an error");
+ return 1;
+}
+
+static void point_of(const struct janas_json *page, double *lat, double *lon)
+{
+ const struct janas_json *co = janas_json_get(page, "coordinates");
+ const struct janas_json *c0 =
+ co && co->type == JANAS_JSON_ARRAY ? co->child : NULL;
+ *lat = janas_json_num(janas_json_get(c0, "lat"), NAN);
+ *lon = janas_json_num(janas_json_get(c0, "lon"), NAN);
+}
+
+int wiki_read_hits(const char *text, size_t n, struct wiki_hit *hits, int max,
+ char *err, size_t err_len)
+{
+ char why[128];
+ struct janas_json_doc *d = janas_json_parse(text, n, why, sizeof why);
+ if (!d) {
+ snprintf(err, err_len, "Wikipedia: an answer it could not read (%s)",
+ why);
+ return -1;
+ }
+ const struct janas_json *root = janas_json_root(d);
+ if (api_error(root, err, err_len)) {
+ janas_json_free(d);
+ return -1;
+ }
+ const struct janas_json *pages =
+ janas_json_get(janas_json_get(root, "query"), "pages");
+ int k = 0;
+ for (const struct janas_json *p =
+ pages && pages->type == JANAS_JSON_ARRAY ? pages->child : NULL;
+ p && k < max; p = p->next) {
+ struct wiki_hit *h = &hits[k];
+ memset(h, 0, sizeof *h);
+ copy(h->title, sizeof h->title,
+ janas_json_str(janas_json_get(p, "title")));
+ if (!h->title[0])
+ continue;
+ copy(h->desc, sizeof h->desc,
+ janas_json_str(janas_json_get(p, "description")));
+ const char *ex = janas_json_str(janas_json_get(p, "extract"));
+ if (ex) {
+ size_t len = strlen(ex);
+ size_t cut = wiki_cut(ex, len, sizeof h->text - 1);
+ memcpy(h->text, ex, cut);
+ h->text[cut] = 0;
+ }
+ point_of(p, &h->lat, &h->lon);
+ h->index = (int)janas_json_num(janas_json_get(p, "index"), k);
+ /* in the search's order: the API gives them by page id */
+ int i = k++;
+ while (i > 0 && hits[i - 1].index > hits[i].index) {
+ struct wiki_hit t = hits[i - 1];
+ hits[i - 1] = hits[i];
+ hits[i] = t;
+ i--;
+ }
+ }
+ janas_json_free(d);
+ return k;
+}
+
+/* The text with one blank line at most between paragraphs, and none made
+ of spaces: the plain text leaves two or three around each heading, and
+ every byte is the model's context. Its length. */
+static size_t squeeze(const char *s, char *to)
+{
+ size_t n = 0;
+ int newlines = 2; /* none at the start */
+ for (; *s; s++) {
+ if (*s == '\n') {
+ while (n && to[n - 1] == ' ')
+ n--;
+ if (++newlines > 2)
+ continue;
+ } else if (*s == ' ' && newlines) {
+ continue; /* a line's leading spaces */
+ } else {
+ newlines = 0;
+ }
+ to[n++] = *s;
+ }
+ while (n && to[n - 1] == '\n')
+ n--;
+ to[n] = 0;
+ return n;
+}
+
+int wiki_read_page(const char *text, size_t n, struct wiki_page *p, char *err,
+ size_t err_len)
+{
+ memset(p, 0, sizeof *p);
+ p->lat = p->lon = NAN;
+ char why[128];
+ struct janas_json_doc *d = janas_json_parse(text, n, why, sizeof why);
+ if (!d) {
+ snprintf(err, err_len, "Wikipedia: an answer it could not read (%s)",
+ why);
+ return -1;
+ }
+ const struct janas_json *root = janas_json_root(d);
+ if (api_error(root, err, err_len)) {
+ janas_json_free(d);
+ return -1;
+ }
+ const struct janas_json *q = janas_json_get(root, "query");
+ const struct janas_json *pages = janas_json_get(q, "pages");
+ const struct janas_json *pg =
+ pages && pages->type == JANAS_JSON_ARRAY ? pages->child : NULL;
+ if (!pg) {
+ snprintf(err, err_len, "Wikipedia: an answer without the page");
+ janas_json_free(d);
+ return -1;
+ }
+ copy(p->title, sizeof p->title,
+ janas_json_str(janas_json_get(pg, "title")));
+ const struct janas_json *rd = janas_json_get(q, "redirects");
+ if (rd && rd->type == JANAS_JSON_ARRAY && rd->child)
+ copy(p->from, sizeof p->from,
+ janas_json_str(janas_json_get(rd->child, "from")));
+ const struct janas_json *inv = janas_json_get(pg, "invalid");
+ if (inv) {
+ const char *r = janas_json_str(janas_json_get(pg, "invalidreason"));
+ snprintf(err, err_len, "Wikipedia: not a page's title (%s)",
+ r ? r : "invalid");
+ janas_json_free(d);
+ return -1;
+ }
+ p->missing = janas_json_get(pg, "missing") != NULL;
+ p->disamb = janas_json_get(janas_json_get(pg, "pageprops"),
+ "disambiguation") != NULL;
+ copy(p->desc, sizeof p->desc,
+ janas_json_str(janas_json_get(pg, "description")));
+ const char *url = janas_json_str(janas_json_get(pg, "canonicalurl"));
+ copy(p->url, sizeof p->url,
+ url ? url : janas_json_str(janas_json_get(pg, "fullurl")));
+ point_of(pg, &p->lat, &p->lon);
+ const char *ex = janas_json_str(janas_json_get(pg, "extract"));
+ int ok = 0;
+ if (ex) {
+ p->text = malloc(strlen(ex) + 1);
+ if (p->text)
+ p->len = squeeze(ex, p->text);
+ ok = p->text != NULL;
+ } else {
+ ok = 1;
+ }
+ janas_json_free(d);
+ if (!ok)
+ snprintf(err, err_len, "out of memory");
+ return ok ? 0 : -1;
+}
+
+void wiki_page_free(struct wiki_page *p)
+{
+ free(p->text);
+ p->text = NULL;
+ p->len = 0;
+}
+
+/* ---- the text by its headings ---- */
+
+struct heading {
+ size_t at, end; /* the line: its start, and past its newline */
+ int level; /* "== A ==" 2, "=== B ===" 3 */
+ const char *name;
+ size_t name_n;
+};
+
+/* The next heading from from, which is at a line's start. */
+static int next_heading(const char *t, size_t len, size_t from,
+ struct heading *h)
+{
+ for (size_t i = from; i < len;) {
+ const char *nl = memchr(t + i, '\n', len - i);
+ size_t e = nl ? (size_t)(nl - t) : len;
+ size_t lv = 0;
+ while (i + lv < e && t[i + lv] == '=')
+ lv++;
+ if (lv >= 2 && e > i + 2 * lv && t[e - 1] == '=') {
+ size_t a = i + lv, b = e;
+ while (b > a && t[b - 1] == '=')
+ b--;
+ while (a < b && t[a] == ' ')
+ a++;
+ while (b > a && t[b - 1] == ' ')
+ b--;
+ *h = (struct heading){.at = i,
+ .end = nl ? e + 1 : e,
+ .level = (int)lv,
+ .name = t + a,
+ .name_n = b - a};
+ return 1;
+ }
+ i = nl ? e + 1 : len;
+ }
+ return 0;
+}
+
+static size_t trim_end(const char *t, size_t n)
+{
+ while (n && (t[n - 1] == '\n' || t[n - 1] == ' '))
+ n--;
+ return n;
+}
+
+size_t wiki_intro_len(const char *text, size_t len)
+{
+ struct heading h;
+ return trim_end(text, next_heading(text, len, 0, &h) ? h.at : len);
+}
+
+int wiki_section(const char *text, size_t len, const char *name, size_t *start,
+ size_t *n)
+{
+ while (*name == ' ')
+ name++;
+ size_t want = strlen(name);
+ while (want && name[want - 1] == ' ')
+ want--;
+ if (!want)
+ return -1;
+ struct heading h, best = {0};
+ int best_rank = 0;
+ for (size_t at = 0; next_heading(text, len, at, &h); at = h.end) {
+ char hn[256];
+ snprintf(hn, sizeof hn, "%.*s", (int)h.name_n, h.name);
+ char nm[256];
+ snprintf(nm, sizeof nm, "%.*s", (int)want, name);
+ int rank = strcasecmp(hn, nm) == 0 ? 3
+ : strncasecmp(hn, nm, strlen(nm)) == 0 ? 2
+ : strcasestr(hn, nm) ? 1
+ : 0;
+ if (rank > best_rank) {
+ best = h;
+ best_rank = rank;
+ if (rank == 3)
+ break;
+ }
+ }
+ if (!best_rank)
+ return -1;
+ size_t end = len;
+ for (size_t at = best.end; next_heading(text, len, at, &h); at = h.end)
+ if (h.level <= best.level) {
+ end = h.at;
+ break;
+ }
+ *start = best.at;
+ *n = trim_end(text + best.at, end - best.at);
+ return 0;
+}
+
+void wiki_section_list(const char *text, size_t len, struct janas_buf *out)
+{
+ struct heading h;
+ int top = 0, open = 0, subs = 0;
+ for (size_t at = 0; next_heading(text, len, at, &h); at = h.end) {
+ if (!top || h.level < top)
+ top = h.level; /* the shallowest seen: 2 as a rule */
+ if (h.level == top) {
+ if (open)
+ janas_buf_puts(out, subs ? "); " : "; ");
+ janas_buf_put(out, h.name, h.name_n);
+ open = 1;
+ subs = 0;
+ } else if (h.level == top + 1 && open) {
+ janas_buf_puts(out, subs ? ", " : " (");
+ janas_buf_put(out, h.name, h.name_n);
+ subs++;
+ }
+ }
+ if (open && subs)
+ janas_buf_puts(out, ")");
+}
+
+size_t wiki_drop_heads(const char *t, size_t n)
+{
+ for (;;) {
+ n = trim_end(t, n);
+ size_t a = n;
+ while (a && t[a - 1] != '\n')
+ a--;
+ struct heading h;
+ if (a == n || !next_heading(t, n, a, &h) || h.at != a)
+ return n;
+ n = a;
+ }
+}
+
+size_t wiki_cut(const char *s, size_t n, size_t max)
+{
+ if (n <= max)
+ return n;
+ size_t lo = max / 2;
+ for (size_t i = max; i > lo; i--)
+ if (s[i - 1] == '\n')
+ return trim_end(s, i);
+ for (size_t i = max; i > lo; i--)
+ if (s[i - 1] == '.' && s[i] == ' ')
+ return i;
+ for (size_t i = max; i > lo; i--)
+ if (s[i] == ' ')
+ return i;
+ size_t i = max;
+ while (i > 0 && ((unsigned char)s[i] & 0xC0) == 0x80)
+ i--; /* not inside a character */
+ return i;
+}
diff --git a/src/wiki/tools.c b/src/wiki/tools.c
new file mode 100644
index 0000000..3609801
--- /dev/null
+++ b/src/wiki/tools.c
@@ -0,0 +1,594 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * tools.c - the tools janas-wiki offers (see wiki.h): wiki_search,
+ * wiki_page and wiki_nearby, on the API of the Wikipedia of a language
+ * (action=query: TextExtracts for the text, GeoData for the places).
+ */
+#include <ctype.h>
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "common/geo.h"
+#include "common/locate.h"
+#include "common/mcp_server.h"
+#include "wiki.h"
+
+#define KEEP_S 3600 /* a page changes seldom within the hour */
+#define WHOLE_MAX 8000 /* a page this long is given whole */
+#define INTRO_MAX 6000 /* else its introduction, at most this */
+#define SECTION_MAX 10000 /* and a section, at most this */
+#define LICENSE \
+ "Text from Wikipedia, under CC BY-SA 4.0: give the page's address as " \
+ "the source."
+
+static const char *arg_str(const struct janas_json *args, const char *name)
+{
+ const char *s = janas_json_str(janas_json_get(args, name));
+ return s && *s ? s : NULL;
+}
+
+static double arg_num(const struct janas_json *args, const char *name,
+ double def)
+{
+ const struct janas_json *v = janas_json_get(args, name);
+ return v && v->type == JANAS_JSON_NUMBER ? janas_json_num(v, def) : def;
+}
+
+static int result(struct janas_buf *out, struct janas_buf *b, int is_error)
+{
+ janas_mcps_text_result(b, out->p ? out->p : "", out->n, is_error);
+ janas_buf_free(out);
+ return 0;
+}
+
+static int fail(struct janas_buf *b, const char *text)
+{
+ struct janas_buf out = {0};
+ janas_buf_puts(&out, text);
+ return result(&out, b, 1);
+}
+
+static int lang_ok(const char *s, size_t n)
+{
+ int ok = n >= 2 && n <= 12;
+ for (size_t i = 0; ok && i < n; i++)
+ ok = islower((unsigned char)s[i]) || s[i] == '-';
+ return ok;
+}
+
+/* The language of the Wikipedia asked for: "it", "en", "zh-yue"; it goes
+ into the host's name, so nothing else is taken. When the model gives
+ none, the computer's (LANG=it_IT.UTF-8: it), else English. */
+static const char *arg_lang(const struct janas_json *args, char *to, size_t cap)
+{
+ const char *s = arg_str(args, "language");
+ if (s && lang_ok(s, strlen(s)) && strlen(s) < cap) {
+ snprintf(to, cap, "%s", s);
+ return to;
+ }
+ static const char *const vars[] = {"LC_ALL", "LC_MESSAGES", "LANG"};
+ for (size_t i = 0; i < sizeof vars / sizeof *vars; i++) {
+ const char *v = getenv(vars[i]);
+ if (!v || !*v)
+ continue;
+ size_t n = strcspn(v, "_.@");
+ if (lang_ok(v, n) && n < cap) {
+ snprintf(to, cap, "%.*s", (int)n, v);
+ return to;
+ }
+ break; /* the first one set rules, "C" too */
+ }
+ snprintf(to, cap, "en");
+ return to;
+}
+
+static void url_put(struct janas_buf *b, const char *s)
+{
+ static const char hex[] = "0123456789ABCDEF";
+ for (; *s; s++) {
+ unsigned char c = (unsigned char)*s;
+ if (isalnum(c) || c == '-' || c == '_' || c == '.' || c == '~')
+ janas_buf_put(b, (const char *)&c, 1);
+ else
+ janas_buf_printf(b, "%%%c%c", hex[c >> 4], hex[c & 15]);
+ }
+}
+
+static void api_url(struct janas_buf *u, const char *lang)
+{
+ janas_buf_printf(u,
+ "https://%s.wikipedia.org/w/api.php?action=query&"
+ "format=json&formatversion=2&",
+ lang);
+}
+
+/* The answer to url into body: 0, or -1 with the reason in err. */
+static int ask(struct janas_buf *url, struct janas_buf *body, char *err,
+ size_t err_len)
+{
+ if (url->oom) {
+ snprintf(err, err_len, "out of memory");
+ janas_buf_free(url);
+ return -1;
+ }
+ char why[256] = "";
+ int status = wiki_fetch(url->p, KEEP_S, body, why, sizeof why);
+ janas_buf_free(url);
+ if (status == 200)
+ return 0;
+ if (status == 429)
+ snprintf(err, err_len,
+ "Wikipedia asks to slow down (HTTP 429): try again in a "
+ "minute");
+ else if (status > 0)
+ snprintf(err, err_len, "Wikipedia answered HTTP %d", status);
+ else
+ snprintf(err, err_len, "Wikipedia did not answer (%s)", why);
+ return -1;
+}
+
+static void put_point(struct janas_buf *out, double lat, double lon)
+{
+ janas_buf_printf(out, "%.4f, %.4f", lat, lon);
+}
+
+/* ---- wiki_search ---- */
+
+static int tool_search(const struct janas_json *args, struct janas_buf *b)
+{
+ const char *q = arg_str(args, "query");
+ if (!q)
+ return fail(b, "No query given: what to look for.");
+ char lang[16];
+ arg_lang(args, lang, sizeof lang);
+ int limit = (int)arg_num(args, "limit", 8);
+ limit = limit < 1 ? 1 : limit > 20 ? 20 : limit;
+ struct janas_buf url = {0}, body = {0};
+ api_url(&url, lang);
+ janas_buf_puts(&url, "generator=search&gsrsearch=");
+ url_put(&url, q);
+ janas_buf_printf(&url, "&gsrlimit=%d&prop=description%%7Ccoordinates",
+ limit);
+ char err[384];
+ struct wiki_hit *hits = calloc(WIKI_HITS, sizeof *hits);
+ int n = !hits ? -1
+ : ask(&url, &body, err, sizeof err) != 0
+ ? -1
+ : wiki_read_hits(body.p, body.n, hits, limit, err, sizeof err);
+ janas_buf_free(&body);
+ /* titles and a line each: what the model needs to pick one, and no
+ more - every token of it is read before it answers */
+ struct janas_buf out = {0};
+ if (!hits)
+ janas_buf_puts(&out, "out of memory");
+ else if (n < 0)
+ janas_buf_printf(&out, "%s.", err);
+ else if (n == 0)
+ janas_buf_printf(&out,
+ "Nothing found on Wikipedia (%s) for \"%s\". Try "
+ "other words, or another language's Wikipedia "
+ "(en has the most pages).",
+ lang, q);
+ else {
+ janas_buf_printf(&out, "Wikipedia (%s), pages for \"%s\":\n", lang, q);
+ for (int i = 0; i < n; i++) {
+ const struct wiki_hit *h = &hits[i];
+ janas_buf_printf(&out, "%d. %s", i + 1, h->title);
+ if (h->desc[0])
+ janas_buf_printf(&out, " - %s", h->desc);
+ janas_buf_puts(&out, "\n");
+ }
+ janas_buf_puts(&out, "A page is shown to the user by its title, as "
+ "written above.");
+ }
+ free(hits);
+ return result(&out, b, n < 0 || !hits);
+}
+
+/* ---- wiki_page ---- */
+
+/* Words in n bytes of text. */
+static size_t words(const char *s, size_t n)
+{
+ size_t w = 0;
+ for (size_t i = 0; i < n; i++)
+ if (s[i] != ' ' && s[i] != '\n' &&
+ (i == 0 || s[i - 1] == ' ' || s[i - 1] == '\n'))
+ w++;
+ return w;
+}
+
+/*
+ * The page goes to the user as it is, and the model gets a note of it: a
+ * page is thousands of tokens, which a model reads before it can answer -
+ * over a minute of a large one for a page, and a few pages fill its
+ * context - while the user asked to read it, not to have it retold.
+ */
+static int tool_page(const struct janas_json *args, struct janas_buf *b)
+{
+ const char *title = arg_str(args, "title");
+ if (!title)
+ return fail(b, "No title given: the page's title, as a search "
+ "gives it.");
+ const char *section = arg_str(args, "section");
+ char lang[16];
+ arg_lang(args, lang, sizeof lang);
+ struct janas_buf url = {0}, body = {0};
+ api_url(&url, lang);
+ janas_buf_puts(&url, "redirects=1&titles=");
+ url_put(&url, title);
+ janas_buf_puts(&url, "&prop=extracts%7Ccoordinates%7Cdescription%7C"
+ "info%7Cpageprops&inprop=url&explaintext=1&"
+ "exsectionformat=wiki&ppprop=disambiguation");
+ char err[384];
+ struct wiki_page p;
+ int rc = ask(&url, &body, err, sizeof err) != 0
+ ? -1
+ : wiki_read_page(body.p, body.n, &p, err, sizeof err);
+ janas_buf_free(&body);
+ struct janas_buf out = {0}, note = {0}, list = {0};
+ if (rc != 0) {
+ janas_buf_printf(&out, "%s.", err);
+ return result(&out, b, 1);
+ }
+ if (p.missing || !p.text) {
+ janas_buf_printf(&out,
+ "There is no page \"%s\" on Wikipedia (%s): search "
+ "for it, and ask for a page by the title the search "
+ "gives.",
+ title, lang);
+ wiki_page_free(&p);
+ return result(&out, b, 1);
+ }
+ /* the user's: the page as it is */
+ janas_buf_printf(&out, "%s", p.title);
+ if (p.desc[0])
+ janas_buf_printf(&out, " - %s", p.desc);
+ janas_buf_printf(&out, "\nWikipedia (%s): %s\n\n", lang, p.url);
+ const char *what = "its introduction";
+ char what_s[300];
+ size_t from = 0, n = 0, shown;
+ int found = 0;
+ if (p.disamb) {
+ what = "a disambiguation page, the pages of that name";
+ shown = wiki_cut(p.text, p.len, WHOLE_MAX);
+ janas_buf_put(&out, p.text, shown);
+ } else if (section &&
+ wiki_section(p.text, p.len, section, &from, &n) == 0) {
+ found = 1;
+ shown = wiki_drop_heads(p.text + from,
+ wiki_cut(p.text + from, n, SECTION_MAX));
+ janas_buf_put(&out, p.text + from, shown);
+ snprintf(
+ what_s, sizeof what_s, "its section \"%.*s\"",
+ (int)strcspn(p.text + from + strspn(p.text + from, "= "), "=\n"),
+ p.text + from + strspn(p.text + from, "= "));
+ what = what_s;
+ if (shown < n)
+ wiki_section_list(p.text + from, n, &list);
+ } else {
+ if (p.len <= WHOLE_MAX) {
+ what = "whole";
+ shown = p.len;
+ janas_buf_put(&out, p.text, p.len);
+ } else {
+ shown = wiki_cut(p.text, wiki_intro_len(p.text, p.len), INTRO_MAX);
+ janas_buf_put(&out, p.text, shown);
+ wiki_section_list(p.text, p.len, &list);
+ }
+ }
+ size_t nw = words(out.p ? out.p : "", out.n);
+ if (list.p)
+ janas_buf_printf(&out, "\n\nSections: %s.", list.p);
+ janas_buf_puts(&out, "\n\nText from Wikipedia, CC BY-SA 4.0.");
+ /* the model's: a note */
+ janas_buf_printf(&note,
+ "The page \"%s\" of Wikipedia (%s), %s, is shown to "
+ "the user as it is: %s, %zu words.",
+ p.title, lang, p.url, what, nw);
+ if (p.from[0])
+ janas_buf_printf(&note, " Asked as \"%s\", which leads to it.", p.from);
+ if (section && !found && !p.disamb)
+ janas_buf_printf(&note, " It has no section \"%s\".", section);
+ if (list.p)
+ janas_buf_printf(&note, " Its sections, to show one when asked: %s.",
+ list.p);
+ janas_buf_puts(&note, " Do not repeat, translate or summarize it unless "
+ "the user asks; tell them, in a line in their "
+ "language, that the page is above, with its "
+ "address.");
+ janas_buf_free(&list);
+ wiki_page_free(&p);
+ if (out.oom || note.oom) {
+ janas_buf_free(&out);
+ janas_buf_free(&note);
+ return fail(b, "out of memory");
+ }
+ janas_mcps_split_result(b, note.p, note.n, out.p, out.n);
+ janas_buf_free(&out);
+ janas_buf_free(&note);
+ return 0;
+}
+
+/* ---- wiki_nearby ---- */
+
+/* "38.02, 12.51" */
+static int as_point(const char *q, double *lat, double *lon)
+{
+ char *end;
+ double a = strtod(q, &end);
+ if (end == q)
+ return 0;
+ while (*end == ' ' || *end == ',' || *end == ';')
+ end++;
+ char *end2;
+ double b = strtod(end, &end2);
+ while (*end2 == ' ')
+ end2++;
+ if (end2 == end || *end2 || fabs(a) > 90 || fabs(b) > 180)
+ return 0;
+ *lat = a;
+ *lon = b;
+ return 1;
+}
+
+/* A place's point from its page, or else from the first page with one
+ that a search for it finds. 0, or -1 with the reason in err. */
+static int place_point(const char *place, const char *lang, double *lat,
+ double *lon, char *name, size_t name_cap, char *err,
+ size_t err_len)
+{
+ struct janas_buf url = {0}, body = {0};
+ api_url(&url, lang);
+ janas_buf_puts(&url, "redirects=1&titles=");
+ url_put(&url, place);
+ janas_buf_puts(&url, "&prop=coordinates%7Cdescription");
+ struct wiki_page p;
+ if (ask(&url, &body, err, err_len) == 0 &&
+ wiki_read_page(body.p, body.n, &p, err, err_len) == 0) {
+ wiki_page_free(&p);
+ if (!p.missing && !isnan(p.lat)) {
+ *lat = p.lat;
+ *lon = p.lon;
+ snprintf(name, name_cap, "%s", p.title);
+ janas_buf_free(&body);
+ return 0;
+ }
+ }
+ body.n = 0;
+ api_url(&url, lang);
+ janas_buf_puts(&url, "generator=search&gsrlimit=5&gsrsearch=");
+ url_put(&url, place);
+ janas_buf_puts(&url, "&prop=coordinates");
+ struct wiki_hit *hits = calloc(5, sizeof *hits);
+ int n = !hits || ask(&url, &body, err, err_len) != 0
+ ? -1
+ : wiki_read_hits(body.p, body.n, hits, 5, err, err_len);
+ janas_buf_free(&body);
+ int found = -1;
+ for (int i = 0; i < n && found < 0; i++)
+ if (!isnan(hits[i].lat)) {
+ *lat = hits[i].lat;
+ *lon = hits[i].lon;
+ snprintf(name, name_cap, "%s", hits[i].title);
+ found = 0;
+ }
+ free(hits);
+ if (found != 0 && n >= 0)
+ snprintf(err, err_len,
+ "no page of Wikipedia (%s) with coordinates for \"%s\"", lang,
+ place);
+ return found;
+}
+
+static int by_km(const void *a, const void *b)
+{
+ double x = ((const struct wiki_hit *)a)->km;
+ double y = ((const struct wiki_hit *)b)->km;
+ return x < y ? -1 : x > y;
+}
+
+/* A point in words: its town, or "3 km N of Erice" */
+static void point_name(double lat, double lon, char *name, size_t cap)
+{
+ double km;
+ const struct geo_city *c = geo_city_near(lat, lon, &km);
+ if (!c)
+ snprintf(name, cap, "%.4f, %.4f", lat, lon);
+ else if (km < 3)
+ snprintf(name, cap, "%s", c->name);
+ else
+ snprintf(
+ name, cap, "%.0f km %s of %s", km,
+ geo_compass(geo_bearing(c->lat * 1e-5, c->lon * 1e-5, lat, lon)),
+ c->name);
+}
+
+static int tool_nearby(const struct janas_json *args, struct janas_buf *b)
+{
+ const char *place = arg_str(args, "place");
+ double lat = arg_num(args, "latitude", NAN);
+ double lon = arg_num(args, "longitude", NAN);
+ char lang[16], name[256] = "", how[96] = "", err[384];
+ arg_lang(args, lang, sizeof lang);
+ double km = arg_num(args, "radius_km", 2);
+ km = km < 0.1 ? 0.1 : km > 10 ? 10 : km;
+ int limit = (int)arg_num(args, "limit", 15);
+ limit = limit < 1 ? 1 : limit > WIKI_HITS ? WIKI_HITS : limit;
+ struct janas_buf out = {0};
+ if (place && as_point(place, &lat, &lon)) {
+ place = NULL;
+ } else if (place) {
+ if (place_point(place, lang, &lat, &lon, name, sizeof name, err,
+ sizeof err) != 0) {
+ janas_buf_printf(&out,
+ "%s. Give the place's coordinates, or "
+ "its name as its page has it.",
+ err);
+ return result(&out, b, 1);
+ }
+ } else if (isnan(lat) || isnan(lon)) {
+ struct janas_where w;
+ if (janas_where(&w, err, sizeof err) != 0) {
+ janas_buf_printf(&out, "No place given, and %s.", err);
+ return result(&out, b, 1);
+ }
+ lat = w.lat;
+ lon = w.lon;
+ snprintf(name, sizeof name, "%s", w.city);
+ snprintf(how, sizeof how, "%s", w.how);
+ }
+ if (!name[0])
+ point_name(lat, lon, name, sizeof name);
+ struct janas_buf url = {0}, body = {0};
+ api_url(&url, lang);
+ janas_buf_printf(&url,
+ "generator=geosearch&ggscoord=%.5f%%7C%.5f&"
+ "ggsradius=%d&ggslimit=%d&prop=coordinates%%7C"
+ "description&colimit=max",
+ lat, lon, (int)(km * 1000), limit);
+ struct wiki_hit *hits = calloc(WIKI_HITS, sizeof *hits);
+ int n = !hits ? -1
+ : ask(&url, &body, err, sizeof err) != 0
+ ? -1
+ : wiki_read_hits(body.p, body.n, hits, limit, err, sizeof err);
+ janas_buf_free(&body);
+ if (n < 0) {
+ janas_buf_printf(&out, "%s.", hits ? err : "out of memory");
+ free(hits);
+ return result(&out, b, 1);
+ }
+ for (int i = 0; i < n; i++) /* nearest first; without a point last */
+ hits[i].km = isnan(hits[i].lat)
+ ? 1e9
+ : geo_km(lat, lon, hits[i].lat, hits[i].lon);
+ qsort(hits, (size_t)n, sizeof *hits, by_km);
+ janas_buf_printf(&out, "Wikipedia (%s): %d page%s within %.1f km of %s (",
+ lang, n, n == 1 ? "" : "s", km, name);
+ put_point(&out, lat, lon);
+ janas_buf_puts(&out, ")");
+ if (how[0])
+ janas_buf_printf(&out, " - where the user is, %s", how);
+ janas_buf_puts(&out, n ? ":\n" : ".\n");
+ for (int i = 0; i < n; i++) {
+ const struct wiki_hit *h = &hits[i];
+ double d = h->km;
+ janas_buf_printf(&out, "\n%d. %s", i + 1, h->title);
+ if (h->desc[0])
+ janas_buf_printf(&out, " - %s", h->desc);
+ if (d >= 1e8)
+ continue;
+ if (d < 0.05)
+ janas_buf_puts(&out, ": here");
+ else {
+ const char *dir =
+ geo_compass(geo_bearing(lat, lon, h->lat, h->lon));
+ if (d < 1)
+ janas_buf_printf(&out, ": %.0f m %s", round(d * 100) * 10, dir);
+ else
+ janas_buf_printf(&out, ": %.1f km %s", d, dir);
+ }
+ }
+ if (n)
+ janas_buf_puts(&out, "\n\nEach is read by its title, as written "
+ "above.");
+ else
+ janas_buf_puts(&out, "A wider radius (up to 10 km) may find some.");
+ if (how[0])
+ janas_buf_printf(&out,
+ "\nNo place was named: this is where the user is, "
+ "%s. Tell the user which place it is and that it "
+ "may be off: they can name theirs.",
+ how);
+ janas_buf_puts(&out, "\n" LICENSE);
+ free(hits);
+ return result(&out, b, 0);
+}
+
+/* ---- the list ---- */
+
+static void schema_str(struct janas_buf *b, const char *name, const char *what)
+{
+ janas_buf_printf(b,
+ "\"%s\": {\"type\": \"string\", \"description\": ", name);
+ janas_json_write_str(b, what, strlen(what));
+ janas_buf_puts(b, "}");
+}
+
+static void lang_prop(struct janas_buf *b)
+{
+ schema_str(b, "language",
+ "The Wikipedia's language: the user's (it, en...).");
+}
+
+void wiki_tools_list(void *ctx, struct janas_buf *b)
+{
+ (void)ctx;
+ janas_buf_puts(
+ b, "\"tools\": [{\"name\": \"wiki_search\", \"title\": \"Search "
+ "Wikipedia\", \"description\": \"The pages of Wikipedia that "
+ "match some words, best first: their titles, each with what it "
+ "is about in a line.\", \"inputSchema\": {\"type\": \"object\", "
+ "\"properties\": {");
+ schema_str(b, "query", "A name, a subject, a few words.");
+ janas_buf_puts(b, ", ");
+ lang_prop(b);
+ janas_buf_puts(
+ b, ", \"limit\": {\"type\": \"integer\", \"minimum\": 1, "
+ "\"maximum\": 20, \"description\": \"How many pages (default "
+ "8).\"}}, \"required\": [\"query\"], \"additionalProperties\": "
+ "false}}, {\"name\": \"wiki_page\", \"title\": \"A page of "
+ "Wikipedia\", \"description\": \"Shows the user a page of "
+ "Wikipedia as it is: a short one whole, a long one its "
+ "introduction, or the section asked for. You get a note of it "
+ "(its address, its sections), not the text.\", "
+ "\"inputSchema\": {\"type\": \"object\", \"properties\": {");
+ schema_str(b, "title", "The page's title, as a search gives it.");
+ janas_buf_puts(b, ", ");
+ schema_str(b, "section", "A section, by the name the note lists.");
+ janas_buf_puts(b, ", ");
+ lang_prop(b);
+ janas_buf_puts(
+ b, "}, \"required\": [\"title\"], \"additionalProperties\": "
+ "false}}, {\"name\": \"wiki_nearby\", \"title\": \"Wikipedia "
+ "around a place\", \"description\": \"The pages of Wikipedia "
+ "about what lies around a place - monuments, churches, "
+ "museums, stations, villages - nearest first, with how far and "
+ "which way.\", \"inputSchema\": {\"type\": \"object\", "
+ "\"properties\": {");
+ schema_str(b, "place",
+ "A place, as its page is titled, or \"lat,lon\". Leave out "
+ "place and coordinates only when the user names no place: "
+ "then where the user is.");
+ janas_buf_puts(
+ b, ", \"latitude\": {\"type\": \"number\", \"minimum\": -90, "
+ "\"maximum\": 90}, \"longitude\": {\"type\": \"number\", "
+ "\"minimum\": -180, \"maximum\": 180}, \"radius_km\": "
+ "{\"type\": \"number\", \"minimum\": 0.1, \"maximum\": 10, "
+ "\"description\": \"How far around, in km (default 2).\"}, "
+ "\"limit\": {\"type\": \"integer\", \"minimum\": 1, "
+ "\"maximum\": 30, \"description\": \"How many pages (default "
+ "15).\"}, ");
+ lang_prop(b);
+ janas_buf_puts(b, "}, \"additionalProperties\": false}}]");
+}
+
+int wiki_tools_call(void *ctx, const struct janas_json *params,
+ struct janas_buf *b)
+{
+ (void)ctx;
+ const struct janas_json *name = janas_json_get(params, "name");
+ const struct janas_json *args = janas_json_get(params, "arguments");
+ if (args && args->type != JANAS_JSON_OBJECT)
+ args = NULL;
+ if (janas_json_is(name, "wiki_search"))
+ return tool_search(args, b);
+ if (janas_json_is(name, "wiki_page"))
+ return tool_page(args, b);
+ if (janas_json_is(name, "wiki_nearby"))
+ return tool_nearby(args, b);
+ return -1;
+}
diff --git a/src/wiki/wiki.h b/src/wiki/wiki.h
new file mode 100644
index 0000000..122d642
--- /dev/null
+++ b/src/wiki/wiki.h
@@ -0,0 +1,90 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * wiki.h - janas-wiki, Wikipedia as an MCP service: what its parts share.
+ * fetch.c asks Wikipedia's API (answers kept a while), read.c reads its
+ * answers and cuts a page into its sections, tools.c offers the tools.
+ */
+#ifndef JANAS_WIKI_H
+#define JANAS_WIKI_H
+
+#include <stddef.h>
+
+#include "llm/json.h"
+
+/* ---- fetch.c ---- */
+
+/* GET of url, the body into out, with the User-Agent Wikimedia asks for;
+ answers of status 200 are kept keep_s seconds and given again meanwhile.
+ The HTTP status, or -1 with the reason in err. */
+int wiki_fetch(const char *url, int keep_s, struct janas_buf *out, char *err,
+ size_t err_len);
+void wiki_fetch_free(void);
+
+/* ---- read.c ---- */
+
+#define WIKI_HITS 30
+
+/* A page as a search or a list gives it */
+struct wiki_hit {
+ char title[256];
+ char desc[256]; /* Wikidata's short description; "" when none */
+ char text[1200]; /* its first sentences; "" when not asked */
+ double lat, lon; /* its primary coordinates; NAN when none */
+ double km; /* from the point asked about (wiki_nearby) */
+ int index; /* its rank in the search, or in the list */
+};
+
+/* The pages of an answer of action=query with a generator (search,
+ geosearch), in their order. How many, or -1 with the reason in err (an
+ error of the API, an answer not read). */
+int wiki_read_hits(const char *text, size_t n, struct wiki_hit *hits, int max,
+ char *err, size_t err_len);
+
+struct wiki_page {
+ char title[256];
+ char from[256]; /* the title asked for, when it was a redirect */
+ char desc[256];
+ char url[512];
+ double lat, lon;
+ int missing; /* there is no page of that title */
+ int disamb; /* a disambiguation page */
+ char *text; /* the plain text, "== Heading ==" lines; malloc'd */
+ size_t len;
+};
+
+/* A page from an answer of action=query&titles=... (extracts,
+ coordinates, description, info, pageprops). 0, or -1 with the reason in
+ err; free with wiki_page_free. */
+int wiki_read_page(const char *text, size_t n, struct wiki_page *p, char *err,
+ size_t err_len);
+void wiki_page_free(struct wiki_page *p);
+
+/* The page's text before its first heading. */
+size_t wiki_intro_len(const char *text, size_t len);
+
+/* The section whose heading is name (its name, case aside; else the first
+ heading that begins with it, else holds it), with its subsections: its
+ start (at its heading) and length. 0, or -1 when there is none. */
+int wiki_section(const char *text, size_t len, const char *name, size_t *start,
+ size_t *n);
+
+/* The page's sections as "A (A1, A2); B; ...": level 2 headings, those of
+ level 3 in brackets. */
+void wiki_section_list(const char *text, size_t len, struct janas_buf *out);
+
+/* n less the headings (and blank lines) the text ends with: a cut text
+ does not end on a heading whose text is left out. */
+size_t wiki_drop_heads(const char *text, size_t n);
+
+/* At most max bytes of s, cut at the end of a paragraph or else of a
+ sentence or a word, and never inside a UTF-8 character. */
+size_t wiki_cut(const char *s, size_t n, size_t max);
+
+/* ---- tools.c ---- */
+
+void wiki_tools_list(void *ctx, struct janas_buf *b);
+int wiki_tools_call(void *ctx, const struct janas_json *params,
+ struct janas_buf *b);
+
+#endif
diff --git a/tests/llm_keep.c b/tests/llm_keep.c
index da30ad9..18b68dc 100644
--- a/tests/llm_keep.c
+++ b/tests/llm_keep.c
@@ -13,8 +13,12 @@
* keeps them in too little memory to hold one, and must behave as the first.
* Last, the disk (janas_llm_chat_keep_disk): a conversation with a long
* system message is written when its chat ends, and a new chat finds it
- * computed, with the same reply. The disk is a directory of the test's own
- * (XDG_CACHE_HOME), removed at the end.
+ * computed, with the same reply. And the system message read ahead
+ * (janas_llm_chat_prepare), as janas-chat does while its user writes: the
+ * reply to the first message is the same as without it, the message
+ * finds the system message computed, a new chat finds it on the disk at
+ * once, and a new system message set after it drops it. The disk is a
+ * directory of the test's own (XDG_CACHE_HOME), removed at the end.
*
* Usage: llm_keep <model.jns> [mtp=<file>] [draft=<file>]
*/
@@ -168,6 +172,144 @@ static int run_disk(janas_llm *llm)
return 0;
}
+/* A message sent (janas_llm_chat_send) and its reply read, into t. */
+static int send_reply(janas_llm_chat *c, const char *text, struct turn *t)
+{
+ if (janas_llm_chat_send(c, text, -1) != JANAS_LLM_OK) {
+ fprintf(stderr, "send: %s\n", janas_llm_last_error());
+ return -1;
+ }
+ size_t len = 0;
+ for (;;) {
+ char buf[256];
+ int32_t k = 0;
+ int32_t rc = janas_llm_chat_next(c, buf, sizeof(buf), &k);
+ if (rc == JANAS_LLM_DONE)
+ break;
+ if (rc != JANAS_LLM_OK) {
+ fprintf(stderr, "next: %s\n", janas_llm_last_error());
+ return -1;
+ }
+ if (len + (size_t)k < CAP) {
+ memcpy(t->text + len, buf, (size_t)k);
+ len += (size_t)k;
+ }
+ }
+ t->text[len] = 0;
+ struct janas_llm_chat_stats st = {.size = sizeof(st)};
+ janas_llm_chat_stats(c, &st);
+ t->prompt = st.prompt_tokens;
+ t->cached = st.cached_tokens;
+ return 0;
+}
+
+/* A chat with the system message sys; keep: kept in memory and on the
+ disk. */
+static janas_llm_chat *chat_with(janas_llm *llm, const char *sys, int keep)
+{
+ struct janas_llm_chat_params p;
+ janas_llm_chat_params_default(&p);
+ p.temperature = 0;
+ p.max_reply = REPLY;
+ p.thinking = 0;
+ janas_llm_chat *c;
+ if (janas_llm_chat_create(llm, &p, &c) != JANAS_LLM_OK)
+ return NULL;
+ if (janas_llm_chat_system(c, sys, -1) != JANAS_LLM_OK ||
+ (keep &&
+ (janas_llm_chat_keep(c, 2, 0) != JANAS_LLM_OK ||
+ janas_llm_chat_keep_disk(c, (uint64_t)1 << 30) != JANAS_LLM_OK))) {
+ janas_llm_chat_destroy(c);
+ return NULL;
+ }
+ return c;
+}
+
+/* The system message read ahead: rc of the first call, steps, and the
+ tokens read of how many. */
+static int prepare_all(janas_llm_chat *c, int *first, int *steps, int32_t *done,
+ int32_t *total)
+{
+ int rc;
+ *steps = 0;
+ while ((rc = janas_llm_chat_prepare(c, done, total)) == 1)
+ if ((*steps)++ == 0)
+ *first = 1;
+ if (*steps == 0)
+ *first = rc;
+ return rc;
+}
+
+static int run_prepare(janas_llm *llm)
+{
+ static char sys[32768];
+ size_t n = (size_t)snprintf(sys, sizeof(sys), "Read ahead.\n");
+ for (int i = 1; i <= 90; i++)
+ n += (size_t)snprintf(sys + n, sizeof(sys) - n,
+ "Rule %d: answer briefly, in English, and "
+ "never mention the number %d.\n",
+ i, 1000 + 7 * i);
+ static struct turn plain, ahead, again, other;
+ int fail = 0, first = 0, steps = 0, first2 = 0, steps2 = 0;
+ int32_t done = 0, total = 0, done2 = 0, total2 = 0;
+ /* without it */
+ janas_llm_chat *c = chat_with(llm, sys, 0);
+ if (!c || send_reply(c, A1, &plain))
+ return -1;
+ janas_llm_chat_destroy(c);
+ /* read ahead, then the message */
+ c = chat_with(llm, sys, 1);
+ if (!c || prepare_all(c, &first, &steps, &done, &total) != 0 ||
+ send_reply(c, A1, &ahead))
+ return -1;
+ janas_llm_chat_destroy(c); /* and to the disk */
+ /* a new chat: found on the disk */
+ c = chat_with(llm, sys, 1);
+ if (!c || prepare_all(c, &first2, &steps2, &done2, &total2) != 0 ||
+ send_reply(c, A1, &again))
+ return -1;
+ janas_llm_chat_destroy(c);
+ /* read ahead, then another system message */
+ c = chat_with(llm, sys, 0);
+ int32_t d3, t3;
+ int other_ok =
+ c && janas_llm_chat_prepare(c, &d3, &t3) >= 0 &&
+ janas_llm_chat_system(c, "Answer in one word.", -1) == JANAS_LLM_OK &&
+ send_reply(c, A1, &other) == 0;
+ if (c)
+ janas_llm_chat_destroy(c);
+ printf("prepare: %d steps, %d of %d tokens; prompt/cached %u/%u (without "
+ "it %u/%u); a new chat: %d steps (first %d), %d of %d, %u/%u; "
+ "another system message: %u/%u\n",
+ steps, done, total, ahead.prompt, ahead.cached, plain.prompt,
+ plain.cached, steps2, first2, done2, total2, again.prompt,
+ again.cached, other.prompt, other.cached);
+ if (done != total || total < 1024 || steps < 1) {
+ printf("FAIL: prepare: not read to the end\n");
+ fail = 1;
+ }
+ if (strcmp(plain.text, ahead.text) || strcmp(plain.text, again.text)) {
+ printf("FAIL: prepare: another reply\n--- without\n%s\n--- "
+ "ahead\n%s\n--- again\n%s\n",
+ plain.text, ahead.text, again.text);
+ fail = 1;
+ }
+ if (ahead.cached + 1 < (uint32_t)total ||
+ again.cached + 1 < (uint32_t)total) {
+ printf("FAIL: prepare: the message did not find it computed\n");
+ fail = 1;
+ }
+ if (steps2 != 0 || first2 != 0 || done2 != total2) {
+ printf("FAIL: prepare: a new chat read it again (%d steps)\n", steps2);
+ fail = 1;
+ }
+ if (!other_ok || other.cached > 8 || other.prompt >= (uint32_t)total) {
+ printf("FAIL: prepare: another system message kept the first\n");
+ fail = 1;
+ }
+ return fail;
+}
+
int main(int argc, char **argv)
{
if (argc < 2) {
@@ -233,10 +375,12 @@ int main(int argc, char **argv)
tmp && *tmp ? tmp : "/tmp", (int)getpid());
if (!fail) {
setenv("XDG_CACHE_HOME", dir, 1);
- fail = run_disk(llm) != 0;
+ fail = run_disk(llm) != 0 || run_prepare(llm) != 0;
nftw(dir, rm_one, 16, FTW_DEPTH | FTW_PHYS);
}
janas_llm_close(llm);
- printf("%s\n", fail ? "FAIL" : "OK: same replies, first turns kept");
+ printf("%s\n", fail ? "FAIL"
+ : "OK: same replies, first turns kept, system "
+ "message read ahead");
return fail;
}
diff --git a/tests/mcp_fake_server.c b/tests/mcp_fake_server.c
index 33c9690..afc2555 100644
--- a/tests/mcp_fake_server.c
+++ b/tests/mcp_fake_server.c
@@ -162,7 +162,10 @@ static void call(const struct janas_json *id, const struct janas_json *params)
"\"mimeType\":\"image/png\"},{\"type\":\"resource_link\","
"\"uri\":\"file:///x.txt\",\"name\":\"x.txt\"},{\"type\":"
"\"resource\",\"resource\":{\"uri\":\"file:///y.txt\","
- "\"text\":\"why\"}}]");
+ "\"text\":\"why\"}},{\"type\":\"text\",\"text\":\"for "
+ "you\",\"annotations\":{\"audience\":[\"user\"]}},{\"type\""
+ ":\"text\",\"text\":\"both\",\"annotations\":{\"audience\""
+ ":[\"user\",\"assistant\"]}}]");
} else if (strcmp(name, "whoami") == 0) {
char s[600];
snprintf(s, sizeof(s), "name=%s param=%s", seen_name, seen_param);
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 42a0f13..ee8e2ef 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -248,8 +248,19 @@ static void check_calls(janas_mcp *m)
CHECK(janas_mcp_call(m, "picture", -1, "{}", -1, 10) == JANAS_MCP_OK &&
janas_mcp_result(m, buf, sizeof(buf), &len) == JANAS_MCP_OK &&
strstr(buf, "[image image/png, 6 bytes") &&
- strstr(buf, "file:///x.txt") && strstr(buf, "why"),
+ strstr(buf, "file:///x.txt") && strstr(buf, "why") &&
+ strstr(buf, "both") && !strstr(buf, "for you"),
"picture: %s", buf);
+ /* the part for the user alone, apart */
+ CHECK(janas_mcp_result_user(m, buf, sizeof(buf), &len) == JANAS_MCP_OK &&
+ strcmp(buf, "for you") == 0 && len == 7,
+ "for the user alone: %s", buf);
+ CHECK(janas_mcp_call(m, "add", -1, "{\"a\": 1, \"b\": 2}", -1, 10) ==
+ JANAS_MCP_OK &&
+ janas_mcp_result_user(m, buf, sizeof(buf), &len) ==
+ JANAS_MCP_OK &&
+ len == 0,
+ "nothing for the user alone: %d", len);
CHECK(janas_mcp_call(m, "nothing", -1, "{}", -1, 10) == JANAS_MCP_EFAIL,
"unknown tool");
CHECK(janas_mcp_call(m, "add", -1, "[1]", -1, 10) == JANAS_MCP_EINVAL,
diff --git a/tests/test_wiki_parse.c b/tests/test_wiki_parse.c
new file mode 100644
index 0000000..26bdbd7
--- /dev/null
+++ b/tests/test_wiki_parse.c
@@ -0,0 +1,198 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ Copyright (C) 2026 Maurizio Cammalleri */
+/*
+ * test_wiki_parse.c - janas-wiki's reading of Wikipedia's answers, without
+ * the network: a search and a geosearch as they came on 1 October 2026
+ * (cut to three pages, given by page id and not in their order), a page
+ * reached through a redirect, a disambiguation page, a missing one and an
+ * error of the API; and a page's text cut by its headings.
+ * The sources belong to the program, so they are compiled in here.
+ */
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "wiki/read.c"
+
+static int failures;
+
+#define CHECK(c, ...) \
+ do { \
+ if (!(c)) { \
+ printf(__VA_ARGS__); \
+ printf("\n"); \
+ failures++; \
+ } \
+ } while (0)
+
+static const char SEARCH[] =
+ "{\"batchcomplete\": true, \"continue\": {\"gsroffset\": 3, "
+ "\"continue\": \"gsroffset||\"}, \"query\": {\"pages\": [{\"pageid\": "
+ "4173, \"ns\": 0, \"title\": \"Trapani\", \"index\": 2, \"coordinates\": "
+ "[{\"lat\": 38.0175, \"lon\": 12.515, \"primary\": true, \"globe\": "
+ "\"earth\"}], \"description\": \"comune italiano\", \"extract\": "
+ "\"Trapani \\u00e8 un comune italiano di 54 546 abitanti.\"}, "
+ "{\"pageid\": 232190, \"ns\": 0, \"title\": \"I promessi sposi (film "
+ "1941)\", \"index\": 3, \"description\": \"film del 1941 diretto da "
+ "Mario Camerini\", \"extract\": \"I promessi sposi \\u00e8 un film del "
+ "1941.\"}, {\"pageid\": 2719455, \"ns\": 0, \"title\": \"I promessi "
+ "sposi\", \"index\": 1, \"extract\": \"I promessi sposi \\u00e8 un "
+ "romanzo storico di Alessandro Manzoni.\"}]}}";
+
+static const char NEAR[] =
+ "{\"batchcomplete\": true, \"query\": {\"pages\": [{\"pageid\": 1, "
+ "\"title\": \"Castello di Terra\", \"index\": 5, \"coordinates\": "
+ "[{\"lat\": 38.019264, \"lon\": 12.514415}], \"description\": "
+ "\"castello di Trapani, Italia\"}, {\"pageid\": 2, \"title\": "
+ "\"Trapani\", \"index\": -1, \"coordinates\": [{\"lat\": 38.0175, "
+ "\"lon\": 12.515}]}, {\"pageid\": 3, \"title\": \"Palazzo D'Al\\u00ec\", "
+ "\"index\": 2, \"coordinates\": [{\"lat\": 38.01856, \"lon\": "
+ "12.5136}]}]}}";
+
+static const char PAGE[] =
+ "{\"batchcomplete\": true, \"query\": {\"redirects\": [{\"from\": "
+ "\"Manzoni\", \"to\": \"Alessandro Manzoni\"}], \"pages\": "
+ "[{\"pageid\": 2719455, \"ns\": 0, \"title\": \"Alessandro Manzoni\", "
+ "\"description\": \"scrittore, poeta e drammaturgo italiano\", "
+ "\"fullurl\": \"https://it.wikipedia.org/wiki/Alessandro_Manzoni\", "
+ "\"canonicalurl\": \"https://it.wikipedia.org/wiki/Alessandro_Manzoni\", "
+ "\"extract\": \"Alessandro Manzoni \\u00e8 stato uno scrittore.\\nNato "
+ "a Milano.\\n\\n\\n== Biografia ==\\nLa vita.\\n\\n=== Infanzia "
+ "===\\nI primi anni.\\n\\n=== La conversione ===\\nNel 1810.\\n\\n\\n== "
+ "Opere ==\\nI promessi sposi.\\n\\n== Note ==\\n\"}]}}";
+
+static const char DISAMB[] =
+ "{\"query\": {\"pages\": [{\"pageid\": 2786, \"title\": \"Mercurio\", "
+ "\"pageprops\": {\"disambiguation\": \"\"}, \"extract\": \"Mercurio "
+ "\\u2013 pianeta\\nMercurio \\u2013 elemento chimico\"}]}}";
+
+static const char MISSING[] =
+ "{\"batchcomplete\": true, \"query\": {\"pages\": [{\"ns\": 0, "
+ "\"title\": \"Xyzzyqq\", \"missing\": true}]}}";
+
+static const char ERROR[] =
+ "{\"error\": {\"code\": \"badvalue\", \"info\": \"Unrecognized value "
+ "for parameter \\\"prop\\\": nope.\"}, \"servedby\": \"mw-api\"}";
+
+static void test_hits(void)
+{
+ struct wiki_hit h[WIKI_HITS];
+ char err[256];
+ int n =
+ wiki_read_hits(SEARCH, strlen(SEARCH), h, WIKI_HITS, err, sizeof err);
+ CHECK(n == 3, "search: %d (%s)", n, n < 0 ? err : "");
+ if (n == 3) {
+ CHECK(strcmp(h[0].title, "I promessi sposi") == 0 &&
+ strcmp(h[1].title, "Trapani") == 0 &&
+ strcmp(h[2].title, "I promessi sposi (film 1941)") == 0,
+ "search order: %s / %s / %s", h[0].title, h[1].title, h[2].title);
+ CHECK(isnan(h[0].lat) && fabs(h[1].lat - 38.0175) < 1e-9 &&
+ fabs(h[1].lon - 12.515) < 1e-9,
+ "search points");
+ CHECK(strcmp(h[1].desc, "comune italiano") == 0 &&
+ strstr(h[1].text, "54 546") && h[0].desc[0] == 0,
+ "search texts: '%s' '%s'", h[1].desc, h[1].text);
+ }
+ n = wiki_read_hits(SEARCH, strlen(SEARCH), h, 2, err, sizeof err);
+ CHECK(n == 2, "search, at most 2: %d", n);
+ n = wiki_read_hits(NEAR, strlen(NEAR), h, WIKI_HITS, err, sizeof err);
+ CHECK(n == 3 && strcmp(h[0].title, "Trapani") == 0 &&
+ strcmp(h[1].title, "Palazzo D'Alì") == 0,
+ "geosearch: %d %s %s", n, n > 1 ? h[0].title : "",
+ n > 1 ? h[1].title : "");
+ n = wiki_read_hits(ERROR, strlen(ERROR), h, WIKI_HITS, err, sizeof err);
+ CHECK(n < 0 && strstr(err, "Unrecognized value"), "error: %d %s", n, err);
+ n = wiki_read_hits("<html>", 6, h, WIKI_HITS, err, sizeof err);
+ CHECK(n < 0, "not json: %d", n);
+ n = wiki_read_hits("{\"batchcomplete\": true}", 23, h, WIKI_HITS, err,
+ sizeof err);
+ CHECK(n == 0, "nothing found: %d", n);
+}
+
+static void test_page(void)
+{
+ struct wiki_page p;
+ char err[256];
+ CHECK(wiki_read_page(PAGE, strlen(PAGE), &p, err, sizeof err) == 0,
+ "page: %s", err);
+ CHECK(strcmp(p.title, "Alessandro Manzoni") == 0 &&
+ strcmp(p.from, "Manzoni") == 0 && !p.missing && !p.disamb &&
+ isnan(p.lat) && strstr(p.url, "Alessandro_Manzoni"),
+ "page fields: %s %s %s", p.title, p.from, p.url);
+ size_t intro = wiki_intro_len(p.text, p.len);
+ CHECK(intro == strlen("Alessandro Manzoni è stato uno scrittore.\n"
+ "Nato a Milano."),
+ "intro: %zu", intro);
+ struct janas_buf list = {0};
+ wiki_section_list(p.text, p.len, &list);
+ CHECK(list.p && strcmp(list.p, "Biografia (Infanzia, La conversione); "
+ "Opere; Note") == 0,
+ "sections: %s", list.p ? list.p : "(none)");
+ janas_buf_free(&list);
+ size_t at, n;
+ CHECK(wiki_section(p.text, p.len, "biografia", &at, &n) == 0 &&
+ strncmp(p.text + at, "== Biografia ==", 15) == 0 &&
+ strstr(p.text + at, "Nel 1810.") &&
+ memcmp(p.text + at + n - 9, "Nel 1810.", 9) == 0,
+ "section Biografia: %.*s", (int)n, p.text + at);
+ CHECK(wiki_section(p.text, p.len, "La conv", &at, &n) == 0 &&
+ n == strlen("=== La conversione ===\nNel 1810."),
+ "section by its start: %zu", n);
+ CHECK(wiki_section(p.text, p.len, "conversione", &at, &n) == 0,
+ "section by a part");
+ CHECK(wiki_section(p.text, p.len, "Opere", &at, &n) == 0 &&
+ n == strlen("== Opere ==\nI promessi sposi."),
+ "section Opere: %zu", n);
+ CHECK(wiki_section(p.text, p.len, "Discografia", &at, &n) != 0,
+ "no such section");
+ CHECK(strstr(p.text, "Milano.\n\n== Biografia ==\nLa vita.\n\n=== "
+ "Infanzia") &&
+ p.text[p.len - 1] == '=',
+ "squeezed: %s", p.text);
+ const char *cut = "Testo.\n\n== A ==\nDi A.\n\n== B ==\n\n=== B1 ===\n";
+ CHECK(wiki_drop_heads(cut, strlen(cut)) == strlen("Testo.\n\n== A "
+ "==\nDi A."),
+ "headings dropped: %zu", wiki_drop_heads(cut, strlen(cut)));
+ wiki_page_free(&p);
+
+ CHECK(wiki_read_page(DISAMB, strlen(DISAMB), &p, err, sizeof err) == 0 &&
+ p.disamb && strstr(p.text, "elemento chimico"),
+ "disambiguation");
+ wiki_page_free(&p);
+ CHECK(wiki_read_page(MISSING, strlen(MISSING), &p, err, sizeof err) == 0 &&
+ p.missing && !p.text,
+ "missing");
+ wiki_page_free(&p);
+ CHECK(wiki_read_page(ERROR, strlen(ERROR), &p, err, sizeof err) != 0,
+ "page error");
+}
+
+static void test_cut(void)
+{
+ const char *s = "Uno due tre.\n\nQuattro cinque. Sei sette otto.";
+ size_t n = strlen(s);
+ CHECK(wiki_cut(s, n, 100) == n, "no cut");
+ CHECK(wiki_cut(s, n, 20) == 12, "cut at the paragraph: %zu",
+ wiki_cut(s, n, 20));
+ CHECK(wiki_cut(s, n, 35) == 29, "cut at the sentence: %zu",
+ wiki_cut(s, n, 35));
+ const char *u = "aaaa è è è è è è è è";
+ size_t k = wiki_cut(u, strlen(u), 8);
+ CHECK(k == 7, "cut at a word: %zu", k); /* "aaaa è" */
+ const char *v = "èèèèèèèèèè";
+ k = wiki_cut(v, strlen(v), 7);
+ CHECK(k == 6, "cut not inside a character: %zu", k);
+}
+
+int main(void)
+{
+ test_hits();
+ test_page();
+ test_cut();
+ if (failures) {
+ printf("test_wiki_parse: %d failures\n", failures);
+ return 1;
+ }
+ printf("test_wiki_parse: ok\n");
+ return 0;
+}