Add shared read-only Git and database research tools
This commit is contained in:
Nico committed
1 parent
0c750dbb74
commit
02f63702ba
30 files changed
+3231
-42
No files matched your search
@@ -96,8 +96,9 @@ contract rather than granting a model extra allocations through this schema.
|
||||
All source, database, human feedback and prior model notes are untrusted data.
|
||||
Symbol occurrences and partial/empty queries retain their existing scope warnings.
|
||||
No conclusions about current live server behavior are inferred from old snapshots.
|
||||
The context includes current-revision evidence rather than silently dropping
|
||||
history. If the configured byte bound is exceeded, dispatch rejects explicitly;
|
||||
The durable context includes current-revision evidence. The opt-in project-research
|
||||
prompt uses a compact view documented in [project-research-v1.md](project-research-v1.md).
|
||||
If the configured byte bound is exceeded, dispatch rejects explicitly;
|
||||
operators must align context, gateway request and artifact limits.
|
||||
|
||||
## Budget and stopping
|
||||
@@ -119,16 +120,16 @@ Logical defaults, frozen per analysis revision:
|
||||
| Config | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `max_iterations_per_hypothesis` | 50 | Maximum research-producing model iterations; one final assessment/closure is permitted |
|
||||
| `max_invalid_responses` | 3 | Consecutive rejected replies before abandoning that hypothesis's controller attempt |
|
||||
| `max_invalid_responses` | 3 | Consecutive rejected replies before blocking the case for technical correction |
|
||||
| `max_questions_per_hypothesis` | 30 | Bound on accumulated question records |
|
||||
| `test_deadline_seconds` | 21600 | Controller-owned external test deadline |
|
||||
| `max_steps_per_dispatch` | 8 | Fair scheduler yield boundary |
|
||||
|
||||
An invalid reply changes only retry/audit bookkeeping. A following prompt includes
|
||||
its safe rejection code. Repeated invalid replies cause a recorded
|
||||
`invalid_responses` disposition, not a factual rejection. If a previous result
|
||||
cannot be assessed within that limit, it is deterministically closed with zero
|
||||
reward before ending that controller attempt. Existing credit is not refilled.
|
||||
its safe rejection code. Repeated invalid replies cause `BLOCKED` with
|
||||
`INVALID_LLM_RESPONSES`, requiring explicit operator resume after correction.
|
||||
The hypothesis stays active; pending results, reservations and remaining credit
|
||||
are preserved. No budget completion or zero-score settlement is fabricated.
|
||||
The same initial hypotheses cannot be regenerated to reset their limits.
|
||||
|
||||
The iteration cap prevents free model-only research loops even when credit is
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
# Projekt-Recherche v1
|
||||
|
||||
`ProjectResearch` ist die gemeinsame lesende Schnittstelle für die deterministische
|
||||
Case-Aufbereitung und die LLM-gesteuerte Hypothesenuntersuchung. Die erste LLM-Phase
|
||||
bleibt der CaseInterpreter. Der CaseBuilder diagnostiziert nicht und führt keine
|
||||
LLM-Abfragen aus. `docs/architecture.md` bleibt unverändert.
|
||||
|
||||
## Datenquellen und Grenzen
|
||||
|
||||
- Sourcecode: lokaler Git-Clone des vom Betreiber freigegebenen Repositories.
|
||||
Abfragen lesen Git-Objekte eines vollständigen Commit-Hashes, nicht den veränderlichen
|
||||
Arbeitsbaum. Ein Branchwechsel oder Git-Pull ändert keine bestehende Bindung.
|
||||
- Source-Schemata: SQL-Dateien desselben Commits. Sie beweisen Tabellenstrukturen
|
||||
dieses Codestands, keine tatsächlich vorhandenen Datenbankzeilen.
|
||||
- Datenbank: parameterisierte SELECT-Abfragen gegen ausdrücklich freigegebene Tabellen
|
||||
einer MySQL-/MariaDB-Datenbank. Zugangsdaten bleiben in Environment-Variablen oder
|
||||
einer lokalen Passwortdatei. Sie werden nicht in Requests, Captures oder Logs kopiert.
|
||||
- Externe Webrecherche: weiterhin separat für vorgesehenes Verhalten. Dieser Meilenstein
|
||||
aktiviert keine Google-Suche und führt keine kostenpflichtigen LLM-Aufrufe aus.
|
||||
|
||||
Die LLM darf weder Serveradresse, URL, Branch, Dateisystemwurzel, Datenbank noch
|
||||
Zugangsdaten bestimmen. Freies SQL, Shellzugriff, Joins mit frei vorgegebenen Ausdrücken,
|
||||
Schreiboperationen, Builds und Labsteuerung stehen nicht zur Verfügung.
|
||||
Zusammenhänge werden durch aufeinanderfolgende explizite Abfragen untersucht.
|
||||
|
||||
## Operationen
|
||||
|
||||
Die Investigation verwendet `next.kind = "tool"`, `operation = "project.query"`
|
||||
und `arguments` gemäß `project-query-v1.schema.json`.
|
||||
|
||||
| `arguments.kind` | Funktion |
|
||||
| --- | --- |
|
||||
| `source.files` | Dateipfade durch literalen Teilstring finden |
|
||||
| `source.search` | Literale Textsuche, optional auf Pfadpräfix begrenzt |
|
||||
| `source.symbol` | Suche nach vollständigem Symbolwort |
|
||||
| `source.registration` | Symbolvorkommen als Ausgangspunkt einer Registrierungsprüfung |
|
||||
| `source.schema` | Literale Suche ausschließlich in SQL-Dateien |
|
||||
| `source.read` | Begrenzten Zeilenbereich einer bekannten Datei lesen |
|
||||
| `database.tables` | Namen in der konfigurierten Tabellen-Allowlist finden |
|
||||
| `database.schema` | Tatsächliche Spalten, Typen, Nullbarkeit und Schlüssel lesen |
|
||||
| `database.rows` | Spalten auswählen, explizite Filter und begrenzte Seite lesen |
|
||||
| `database.count` | Vollständige Trefferzahl für dieselben Filter bestimmen |
|
||||
|
||||
DB-Filter unterstützen `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `contains`, `in`.
|
||||
Mehrere Filter werden mit AND verbunden. `contains` behandelt `%`, `_` und das
|
||||
Escape-Zeichen als literale Eingabe. Werte werden ausschließlich als SQL-Parameter
|
||||
übergeben. Tabellen und Spalten sind validierte Bezeichner; Tabellen müssen zusätzlich
|
||||
in der Betreiber-Allowlist liegen. Ein Schema-Lookup prüft die tatsächlichen Spalten.
|
||||
SQL-DECIMAL-Werte werden als exakte Zeichenfolgen übertragen, nicht gerundet.
|
||||
|
||||
Textsuche ist lexikalisch: ein Treffer beweist weder eine semantische Definition noch
|
||||
eine Registrierung oder einen ausgeführten Aufruf. Auch historische SQL-Updates sind
|
||||
kein Ersatz für die aktuelle Datenbank. Pfad-Traversal, absolute Pfade und Git-Metadaten
|
||||
werden abgelehnt; Symlinks und Submodule werden nicht als lesbare Source-Dateien aufgenommen.
|
||||
|
||||
Abfragen haben konfigurierbare Zeilen-, Byte-, Datei- und Zeitlimits. Ergebnisse markieren
|
||||
Pagination, ausgelassene Dateien und gekürzte Zeilen. `complete_filtered_rows` gilt nur
|
||||
für das genau beschriebene Prädikat ohne Offset/weitere Seite. Eine vollständige Abfrage
|
||||
mit null Treffern ist ein belastbarer Abwesenheitsbeleg **innerhalb dieses Snapshots und
|
||||
Prädikats**. Eine partielle Suche rechtfertigt keinen globalen Abwesenheitsschluss.
|
||||
|
||||
## Persistenz und Budget
|
||||
|
||||
Captures besitzen Formatversion 1, Schema, Anfrage, Ursprung und Ergebnis. Git-Ursprünge
|
||||
enthalten URL und Commit; Treffer zusätzlich Blob-ID, SHA-256 und Zeilennummer.
|
||||
DB-Ursprünge enthalten Datenbank und die vom Betreiber vergebene Snapshot-Identität.
|
||||
Diese Identität muss beim Wechsel/Neuimport eines Snapshots ebenfalls geändert werden;
|
||||
sie ist keine automatisch berechnete Prüfsumme eines laufenden Servers.
|
||||
|
||||
Investigation-Ergebnisse werden unter `analysis/evidence/captures/<sha256>.json`
|
||||
zusammen mit Requests, Rohantworten und Evidence Records append-only gespeichert.
|
||||
Auch leere Antworten behalten Anfrage und Abdeckung. Historienprüfung und Wiedereinstieg
|
||||
benötigen keinen laufenden Git-/DB-Provider. Die Fallakte enthält die tatsächlich gelesenen
|
||||
Ausschnitte und Zeilen, nicht eine vollständige Kopie von Repository und World-DB.
|
||||
|
||||
Ein Tool schreibt selbst nicht in den Case. Der bestehende Controller reserviert das
|
||||
positive Aktionsbudget für `project.query`, führt die Anfrage aus und übernimmt validierte
|
||||
Captures atomar mit der Evidenz. Wiederholte identische Ergebnisse sind keine neue Evidenz.
|
||||
Der In-Memory-Cache friert eine Antwort während Query/Validierung/Persistenz ein; bei einem
|
||||
Neustart sind gespeicherte Evidenz und der bestätigte Plan autoritativ.
|
||||
|
||||
Ausfälle der Recherche führen zu `BLOCKED / RESEARCH_UNAVAILABLE`. Ein bestätigter Plan
|
||||
bleibt wiederaufnehmbar, einschließlich seiner Reservation. Ungültige Modellantworten
|
||||
führen nach dem konfigurierten Limit zu `BLOCKED / INVALID_LLM_RESPONSES`; eine technische
|
||||
Ablehnung beendet keine Hypothese und verändert keine vorhandene Evidenzbewertung.
|
||||
Nach Behebung ist eine explizite Operator-Wiederaufnahme über `CheckpointStore.advance`
|
||||
in den im letzten Blockierungscheckpoint hinterlegten `resume_state` nötig. Der
|
||||
Retry-Zeitpunkt und die bestehende Feedback-Sperre bleiben verbindlich.
|
||||
|
||||
## Case-Aufbereitung
|
||||
|
||||
`CaseBuilder(..., project_research=service)` sammelt vor Abschluss einer Revision
|
||||
deterministisch konfigurierte Queries und Entity-Lookups. Namen und Questvoraussetzungen
|
||||
werden mit Provenienz als technische Fakten sichtbar, bevor die erste LLM-Anfrage beginnt.
|
||||
Das verhindert, dass eine numerische ID allein als Name oder betroffener NPC ausgelegt wird.
|
||||
Abfragen und Resultate liegen unter `research/project/`; die Case-Inputs werden mit einem
|
||||
neuen versionierten Index erweitert. Derselbe Enrichment-Checkpoint wird nicht wiederholt.
|
||||
Eine abgeschlossene Revision wird nicht nachträglich mit neuen Rohinputs umgeschrieben.
|
||||
|
||||
Die Beispielkonfiguration löst Creature- und Quest-IDs generisch auf. Sie enthält keine
|
||||
BUG-000020-spezifische Diagnose oder Wolpertinger-ID. Die LLM kann während der Untersuchung
|
||||
weitere Tabellen und Source-Ausschnitte gezielt abfragen.
|
||||
|
||||
Mit aktivierter Projekt-Recherche wird `investigation_project_v1` verwendet. Der volle
|
||||
Context bleibt unverändert archiviert. Der Prompt lässt Input-Inventar und doppelte
|
||||
vorige Resultate weg; fremde Hypothesen behalten Evidenz-IDs/Provenienz, aber keine Payloads.
|
||||
Die Auswahl ist deterministisch und gekennzeichnet. Bereits gespeicherte Legacy-Prompts
|
||||
bleiben mit ihrer alten Version rekonstruierbar. Dies reduziert Kontextmenge, garantiert
|
||||
aber keinen bestimmten Eurobetrag und ersetzt keine Messung des nächsten LLM-Tests.
|
||||
|
||||
## Lokale Testumgebung
|
||||
|
||||
Die eingerichtete Instanz benutzt MariaDB 10.11.14 aus dem offiziellen portablen ZIP
|
||||
(SHA-256 `838b7d91b871a30c2e42e5ceff9c6859ddd061b57328fb7cb51154af9bd8ddf4`).
|
||||
Es wird kein Windows-Dienst installiert. Daten und Logs liegen ausschließlich unter
|
||||
`service-data/research/`, Git-Clone ebenfalls dort. Diese Dateien werden nicht committet.
|
||||
|
||||
Importiert wurde ausschließlich `cata_world` (206 Tabellen) aus dem bereitgestellten
|
||||
Backup, SHA-256 `4964f277ef5cf7f7f98bf4378971dcb55180bac813d49bcda6d2f03ff6969662`.
|
||||
Account-, Charakter- und weitere Datenbankabschnitte wurden ausgelassen.
|
||||
Die Instanz bindet `127.0.0.1:33079`; `viano_reader` besitzt SELECT ohne GRANT OPTION.
|
||||
`read_only` ist aktiviert, Abfragen verwenden zusätzlich eine Read-only-Transaktion.
|
||||
Der administrative Restore ist ein separates Entwicklungswerkzeug, keine Runtime-Funktion
|
||||
des Analyseprogramms und kein Modelltool.
|
||||
|
||||
Optionale Dependencies installieren:
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe -m pip install -e ".[research,test]"
|
||||
```
|
||||
|
||||
`config/project.local.toml` wurde aus der Beispielkonfiguration vorbereitet. Das Programm
|
||||
lädt relative Providerpfade relativ zu dieser Konfigurationsdatei. Ein zukünftiger
|
||||
Server nutzt eigene lokale Zugangsdaten und dieselbe Schnittstelle mit SELECT-only-Rechten.
|
||||
|
||||
Die bereits initialisierte Instanz bei Bedarf starten/stoppen:
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe scripts/dev_world_db.py start --binary-dir service-data/research/runtime/portable/mariadb-10.11.14-winx64/bin --directory service-data/research/world-db
|
||||
.\.venv\Scripts\python.exe scripts/dev_world_db.py stop --binary-dir service-data/research/runtime/portable/mariadb-10.11.14-winx64/bin --directory service-data/research/world-db
|
||||
```
|
||||
|
||||
Ein neuer Rechner benötigt zunächst den portablen Server, eine initialisierte Datadir
|
||||
(`mariadb-install-db.exe --datadir=<absoluter Pfad> --port=33079 --silent`) und einen
|
||||
einmaligen `dev_world_db.py restore --dump <Backup>` gegen diese neue lokale Instanz.
|
||||
Das Werkzeug verweigert Administration, wenn der Port zu einer anderen Datadir gehört.
|
||||
Zugangsdaten bleiben unter `service-data/`; `reader.local.txt` enthält nur das Reader-Passwort.
|
||||
|
||||
Eine strukturierte Anfrage kann ohne LLM und ohne Paketänderung geprüft werden:
|
||||
|
||||
```json
|
||||
{"kind":"database.rows","table":"creature_template","columns":["entry","name"],"filters":[{"column":"name","operator":"contains","value":"Wolpertinger"}],"offset":0,"limit":10}
|
||||
```
|
||||
|
||||
Als `service-data/research/query.json` speichern und ausführen:
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe -m viano_bug_analysis.project_research --config config/project.local.toml --query service-data/research/query.json
|
||||
```
|
||||
|
||||
Ein späterer, ausdrücklich gestarteter LLM-Trial erhält zusätzlich
|
||||
`--project-config config/project.local.toml`. Für den Qualitäts-/Kostenvergleich einen
|
||||
frischen Testcase verwenden: alte Hypothesen und frühere terminale Budgetstände werden
|
||||
durch diesen Meilenstein nicht heimlich korrigiert oder zurückgesetzt.
|
||||
|
||||
Offline-Suite und optionale Integrationstests:
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe -m pytest -q
|
||||
$env:VBA_TEST_PROJECT_CONFIG = "config/project.local.toml"
|
||||
.\.venv\Scripts\python.exe -m pytest tests/test_project_database_integration.py -q
|
||||
```
|
||||
|
||||
Die Integrationstests prüfen den bekannten Backupstand ausschließlich lesend. Der
|
||||
CaseBuilder-Smoke-Test aus den echten wowdiag/wowsrc-Paketen liegt separat unter
|
||||
`service-data/research/smoke`; die ursprüngliche gestoppte Fallakte bleibt erhalten.
|
||||
|
||||
Gemini unterstützt Google Search Grounding, wenn die API-Anwendung es aktiviert:
|
||||
https://ai.google.dev/gemini-api/docs/google-search . Der aktuelle OpenAI-kompatible Adapter
|
||||
setzt keine solchen Tools. Ein Gitea Runner ist für diesen Stand nicht nötig; er könnte
|
||||
später Indizes aufbauen, während die Analyse weiterhin nur lesend auf diese zugreift.
|
||||
Reference in new issue
Block a user