@pellux/goodvibes-sdk 0.27.2 → 0.27.4

package/dist/_internal/platform/knowledge/extractors.js

@@ -2,6 +2,7 @@ import JSZip from 'jszip';
 import { extname } from 'node:path';
 import { guessMimeType } from '../artifacts/types.js';
 import { extractReadableHtml } from './html-readability.js';
+import { extractPdf } from './pdf-extractor.js';
 const MAX_STRUCTURE_SEARCH_TEXT_CHARS = 128 * 1024;
 function decodeHtmlEntities(value) {
     return value
@@ -306,122 +307,6 @@ function extractYaml(buffer) {
         metadata: {},
     };
 }
-async function extractPdf(buffer) {
-    const parsed = await extractPdfWithPdfJs(buffer);
-    if (parsed)
-        return parsed;
-    return extractPdfRawStreams(buffer);
-}
-async function extractPdfWithPdfJs(buffer) {
-    try {
-        const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
-        const loadingTask = pdfjs.getDocument({
-            data: new Uint8Array(buffer),
-            useSystemFonts: true,
-        });
-        const document = await loadingTask.promise;
-        const pageCount = document.numPages;
-        const pageTexts = [];
-        for (let pageNumber = 1; pageNumber <= pageCount; pageNumber += 1) {
-            const page = await document.getPage(pageNumber);
-            const content = await page.getTextContent();
-            const lines = textContentItemsToLines(content.items);
-            if (lines.length > 0)
-                pageTexts.push(lines.join('\n'));
-            page.cleanup();
-        }
-        await document.destroy();
-        const text = cleanText(pageTexts.join('\n\n'));
-        if (!text)
-            return undefined;
-        const searchText = searchTextPayload(text);
-        return {
-            extractorId: 'pdfjs',
-            format: 'pdf',
-            title: firstNonEmptyLine(text) ?? 'PDF document',
-            summary: summarizeText(text) ?? 'PDF document.',
-            excerpt: excerptText(text),
-            sections: uniqueStrings(text.split(/\n+/), 24),
-            links: uniqueStrings(Array.from(text.matchAll(/\bhttps?:\/\/[^\s)]+/g), (match) => match[0]), 50),
-            estimatedTokens: estimateTokens(text),
-            structure: {
-                pageCount,
-                extractedTextChars: text.length,
-                ...(searchText ? { searchText } : {}),
-            },
-            metadata: {
-                limitations: ['PDF text extraction does not perform OCR for scanned images.'],
-            },
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-function textContentItemsToLines(items) {
-    const lines = [];
-    let current = '';
-    for (const item of items) {
-        const record = unknownRecord(item);
-        const text = typeof record.str === 'string' ? cleanText(record.str) : '';
-        if (text)
-            current = current ? `${current} ${text}` : text;
-        if (record.hasEOL === true && current) {
-            lines.push(current);
-            current = '';
-        }
-    }
-    if (current)
-        lines.push(current);
-    return lines;
-}
-function unknownRecord(value) {
-    return value && typeof value === 'object' ? value : {};
-}
-function extractPdfRawStreams(buffer) {
-    const body = buffer.toString('latin1');
-    const texts = [];
-    const streamRe = /stream\r?\n([\s\S]*?)\r?\nendstream/g;
-    let match;
-    while ((match = streamRe.exec(body)) !== null) {
-        const chunk = match[1];
-        const parenRe = /\(([^)\\]*(?:\\.[^)\\]*)*)\)/g;
-        let textMatch;
-        while ((textMatch = parenRe.exec(chunk)) !== null) {
-            const text = cleanText(textMatch[1]
-                .replace(/\\n/g, '\n')
-                .replace(/\\r/g, '\r')
-                .replace(/\\t/g, '\t')
-                .replace(/\\\\/g, '\\')
-                .replace(/\\\(/g, '(')
-                .replace(/\\\)/g, ')'));
-            if (text.length > 1)
-                texts.push(text);
-        }
-    }
-    const combined = uniqueStrings(texts, 64).join('\n');
-    const searchable = uniqueStrings(texts, 512).join('\n');
-    const searchText = searchTextPayload(searchable);
-    return {
-        extractorId: 'pdf',
-        format: 'pdf',
-        title: firstNonEmptyLine(combined) ?? 'PDF document',
-        summary: summarizeText(combined) ?? 'PDF extraction produced limited text; OCR is not used in-core.',
-        excerpt: excerptText(combined),
-        sections: uniqueStrings(combined.split(/\n+/), 8),
-        links: uniqueStrings(Array.from(combined.matchAll(/\bhttps?:\/\/[^\s)]+/g), (match) => match[0]), 50),
-        estimatedTokens: estimateTokens(combined),
-        structure: {
-            extractedStringCount: texts.length,
-            ...(searchText ? { searchText } : {}),
-        },
-        metadata: {
-            limitations: texts.length === 0
-                ? ['No readable text streams were found. Complex PDFs need OCR or a dedicated provider.']
-                : ['PDF extraction is best-effort and does not use OCR.'],
-        },
-    };
-}
 async function extractDocx(buffer) {
     const zip = await JSZip.loadAsync(buffer);
     const file = zip.file('word/document.xml');

package/dist/_internal/platform/knowledge/home-graph/ask.d.ts

@@ -0,0 +1,13 @@
+import type { KnowledgeSemanticService } from '../semantic/index.js';
+import type { KnowledgeStore } from '../store.js';
+import type { HomeGraphAskInput, HomeGraphAskResult, HomeGraphSearchResult } from './types.js';
+import type { HomeGraphSearchState } from './search.js';
+export declare function answerHomeGraphQuery(input: {
+    readonly store: KnowledgeStore;
+    readonly semanticService?: KnowledgeSemanticService;
+    readonly spaceId: string;
+    readonly query: HomeGraphAskInput;
+    readonly state: HomeGraphSearchState;
+    readonly results: readonly HomeGraphSearchResult[];
+}): Promise<HomeGraphAskResult>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/_internal/platform/knowledge/home-graph/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/ask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,wBAAwB,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoD9B"}

package/dist/_internal/platform/knowledge/home-graph/ask.js

@@ -0,0 +1,65 @@
+import { collectLinkedObjects, renderAskAnswer } from './state.js';
+export async function answerHomeGraphQuery(input) {
+    const sources = input.results.flatMap((result) => result.source ? [result.source] : []);
+    const linkedObjects = collectLinkedObjects(input.results, input.state);
+    if (input.semanticService) {
+        await input.semanticService.enrichSources(uniqueSources(sources), {
+            knowledgeSpaceId: input.spaceId,
+            limit: Math.min(3, Math.max(1, sources.length)),
+        });
+        const answer = await input.semanticService.answer({
+            query: input.query.query,
+            knowledgeSpaceId: input.spaceId,
+            mode: input.query.mode ?? 'standard',
+            limit: input.query.limit ?? 8,
+            includeSources: input.query.includeSources,
+            includeConfidence: input.query.includeConfidence,
+            includeLinkedObjects: input.query.includeLinkedObjects,
+            candidateSourceIds: sources.map((source) => source.id),
+            candidateNodeIds: input.results.flatMap((result) => result.node ? [result.node.id] : []),
+            linkedObjects,
+            noMatchMessage: `No Home Graph knowledge matched "${input.query.query}".`,
+        });
+        return {
+            ok: true,
+            spaceId: input.spaceId,
+            query: input.query.query,
+            answer: {
+                text: answer.answer.text,
+                mode: answer.answer.mode,
+                confidence: answer.answer.confidence,
+                sources: answer.answer.sources,
+                linkedObjects: answer.answer.linkedObjects,
+                facts: answer.answer.facts,
+                gaps: answer.answer.gaps,
+                synthesized: answer.answer.synthesized,
+            },
+            results: input.results,
+        };
+    }
+    const confidence = Math.min(100, Math.max(10, input.results[0]?.score ?? 10));
+    return {
+        ok: true,
+        spaceId: input.spaceId,
+        query: input.query.query,
+        answer: {
+            text: renderAskAnswer(input.query.query, input.results, input.query.mode ?? 'standard'),
+            mode: input.query.mode ?? 'standard',
+            confidence,
+            sources: input.query.includeSources === false ? [] : sources,
+            linkedObjects: input.query.includeLinkedObjects === false ? [] : linkedObjects,
+        },
+        results: input.results,
+    };
+}
+function uniqueSources(sources) {
+    const seen = new Set();
+    const out = [];
+    for (const source of sources) {
+        if (seen.has(source.id))
+            continue;
+        seen.add(source.id);
+        out.push(source);
+    }
+    return out;
+}

package/dist/_internal/platform/knowledge/home-graph/auto-link.d.ts

@@ -0,0 +1,27 @@
+import type { KnowledgeStore } from '../store.js';
+import type { KnowledgeEdgeRecord, KnowledgeExtractionRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import type { HomeGraphState } from './state.js';
+export interface HomeGraphAutoLinkResult {
+    readonly edge: KnowledgeEdgeRecord;
+    readonly node: KnowledgeNodeRecord;
+    readonly relation: string;
+    readonly score: number;
+    readonly reasons: readonly string[];
+}
+export declare function autoLinkHomeGraphSource(input: {
+    readonly store: KnowledgeStore;
+    readonly spaceId: string;
+    readonly installationId: string;
+    readonly source: KnowledgeSourceRecord;
+    readonly extraction?: KnowledgeExtractionRecord;
+    readonly state: HomeGraphState;
+}): Promise<HomeGraphAutoLinkResult | undefined>;
+export declare function autoLinkHomeGraphSources(input: {
+    readonly store: KnowledgeStore;
+    readonly spaceId: string;
+    readonly installationId: string;
+    readonly sources: readonly KnowledgeSourceRecord[];
+    readonly extractionBySourceId: ReadonlyMap<string, KnowledgeExtractionRecord>;
+    readonly state: HomeGraphState;
+}): Promise<readonly HomeGraphAutoLinkResult[]>;
+//# sourceMappingURL=auto-link.d.ts.map

package/dist/_internal/platform/knowledge/home-graph/auto-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-link.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/auto-link.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAQrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CA2B/C;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IAC9E,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAiB9C"}

package/dist/_internal/platform/knowledge/home-graph/auto-link.js

@@ -0,0 +1,236 @@
+import { buildHomeGraphMetadata, edgeIsActive, isGeneratedPageSource, readRecord, uniqueStrings, } from './helpers.js';
+const MIN_AUTO_LINK_SCORE = 90;
+const MIN_SOURCE_TEXT_CHARS = 16;
+const MAX_TEXT_FIELD_CHARS = 32_768;
+const GENERIC_TOKENS = new Set(['device', 'home', 'assistant', 'smart', 'manual', 'owner', 'guide', 'user', 'the']);
+export async function autoLinkHomeGraphSource(input) {
+    if (isGeneratedPageSource(input.source) || shouldSkipAutoLink(input.source))
+        return undefined;
+    if (hasActiveSourceLink(input.source.id, input.state.edges))
+        return undefined;
+    const candidates = scoreCandidates(input.source, input.extraction, input.state);
+    const best = candidates[0];
+    if (!best || best.score < MIN_AUTO_LINK_SCORE)
+        return undefined;
+    const next = candidates[1];
+    if (next && best.score - next.score < 20 && !best.reasons.some((reason) => reason.startsWith('exact-model:'))) {
+        return undefined;
+    }
+    const relation = inferRelation(input.source);
+    const edge = await input.store.upsertEdge({
+        fromKind: 'source',
+        fromId: input.source.id,
+        toKind: 'node',
+        toId: best.node.id,
+        relation,
+        weight: Math.min(5, Math.max(1, Math.round(best.score / 60))),
+        metadata: buildHomeGraphMetadata(input.spaceId, input.installationId, {
+            linkStatus: 'active',
+            linkMethod: 'homegraph-auto-link',
+            autoLinkedAt: Date.now(),
+            autoLinkScore: best.score,
+            autoLinkReasons: best.reasons,
+        }),
+    });
+    return { edge, node: best.node, relation, score: best.score, reasons: best.reasons };
+}
+export async function autoLinkHomeGraphSources(input) {
+    const linked = [];
+    for (const source of input.sources) {
+        const result = await autoLinkHomeGraphSource({
+            store: input.store,
+            spaceId: input.spaceId,
+            installationId: input.installationId,
+            source,
+            extraction: input.extractionBySourceId.get(source.id),
+            state: {
+                ...input.state,
+                edges: [...input.state.edges, ...linked.map((entry) => entry.edge)],
+            },
+        });
+        if (result)
+            linked.push(result);
+    }
+    return linked;
+}
+function scoreCandidates(source, extraction, state) {
+    const sourceText = sourceEvidenceText(source, extraction);
+    if (sourceText.length < MIN_SOURCE_TEXT_CHARS)
+        return [];
+    const lower = sourceText.toLowerCase();
+    const sourceTokens = new Set(tokenize(sourceText));
+    return state.nodes
+        .filter((node) => isAutoLinkCandidateNode(node))
+        .map((node) => {
+        const reasons = [];
+        let score = 0;
+        const identity = nodeIdentity(node, state);
+        for (const model of identity.models) {
+            if (model.length >= 4 && includesIdentity(lower, model)) {
+                score += model.length >= 8 ? 180 : 120;
+                reasons.push(`exact-model:${model}`);
+            }
+        }
+        for (const entityId of identity.entityIds) {
+            if (includesIdentity(lower, entityId)) {
+                score += 140;
+                reasons.push(`entity-id:${entityId}`);
+            }
+        }
+        for (const deviceId of identity.deviceIds) {
+            if (includesIdentity(lower, deviceId)) {
+                score += 120;
+                reasons.push(`device-id:${deviceId}`);
+            }
+        }
+        const titleTokens = tokenize(node.title).filter((token) => !isGenericToken(token));
+        const overlap = titleTokens.filter((token) => sourceTokens.has(token));
+        if (overlap.length > 0) {
+            score += overlap.reduce((sum, token) => sum + (token.length <= 3 ? 12 : 18), 0);
+            reasons.push(`title:${overlap.slice(0, 5).join(',')}`);
+        }
+        const manufacturerMatches = identity.manufacturers.filter((manufacturer) => includesIdentity(lower, manufacturer));
+        if (manufacturerMatches.length > 0) {
+            score += 28;
+            reasons.push(`manufacturer:${manufacturerMatches[0]}`);
+        }
+        const relatedEntityMatches = identity.relatedEntityTokens.filter((token) => sourceTokens.has(token));
+        if (relatedEntityMatches.length > 0) {
+            score += Math.min(50, relatedEntityMatches.length * 10);
+            reasons.push(`related-entity:${relatedEntityMatches.slice(0, 5).join(',')}`);
+        }
+        if (node.kind === 'ha_device' && isManualLikeSource(source))
+            score += 16;
+        if (node.kind === 'ha_integration' && isIntegrationDocumentationSource(source))
+            score += 40;
+        if (node.kind === 'ha_integration' && isManualLikeSource(source))
+            score -= 45;
+        return { node, score, reasons };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((left, right) => right.score - left.score || left.node.id.localeCompare(right.node.id));
+}
+function shouldSkipAutoLink(source) {
+    const kind = typeof source.metadata.homeGraphSourceKind === 'string' ? source.metadata.homeGraphSourceKind : '';
+    return kind === 'snapshot' || kind === 'generated-page';
+}
+function hasActiveSourceLink(sourceId, edges) {
+    return edges.some((edge) => edgeIsActive(edge) && ((edge.fromKind === 'source' && edge.fromId === sourceId && edge.toKind === 'node')
+        || (edge.fromKind === 'node' && edge.toKind === 'source' && edge.toId === sourceId)));
+}
+function isAutoLinkCandidateNode(node) {
+    return node.kind === 'ha_device'
+        || node.kind === 'ha_entity'
+        || node.kind === 'ha_integration'
+        || node.kind === 'ha_area'
+        || node.kind === 'ha_room';
+}
+function sourceEvidenceText(source, extraction) {
+    const structure = readRecord(extraction?.structure);
+    return uniqueStrings([
+        source.title,
+        source.summary,
+        source.description,
+        source.sourceUri,
+        source.canonicalUri,
+        source.tags.join(' '),
+        extraction?.title,
+        extraction?.summary,
+        extraction?.excerpt,
+        ...(extraction?.sections ?? []),
+        readString(structure.searchText),
+    ]).join('\n').slice(0, MAX_TEXT_FIELD_CHARS);
+}
+function nodeIdentity(node, state) {
+    const homeAssistant = readRecord(node.metadata.homeAssistant);
+    const relatedEntities = node.kind === 'ha_device'
+        ? relatedEntityNodes(node.id, state)
+        : [];
+    return {
+        models: uniqueStrings([
+            readString(node.metadata.model),
+            readString(node.metadata.modelId),
+            readString(node.metadata.model_id),
+        ]),
+        manufacturers: uniqueStrings([
+            readString(node.metadata.manufacturer),
+            readString(node.metadata.vendor),
+        ]),
+        entityIds: uniqueStrings([
+            readString(homeAssistant.entityId),
+            ...relatedEntities.map((entity) => readString(readRecord(entity.metadata.homeAssistant).entityId)),
+        ]),
+        deviceIds: uniqueStrings([
+            readString(homeAssistant.deviceId),
+            node.kind === 'ha_device' ? readString(homeAssistant.objectId) : undefined,
+        ]),
+        relatedEntityTokens: uniqueStrings(relatedEntities.flatMap((entity) => [
+            ...tokenize(entity.title),
+            ...tokenize(readString(readRecord(entity.metadata.homeAssistant).entityId) ?? ''),
+            readString(entity.metadata.domain),
+            readString(entity.metadata.platform),
+        ])),
+    };
+}
+function relatedEntityNodes(deviceNodeId, state) {
+    const entityIds = new Set(state.edges.filter((edge) => (edgeIsActive(edge)
+        && edge.fromKind === 'node'
+        && edge.toKind === 'node'
+        && edge.toId === deviceNodeId
+        && edge.relation === 'belongs_to_device')).map((edge) => edge.fromId));
+    return state.nodes.filter((node) => entityIds.has(node.id) && node.kind === 'ha_entity');
+}
+function inferRelation(source) {
+    const tags = source.tags.map((tag) => tag.toLowerCase());
+    const text = [source.sourceType, source.title, source.sourceUri, ...tags].join(' ').toLowerCase();
+    if (text.includes('receipt'))
+        return 'has_receipt';
+    if (text.includes('warranty'))
+        return 'has_warranty';
+    if (isManualLikeSource(source))
+        return 'has_manual';
+    return 'source_for';
+}
+function isManualLikeSource(source) {
+    const tags = source.tags.map((tag) => tag.toLowerCase());
+    const text = [source.sourceType, source.title, source.sourceUri, ...tags].join(' ').toLowerCase();
+    return source.sourceType === 'manual'
+        || tags.includes('manual')
+        || tags.includes('artifact')
+        || tags.includes('document')
+        || /\bmanual\b|\.pdf\b|owner.?s guide|user guide/.test(text);
+}
+function isIntegrationDocumentationSource(source) {
+    const tags = source.tags.map((tag) => tag.toLowerCase());
+    const kind = typeof source.metadata.homeGraphSourceKind === 'string'
+        ? source.metadata.homeGraphSourceKind.toLowerCase()
+        : '';
+    return tags.includes('integration') || tags.includes('documentation') || kind === 'documentation-candidate';
+}
+function tokenize(value) {
+    return uniqueStrings(value.toLowerCase().split(/[^a-z0-9_.:-]+/).filter((token) => token.length >= 2));
+}
+function isGenericToken(value) {
+    return GENERIC_TOKENS.has(value);
+}
+function includesIdentity(haystack, identity) {
+    const normalized = identity.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (/^[a-z0-9_.:-]+$/.test(normalized)) {
+        return new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(normalized)}(?:$|[^a-z0-9])`).test(haystack);
+    }
+    return haystack.includes(normalized);
+}
+function readString(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/_internal/platform/knowledge/home-graph/generated-pages.d.ts

@@ -10,6 +10,7 @@ interface HomeGraphPageContext {
 export declare function generateAutomaticHomeGraphPages(context: HomeGraphPageContext & {
     readonly input: HomeGraphSnapshotInput;
 }): Promise<HomeGraphGeneratedPagesSummary>;
+export declare function refreshAutomaticHomeGraphPages(context: HomeGraphPageContext): Promise<HomeGraphGeneratedPagesSummary>;
 export declare function refreshHomeGraphDevicePassport(context: HomeGraphPageContext & {
     readonly input: HomeGraphProjectionInput;
 }): Promise<HomeGraphDevicePassportResult & {

package/dist/_internal/platform/knowledge/home-graph/generated-pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generated-pages.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/generated-pages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA8BlD,OAAO,KAAK,EACV,6BAA6B,EAC7B,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,GACzE,OAAO,CAAC,8BAA8B,CAAC,CAoEzC;AAED,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,6BAA6B,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CA0EhF;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,yBAAyB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CAsC5E;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,yBAAyB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CAyB5E"}
+{"version":3,"file":"generated-pages.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/generated-pages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA8BlD,OAAO,KAAK,EACV,6BAA6B,EAC7B,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,GACzE,OAAO,CAAC,8BAA8B,CAAC,CAEzC;AAED,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,8BAA8B,CAAC,CAEzC;AA2ED,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,6BAA6B,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CA2EhF;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,yBAAyB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CAsC5E;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,oBAAoB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC3E,OAAO,CAAC,yBAAyB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CAyB5E"}

package/dist/_internal/platform/knowledge/home-graph/generated-pages.js

@@ -3,13 +3,19 @@ import { HOME_GRAPH_CONNECTOR_ID, buildHomeGraphMetadata, edgeIsActive, homeGrap
 import { findHomeAssistantNode, missingDevicePassportFields, readHomeGraphState, renderHomeGraphState, safeHomeGraphFilename, sourcesLinkedToNode, } from './state.js';
 import { renderDevicePassportPage, renderPacketPage, renderRoomPage, } from './rendering.js';
 export async function generateAutomaticHomeGraphPages(context) {
-    const options = context.input.pageAutomation ?? {};
+    return generateHomeGraphPagesForCurrentState(context, context.input.pageAutomation ?? {});
+}
+export async function refreshAutomaticHomeGraphPages(context) {
+    return generateHomeGraphPagesForCurrentState(context, {});
+}
+async function generateHomeGraphPagesForCurrentState(context, options) {
+    const effectiveOptions = options ?? {};
     const summary = createGeneratedPagesSummary();
-    if (options.enabled === false)
+    if (effectiveOptions.enabled === false)
         return summary;
     const state = readHomeGraphState(context.store, context.spaceId);
-    if (options.devicePassports !== false) {
-        const devices = limitRecords(state.nodes.filter((node) => node.kind === 'ha_device' && node.status !== 'stale').sort(compareByTitle), options.maxDevicePassports);
+    if (effectiveOptions.devicePassports !== false) {
+        const devices = limitRecords(state.nodes.filter((node) => node.kind === 'ha_device' && node.status !== 'stale').sort(compareByTitle), effectiveOptions.maxDevicePassports);
         for (const device of devices) {
             const deviceId = readHomeAssistantObjectId(device, 'objectId', 'deviceId') ?? device.id;
             try {
@@ -36,10 +42,10 @@ export async function generateAutomaticHomeGraphPages(context) {
             }
         }
     }
-    if (options.roomPages !== false) {
+    if (effectiveOptions.roomPages !== false) {
         const rooms = limitRecords(state.nodes
             .filter((node) => (node.kind === 'ha_area' || node.kind === 'ha_room') && node.status !== 'stale')
-            .sort(compareByTitle), options.maxRoomPages);
+            .sort(compareByTitle), effectiveOptions.maxRoomPages);
         for (const room of rooms) {
             const areaId = readHomeAssistantObjectId(room, 'objectId', 'areaId') ?? room.id;
             try {
@@ -84,6 +90,7 @@ export async function refreshHomeGraphDevicePassport(context) {
         && edge.toId === device.id
         && edge.relation === 'belongs_to_device'))));
     const sources = sourcesLinkedToNode(device.id, state).filter((source) => !isGeneratedPageSource(source));
+    const semanticFacts = semanticFactsLinkedToSources(sources, state.nodes, state.edges);
     const issues = state.issues.filter((issue) => issue.nodeId === device.id);
     const missingFields = missingDevicePassportFields(device, sources);
     const passport = await store.upsertNode({
@@ -109,7 +116,7 @@ export async function refreshHomeGraphDevicePassport(context) {
         relation: 'source_for',
         metadata: buildHomeGraphMetadata(spaceId, installationId),
     });
-    const markdown = renderDevicePassportPage({ spaceId, device, entities, sources, issues, missingFields });
+    const markdown = renderDevicePassportPage({ spaceId, device, entities, sources, extractions: state.extractions, issues, missingFields, semanticFacts });
     const generated = await materializeGeneratedMarkdown({
         store,
         artifactStore,
@@ -147,7 +154,7 @@ export async function generateHomeGraphRoomPage(context) {
     const state = readHomeGraphState(store, spaceId);
     const areaId = input.areaId ?? input.roomId;
     const title = input.title ?? resolveRoomTitle(state.nodes, areaId) ?? 'Home Graph Room';
-    const markdown = renderRoomPage({ ...state, title }, areaId);
+    const markdown = renderRoomPage({ ...state, title, extractions: state.extractions }, areaId);
     const filename = `${safeHomeGraphFilename(title)}.md`;
     const targetNode = areaId
         ? findHomeAssistantNode(state.nodes, 'ha_area', areaId) ?? findHomeAssistantNode(state.nodes, 'ha_room', areaId)
@@ -272,6 +279,15 @@ function createGeneratedPagesSummary() {
 function compareByTitle(left, right) {
     return left.title.localeCompare(right.title) || left.id.localeCompare(right.id);
 }
+function semanticFactsLinkedToSources(sources, nodes, edges) {
+    const sourceIds = new Set(sources.map((source) => source.id));
+    const factIds = new Set(edges.filter((edge) => (edgeIsActive(edge)
+        && edge.fromKind === 'source'
+        && sourceIds.has(edge.fromId)
+        && edge.toKind === 'node'
+        && edge.relation === 'supports_fact')).map((edge) => edge.toId));
+    return nodes.filter((node) => factIds.has(node.id));
+}
 function limitRecords(records, limit) {
     if (typeof limit !== 'number')
         return records;

package/dist/_internal/platform/knowledge/home-graph/index.d.ts

@@ -1,4 +1,4 @@
 export { HomeGraphService } from './service.js';
 export { HOME_GRAPH_NODE_KINDS, HOME_GRAPH_RELATIONS, } from './types.js';
-export type { HomeGraphAskInput, HomeGraphAskResult, HomeGraphDevicePassportResult, HomeGraphExport, HomeGraphGeneratedPagesSummary, HomeGraphIngestArtifactInput, HomeGraphIngestNoteInput, HomeGraphIngestResult, HomeGraphIngestUrlInput, HomeGraphKnowledgeTarget, HomeGraphLinkInput, HomeGraphLinkResult, HomeGraphMapEdge, HomeGraphMapHaFilterInput, HomeGraphMapInput, HomeGraphMapNode, HomeGraphMapResult, HomeGraphNodeKind, HomeGraphObjectInput, HomeGraphObjectKind, HomeGraphPageAutomationOptions, HomeGraphProjectionInput, HomeGraphProjectionResult, HomeGraphReindexResult, HomeGraphRelation, HomeGraphReviewInput, HomeGraphSnapshotInput, HomeGraphStatus, HomeGraphSyncResult, } from './types.js';
+export type { HomeGraphAskInput, HomeGraphAskResult, HomeGraphDevicePassportResult, HomeGraphExport, HomeGraphGeneratedPagesSummary, HomeGraphIngestArtifactInput, HomeGraphIngestNoteInput, HomeGraphIngestResult, HomeGraphIngestUrlInput, HomeGraphKnowledgeTarget, HomeGraphLinkInput, HomeGraphLinkResult, HomeGraphMapEdge, HomeGraphMapHaFilterInput, HomeGraphMapInput, HomeGraphMapNode, HomeGraphMapResult, HomeGraphNodeKind, HomeGraphObjectInput, HomeGraphObjectKind, HomeGraphPageAutomationOptions, HomeGraphPageListResult, HomeGraphProjectionInput, HomeGraphProjectionResult, HomeGraphReindexResult, HomeGraphRelation, HomeGraphReviewInput, HomeGraphSnapshotInput, HomeGraphStatus, HomeGraphSyncResult, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/knowledge/home-graph/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,6BAA6B,EAC7B,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,6BAA6B,EAC7B,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC9B,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/_internal/platform/knowledge/home-graph/pages.d.ts

@@ -0,0 +1,11 @@
+import type { ArtifactStore } from '../../artifacts/index.js';
+import type { KnowledgeSourceRecord } from '../types.js';
+import type { HomeGraphPageListResult } from './types.js';
+export declare function listHomeGraphPages(input: {
+    readonly artifactStore: ArtifactStore;
+    readonly spaceId: string;
+    readonly sources: readonly KnowledgeSourceRecord[];
+    readonly limit: number;
+    readonly includeMarkdown: boolean;
+}): Promise<HomeGraphPageListResult>;
+//# sourceMappingURL=pages.d.ts.map

package/dist/_internal/platform/knowledge/home-graph/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/pages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA0BnC"}

package/dist/_internal/platform/knowledge/home-graph/pages.js

@@ -0,0 +1,44 @@
+import { isGeneratedPageSource } from './helpers.js';
+export async function listHomeGraphPages(input) {
+    const pages = [];
+    const sources = input.sources
+        .filter(isGeneratedPageSource)
+        .sort(compareGeneratedPages)
+        .slice(0, input.limit);
+    for (const source of sources) {
+        const artifact = typeof source.artifactId === 'string' ? input.artifactStore.get(source.artifactId) : undefined;
+        const markdown = input.includeMarkdown && artifact
+            ? await readMarkdown(input.artifactStore, artifact.id)
+            : undefined;
+        pages.push({
+            source,
+            ...(artifact ? {
+                artifact: {
+                    id: artifact.id,
+                    mimeType: artifact.mimeType,
+                    filename: artifact.filename,
+                    createdAt: artifact.createdAt,
+                    metadata: artifact.metadata,
+                },
+            } : {}),
+            ...(markdown ? { markdown } : {}),
+        });
+    }
+    return { ok: true, spaceId: input.spaceId, pages };
+}
+function compareGeneratedPages(left, right) {
+    const leftKind = typeof left.metadata.projectionKind === 'string' ? left.metadata.projectionKind : '';
+    const rightKind = typeof right.metadata.projectionKind === 'string' ? right.metadata.projectionKind : '';
+    return leftKind.localeCompare(rightKind)
+        || (left.title ?? left.id).localeCompare(right.title ?? right.id)
+        || left.id.localeCompare(right.id);
+}
+async function readMarkdown(artifactStore, artifactId) {
+    try {
+        const { buffer } = await artifactStore.readContent(artifactId);
+        return buffer.toString('utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}