From 8c7923513e6b11680c1ea06e33c3a580f8c604d4 Mon Sep 17 00:00:00 2001 From: alkhatibdev Date: Tue, 10 Nov 2026 13:28:20 +0400 Subject: [PATCH] feat: the Settings page says whether searches use the search questions Signed-off-by: alkhatibdev --- dashboard/src/api/schema.d.ts | 49 ++++++++++++ dashboard/src/i18n/en.ts | 20 ++++- dashboard/src/lib/governance.test.ts | 21 +++++ dashboard/src/lib/governance.ts | 13 +++- dashboard/src/pages/Settings.test.tsx | 47 ++++++++++++ dashboard/src/pages/Settings.tsx | 36 +++++++++ dashboard/src/test/fixtures.ts | 23 ++++++ docs/api-changelog.md | 4 + docs/openapi.json | 76 +++++++++++++++++++ packages/dpolens/src/dpolens/api/instance.py | 50 +++++++++++- .../src/dpolens/engine/search/questions.py | 9 ++- tests/integration/test_laws_api.py | 61 ++++++++++++++- 12 files changed, 401 insertions(+), 8 deletions(-) diff --git a/dashboard/src/api/schema.d.ts b/dashboard/src/api/schema.d.ts index 582389d..68dc123 100644 --- a/dashboard/src/api/schema.d.ts +++ b/dashboard/src/api/schema.d.ts @@ -1716,6 +1716,7 @@ export interface components { questions_log: components["schemas"]["QuestionsLogSettings"]; sign_in: components["schemas"]["SignInSettings"]; assistants: components["schemas"]["AssistantSettings"]; + search_questions: components["schemas"]["SearchQuestionsSettings"]; /** * Ai Provider * @description The service an answer is written with. Null: none is used, search runs on this instance's own model, and nothing anybody asks is sent elsewhere @@ -2604,6 +2605,54 @@ export interface components { */ effective_date: string; }; + /** SearchQuestionsLaw */ + SearchQuestionsLaw: { + /** + * Law + * @description The law's slug + */ + law: string; + /** + * Short Name + * @description What people call the law, in English + */ + short_name: string; + /** + * Questions + * @description How many questions the law's file holds + */ + questions: number; + /** + * Current + * @description How many sit beside the words they were written for, and so are used. The rest wait to be written again for words that have changed + */ + current: number; + /** + * Written By + * @description The models that wrote them + */ + written_by: string; + /** + * Checked By + * @description The models that checked them + */ + checked_by: string; + /** + * Written On + * Format: date + */ + written_on: string; + }; + /** SearchQuestionsSettings */ + SearchQuestionsSettings: { + /** + * On + * @description Whether searches use the search questions, which only reorder the clauses a search found and are never returned. Changed with `dpolens search-questions on` or `off`, which the governance log records + */ + on: boolean; + /** Laws */ + laws: components["schemas"]["SearchQuestionsLaw"][]; + }; /** SearchRequest */ SearchRequest: { /** diff --git a/dashboard/src/i18n/en.ts b/dashboard/src/i18n/en.ts index afcfc2c..470be09 100644 --- a/dashboard/src/i18n/en.ts +++ b/dashboard/src/i18n/en.ts @@ -746,6 +746,11 @@ export const en = { update: "Loaded {{pack}} {{version}}, downloaded from {{repository}} on GitHub", file: "Loaded {{pack}} {{version}}, imported from a file", }, + search_questions_loaded_one: "Loaded {{number}} search question for {{pack}}, written {{date}}", + search_questions_loaded_other: + "Loaded {{number}} search questions for {{pack}}, written {{date}}", + search_questions_on: "Turned the search questions on", + search_questions_off: "Turned the search questions off", document_drafted: "Uploaded {{file}}, a draft of {{policy}}", document_flag_accepted_one: "Accepted {{count}} flag in the draft of {{policy}}", document_flag_accepted_other: "Accepted {{count}} flags in the draft of {{policy}}", @@ -1201,7 +1206,7 @@ export const en = { settings: { title: "Settings", subtitle: - "How this instance is set up. These are fixed when it starts, so changing one means a restart.", + "How this instance is set up. Most are fixed when it starts, so changing one means a restart.", howTo: "How to change them", questionsLog: "Questions log", keptFor: "Kept for", @@ -1237,6 +1242,19 @@ export const en = { runsOn: "Search runs on", ownModel: "This instance, on its own model", nothingSent: "Nothing a person asks or reads here is sent to another service.", + searchQuestions: "Search questions", + searchQuestionsNote: + "Questions a model wrote beside each clause of a law, and another checked. They only reorder the clauses a search found, and are never shown. The command dpolens search-questions off turns them off, and the governance log records it.", + inSearches: "In searches", + used: "Used", + turnedOff: "Turned off", + questionsFor_one: "{{number}} question, written {{date}}", + questionsFor_other: "{{number}} questions, written {{date}}", + questionsStale_one: "{{number}} question, {{current}} current, written {{date}}", + questionsStale_other: "{{number}} questions, {{current}} of them current, written {{date}}", + writtenBy: "Written by", + checkedBy: "Checked by", + noQuestions: "No law has them loaded", instance: "This instance", version: "Version", id: "Instance ID", diff --git a/dashboard/src/lib/governance.test.ts b/dashboard/src/lib/governance.test.ts index 25f01f2..d361341 100644 --- a/dashboard/src/lib/governance.test.ts +++ b/dashboard/src/lib/governance.test.ts @@ -118,3 +118,24 @@ describe("a law's entries in the governance log", () => { ).toBe("Loaded GDPR 2026.1"); }); }); + +describe("the search questions' entries in the governance log", () => { + it("say how many were loaded for which law, and when they were written", () => { + expect( + sentence("search_questions.loaded", { + pack: "uae-pdpl", + questions: 1081, + written_on: "2026-11-07", + }), + ).toBe("Loaded 1,081 search questions for UAE PDPL, written 7 November 2026"); + }); + + it("say which way they were turned", () => { + expect(sentence("search_questions.switched", { before: true, after: false })).toBe( + "Turned the search questions off", + ); + expect(sentence("search_questions.switched", { before: false, after: true })).toBe( + "Turned the search questions on", + ); + }); +}); diff --git a/dashboard/src/lib/governance.ts b/dashboard/src/lib/governance.ts index 1c53463..5595da9 100644 --- a/dashboard/src/lib/governance.ts +++ b/dashboard/src/lib/governance.ts @@ -1,7 +1,7 @@ import type { TFunction } from "i18next"; import type { Entry } from "@/api/client"; -import { formatDate } from "@/lib/format"; +import { formatDate, formatNumber } from "@/lib/format"; import { wordsFor } from "@/lib/permissionWords"; type Details = Record; @@ -125,6 +125,17 @@ export function describeEntry(t: TFunction, entry: Entry): string { } case "laws.selection_cleared": return t("entries.laws_selection_cleared"); + case "search_questions.loaded": { + const count = Number(details.questions ?? 0); + return t("entries.search_questions_loaded", { + count, + number: formatNumber(count), + pack: law(details.pack ?? entry.target_id), + date: formatDate(text(details.written_on)), + }); + } + case "search_questions.switched": + return t(details.after ? "entries.search_questions_on" : "entries.search_questions_off"); case "document.drafted": return t("entries.document_drafted", { file: text(details.file), policy: policy(details) }); case "document.flag_accepted": diff --git a/dashboard/src/pages/Settings.test.tsx b/dashboard/src/pages/Settings.test.tsx index 644c31f..c880b20 100644 --- a/dashboard/src/pages/Settings.test.tsx +++ b/dashboard/src/pages/Settings.test.tsx @@ -42,6 +42,53 @@ describe("settings", () => { ); }); + it("says whether searches use the search questions, and which laws have them", async () => { + serve({ + "GET /v1/sessions/current": { body: admin }, + "GET /v1/settings": { body: settings }, + "GET /v1/governance/verification": { body: intact }, + }); + renderAt("/settings"); + + expect(await screen.findByText("Used")).toBeInTheDocument(); + expect(screen.getByText("4,573 questions, written 7 November 2026")).toBeInTheDocument(); + expect(screen.getByText("1,081 questions, written 7 November 2026")).toBeInTheDocument(); + // Two laws by the same models name each model once. + expect(screen.getByText("claude-sonnet-5-5")).toBeInTheDocument(); + expect(screen.getByText("claude-opus-5-5")).toBeInTheDocument(); + }); + + it("says when the search questions are turned off, or some wait to be written again", async () => { + const [gdpr, uae] = settings.search_questions.laws; + serve({ + "GET /v1/sessions/current": { body: admin }, + "GET /v1/settings": { + body: { + ...settings, + search_questions: { on: false, laws: [gdpr, { ...uae, current: 1000 }] }, + }, + }, + "GET /v1/governance/verification": { body: intact }, + }); + renderAt("/settings"); + + expect(await screen.findByText("Turned off")).toBeInTheDocument(); + expect( + screen.getByText("1,081 questions, 1,000 of them current, written 7 November 2026"), + ).toBeInTheDocument(); + }); + + it("says so when no law has search questions", async () => { + serve({ + "GET /v1/sessions/current": { body: admin }, + "GET /v1/settings": { body: { ...settings, search_questions: { on: true, laws: [] } } }, + "GET /v1/governance/verification": { body: intact }, + }); + renderAt("/settings"); + + expect(await screen.findByText("No law has them loaded")).toBeInTheDocument(); + }); + it("says how long a question is kept when a retention is set", async () => { serve({ "GET /v1/sessions/current": { body: admin }, diff --git a/dashboard/src/pages/Settings.tsx b/dashboard/src/pages/Settings.tsx index 675b72d..7779f52 100644 --- a/dashboard/src/pages/Settings.tsx +++ b/dashboard/src/pages/Settings.tsx @@ -36,6 +36,11 @@ function Group({ title, note, children }: { title: string; note?: string; childr ); } +/** Each model once, though several laws may name it. */ +function unique(names: string[]): string { + return [...new Set(names.flatMap((name) => name.split(", ")))].join(", "); +} + function CopyUrl({ value }: { value: string }) { const { t } = useTranslation(); const [copied, setCopied] = useState(false); @@ -158,6 +163,37 @@ export function SettingsPage() { {t("settings.ownModel")} + + + {settings.data.search_questions.on ? t("settings.used") : t("settings.turnedOff")} + + {settings.data.search_questions.laws.map((law) => ( + + {t( + law.current < law.questions ? "settings.questionsStale" : "settings.questionsFor", + { + count: law.questions, + number: formatNumber(law.questions), + current: formatNumber(law.current), + date: formatDate(law.written_on), + }, + )} + + ))} + {settings.data.search_questions.laws.length ? ( + <> + + {unique(settings.data.search_questions.laws.map((law) => law.written_by))} + + + {unique(settings.data.search_questions.laws.map((law) => law.checked_by))} + + + ) : ( + {t("settings.noQuestions")} + )} + + {settings.data.instance.version} diff --git a/dashboard/src/test/fixtures.ts b/dashboard/src/test/fixtures.ts index 6574671..33b85ec 100644 --- a/dashboard/src/test/fixtures.ts +++ b/dashboard/src/test/fixtures.ts @@ -484,6 +484,29 @@ export const settings: InstanceSettings = { wrong_password_window_minutes: 15, }, assistants: { mcp_url: "https://dpolens.example.com/mcp", requests_per_minute: 60 }, + search_questions: { + on: true, + laws: [ + { + law: "gdpr", + short_name: "GDPR", + questions: 4573, + current: 4573, + written_by: "claude-sonnet-5-5", + checked_by: "claude-opus-5-5", + written_on: "2026-11-07", + }, + { + law: "uae-pdpl", + short_name: "UAE PDPL", + questions: 1081, + current: 1081, + written_by: "claude-sonnet-5-5", + checked_by: "claude-opus-5-5", + written_on: "2026-11-07", + }, + ], + }, ai_provider: null, instance: { version: "0.1.0", diff --git a/docs/api-changelog.md b/docs/api-changelog.md index aaa315d..a49b200 100644 --- a/docs/api-changelog.md +++ b/docs/api-changelog.md @@ -32,6 +32,10 @@ breaking change needs a new major version. search, and still read by key - `coming` holds the words an amendment gives a clause from a later day, with that day and the amendment, when one does +- `GET /v1/settings` carries `search_questions`: whether searches use the search + questions, and for each law that has them how many it holds, how many are current, + which models wrote and checked them, and when. They are turned on and off with + `dpolens search-questions`, not through the API ## 0.2.0 diff --git a/docs/openapi.json b/docs/openapi.json index db835c5..6777701 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -8822,6 +8822,9 @@ "assistants": { "$ref": "#/components/schemas/AssistantSettings" }, + "search_questions": { + "$ref": "#/components/schemas/SearchQuestionsSettings" + }, "ai_provider": { "anyOf": [ { @@ -8843,6 +8846,7 @@ "questions_log", "sign_in", "assistants", + "search_questions", "ai_provider", "instance" ], @@ -10865,6 +10869,78 @@ ], "title": "ScheduledVersion" }, + "SearchQuestionsLaw": { + "properties": { + "law": { + "type": "string", + "title": "Law", + "description": "The law's slug" + }, + "short_name": { + "type": "string", + "title": "Short Name", + "description": "What people call the law, in English" + }, + "questions": { + "type": "integer", + "title": "Questions", + "description": "How many questions the law's file holds" + }, + "current": { + "type": "integer", + "title": "Current", + "description": "How many sit beside the words they were written for, and so are used. The rest wait to be written again for words that have changed" + }, + "written_by": { + "type": "string", + "title": "Written By", + "description": "The models that wrote them" + }, + "checked_by": { + "type": "string", + "title": "Checked By", + "description": "The models that checked them" + }, + "written_on": { + "type": "string", + "format": "date", + "title": "Written On" + } + }, + "type": "object", + "required": [ + "law", + "short_name", + "questions", + "current", + "written_by", + "checked_by", + "written_on" + ], + "title": "SearchQuestionsLaw" + }, + "SearchQuestionsSettings": { + "properties": { + "on": { + "type": "boolean", + "title": "On", + "description": "Whether searches use the search questions, which only reorder the clauses a search found and are never returned. Changed with `dpolens search-questions on` or `off`, which the governance log records" + }, + "laws": { + "items": { + "$ref": "#/components/schemas/SearchQuestionsLaw" + }, + "type": "array", + "title": "Laws" + } + }, + "type": "object", + "required": [ + "on", + "laws" + ], + "title": "SearchQuestionsSettings" + }, "SearchRequest": { "properties": { "query": { diff --git a/packages/dpolens/src/dpolens/api/instance.py b/packages/dpolens/src/dpolens/api/instance.py index 13d0625..c7d5b95 100644 --- a/packages/dpolens/src/dpolens/api/instance.py +++ b/packages/dpolens/src/dpolens/api/instance.py @@ -3,13 +3,14 @@ The MCP server's URL is a setting rather than something the dashboard works out, because behind a proxy or on another port nothing on the page can know it. -The settings are read here and changed nowhere: each is fixed when the instance -starts, so changing one is a change to its environment and a restart. +The settings are read here and changed nowhere. Most are fixed when the instance starts, so +changing one is a change to its environment and a restart. Whether searches use the search +questions is changed with `dpolens search-questions`, which the governance log records. """ from __future__ import annotations -from datetime import datetime +from datetime import date, datetime from typing import Annotated from fastapi import APIRouter, Depends @@ -23,6 +24,7 @@ from dpolens.engine.auth.tokens import Authenticated from dpolens.engine.instance import this_instance from dpolens.engine.logs.redaction import BUILT_IN +from dpolens.engine.search.questions import loaded_files, questions_on router = APIRouter(prefix="/v1", tags=["instance"], responses=problems.responses(401, 403, 429)) @@ -71,6 +73,32 @@ class AssistantSettings(BaseModel): ) +class SearchQuestionsLaw(BaseModel): + law: str = Field(description="The law's slug") + short_name: str = Field(description="What people call the law, in English") + questions: int = Field(description="How many questions the law's file holds") + current: int = Field( + description=( + "How many sit beside the words they were written for, and so are used. The rest " + "wait to be written again for words that have changed" + ) + ) + written_by: str = Field(description="The models that wrote them") + checked_by: str = Field(description="The models that checked them") + written_on: date + + +class SearchQuestionsSettings(BaseModel): + on: bool = Field( + description=( + "Whether searches use the search questions, which only reorder the clauses a " + "search found and are never returned. Changed with `dpolens search-questions on` " + "or `off`, which the governance log records" + ) + ) + laws: list[SearchQuestionsLaw] + + class InstanceFacts(BaseModel): version: str id: str @@ -81,6 +109,7 @@ class InstanceSettings(BaseModel): questions_log: QuestionsLogSettings sign_in: SignInSettings assistants: AssistantSettings + search_questions: SearchQuestionsSettings ai_provider: str | None = Field( description=( "The service an answer is written with. Null: none is used, search runs on " @@ -110,6 +139,21 @@ def read_settings(who: SettingsReader, settings: Configured, opened: Opened) -> mcp_url=settings.public_mcp_url, requests_per_minute=settings.rate_limit_per_minute, ), + search_questions=SearchQuestionsSettings( + on=questions_on(opened), + laws=[ + SearchQuestionsLaw( + law=file.pack, + short_name=file.short_name, + questions=file.questions, + current=file.current, + written_by=file.written_by, + checked_by=file.checked_by, + written_on=file.written_on, + ) + for file in loaded_files(opened) + ], + ), ai_provider=None, instance=InstanceFacts(version=__version__, id=str(row.id), created_at=row.created_at), ) diff --git a/packages/dpolens/src/dpolens/engine/search/questions.py b/packages/dpolens/src/dpolens/engine/search/questions.py index 6d47d41..ac82104 100644 --- a/packages/dpolens/src/dpolens/engine/search/questions.py +++ b/packages/dpolens/src/dpolens/engine/search/questions.py @@ -145,6 +145,7 @@ def load_questions(session: Session, path: Path, *, actor: Actor) -> Loaded: target_type="pack", target_id=slug, details={ + "pack": slug, "questions": len(rows), "current": current, "written_by": _named(data["written_by"]), @@ -322,6 +323,8 @@ class QuestionFile: """A law's questions as loaded: how many, how many still current, and who wrote them.""" pack: str + short_name: str + """What people call the law, in English, which is the interface's language.""" questions: int current: int written_by: str @@ -333,6 +336,7 @@ def loaded_files(session: Session) -> list[QuestionFile]: return [ QuestionFile( pack=row.slug, + short_name=row.short_name, questions=int(row.questions), current=int(row.current), written_by=row.written_by, @@ -342,12 +346,13 @@ def loaded_files(session: Session) -> list[QuestionFile]: for row in session.execute( text( """ - SELECT p.slug, f.written_by, f.checked_by, f.written_on, + SELECT p.slug, n.short_name, f.written_by, f.checked_by, f.written_on, count(q.id) AS questions, count(q.id) FILTER (WHERE q.current) AS current FROM search_question_files f JOIN packs p ON p.id = f.pack_id + JOIN pack_names n ON n.pack_id = p.id AND n.lang = 'en' LEFT JOIN search_questions q ON q.pack_id = f.pack_id - GROUP BY p.slug, f.written_by, f.checked_by, f.written_on + GROUP BY p.slug, n.short_name, f.written_by, f.checked_by, f.written_on ORDER BY p.slug """ ) diff --git a/tests/integration/test_laws_api.py b/tests/integration/test_laws_api.py index fb0589a..35b7edd 100644 --- a/tests/integration/test_laws_api.py +++ b/tests/integration/test_laws_api.py @@ -11,8 +11,9 @@ from pathlib import Path import pytest +import yaml from fastapi.testclient import TestClient -from sqlalchemy import Engine, create_engine, select +from sqlalchemy import Engine, create_engine, select, text from dpolens.api.app import create_app from dpolens.engine.auth import permissions as catalog @@ -23,6 +24,11 @@ from dpolens.engine.logs.governance import LAWS_SELECTED, Actor from dpolens.engine.logs.models import GovernanceEntry from dpolens.engine.packs.load import load_pack +from dpolens.engine.search.questions import ( + current_fingerprints, + load_questions, + switch_questions, +) from dpolens.engine.session import session_from from dpolens.settings import Settings @@ -205,10 +211,63 @@ def test_says_how_the_instance_is_set_up( "requests_per_minute": 60, } assert body["ai_provider"] is None + assert body["search_questions"] == {"on": True, "laws": []} with session_from(own[1]) as opened: row = opened.scalars(select(Instance)).one() assert body["instance"]["id"] == str(row.id) + def test_say_whether_searches_use_the_search_questions_and_which_laws_have_them( + self, app_client: TestClient, own: tuple[str, Engine], tmp_path: Path + ) -> None: + owner = own[1] + key = "testlaw:art-6:para-1" + with session_from(owner) as opened: + written_for = current_fingerprints(opened, [key])[key] + file = tmp_path / "testlaw.yaml" + file.write_text( + yaml.safe_dump( + { + "pack": "testlaw", + "written_by": ["a writer"], + "checked_by": ["a checker"], + "written_on": "2026-11-08", + "write_prompt": "0" * 16, + "check_prompt": "1" * 16, + "clauses": [ + {"key": key, "text": written_for, "en": ["Is consent enough?"], "ar": []}, + {"key": "testlaw:art-5", "text": "f" * 16, "en": ["Must we erase?"]}, + ], + } + ), + encoding="utf-8", + ) + with session_from(owner) as opened: + load_questions(opened, file, actor=ACTOR) + switch_questions(opened, False, actor=ACTOR) + try: + response = signed_in(app_client, DPO).get("/v1/settings", headers=SAME_ORIGIN) + + assert response.status_code == 200, response.text + assert response.json()["search_questions"] == { + "on": False, + "laws": [ + { + "law": "testlaw", + "short_name": "TESTLAW", + "questions": 2, + # The second was written for words the clause no longer holds. + "current": 1, + "written_by": "a writer", + "checked_by": "a checker", + "written_on": "2026-11-08", + } + ], + } + finally: + with session_from(owner) as opened: + switch_questions(opened, True, actor=ACTOR) + opened.execute(text("DELETE FROM search_question_files")) + def test_reading_them_needs_the_permission_to_change_them(self, app_client: TestClient) -> None: response = signed_in(app_client, DEVELOPER).get("/v1/settings", headers=SAME_ORIGIN)