@pellux/goodvibes-sdk 0.26.6 → 0.26.8

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

@@ -0,0 +1,278 @@
+import { buildIssue, readRecord, stableHash, uniqueStrings } from './helpers.js';
+import { readHomeGraphState, sourcesLinkedToNode } from './state.js';
+const QUALITY_NAMESPACE_PREFIX = 'homegraph';
+const EXCLUDED_SOFTWARE_TERMS = [
+    'add-on',
+    'addon',
+    'automation',
+    'cloud',
+    'core',
+    'helper',
+    'home assistant',
+    'integration',
+    'operating system',
+    'scene',
+    'script',
+    'service',
+    'software',
+    'supervisor',
+    'template',
+    'virtual',
+];
+const EXCLUDED_INFRASTRUCTURE_TERMS = [
+    'adapter',
+    'bridge',
+    'coordinator',
+    'dongle',
+    'gateway',
+    'hub',
+];
+const EXCLUDED_MAINS_TERMS = [
+    'air conditioner',
+    'appliance',
+    'bulb',
+    'dishwasher',
+    'dryer',
+    'furnace',
+    'heat pump',
+    'hvac',
+    'light',
+    'microwave',
+    'outlet',
+    'plug',
+    'power strip',
+    'receiver',
+    'refrigerator',
+    'soundbar',
+    'speaker',
+    'switch',
+    'television',
+    'tv',
+    'washer',
+];
+const BATTERY_EVIDENCE_TERMS = [
+    'battery',
+    'battery powered',
+    'button cell',
+    'cr123',
+    'cr2032',
+    'keypad',
+    'leak sensor',
+    'lithium',
+    'motion sensor',
+    'remote',
+    'rechargeable',
+];
+const BATTERY_ENTITY_DOMAINS = new Set(['binary_sensor', 'lock', 'remote']);
+const BATTERY_DEVICE_CLASSES = new Set([
+    'battery',
+    'door',
+    'gas',
+    'moisture',
+    'motion',
+    'occupancy',
+    'opening',
+    'safety',
+    'smoke',
+    'tamper',
+    'vibration',
+    'window',
+]);
+const MANUAL_ENTITY_DOMAINS = new Set([
+    'alarm_control_panel',
+    'binary_sensor',
+    'camera',
+    'climate',
+    'cover',
+    'fan',
+    'humidifier',
+    'light',
+    'lock',
+    'media_player',
+    'remote',
+    'sensor',
+    'switch',
+    'vacuum',
+    'water_heater',
+]);
+export function homeGraphQualityNamespace(spaceId) {
+    return `${QUALITY_NAMESPACE_PREFIX}:${spaceId}:quality`;
+}
+export async function refreshHomeGraphQualityIssues(store, spaceId, installationId) {
+    const state = readHomeGraphState(store, spaceId);
+    const issues = [];
+    for (const node of state.nodes) {
+        if (node.kind !== 'ha_device')
+            continue;
+        if (sourcesLinkedToNode(node.id, state).length === 0 && shouldRequireManual(node, state)) {
+            issues.push(qualityIssue(spaceId, installationId, 'homegraph.device.missing_manual', `${node.title} has no linked manual or source.`, node));
+        }
+        if (shouldRequireBatteryType(node, state)) {
+            issues.push(qualityIssue(spaceId, installationId, 'homegraph.device.unknown_battery', `${node.title} has no known battery type.`, node));
+        }
+    }
+    return store.replaceIssues(issues.filter((issue) => !isSuppressedGeneratedIssue(store.getIssue(issue.id), issue)), homeGraphQualityNamespace(spaceId));
+}
+function qualityIssue(spaceId, installationId, code, message, node) {
+    const issue = buildIssue(spaceId, installationId, code, message, { nodeId: node.id });
+    return {
+        ...issue,
+        metadata: {
+            ...(issue.metadata ?? {}),
+            generated: true,
+            subjectFingerprint: subjectFingerprint(node, code),
+        },
+    };
+}
+function isSuppressedGeneratedIssue(existing, input) {
+    if (!existing || existing.status !== 'resolved')
+        return false;
+    const existingFingerprint = typeof existing.metadata.subjectFingerprint === 'string'
+        ? existing.metadata.subjectFingerprint
+        : undefined;
+    const inputFingerprint = typeof input.metadata?.subjectFingerprint === 'string'
+        ? input.metadata.subjectFingerprint
+        : undefined;
+    return existingFingerprint === inputFingerprint;
+}
+function shouldRequireBatteryType(node, state) {
+    if (readNonEmptyString(node.metadata.batteryType))
+        return false;
+    const powered = readBooleanLike(node.metadata.batteryPowered);
+    if (powered === false)
+        return false;
+    if (powered === true)
+        return true;
+    if (isSoftwareOrInfrastructure(node, state))
+        return false;
+    if (hasAny(qualityText(node, state), EXCLUDED_MAINS_TERMS))
+        return false;
+    if (hasAny(qualityText(node, state), BATTERY_EVIDENCE_TERMS))
+        return true;
+    return relatedEntities(node, state).some((entity) => {
+        const domain = entityDomain(entity);
+        const deviceClass = entityDeviceClass(entity);
+        return (domain ? BATTERY_ENTITY_DOMAINS.has(domain) : false)
+            || (deviceClass ? BATTERY_DEVICE_CLASSES.has(deviceClass) : false);
+    });
+}
+function shouldRequireManual(node, state) {
+    const required = readBooleanLike(node.metadata.manualRequired);
+    if (required === false)
+        return false;
+    if (required === true)
+        return true;
+    if (isSoftwareOrInfrastructure(node, state))
+        return false;
+    if (readNonEmptyString(node.metadata.manufacturer) || readNonEmptyString(node.metadata.model))
+        return true;
+    return relatedEntities(node, state).some((entity) => {
+        const domain = entityDomain(entity);
+        return domain ? MANUAL_ENTITY_DOMAINS.has(domain) : false;
+    });
+}
+function isSoftwareOrInfrastructure(node, state) {
+    const text = qualityText(node, state);
+    if (hasAny(text, EXCLUDED_SOFTWARE_TERMS))
+        return true;
+    if (hasAny(text, EXCLUDED_INFRASTRUCTURE_TERMS))
+        return true;
+    return relatedEntities(node, state).every((entity) => {
+        const domain = entityDomain(entity);
+        return domain === 'sun' || domain === 'weather';
+    }) && relatedEntities(node, state).length > 0;
+}
+function subjectFingerprint(node, code) {
+    const homeAssistant = readRecord(node.metadata.homeAssistant);
+    const attributes = readRecord(node.metadata.attributes);
+    return stableHash(JSON.stringify({
+        code,
+        kind: node.kind,
+        title: node.title,
+        manufacturer: node.metadata.manufacturer,
+        model: node.metadata.model,
+        batteryPowered: node.metadata.batteryPowered,
+        batteryType: node.metadata.batteryType,
+        manualRequired: node.metadata.manualRequired,
+        objectKind: homeAssistant.objectKind,
+        objectId: homeAssistant.objectId,
+        entityId: homeAssistant.entityId,
+        deviceId: homeAssistant.deviceId,
+        integrationId: homeAssistant.integrationId,
+        domain: homeAssistant.domain,
+        deviceClass: attributes.device_class,
+    }));
+}
+function relatedEntities(node, state) {
+    const byId = new Map(state.nodes.map((entry) => [entry.id, entry]));
+    return state.edges
+        .filter((edge) => edge.fromKind === 'node' && edge.toKind === 'node' && edge.toId === node.id && edge.relation === 'belongs_to_device')
+        .flatMap((edge) => {
+        const entry = byId.get(edge.fromId);
+        return entry?.kind === 'ha_entity' ? [entry] : [];
+    });
+}
+function qualityText(node, state) {
+    const values = uniqueStrings([
+        node.title,
+        node.summary,
+        ...node.aliases,
+        ...metadataStrings(node.metadata),
+        ...relatedEntities(node, state).flatMap((entity) => [
+            entity.title,
+            entity.summary,
+            ...entity.aliases,
+            ...metadataStrings(entity.metadata),
+        ]),
+    ]);
+    return values.join(' ').toLowerCase();
+}
+function metadataStrings(metadata) {
+    const homeAssistant = readRecord(metadata.homeAssistant);
+    const attributes = readRecord(metadata.attributes);
+    return uniqueStrings([
+        readNonEmptyString(metadata.manufacturer),
+        readNonEmptyString(metadata.model),
+        readNonEmptyString(metadata.entryType),
+        readNonEmptyString(metadata.entry_type),
+        readNonEmptyString(homeAssistant.objectKind),
+        readNonEmptyString(homeAssistant.objectId),
+        readNonEmptyString(homeAssistant.entityId),
+        readNonEmptyString(homeAssistant.deviceId),
+        readNonEmptyString(homeAssistant.integrationId),
+        readNonEmptyString(homeAssistant.domain),
+        readNonEmptyString(attributes.device_class),
+        readNonEmptyString(attributes.friendly_name),
+    ]);
+}
+function entityDomain(node) {
+    const homeAssistant = readRecord(node.metadata.homeAssistant);
+    const entityId = readNonEmptyString(homeAssistant.entityId);
+    if (entityId?.includes('.'))
+        return entityId.split('.', 1)[0];
+    return readNonEmptyString(homeAssistant.domain);
+}
+function entityDeviceClass(node) {
+    return readNonEmptyString(readRecord(node.metadata.attributes).device_class)?.toLowerCase();
+}
+function hasAny(text, terms) {
+    return terms.some((term) => text.includes(term));
+}
+function readBooleanLike(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', 'yes', '1'].includes(normalized))
+            return true;
+        if (['false', 'no', '0', 'none', 'not_applicable', 'not applicable'].includes(normalized))
+            return false;
+    }
+    return undefined;
+}
+function readNonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}

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

@@ -0,0 +1,14 @@
+import type { KnowledgeIssueRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import type { KnowledgeStore } from '../store.js';
+import type { HomeGraphReviewInput } from './types.js';
+export interface HomeGraphReviewResult {
+    readonly ok: true;
+    readonly spaceId: string;
+    readonly issue?: KnowledgeIssueRecord;
+    readonly node?: KnowledgeNodeRecord;
+    readonly source?: KnowledgeSourceRecord;
+    readonly suppression?: Record<string, unknown>;
+    readonly appliedFacts?: Record<string, unknown>;
+}
+export declare function reviewHomeGraphFact(store: KnowledgeStore, spaceId: string, installationId: string, input: HomeGraphReviewInput): Promise<HomeGraphReviewResult>;
+//# sourceMappingURL=review.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/review.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA+EhC"}

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

@@ -0,0 +1,183 @@
+import { belongsToSpace, buildHomeGraphMetadata, readRecord } from './helpers.js';
+export async function reviewHomeGraphFact(store, spaceId, installationId, input) {
+    const reviewedAt = Date.now();
+    if (input.issueId) {
+        const issue = store.getIssue(input.issueId);
+        if (!issue || !belongsToSpace(issue, spaceId))
+            throw new Error(`Unknown Home Graph issue: ${input.issueId}`);
+        const subjectNode = issue.nodeId ? store.getNode(issue.nodeId) : null;
+        const appliedFacts = await applyHomeGraphReviewFacts(store, spaceId, issue, subjectNode, input);
+        const suppression = buildSuppression(input, issue, reviewedAt);
+        const updatedIssue = await store.upsertIssue({
+            id: issue.id,
+            severity: issue.severity,
+            code: issue.code,
+            message: issue.message,
+            status: issueStatusForAction(input.action, issue.status),
+            sourceId: issue.sourceId,
+            nodeId: issue.nodeId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                review: reviewMetadata(input, reviewedAt),
+                ...(suppression ? { suppression } : {}),
+            }),
+        });
+        const node = appliedFacts?.node ?? subjectNode ?? undefined;
+        return {
+            ok: true,
+            spaceId,
+            issue: updatedIssue,
+            ...(node ? { node } : {}),
+            ...(suppression ? { suppression } : {}),
+            ...(appliedFacts?.facts ? { appliedFacts: appliedFacts.facts } : {}),
+        };
+    }
+    if (input.nodeId) {
+        const node = store.getNode(input.nodeId);
+        if (!node || !belongsToSpace(node, spaceId))
+            throw new Error(`Unknown Home Graph node: ${input.nodeId}`);
+        const facts = normalizeReviewFacts(input);
+        const updated = await store.upsertNode({
+            id: node.id,
+            kind: node.kind,
+            slug: node.slug,
+            title: node.title,
+            summary: node.summary,
+            aliases: node.aliases,
+            status: input.action === 'forget' ? 'stale' : node.status,
+            confidence: input.action === 'accept' ? 100 : node.confidence,
+            sourceId: node.sourceId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                ...facts,
+                review: reviewMetadata(input, reviewedAt),
+            }),
+        });
+        return { ok: true, spaceId, node: updated, ...(Object.keys(facts).length > 0 ? { appliedFacts: facts } : {}) };
+    }
+    if (input.sourceId) {
+        const source = store.getSource(input.sourceId);
+        if (!source || !belongsToSpace(source, spaceId))
+            throw new Error(`Unknown Home Graph source: ${input.sourceId}`);
+        const updated = await store.upsertSource({
+            id: source.id,
+            connectorId: source.connectorId,
+            sourceType: source.sourceType,
+            title: source.title,
+            sourceUri: source.sourceUri,
+            canonicalUri: source.canonicalUri,
+            summary: source.summary,
+            description: source.description,
+            tags: source.tags,
+            folderPath: source.folderPath,
+            status: input.action === 'forget' ? 'stale' : source.status,
+            artifactId: source.artifactId,
+            contentHash: source.contentHash,
+            lastCrawledAt: source.lastCrawledAt,
+            crawlError: source.crawlError,
+            sessionId: source.sessionId,
+            metadata: buildHomeGraphMetadata(spaceId, installationId, {
+                review: reviewMetadata(input, reviewedAt),
+            }),
+        });
+        return { ok: true, spaceId, source: updated };
+    }
+    throw new Error('reviewFact requires issueId, nodeId, or sourceId.');
+}
+async function applyHomeGraphReviewFacts(store, spaceId, issue, node, input) {
+    if (!node || !belongsToSpace(node, spaceId))
+        return undefined;
+    const facts = deriveIssueFacts(issue, input);
+    if (Object.keys(facts).length === 0)
+        return undefined;
+    const updated = await store.upsertNode({
+        id: node.id,
+        kind: node.kind,
+        slug: node.slug,
+        title: node.title,
+        summary: node.summary,
+        aliases: node.aliases,
+        status: node.status,
+        confidence: Math.max(node.confidence, input.action === 'accept' ? 100 : node.confidence),
+        sourceId: node.sourceId,
+        metadata: facts,
+    });
+    return { node: updated, facts };
+}
+function deriveIssueFacts(issue, input) {
+    const facts = normalizeReviewFacts(input);
+    if (issue.code === 'homegraph.device.unknown_battery') {
+        const category = readCategory(input);
+        const batteryType = readString(facts.batteryType);
+        if (batteryType && batteryType !== 'none' && typeof facts.batteryPowered !== 'boolean') {
+            return { ...facts, batteryPowered: true };
+        }
+        if (facts.batteryPowered === false && !batteryType) {
+            return { ...facts, batteryType: 'none' };
+        }
+        if (Object.keys(facts).length > 0)
+            return facts;
+        if (input.action === 'reject' || input.action === 'resolve' || category === 'not_applicable') {
+            return { batteryPowered: false, batteryType: 'none' };
+        }
+    }
+    if (issue.code === 'homegraph.device.missing_manual') {
+        const category = readCategory(input);
+        if (Object.keys(facts).length > 0)
+            return facts;
+        if (input.action === 'reject' || input.action === 'resolve' || category === 'not_applicable') {
+            return { manualRequired: false };
+        }
+    }
+    return facts;
+}
+function normalizeReviewFacts(input) {
+    const value = readRecord(input.value);
+    const fact = readRecord(value.fact);
+    const source = Object.keys(fact).length > 0 ? fact : value;
+    const allowed = {};
+    for (const key of [
+        'batteryPowered',
+        'batteryType',
+        'manualRequired',
+        'manufacturer',
+        'model',
+        'serial',
+        'firmware',
+        'installDate',
+        'purchaseDate',
+        'warrantyExpiration',
+    ]) {
+        if (key in source)
+            allowed[key] = source[key];
+    }
+    return allowed;
+}
+function reviewMetadata(input, reviewedAt) {
+    return {
+        action: input.action,
+        reviewer: input.reviewer ?? 'homeassistant',
+        reviewedAt,
+        ...(input.value ? { value: input.value } : {}),
+    };
+}
+function buildSuppression(input, issue, reviewedAt) {
+    if (!['accept', 'reject', 'resolve'].includes(input.action))
+        return undefined;
+    return {
+        suppressed: true,
+        action: input.action,
+        reviewedAt,
+        reviewer: input.reviewer ?? 'homeassistant',
+        issueId: issue.id,
+        code: issue.code,
+        subjectId: issue.metadata.subjectId ?? issue.nodeId ?? issue.sourceId ?? issue.id,
+    };
+}
+function issueStatusForAction(action, current) {
+    return action === 'reject' || action === 'resolve' || action === 'accept' ? 'resolved' : current;
+}
+function readCategory(input) {
+    return readString(readRecord(input.value).category)?.toLowerCase().replace(/[-\s]+/g, '_');
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}

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

@@ -0,0 +1,13 @@
+import type { KnowledgeStore } from '../store.js';
+import type { KnowledgeEdgeRecord, KnowledgeExtractionRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import type { HomeGraphSearchResult } from './types.js';
+export interface HomeGraphSearchState {
+    readonly spaceId: string;
+    readonly sources: readonly KnowledgeSourceRecord[];
+    readonly nodes: readonly KnowledgeNodeRecord[];
+    readonly edges: readonly KnowledgeEdgeRecord[];
+    readonly extractionBySourceId: ReadonlyMap<string, KnowledgeExtractionRecord>;
+}
+export declare function readHomeGraphSearchState(store: KnowledgeStore, spaceId: string): HomeGraphSearchState;
+export declare function scoreHomeGraphResults(query: string, sources: readonly KnowledgeSourceRecord[], nodes: readonly KnowledgeNodeRecord[], extractionBySourceId: (sourceId: string) => KnowledgeExtractionRecord | null | undefined, limit: number): HomeGraphSearchResult[];
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/search.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;AAErB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC/E;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAqBrG;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,yBAAyB,GAAG,IAAI,GAAG,SAAS,EACxF,KAAK,EAAE,MAAM,GACZ,qBAAqB,EAAE,CA+CzB"}

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

@@ -0,0 +1,136 @@
+import { belongsToSpace, edgeIsActive, readRecord } from './helpers.js';
+const MAX_FIELD_CHARS = 4_096;
+const MAX_SECTION_COUNT = 32;
+const MAX_SEARCH_TEXT_CHARS = 64 * 1024;
+export function readHomeGraphSearchState(store, spaceId) {
+    const sources = store.listSources(10_000).filter((source) => belongsToSpace(source, spaceId));
+    const nodes = store.listNodes(10_000).filter((node) => belongsToSpace(node, spaceId));
+    const sourceIds = new Set(sources.map((source) => source.id));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = store.listEdges().filter((edge) => (edgeIsActive(edge)
+        && belongsToSpace(edge, spaceId)
+        && (edge.fromKind !== 'source' || sourceIds.has(edge.fromId))
+        && (edge.toKind !== 'source' || sourceIds.has(edge.toId))
+        && (edge.fromKind !== 'node' || nodeIds.has(edge.fromId))
+        && (edge.toKind !== 'node' || nodeIds.has(edge.toId))));
+    const extractionBySourceId = new Map();
+    for (const extraction of store.listExtractions(10_000)) {
+        if (!sourceIds.has(extraction.sourceId) && !belongsToSpace(extraction, spaceId))
+            continue;
+        if (!extractionBySourceId.has(extraction.sourceId)) {
+            extractionBySourceId.set(extraction.sourceId, extraction);
+        }
+    }
+    return { spaceId, sources, nodes, edges, extractionBySourceId };
+}
+export function scoreHomeGraphResults(query, sources, nodes, extractionBySourceId, limit) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return [];
+    const sourceResults = sources.map((source) => {
+        const extraction = extractionBySourceId(source.id);
+        const baseScore = scoreFields(tokens, [
+            source.title,
+            source.summary,
+            source.description,
+            source.sourceUri,
+            source.canonicalUri,
+            source.tags.join(' '),
+            extraction?.title,
+            extraction?.summary,
+            extraction?.excerpt,
+            readSearchText(extraction),
+            ...limitedSections(extraction),
+        ]);
+        return {
+            kind: 'source',
+            id: source.id,
+            score: baseScore > 0 ? baseScore + (extraction ? 8 : 0) : 0,
+            title: source.title ?? source.sourceUri ?? source.id,
+            summary: extraction?.summary ?? source.summary,
+            source,
+        };
+    });
+    const nodeResults = nodes.map((node) => {
+        const baseScore = scoreFields(tokens, [
+            node.title,
+            node.summary,
+            node.aliases.join(' '),
+            readNodeMetadataText(node),
+        ]);
+        return {
+            kind: 'node',
+            id: node.id,
+            score: baseScore > 0 ? baseScore + Math.round(node.confidence / 20) : 0,
+            title: node.title,
+            summary: node.summary,
+            node,
+        };
+    });
+    return [...sourceResults, ...nodeResults]
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, Math.max(1, limit));
+}
+function limitedSections(extraction) {
+    if (!extraction)
+        return [];
+    return extraction.sections.slice(0, MAX_SECTION_COUNT).map((section) => clampText(section, MAX_FIELD_CHARS));
+}
+function readSearchText(extraction) {
+    if (!extraction)
+        return undefined;
+    const structure = readRecord(extraction.structure);
+    const metadata = readRecord(extraction.metadata);
+    return firstBoundedText([
+        structure.searchText,
+        structure.text,
+        structure.content,
+        metadata.searchText,
+    ], MAX_SEARCH_TEXT_CHARS);
+}
+function readNodeMetadataText(node) {
+    const homeAssistant = readRecord(node.metadata.homeAssistant);
+    const values = [
+        homeAssistant.objectKind,
+        homeAssistant.objectId,
+        homeAssistant.entityId,
+        homeAssistant.deviceId,
+        homeAssistant.areaId,
+        homeAssistant.integrationId,
+        node.metadata.manufacturer,
+        node.metadata.model,
+    ].filter((value) => typeof value === 'string' && value.trim().length > 0);
+    return values.length > 0 ? values.join(' ') : undefined;
+}
+function firstBoundedText(values, maxLength) {
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed)
+            continue;
+        return clampText(trimmed, maxLength);
+    }
+    return undefined;
+}
+function clampText(value, maxLength) {
+    return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+function tokenize(value) {
+    return value.toLowerCase().split(/[^a-z0-9_.:-]+/).map((entry) => entry.trim()).filter(Boolean);
+}
+function scoreFields(tokens, fields) {
+    let score = 0;
+    for (const field of fields) {
+        const raw = typeof field === 'string' ? field.trim() : '';
+        const haystack = clampText(raw, MAX_SEARCH_TEXT_CHARS).toLowerCase();
+        if (!haystack)
+            continue;
+        for (const token of tokens) {
+            if (haystack.includes(token))
+                score += 10;
+        }
+    }
+    return score;
+}

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

@@ -1,6 +1,7 @@
 import type { ArtifactStore } from '../../artifacts/index.js';
 import type { KnowledgeStore } from '../store.js';
 import type { KnowledgeEdgeRecord, KnowledgeIssueRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from '../types.js';
+import { type HomeGraphReviewResult } from './review.js';
 import type { HomeGraphAskInput, HomeGraphAskResult, HomeGraphDevicePassportResult, HomeGraphExport, HomeGraphIngestArtifactInput, HomeGraphIngestNoteInput, HomeGraphIngestResult, HomeGraphIngestUrlInput, HomeGraphLinkInput, HomeGraphLinkResult, HomeGraphProjectionInput, HomeGraphProjectionResult, HomeGraphReviewInput, HomeGraphSpaceInput, HomeGraphSnapshotInput, HomeGraphStatus, HomeGraphSyncResult } from './types.js';
 export declare class HomeGraphService {
     private readonly store;
@@ -30,13 +31,7 @@ export declare class HomeGraphService {
         readonly spaceId: string;
         readonly issues: readonly KnowledgeIssueRecord[];
     }>;
-    reviewFact(input: HomeGraphReviewInput): Promise<{
-        readonly ok: true;
-        readonly spaceId: string;
-        readonly issue?: KnowledgeIssueRecord;
-        readonly node?: KnowledgeNodeRecord;
-        readonly source?: KnowledgeSourceRecord;
-    }>;
+    reviewFact(input: HomeGraphReviewInput): Promise<HomeGraphReviewResult>;
     listSources(input?: HomeGraphSpaceInput & {
         readonly limit?: number;
     }): Promise<{

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

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/home-graph/service.ts"],"names":[],"mappings":"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"}