knowledge graph

# valoswiss-knowledge-graph

**Macro-categoria**: 🧠 INFRA/AI/META
**Scope**: Knowledge graph advisor↔client↔family↔asset↔transaction con temporal versioning Graphiti-style. Entities + Relationships + Timeline events. Query NL → Cypher fallback. Family relationship state changes versioned. Hybrid retrieval graph traversal + vector similarity.
**Born**: 2026-05-03 (Wave 5 INFRA/AI/META) — extend `family-governance` schema con backbone graph
**Owner downstream**: ADVISOR (client context graph view), SUPERVISOR/ADMIN (cross-tenant graph + ingestion config), agent runtime (advisor-copilot context augmentation, memory-layer entity backbone)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento sul knowledge-graph, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Postgres extension check** (KG su Postgres native, NO Neo4j)
   ```bash
   psql "$DATABASE_URL" -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector','pg_trgm','ltree','intarray');"
   ```
   Atteso `vector >= 0.7.0`, `pg_trgm`, `ltree` (path queries), `intarray` (ID array ops). Se manca → CREATE EXTENSION.
3. **family-governance schema base attivo**
   ```bash
   ls apps/api/src/modules/family-group/family-group.service.ts 2>/dev/null
   psql "$DATABASE_URL" -c "\dt \"FamilyGroup\""
   ```
   Il KG estende `family-governance` — se manca, fermati e documenta dipendenza.
4. **Prisma schema sync** — verifica 4 model `KGEntity` / `KGRelationship` / `KGTimelineEvent` / `KGEntityEmbedding` + 2 enum `KGEntityType` / `KGRelationshipType` migrati
   ```bash
   cd apps/api && npx prisma migrate status | grep -i "kg_\|knowledge"
   ```
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"knowledgeGraph": true` subito dopo `memoryLayer`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'knowledgeGraph'` in `defaultModules` per `ADVISOR`, `SUPERVISOR`, `ADMIN`, `FAMILY_OFFICE_PRINCIPAL`. NON in PROSPECT/CLIENT generic.
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `knowledgeGraph` con `sidebarSection: 'AGENTI & AI'`, `requiredRole: 'ADVISOR'`, icon `🕸️`, `personaHint: 'meta-infrastructure'`.
8. **Backend health endpoint**
   ```bash
   curl -sf http://127.0.0.1:4010/api/kg/health -H "Cookie: valo_token=<dev>" | jq .
   ```
   Atteso `{ status:'ok', entities:N, relationships:M, lastEpisode:'...' }`.
9. **Frontend KGViewer build** — verifica D3 force-directed graph component carica
   ```bash
   ls apps/web/src/app/components/KGViewer.tsx 2>/dev/null
   ```
10. **Pre-commit triage** — verifica HEAD su file CRITICAL non contenga pattern legacy (vedi §7 Wave 1.6).

Se uno qualunque dei 10 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration V16 è invariante non negoziabile.

---

## §1 · Aree di competenza

### 1.1 Modello concettuale (Graphiti temporal episode)

```
ENTITY (nodo)
├── id, tenant_id, type, name, properties JSON
├── createdAt, validFrom, validTo (temporal versioning)
├── embedding (pgvector — semantic search)
└── tags[], metadata JSON

RELATIONSHIP (arco diretto)
├── id, tenant_id, fromEntityId, toEntityId, type
├── properties JSON, weight Float
├── createdAt, validFrom, validTo, supersededBy
└── episodeId (Graphiti pattern — episode che ha generato la relazione)

TIMELINE_EVENT (state-change versioning)
├── id, tenant_id, entityId, eventType, content
├── propertyDeltaBefore JSON, propertyDeltaAfter JSON
├── occurredAt, recordedAt
└── episodeId, sourceDocumentId?
```

### 1.2 Entity types canonical (KGEntityType enum)

| Type | Descrizione | Esempio |
|---|---|---|
| `ADVISOR` | consulente ValoSwiss | "Marco Bianchi, Senior Advisor WS" |
| `CLIENT` | cliente onboarded | "Famiglia Rossi, UHNW, AUM 12M EUR" |
| `PROSPECT` | prospect non ancora cliente | "Lead Q2 2026, source LinkedIn" |
| `FAMILY_GROUP` | aggregazione multi-cliente | "Rossi family group, 5 membri, 3 generazioni" |
| `LEGAL_ENTITY` | persona giuridica struttura | "Rossi Holding SRL, Lussemburgo" |
| `ASSET` | strumento finanziario | "AAPL, ISIN US0378331005" |
| `PORTFOLIO` | portafoglio cliente | "Mario Rossi conservativo 60/40" |
| `TRANSACTION` | movimento storico | "BUY 100 AAPL @ 178.50 on 2026-04-15" |
| `EVENT` | evento vita / mercato | "earnings call AAPL Q2 2026" |
| `DOCUMENT` | documento ingestato | "KYC PDF Rossi Mario 2026" |
| `LOCATION` | giurisdizione | "Lussemburgo", "Singapore" |
| `ORGANIZATION` | banca, fund, broker | "JP Morgan Switzerland", "BlackRock" |

### 1.3 Relationship types canonical (KGRelationshipType enum)

| Type | Direzione semantica | Esempio |
|---|---|---|
| `MANAGES` | ADVISOR → CLIENT | Marco manages Rossi family |
| `MEMBER_OF` | CLIENT → FAMILY_GROUP | Mario member of Rossi |
| `OWNS` | CLIENT → ASSET (via PORTFOLIO) | Mario owns 100 AAPL |
| `OWNS_PCT` | LEGAL_ENTITY → LEGAL_ENTITY | Holding owns 100% SubCo |
| `CONTROLS` | LEGAL_ENTITY → LEGAL_ENTITY | con voting >50% |
| `BENEFICIARY_OF` | CLIENT → LEGAL_ENTITY | Trust beneficiary |
| `TRUSTEE_OF` | CLIENT → LEGAL_ENTITY | trustee role |
| `RELATED_TO` | CLIENT → CLIENT | family relation generic |
| `PARENT_OF` | CLIENT → CLIENT | generazionale |
| `SPOUSE_OF` | CLIENT → CLIENT | bidirezionale |
| `EXECUTED` | CLIENT → TRANSACTION | trade execution |
| `OCCURRED_AT` | EVENT → LOCATION | event geographic |
| `MENTIONED_IN` | ENTITY → DOCUMENT | extraction from doc |
| `DOMICILED_IN` | LEGAL_ENTITY → LOCATION | tax domicile |

### 1.4 Temporal versioning (Graphiti-style)

Ogni `KGRelationship` ha `validFrom` + `validTo`. Quando una relationship cambia stato:
1. **NON** UPDATE la relationship esistente
2. SET `validTo = now()` + `supersededBy = newId` su quella vecchia
3. INSERT nuova relationship con `validFrom = now()`, `validTo = NULL`
4. INSERT `KGTimelineEvent` con `eventType=RELATIONSHIP_CHANGED`, `propertyDeltaBefore/After`

Query "as-of date":
```sql
SELECT * FROM "KGRelationship"
WHERE tenant_id = $1
  AND validFrom <= $asOfDate
  AND (validTo IS NULL OR validTo > $asOfDate);
```

### 1.5 Ingestion sources (Cognee-inspired)

| Source | Pattern | Esempio |
|---|---|---|
| **Family-governance** | hooks su `FamilyProposal.create()` → KGTimelineEvent `PROPOSAL_CREATED` | trigger DB |
| **Document vault** | OCR → LLM extract entities → KGEntity insert + KGRelationship `MENTIONED_IN` | post-upload pipeline |
| **Memory layer** | `LIFE_EVENT` extracted facts → KGTimelineEvent + entity link | sibling agent §1.5 |
| **Trading agents** | TradingDecision finalized → KGTimelineEvent `DECISION_FINALIZED` su entity ASSET | post-decision hook |
| **Portfolio sync** | PortfolioSnapshot daily → bulk insert KGRelationship `OWNS` con `validFrom=now` | cron 04:00 |
| **News briefing** | extracted ticker mentions → KGRelationship `MENTIONED_IN` ASSET→DOCUMENT | news pipeline |
| **Manual advisor input** | UI form `/knowledge-graph/new-relationship` | interactive |

### 1.6 Persona visibility

- **ADVISOR**: vede graph propri client (filter `tenant_id` + ADVISOR-CLIENT relationship via `MANAGES`)
- **SUPERVISOR/ADMIN**: cross-tenant + cross-advisor + ingestion config
- **FAMILY_OFFICE_PRINCIPAL**: vede graph propria famiglia (entity tree + relationships) read-only
- **FAMILY_OFFICE_STAFF**: idem FO_PRINCIPAL ma scope ridotto (no transactions detail)
- **NEXTGEN_HEIR**: vede slice generazionale (entity tree filtered by generation level), no peer transactions
- **CLIENT/PROSPECT generic**: NEGATO (PII cross-cliente potenziale via graph traversal)
- **RELATIONSHIP_MANAGER**: idem ADVISOR

### 1.7 Query patterns

**Pattern 1 — Direct entity lookup**
```
GET /kg/entities/:id → include relationships outgoing+incoming + timeline last 10
```

**Pattern 2 — Graph traversal NL**
```
POST /kg/query
{
  "question": "Quali asset detiene la famiglia Rossi tramite il trust lussemburghese?",
  "maxHops": 4,
  "asOfDate": "2026-05-03"
}
→ NL → Cypher-like query plan → execute traversal → return paths + entities
```

**Pattern 3 — Hybrid retrieval (vector + graph)**
```
1. Embed question → top-K=20 entities by cosine sim
2. Per ogni candidate, expand 2-hop neighbors
3. Score = 0.6 * vector_sim + 0.4 * graph_centrality
4. Return ranked top-10 entity + 2-hop subgraph
```

---

## §2 · Pattern di codice

### 2.1 Service NestJS — KnowledgeGraphService

```typescript
// apps/api/src/modules/knowledge-graph/knowledge-graph.service.ts
import { Injectable, Logger, Optional, NotFoundException } from '@nestjs/common';
import { TenantPrismaService } from '../../common/prisma/tenant-prisma.service';
import { EmbeddingProvider } from '../memory-layer/embedding.provider';
import { KGEntityType, KGRelationshipType } from '@prisma/client';

export interface CreateEntityInput {
  type: KGEntityType;
  name: string;
  properties?: Record<string, unknown>;
  tags?: string[];
  validFrom?: Date;
  embedText?: string;
}

export interface CreateRelationshipInput {
  fromEntityId: string;
  toEntityId: string;
  type: KGRelationshipType;
  properties?: Record<string, unknown>;
  weight?: number;
  validFrom?: Date;
  episodeId?: string;
}

@Injectable()
export class KnowledgeGraphService {
  private readonly logger = new Logger(KnowledgeGraphService.name);

  constructor(
    @Optional() private readonly prisma: TenantPrismaService,
    private readonly embeddings: EmbeddingProvider,
  ) {}

  async createEntity(tenantId: string, actorUserId: string, input: CreateEntityInput) {
    if (!this.prisma) {
      this.logger.warn('TenantPrismaService not available, createEntity skipped');
      return null;
    }
    // explicit getter Wave 1.6 — NO cast as-any on prisma client
    const kgEntity = this.prisma.kgEntity;
    const kgEntityEmbedding = this.prisma.kgEntityEmbedding;

    const entity = await kgEntity.create({
      data: {
        tenant_id: tenantId,
        type: input.type,
        name: input.name,
        properties: input.properties ?? {},
        tags: input.tags ?? [],
        validFrom: input.validFrom ?? new Date(),
        validTo: null,
        createdBy: actorUserId,
      },
    });

    if (input.embedText) {
      try {
        const embedding = await this.embeddings.embed(input.embedText);
        await kgEntityEmbedding.create({
          data: {
            tenant_id: tenantId,
            entityId: entity.id,
            provider: 'voyage-3-large',
            dim: embedding.length,
            embedding,
          },
        });
      } catch (e) {
        this.logger.warn(`embedding failed for entity ${entity.id}: ${(e as Error).message}`);
      }
    }
    return entity;
  }

  async createRelationship(
    tenantId: string,
    actorUserId: string,
    input: CreateRelationshipInput,
  ) {
    if (!this.prisma) return null;
    const kgRelationship = this.prisma.kgRelationship;
    const kgTimelineEvent = this.prisma.kgTimelineEvent;
    const kgEntity = this.prisma.kgEntity;

    // verify endpoints exist + same tenant
    const [from, to] = await Promise.all([
      kgEntity.findFirst({ where: { id: input.fromEntityId, tenant_id: tenantId } }),
      kgEntity.findFirst({ where: { id: input.toEntityId, tenant_id: tenantId } }),
    ]);
    if (!from || !to) {
      throw new NotFoundException('entity not found or cross-tenant violation');
    }

    // close any conflicting active relationship of same type (Graphiti supersession)
    const conflicting = await kgRelationship.findFirst({
      where: {
        tenant_id: tenantId,
        fromEntityId: input.fromEntityId,
        toEntityId: input.toEntityId,
        type: input.type,
        validTo: null,
      },
    });

    const now = new Date();
    const validFrom = input.validFrom ?? now;
    const newRel = await kgRelationship.create({
      data: {
        tenant_id: tenantId,
        fromEntityId

…[truncato — apri il file MD per testo completo]