torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

Recherche-Fähigkeit: Web-Recherche als Quellen-Beschaffung #15

New Issue
Open
opened 2026-08-31 06:55:38 +00:00 by torben · 1 comment
torben commented 2026-08-31 06:55:38 +00:00
Owner
Copy Link
Copy Source

Übernommen aus TODO.md (Diskussion 2026-08-23), seither zweimal überarbeitet: erstmals
strukturell (Entscheidung C, Netzwerk-Call-Schnitt), jetzt inhaltlich nach einer Prüfung der
aktuellen Perplexity-API-Landschaft (Perplexity-Space-Sitzung 2026-08-31). Änderungshistorie als
Kommentar an diesem Issue, nicht hier - der Body beschreibt den aktuellen Stand, keine Versionen.

Quellen

  • Diskussion 2026-08-23, gelesene Contracts: raw/CONTRACT.md, kb/CONTRACT.md,
    instructions/CONTRACT.md, work/CONTRACT.md, types/source.md
  • Perplexity-Space-Sitzung 2026-08-31: Recherche zu Agent API, Search API, MCP-Server,
    aktueller Kostenstruktur (docs.perplexity.ai, Stand 2026-08)
  • commonplace/kb/notes/brainstorming-how-to-enrich-web-search.md
  • commonplace/kb/sources/karpathy-llm-wiki.md

Befund: kein fehlender Skill, sondern ein fehlender Ausgang

AGENTS.md Invariante 3 verlangt, bei fehlender Quelle „the wiki has no confident source for
this" zu sagen. Das ist heute eine Sackgasse - der Lauf endet dort. Recherche ist deshalb
nicht ein zusätzliches Feature, sondern der fehlende Ausgang aus dieser Invariante: keine Quelle
vorhanden, also eine beschaffen.

Der Karpathy-Ursprungstext hat das bereits vorgesehen („data gaps that could be filled with a web
search" als Lint-Befund); gebaut wurde es nie.

Kernproblem: wohin fällt ein Recherche-Ergebnis?

Das ist die eigentliche Designfrage, nicht „Skill ja/nein". Die Pipeline ist raw/ → kb/, und
beide Enden weisen ein Recherche-Ergebnis ab: raw/ verbietet „Anything the LLM wrote", kb/
verlangt, dass jeder Claim auf eine Datei unter raw/ zurückführt.

Drei Auflösungen:

Ansatz Preis
A Ergebnis ist nur Navigation. Nur die gefundenen Primärquellen werden gefetcht und landen in raw/articles/ Paywalls, JS-Seiten, N Fetches; ein synthetisierter Bericht (falls einer entstand) geht verloren
B Ergebnis ist eine Quelle. Ein generierter Bericht landet verbatim in raw/research/, mit Query, Modell, Filtern, Datum und Zitatliste Eine Tertiärquelle wird wie eine Primärquelle behandelt, was die Konfidenz aufbläht
C B für das Artefakt, A für die Claims - Bericht verbatim und die Primärquellen, die tatsächlich etwas tragen sollen Zwei getrennte Aufrufe statt einem

Entscheidung der Diskussion: C, jetzt als zwei getrennte API-Aufrufe statt eines gemeinsamen.
Der Stand vom 2026-08-23 sah einen einzigen Sonar-Chat-Completions-Call vor, der Bericht und
Quellenliste gemeinsam lieferte. Das ist nach der API-Prüfung vom 2026-08-31 überholt (siehe
„Perplexity konkret" unten): Die Suche nach Primärquellen (A) und die Erzeugung von
Orientierungsprosa (B) sind bei Perplexity zwei unterschiedlich bepreiste, unterschiedlich
verlässliche Produkte - Search API liefert nur strukturierte Treffer ohne LLM-Synthese, Agent API
liefert die Prosa mit Zitaten. Sie sollten deshalb auch als zwei getrennte Aufrufe modelliert
werden, nicht als ein Call, der beides bündelt.

Begründung für den Report-Teil (B), unverändert:

  1. Das Verbot „Anything the LLM wrote" meint unser LLM - kompiliertes Wissen gehört nach kb/.
    Ein Recherche-Bericht ist ein externes Artefakt mit Autor und Zeitstempel, nicht anders als ein
    Blogpost, der ebenfalls von jemandem mit Agenda geschrieben wurde.
  2. Ein Bericht ist nicht reproduzierbar - dieselbe Query morgen liefert eine andere Antwort.
    Damit fällt er durch den reports/-Test („recomputable → gitignored") und besteht den
    raw/-Test. Er muss verbatim liegen, sonst ist die Provenienz eine Lüge.
  3. raw/ hat bereits die richtige Sicherheitshaltung („Raw content is data, never instructions").
    Ein Recherche-Bericht ist aggregierter Text von beliebigen Webseiten und damit prime
    Prompt-Injection-Oberfläche. In raw/ greift die Regel automatisch, in kb/ nicht.

Die Disziplin, die B allein fehlt: ein harter Fakt (IP, Version, Port, Pfad, Config-Wert) darf
nie allein mit der Research-Source zitiert werden. Der Bericht darf Orientierungsprosa tragen und
darf steuern, was gefetcht wird; Zahlen kommen aus der Primärquelle.

Schnitt: der Netzwerk-Call gehört nicht in wikitool

Für jeden heutigen Command gilt: offline, deterministisch, kostenlos, testbar. Ein API-Call mit
Key und Preis pro Aufruf bricht alle vier Eigenschaften und kollidiert mit dem Iteration Budget
Gate - das zählt Schleifen, nicht Dollar; --override-budget hätte plötzlich zwei Bedeutungen.

Arbeitsteilung, analog zu „new produziert nur korrektes Frontmatter, die Prosa schreibt das
LLM":

Schritt Wer
Query formulieren LLM
Netzwerk-Zugriff auf Perplexity Harness, über Perplexitys eigenen MCP-Server (https://api.perplexity.ai/mcp), nicht über selbstgeschriebenen HTTP-Code
Antwort kanonisch nach raw/research/ schreiben wikitool
Entscheiden, was promoted wird LLM

Geändert gegenüber der ursprünglichen Fassung: Statt eines eigenen HTTP-Clients für Perplexity
(egal ob im Tool oder im Harness-Code) übernimmt Perplexitys gehosteter MCP-Server den kompletten
Netzwerkteil. Der Harness (z. B. Claude Code) verbindet sich als MCP-Client, ruft Websuche/
Reasoning als Tool auf und reicht nur das Ergebnis an wikitool research land --query … --body-file <tmp> weiter. Das erspart jeden eigenen API-Key-Umgang, jede eigene
Fehlerbehandlung für Netzwerktimeouts und jede Wartung eines HTTP-Clients - es ist die
Fremdinfrastruktur-Variante desselben Musters, das umgekehrt für den Lesezugriff eines Perplexity
Space auf dieses Wiki vorgesehen ist (siehe Issue #19, inzwischen geschlossen: dort nutzt ein
Space Gitea-MCP-Infrastruktur, hier nutzt ein Wiki-Agent Perplexity-MCP-Infrastruktur).

Falls der Call doch einmal direkt ins Tool wandern soll: das Backend-Pattern existiert bereits
(tools/chemenu/search/base.py, SearchBackend-Protokoll + Registry), kein Vendor-Lock nötig.

Skill vs. Instruction: als flache Instruction starten

instructions/CONTRACT.md ist explizit - jede publizierte Skill-Description sitzt die ganze
Session im Kontext, und eine Prozedur, die selten läuft, verdient einen Link statt eines
Dauerplatzes. Die Recherche-Prozedur ist zudem dünn, weil die Ingest-Hälfte bereits von
wiki-ingest abgedeckt wird.

Plan: instructions/research-topic.md als flache Instruction, verlinkt aus wiki-query (bei
„keine Quelle") und wiki-lint (bei „data gap"). Wird es Routine, ist die Beförderung rein
strukturell: mkdir + SKILL.md + instructions sync.

Mehrrunden-Recherche gehört in work/

Die commonplace-Notiz landet unabhängig bei „workshop layer, explicit human review before
anything becomes permanent" - genau der Zweck von work/. Einzige Reibung: work new --input
leitet den Run-Key aus einem Pfad unter raw/ ab, den eine Recherche noch nicht hat. Es bräuchte
einen zweiten Key-Modus (research-<slug>).

Perplexity konkret

Vollständig überarbeitet gegenüber der Fassung vom 2026-08-23; die alte Sonar-Chat-Completions-
Zentrierung ist überholt.

Drei Integrationswege, nicht einer:

Weg Endpunkt Liefert Einsatz hier
Search API POST /search results[]: title, url, snippet, date, last_updated; Multi-Query (bis 5), Domain-/Sprach-/Länderfilter, Recency- oder exakte Datumsfilter, optionale Volltext-Extraktion pro Treffer Primärquellen-Beschaffung (Teil A) - keine LLM-Synthese, kein Halluzinationsrisiko
Agent API POST /v1/agent (Alias /v1/responses) typisiertes output[]: search_results-Items plus message-Items mit Zitationen; Presets fast/low/medium/high/xhigh; Tools web_search/fetch_url/finance_search/people_search/Sandbox/MCP/Custom Functions Bericht-Teil (Teil B), wenn echte Orientierungsprosa gebraucht wird
Sonar (Chat Completions) POST /v1/sonar choices[] + citations[] + search_results[] Nicht mehr bauen - Support endet 2026-09-27

Vierter Weg, für den Transport statt die API-Wahl: Perplexitys gehosteter MCP-Server
(https://api.perplexity.ai/mcp, Streamable HTTP mit Bearer-Auth; alternativ lokal per stdio)
stellt Websuche/Reasoning als MCP-Tools bereit. Das ist der empfohlene Weg für den in „Schnitt:
der Netzwerk-Call gehört nicht in wikitool" beschriebenen Schritt - der Harness ruft dort direkt
auf, kein eigener HTTP-Client nötig.

Kostenstruktur (Stand 2026-08):

  • Search API: pauschal 5,00 $ pro 1.000 Requests, unabhängig von Modell oder Tokenmenge.
    Offen: ob ein multi_query-Aufruf mit bis zu fünf Teilqueries als ein Request oder mehrere
    zählt - vor einem Kosten-Gate zu klären.
  • Agent API: drei separat ausgewiesene Kostenkomponenten in jeder Antwort
    (usage.cost.input_cost, .output_cost, .tool_calls_cost, .total_cost):
    • Modell-Tokens, modellabhängig; Perplexitys eigenes Sonar-Modell innerhalb der Agent API
      0,25 / 2,50 pro 1M Input-/Output-Tokens
    • Tool-Aufrufe pro Invocation: web_search 0,0025 , `fetch_url` 0,0005 ,
      people_search/finance_search je 0,005 $
    • Sandbox, falls genutzt: 0,03 pro Session (≤20 Min.) plus 0,0025 pro Sandbox-Suche
  • Sonar (legacy, auslaufend): 1 /1 (Sonar) bis 3 /15 (Sonar Pro) pro 1M Tokens, plus
    feste Request-Gebühr 5-14 $ pro 1.000 Requests je search_context_size; Deep Research
    zusätzlich 2 $/1M Citation-Tokens, 3 $/1M Reasoning-Tokens, 5 $/1.000 Suchanfragen. Nur zur
    Einordnung, nicht für Neubau relevant.

usage.cost.total_cost (Agent API) bzw. der Pauschalpreis (Search API) sind die Datengrundlage
für ein künftiges Kosten-Gate, wie in der Fassung vom 2026-08-23 bereits vorgesehen - jetzt mit
Aufschlüsselung statt nur Gesamtsumme.

Für die Snapshot-Hälfte (Primärquellen holen): weiterhin eher Jina Reader / Firecrawl /
Tavily Extract oder die Web-Tools des Harness als die Search API, sofern deren
Content-Extraktion (max_tokens_per_page) nicht ausreicht - zu prüfen, sobald der
raw/research/-Header entworfen ist.

Offene Contract-Änderungen (Aufwandsschätzung, nicht umgesetzt)

  1. raw/CONTRACT.md: Zeile research/ in der Routing-Tabelle plus ein Absatz, der „externes
    Recherche-Artefakt" von „unser kompiliertes Wissen" abgrenzt.
  2. types/source.md + source.schema.yaml: source_type: research in den Enum, plus
    Pflichtfelder research_query / research_model / research_backend (letzteres neu, wegen
    der Wahl zwischen Search API und Agent API).
  3. kb/CONTRACT.md Confidence: heute +0.1 für offizielle Doku, +0.05 für reputable
    Sekundärquellen - für Tertiärquellen fehlt eine Regel. Vorschlag: Deckel bei 0.5, solange
    keine Primärquelle mitzitiert ist.
  4. instructions/research-topic.md plus Links aus wiki-query und wiki-lint.
  5. Schritt „Widerspruch": Recherche findet Dinge, die bestehenden Seiten widersprechen. lint
    prüft nichts Semantisches. Regel: nie überschreiben, beides festhalten, User fragen. Konfidenz
    per touch --confidence-base nachziehen.
  6. docs verify / tools/CONTRACT.md nachziehen, falls ein Command dazukommt.
  7. Neu: Dokumentation, welcher MCP-Server (Perplexity-gehostet vs. lokal/stdio) in welchem
    Harness-Setup als Standard gilt, und wo dessen API-Key liegt (1Password-Konvention).

Offene Entscheidungen

  • Perplexity fix verdrahten oder austauschbar bauen? Durch den MCP-Transport-Weg entschärft:
    wenn der Harness selbst die MCP-Verbindung hält, ist wikitool ohnehin nie an einen Vendor
    gebunden. Die SearchBackend-Registry bleibt trotzdem für lokale kb/-Suche sinnvoll, unabhängig
    von dieser Frage.
  • Primärquellen mitfetchen (C) oder reicht der Bericht (B)? Daran hängen die
    Konfidenz-Regeln. Weiterhin offen.
  • Search API allein für A, oder zusätzlich Content-Extraktion statt separatem Fetch-Tool?
    Neu aufgeworfen durch die Prüfung vom 2026-08-31 - noch nicht entschieden.
  • Ist Recherche Alltag oder Ausnahme? Entscheidet Skill vs. Instruction - die einzige
    Entscheidung hier, die in jeder Session Kontext-Budget kostet.

Nächster konkreter Schritt

Den kanonischen raw/research/-Header entwerfen (Dateiformat), jetzt mit Feldern für
research_backend (search-api | agent-api) statt nur einem Sonar-Modellnamen. Daran zeigt sich,
ob B/C tragfähig ist - und es ist die kleinste Einheit, die etwas beweist, ohne dass ein API-Key
im Spiel sein muss.

Akzeptanzkriterien

  • Der raw/research/-Header ist entworfen und an einem echten (auch von Hand eingefügten)
    Report erprobt, inklusive research_backend-Feld.
  • Geklärt, ob multi_query in der Search API als ein oder mehrere Requests abgerechnet wird.
  • Die vier offenen Entscheidungen oben sind getroffen und hier notiert.
  • raw/CONTRACT.md, types/source.md und kb/CONTRACT.md tragen die Regeln, die aus der
    Entscheidung folgen.
  • instructions/research-topic.md existiert und ist aus wiki-query und wiki-lint
    verlinkt.
  • Dokumentiert, welcher Perplexity-MCP-Server-Modus (gehostet vs. lokal) als Standard gilt.
  • Changelog-Eintrag. MINOR, solange kein bestehender Inhalt migriert werden muss - ein
    neuer source_type-Enum-Wert ist additiv, eine geänderte Konfidenz-Regel für bestehende
    Seiten wäre es nicht.

Pfade nachgezogen 2026-09-04 (#29): wiki_tools/search/base.py → tools/chemenu/search/base.py
(Datei und SearchBackend-Protokoll dort verifiziert). Die commonplace/kb/…-Pfade sind korrekt
und bleiben - beide Dateien existieren. Bei #19 ergänzt, dass es inzwischen geschlossen ist, damit
der Verweis nicht als offener Strang gelesen wird. Die Sonar-Frist 2026-09-27 ist zum Zeitpunkt
dieses Durchgangs noch Zukunft und bleibt als Frist stehen; sie ist danach als abgelaufen
umzuformulieren.

Übernommen aus `TODO.md` (Diskussion 2026-08-23), seither zweimal überarbeitet: erstmals strukturell (Entscheidung C, Netzwerk-Call-Schnitt), jetzt inhaltlich nach einer Prüfung der aktuellen Perplexity-API-Landschaft (Perplexity-Space-Sitzung 2026-08-31). Änderungshistorie als Kommentar an diesem Issue, nicht hier - der Body beschreibt den aktuellen Stand, keine Versionen. ## Quellen - Diskussion 2026-08-23, gelesene Contracts: `raw/CONTRACT.md`, `kb/CONTRACT.md`, `instructions/CONTRACT.md`, `work/CONTRACT.md`, `types/source.md` - Perplexity-Space-Sitzung 2026-08-31: Recherche zu Agent API, Search API, MCP-Server, aktueller Kostenstruktur (docs.perplexity.ai, Stand 2026-08) - `commonplace/kb/notes/brainstorming-how-to-enrich-web-search.md` - `commonplace/kb/sources/karpathy-llm-wiki.md` ## Befund: kein fehlender Skill, sondern ein fehlender Ausgang `AGENTS.md` Invariante 3 verlangt, bei fehlender Quelle „the wiki has no confident source for this" zu sagen. Das ist heute eine **Sackgasse** - der Lauf endet dort. Recherche ist deshalb nicht ein zusätzliches Feature, sondern der fehlende Ausgang aus dieser Invariante: keine Quelle vorhanden, also eine beschaffen. Der Karpathy-Ursprungstext hat das bereits vorgesehen („data gaps that could be filled with a web search" als Lint-Befund); gebaut wurde es nie. ## Kernproblem: wohin fällt ein Recherche-Ergebnis? Das ist die eigentliche Designfrage, nicht „Skill ja/nein". Die Pipeline ist `raw/` → `kb/`, und **beide Enden weisen ein Recherche-Ergebnis ab**: `raw/` verbietet „Anything the LLM wrote", `kb/` verlangt, dass jeder Claim auf eine Datei unter `raw/` zurückführt. Drei Auflösungen: | | Ansatz | Preis | |---|---|---| | **A** | Ergebnis ist nur Navigation. Nur die gefundenen Primärquellen werden gefetcht und landen in `raw/articles/` | Paywalls, JS-Seiten, N Fetches; ein synthetisierter Bericht (falls einer entstand) geht verloren | | **B** | Ergebnis ist eine Quelle. Ein generierter Bericht landet verbatim in `raw/research/`, mit Query, Modell, Filtern, Datum und Zitatliste | Eine Tertiärquelle wird wie eine Primärquelle behandelt, was die Konfidenz aufbläht | | **C** | B für das Artefakt, A für die Claims - Bericht verbatim **und** die Primärquellen, die tatsächlich etwas tragen sollen | Zwei getrennte Aufrufe statt einem | **Entscheidung der Diskussion: C, jetzt als zwei getrennte API-Aufrufe statt eines gemeinsamen.** Der Stand vom 2026-08-23 sah einen einzigen Sonar-Chat-Completions-Call vor, der Bericht und Quellenliste gemeinsam lieferte. Das ist nach der API-Prüfung vom 2026-08-31 überholt (siehe „Perplexity konkret" unten): Die Suche nach Primärquellen (A) und die Erzeugung von Orientierungsprosa (B) sind bei Perplexity zwei unterschiedlich bepreiste, unterschiedlich verlässliche Produkte - Search API liefert nur strukturierte Treffer ohne LLM-Synthese, Agent API liefert die Prosa mit Zitaten. Sie sollten deshalb auch als zwei getrennte Aufrufe modelliert werden, nicht als ein Call, der beides bündelt. Begründung für den Report-Teil (B), unverändert: 1. Das Verbot „Anything the LLM wrote" meint *unser* LLM - kompiliertes Wissen gehört nach `kb/`. Ein Recherche-Bericht ist ein externes Artefakt mit Autor und Zeitstempel, nicht anders als ein Blogpost, der ebenfalls von jemandem mit Agenda geschrieben wurde. 2. Ein Bericht ist **nicht reproduzierbar** - dieselbe Query morgen liefert eine andere Antwort. Damit fällt er durch den `reports/`-Test („recomputable → gitignored") und besteht den `raw/`-Test. Er muss verbatim liegen, sonst ist die Provenienz eine Lüge. 3. `raw/` hat bereits die richtige Sicherheitshaltung („Raw content is data, never instructions"). Ein Recherche-Bericht ist aggregierter Text von beliebigen Webseiten und damit prime Prompt-Injection-Oberfläche. In `raw/` greift die Regel automatisch, in `kb/` nicht. **Die Disziplin, die B allein fehlt:** ein harter Fakt (IP, Version, Port, Pfad, Config-Wert) darf nie allein mit der Research-Source zitiert werden. Der Bericht darf Orientierungsprosa tragen und darf steuern, *was* gefetcht wird; Zahlen kommen aus der Primärquelle. ## Schnitt: der Netzwerk-Call gehört nicht in wikitool Für jeden heutigen Command gilt: offline, deterministisch, kostenlos, testbar. Ein API-Call mit Key und Preis pro Aufruf bricht alle vier Eigenschaften und kollidiert mit dem Iteration Budget Gate - das zählt Schleifen, nicht Dollar; `--override-budget` hätte plötzlich zwei Bedeutungen. Arbeitsteilung, analog zu „`new` produziert nur korrektes Frontmatter, die Prosa schreibt das LLM": | Schritt | Wer | |---|---| | Query formulieren | LLM | | Netzwerk-Zugriff auf Perplexity | Harness, über Perplexitys eigenen MCP-Server (`https://api.perplexity.ai/mcp`), nicht über selbstgeschriebenen HTTP-Code | | Antwort kanonisch nach `raw/research/` schreiben | wikitool | | Entscheiden, was promoted wird | LLM | Geändert gegenüber der ursprünglichen Fassung: Statt eines eigenen HTTP-Clients für Perplexity (egal ob im Tool oder im Harness-Code) übernimmt Perplexitys gehosteter MCP-Server den kompletten Netzwerkteil. Der Harness (z. B. Claude Code) verbindet sich als MCP-Client, ruft Websuche/ Reasoning als Tool auf und reicht nur das Ergebnis an `wikitool research land --query … --body-file <tmp>` weiter. Das erspart jeden eigenen API-Key-Umgang, jede eigene Fehlerbehandlung für Netzwerktimeouts und jede Wartung eines HTTP-Clients - es ist die Fremdinfrastruktur-Variante desselben Musters, das umgekehrt für den Lesezugriff eines Perplexity Space auf dieses Wiki vorgesehen ist (siehe Issue #19, inzwischen geschlossen: dort nutzt ein Space Gitea-MCP-Infrastruktur, hier nutzt ein Wiki-Agent Perplexity-MCP-Infrastruktur). Falls der Call doch einmal direkt ins Tool wandern soll: das Backend-Pattern existiert bereits (`tools/chemenu/search/base.py`, `SearchBackend`-Protokoll + Registry), kein Vendor-Lock nötig. ## Skill vs. Instruction: als flache Instruction starten `instructions/CONTRACT.md` ist explizit - jede publizierte Skill-Description sitzt die ganze Session im Kontext, und eine Prozedur, die selten läuft, verdient einen Link statt eines Dauerplatzes. Die Recherche-Prozedur ist zudem dünn, weil die Ingest-Hälfte bereits von `wiki-ingest` abgedeckt wird. Plan: `instructions/research-topic.md` als flache Instruction, verlinkt aus `wiki-query` (bei „keine Quelle") und `wiki-lint` (bei „data gap"). Wird es Routine, ist die Beförderung rein strukturell: `mkdir` + `SKILL.md` + `instructions sync`. ## Mehrrunden-Recherche gehört in work/ Die commonplace-Notiz landet unabhängig bei „workshop layer, explicit human review before anything becomes permanent" - genau der Zweck von `work/`. Einzige Reibung: `work new --input` leitet den Run-Key aus einem Pfad unter `raw/` ab, den eine Recherche noch nicht hat. Es bräuchte einen zweiten Key-Modus (`research-<slug>`). ## Perplexity konkret Vollständig überarbeitet gegenüber der Fassung vom 2026-08-23; die alte Sonar-Chat-Completions- Zentrierung ist überholt. **Drei Integrationswege, nicht einer:** | Weg | Endpunkt | Liefert | Einsatz hier | |---|---|---|---| | Search API | `POST /search` | `results[]`: title, url, snippet, date, last_updated; Multi-Query (bis 5), Domain-/Sprach-/Länderfilter, Recency- oder exakte Datumsfilter, optionale Volltext-Extraktion pro Treffer | Primärquellen-Beschaffung (Teil A) - keine LLM-Synthese, kein Halluzinationsrisiko | | Agent API | `POST /v1/agent` (Alias `/v1/responses`) | typisiertes `output[]`: `search_results`-Items plus `message`-Items mit Zitationen; Presets `fast`/`low`/`medium`/`high`/`xhigh`; Tools `web_search`/`fetch_url`/`finance_search`/`people_search`/Sandbox/MCP/Custom Functions | Bericht-Teil (Teil B), wenn echte Orientierungsprosa gebraucht wird | | Sonar (Chat Completions) | `POST /v1/sonar` | `choices[]` + `citations[]` + `search_results[]` | **Nicht mehr bauen** - Support endet 2026-09-27 | **Vierter Weg, für den Transport statt die API-Wahl:** Perplexitys gehosteter MCP-Server (`https://api.perplexity.ai/mcp`, Streamable HTTP mit Bearer-Auth; alternativ lokal per stdio) stellt Websuche/Reasoning als MCP-Tools bereit. Das ist der empfohlene Weg für den in „Schnitt: der Netzwerk-Call gehört nicht in wikitool" beschriebenen Schritt - der Harness ruft dort direkt auf, kein eigener HTTP-Client nötig. **Kostenstruktur (Stand 2026-08):** - **Search API:** pauschal 5,00 $ pro 1.000 Requests, unabhängig von Modell oder Tokenmenge. Offen: ob ein `multi_query`-Aufruf mit bis zu fünf Teilqueries als ein Request oder mehrere zählt - vor einem Kosten-Gate zu klären. - **Agent API:** drei separat ausgewiesene Kostenkomponenten in jeder Antwort (`usage.cost.input_cost`, `.output_cost`, `.tool_calls_cost`, `.total_cost`): - Modell-Tokens, modellabhängig; Perplexitys eigenes Sonar-Modell innerhalb der Agent API 0,25 $ / 2,50 $ pro 1M Input-/Output-Tokens - Tool-Aufrufe pro Invocation: `web_search` 0,0025 $, `fetch_url` 0,0005 $, `people_search`/`finance_search` je 0,005 $ - Sandbox, falls genutzt: 0,03 $ pro Session (≤20 Min.) plus 0,0025 $ pro Sandbox-Suche - **Sonar (legacy, auslaufend):** 1 $/1 $ (Sonar) bis 3 $/15 $ (Sonar Pro) pro 1M Tokens, plus feste Request-Gebühr 5-14 $ pro 1.000 Requests je `search_context_size`; Deep Research zusätzlich 2 $/1M Citation-Tokens, 3 $/1M Reasoning-Tokens, 5 $/1.000 Suchanfragen. Nur zur Einordnung, nicht für Neubau relevant. `usage.cost.total_cost` (Agent API) bzw. der Pauschalpreis (Search API) sind die Datengrundlage für ein künftiges Kosten-Gate, wie in der Fassung vom 2026-08-23 bereits vorgesehen - jetzt mit Aufschlüsselung statt nur Gesamtsumme. **Für die Snapshot-Hälfte (Primärquellen holen):** weiterhin eher Jina Reader / Firecrawl / Tavily Extract oder die Web-Tools des Harness als die Search API, sofern deren Content-Extraktion (`max_tokens_per_page`) nicht ausreicht - zu prüfen, sobald der `raw/research/`-Header entworfen ist. ## Offene Contract-Änderungen (Aufwandsschätzung, nicht umgesetzt) 1. `raw/CONTRACT.md`: Zeile `research/` in der Routing-Tabelle plus ein Absatz, der „externes Recherche-Artefakt" von „unser kompiliertes Wissen" abgrenzt. 2. `types/source.md` + `source.schema.yaml`: `source_type: research` in den Enum, plus Pflichtfelder `research_query` / `research_model` / `research_backend` (letzteres neu, wegen der Wahl zwischen Search API und Agent API). 3. `kb/CONTRACT.md` Confidence: heute +0.1 für offizielle Doku, +0.05 für reputable Sekundärquellen - für **Tertiärquellen** fehlt eine Regel. Vorschlag: Deckel bei 0.5, solange keine Primärquelle mitzitiert ist. 4. `instructions/research-topic.md` plus Links aus `wiki-query` und `wiki-lint`. 5. Schritt „Widerspruch": Recherche findet Dinge, die bestehenden Seiten widersprechen. `lint` prüft nichts Semantisches. Regel: nie überschreiben, beides festhalten, User fragen. Konfidenz per `touch --confidence-base` nachziehen. 6. `docs verify` / `tools/CONTRACT.md` nachziehen, falls ein Command dazukommt. 7. Neu: Dokumentation, welcher MCP-Server (Perplexity-gehostet vs. lokal/stdio) in welchem Harness-Setup als Standard gilt, und wo dessen API-Key liegt (1Password-Konvention). ## Offene Entscheidungen - **Perplexity fix verdrahten oder austauschbar bauen?** Durch den MCP-Transport-Weg entschärft: wenn der Harness selbst die MCP-Verbindung hält, ist wikitool ohnehin nie an einen Vendor gebunden. Die `SearchBackend`-Registry bleibt trotzdem für lokale kb/-Suche sinnvoll, unabhängig von dieser Frage. - **Primärquellen mitfetchen (C) oder reicht der Bericht (B)?** Daran hängen die Konfidenz-Regeln. Weiterhin offen. - **Search API allein für A, oder zusätzlich Content-Extraktion statt separatem Fetch-Tool?** Neu aufgeworfen durch die Prüfung vom 2026-08-31 - noch nicht entschieden. - **Ist Recherche Alltag oder Ausnahme?** Entscheidet Skill vs. Instruction - die einzige Entscheidung hier, die in *jeder* Session Kontext-Budget kostet. ## Nächster konkreter Schritt Den kanonischen `raw/research/`-Header entwerfen (Dateiformat), jetzt mit Feldern für `research_backend` (search-api | agent-api) statt nur einem Sonar-Modellnamen. Daran zeigt sich, ob B/C tragfähig ist - und es ist die kleinste Einheit, die etwas beweist, ohne dass ein API-Key im Spiel sein muss. ## Akzeptanzkriterien - [ ] Der `raw/research/`-Header ist entworfen und an einem echten (auch von Hand eingefügten) Report erprobt, inklusive `research_backend`-Feld. - [ ] Geklärt, ob `multi_query` in der Search API als ein oder mehrere Requests abgerechnet wird. - [ ] Die vier offenen Entscheidungen oben sind getroffen und hier notiert. - [ ] `raw/CONTRACT.md`, `types/source.md` und `kb/CONTRACT.md` tragen die Regeln, die aus der Entscheidung folgen. - [ ] `instructions/research-topic.md` existiert und ist aus `wiki-query` und `wiki-lint` verlinkt. - [ ] Dokumentiert, welcher Perplexity-MCP-Server-Modus (gehostet vs. lokal) als Standard gilt. - [ ] Changelog-Eintrag. **MINOR**, solange kein bestehender Inhalt migriert werden muss - ein neuer `source_type`-Enum-Wert ist additiv, eine geänderte Konfidenz-Regel für bestehende Seiten wäre es nicht. --- *Pfade nachgezogen 2026-09-04 (#29): `wiki_tools/search/base.py` → `tools/chemenu/search/base.py` (Datei und `SearchBackend`-Protokoll dort verifiziert). Die `commonplace/kb/…`-Pfade sind korrekt und bleiben - beide Dateien existieren. Bei #19 ergänzt, dass es inzwischen geschlossen ist, damit der Verweis nicht als offener Strang gelesen wird. Die Sonar-Frist 2026-09-27 ist zum Zeitpunkt dieses Durchgangs noch Zukunft und bleibt als Frist stehen; sie ist danach als abgelaufen umzuformulieren.*
torben added the prio/waitingsize/L labels 2026-08-31 06:56:52 +00:00
torben commented 2026-08-31 14:25:25 +00:00
Author
Owner
Copy Link
Copy Source

Änderungslog

2026-08-31 (Perplexity-Space-Sitzung): Body vollständig überarbeitet gegenüber der
Fassung vom 2026-08-23. Auslöser: Prüfung der aktuellen Perplexity-API-Landschaft im
Rahmen der Frage, wie sich dieses Repo an einen Perplexity Space koppeln lässt
(siehe auch Issue #19).

Geänderte Punkte:

  1. Zielendpunkt korrigiert. Ursprünglich war ein Sonar-Chat-Completions-Call
    (/v1/sonar) für Bericht und Quellenliste gemeinsam vorgesehen. Dieser Endpunkt
    wird am 2026-09-27 abgeschaltet - vier Wochen ab jetzt. Dagegen zu bauen wäre keine
    Terminplanung mehr gewesen, sondern ein Fehlgriff.
  2. Dritte API ergänzt. Die eigenständige Search API (POST /search) fehlte in der
    ursprünglichen Analyse komplett. Sie liefert exakt das, was der Body selbst als
    "eigentlich wertvoll" markiert (search_results[]-Metadaten), ohne LLM-Synthese,
    ohne Halluzinationsrisiko, pauschal abgerechnet.
  3. Entscheidung C aufgeteilt. Statt eines Calls für Bericht+Quellen jetzt zwei
    getrennte, unterschiedlich bepreiste Aufrufe: Search API für Teil A (Primärquellen),
    Agent API nur für Teil B (Orientierungsprosa), falls überhaupt gebraucht.
  4. Netzwerk-Transport geändert. Statt eines selbstgeschriebenen HTTP-Clients (im
    Tool oder im Harness-Code) übernimmt Perplexitys eigener gehosteter MCP-Server
    (https://api.perplexity.ai/mcp) den Netzwerkteil. Der Harness verbindet sich als
    MCP-Client; wikitool bekommt nur noch die fertige Antwort zum Kanonisieren. Das ist
    dieselbe Musterlösung wie in Issue #19, nur in umgekehrter Richtung (dort: Space
    nutzt Gitea-MCP; hier: Wiki-Agent nutzt Perplexity-MCP).
  5. Kostenstruktur aktualisiert und aufgeschlüsselt (Search API: 5,00 $ pauschal je
    1.000 Requests; Agent API: Modell-Tokens + Tool-Aufrufe + ggf. Sandbox, alle drei
    Komponenten einzeln in usage.cost je Antwort ausgewiesen; Sonar-Preise nur noch
    zur historischen Einordnung).
  6. Offene Contract-Änderungen um Punkt 7 ergänzt (Dokumentation, welcher
    MCP-Server-Modus als Standard gilt, plus 1Password-Konvention für den Key).
  7. Akzeptanzkriterien erweitert um research_backend-Feld, die Klärung der
    multi_query-Abrechnung und die MCP-Server-Modus-Dokumentation.

Unverändert geblieben: der Grundbefund (Invariante 3 als fehlender Ausgang), die
Begründung für Entscheidung C, die Skill-vs-Instruction-Entscheidung (flache
Instruction), und die Einordnung der Mehrrunden-Recherche in work/.

## Änderungslog **2026-08-31 (Perplexity-Space-Sitzung):** Body vollständig überarbeitet gegenüber der Fassung vom 2026-08-23. Auslöser: Prüfung der aktuellen Perplexity-API-Landschaft im Rahmen der Frage, wie sich dieses Repo an einen Perplexity Space koppeln lässt (siehe auch Issue #19). Geänderte Punkte: 1. **Zielendpunkt korrigiert.** Ursprünglich war ein Sonar-Chat-Completions-Call (`/v1/sonar`) für Bericht und Quellenliste gemeinsam vorgesehen. Dieser Endpunkt wird am 2026-09-27 abgeschaltet - vier Wochen ab jetzt. Dagegen zu bauen wäre keine Terminplanung mehr gewesen, sondern ein Fehlgriff. 2. **Dritte API ergänzt.** Die eigenständige Search API (`POST /search`) fehlte in der ursprünglichen Analyse komplett. Sie liefert exakt das, was der Body selbst als "eigentlich wertvoll" markiert (`search_results[]`-Metadaten), ohne LLM-Synthese, ohne Halluzinationsrisiko, pauschal abgerechnet. 3. **Entscheidung C aufgeteilt.** Statt eines Calls für Bericht+Quellen jetzt zwei getrennte, unterschiedlich bepreiste Aufrufe: Search API für Teil A (Primärquellen), Agent API nur für Teil B (Orientierungsprosa), falls überhaupt gebraucht. 4. **Netzwerk-Transport geändert.** Statt eines selbstgeschriebenen HTTP-Clients (im Tool oder im Harness-Code) übernimmt Perplexitys eigener gehosteter MCP-Server (`https://api.perplexity.ai/mcp`) den Netzwerkteil. Der Harness verbindet sich als MCP-Client; wikitool bekommt nur noch die fertige Antwort zum Kanonisieren. Das ist dieselbe Musterlösung wie in Issue #19, nur in umgekehrter Richtung (dort: Space nutzt Gitea-MCP; hier: Wiki-Agent nutzt Perplexity-MCP). 5. **Kostenstruktur aktualisiert und aufgeschlüsselt** (Search API: 5,00 $ pauschal je 1.000 Requests; Agent API: Modell-Tokens + Tool-Aufrufe + ggf. Sandbox, alle drei Komponenten einzeln in `usage.cost` je Antwort ausgewiesen; Sonar-Preise nur noch zur historischen Einordnung). 6. **Offene Contract-Änderungen um Punkt 7 ergänzt** (Dokumentation, welcher MCP-Server-Modus als Standard gilt, plus 1Password-Konvention für den Key). 7. **Akzeptanzkriterien erweitert** um `research_backend`-Feld, die Klärung der `multi_query`-Abrechnung und die MCP-Server-Modus-Dokumentation. Unverändert geblieben: der Grundbefund (Invariante 3 als fehlender Ausgang), die Begründung für Entscheidung C, die Skill-vs-Instruction-Entscheidung (flache Instruction), und die Einordnung der Mehrrunden-Recherche in `work/`.
torben added the area/kbkind/decision labels 2026-09-02 21:25:02 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No Label area/kb kind/decision prio/waiting size/L
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#15
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?