diff --git a/docs/innboks-ingestion-funn-2026-06.md b/docs/innboks-ingestion-funn-2026-06.md new file mode 100644 index 0000000..0094ea4 --- /dev/null +++ b/docs/innboks-ingestion-funn-2026-06.md @@ -0,0 +1,109 @@ +# Innboks-ingestion — funn-grunnlag (2026-06-26) + +> Self-bearing grunnlag for den **køede** innboks-ingestion-oppgaven (start **etter** +> OKF-fasen er stengt; egen minor-bump). Speiler rollen `okf-second-brain-note-2026-06.md` +> hadde for OKF-fasen. Alle påstander om Google-repoet er **verifisert mot faktisk lest +> innhold** (kilder i §9) — ikke antakelser. + +## 1. Oppgaven + +Bruker slipper vilkårlige dokumenter (PDF, Word, tekst, e-post) i en **innboks-mappe**. +okr-pluginen skal oppdage dem, konvertere til markdown, og legge dem inn **OKF-kompatibelt** +i second-brain-treet — med korrekt frontmatter (`type/resource/title/description/tags/timestamp`), +`index.md` per nivå, **og relasjoner/kryss-lenker** mellom konsepter. Original beholdes, +markdown-peker plasseres. Søsken-pluginen `ms-ai-architect` har samme oppgave (delt mønster). + +## 2. Hovedkonklusjon + +**Det finnes ingen ferdig innboks→OKF-ingestion-løsning med relasjonshåndtering — verken i +`GoogleCloudPlatform/knowledge-catalog` eller i okr-pluginen.** Google gir oss spec + +gjenbrukbare byggeklosser (index-generator, relasjons-mønster, kilde-utvidelsespunkt), men +**ikke** en pipeline fra «ustrukturert innboks» til «ferdig OKF-bundle». Dette blir et reelt +byggeløp. + +Rammeavklaring (verifisert): «knowledge-catalog» = Google Cloud **Knowledge Catalog (tidl. +Dataplex)** — metadata for *dataassets*. «OKF» (`okf/`) er et eget, vendor-nøytralt +markdown-format. Beslektede, men distinkte spor i repoet. + +## 3. Hva Google-repoet faktisk har + +| Komponent | Sti | Hva det er | Innboks-ingestion? | +|---|---|---|---| +| `reference_agent` | `okf/src/reference_agent/` | OKF-**produsent** (CLI: `enrich`/`visualize`). Auto-genererer `index.md` + auto-vever kryss-lenker | **Delvis** — kun fra **BigQuery + web-crawl**, ingen «ingest folder»-kommando | +| `bundle/index.py` (`regenerate_indexes`) | `okf/src/reference_agent/bundle/` | Kildeagnostisk `index.md`-generator per nivå (LLM-synt. mappebeskrivelser) | Gjenbrukbart | +| `sources/base.py` (`Source`-ABC) | `okf/src/reference_agent/sources/` | Utvidelsespunkt for kilder; eneste impl. er `bq` (`_SOURCES = ("bq",)`) | Utvidelsespunkt — ingen fil-/dokumentkilde finnes | +| `fileskb` / `md-fileset` | `samples/enrichment/src/tools/fileskb/`, `toolbox/enrichment/src/tools/md/` | **Read-only** MCP over en markdown-mappe (`fileset-source`-skill) | Nei — retrieval, antar allerede markdown | +| `enrichment` | `samples/enrichment/`, `toolbox/enrichment/` | Beriker **katalog-metadata** for et BQ-datasett, publiserer til Dataplex | Nei — ikke OKF-output | +| `discovery` | `samples/discovery/SKILL.md` | `knowledge_catalog_discovery_agent` — søk/ranking | Nei — ren retrieval | +| `mdcode` | `toolbox/mdcode/` | Spec + bi-direksjonell sync (`kcmd` pull/push) mot Dataplex | Nei — sync, ikke ingestion | +| `okf/SPEC.md` | `okf/` | OKF v0.1 spec (markdown + frontmatter, `index.md`, `log.md`, kryss-lenker, citations) | Spec | + +## 4. Relasjons-modellen i OKF (verifisert, `okf/SPEC.md` §5, §8) + +- Relasjoner = **vanlige markdown-lenker i body**, IKKE et frontmatter-felt. Anbefalt + bundle-relativ form (`/tables/customers.md`). En lenke er en *uttypet, rettet* relasjon; + *hvilken* relasjon (join/parent/depends-on) bæres av prosaen rundt lenken. +- Citations (§8) = lenker til eksterne kilder. Vieweren beregner «Cited by»-backlinks som + reverserte kanter. +- **Auto-etablering finnes** i `reference_agent` (`prompts/reference_instruction.md` + + `web_ingestion_instruction.md`: mynter `references/joins/__.md`, `references/metrics/.md`, + legger til `# Joins`/`# Metrics`-seksjoner) — men logikken er **skreddersydd for BQ-joins/metrikker + + web-dokumentasjon**, ikke et vilkårlig dokumentkorpus. +- Kontrast: `mdcode` har et eget `EntryLink`-konsept i YAML for *katalog*-relasjoner — separat fra OKF. + +## 5. Gap — hva vi må bygge selv + +1. **Dokument-konvertering** (PDF/Word/e-post/tekst → markdown). Finnes ikke i repoet. De + eneste fil-verktøyene (`fileskb`/`md-fileset`) antar markdown og er read-only. +2. **Konsept-ekstraksjon + frontmatter-tilordning** for vilkårlige dokumenter (splitte til + «konsepter», sette `type/resource/title/description/tags/timestamp`). reference_agent gjør + dette kun for BQ-tabeller. +3. **Generalisert relasjons-oppdagelse** — dagens relasjons-prompt er BQ/web-spesifikk og må + generaliseres til vilkårlige dokumenter. +4. **Innboks-orkestrering** — oppdage nye filer, beholde original + markdown-peker, idempotent + re-kjøring, plassering i riktig nivå av treet. + +## 6. Gjenbrukbart (lener oss på, bygger ikke fra null) + +- **Index-generering:** Vi har allerede `scripts/okf-index.mjs` (Step 6, OKF-fasen) som speiler + Googles `regenerate_indexes` — kildeagnostisk, idempotent. Innboks-pipelinen kan kalle den + etter skriv (samme mønster som `oppsett.md`-tre-skriverne i Step 8). +- **Frontmatter:** `lib/frontmatter.mjs` (parse/skrive) + `scripts/okf-check.mjs` (validering) + fra OKF-fasen dekker skrive- og verifiserings-siden. +- **Kilde-mønster:** Googles `Source`-ABC viser et rent adapter-mønster — en «innboks-kilde» + som lister konsepter fra en mappe kunne mate eksisterende skrive-/index-/kryss-lenke-maskineri. + +## 7. Forbehold / ikke verifisert (verifiseringsplikt) + +- **`kb-search/SKILL.md` ble IKKE funnet** i repoet, til tross for at våre egne planer + (`plan.md:26`, `brief.md:168`) refererer den. Skillene som finnes heter `fileset-source` + (retrieval) og `knowledge_catalog_discovery_agent` (søk). Mulig repoet har endret seg, eller + referansen var unøyaktig. **Ikke kritisk for OKF-fasen** (vår retrieval-SKILL er ferdig og + testet), men korrigerer en navne-antakelse for innboks-løpet. +- Ikke fullt lest: `okf/src/reference_agent/{agent.py, runner.py, tools/*.py}` og + `toolbox/enrichment/src/agent/*`. Kilde-/ingestion-konklusjonen er likevel entydig fra + `cli.py` (`_SOURCES = ("bq",)`), `sources/`-innholdet, og enrichment-README/`enrich.py`. + +## 8. Sekvens / scope + +- **Start: etter OKF-fasen er stengt** (Session 5 release → 1.6.0). Scope-guard: innboks bygger + på OKF-leveransen og er bevisst utsatt — **ikke start før operatør sier fra**. +- Eget Voyage-løp (brief → plan → execute), egen **minor-bump** (1.7.0-kandidat). +- Delt mønster med `ms-ai-architect` — vurder felles abstraksjon før dobbel-implementasjon. + +## 9. Kilder (faktisk lest, etterprøvbart) + +GitHub API-mappelistinger: repo-rot, `okf/`, `samples/`, `toolbox/`, +`okf/src/reference_agent/{prompts,tools,sources,bundle}`, `samples/enrichment/src/{enrichment,tools}`, +`toolbox/enrichment/src/{agent,tools}`, `toolbox/mdcode/{docs,demo}`. + +Rå filer (`raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/`): +`README.md`, `samples/README.md`, `okf/README.md`, `okf/SPEC.md`, +`okf/src/reference_agent/cli.py`, `.../sources/base.py`, `.../prompts/reference_instruction.md`, +`.../prompts/web_ingestion_instruction.md`, `.../bundle/synthesizer.py`, `.../bundle/index.py`, +`samples/enrichment/README.md`, `samples/enrichment/src/enrichment/enrich.py`, +`samples/enrichment/src/tools/fileskb/README.md`, `toolbox/enrichment/README.md`, +`samples/discovery/SKILL.md`, `toolbox/mdcode/docs/spec.md`, `toolbox/mdcode/docs/concept.md`, +`toolbox/mdcode/README.md`. + +Undersøkelse utført 2026-06-26 (Opus-subagent, web-verifisert).