vegard
0a467066ba
Nystart basert på arkitektonisk innsikt fra Sidelinja v1. Koden er ny, visjon og primitiver er validert gjennom tidligere arbeid. Inneholder: - Komplett arkitekturdokumentasjon (docs/arkitektur.md) - 6 vedtatte retninger (docs/retninger/) - Alle concepts, features, proposals og erfaringer fra v1 - Server-oppsett og drift (docs/setup/) - LiteLLM-konfigurasjon (API-nøkler via env) - Editor.svelte referanse fra v1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# Feature: Kunnskaps-Bridge (Cross-Workspace Discovery)
|
|
**Filsti:** `docs/features/kunnskaps_bridge.md`
|
|
|
|
## 1. Konsept
|
|
En valgfri, opt-in feature som lar brukere oppdage semantisk beslektet kunnskap på tvers av workspaces de har tilgang til. Bryter ikke workspace-isolasjonen — resultatet er en *peker* ("dette finnes i Podcast B"), ikke selve innholdet. Brukeren må ha tilgang til begge workspaces for å se treffet.
|
|
|
|
## 2. Avgrensning: Hva dette IKKE er
|
|
- **Ikke datadeling.** Ingen data kopieres mellom workspaces. Bridge viser kun at en relevant node *finnes*.
|
|
- **Ikke automatisk.** Begge workspaces må ha Bridge eksplisitt aktivert av en admin.
|
|
- **Ikke synlig for gjester.** Kun for workspace-medlemmer med tilgang til begge sider.
|
|
- **Ikke et søk i andres data.** Du ser bare treff i workspaces du allerede er medlem av.
|
|
|
|
## 3. Teknisk arkitektur
|
|
|
|
### 3.1 Vector Embeddings (pgvector)
|
|
Krever `pgvector`-extension i PostgreSQL:
|
|
|
|
```sql
|
|
CREATE EXTENSION IF NOT EXISTS vector;
|
|
|
|
ALTER TABLE actors ADD COLUMN embedding vector(768);
|
|
ALTER TABLE topics ADD COLUMN embedding vector(768);
|
|
ALTER TABLE factoids ADD COLUMN embedding vector(768);
|
|
|
|
CREATE INDEX idx_actors_embedding ON actors USING ivfflat (embedding vector_cosine_ops);
|
|
CREATE INDEX idx_topics_embedding ON topics USING ivfflat (embedding vector_cosine_ops);
|
|
CREATE INDEX idx_factoids_embedding ON factoids USING ivfflat (embedding vector_cosine_ops);
|
|
```
|
|
|
|
### 3.2 Embedding-generering (`generate_embeddings`)
|
|
En jobbkø-jobb som genererer embeddings for nye/endrede noder:
|
|
1. Rust-worker plukker opp jobben fra jobbkøen.
|
|
2. Bygger en tekst-representasjon av noden (navn, body, tilknyttede faktoider).
|
|
3. Sender til AI Gateway (`sidelinja/rutine`) for embedding-generering.
|
|
4. Lagrer vektoren i pgvector-kolonnen.
|
|
5. Re-genereres ved vesentlige endringer av noden.
|
|
|
|
### 3.3 Cross-workspace søk
|
|
Når en bruker utforsker en node (f.eks. Tema "Skolepolitikk"):
|
|
1. SvelteKit server-side henter brukerens tilgjengelige workspaces fra `workspace_members`.
|
|
2. Kjører et similarity-søk med `<=>` (cosine distance) **som superuser** (bypasser RLS) — men filtrerer eksplisitt mot brukerens workspace-liste:
|
|
```sql
|
|
SELECT n.workspace_id, t.name, t.embedding <=> $target_embedding AS distance
|
|
FROM topics t
|
|
JOIN nodes n ON t.id = n.id
|
|
WHERE n.workspace_id = ANY($user_workspace_ids)
|
|
AND n.workspace_id != $current_workspace_id
|
|
AND t.embedding <=> $target_embedding < 0.3
|
|
ORDER BY distance
|
|
LIMIT 10;
|
|
```
|
|
3. Resultatet vises som en diskret "Finnes også i..."-seksjon i UI-et.
|
|
|
|
### 3.4 Workspace-config
|
|
Bridge aktiveres per workspace i `workspaces.settings`:
|
|
```json
|
|
{
|
|
"bridge_enabled": true,
|
|
"bridge_discoverable": true
|
|
}
|
|
```
|
|
- `bridge_enabled` — workspace kan søke i andre workspaces
|
|
- `bridge_discoverable` — andre workspaces kan finne noder i dette workspace-et
|
|
|
|
Begge må være `true` for at en kobling skal vises.
|
|
|
|
## 4. Dataklassifisering
|
|
|
|
| Data | Kategori | Detaljer |
|
|
|---|---|---|
|
|
| Embedding-vektorer | Avledet (PG) | Kan regenereres fra nodeinnhold |
|
|
|
|
## 5. Instruks for Claude Code
|
|
* pgvector er en ny avhengighet — dokumenter i docker-compose og setup-guides.
|
|
* Cross-workspace søk er det **eneste** stedet i systemet der bruker-initierte handlinger bypasser RLS. Isolér denne koden grundig — egen funksjon med eksplisitt workspace-filtrering, aldri gjenbruk i andre kontekster.
|
|
* Embedding-dimensjon (768) bør matche modellen som brukes. Konfigurér som konstant, ikke hardkod overalt.
|
|
* Jobbtype `generate_embeddings` bruker `sidelinja/rutine` som modellalias.
|
|
* Bridge er **Lag 4+** — krever fylt kunnskapsgraf i minst to workspaces.
|