Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 kami
|
64e5f3bdc1 |
@@ -82,23 +82,9 @@ workspace enforces that the Go and relabelling prompts remain identical.
|
||||
|
||||
## Non-goals (hard constraints)
|
||||
|
||||
Not a nag, not autonomous. Maven's persona is **feminine** — Russian
|
||||
Never phones home. Not a nag, not autonomous. Maven's persona is **feminine** — Russian
|
||||
self-reference must use feminine forms (the user is male; see memory `maven-persona-gender`).
|
||||
|
||||
**"Never phones home" is DEPRECATED** (owner's call, 2026-07-31). It used to be a hard
|
||||
constraint and it is not one any more: a 0.8B — and a 1.7B — does not know enough to answer
|
||||
world questions, so she needs to read external sources. What replaces it:
|
||||
|
||||
- **No telemetry, no cloud model, no third-party account.** That part never changes. Nothing
|
||||
about Maven is reported to anyone, and inference stays on the box.
|
||||
- **Local sources first.** Kiwix ZIMs on homesrv (Wikipedia, ifixit) before anything on the
|
||||
network. Reading beats recalling for a small model, and a local read costs nothing.
|
||||
- **External search is allowed and off unless configured**, like the weather and telegram
|
||||
capabilities.
|
||||
- **His notes and facts are never search input.** Looking up why the sky is blue and sending
|
||||
his stored personal notes to an upstream engine are different acts. Only the utterance goes
|
||||
out, never the persona block, history, or matched notes.
|
||||
|
||||
## Web UI conventions
|
||||
|
||||
Server-rendered pages share `cmd/mavweb/static/ui.css` (served at `/ui.css`) and the `nav`
|
||||
|
||||
@@ -15,8 +15,7 @@
|
||||
|
||||
**Maven** — self-hosted personal assistant. Manages your day, acts on your
|
||||
homelab. One daemon on homesrv (always-on, not the workstation), multiple
|
||||
client surfaces. Inference and data stay on the box; she may READ external
|
||||
sources (see Non-goals — "never phones home" is deprecated).
|
||||
client surfaces. All local, never phones home.
|
||||
|
||||
Primary name is "Maven", with feminine-gendered Russian self-reference
|
||||
("она", "меня", "помогла"). Clients may choose their own UI label. Consistent
|
||||
@@ -36,13 +35,8 @@ Inside boundary — the ones that actually constrain the build:
|
||||
she records. A confident wrong fact is worse than a known gap.
|
||||
- **Not a nag** — she'd rather miss a nudge than be mutable. Shuts up when
|
||||
uncertain. Load-bearing.
|
||||
- **Not a stranger** — runs on your stuff, your model, your data. No
|
||||
telemetry, no cloud model, no third-party account. She may READ external
|
||||
sources to answer world questions (Kiwix first, then optional search); she
|
||||
never reports anything about you to anyone, and your notes and facts are
|
||||
never used as search input. **"Never phones home" as an absolute is
|
||||
deprecated** — owner's call, 2026-07-31: a small model does not know enough
|
||||
to be useful without reading.
|
||||
- **Not a stranger** — runs on your stuff, your model, your data. Never
|
||||
phones home.
|
||||
- **Not a relationship** — mom-tone is a function that makes nudges land, not
|
||||
emotional company. Names the drift a warm small model falls into.
|
||||
|
||||
@@ -464,7 +458,7 @@ decides *insistence*. Both are needed.
|
||||
|
||||
sev ≤ 2 drops on away, sev ≥ 3 holds: a missed water nudge is noise, a missed
|
||||
backup failure isn't. Away-channels (ntfy/telegram) leave the box — the one
|
||||
path that leaves the box for a person to see, through your own relay. **Minimal
|
||||
path that crosses "never phones home," through your own relay. **Minimal
|
||||
body** — "disk low on homesrv," not detail; don't make notifications a
|
||||
shoulder-surf exfil surface.
|
||||
|
||||
|
||||
@@ -90,7 +90,4 @@ later* is the worker + RAG.
|
||||
4. **Deferred work** — larger reasoner, custom Piper voice and other expansions.
|
||||
|
||||
## Non-goals (unchanged)
|
||||
Not a nag. Not autonomous. Feminine-gendered RU self-ref. No telemetry, no
|
||||
cloud model, no third-party account — but she MAY read external sources to
|
||||
answer world questions (Kiwix first, search optional). "Never phones home" as
|
||||
an absolute is deprecated, owner's call 2026-07-31; see CLAUDE.md § Non-goals.
|
||||
Never phones home. Not a nag. Not autonomous. Feminine-gendered RU self-ref.
|
||||
|
||||
@@ -1,116 +0,0 @@
|
||||
// Package kiwix reads a local Kiwix server (offline Wikipedia and friends).
|
||||
//
|
||||
// Why: the resident model is a 0.8B and invents facts. Letting her read a local
|
||||
// article snippet beats letting her recall. Nothing here talks to the internet;
|
||||
// the Kiwix server is on the same box.
|
||||
//
|
||||
// This is search only. Full articles are ~100KB of HTML, far too big for a 4096
|
||||
// token context, so the unit of context is the search snippet (~500 chars).
|
||||
package kiwix
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/xml"
|
||||
"fmt"
|
||||
"html"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"regexp"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Result is one search hit.
|
||||
type Result struct {
|
||||
Title string // article title, e.g. "Rayleigh scattering"
|
||||
Path string // e.g. /content/wikipedia_en_all_maxi_2026-02/Rayleigh_scattering
|
||||
Snippet string // plain text, tags stripped, entities decoded
|
||||
WordCount int // 0 if the server did not say
|
||||
}
|
||||
|
||||
// Client is a Kiwix HTTP client. Boring on purpose: no retries, no cache.
|
||||
type Client struct {
|
||||
base string
|
||||
http *http.Client
|
||||
}
|
||||
|
||||
// New makes a client for a Kiwix base URL like http://127.0.0.1:8034.
|
||||
func New(baseURL string) *Client {
|
||||
return &Client{
|
||||
base: strings.TrimRight(baseURL, "/"),
|
||||
http: &http.Client{Timeout: 10 * time.Second},
|
||||
}
|
||||
}
|
||||
|
||||
// Search runs a keyword search in one ZIM (book) and returns up to limit hits.
|
||||
//
|
||||
// Ranking is keyword based, not semantic: "Rayleigh scattering" finds the right
|
||||
// article, "why is the sky blue" finds a TV episode. Pass keywords, not questions.
|
||||
func (c *Client) Search(ctx context.Context, pattern, book string, limit int) ([]Result, error) {
|
||||
if limit <= 0 {
|
||||
limit = 5
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("pattern", pattern)
|
||||
q.Set("books.name", book)
|
||||
q.Set("format", "xml")
|
||||
q.Set("pageLength", strconv.Itoa(limit))
|
||||
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.base+"/search?"+q.Encode(), nil)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
resp, err := c.http.Do(req)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("kiwix search: http %d", resp.StatusCode)
|
||||
}
|
||||
return ParseSearchRSS(resp.Body)
|
||||
}
|
||||
|
||||
// rss mirrors just the bits of the RSS 2.0 reply we use.
|
||||
type rss struct {
|
||||
Items []struct {
|
||||
Title string `xml:"title"`
|
||||
Link string `xml:"link"`
|
||||
// innerxml keeps the <b> match markers so we can strip them ourselves.
|
||||
Description struct {
|
||||
Inner string `xml:",innerxml"`
|
||||
} `xml:"description"`
|
||||
WordCount string `xml:"wordCount"`
|
||||
} `xml:"channel>item"`
|
||||
}
|
||||
|
||||
var tagRE = regexp.MustCompile(`<[^>]*>`)
|
||||
|
||||
// ParseSearchRSS turns a Kiwix search reply into results. Exported so the parser
|
||||
// is testable from a captured response, with no server running.
|
||||
func ParseSearchRSS(r io.Reader) ([]Result, error) {
|
||||
var doc rss
|
||||
if err := xml.NewDecoder(r).Decode(&doc); err != nil {
|
||||
return nil, fmt.Errorf("kiwix search: bad xml: %w", err)
|
||||
}
|
||||
out := make([]Result, 0, len(doc.Items))
|
||||
for _, it := range doc.Items {
|
||||
n, _ := strconv.Atoi(strings.ReplaceAll(it.WordCount, ",", ""))
|
||||
out = append(out, Result{
|
||||
Title: strings.TrimSpace(it.Title),
|
||||
Path: strings.TrimSpace(it.Link),
|
||||
Snippet: plainText(it.Description.Inner),
|
||||
WordCount: n,
|
||||
})
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// plainText drops markup and decodes entities, leaving text a model can read.
|
||||
func plainText(s string) string {
|
||||
s = tagRE.ReplaceAllString(s, "")
|
||||
s = html.UnescapeString(s)
|
||||
return strings.TrimSpace(strings.Join(strings.Fields(s), " "))
|
||||
}
|
||||
@@ -1,90 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// A real reply from the live server, trimmed to two items.
|
||||
const sampleRSS = `<?xml version="1.0" encoding="UTF-8"?>
|
||||
<rss version="2.0" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
|
||||
<channel>
|
||||
<title>Search: Rayleigh scattering</title>
|
||||
<opensearch:totalResults>800</opensearch:totalResults>
|
||||
<item>
|
||||
<title>Rayleigh scattering</title>
|
||||
<link>/content/wikipedia_en_all_maxi_2026-02/Rayleigh_scattering</link>
|
||||
<description><b>Rayleigh</b> scattering causes the blue color of the sky & yellow colors near the Sun.[1]</description>
|
||||
<book><title>Wikipedia</title></book>
|
||||
<wordCount>2,818</wordCount>
|
||||
</item>
|
||||
<item>
|
||||
<title>Hyper–Rayleigh scattering</title>
|
||||
<link>/content/wikipedia_en_all_maxi_2026-02/Hyper%E2%80%93Rayleigh_scattering</link>
|
||||
<description>...<b>Rayleigh</b> scattering" is a nonlinear optical counterpart.</description>
|
||||
<book><title>Wikipedia</title></book>
|
||||
<wordCount>914</wordCount>
|
||||
</item>
|
||||
</channel>
|
||||
</rss>`
|
||||
|
||||
func TestParseSearchRSS(t *testing.T) {
|
||||
got, err := ParseSearchRSS(strings.NewReader(sampleRSS))
|
||||
if err != nil {
|
||||
t.Fatalf("parse: %v", err)
|
||||
}
|
||||
if len(got) != 2 {
|
||||
t.Fatalf("want 2 results, got %d", len(got))
|
||||
}
|
||||
if got[0].Title != "Rayleigh scattering" {
|
||||
t.Errorf("title = %q", got[0].Title)
|
||||
}
|
||||
if got[0].Path != "/content/wikipedia_en_all_maxi_2026-02/Rayleigh_scattering" {
|
||||
t.Errorf("path = %q", got[0].Path)
|
||||
}
|
||||
if got[0].WordCount != 2818 {
|
||||
t.Errorf("wordCount = %d", got[0].WordCount)
|
||||
}
|
||||
want := "Rayleigh scattering causes the blue color of the sky & yellow colors near the Sun.[1]"
|
||||
if got[0].Snippet != want {
|
||||
t.Errorf("snippet = %q, want %q", got[0].Snippet, want)
|
||||
}
|
||||
if strings.Contains(got[1].Snippet, "<b>") {
|
||||
t.Errorf("second snippet still has tags: %q", got[1].Snippet)
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseSearchRSSBadXML(t *testing.T) {
|
||||
if _, err := ParseSearchRSS(strings.NewReader("not xml at all")); err == nil {
|
||||
t.Fatal("want an error on junk input")
|
||||
}
|
||||
}
|
||||
|
||||
// Opt-in: needs a live Kiwix server. CI has none.
|
||||
// MAVEN_KIWIX_URL=http://127.0.0.1:8034 no_proxy=127.0.0.1,localhost go test -run Retrieval -v ./internal/kiwix/
|
||||
func TestRetrievalEval(t *testing.T) {
|
||||
base := os.Getenv("MAVEN_KIWIX_URL")
|
||||
if base == "" {
|
||||
t.Skip("set MAVEN_KIWIX_URL to run the retrieval eval")
|
||||
}
|
||||
noProxyLoopback(t)
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
|
||||
defer cancel()
|
||||
|
||||
rep, err := RunRetrievalEval(ctx, New(base), 5)
|
||||
if err != nil {
|
||||
t.Fatalf("eval: %v", err)
|
||||
}
|
||||
// No pass bar on purpose: the number is the finding.
|
||||
t.Log("\n" + rep.String() + rep.Detail())
|
||||
}
|
||||
|
||||
// noProxyLoopback stops the box's SOCKS bridge from eating loopback requests.
|
||||
func noProxyLoopback(t *testing.T) {
|
||||
t.Setenv("no_proxy", "127.0.0.1,localhost")
|
||||
t.Setenv("NO_PROXY", "127.0.0.1,localhost")
|
||||
}
|
||||
@@ -1,63 +0,0 @@
|
||||
{
|
||||
"name": "kiwix-knowledge-v1",
|
||||
"book": "wikipedia_en_all_maxi_2026-02",
|
||||
"note": "The 9 knowledge cases from internal/phraser/eval/talk_v1.json. Queries are hand-written English keywords on purpose: Kiwix ranks by keyword, not meaning, so a natural question fails. Writing them by hand separates 'retrieval is broken' from 'the model writes bad queries'.",
|
||||
"cases": [
|
||||
{
|
||||
"id": "know-sky-blue",
|
||||
"question": "почему небо синее?",
|
||||
"query": "Rayleigh scattering sky blue",
|
||||
"want_titles": ["Rayleigh scattering", "Diffuse sky radiation"]
|
||||
},
|
||||
{
|
||||
"id": "know-boil-egg",
|
||||
"question": "сколько варить яйцо вкрутую?",
|
||||
"query": "boiled egg cooking",
|
||||
"want_titles": ["Boiled egg", "Egg as food"]
|
||||
},
|
||||
{
|
||||
"id": "know-ssd-vs-hdd",
|
||||
"question": "чем ssd отличается от hdd?",
|
||||
"query": "solid-state drive",
|
||||
"want_titles": ["Solid-state drive", "Hard disk drive"]
|
||||
},
|
||||
{
|
||||
"id": "know-cat-purr",
|
||||
"question": "почему кошки мурчат?",
|
||||
"query": "cat purr",
|
||||
"want_titles": ["Purr", "Cat communication"]
|
||||
},
|
||||
{
|
||||
"id": "know-hiccups",
|
||||
"question": "как быстро избавиться от икоты?",
|
||||
"query": "hiccup",
|
||||
"want_titles": ["Hiccup"]
|
||||
},
|
||||
{
|
||||
"id": "know-polite-form",
|
||||
"question": "не могли бы вы объяснить, что такое vpn?",
|
||||
"query": "virtual private network",
|
||||
"want_titles": ["Virtual private network"]
|
||||
},
|
||||
{
|
||||
"id": "know-dont-know",
|
||||
"question": "как зовут моего соседа снизу?",
|
||||
"query": "name of my downstairs neighbour",
|
||||
"want_titles": [],
|
||||
"expect_miss": true,
|
||||
"note": "Unanswerable by design. Retrieval SHOULD find nothing useful. Counted as a hit only when nothing relevant comes back."
|
||||
},
|
||||
{
|
||||
"id": "know-water-per-day",
|
||||
"question": "сколько воды в день надо пить?",
|
||||
"query": "human daily water requirement drinking",
|
||||
"want_titles": ["Drinking water", "Water", "Dehydration", "Hydration"]
|
||||
},
|
||||
{
|
||||
"id": "know-thunder-delay",
|
||||
"question": "почему гром слышно позже молнии?",
|
||||
"query": "thunder speed of sound lightning",
|
||||
"want_titles": ["Thunder", "Lightning"]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,135 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
// This scores retrieval alone: no LLM. For each general-knowledge question we
|
||||
// hand-write English keywords and ask whether the article that would answer it
|
||||
// comes back in the top N hits. If this score is low, reading Wikipedia cannot
|
||||
// help the model no matter how good the prompt is.
|
||||
//
|
||||
// The unanswerable case (know-dont-know) is not scored. Whether the junk it
|
||||
// returns is "nothing useful" is a human judgement, so the report just prints
|
||||
// the titles and leaves the score to the 8 answerable cases.
|
||||
|
||||
import (
|
||||
"context"
|
||||
_ "embed"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
//go:embed knowledge_v1.json
|
||||
var knowledgeFixtureJSON []byte
|
||||
|
||||
// EvalCase — one question with hand-written keywords.
|
||||
type EvalCase struct {
|
||||
ID string `json:"id"`
|
||||
Question string `json:"question"`
|
||||
Query string `json:"query"`
|
||||
WantTitles []string `json:"want_titles"`
|
||||
ExpectMiss bool `json:"expect_miss"`
|
||||
}
|
||||
|
||||
type fixture struct {
|
||||
Name string `json:"name"`
|
||||
Book string `json:"book"`
|
||||
Cases []EvalCase `json:"cases"`
|
||||
}
|
||||
|
||||
// Outcome — what one case retrieved.
|
||||
type Outcome struct {
|
||||
Case EvalCase
|
||||
Titles []string // titles of the top N hits, in rank order
|
||||
Rank int // 1-based rank of the first wanted title, 0 if none
|
||||
Err error
|
||||
}
|
||||
|
||||
// Hit is true when a wanted title came back.
|
||||
func (o Outcome) Hit() bool { return o.Rank > 0 }
|
||||
|
||||
// Report — the score plus per-case detail.
|
||||
type Report struct {
|
||||
Name string
|
||||
Book string
|
||||
TopN int
|
||||
Scored int // answerable cases
|
||||
Hits int
|
||||
Errors int
|
||||
Outcomes []Outcome
|
||||
}
|
||||
|
||||
// Accuracy over the answerable cases.
|
||||
func (r Report) Accuracy() float64 {
|
||||
if r.Scored == 0 {
|
||||
return 0
|
||||
}
|
||||
return float64(r.Hits) / float64(r.Scored)
|
||||
}
|
||||
|
||||
// RunRetrievalEval searches for every fixture case.
|
||||
func RunRetrievalEval(ctx context.Context, c *Client, topN int) (Report, error) {
|
||||
var f fixture
|
||||
if err := json.Unmarshal(knowledgeFixtureJSON, &f); err != nil {
|
||||
return Report{}, err
|
||||
}
|
||||
rep := Report{Name: f.Name, Book: f.Book, TopN: topN}
|
||||
for _, cs := range f.Cases {
|
||||
res, err := c.Search(ctx, cs.Query, f.Book, topN)
|
||||
o := Outcome{Case: cs, Err: err}
|
||||
if err != nil {
|
||||
rep.Errors++
|
||||
}
|
||||
for i, hit := range res {
|
||||
o.Titles = append(o.Titles, hit.Title)
|
||||
if o.Rank == 0 && matches(cs.WantTitles, hit.Title) {
|
||||
o.Rank = i + 1
|
||||
}
|
||||
}
|
||||
if !cs.ExpectMiss {
|
||||
rep.Scored++
|
||||
if o.Hit() {
|
||||
rep.Hits++
|
||||
}
|
||||
}
|
||||
rep.Outcomes = append(rep.Outcomes, o)
|
||||
}
|
||||
return rep, nil
|
||||
}
|
||||
|
||||
func matches(want []string, title string) bool {
|
||||
for _, w := range want {
|
||||
if strings.EqualFold(strings.TrimSpace(title), w) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// String — the headline number.
|
||||
func (r Report) String() string {
|
||||
var b strings.Builder
|
||||
fmt.Fprintf(&b, "%s: %d/%d answerable questions retrieve a wanted article in top %d (%.1f%%), %d errors\n",
|
||||
r.Name, r.Hits, r.Scored, r.TopN, 100*r.Accuracy(), r.Errors)
|
||||
fmt.Fprintf(&b, " book: %s\n", r.Book)
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// Detail — per case: what was asked, what was searched, what came back.
|
||||
func (r Report) Detail() string {
|
||||
var b strings.Builder
|
||||
for _, o := range r.Outcomes {
|
||||
mark := "MISS"
|
||||
switch {
|
||||
case o.Case.ExpectMiss:
|
||||
mark = "n/a "
|
||||
case o.Hit():
|
||||
mark = fmt.Sprintf("hit@%d", o.Rank)
|
||||
}
|
||||
fmt.Fprintf(&b, " %-6s %-20s q=%q\n", mark, o.Case.ID, o.Case.Query)
|
||||
if o.Err != nil {
|
||||
fmt.Fprintf(&b, " error: %v\n", o.Err)
|
||||
continue
|
||||
}
|
||||
fmt.Fprintf(&b, " got: %s\n", strings.Join(o.Titles, " | "))
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
@@ -1,183 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
// Turning a Russian question into an English Kiwix search.
|
||||
//
|
||||
// Kiwix ranks by keyword, not by meaning. "why is the sky blue" returns a TV
|
||||
// episode; "Rayleigh scattering sky blue" returns the right article. So the
|
||||
// model's job here is NOT translation — it is naming the English article the
|
||||
// answer lives in.
|
||||
//
|
||||
// The output space is a handful of words, so it is worth locking down hard: a
|
||||
// GBNF grammar for the shape, a tiny token cap, and a cleanup pass that throws
|
||||
// away anything odd rather than handing junk to Kiwix.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"unicode"
|
||||
|
||||
"github.com/kami/maven/internal/llm"
|
||||
)
|
||||
|
||||
// Completer — the LLM seam, so tests can fake it. *llm.Client satisfies it.
|
||||
type Completer interface {
|
||||
Complete(ctx context.Context, r llm.Req) (string, error)
|
||||
}
|
||||
|
||||
// queryGrammar — one JSON object holding 1..6 keyword words. Latin letters,
|
||||
// digits and hyphens only, so the model physically cannot answer the question
|
||||
// or reply in Russian.
|
||||
//
|
||||
// Why the JSON wrapper: this model always thinks out loud and this llama-server
|
||||
// build ignores the thinking switch (see ROUTING-EVAL-31-07-2026.md). A bare
|
||||
// word-list grammar just captured the reasoning — every case came back as
|
||||
// "Let me analyze this request carefully". Demanding JSON, like routeGrammar and
|
||||
// responseGrammar already do, gives the reasoning nowhere to go.
|
||||
const queryGrammar = `
|
||||
root ::= "{" ws "\"query\"" ws ":" ws "\"" word (" " word){0,5} "\"" ws "}"
|
||||
word ::= [A-Za-z0-9] [A-Za-z0-9-]{0,23}
|
||||
ws ::= [ \t\n]*
|
||||
`
|
||||
|
||||
// rewriteSystem — asks for search keywords, not an answer and not a translation.
|
||||
const rewriteSystem = `You turn a question into a search query for English Wikipedia.
|
||||
|
||||
Rules:
|
||||
- Output ONLY English search keywords. Never an answer, never an explanation.
|
||||
- Do NOT translate the sentence. Name the thing the answer is about.
|
||||
- The output must be a noun phrase, like a Wikipedia article title.
|
||||
- Never use question words: no why, how, what, when, which, "how much",
|
||||
"how long", "how to", "vs", "reason", "difference".
|
||||
- 2 to 4 words.
|
||||
|
||||
Reply with JSON: {"query":"<keywords>"}
|
||||
|
||||
Good:
|
||||
"почему листья желтеют осенью?" -> {"query":"leaf senescence autumn"}
|
||||
"как работает микроволновка?" -> {"query":"microwave oven"}
|
||||
"не могли бы вы объяснить, что такое блокчейн?" -> {"query":"blockchain"}
|
||||
"сколько живут собаки?" -> {"query":"dog lifespan"}
|
||||
"как избавиться от комаров в квартире?" -> {"query":"mosquito control"}
|
||||
"чем чай отличается от кофе?" -> {"query":"tea"}
|
||||
|
||||
Only JSON, no explanation.`
|
||||
|
||||
// maxQueryTokens — the output is a few words plus the JSON wrapper. A tight cap
|
||||
// is the cheapest guard against the model rambling into an answer.
|
||||
const maxQueryTokens = 32
|
||||
|
||||
// Rewriter asks the resident model for English search keywords.
|
||||
type Rewriter struct{ c Completer }
|
||||
|
||||
func NewRewriter(c Completer) *Rewriter { return &Rewriter{c: c} }
|
||||
|
||||
// Rewrite returns English keywords for a question in any language.
|
||||
// It errors rather than returning something Kiwix should not see.
|
||||
func (r *Rewriter) Rewrite(ctx context.Context, question string) (string, error) {
|
||||
raw, err := r.c.Complete(ctx, llm.Req{
|
||||
System: rewriteSystem,
|
||||
User: strings.TrimSpace(question),
|
||||
Grammar: queryGrammar,
|
||||
MaxTokens: maxQueryTokens,
|
||||
RepeatPenalty: 1.15,
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return CleanQuery(unwrapJSON(raw))
|
||||
}
|
||||
|
||||
// unwrapJSON pulls the query out of {"query":"..."}. If the reply is not that
|
||||
// shape it is returned as-is, and CleanQuery decides whether it is usable.
|
||||
func unwrapJSON(raw string) string {
|
||||
s := strings.TrimSpace(raw)
|
||||
if !strings.HasPrefix(s, "{") {
|
||||
return s
|
||||
}
|
||||
var got struct{ Query string }
|
||||
if err := json.Unmarshal([]byte(s), &got); err != nil {
|
||||
return s
|
||||
}
|
||||
return got.Query
|
||||
}
|
||||
|
||||
// maxQueryWords matches the grammar's bound. Anything longer is prose.
|
||||
const maxQueryWords = 6
|
||||
|
||||
// CleanQuery checks and tidies whatever the model produced. The grammar makes
|
||||
// bad output unlikely, not impossible (a server without grammar support, a
|
||||
// different model), so this is the real gate in front of Kiwix.
|
||||
//
|
||||
// Exported so it can be tested without a model.
|
||||
func CleanQuery(raw string) (string, error) {
|
||||
s := strings.TrimSpace(raw)
|
||||
// Models like to wrap answers in quotes. Drop surrounding ones.
|
||||
s = strings.Trim(s, "\"'`")
|
||||
// Keep the first line only: everything after it is prose.
|
||||
if i := strings.IndexAny(s, "\r\n"); i >= 0 {
|
||||
s = s[:i]
|
||||
}
|
||||
// Keep letters, digits, spaces and hyphens; anything else becomes a space.
|
||||
var b strings.Builder
|
||||
for _, ru := range s {
|
||||
switch {
|
||||
case unicode.IsLetter(ru) || unicode.IsDigit(ru) || ru == '-':
|
||||
b.WriteRune(ru)
|
||||
default:
|
||||
b.WriteRune(' ')
|
||||
}
|
||||
}
|
||||
words := strings.Fields(b.String())
|
||||
if len(words) == 0 {
|
||||
return "", fmt.Errorf("kiwix rewrite: empty query")
|
||||
}
|
||||
if len(words) > maxQueryWords {
|
||||
return "", fmt.Errorf("kiwix rewrite: %d words, want at most %d (looks like prose)", len(words), maxQueryWords)
|
||||
}
|
||||
words = dropStopWords(words)
|
||||
out := strings.Join(words, " ")
|
||||
// The ZIMs are English. Non-Latin letters mean the model ignored the ask.
|
||||
for _, ru := range out {
|
||||
if unicode.IsLetter(ru) && !isLatin(ru) {
|
||||
return "", fmt.Errorf("kiwix rewrite: query is not English: %q", out)
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// stopWords — question words and filler. The model keeps writing question-shaped
|
||||
// queries ("why is the sky blue", "how much water to drink daily") no matter how
|
||||
// the prompt is worded, and Kiwix ranks on every word, so those words drag in
|
||||
// song and episode titles. Dropping them in code is not a style preference: a
|
||||
// keyword ranker gets nothing from them.
|
||||
var stopWords = map[string]bool{
|
||||
"a": true, "an": true, "the": true, "is": true, "are": true, "was": true,
|
||||
"do": true, "does": true, "did": true, "to": true, "of": true, "in": true,
|
||||
"on": true, "for": true, "and": true, "or": true, "my": true, "me": true,
|
||||
"i": true, "it": true, "its": true, "be": true, "been": true, "get": true,
|
||||
"how": true, "why": true, "what": true, "when": true, "which": true,
|
||||
"who": true, "where": true, "much": true, "many": true, "long": true,
|
||||
"vs": true, "than": true, "rid": true, "from": true, "about": true,
|
||||
}
|
||||
|
||||
// dropStopWords removes filler, but never everything: if the query was nothing
|
||||
// but stop words there is nothing better to search, so the original is kept and
|
||||
// the caller sees whatever Kiwix makes of it.
|
||||
func dropStopWords(words []string) []string {
|
||||
kept := make([]string, 0, len(words))
|
||||
for _, w := range words {
|
||||
if !stopWords[strings.ToLower(w)] {
|
||||
kept = append(kept, w)
|
||||
}
|
||||
}
|
||||
if len(kept) == 0 {
|
||||
return words
|
||||
}
|
||||
return kept
|
||||
}
|
||||
|
||||
func isLatin(ru rune) bool {
|
||||
return (ru >= 'a' && ru <= 'z') || (ru >= 'A' && ru <= 'Z')
|
||||
}
|
||||
@@ -1,96 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
// End-to-end score: Russian question -> model rewrite -> Kiwix search -> did a
|
||||
// wanted article come back. Same 9 cases as the retrieval eval, so the two
|
||||
// numbers are directly comparable: retrieval with hand-written keywords is the
|
||||
// ceiling, this is what the model actually reaches.
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// RewriteOutcome — one case, end to end.
|
||||
type RewriteOutcome struct {
|
||||
Outcome
|
||||
ModelQuery string // what the model asked for ("" if it failed)
|
||||
RewriteErr error
|
||||
}
|
||||
|
||||
// RunRewriteEval rewrites every question with the model, then searches.
|
||||
func RunRewriteEval(ctx context.Context, c *Client, rw *Rewriter, topN int) (RewriteReport, error) {
|
||||
var f fixture
|
||||
if err := json.Unmarshal(knowledgeFixtureJSON, &f); err != nil {
|
||||
return RewriteReport{}, err
|
||||
}
|
||||
rep := RewriteReport{Report: Report{Name: f.Name + "-rewrite", Book: f.Book, TopN: topN}}
|
||||
for _, cs := range f.Cases {
|
||||
out := RewriteOutcome{Outcome: Outcome{Case: cs}}
|
||||
q, err := rw.Rewrite(ctx, cs.Question)
|
||||
out.ModelQuery, out.RewriteErr = q, err
|
||||
if err == nil {
|
||||
res, serr := c.Search(ctx, q, f.Book, topN)
|
||||
out.Err = serr
|
||||
for i, hit := range res {
|
||||
out.Titles = append(out.Titles, hit.Title)
|
||||
if out.Rank == 0 && matches(cs.WantTitles, hit.Title) {
|
||||
out.Rank = i + 1
|
||||
}
|
||||
}
|
||||
}
|
||||
if out.RewriteErr != nil || out.Err != nil {
|
||||
rep.Errors++
|
||||
}
|
||||
if !cs.ExpectMiss {
|
||||
rep.Scored++
|
||||
if out.Hit() {
|
||||
rep.Hits++
|
||||
}
|
||||
}
|
||||
rep.Cases = append(rep.Cases, out)
|
||||
}
|
||||
return rep, nil
|
||||
}
|
||||
|
||||
// RewriteReport — the score plus per-case detail.
|
||||
type RewriteReport struct {
|
||||
Report
|
||||
Cases []RewriteOutcome
|
||||
}
|
||||
|
||||
// String — the headline number.
|
||||
func (r RewriteReport) String() string {
|
||||
return fmt.Sprintf("%s: %d/%d answerable questions retrieve a wanted article in top %d (%.1f%%), %d errors\n book: %s\n",
|
||||
r.Name, r.Hits, r.Scored, r.TopN, 100*r.Accuracy(), r.Errors, r.Book)
|
||||
}
|
||||
|
||||
// Detail — per case: hand-written query next to the model's, and what came back.
|
||||
// The point is seeing WHERE the model's phrasing differs, not just the score.
|
||||
func (r RewriteReport) Detail() string {
|
||||
var b strings.Builder
|
||||
for _, o := range r.Cases {
|
||||
mark := "MISS"
|
||||
switch {
|
||||
case o.Case.ExpectMiss:
|
||||
mark = "n/a "
|
||||
case o.Hit():
|
||||
mark = fmt.Sprintf("hit@%d", o.Rank)
|
||||
}
|
||||
fmt.Fprintf(&b, " %-6s %-20s\n", mark, o.Case.ID)
|
||||
fmt.Fprintf(&b, " asked: %s\n", o.Case.Question)
|
||||
fmt.Fprintf(&b, " hand: %q\n", o.Case.Query)
|
||||
fmt.Fprintf(&b, " model: %q\n", o.ModelQuery)
|
||||
if o.RewriteErr != nil {
|
||||
fmt.Fprintf(&b, " rewrite rejected: %v\n", o.RewriteErr)
|
||||
continue
|
||||
}
|
||||
if o.Err != nil {
|
||||
fmt.Fprintf(&b, " search error: %v\n", o.Err)
|
||||
continue
|
||||
}
|
||||
fmt.Fprintf(&b, " got: %s\n", strings.Join(o.Titles, " | "))
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
@@ -1,33 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/kami/maven/internal/llm"
|
||||
)
|
||||
|
||||
// Opt-in: needs a live Kiwix server AND a live llama-server.
|
||||
// MAVEN_KIWIX_URL=http://127.0.0.1:8034 MAVEN_LLM_URL=http://127.0.0.1:18099 \
|
||||
//
|
||||
// no_proxy=127.0.0.1,localhost go test -run RewriteEval -v ./internal/kiwix/
|
||||
func TestRewriteEval(t *testing.T) {
|
||||
kbase, lbase := os.Getenv("MAVEN_KIWIX_URL"), os.Getenv("MAVEN_LLM_URL")
|
||||
if kbase == "" || lbase == "" {
|
||||
t.Skip("set MAVEN_KIWIX_URL and MAVEN_LLM_URL to run the rewrite eval")
|
||||
}
|
||||
noProxyLoopback(t)
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
|
||||
defer cancel()
|
||||
|
||||
rw := NewRewriter(llm.New(lbase, 3*time.Minute))
|
||||
rep, err := RunRewriteEval(ctx, New(kbase), rw, 5)
|
||||
if err != nil {
|
||||
t.Fatalf("eval: %v", err)
|
||||
}
|
||||
// No pass bar on purpose: the number is the finding.
|
||||
t.Log("\n" + rep.String() + rep.Detail())
|
||||
}
|
||||
@@ -1,105 +0,0 @@
|
||||
package kiwix
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
|
||||
"github.com/kami/maven/internal/llm"
|
||||
)
|
||||
|
||||
// Bad model output must never reach Kiwix. No model needed for this.
|
||||
func TestCleanQueryRejectsJunk(t *testing.T) {
|
||||
bad := []struct{ name, raw string }{
|
||||
{"empty", ""},
|
||||
{"blank", " \n "},
|
||||
{"russian came back", "почему небо синее"},
|
||||
{"mixed russian", "sky синее scattering"},
|
||||
{"full sentence", "The sky looks blue because of the scattering of sunlight by air molecules"},
|
||||
{"prose with quotes", `Sure! Here is a good search query: "Rayleigh scattering", which explains it.`},
|
||||
}
|
||||
for _, c := range bad {
|
||||
if got, err := CleanQuery(c.raw); err == nil {
|
||||
t.Errorf("%s: want rejection, got %q", c.name, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestCleanQueryCleans(t *testing.T) {
|
||||
ok := []struct{ raw, want string }{
|
||||
{"Rayleigh scattering sky", "Rayleigh scattering sky"},
|
||||
{" boiled egg cooking \n", "boiled egg cooking"},
|
||||
{`"virtual private network"`, "virtual private network"},
|
||||
{"solid-state drive", "solid-state drive"},
|
||||
{"cat purr.", "cat purr"},
|
||||
{"hiccup\nAlso: hiccough", "hiccup"},
|
||||
// Question words are filler to a keyword ranker, so they go.
|
||||
{"why is the sky blue", "sky blue"},
|
||||
{"how much water to drink daily", "water drink daily"},
|
||||
{"SSD vs HDD comparison", "SSD HDD comparison"},
|
||||
// Nothing but filler: keep it rather than return nothing.
|
||||
{"what is it", "what is it"},
|
||||
}
|
||||
for _, c := range ok {
|
||||
got, err := CleanQuery(c.raw)
|
||||
if err != nil {
|
||||
t.Errorf("%q: %v", c.raw, err)
|
||||
continue
|
||||
}
|
||||
if got != c.want {
|
||||
t.Errorf("%q -> %q, want %q", c.raw, got, c.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
type fakeCompleter struct {
|
||||
out string
|
||||
req llm.Req
|
||||
}
|
||||
|
||||
func (f *fakeCompleter) Complete(_ context.Context, r llm.Req) (string, error) {
|
||||
f.req = r
|
||||
return f.out, nil
|
||||
}
|
||||
|
||||
func TestRewriteConstrainsTheCall(t *testing.T) {
|
||||
f := &fakeCompleter{out: `{"query":"Rayleigh scattering sky"}`}
|
||||
got, err := NewRewriter(f).Rewrite(context.Background(), "почему небо синее?")
|
||||
if err != nil {
|
||||
t.Fatalf("rewrite: %v", err)
|
||||
}
|
||||
if got != "Rayleigh scattering sky" {
|
||||
t.Errorf("query = %q", got)
|
||||
}
|
||||
if f.req.Grammar == "" {
|
||||
t.Error("no grammar sent")
|
||||
}
|
||||
if f.req.MaxTokens == 0 || f.req.MaxTokens > 32 {
|
||||
t.Errorf("max_tokens = %d, want a small cap", f.req.MaxTokens)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRewriteRejectsBadModelOutput(t *testing.T) {
|
||||
bad := []string{
|
||||
`{"query":"почему небо синее"}`, // never translated
|
||||
`{"query":""}`, // empty
|
||||
`{"query":"the sky is blue because sunlight is scattered by air"}`, // an answer
|
||||
// Note: a SHORT English prose fragment ("Let me analyze this request")
|
||||
// is under the word cap and cannot be caught here. The grammar is what
|
||||
// stops that one.
|
||||
}
|
||||
for _, out := range bad {
|
||||
f := &fakeCompleter{out: out}
|
||||
if got, err := NewRewriter(f).Rewrite(context.Background(), "почему небо синее?"); err == nil {
|
||||
t.Errorf("%s: want rejection, got %q", out, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A reply that is not the JSON shape but is still usable keywords should pass.
|
||||
func TestRewriteFallsBackToPlainText(t *testing.T) {
|
||||
f := &fakeCompleter{out: "Rayleigh scattering sky"}
|
||||
got, err := NewRewriter(f).Rewrite(context.Background(), "почему небо синее?")
|
||||
if err != nil || got != "Rayleigh scattering sky" {
|
||||
t.Errorf("got %q, %v", got, err)
|
||||
}
|
||||
}
|
||||
@@ -1,33 +0,0 @@
|
||||
package eval
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestAddressReportsEveryBreak — the real reply from a nudge eval run broke in
|
||||
// two ways at once and the check named only the plural. Both must print: a
|
||||
// half-reported failure reads as a milder problem than it is.
|
||||
func TestAddressReportsEveryBreak(t *testing.T) {
|
||||
body := "Смотрите на его потребление воды."
|
||||
res := checkAddress(body)
|
||||
if res.Pass {
|
||||
t.Fatalf("checkAddress passed %q", body)
|
||||
}
|
||||
for _, want := range []string{"смотрите", "его"} {
|
||||
if !strings.Contains(res.Detail, want) {
|
||||
t.Errorf("detail %q does not name %q", res.Detail, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// One word repeated is one problem, so the detail must not say it twice.
|
||||
func TestAddressDeduplicates(t *testing.T) {
|
||||
res := checkAddress("Вам стоит поесть, вам это нужно.")
|
||||
if res.Pass {
|
||||
t.Fatal("expected failure")
|
||||
}
|
||||
if n := strings.Count(res.Detail, "formal"); n != 1 {
|
||||
t.Errorf("detail repeats the same break %d times: %q", n, res.Detail)
|
||||
}
|
||||
}
|
||||
@@ -434,26 +434,14 @@ func looksVerb(w string) bool {
|
||||
func checkAddress(body string) Result {
|
||||
words := addressWordRE.FindAllString(strings.ToLower(body), -1)
|
||||
|
||||
// Every break, not just the first. A bad reply usually breaks in more than
|
||||
// one way at once — "Смотрите на его потребление воды" is a plural imperative
|
||||
// AND third person about him — and reporting only the first hid the second,
|
||||
// which made the failure look milder than it was.
|
||||
var breaks []string
|
||||
seen := map[string]bool{}
|
||||
add := func(msg string) {
|
||||
if seen[msg] {
|
||||
return // the same word twice in one message is one problem, not two
|
||||
}
|
||||
seen[msg] = true
|
||||
breaks = append(breaks, msg)
|
||||
}
|
||||
|
||||
for i, w := range words {
|
||||
if formalPronouns[w] {
|
||||
add(fmt.Sprintf("formal %q — she says ты/тебя/тебе", w))
|
||||
return Result{CheckAddress, false,
|
||||
fmt.Sprintf("formal %q — she says ты/тебя/тебе", w)}
|
||||
}
|
||||
if pluralVerb(w) && !(i > 0 && prepositions[words[i-1]]) {
|
||||
add(fmt.Sprintf("plural imperative %q — she uses the singular", w))
|
||||
return Result{CheckAddress, false,
|
||||
fmt.Sprintf("plural imperative %q — she uses the singular", w)}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -467,26 +455,17 @@ func checkAddress(body string) Result {
|
||||
if !unicode.Is(unicode.Cyrillic, []rune(p)[0]) && !isLatinWord(p) {
|
||||
continue // punctuation
|
||||
}
|
||||
// pluralVerb as well as looksVerb: looksVerb knows the imperative in
|
||||
// -й/-йте but not the -те plural ("смотрите"), so "Смотрите на его
|
||||
// потребление воды" counted "смотрите" as the person being talked
|
||||
// about and the "его" never printed. Third time a verb form has
|
||||
// blinded this check — if a fourth turns up, the antecedent test
|
||||
// wants a real morphology table, not another suffix.
|
||||
if notAnAntecedent[p] || prepositions[p] || thirdPersonHim[p] || looksVerb(p) || pluralVerb(p) {
|
||||
if notAnAntecedent[p] || prepositions[p] || thirdPersonHim[p] || looksVerb(p) {
|
||||
continue
|
||||
}
|
||||
named = true
|
||||
break
|
||||
}
|
||||
if !named {
|
||||
add(fmt.Sprintf("third person %q with nobody else named — she talks to him, not about him", w))
|
||||
return Result{CheckAddress, false,
|
||||
fmt.Sprintf("third person %q with nobody else named — she talks to him, not about him", w)}
|
||||
}
|
||||
}
|
||||
|
||||
if len(breaks) > 0 {
|
||||
return Result{CheckAddress, false, strings.Join(breaks, " + ")}
|
||||
}
|
||||
return Result{CheckAddress, true, ""}
|
||||
}
|
||||
|
||||
|
||||
@@ -132,19 +132,10 @@ func TestLLMTalkBaseline(t *testing.T) {
|
||||
p := phraser.NewLLMPhraserAt(base, cfg)
|
||||
defer p.Close()
|
||||
|
||||
// Unreachable server is fatal here, not a logged warning, and that differs
|
||||
// from the nudge test on purpose. PhraseNudge returns its errors, so a dead
|
||||
// server there shows up honestly in the Errors column. PhraseChat and
|
||||
// PhraseQuery do NOT: they swallow every failure and return a canned string
|
||||
// ("поговорили.", "не знаю.", "вот что я нашла: …"). So on these three paths
|
||||
// a dead server produces a full report with 0 errors and a terrible score —
|
||||
// a number that looks like bad phrasing and is really no phrasing at all.
|
||||
// Refusing to score without a confirmed model is the only guard available
|
||||
// until the phraser reports its failures (Vikunja #397).
|
||||
model, err := llm.ModelID(ctx, base)
|
||||
if err != nil {
|
||||
t.Fatalf("no model at %s: %v — refusing to score, these paths hide their errors "+
|
||||
"and would report a plausible-looking result off a dead server", base, err)
|
||||
t.Logf("could not read model id from %s: %v — report will say %q", base, err, llm.UnknownModel)
|
||||
model = llm.UnknownModel
|
||||
}
|
||||
t.Logf("scoring model %s at %s", model, base)
|
||||
|
||||
@@ -154,10 +145,7 @@ func TestLLMTalkBaseline(t *testing.T) {
|
||||
}
|
||||
t.Log("\n" + rep.String() + "\nreplies:\n" + rep.Replies() + "\nfailures:\n" + rep.Failures())
|
||||
|
||||
// And again afterwards: the run takes minutes, and a server that died or got
|
||||
// OOM-killed halfway through would leave the first cases scored and the rest
|
||||
// silently canned. Checking only at the start would not catch that.
|
||||
if _, err := llm.ModelID(ctx, base); err != nil {
|
||||
t.Fatalf("model at %s went away during the run: %v — the score above is not trustworthy", base, err)
|
||||
if rep.Errors == rep.Total {
|
||||
t.Errorf("all %d cases errored — harness fault, not a measurement", rep.Total)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -7,7 +7,6 @@
|
||||
"The owner is a man, addressed informally as ty, living alone with a home server. Every utterance is written the way he actually talks to her.",
|
||||
"chat-formality-bait and chat-about-me exist to provoke the two persona breaks the nudge eval caught: the formal vy/vas plural, and talking about him in the third person.",
|
||||
"want_any fragments are stems so Russian declension does not defeat the on-topic check. They are lowercased before comparison.",
|
||||
"want_any is a plain substring test, so a fragment that is too short passes by accident: \"ты\" matches inside \"работы\", \"нет\" inside \"интернет\". Keep every fragment to three or more letters of a real stem.",
|
||||
"Notes are written as the store would have them: short, first person, no punctuation discipline."
|
||||
],
|
||||
"cases": [
|
||||
@@ -31,7 +30,7 @@
|
||||
"id": "chat-about-me",
|
||||
"path": "chat",
|
||||
"utterance": "расскажи обо мне",
|
||||
"want_any": ["теб"],
|
||||
"want_any": ["ты", "тебя", "теб"],
|
||||
"tags": ["persona-bait", "third-person"],
|
||||
"note": "Baits the third person: she should say 'ты живёшь один', not 'он живёт один', as if reporting to somebody else."
|
||||
},
|
||||
@@ -119,7 +118,7 @@
|
||||
"path": "query",
|
||||
"utterance": "сколько я заплатил за домен?",
|
||||
"notes": ["домен продлевается в марте", "хостинг оплачен на год вперёд"],
|
||||
"want_any": ["домен", "не зна", "не указ"],
|
||||
"want_any": ["домен", "не зна", "не указ", "нет"],
|
||||
"tags": ["notes", "negative"],
|
||||
"note": "The notes do not contain the price. The prompt tells her to say so; a made-up number is the failure being watched for."
|
||||
},
|
||||
@@ -204,7 +203,7 @@
|
||||
"id": "know-dont-know",
|
||||
"path": "knowledge",
|
||||
"utterance": "как зовут моего соседа снизу?",
|
||||
"want_any": ["не зна", "не мог"],
|
||||
"want_any": ["не зна", "не мог", "нет"],
|
||||
"tags": ["general", "negative"],
|
||||
"note": "Unanswerable without notes. Admitting it beats inventing a name; watching for the invention."
|
||||
},
|
||||
|
||||
@@ -1,124 +0,0 @@
|
||||
package phraser
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/kami/maven/internal/loop"
|
||||
)
|
||||
|
||||
// grammarSpy stands in for llama-server: it records the grammar field of every
|
||||
// request and always answers with a contract-shaped reply.
|
||||
type grammarSpy struct {
|
||||
srv *httptest.Server
|
||||
grammars []string
|
||||
}
|
||||
|
||||
func newGrammarSpy(t *testing.T) *grammarSpy {
|
||||
t.Helper()
|
||||
s := &grammarSpy{}
|
||||
s.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
var req chatReq
|
||||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||||
t.Errorf("spy: decode request: %v", err)
|
||||
}
|
||||
s.grammars = append(s.grammars, req.Grammar)
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.Write([]byte(`{"choices":[{"message":{"content":"{\"response\": \"ага\", \"mood\": \"neutral\"}"}}]}`))
|
||||
}))
|
||||
t.Cleanup(s.srv.Close)
|
||||
return s
|
||||
}
|
||||
|
||||
// callAllPhrasingPaths hits every path that expects the JSON contract.
|
||||
func callAllPhrasingPaths(t *testing.T, p *LLMPhraser) {
|
||||
t.Helper()
|
||||
ctx := context.Background()
|
||||
if _, err := p.PhraseNudge(ctx, loop.Candidate{Rule: loop.WaterRule(), Severity: loop.Sev1}); err != nil {
|
||||
t.Fatalf("PhraseNudge: %v", err)
|
||||
}
|
||||
if _, err := p.PhraseChat(ctx, "привет", nil); err != nil {
|
||||
t.Fatalf("PhraseChat: %v", err)
|
||||
}
|
||||
// Both branches: no notes (general knowledge) and with notes (grounded).
|
||||
if _, err := p.PhraseQuery(ctx, "сколько воды я выпил", nil); err != nil {
|
||||
t.Fatalf("PhraseQuery (no notes): %v", err)
|
||||
}
|
||||
if _, err := p.PhraseQuery(ctx, "сколько воды я выпил", []string{"два литра"}); err != nil {
|
||||
t.Fatalf("PhraseQuery (notes): %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestGrammarIsAttachedToEveryPhrasingRequest(t *testing.T) {
|
||||
if strings.TrimSpace(responseGrammar) == "" {
|
||||
t.Fatal("responseGrammar is empty")
|
||||
}
|
||||
spy := newGrammarSpy(t)
|
||||
p := NewLLMPhraserAt(spy.srv.URL, Config{})
|
||||
|
||||
callAllPhrasingPaths(t, p)
|
||||
|
||||
if len(spy.grammars) != 4 {
|
||||
t.Fatalf("expected 4 requests, got %d", len(spy.grammars))
|
||||
}
|
||||
for i, g := range spy.grammars {
|
||||
if g != responseGrammar {
|
||||
t.Errorf("request %d carries grammar %q, want responseGrammar", i, g)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestNoGrammarConfigDisablesIt(t *testing.T) {
|
||||
spy := newGrammarSpy(t)
|
||||
p := NewLLMPhraserAt(spy.srv.URL, Config{NoGrammar: true})
|
||||
|
||||
callAllPhrasingPaths(t, p)
|
||||
|
||||
for i, g := range spy.grammars {
|
||||
if g != "" {
|
||||
t.Errorf("request %d still carries a grammar with NoGrammar set: %q", i, g)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The grammar's string rule must accept any codepoint, not just ASCII. Replies
|
||||
// are Russian: an ASCII-only class would constrain the model into empty replies.
|
||||
func TestGrammarStringRuleIsNotASCIIOnly(t *testing.T) {
|
||||
if !strings.Contains(responseGrammar, `([^"\\] | "\\" ["\\/bfnrt])`) {
|
||||
t.Error("string rule is not the any-codepoint-except-quote-and-backslash class; Cyrillic replies would be impossible")
|
||||
}
|
||||
}
|
||||
|
||||
// What the grammar describes must survive the parser that reads it back — a
|
||||
// Russian body with an escaped quote inside, hand-built to test the contract.
|
||||
func TestGrammarShapedJSONParses(t *testing.T) {
|
||||
raw := `{"response": "он сказал \"привет\" и ушёл.\nвот так.", "mood": "confused"}`
|
||||
text, mood := parseResponseMood(raw)
|
||||
if want := "он сказал \"привет\" и ушёл.\nвот так."; text != want {
|
||||
t.Errorf("response = %q, want %q", text, want)
|
||||
}
|
||||
if mood != "confused" {
|
||||
t.Errorf("mood = %q, want confused", mood)
|
||||
}
|
||||
}
|
||||
|
||||
// Every mood the grammar permits is one the contract knows, and all five are there.
|
||||
func TestGrammarMoodEnumMatchesTheContract(t *testing.T) {
|
||||
for _, m := range []string{"neutral", "happy", "thinking", "tired", "confused"} {
|
||||
if !strings.Contains(responseGrammar, `"\"`+m+`\""`) {
|
||||
t.Errorf("mood %q missing from the grammar", m)
|
||||
}
|
||||
}
|
||||
// No sixth mood: the enum line lists exactly five alternatives.
|
||||
for _, line := range strings.Split(responseGrammar, "\n") {
|
||||
if strings.HasPrefix(line, "mood") {
|
||||
if n := strings.Count(line, "|") + 1; n != 5 {
|
||||
t.Errorf("mood rule lists %d alternatives, want 5: %s", n, line)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -45,13 +45,6 @@ type Config struct {
|
||||
// address him, the time) fresh for each turn. See internal/persona.
|
||||
// nil ⇒ no block, the prompts stand alone.
|
||||
ContextBlock func() string
|
||||
|
||||
// NoGrammar turns the GBNF constraint off (zero value ⇒ grammar ON).
|
||||
// The escape hatch exists because the target resident model — the
|
||||
// locally CPT'd Qwen3-1.7B — does not exist yet: if its chat template
|
||||
// ever fights the grammar, the fix should be a config flip on the
|
||||
// deploy box, not a code change and a rebuild.
|
||||
NoGrammar bool
|
||||
}
|
||||
|
||||
func DefaultConfig(modelPath string) Config {
|
||||
@@ -297,7 +290,6 @@ func (p *LLMPhraser) chatWithMessages(ctx context.Context, msgs []chatMsg, maxTo
|
||||
Messages: msgs,
|
||||
Temperature: 0.7,
|
||||
MaxTokens: maxTokens,
|
||||
Grammar: p.grammar(),
|
||||
}
|
||||
body, err := json.Marshal(req)
|
||||
if err != nil {
|
||||
@@ -377,37 +369,6 @@ type chatReq struct {
|
||||
Messages []chatMsg `json:"messages"`
|
||||
Temperature float64 `json:"temperature"`
|
||||
MaxTokens int `json:"max_tokens"`
|
||||
// Grammar is llama-server's `grammar` field (GBNF). Same wiring as
|
||||
// internal/llm.Req.Grammar. Empty ⇒ unconstrained sampling.
|
||||
Grammar string `json:"grammar,omitempty"`
|
||||
}
|
||||
|
||||
// responseGrammar — GBNF constraining the model to the documented phrasing
|
||||
// contract and nothing else: {"response": "<text>", "mood": "<enum>"}.
|
||||
//
|
||||
// Without it a 0.8B answers roughly one chat turn in three with open reasoning
|
||||
// as plain text ("Thinking Process:" …), which no tag-stripper can remove and
|
||||
// which eats the token budget before the JSON closes. Modelled on
|
||||
// routeGrammar in internal/router/llmrouter.go so the two read alike.
|
||||
//
|
||||
// text accepts ANY codepoint except the two JSON must escape — the replies are
|
||||
// Russian, so an ASCII-only rule would make every reply empty. The escape rule
|
||||
// is what lets the model close a string it opened with a quote inside. Length
|
||||
// is bounded so a repetition loop truncates the field, not the JSON object.
|
||||
const responseGrammar = `
|
||||
root ::= "{" ws "\"response\"" ws ":" ws string ws "," ws "\"mood\"" ws ":" ws mood ws "}"
|
||||
mood ::= "\"neutral\"" | "\"happy\"" | "\"thinking\"" | "\"tired\"" | "\"confused\""
|
||||
string ::= "\"" ([^"\\] | "\\" ["\\/bfnrt]){0,400} "\""
|
||||
ws ::= [ \t\n]*
|
||||
`
|
||||
|
||||
// grammar returns the GBNF to attach to a phrasing request, or "" when the
|
||||
// operator turned it off.
|
||||
func (p *LLMPhraser) grammar() string {
|
||||
if p.cfg.NoGrammar {
|
||||
return ""
|
||||
}
|
||||
return responseGrammar
|
||||
}
|
||||
|
||||
type chatResp struct {
|
||||
@@ -432,7 +393,6 @@ func (p *LLMPhraser) chatWithSystem(ctx context.Context, system, user string, ma
|
||||
},
|
||||
Temperature: 0.7,
|
||||
MaxTokens: maxTokens,
|
||||
Grammar: p.grammar(),
|
||||
}
|
||||
body, err := json.Marshal(req)
|
||||
if err != nil {
|
||||
|
||||
Reference in New Issue
Block a user