md-semantic-search 1.1.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +88 -14
  2. package/RESEARCH.md +182 -0
  3. package/bin/cli.mjs +197 -8
  4. package/dist/binary-format.js +9 -0
  5. package/dist/completions.js +5 -0
  6. package/dist/core.d.ts +16 -4
  7. package/dist/core.js +105 -14
  8. package/dist/federation.d.ts +16 -1
  9. package/dist/federation.js +33 -16
  10. package/dist/filter.d.ts +7 -0
  11. package/dist/filter.js +13 -0
  12. package/dist/hnsw.d.ts +96 -0
  13. package/dist/hnsw.js +326 -0
  14. package/dist/indexer.d.ts +17 -1
  15. package/dist/indexer.js +91 -17
  16. package/dist/lexical.d.ts +10 -0
  17. package/dist/lexical.js +98 -15
  18. package/dist/markdown-parser.d.ts +62 -0
  19. package/dist/markdown-parser.js +227 -30
  20. package/dist/mcp.d.ts +86 -3
  21. package/dist/mcp.js +259 -31
  22. package/dist/models.d.ts +7 -1
  23. package/dist/models.js +32 -1
  24. package/dist/providers.d.ts +56 -0
  25. package/dist/providers.js +305 -0
  26. package/dist/quantization.d.ts +12 -0
  27. package/dist/quantization.js +54 -0
  28. package/dist/rag.d.ts +60 -0
  29. package/dist/rag.js +133 -35
  30. package/dist/repair.d.ts +1 -1
  31. package/dist/repair.js +53 -2
  32. package/dist/rerank.d.ts +32 -3
  33. package/dist/rerank.js +58 -8
  34. package/dist/search.d.ts +48 -3
  35. package/dist/search.js +384 -78
  36. package/dist/serve.d.ts +35 -0
  37. package/dist/serve.js +478 -58
  38. package/dist/tui.d.ts +6 -0
  39. package/dist/tui.js +52 -2
  40. package/dist/watcher.js +23 -12
  41. package/dist/webui.d.ts +3 -3
  42. package/dist/webui.js +201 -2
  43. package/package.json +3 -3
  44. package/src/binary-format.ts +13 -0
  45. package/src/completions.ts +5 -0
  46. package/src/core.ts +115 -12
  47. package/src/federation.ts +51 -17
  48. package/src/filter.ts +14 -0
  49. package/src/hnsw.ts +414 -0
  50. package/src/indexer.ts +107 -18
  51. package/src/lexical.ts +91 -13
  52. package/src/markdown-parser.ts +279 -37
  53. package/src/mcp.ts +323 -34
  54. package/src/models.ts +39 -2
  55. package/src/providers.ts +345 -0
  56. package/src/quantization.ts +61 -0
  57. package/src/rag.ts +189 -34
  58. package/src/repair.ts +51 -2
  59. package/src/rerank.ts +81 -8
  60. package/src/search.ts +417 -82
  61. package/src/serve.ts +499 -66
  62. package/src/tui.ts +56 -2
  63. package/src/watcher.ts +21 -10
  64. package/src/webui.ts +201 -2
package/dist/mcp.js CHANGED
@@ -10,13 +10,113 @@ import { buildIndex } from './indexer.js';
10
10
  import { loadIndex, searchIndex } from './search.js';
11
11
  import { searchFederated } from './federation.js';
12
12
  import { askQuestion, chatTurn, loadChatSession } from './rag.js';
13
- import { globToRegExp, getDocLines } from './core.js';
13
+ import { assertSafePath, globToRegExp, getDocLines } from './core.js';
14
14
  import { findRelatedNotes } from './wikilinks.js';
15
15
  /**
16
16
  * Package version reported via MCP initialize → serverInfo.
17
17
  * Single source of truth: package.json (resolved relative to dist/mcp.js).
18
18
  */
19
19
  const MCP_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
20
+ /**
21
+ * Protocol versions this server can speak (issue #197), newest first.
22
+ * `initialize` echoes the client's requested version when we support it,
23
+ * otherwise answers with MCP_SUPPORTED_VERSIONS[0].
24
+ */
25
+ export const MCP_SUPPORTED_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
26
+ /**
27
+ * Resolves the protocol version to answer an `initialize` with: the client's
28
+ * exact request when supported, else the newest version we speak (the spec's
29
+ * "respond with another protocol version you support" branch).
30
+ */
31
+ export function negotiateProtocolVersion(requested) {
32
+ const v = typeof requested === 'string' ? requested : '';
33
+ return MCP_SUPPORTED_VERSIONS.includes(v) ? v : MCP_SUPPORTED_VERSIONS[0];
34
+ }
35
+ /** Server→client requests that outlive this wait degrade, not hang (issue #197). */
36
+ export const DEFAULT_SAMPLING_TIMEOUT_MS = 60_000;
37
+ /** `sampling/createMessage` requires maxTokens — a grounded citation answer fits comfortably. */
38
+ export const DEFAULT_SAMPLING_MAX_TOKENS = 1024;
39
+ export function samplingTimeoutMs(envValue) {
40
+ const raw = Number(envValue ?? process.env.MDSS_SAMPLING_TIMEOUT_MS);
41
+ return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SAMPLING_TIMEOUT_MS;
42
+ }
43
+ /**
44
+ * Builds a client channel over a raw sink. Ids are prefixed `mdss-srv-` so
45
+ * they can never collide with the client's own request ids in either
46
+ * direction's logs or pending maps.
47
+ */
48
+ export function createClientChannel(send) {
49
+ const pending = new Map();
50
+ let nextId = 0;
51
+ return {
52
+ request(method, params = {}, opts = {}) {
53
+ const timeoutMs = opts.timeoutMs ?? DEFAULT_SAMPLING_TIMEOUT_MS;
54
+ const id = `mdss-srv-${++nextId}`;
55
+ return new Promise((resolve, reject) => {
56
+ const timer = setTimeout(() => {
57
+ pending.delete(id);
58
+ reject(new Error(`${method}: client did not respond within ${timeoutMs}ms`));
59
+ }, timeoutMs);
60
+ timer.unref?.();
61
+ pending.set(id, { resolve, reject, timer });
62
+ try {
63
+ send({ jsonrpc: '2.0', id, method, params });
64
+ }
65
+ catch (e) {
66
+ clearTimeout(timer);
67
+ pending.delete(id);
68
+ reject(new Error(`${method}: ${e?.message || String(e)}`));
69
+ }
70
+ });
71
+ },
72
+ handleResponse(msg) {
73
+ if (!msg || typeof msg !== 'object' || msg.method !== undefined)
74
+ return false;
75
+ const entry = pending.get(msg.id);
76
+ if (!entry)
77
+ return false;
78
+ clearTimeout(entry.timer);
79
+ pending.delete(msg.id);
80
+ if (msg.error) {
81
+ entry.reject(new Error(msg.error.message || `client error ${msg.error.code ?? ''}`));
82
+ }
83
+ else {
84
+ entry.resolve(msg.result);
85
+ }
86
+ return true;
87
+ },
88
+ };
89
+ }
90
+ /**
91
+ * A sampling-backed synthesis hook for the RAG layer (issue #197): returns
92
+ * null unless the client both declared the `sampling` capability at
93
+ * initialize AND a reverse channel exists — otherwise ask_knowledge_base goes
94
+ * straight to the local extractive answer. Any in-flight failure (client
95
+ * refusal, timeout, non-text content) throws and degrades the same way.
96
+ */
97
+ export function createSamplingSynthesizer(state) {
98
+ if (!state.channel || !state.clientCapabilities?.sampling)
99
+ return null;
100
+ let used = false;
101
+ const channel = state.channel;
102
+ return {
103
+ used: () => used,
104
+ fn: async ({ system, user }) => {
105
+ const result = await channel.request('sampling/createMessage', {
106
+ messages: [{ role: 'user', content: { type: 'text', text: user } }],
107
+ systemPrompt: system,
108
+ includeContext: 'thisServer',
109
+ maxTokens: DEFAULT_SAMPLING_MAX_TOKENS,
110
+ }, { timeoutMs: samplingTimeoutMs() });
111
+ const text = result?.content?.text;
112
+ if (typeof text !== 'string' || !text.trim()) {
113
+ throw new Error('sampling/createMessage returned no text content');
114
+ }
115
+ used = true;
116
+ return text;
117
+ },
118
+ };
119
+ }
20
120
  export const MCP_TOOLS = [
21
121
  {
22
122
  name: 'search_markdown',
@@ -208,12 +308,21 @@ export async function handleMcpRequest(req, state) {
208
308
  if (id === undefined || id === null) {
209
309
  return null;
210
310
  }
311
+ // A JSON-RPC *response* to one of our server→client requests carries an id
312
+ // but no method — the transport's channel correlation already consumed any
313
+ // that matched; replying to the leftovers would be nonsense.
314
+ if (typeof method !== 'string') {
315
+ return null;
316
+ }
211
317
  if (method === 'initialize') {
318
+ // issue #197: remember what the client can do — `sampling` opens the
319
+ // ask_knowledge_base LLM path — and answer with the negotiated version.
320
+ state.clientCapabilities = params?.capabilities ?? {};
212
321
  return {
213
322
  jsonrpc: '2.0',
214
323
  id,
215
324
  result: {
216
- protocolVersion: '2024-11-05',
325
+ protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
217
326
  capabilities: {
218
327
  tools: {
219
328
  listChanged: false,
@@ -233,6 +342,15 @@ export async function handleMcpRequest(req, state) {
233
342
  },
234
343
  };
235
344
  }
345
+ // issue #197: liveness probe per the 2025-11-25 spec — answer promptly with
346
+ // an empty result, regardless of initialization state.
347
+ if (method === 'ping') {
348
+ return {
349
+ jsonrpc: '2.0',
350
+ id,
351
+ result: {},
352
+ };
353
+ }
236
354
  if (method === 'tools/list') {
237
355
  return {
238
356
  jsonrpc: '2.0',
@@ -363,9 +481,9 @@ export async function handleMcpRequest(req, state) {
363
481
  // Read entire document
364
482
  let fullText = null;
365
483
  if (state.loaded.index.db) {
484
+ const absPath = assertSafePath(path.resolve(state.loaded.index.db, file), [state.loaded.index.db]);
366
485
  try {
367
- const absPath = path.join(state.loaded.index.db, file);
368
- if (fs.existsSync(absPath)) {
486
+ if (fs.existsSync(absPath) && fs.statSync(absPath).isFile()) {
369
487
  fullText = fs.readFileSync(absPath, 'utf8');
370
488
  }
371
489
  }
@@ -398,12 +516,19 @@ export async function handleMcpRequest(req, state) {
398
516
  };
399
517
  }
400
518
  catch (e) {
519
+ if (/path traversal guard|Forbidden path/i.test(e.message || '')) {
520
+ return {
521
+ jsonrpc: '2.0',
522
+ id,
523
+ error: { code: -32602, message: e.message },
524
+ };
525
+ }
401
526
  return {
402
527
  jsonrpc: '2.0',
403
528
  id,
404
- result: {
405
- isError: true,
406
- content: [{ type: 'text', text: `Error reading resource: ${e.message}` }],
529
+ error: {
530
+ code: e.message?.includes('not found') ? -32602 : -32603,
531
+ message: `Error reading resource: ${e.message}`,
407
532
  },
408
533
  };
409
534
  }
@@ -537,8 +662,19 @@ export async function handleMcpRequest(req, state) {
537
662
  const query = typeof args.query === 'string' ? args.query : '';
538
663
  const k = Number.isInteger(args.k) && args.k > 0 ? args.k : 6;
539
664
  if (Array.isArray(args.vaults) && args.vaults.length > 0) {
540
- rawResult = await searchFederated({
665
+ // issue #179: the vaults argument must never name an arbitrary
666
+ // directory (silent index read + query-cache write outside the
667
+ // vault). Pin federated roots to the daemon's own trust domain —
668
+ // the indexed vault root, widened only via MDSS_ROOT_GUARD.
669
+ const vaultRoots = [
670
+ state.loaded.index.db,
671
+ ...(process.env.MDSS_ROOT_GUARD
672
+ ? process.env.MDSS_ROOT_GUARD.split(path.delimiter).map((p) => p.trim()).filter(Boolean)
673
+ : []),
674
+ ].filter(Boolean);
675
+ const fed = await searchFederated({
541
676
  vaults: args.vaults,
677
+ allowedRoots: vaultRoots,
542
678
  cacheDir: state.cacheDir,
543
679
  query,
544
680
  k,
@@ -549,6 +685,9 @@ export async function handleMcpRequest(req, state) {
549
685
  offline: state.offline,
550
686
  embedFn: state.embedFn,
551
687
  });
688
+ // issue #189: broken vaults surface in the tool payload instead of
689
+ // masquerading as "no results"
690
+ rawResult = { results: fed.hits, vaultErrors: fed.vaultErrors };
552
691
  }
553
692
  else {
554
693
  rawResult = await searchIndex({
@@ -632,6 +771,11 @@ export async function handleMcpRequest(req, state) {
632
771
  const query = args.query;
633
772
  const k = typeof args.k === 'number' ? args.k : 5;
634
773
  const sessionId = args.sessionId || args.session_id;
774
+ // issue #197: with a sampling-capable client, hand the synthesis to
775
+ // the client's own LLM via sampling/createMessage — no local model,
776
+ // no user-side LLM config. Any failure (capability absent, client
777
+ // refusal, timeout) degrades to the extractive answer as before.
778
+ const sampling = createSamplingSynthesizer(state);
635
779
  if (sessionId && typeof sessionId === 'string') {
636
780
  const indexDir = state.loaded.indexDir || (state.loaded.index?.db ? path.join(state.loaded.index.db, '.mdss') : state.cacheDir);
637
781
  const session = loadChatSession(indexDir, sessionId);
@@ -643,6 +787,7 @@ export async function handleMcpRequest(req, state) {
643
787
  cacheDir: state.cacheDir,
644
788
  k,
645
789
  embedFn: state.embedFn,
790
+ llmRequestFn: sampling?.fn,
646
791
  });
647
792
  rawResult = {
648
793
  answer: turnResult.answer,
@@ -650,16 +795,22 @@ export async function handleMcpRequest(req, state) {
650
795
  manifest: turnResult.manifest,
651
796
  sessionId: turnResult.session.id,
652
797
  turnsCount: turnResult.session.turns.length,
798
+ answerMode: sampling?.used() ? 'sampling' : 'extractive',
653
799
  };
654
800
  }
655
801
  else {
656
- rawResult = await askQuestion({
802
+ const synth = await askQuestion({
657
803
  loaded: state.loaded,
658
804
  cacheDir: state.cacheDir,
659
805
  query,
660
806
  k,
661
807
  embedFn: state.embedFn,
808
+ llmRequestFn: sampling?.fn,
662
809
  });
810
+ rawResult = {
811
+ ...synth,
812
+ answerMode: sampling?.used() ? 'sampling' : 'extractive',
813
+ };
663
814
  }
664
815
  }
665
816
  else {
@@ -669,12 +820,22 @@ export async function handleMcpRequest(req, state) {
669
820
  error: { code: -32601, message: `Unknown tool: ${name}` },
670
821
  };
671
822
  }
823
+ // issue #205: the MCP spec requires structuredContent to be an OBJECT
824
+ // when present — strict clients reject bare arrays outright. Text content
825
+ // keeps the raw result verbatim for clients reading content[0].text.
826
+ const structured = Array.isArray(rawResult)
827
+ ? name === 'list_files'
828
+ ? { files: rawResult }
829
+ : name === 'get_chunk'
830
+ ? { chunks: rawResult }
831
+ : { results: rawResult }
832
+ : rawResult;
672
833
  return {
673
834
  jsonrpc: '2.0',
674
835
  id,
675
836
  result: {
676
837
  content: [{ type: 'text', text: JSON.stringify(rawResult, null, 2) }],
677
- structuredContent: rawResult,
838
+ structuredContent: structured,
678
839
  },
679
840
  };
680
841
  }
@@ -696,7 +857,7 @@ export async function handleMcpRequest(req, state) {
696
857
  };
697
858
  }
698
859
  export async function startMcpServer(opts) {
699
- const { indexDir, cacheDir, db, modelName = 'e5-base', ignore = [], offline = false, embedFn, log = () => { }, } = opts;
860
+ const { indexDir, cacheDir, db, modelName = 'e5-base', ignore = [], offline = false, embedFn, input = process.stdin, output = process.stdout, log = () => { }, } = opts;
700
861
  fs.mkdirSync(indexDir, { recursive: true });
701
862
  if (!fs.existsSync(path.join(indexDir, 'vectors.json'))) {
702
863
  if (!db)
@@ -709,32 +870,99 @@ export async function startMcpServer(opts) {
709
870
  cacheDir,
710
871
  offline,
711
872
  embedFn,
873
+ output,
712
874
  };
875
+ // issue #197: over stdio the reverse channel is the transport itself —
876
+ // server→client requests (sampling) go out as JSON-RPC lines on stdout and
877
+ // the client answers with plain response lines on stdin.
878
+ const channel = createClientChannel((msg) => output.write(JSON.stringify(msg) + '\n'));
879
+ state.channel = channel;
713
880
  const rl = readline.createInterface({
714
- input: process.stdin,
715
- output: process.stdout,
881
+ input,
716
882
  terminal: false,
717
883
  });
718
- rl.on('line', async (line) => {
884
+ // issue #185: an async 'line' handler drops its promise — any rejection
885
+ // outside the per-tool try/catch (e.g. a primitive `params` reaching
886
+ // prompts/get) would crash the whole process (unhandled rejection, Node ≥15),
887
+ // and handling lines in parallel can reorder responses. Route every line
888
+ // through one guarded, serialized handler.
889
+ let tail = Promise.resolve();
890
+ rl.on('line', (line) => {
891
+ // issue #197: a response line resolves a pending server→client request
892
+ // immediately — the serialized chain below is blocked awaiting exactly
893
+ // that request (sampling), so queueing the answer behind itself would
894
+ // deadlock. Only client requests/notifications join the chain.
719
895
  const trimmed = line.trim();
720
- if (!trimmed)
721
- return;
722
- let req;
723
- try {
724
- req = JSON.parse(trimmed);
725
- }
726
- catch {
727
- process.stdout.write(JSON.stringify({
728
- jsonrpc: '2.0',
729
- id: null,
730
- error: { code: -32700, message: 'Parse error: invalid JSON' },
731
- }) + '\n');
732
- return;
733
- }
734
- const res = await handleMcpRequest(req, state);
735
- if (res) {
736
- process.stdout.write(JSON.stringify(res) + '\n');
896
+ if (trimmed) {
897
+ try {
898
+ const msg = JSON.parse(trimmed);
899
+ if (msg &&
900
+ typeof msg === 'object' &&
901
+ msg.method === undefined &&
902
+ (msg.result !== undefined || msg.error !== undefined) &&
903
+ channel.handleResponse(msg)) {
904
+ return;
905
+ }
906
+ }
907
+ catch {
908
+ /* not JSON — handleStdioLine turns it into -32700 */
909
+ }
737
910
  }
911
+ tail = tail
912
+ .then(() => handleStdioLine(line, state))
913
+ .catch(() => {
914
+ /* handleStdioLine guards everything — keep the chain alive regardless */
915
+ });
738
916
  });
739
917
  return { state, rl };
740
918
  }
919
+ /**
920
+ * One guarded, in-order stdio JSON-RPC exchange (issues #180/#185): caps the
921
+ * line length, turns JSON parse failures into `-32700`, and converts ANY
922
+ * handler escape into a `-32603` response instead of an unhandled rejection
923
+ * that would kill the daemon.
924
+ */
925
+ export const MAX_STDIO_LINE_CHARS = 1024 * 1024;
926
+ export async function handleStdioLine(line, state) {
927
+ const out = state.output ?? process.stdout;
928
+ if (line.length > MAX_STDIO_LINE_CHARS) {
929
+ out.write(JSON.stringify({
930
+ jsonrpc: '2.0',
931
+ id: null,
932
+ error: {
933
+ code: -32600,
934
+ message: `Request too large (max ${MAX_STDIO_LINE_CHARS} chars per line)`,
935
+ },
936
+ }) + '\n');
937
+ return;
938
+ }
939
+ const trimmed = line.trim();
940
+ if (!trimmed)
941
+ return;
942
+ let req;
943
+ try {
944
+ req = JSON.parse(trimmed);
945
+ }
946
+ catch {
947
+ out.write(JSON.stringify({
948
+ jsonrpc: '2.0',
949
+ id: null,
950
+ error: { code: -32700, message: 'Parse error: invalid JSON' },
951
+ }) + '\n');
952
+ return;
953
+ }
954
+ let res;
955
+ try {
956
+ res = await handleMcpRequest(req, state);
957
+ }
958
+ catch (e) {
959
+ res = {
960
+ jsonrpc: '2.0',
961
+ id: req && typeof req === 'object' && 'id' in req ? req.id : null,
962
+ error: { code: -32603, message: `Internal error: ${e?.message || String(e)}` },
963
+ };
964
+ }
965
+ if (res) {
966
+ out.write(JSON.stringify(res) + '\n');
967
+ }
968
+ }
package/dist/models.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export type Pooling = 'mean' | 'last_token' | 'none';
1
+ export type Pooling = 'mean' | 'last_token' | 'none' | 'cls';
2
2
  export type DType = 'q8' | 'q4' | 'fp16' | 'fp32' | 'int8' | 'uint8';
3
3
  export interface ModelAdapter {
4
4
  id: string;
@@ -13,6 +13,12 @@ export interface ModelAdapter {
13
13
  dtype?: DType | string;
14
14
  maxTokens?: number;
15
15
  sessionOptions?: Record<string, unknown>;
16
+ /**
17
+ * issue #200: the ONNX graph already emits a pooled `sentence_embedding`
18
+ * (e.g. EmbeddingGemma) — embedding bypasses the feature-extraction
19
+ * pipeline and reads that output directly; `pooling: 'none'` is implied.
20
+ */
21
+ pooledOutput?: boolean;
16
22
  family?: string;
17
23
  note?: string;
18
24
  unknownAdapter?: boolean;
package/dist/models.js CHANGED
@@ -71,9 +71,39 @@ export const MODELS = {
71
71
  family: 'qwen3',
72
72
  note: '~613 MB q8. Opt-in Qwen3 embedding model with Matryoshka/MRL support.',
73
73
  },
74
+ 'granite-multilingual-311m': {
75
+ id: 'onnx-community/granite-embedding-311m-multilingual-r2-ONNX',
76
+ revision: '8f039f21d4181327268271bea4b11ddcc7eef88d',
77
+ nativeDim: 768,
78
+ dim: 768,
79
+ queryPrefix: '',
80
+ passagePrefix: '',
81
+ pooling: 'cls',
82
+ normalize: true,
83
+ dtype: 'q8',
84
+ maxTokens: 8192,
85
+ family: 'granite',
86
+ note: '~298 MB q8. IBM Granite r2, ModernBERT (8k context), CLS pooling, Apache-2.0. Issue #200.',
87
+ },
88
+ 'embeddinggemma-300m': {
89
+ id: 'onnx-community/embeddinggemma-300m-ONNX',
90
+ revision: '5090578d9565bb06545b4552f76e6bc2c93e4a66',
91
+ nativeDim: 768,
92
+ dim: 768,
93
+ dimensions: [64, 128, 256, 512, 768],
94
+ queryPrefix: 'task: search result | query: ',
95
+ passagePrefix: 'title: none | text: ',
96
+ pooling: 'none',
97
+ normalize: true,
98
+ dtype: 'q8',
99
+ maxTokens: 2048,
100
+ pooledOutput: true,
101
+ family: 'gemma',
102
+ note: '~300 MB q8. Google EmbeddingGemma, pre-pooled sentence_embedding output, MRL. Gemma license (not MIT/Apache). Issue #200.',
103
+ },
74
104
  };
75
105
  export const DEFAULT_MODEL = 'e5-base';
76
- export const POOLING = ['mean', 'last_token', 'none'];
106
+ export const POOLING = ['mean', 'last_token', 'none', 'cls'];
77
107
  const POOLING_SET = new Set(POOLING);
78
108
  const aliasByRepoId = new Map();
79
109
  for (const [alias, adapter] of Object.entries(MODELS)) {
@@ -115,6 +145,7 @@ export function normalizeAdapter(raw) {
115
145
  normalize: raw.normalize !== false,
116
146
  dtype: typeof raw.dtype === 'string' && raw.dtype.length > 0 ? raw.dtype : 'q8',
117
147
  ...(Number.isSafeInteger(raw.maxTokens) && raw.maxTokens && raw.maxTokens > 0 ? { maxTokens: raw.maxTokens } : {}),
148
+ ...(raw.pooledOutput === true ? { pooledOutput: true } : {}),
118
149
  ...(typeof raw.family === 'string' && raw.family.length > 0 ? { family: raw.family } : {}),
119
150
  ...(typeof raw.note === 'string' ? { note: raw.note } : {}),
120
151
  });
@@ -19,3 +19,59 @@ export interface ResolvedEmbedder {
19
19
  }
20
20
  /** Build an external embedder; dim is probed once on first use and cached. */
21
21
  export declare function resolveExternalEmbedder(cfg: ProviderConfig): ResolvedEmbedder;
22
+ /**
23
+ * Chat provider (issue #199): one OpenAI-compatible `/chat/completions` path
24
+ * for answer synthesis — the same lingua franca HyDE already speaks — with an
25
+ * Ollama-native `/api/generate` legacy path (`--llm-provider ollama`) that
26
+ * preserves the pre-#199 wire format for existing setups.
27
+ */
28
+ export type ChatProviderId = 'openai' | 'ollama';
29
+ export interface ChatProviderConfig {
30
+ provider: ChatProviderId;
31
+ /** Provider-side model name; omitted bodies let the server pick its default. */
32
+ model?: string;
33
+ baseUrl?: string;
34
+ keyFile?: string;
35
+ /** Injected fetch for tests; defaults to globalThis.fetch. */
36
+ fetchImpl?: typeof fetch;
37
+ }
38
+ export interface ChatRequest {
39
+ system: string;
40
+ user: string;
41
+ /** Streaming render hook; fires once per token chunk when the wire streams. */
42
+ onDelta?: (delta: string) => void;
43
+ /** Cooperative cancel (serve: client disconnected mid-stream). */
44
+ signal?: AbortSignal;
45
+ }
46
+ export interface ResolvedChat {
47
+ id: ChatProviderId;
48
+ model: string;
49
+ /** Streams one completion; resolves to the assembled full text. */
50
+ complete(req: ChatRequest): Promise<string>;
51
+ }
52
+ /**
53
+ * Incremental SSE frame parser (issue #199): feed it raw network chunks, it
54
+ * emits one `data:` payload per complete event. Handles CRLF, LF-only streams,
55
+ * multi-line `data:` fields (joined with \n per the WHATWG spec), comment
56
+ * keep-alive lines (`: ping`), and chunks that split a line or a CRLF pair
57
+ * across the boundary. Non-`data` fields (event/id/retry) are irrelevant to
58
+ * the chat delta stream and dropped.
59
+ */
60
+ export declare function createSseParser(onData: (data: string) => void): {
61
+ push(chunk: string): void;
62
+ end(): void;
63
+ };
64
+ /** `data:` payload of an OpenAI streaming chunk → delta text ('' when none). */
65
+ export declare function openAiDeltaText(payload: string): string;
66
+ /** One Ollama NDJSON streaming line → delta text ('' when none). */
67
+ export declare function ollamaDeltaText(line: string): string;
68
+ /**
69
+ * Build a chat completion provider over HTTP streaming (issue #199).
70
+ * `openai` → POST {base}/chat/completions with `stream:true`, SSE deltas.
71
+ * `ollama` → POST {base}/api/generate with `stream:true`, NDJSON deltas —
72
+ * the pre-#199 endpoint, upgraded from `stream:false` to streaming. The
73
+ * openai path additionally falls back to /api/generate once when the endpoint
74
+ * answers 404/405 (not OpenAI-shaped), so an Ollama root URL keeps working
75
+ * with default flags.
76
+ */
77
+ export declare function resolveChatProvider(cfg: ChatProviderConfig): ResolvedChat;