open/okr

Kjell Tore Guttormsen 80d96898bc docs(okr): innboks-ingestion funn-grunnlag (web-verifisert)

Self-bearing grunnlag for den koeede innboks-ingestion-oppgaven (start etter
OKF-fasen). Web-verifisert undersoekelse av GoogleCloudPlatform/knowledge-catalog:
ingen ferdig innboks->OKF-pipeline finnes (verken Google eller oss). Dokumenterer
hva som finnes (reference_agent/index-generator/Source-ABC/fileskb), OKF-relasjons-
modellen (markdown-lenker i body), gap (dok-konvertering + konsept-ekstraksjon +
generalisert relasjons-oppdagelse), gjenbrukbare byggeklosser, og kilder for
etterproevbarhet. STATE I-koe-peker oppdatert (local-only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFW5scLL7oEwWWTv1fPQG6

2026-06-26 18:03:55 +02:00

7.2 KiB

Raw Blame History

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/<a>__<b>.md, references/metrics/<slug>.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

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.
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.
Generalisert relasjons-oppdagelse — dagens relasjons-prompt er BQ/web-spesifikk og må generaliseres til vilkårlige dokumenter.
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).

7.2 KiB Raw Blame History