@pellux/goodvibes-sdk 0.27.3 → 0.27.5

package/dist/_internal/platform/knowledge/semantic/enrichment.js

@@ -0,0 +1,492 @@
+import { MAX_SEMANTIC_SOURCE_CHARS, applySourceMetadata, clampText, normalizeWhitespace, readRecord, readString, semanticHash, semanticMetadata, semanticSlug, sourceKnowledgeSpace, sourceSemanticHash, sourceSemanticText, splitSentences, uniqueStrings, } from './utils.js';
+export async function enrichKnowledgeSource(context, source, options = {}) {
+    const extraction = context.store.getExtractionBySourceId(source.id);
+    const text = sourceSemanticText(source, extraction);
+    const textHash = sourceSemanticHash(source, extraction);
+    const existingSemantic = readRecord(source.metadata.semanticEnrichment);
+    if (!options.force && existingSemantic.textHash === textHash) {
+        return emptyResult(source, true, 'semantic enrichment is current');
+    }
+    if (text.length < 40) {
+        await markSourceSemanticState(context.store, source, textHash, {
+            skippedReason: 'source has too little extracted text',
+        });
+        return emptyResult(source, true, 'source has too little extracted text');
+    }
+    const llmExtraction = await extractSemanticsWithLlm(context.llm ?? null, source, extraction, text);
+    const semantic = normalizeSemanticExtraction(llmExtraction)
+        ?? deterministicSemanticExtraction(source, extraction, text);
+    const persisted = await persistSemanticExtraction(context.store, source, extraction, semantic, {
+        knowledgeSpaceId: options.knowledgeSpaceId,
+        textHash,
+    });
+    await markSourceSemanticState(context.store, source, textHash, {
+        extractor: semantic.extractor,
+        factCount: persisted.facts.length,
+        entityCount: persisted.entities.length,
+        gapCount: persisted.gaps.length,
+    });
+    return persisted;
+}
+async function extractSemanticsWithLlm(llm, source, extraction, text) {
+    if (!llm)
+        return null;
+    return llm.completeJson({
+        purpose: 'knowledge-semantic-enrichment',
+        maxTokens: 2600,
+        timeoutMs: 20_000,
+        systemPrompt: [
+            'You extract a durable semantic knowledge graph from source material.',
+            'Return only JSON. Do not invent facts. Every fact must be grounded in the supplied source text.',
+            'Capture capabilities, features, specifications, procedures, warnings, maintenance items, compatibility, configuration, and troubleshooting facts when present.',
+            'Prefer precise facts over broad summaries. Preserve numbers, model names, ports, version names, constraints, and useful procedures.',
+        ].join(' '),
+        prompt: JSON.stringify({
+            source: {
+                id: source.id,
+                title: source.title,
+                sourceType: source.sourceType,
+                tags: source.tags,
+                uri: source.canonicalUri ?? source.sourceUri,
+                metadata: source.metadata,
+            },
+            extraction: {
+                format: extraction?.format,
+                title: extraction?.title,
+                summary: extraction?.summary,
+                sections: extraction?.sections.slice(0, 80),
+            },
+            instructions: {
+                outputShape: {
+                    summary: 'short source summary',
+                    entities: [{ title: 'entity name', kind: 'entity type', aliases: ['alternate names'], summary: 'one sentence', confidence: 0 }],
+                    facts: [{
+                            kind: 'feature|capability|specification|identity|procedure|warning|maintenance|compatibility|configuration|troubleshooting|relationship|note',
+                            title: 'short fact title',
+                            value: 'precise value when applicable',
+                            summary: 'source-grounded explanation',
+                            evidence: 'short quote or close paraphrase from source',
+                            confidence: 0,
+                            labels: ['optional labels'],
+                            targetHints: ['entities this fact describes'],
+                        }],
+                    relations: [{ from: 'entity/fact title', relation: 'relation label', to: 'entity/fact title', evidence: 'source-grounded evidence', confidence: 0 }],
+                    gaps: [{ question: 'missing useful question', reason: 'why source does not answer it', subject: 'optional subject', severity: 'info|warning|error' }],
+                    wikiPage: { title: 'living page title', markdown: 'concise markdown page synthesized only from extracted facts' },
+                },
+            },
+            text: clampText(text, MAX_SEMANTIC_SOURCE_CHARS),
+        }),
+    });
+}
+function normalizeSemanticExtraction(value) {
+    const record = readRecord(value);
+    const facts = readArray(record.facts).map(normalizeFact).filter(isFact);
+    const entities = readArray(record.entities).map(normalizeEntity).filter(isEntity);
+    const relations = readArray(record.relations).map(normalizeRelation).filter(isRelation);
+    const gaps = readArray(record.gaps).map(normalizeGap).filter(isGap);
+    const wikiRecord = readRecord(record.wikiPage);
+    const markdown = readString(wikiRecord.markdown);
+    const title = readString(wikiRecord.title);
+    if (facts.length === 0 && entities.length === 0 && !markdown)
+        return null;
+    return {
+        summary: readString(record.summary),
+        entities,
+        facts,
+        relations,
+        gaps,
+        ...(markdown || title ? { wikiPage: { ...(title ? { title } : {}), ...(markdown ? { markdown } : {}) } } : {}),
+        extractor: 'llm',
+    };
+}
+function deterministicSemanticExtraction(source, extraction, text) {
+    const sentences = splitSentences(text);
+    const facts = sentences
+        .map((sentence) => classifySentenceFact(sentence))
+        .filter((fact) => Boolean(fact))
+        .slice(0, 80);
+    const entities = uniqueStrings([
+        source.title,
+        extraction?.title,
+        ...source.tags,
+    ]).slice(0, 12).map((title) => ({
+        title,
+        kind: title === source.title ? source.sourceType : 'topic',
+        summary: `Entity inferred from ${source.title ?? source.id}.`,
+        confidence: 45,
+    }));
+    return {
+        summary: extraction?.summary ?? source.summary ?? clampText(text, 360),
+        entities,
+        facts,
+        relations: [],
+        gaps: facts.length === 0
+            ? [{ question: `What useful facts should be extracted from ${source.title ?? source.id}?`, reason: 'No high-confidence semantic facts were detected.', severity: 'info' }]
+            : [],
+        wikiPage: {
+            title: source.title ? `${source.title} knowledge page` : 'Knowledge page',
+            markdown: renderDeterministicWikiPage(source, facts),
+        },
+        extractor: 'deterministic',
+    };
+}
+function classifySentenceFact(sentence) {
+    const text = normalizeWhitespace(sentence);
+    if (text.length < 28)
+        return null;
+    const lower = text.toLowerCase();
+    const kind = (() => {
+        if (/\b(warning|caution|do not|never|risk|hazard|important)\b/.test(lower))
+            return 'warning';
+        if (/\b(reset|press|hold|select|open|install|pair|configure|enable|disable|connect|setup|set up)\b/.test(lower))
+            return 'procedure';
+        if (/\b(clean|replace|battery|filter|firmware|update|service|maintenance|warranty)\b/.test(lower))
+            return 'maintenance';
+        if (/\b(compatible|works with|requires|supports?|supported|connects? to|integrates? with)\b/.test(lower))
+            return 'compatibility';
+        if (/\b(feature|features|capabilit|function|mode|built-in|includes?|provides?|allows?|can )\b/.test(lower))
+            return 'feature';
+        if (/\b(specification|specifications|model|serial|version|hdmi|usb|port|ports|resolution|volt|watt|hz|inch|mm|gb|mb|ip[0-9])\b/.test(lower))
+            return 'specification';
+        return null;
+    })();
+    if (!kind)
+        return null;
+    return {
+        kind,
+        title: titleFromSentence(text),
+        summary: text,
+        evidence: text,
+        confidence: 55,
+        labels: inferLabels(text),
+    };
+}
+async function persistSemanticExtraction(store, source, extraction, semantic, options) {
+    const spaceId = options.knowledgeSpaceId ?? sourceKnowledgeSpace(source);
+    const entities = [];
+    const facts = [];
+    const gaps = [];
+    for (const entity of semantic.entities.slice(0, 60)) {
+        const node = await store.upsertNode({
+            id: `sem-entity-${semanticHash(spaceId, source.id, entity.title)}`,
+            kind: 'knowledge_entity',
+            slug: semanticSlug(`${spaceId}-${entity.title}`),
+            title: entity.title,
+            summary: entity.summary,
+            aliases: entity.aliases,
+            confidence: entity.confidence ?? 65,
+            sourceId: source.id,
+            metadata: semanticMetadata(spaceId, {
+                ...(entity.metadata ?? {}),
+                semanticKind: 'entity',
+                entityKind: entity.kind ?? 'entity',
+                sourceId: source.id,
+                extractionId: extraction?.id,
+                extractor: semantic.extractor,
+                textHash: options.textHash,
+            }),
+        });
+        entities.push(node);
+        await linkSourceToNode(store, source.id, node.id, 'mentions_entity', spaceId, semantic.extractor);
+    }
+    for (const fact of semantic.facts.slice(0, 160)) {
+        const node = await store.upsertNode({
+            id: `sem-fact-${semanticHash(spaceId, source.id, fact.kind, fact.title, fact.value ?? fact.summary)}`,
+            kind: 'fact',
+            slug: semanticSlug(`${spaceId}-${fact.kind}-${fact.title}-${fact.value ?? ''}`),
+            title: fact.title,
+            summary: fact.summary ?? fact.value ?? fact.evidence,
+            aliases: fact.labels,
+            confidence: fact.confidence ?? 70,
+            sourceId: source.id,
+            metadata: semanticMetadata(spaceId, {
+                semanticKind: 'fact',
+                factKind: fact.kind,
+                value: fact.value,
+                evidence: fact.evidence,
+                labels: fact.labels ?? [],
+                targetHints: fact.targetHints ?? [],
+                sourceId: source.id,
+                extractionId: extraction?.id,
+                extractor: semantic.extractor,
+                textHash: options.textHash,
+            }),
+        });
+        facts.push(node);
+        await linkSourceToNode(store, source.id, node.id, 'supports_fact', spaceId, semantic.extractor);
+        await linkFactToEntities(store, node, entities, fact, spaceId, semantic.extractor);
+    }
+    for (const relation of semantic.relations.slice(0, 80)) {
+        await linkRelation(store, entities, facts, relation, spaceId, semantic.extractor);
+    }
+    for (const gap of semantic.gaps.slice(0, 32)) {
+        const node = await store.upsertNode({
+            id: `sem-gap-${semanticHash(spaceId, source.id, gap.question)}`,
+            kind: 'knowledge_gap',
+            slug: semanticSlug(`${spaceId}-gap-${gap.question}`),
+            title: gap.question,
+            summary: gap.reason,
+            confidence: gap.severity === 'error' ? 85 : gap.severity === 'warning' ? 70 : 50,
+            sourceId: source.id,
+            metadata: semanticMetadata(spaceId, {
+                semanticKind: 'gap',
+                subject: gap.subject,
+                severity: gap.severity ?? 'info',
+                sourceId: source.id,
+                extractionId: extraction?.id,
+                extractor: semantic.extractor,
+                textHash: options.textHash,
+            }),
+        });
+        gaps.push(node);
+        await linkSourceToNode(store, source.id, node.id, 'has_gap', spaceId, semantic.extractor);
+        await store.upsertIssue({
+            id: `sem-issue-${semanticHash(spaceId, source.id, gap.question)}`,
+            severity: gap.severity ?? 'info',
+            code: 'knowledge.semantic_gap',
+            message: gap.question,
+            status: 'open',
+            sourceId: source.id,
+            nodeId: node.id,
+            metadata: semanticMetadata(spaceId, {
+                reason: gap.reason,
+                subject: gap.subject,
+                namespace: `knowledge:${spaceId}:semantic`,
+            }),
+        });
+    }
+    const wikiPage = await persistWikiPage(store, source, semantic, spaceId, options.textHash);
+    return { source, skipped: false, extractor: semantic.extractor, facts, entities, gaps, ...(wikiPage ? { wikiPage } : {}) };
+}
+async function persistWikiPage(store, source, semantic, spaceId, textHash) {
+    const markdown = semantic.wikiPage?.markdown ?? renderDeterministicWikiPage(source, semantic.facts);
+    if (!markdown.trim())
+        return undefined;
+    const page = await store.upsertNode({
+        id: `sem-page-${semanticHash(spaceId, source.id)}`,
+        kind: 'wiki_page',
+        slug: semanticSlug(`${spaceId}-${source.title ?? source.id}-page`),
+        title: semantic.wikiPage?.title ?? `${source.title ?? source.id} knowledge page`,
+        summary: semantic.summary ?? source.summary,
+        aliases: source.title ? [source.title] : [],
+        confidence: semantic.extractor === 'llm' ? 80 : 55,
+        sourceId: source.id,
+        metadata: semanticMetadata(spaceId, {
+            semanticKind: 'wiki_page',
+            markdown,
+            sourceId: source.id,
+            extractor: semantic.extractor,
+            textHash,
+        }),
+    });
+    await linkSourceToNode(store, source.id, page.id, 'compiled_into_page', spaceId, semantic.extractor);
+    return page;
+}
+async function markSourceSemanticState(store, source, textHash, details) {
+    await store.upsertSource(applySourceMetadata(source, {
+        semanticEnrichment: {
+            textHash,
+            enrichedAt: Date.now(),
+            ...details,
+        },
+    }));
+}
+async function linkSourceToNode(store, sourceId, nodeId, relation, spaceId, extractor) {
+    await store.upsertEdge({
+        fromKind: 'source',
+        fromId: sourceId,
+        toKind: 'node',
+        toId: nodeId,
+        relation,
+        weight: extractor === 'llm' ? 1 : 0.6,
+        metadata: semanticMetadata(spaceId, { extractor }),
+    });
+}
+async function linkFactToEntities(store, fact, entities, input, spaceId, extractor) {
+    const hints = uniqueStrings(input.targetHints ?? []);
+    const candidates = hints.length === 0
+        ? entities.slice(0, 1)
+        : entities.filter((entity) => hints.some((hint) => entityMatchesHint(entity, hint)));
+    for (const entity of candidates.slice(0, 6)) {
+        await store.upsertEdge({
+            fromKind: 'node',
+            fromId: fact.id,
+            toKind: 'node',
+            toId: entity.id,
+            relation: 'describes',
+            metadata: semanticMetadata(spaceId, { extractor }),
+        });
+    }
+}
+async function linkRelation(store, entities, facts, relation, spaceId, extractor) {
+    const from = findSemanticNode([...entities, ...facts], relation.from);
+    const to = findSemanticNode([...entities, ...facts], relation.to);
+    if (!from || !to || from.id === to.id)
+        return;
+    await store.upsertEdge({
+        fromKind: 'node',
+        fromId: from.id,
+        toKind: 'node',
+        toId: to.id,
+        relation: semanticSlug(relation.relation).replace(/-/g, '_') || 'related_to',
+        weight: Math.max(0.1, Math.min(1, (relation.confidence ?? 70) / 100)),
+        metadata: semanticMetadata(spaceId, {
+            evidence: relation.evidence,
+            extractor,
+        }),
+    });
+}
+function renderDeterministicWikiPage(source, facts) {
+    const grouped = new Map();
+    for (const fact of facts) {
+        grouped.set(fact.kind, [...(grouped.get(fact.kind) ?? []), fact]);
+    }
+    const sections = [...grouped.entries()].flatMap(([kind, entries]) => [
+        `## ${titleCase(kind)}`,
+        '',
+        ...entries.slice(0, 24).map((fact) => `- ${fact.title}${fact.value ? `: ${fact.value}` : ''}${fact.summary ? ` - ${fact.summary}` : ''}`),
+        '',
+    ]);
+    return [
+        `# ${source.title ?? source.id}`,
+        '',
+        source.summary ?? '',
+        '',
+        ...sections,
+    ].filter((line) => line !== undefined).join('\n').trim();
+}
+function normalizeFact(value) {
+    const record = readRecord(value);
+    const kind = normalizeFactKind(readString(record.kind));
+    const title = readString(record.title);
+    if (!kind || !title)
+        return null;
+    return {
+        kind,
+        title,
+        ...(readString(record.value) ? { value: readString(record.value) } : {}),
+        ...(readString(record.summary) ? { summary: readString(record.summary) } : {}),
+        ...(readString(record.evidence) ? { evidence: readString(record.evidence) } : {}),
+        ...(typeof record.confidence === 'number' ? { confidence: clampConfidence(record.confidence) } : {}),
+        labels: readStringArray(record.labels),
+        targetHints: readStringArray(record.targetHints),
+    };
+}
+function normalizeEntity(value) {
+    const record = readRecord(value);
+    const title = readString(record.title);
+    if (!title)
+        return null;
+    return {
+        title,
+        ...(readString(record.kind) ? { kind: readString(record.kind) } : {}),
+        aliases: readStringArray(record.aliases),
+        ...(readString(record.summary) ? { summary: readString(record.summary) } : {}),
+        ...(typeof record.confidence === 'number' ? { confidence: clampConfidence(record.confidence) } : {}),
+        metadata: readRecord(record.metadata),
+    };
+}
+function normalizeRelation(value) {
+    const record = readRecord(value);
+    const from = readString(record.from);
+    const relation = readString(record.relation);
+    const to = readString(record.to);
+    if (!from || !relation || !to)
+        return null;
+    return {
+        from,
+        relation,
+        to,
+        ...(readString(record.evidence) ? { evidence: readString(record.evidence) } : {}),
+        ...(typeof record.confidence === 'number' ? { confidence: clampConfidence(record.confidence) } : {}),
+    };
+}
+function normalizeGap(value) {
+    const record = readRecord(value);
+    const question = readString(record.question);
+    if (!question)
+        return null;
+    const severity = readString(record.severity);
+    return {
+        question,
+        ...(readString(record.reason) ? { reason: readString(record.reason) } : {}),
+        ...(readString(record.subject) ? { subject: readString(record.subject) } : {}),
+        severity: severity === 'warning' || severity === 'error' ? severity : 'info',
+    };
+}
+function normalizeFactKind(value) {
+    switch (value) {
+        case 'feature':
+        case 'capability':
+        case 'specification':
+        case 'identity':
+        case 'procedure':
+        case 'warning':
+        case 'maintenance':
+        case 'compatibility':
+        case 'configuration':
+        case 'troubleshooting':
+        case 'relationship':
+        case 'note':
+            return value;
+        default:
+            return value ? 'note' : null;
+    }
+}
+function readArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function readStringArray(value) {
+    return Array.isArray(value)
+        ? uniqueStrings(value.map((entry) => typeof entry === 'string' ? entry : undefined))
+        : [];
+}
+function isFact(value) {
+    return Boolean(value);
+}
+function isEntity(value) {
+    return Boolean(value);
+}
+function isRelation(value) {
+    return Boolean(value);
+}
+function isGap(value) {
+    return Boolean(value);
+}
+function clampConfidence(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+function titleFromSentence(sentence) {
+    const withoutLead = sentence.replace(/^(the|this|these|it)\s+/i, '');
+    return clampText(withoutLead, 96).replace(/[.:;,\s]+$/g, '');
+}
+function inferLabels(text) {
+    const lower = text.toLowerCase();
+    return uniqueStrings([
+        /\bhdmi\b/.test(lower) ? 'hdmi' : undefined,
+        /\busb\b/.test(lower) ? 'usb' : undefined,
+        /\bbattery\b/.test(lower) ? 'battery' : undefined,
+        /\bfirmware\b/.test(lower) ? 'firmware' : undefined,
+        /\bwarranty\b/.test(lower) ? 'warranty' : undefined,
+        /\bvoice\b/.test(lower) ? 'voice' : undefined,
+        /\bnetwork|wi-?fi|ethernet|bluetooth\b/.test(lower) ? 'network' : undefined,
+    ]);
+}
+function entityMatchesHint(entity, hint) {
+    const lower = hint.toLowerCase();
+    return entity.title.toLowerCase().includes(lower)
+        || entity.aliases.some((alias) => alias.toLowerCase().includes(lower))
+        || lower.includes(entity.title.toLowerCase());
+}
+function findSemanticNode(nodes, label) {
+    const lower = label.toLowerCase();
+    return nodes.find((node) => node.title.toLowerCase() === lower)
+        ?? nodes.find((node) => node.title.toLowerCase().includes(lower) || lower.includes(node.title.toLowerCase()));
+}
+function titleCase(value) {
+    return value.replace(/[_-]+/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function emptyResult(source, skipped, reason) {
+    return { source, skipped, reason, facts: [], entities: [], gaps: [] };
+}

package/dist/_internal/platform/knowledge/semantic/index.d.ts

@@ -0,0 +1,5 @@
+export { createProviderBackedKnowledgeSemanticLlm } from './llm.js';
+export { KnowledgeSemanticService } from './service.js';
+export type { KnowledgeSemanticServiceOptions } from './service.js';
+export type { KnowledgeSemanticAnswer, KnowledgeSemanticAnswerInput, KnowledgeSemanticAnswerResult, KnowledgeSemanticEnrichmentResult, KnowledgeSemanticExtraction, KnowledgeSemanticFactInput, KnowledgeSemanticFactKind, KnowledgeSemanticGapInput, KnowledgeSemanticLlm, KnowledgeSemanticLlmAnswer, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/knowledge/semantic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EACV,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,iCAAiC,EACjC,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,YAAY,CAAC"}

package/dist/_internal/platform/knowledge/semantic/index.js

@@ -0,0 +1,2 @@
+export { createProviderBackedKnowledgeSemanticLlm } from './llm.js';
+export { KnowledgeSemanticService } from './service.js';

package/dist/_internal/platform/knowledge/semantic/llm.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderRegistry } from '../../providers/registry.js';
+import type { KnowledgeSemanticLlm } from './types.js';
+export interface ProviderBackedKnowledgeSemanticLlmOptions {
+    readonly timeoutMs?: number;
+    readonly maxConcurrent?: number;
+}
+export declare function createProviderBackedKnowledgeSemanticLlm(providerRegistry: ProviderRegistry, options?: ProviderBackedKnowledgeSemanticLlmOptions): KnowledgeSemanticLlm;
+//# sourceMappingURL=llm.d.ts.map

package/dist/_internal/platform/knowledge/semantic/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,wCAAwC,CACtD,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,GAAE,yCAA8C,GACtD,oBAAoB,CAatB"}

package/dist/_internal/platform/knowledge/semantic/llm.js

@@ -0,0 +1,103 @@
+import { logger } from '../../utils/logger.js';
+import { summarizeError } from '../../utils/error-display.js';
+import { extractJsonObject } from './utils.js';
+export function createProviderBackedKnowledgeSemanticLlm(providerRegistry, options = {}) {
+    const limiter = new SemanticLlmLimiter(Math.max(1, options.maxConcurrent ?? 1));
+    const timeoutMs = Math.max(1_000, options.timeoutMs ?? 20_000);
+    return {
+        completeJson: async (input) => limiter.run(async () => {
+            const text = await completeWithCurrentModel(providerRegistry, { ...input, timeoutMs: input.timeoutMs ?? timeoutMs });
+            return text ? extractJsonObject(text) : null;
+        }),
+        completeText: async (input) => limiter.run(async () => completeWithCurrentModel(providerRegistry, { ...input, timeoutMs: input.timeoutMs ?? timeoutMs })),
+    };
+}
+async function completeWithCurrentModel(providerRegistry, input) {
+    const timeoutMs = Math.max(1_000, input.timeoutMs ?? 20_000);
+    const controller = new AbortController();
+    const timeoutSentinel = Symbol('semantic-timeout');
+    let timedOut = false;
+    let timer;
+    const abortFromParent = () => controller.abort();
+    if (input.signal?.aborted)
+        return null;
+    input.signal?.addEventListener('abort', abortFromParent, { once: true });
+    try {
+        const current = providerRegistry.getCurrentModel();
+        const provider = providerRegistry.getForModel(current.id, current.provider);
+        const chatPromise = provider.chat({
+            model: current.id,
+            messages: [{ role: 'user', content: input.prompt }],
+            systemPrompt: input.systemPrompt,
+            maxTokens: input.maxTokens ?? 1800,
+            reasoningEffort: 'low',
+            signal: controller.signal,
+        }).catch((error) => {
+            if (timedOut || controller.signal.aborted)
+                return null;
+            throw error;
+        });
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+                resolve(timeoutSentinel);
+            }, timeoutMs);
+        });
+        const response = await Promise.race([chatPromise, timeoutPromise]);
+        if (response === timeoutSentinel) {
+            logger.debug('Knowledge semantic LLM request timed out', {
+                purpose: input.purpose,
+                timeoutMs,
+            });
+            return null;
+        }
+        if (!response)
+            return null;
+        const content = response.content?.trim() ?? '';
+        return content.length > 0 ? content : null;
+    }
+    catch (error) {
+        logger.debug('Knowledge semantic LLM request failed', {
+            purpose: input.purpose,
+            error: summarizeError(error),
+        });
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        input.signal?.removeEventListener('abort', abortFromParent);
+    }
+}
+class SemanticLlmLimiter {
+    maxConcurrent;
+    active = 0;
+    queue = [];
+    constructor(maxConcurrent) {
+        this.maxConcurrent = maxConcurrent;
+    }
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    async acquire() {
+        if (this.active < this.maxConcurrent) {
+            this.active += 1;
+            return;
+        }
+        await new Promise((resolve) => this.queue.push(resolve));
+        this.active += 1;
+    }
+    release() {
+        this.active = Math.max(0, this.active - 1);
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}

package/dist/_internal/platform/knowledge/semantic/service.d.ts

@@ -0,0 +1,38 @@
+import type { KnowledgeStore } from '../store.js';
+import type { KnowledgeSourceRecord } from '../types.js';
+import type { KnowledgeSemanticAnswerInput, KnowledgeSemanticAnswerResult, KnowledgeSemanticEnrichmentResult, KnowledgeSemanticLlm } from './types.js';
+export interface KnowledgeSemanticServiceOptions {
+    readonly llm?: KnowledgeSemanticLlm | null;
+    readonly maxLlmSourcesPerReindex?: number;
+}
+export declare class KnowledgeSemanticService {
+    private readonly store;
+    private readonly options;
+    constructor(store: KnowledgeStore, options?: KnowledgeSemanticServiceOptions);
+    enrichSource(sourceId: string, input?: {
+        readonly force?: boolean;
+        readonly knowledgeSpaceId?: string;
+    }): Promise<KnowledgeSemanticEnrichmentResult | null>;
+    enrichSources(sources: readonly KnowledgeSourceRecord[], input?: {
+        readonly force?: boolean;
+        readonly knowledgeSpaceId?: string;
+        readonly limit?: number;
+    }): Promise<readonly KnowledgeSemanticEnrichmentResult[]>;
+    reindex(input?: {
+        readonly sourceIds?: readonly string[];
+        readonly limit?: number;
+        readonly force?: boolean;
+        readonly knowledgeSpaceId?: string;
+    }): Promise<{
+        readonly scanned: number;
+        readonly enriched: number;
+        readonly skipped: number;
+        readonly failed: number;
+        readonly errors: readonly {
+            readonly sourceId: string;
+            readonly error: string;
+        }[];
+    }>;
+    answer(input: KnowledgeSemanticAnswerInput): Promise<KnowledgeSemanticAnswerResult>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/_internal/platform/knowledge/semantic/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/semantic/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC7B,iCAAiC,EACjC,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,+BAAoC;IAG1D,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3E,OAAO,CAAC,iCAAiC,GAAG,IAAI,CAAC;IAO9C,aAAa,CACjB,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACpG,OAAO,CAAC,SAAS,iCAAiC,EAAE,CAAC;IASlD,OAAO,CAAC,KAAK,GAAE;QACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC/B,GAAG,OAAO,CAAC;QACf,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,SAAS;YAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACnF,CAAC;IA2BI,MAAM,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,6BAA6B,CAAC;CAI1F"}