@madewithremy/admin 0.1.56 → 0.1.58
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.
- package/CHANGELOG.md +16 -0
- package/README.md +1 -1
- package/dist/client.d.ts +199 -0
- package/dist/config.d.ts +8 -0
- package/dist/ctx.d.ts +36 -0
- package/dist/errors.d.ts +68 -0
- package/dist/http.d.ts +68 -0
- package/dist/index.d.ts +7 -9434
- package/dist/index.js +6 -6
- package/dist/index.js.map +7 -1
- package/dist/ops/agent.d.ts +44 -0
- package/dist/ops/analytics.d.ts +285 -0
- package/dist/ops/apps.d.ts +33 -0
- package/dist/ops/crashes.d.ts +86 -0
- package/dist/ops/cron.d.ts +40 -0
- package/dist/ops/data.d.ts +68 -0
- package/dist/ops/dataSourceConnectors.d.ts +80 -0
- package/dist/ops/dataSourceEvals.d.ts +208 -0
- package/dist/ops/dataSourceJobs.d.ts +141 -0
- package/dist/ops/dataSourceMappers.d.ts +125 -0
- package/dist/ops/dataSources.d.ts +654 -0
- package/dist/ops/db.d.ts +81 -0
- package/dist/ops/diagnostics.d.ts +42 -0
- package/dist/ops/domains.d.ts +250 -0
- package/dist/ops/email.d.ts +305 -0
- package/dist/ops/events.d.ts +56 -0
- package/dist/ops/feedback.d.ts +24 -0
- package/dist/ops/files.d.ts +166 -0
- package/dist/ops/infra.d.ts +163 -0
- package/dist/ops/issues.d.ts +160 -0
- package/dist/ops/jewels.d.ts +249 -0
- package/dist/ops/methods.d.ts +60 -0
- package/dist/ops/prerender.d.ts +74 -0
- package/dist/ops/previews.d.ts +52 -0
- package/dist/ops/qaRecordings.d.ts +68 -0
- package/dist/ops/releases.d.ts +193 -0
- package/dist/ops/requests.d.ts +73 -0
- package/dist/ops/secrets.d.ts +69 -0
- package/dist/ops/settings.d.ts +45 -0
- package/dist/ops/tasks.d.ts +47 -0
- package/dist/ops/usage.d.ts +40 -0
- package/dist/ops/users.d.ts +59 -0
- package/dist/ops/voice.d.ts +178 -0
- package/dist/output.d.ts +19 -0
- package/dist/parseJsonConfig.d.ts +41 -0
- package/dist/poll.d.ts +38 -0
- package/dist/prod.js +24 -21
- package/dist/runningMethod.d.ts +25 -0
- package/dist/sleep.d.ts +12 -0
- package/dist/types/agent.d.ts +95 -0
- package/dist/types/analytics.d.ts +225 -0
- package/dist/types/apps.d.ts +39 -0
- package/dist/types/crashes.d.ts +81 -0
- package/dist/types/cron.d.ts +68 -0
- package/dist/types/data.d.ts +38 -0
- package/dist/types/dataSourceConnectors.d.ts +59 -0
- package/dist/types/dataSourceEvals.d.ts +225 -0
- package/dist/types/dataSourceJobs.d.ts +283 -0
- package/dist/types/dataSourceMappers.d.ts +204 -0
- package/dist/types/dataSourceReaders.d.ts +102 -0
- package/dist/types/dataSources.d.ts +627 -0
- package/dist/types/db.d.ts +63 -0
- package/dist/types/diagnostics.d.ts +96 -0
- package/dist/types/domains.d.ts +277 -0
- package/dist/types/email.d.ts +400 -0
- package/dist/types/events.d.ts +54 -0
- package/dist/types/feedback.d.ts +11 -0
- package/dist/types/files.d.ts +150 -0
- package/dist/types/index.d.ts +37 -0
- package/dist/types/infra.d.ts +188 -0
- package/dist/types/issues.d.ts +106 -0
- package/dist/types/jewels.d.ts +336 -0
- package/dist/types/methods.d.ts +34 -0
- package/dist/types/prerender.d.ts +59 -0
- package/dist/types/previews.d.ts +39 -0
- package/dist/types/progress.d.ts +31 -0
- package/dist/types/qaRecordings.d.ts +51 -0
- package/dist/types/releases.d.ts +233 -0
- package/dist/types/requests.d.ts +114 -0
- package/dist/types/secrets.d.ts +52 -0
- package/dist/types/settings.d.ts +79 -0
- package/dist/types/tasks.d.ts +99 -0
- package/dist/types/usage.d.ts +29 -0
- package/dist/types/users.d.ts +61 -0
- package/dist/types/voice.d.ts +197 -0
- package/dist/upload.d.ts +11 -0
- package/package.json +7 -10
|
@@ -0,0 +1,654 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Data-sources operations: document ingestion, corpus search, pipeline
|
|
3
|
+
* configuration, and version management.
|
|
4
|
+
*
|
|
5
|
+
* Ops are pure (ctx, params) → typed result; no printing, no process coupling.
|
|
6
|
+
* The CLI skin in commands/dataSources.ts owns everything flag-shaped (path
|
|
7
|
+
* resolution, parseKeyValuePairs, configFromFlags, out/progress calls,
|
|
8
|
+
* process.exit for wait-path exit codes).
|
|
9
|
+
*/
|
|
10
|
+
import type { AdminContext } from '../ctx.js';
|
|
11
|
+
import type { DataSourcesBuildProgress, DataSourcesConfigResult, DataSourcesConfigUpdateResult, DataSourcesCreateResult, DataSourcesDeleteResult, DataSourcesDocument, DataSourcesDocumentDeleteManyResult, DataSourcesDocumentDeleteResult, DataSourcesDocumentSelector, DataSourcesDocumentsResult, DataSourcesDocumentStatus, DataSourcesDropResult, DataSourcesIngestUpdate, DataSourcesListEntry, DataSourcesListResult, DataSourcesMoveResult, DataSourcesPromoteResult, DataSourcesRetrievalUpdate, DataSourcesRevectorizeResult, DataSourcesSearchResult, DataSourcesCountResult, DataSourcesDictionaryPushResult, DataSourcesDictionaryStatus, DataSourcesLinkResult, DataSourcesEntitiesResult, DataSourcesPassagesResult } from '../types/dataSources.js';
|
|
12
|
+
import type { DataSourceJob } from '../types/dataSourceJobs.js';
|
|
13
|
+
/** @internal Consumed by the CLI skin; waitForIngest documents the default. */
|
|
14
|
+
export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
|
|
15
|
+
/**
|
|
16
|
+
* The per-document summary projection used by waitForIngest, status, and the
|
|
17
|
+
* revectorize watch loop in the skin. Exported so the skin can reuse it for
|
|
18
|
+
* the revectorize path without re-implementing it.
|
|
19
|
+
* @internal Presentation helper for the CLI skin, not client surface.
|
|
20
|
+
*/
|
|
21
|
+
export declare const summarize: (d: DataSourcesDocumentStatus) => {
|
|
22
|
+
id: string;
|
|
23
|
+
filename: string | null;
|
|
24
|
+
status: string;
|
|
25
|
+
chunks: number | null;
|
|
26
|
+
pages: number | null;
|
|
27
|
+
error?: string | undefined;
|
|
28
|
+
};
|
|
29
|
+
export interface AddDocumentParams {
|
|
30
|
+
/** Data source slug. Created on first use. */
|
|
31
|
+
slug: string;
|
|
32
|
+
/** Original filename — used as the key and for MIME-type inference. */
|
|
33
|
+
filename: string;
|
|
34
|
+
/** File bytes to upload. */
|
|
35
|
+
content: Buffer;
|
|
36
|
+
/**
|
|
37
|
+
* Scalar tags filterable at search time (≤ 16 keys,
|
|
38
|
+
* `string | number | boolean` values).
|
|
39
|
+
*/
|
|
40
|
+
metadata?: Record<string, string | number | boolean>;
|
|
41
|
+
/**
|
|
42
|
+
* What the document is about, as the app's own ids (≤ 256, printable ASCII,
|
|
43
|
+
* no whitespace or commas). Every passage carries them; `[]` clears them.
|
|
44
|
+
*/
|
|
45
|
+
entities?: string[];
|
|
46
|
+
/**
|
|
47
|
+
* The budget in dollars of the job that takes the rest of a file mapping
|
|
48
|
+
* to more than a thousand documents (`AddDocumentResult.job`).
|
|
49
|
+
*/
|
|
50
|
+
budgetDollars?: number;
|
|
51
|
+
/**
|
|
52
|
+
* Receives the exact progress strings the CLI prints today:
|
|
53
|
+
* - `${filename}: unchanged, skipped`
|
|
54
|
+
* - `${filename}: uploading N MB…`
|
|
55
|
+
*/
|
|
56
|
+
onProgress?: (message: string) => void;
|
|
57
|
+
}
|
|
58
|
+
export interface AddDocumentResult {
|
|
59
|
+
filename: string;
|
|
60
|
+
skipped: boolean;
|
|
61
|
+
queued?: boolean;
|
|
62
|
+
/**
|
|
63
|
+
* The document, or the first of them on a mapped source. Null only when the
|
|
64
|
+
* source's mapper answered `deletes` for the file.
|
|
65
|
+
*/
|
|
66
|
+
document: DataSourcesDocument | null;
|
|
67
|
+
/**
|
|
68
|
+
* Every document the file became — one on an unmapped source — or the
|
|
69
|
+
* first thousand of a file that maps to more.
|
|
70
|
+
*/
|
|
71
|
+
documents: DataSourcesDocument[];
|
|
72
|
+
/** How many documents the file maps to in all. */
|
|
73
|
+
documentCount: number;
|
|
74
|
+
/** How the source took the file; absent when it was already current. */
|
|
75
|
+
outcome?: 'unmapped' | 'documents' | 'passthrough' | 'deletes';
|
|
76
|
+
/** Documents the mapper produced that failed validation and were not registered. */
|
|
77
|
+
invalid?: {
|
|
78
|
+
count: number;
|
|
79
|
+
examples: {
|
|
80
|
+
document: number;
|
|
81
|
+
reason: string;
|
|
82
|
+
}[];
|
|
83
|
+
} | null;
|
|
84
|
+
/**
|
|
85
|
+
* The job registering and building the rest of a file that maps to more
|
|
86
|
+
* than a thousand documents; it plans and starts on its own.
|
|
87
|
+
*/
|
|
88
|
+
job?: DataSourceJob | null;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Add one document to a data source.
|
|
92
|
+
*
|
|
93
|
+
* Three-step flow: hash → token → (skip-if-current) → upload → confirm.
|
|
94
|
+
* Re-adding an unchanged file short-circuits at the token step and moves no
|
|
95
|
+
* bytes. Re-adding with different `metadata` updates the tags in-place, also
|
|
96
|
+
* without a re-upload. The data source is created on first use.
|
|
97
|
+
*
|
|
98
|
+
* @throws AdminApiError `invalid_content_hash` (400) — malformed hash
|
|
99
|
+
* (internal; `addDocument` computes this from `content`).
|
|
100
|
+
* @throws AdminApiError `document_limit_reached` (422) — the source holds the
|
|
101
|
+
* app's limit of documents (`documentLimit` in `list`); support raises it.
|
|
102
|
+
* @example
|
|
103
|
+
* const result = await admin.dataSources.addDocument({
|
|
104
|
+
* slug: 'policies',
|
|
105
|
+
* filename: 'contract.pdf',
|
|
106
|
+
* content: pdfBuffer,
|
|
107
|
+
* metadata: { department: 'legal', year: 2026 },
|
|
108
|
+
* });
|
|
109
|
+
*/
|
|
110
|
+
export declare function addDocument(ctx: AdminContext, params: AddDocumentParams): Promise<AddDocumentResult>;
|
|
111
|
+
export interface WaitForIngestParams {
|
|
112
|
+
slug: string;
|
|
113
|
+
documentIds: string[];
|
|
114
|
+
/** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
|
|
115
|
+
timeoutMs?: number;
|
|
116
|
+
/**
|
|
117
|
+
* Receives the exact progress strings the CLI prints today:
|
|
118
|
+
* `ingesting… X/Y done (Ns)`
|
|
119
|
+
*/
|
|
120
|
+
onProgress?: (message: string) => void;
|
|
121
|
+
}
|
|
122
|
+
export type SummarizedDocument = ReturnType<typeof summarize>;
|
|
123
|
+
export interface WaitForIngestResult {
|
|
124
|
+
status: 'up-to-date' | 'done' | 'error' | 'timeout';
|
|
125
|
+
documents: SummarizedDocument[];
|
|
126
|
+
/** Present only on status === 'timeout'. */
|
|
127
|
+
error?: string;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Poll until every queued document reaches a terminal state.
|
|
131
|
+
*
|
|
132
|
+
* Terminal states: `done` (all succeeded), `error` (at least one failed),
|
|
133
|
+
* `timeout` (still processing after `timeoutMs`, default 15 minutes). Polls
|
|
134
|
+
* every 3 seconds. Returns a typed result so the caller can branch on
|
|
135
|
+
* `status` without parsing strings.
|
|
136
|
+
*
|
|
137
|
+
* The `dataSource: slug` envelope and exit-code handling stay in the CLI skin
|
|
138
|
+
* so the printed JSON is byte-identical to the pre-refactor CLI.
|
|
139
|
+
*
|
|
140
|
+
* @example
|
|
141
|
+
* const result = await admin.dataSources.waitForIngest({
|
|
142
|
+
* slug: 'policies',
|
|
143
|
+
* documentIds: [doc.id],
|
|
144
|
+
* onProgress: console.error,
|
|
145
|
+
* });
|
|
146
|
+
* if (result.status === 'error') { ... }
|
|
147
|
+
*/
|
|
148
|
+
export declare function waitForIngest(ctx: AdminContext, params: WaitForIngestParams): Promise<WaitForIngestResult>;
|
|
149
|
+
export interface WaitForCandidateParams {
|
|
150
|
+
slug: string;
|
|
151
|
+
/** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
|
|
152
|
+
timeoutMs?: number;
|
|
153
|
+
/** Receives `rebuilding… X/Y done (Ns)`. */
|
|
154
|
+
onProgress?: (message: string) => void;
|
|
155
|
+
}
|
|
156
|
+
export interface WaitForCandidateResult {
|
|
157
|
+
status: 'ready' | 'error' | 'timeout';
|
|
158
|
+
/** The candidate's build counts when the wait ended; null when it had no candidate. */
|
|
159
|
+
counts: DataSourcesBuildProgress | null;
|
|
160
|
+
/** The failed documents, first page, when any failed. */
|
|
161
|
+
documents: SummarizedDocument[];
|
|
162
|
+
/** Present only on status === 'timeout'. */
|
|
163
|
+
error?: string;
|
|
164
|
+
}
|
|
165
|
+
/** Failed documents fetched for a status or a candidate wait. */
|
|
166
|
+
export declare const FAILURES_PAGE = 50;
|
|
167
|
+
/**
|
|
168
|
+
* Poll a candidate version (`revectorize`) until every document has built.
|
|
169
|
+
* Reads the candidate's counts from the source list — one row, whatever the
|
|
170
|
+
* corpus holds — and fetches the failures only at the end. `error` means at
|
|
171
|
+
* least one failed; `promote` with `force` accepts that.
|
|
172
|
+
*/
|
|
173
|
+
export declare function waitForCandidate(ctx: AdminContext, params: WaitForCandidateParams): Promise<WaitForCandidateResult>;
|
|
174
|
+
export interface DocumentsParams {
|
|
175
|
+
/** Data source slug. */
|
|
176
|
+
slug: string;
|
|
177
|
+
/** true → watch a candidate pipeline (revectorize in progress). */
|
|
178
|
+
candidate?: boolean;
|
|
179
|
+
/** Only these documents (at most DOCUMENTS_IDS_MAX per request). */
|
|
180
|
+
ids?: string[];
|
|
181
|
+
/** Page size, 1..1000 (server default 500). */
|
|
182
|
+
limit?: number;
|
|
183
|
+
/** `nextCursor` from the previous page. */
|
|
184
|
+
cursor?: string;
|
|
185
|
+
/** By the time the document was added; oldest first unless said otherwise. */
|
|
186
|
+
order?: 'oldest' | 'newest';
|
|
187
|
+
/** The failed builds only, newest failure first. */
|
|
188
|
+
status?: 'error';
|
|
189
|
+
/** Filenames starting with this. */
|
|
190
|
+
filename?: string;
|
|
191
|
+
}
|
|
192
|
+
/** The server's cap on `ids` per request; `allDocuments` chunks to it. */
|
|
193
|
+
export declare const DOCUMENTS_IDS_MAX = 200;
|
|
194
|
+
/**
|
|
195
|
+
* Fetch one page of per-document ingest state for one pipeline, oldest first
|
|
196
|
+
* unless `order` says otherwise; `status: 'error'` narrows to the failures and
|
|
197
|
+
* `filename` to a name prefix.
|
|
198
|
+
*
|
|
199
|
+
* Returns an empty document list when the data source does not exist yet.
|
|
200
|
+
* Pass `candidate: true` to watch a revectorization in progress. Follow
|
|
201
|
+
* `nextCursor` for the next page, or use `allDocuments` to walk them all.
|
|
202
|
+
*
|
|
203
|
+
* @example
|
|
204
|
+
* const { documents, nextCursor } = await admin.dataSources.documents({ slug: 'policies' });
|
|
205
|
+
* const failed = await admin.dataSources.documents({ slug: 'policies', status: 'error' });
|
|
206
|
+
*/
|
|
207
|
+
export declare function documents(ctx: AdminContext, params: DocumentsParams): Promise<DataSourcesDocumentsResult>;
|
|
208
|
+
/**
|
|
209
|
+
* Every document (or every one of `ids`), following pages to the end.
|
|
210
|
+
*
|
|
211
|
+
* With `ids`, requests are chunked to the server's per-request cap, so a wait
|
|
212
|
+
* over hundreds of just-added files stays a handful of small calls rather than
|
|
213
|
+
* a walk of the whole source.
|
|
214
|
+
*
|
|
215
|
+
* @example
|
|
216
|
+
* const docs = await admin.dataSources.allDocuments({ slug: 'policies' });
|
|
217
|
+
*/
|
|
218
|
+
export declare function allDocuments(ctx: AdminContext, params: Omit<DocumentsParams, 'cursor' | 'limit'>): Promise<DataSourcesDocumentStatus[]>;
|
|
219
|
+
/**
|
|
220
|
+
* List all data sources with document counts, the most documents each may
|
|
221
|
+
* hold (`documentLimit`, null when unlimited), build progress, and active
|
|
222
|
+
* version metadata.
|
|
223
|
+
*
|
|
224
|
+
* @example
|
|
225
|
+
* const { dataSources } = await admin.dataSources.list();
|
|
226
|
+
*/
|
|
227
|
+
export declare function list(ctx: AdminContext): Promise<DataSourcesListResult>;
|
|
228
|
+
export interface SearchParams {
|
|
229
|
+
/** Data source slug. */
|
|
230
|
+
slug: string;
|
|
231
|
+
/** Natural-language or keyword query. */
|
|
232
|
+
query: string;
|
|
233
|
+
/** Results to return (default 5, max 50). */
|
|
234
|
+
topK?: number;
|
|
235
|
+
/** 'hybrid' (default) | 'semantic' | 'lexical'. */
|
|
236
|
+
mode?: string;
|
|
237
|
+
/** Metadata equality filter or the full filter grammar as a plain object. */
|
|
238
|
+
filter?: Record<string, unknown>;
|
|
239
|
+
/** Cap hits per document; backfills from others. */
|
|
240
|
+
maxPerDocument?: number;
|
|
241
|
+
/** Return query-term offsets per hit. */
|
|
242
|
+
highlight?: boolean;
|
|
243
|
+
/** Search the candidate version instead of the live one. */
|
|
244
|
+
candidate?: boolean;
|
|
245
|
+
/** Assembled from triState(a, 'rerank'/'hybrid') in the skin. */
|
|
246
|
+
retrieval?: Record<string, boolean>;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Query a data source and return ranked passages with citations.
|
|
250
|
+
*
|
|
251
|
+
* `mode` in the response reports what actually ran (e.g. `reranked: false`
|
|
252
|
+
* after an adaptive skip) rather than what was requested, so measurements
|
|
253
|
+
* attribute numbers to the right path. Pass `candidate: true` to evaluate a
|
|
254
|
+
* candidate pipeline before promoting it.
|
|
255
|
+
*
|
|
256
|
+
* @throws AdminApiError `no_candidate_pipeline` (404) — `candidate: true` but
|
|
257
|
+
* no revectorization is in flight; `invalid_query` (400); `invalid_mode`
|
|
258
|
+
* (400).
|
|
259
|
+
* @example
|
|
260
|
+
* const { results } = await admin.dataSources.search({
|
|
261
|
+
* slug: 'policies',
|
|
262
|
+
* query: 'what are the payment terms?',
|
|
263
|
+
* });
|
|
264
|
+
*/
|
|
265
|
+
export declare function search(ctx: AdminContext, params: SearchParams): Promise<DataSourcesSearchResult>;
|
|
266
|
+
export interface CountParams {
|
|
267
|
+
/** Data source slug. */
|
|
268
|
+
slug: string;
|
|
269
|
+
/** Same grammar as search's filter; absent counts the whole corpus. */
|
|
270
|
+
filter?: Record<string, unknown>;
|
|
271
|
+
/** Count the candidate version instead of the live one. */
|
|
272
|
+
candidate?: boolean;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* How many chunks match a filter — exact, over the whole corpus.
|
|
276
|
+
*
|
|
277
|
+
* `count({ slug, filter: { contains: query } })` is how many passages contain
|
|
278
|
+
* all the query's words: the honest figure to show beside a search's hits.
|
|
279
|
+
* Not a relevance count (none exists) and not the set `search` returns.
|
|
280
|
+
*
|
|
281
|
+
* @throws AdminApiError `invalid_filter` (400); `no_candidate_pipeline` (404)
|
|
282
|
+
* with `candidate: true` and no revectorization in flight; `index_warming` /
|
|
283
|
+
* `index_building` (503) while the corpus is loading or building.
|
|
284
|
+
* @example
|
|
285
|
+
* const { chunks } = await admin.dataSources.count({ slug: 'policies', filter: { contains: 'notice period' } });
|
|
286
|
+
*/
|
|
287
|
+
export declare function count(ctx: AdminContext, params: CountParams): Promise<DataSourcesCountResult>;
|
|
288
|
+
export interface EntitiesParams {
|
|
289
|
+
/** Data source slug. */
|
|
290
|
+
slug: string;
|
|
291
|
+
/** Same grammar as search's filter; absent covers the whole corpus. */
|
|
292
|
+
filter?: Record<string, unknown>;
|
|
293
|
+
/** Entities to return, most first (default 20, at most 1,000). */
|
|
294
|
+
limit?: number;
|
|
295
|
+
/** Read the candidate version instead of the live one. */
|
|
296
|
+
candidate?: boolean;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* Which entities the passages matching a filter are about, most first.
|
|
300
|
+
*
|
|
301
|
+
* Filtered on one entity, it answers what appears beside it: a co-mention
|
|
302
|
+
* graph. `chunks` counts passages carrying each id, not documents, and is
|
|
303
|
+
* approximate.
|
|
304
|
+
*
|
|
305
|
+
* @throws AdminApiError `invalid_filter` (400); `no_candidate_pipeline` (404)
|
|
306
|
+
* with `candidate: true` and no revectorization in flight; `index_warming` /
|
|
307
|
+
* `index_building` (503) while the corpus is loading or building.
|
|
308
|
+
* @example
|
|
309
|
+
* const { entities } = await admin.dataSources.entities({ slug: 'manuals', filter: { entities: ['P-101A'] } });
|
|
310
|
+
*/
|
|
311
|
+
export declare function entities(ctx: AdminContext, params: EntitiesParams): Promise<DataSourcesEntitiesResult>;
|
|
312
|
+
export interface PassagesParams {
|
|
313
|
+
/** Data source slug. */
|
|
314
|
+
slug: string;
|
|
315
|
+
/** Same grammar as search's filter; absent lists the whole corpus. */
|
|
316
|
+
filter?: Record<string, unknown>;
|
|
317
|
+
/** The previous page's `nextCursor`. */
|
|
318
|
+
cursor?: string;
|
|
319
|
+
/** Passages per page (default 50, at most 200). */
|
|
320
|
+
limit?: number;
|
|
321
|
+
/** Read the candidate version instead of the live one. */
|
|
322
|
+
candidate?: boolean;
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* One page of every passage matching a filter, unranked: all the pages that
|
|
326
|
+
* mention an entity, rather than search's best few. Passages come document by
|
|
327
|
+
* document, each document's in order.
|
|
328
|
+
*
|
|
329
|
+
* @throws AdminApiError `invalid_filter` (400); `invalid_cursor` (400);
|
|
330
|
+
* `no_candidate_pipeline` (404); `index_warming` / `index_building` (503).
|
|
331
|
+
* @example
|
|
332
|
+
* const { passages, nextCursor } = await admin.dataSources.passages({ slug: 'manuals', filter: { entities: ['P-1004A'] } });
|
|
333
|
+
*/
|
|
334
|
+
export declare function passages(ctx: AdminContext, params: PassagesParams): Promise<DataSourcesPassagesResult>;
|
|
335
|
+
/**
|
|
336
|
+
* Read the full pipeline configuration for one data source.
|
|
337
|
+
*
|
|
338
|
+
* Returns `ingest` (pinned — requires a revectorize to change) and
|
|
339
|
+
* `retrieval` (live — takes effect on the next query, no rebuild needed).
|
|
340
|
+
*
|
|
341
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
342
|
+
* @example
|
|
343
|
+
* const { ingest, retrieval } = await admin.dataSources.configGet('policies');
|
|
344
|
+
*/
|
|
345
|
+
export declare function configGet(ctx: AdminContext, slug: string): Promise<DataSourcesConfigResult>;
|
|
346
|
+
export interface ConfigSetParams {
|
|
347
|
+
/** Data source slug. */
|
|
348
|
+
slug: string;
|
|
349
|
+
/**
|
|
350
|
+
* Ingest settings (pinned). Changes are rejected on a populated source —
|
|
351
|
+
* use `revectorize` instead to rebuild alongside the live one.
|
|
352
|
+
*/
|
|
353
|
+
ingest?: DataSourcesIngestUpdate;
|
|
354
|
+
/**
|
|
355
|
+
* Retrieval settings (live). Take effect on the next query; no rebuild
|
|
356
|
+
* required.
|
|
357
|
+
*/
|
|
358
|
+
retrieval?: DataSourcesRetrievalUpdate;
|
|
359
|
+
/**
|
|
360
|
+
* Where the corpus lives: a dedicated resource (see `admin.infra`) or the
|
|
361
|
+
* shared pool. An empty source moves on the spot; a populated one starts a
|
|
362
|
+
* background move (see `move`) and the response carries its `migration`.
|
|
363
|
+
*/
|
|
364
|
+
placement?: {
|
|
365
|
+
resourceId: string;
|
|
366
|
+
} | 'shared';
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* Update pipeline configuration.
|
|
370
|
+
*
|
|
371
|
+
* `retrieval` changes take effect on the next query at no cost. `ingest`
|
|
372
|
+
* changes are rejected once the source has documents — use `revectorize`
|
|
373
|
+
* instead, which builds a new version alongside the live one so search never
|
|
374
|
+
* degrades.
|
|
375
|
+
*
|
|
376
|
+
* @throws AdminApiError `data_source_not_found` (404),
|
|
377
|
+
* `data_source_migrating` (422) while a move is in flight.
|
|
378
|
+
* @example
|
|
379
|
+
* await admin.dataSources.configSet({
|
|
380
|
+
* slug: 'policies',
|
|
381
|
+
* retrieval: { rerank: { enabled: true } },
|
|
382
|
+
* });
|
|
383
|
+
*/
|
|
384
|
+
export declare function configSet(ctx: AdminContext, params: ConfigSetParams): Promise<DataSourcesConfigUpdateResult>;
|
|
385
|
+
export interface CreateParams {
|
|
386
|
+
/** Data source slug: lowercase [a-z0-9_-], up to 64 characters. */
|
|
387
|
+
slug: string;
|
|
388
|
+
/** Display name. */
|
|
389
|
+
name?: string;
|
|
390
|
+
/** Pinned ingest settings for the new pipeline; platform defaults otherwise. */
|
|
391
|
+
ingest?: DataSourcesIngestUpdate;
|
|
392
|
+
/**
|
|
393
|
+
* Where the corpus lives from the start: a dedicated resource (see
|
|
394
|
+
* `admin.infra`) or the shared pool (the default).
|
|
395
|
+
*/
|
|
396
|
+
placement?: {
|
|
397
|
+
resourceId: string;
|
|
398
|
+
} | 'shared';
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Create an empty data source, optionally on dedicated capacity.
|
|
402
|
+
*
|
|
403
|
+
* The one-step way to start a corpus on a resource. `add` also creates a
|
|
404
|
+
* source on first use, but on the shared pool. Calling this for a source that
|
|
405
|
+
* already exists returns it; a placement given then follows `configSet`'s
|
|
406
|
+
* rule — an empty source moves on the spot, a populated one starts a move.
|
|
407
|
+
*
|
|
408
|
+
* @throws AdminApiError `invalid_data_source` (400), `data_source_limit` (422),
|
|
409
|
+
* `resource_not_found` (404), `resource_destroyed` (422),
|
|
410
|
+
* `data_source_migrating` (422), `capacity_exceeded` (422).
|
|
411
|
+
* @example
|
|
412
|
+
* await admin.dataSources.create({ slug: 'archive', placement: { resourceId } });
|
|
413
|
+
*/
|
|
414
|
+
export declare function create(ctx: AdminContext, params: CreateParams): Promise<DataSourcesCreateResult>;
|
|
415
|
+
export interface MoveParams {
|
|
416
|
+
/** Data source slug. */
|
|
417
|
+
slug: string;
|
|
418
|
+
/** A dedicated resource (see `admin.infra`) or the shared pool. */
|
|
419
|
+
placement: {
|
|
420
|
+
resourceId: string;
|
|
421
|
+
} | 'shared';
|
|
422
|
+
/**
|
|
423
|
+
* Start the copy over instead of resuming a move already under way to the
|
|
424
|
+
* same target: fresh chains cut at the target's current count, progress so
|
|
425
|
+
* far discarded (points already copied are written again, harmlessly).
|
|
426
|
+
*/
|
|
427
|
+
restart?: boolean;
|
|
428
|
+
/**
|
|
429
|
+
* Parallel chains to copy with, instead of the target size's default (XL 32,
|
|
430
|
+
* Large 16, Medium 8, Small 4; max 128). The platform runs four chains per
|
|
431
|
+
* worker, so this is the worker count times four. Takes effect when the
|
|
432
|
+
* copy's windows are cut: with a move already under way, pair it with
|
|
433
|
+
* `restart`.
|
|
434
|
+
*/
|
|
435
|
+
chains?: number;
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Halt a move under way. Its chains stop at their next checkpoint and the
|
|
439
|
+
* record reads `error: "Stopped by operator."`; a plain `move` to the same
|
|
440
|
+
* target resumes from the chains' cursors.
|
|
441
|
+
*
|
|
442
|
+
* @throws AdminApiError `data_source_not_found` (404), `no_move_in_flight`
|
|
443
|
+
* (422) when nothing is being moved.
|
|
444
|
+
* @example
|
|
445
|
+
* await admin.dataSources.stopMove({ slug: 'archive' });
|
|
446
|
+
*/
|
|
447
|
+
export declare function stopMove(ctx: AdminContext, params: {
|
|
448
|
+
slug: string;
|
|
449
|
+
}): Promise<DataSourcesMoveResult>;
|
|
450
|
+
/**
|
|
451
|
+
* Move a data source between placements: shared → dedicated, dedicated →
|
|
452
|
+
* shared, or one resource to another.
|
|
453
|
+
*
|
|
454
|
+
* A populated source is copied onto the target in the background from its
|
|
455
|
+
* stored vectors — nothing is re-extracted or re-embedded — and flips when the
|
|
456
|
+
* copy lands. Search keeps serving from the old placement meanwhile. Adding,
|
|
457
|
+
* removing or reconfiguring documents is refused with `data_source_migrating`
|
|
458
|
+
* until it finishes; `waitForMove` blocks on that. Moving to `'shared'` is how
|
|
459
|
+
* a source leaves a resource that is about to be destroyed.
|
|
460
|
+
*
|
|
461
|
+
* @throws AdminApiError `data_source_not_found` (404), `same_placement` (400),
|
|
462
|
+
* `data_source_busy` (422) while documents are still building or a
|
|
463
|
+
* candidate version exists, `data_source_migrating` (422), `capacity_<phase>`
|
|
464
|
+
* (422) when the target resource is not active, `capacity_exceeded` (422)
|
|
465
|
+
* when the target is too small, `resource_not_found` (404).
|
|
466
|
+
* @example
|
|
467
|
+
* await admin.dataSources.move({ slug: 'archive', placement: { resourceId } });
|
|
468
|
+
* const result = await admin.dataSources.waitForMove({ slug: 'archive' });
|
|
469
|
+
*/
|
|
470
|
+
export declare function move(ctx: AdminContext, params: MoveParams): Promise<DataSourcesMoveResult>;
|
|
471
|
+
export interface WaitForMoveParams {
|
|
472
|
+
slug: string;
|
|
473
|
+
/** How long without movement before giving up. Defaults to DEFAULT_WAIT_TIMEOUT_MS (15 min). */
|
|
474
|
+
timeoutMs?: number;
|
|
475
|
+
/** Receives `copying… X/Y documents · N/min · about M min left (Ns)`. */
|
|
476
|
+
onProgress?: (message: string) => void;
|
|
477
|
+
}
|
|
478
|
+
export type WaitForMoveResult = {
|
|
479
|
+
status: 'done';
|
|
480
|
+
source: DataSourcesListEntry;
|
|
481
|
+
} | {
|
|
482
|
+
status: 'failed';
|
|
483
|
+
source: DataSourcesListEntry;
|
|
484
|
+
error: string;
|
|
485
|
+
} | {
|
|
486
|
+
status: 'timeout';
|
|
487
|
+
source: DataSourcesListEntry;
|
|
488
|
+
error: string;
|
|
489
|
+
};
|
|
490
|
+
/**
|
|
491
|
+
* Poll until a source's move has landed, failed, or the timeout elapses.
|
|
492
|
+
*
|
|
493
|
+
* Reads the source from `list` each poll; done when no move is in flight. A
|
|
494
|
+
* failed move returns immediately with the platform's error.
|
|
495
|
+
*
|
|
496
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
497
|
+
*/
|
|
498
|
+
export declare function waitForMove(ctx: AdminContext, params: WaitForMoveParams): Promise<WaitForMoveResult>;
|
|
499
|
+
export interface RevectorizeParams {
|
|
500
|
+
/** Data source slug. */
|
|
501
|
+
slug: string;
|
|
502
|
+
/** Ingest settings for the new version. Omit to adopt platform defaults. */
|
|
503
|
+
ingest?: DataSourcesIngestUpdate;
|
|
504
|
+
}
|
|
505
|
+
/**
|
|
506
|
+
* Start a new candidate pipeline alongside the live one.
|
|
507
|
+
*
|
|
508
|
+
* Builds a new version with the supplied settings, or platform defaults when
|
|
509
|
+
* none are given (the upgrade path for a source pinned to an older chunker).
|
|
510
|
+
* Search keeps serving the active version throughout. Reuses stored
|
|
511
|
+
* extractions, so changing chunking never re-runs document extraction — only
|
|
512
|
+
* re-chunking and re-embedding. Call `promote` to cut over.
|
|
513
|
+
*
|
|
514
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
515
|
+
* @example
|
|
516
|
+
* const { candidateVersion } = await admin.dataSources.revectorize({
|
|
517
|
+
* slug: 'policies',
|
|
518
|
+
* ingest: { chunking: { maxChars: 900 } },
|
|
519
|
+
* });
|
|
520
|
+
*/
|
|
521
|
+
export declare function revectorize(ctx: AdminContext, params: RevectorizeParams): Promise<DataSourcesRevectorizeResult>;
|
|
522
|
+
export interface PromoteParams {
|
|
523
|
+
/** Data source slug. */
|
|
524
|
+
slug: string;
|
|
525
|
+
/** Promote even if some candidate documents failed. */
|
|
526
|
+
force?: boolean;
|
|
527
|
+
}
|
|
528
|
+
/**
|
|
529
|
+
* Make the candidate pipeline version live.
|
|
530
|
+
*
|
|
531
|
+
* Atomically swaps the candidate for the active version and retires the old
|
|
532
|
+
* one. Without `force`, promotion is blocked when any candidate document
|
|
533
|
+
* failed. The retired version is kept; discard it with `drop` once rollback
|
|
534
|
+
* is no longer wanted.
|
|
535
|
+
*
|
|
536
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
537
|
+
* @example
|
|
538
|
+
* const { activeVersion } = await admin.dataSources.promote({ slug: 'policies' });
|
|
539
|
+
*/
|
|
540
|
+
export declare function promote(ctx: AdminContext, params: PromoteParams): Promise<DataSourcesPromoteResult>;
|
|
541
|
+
export interface DropParams {
|
|
542
|
+
/** Data source slug. */
|
|
543
|
+
slug: string;
|
|
544
|
+
/** Version number to drop. Omitted → the candidate is dropped. */
|
|
545
|
+
version?: number;
|
|
546
|
+
}
|
|
547
|
+
/**
|
|
548
|
+
* Discard a candidate or retired pipeline version.
|
|
549
|
+
*
|
|
550
|
+
* Never touches the active version. Omit `version` to drop the candidate;
|
|
551
|
+
* pass a specific number to drop a retired version once rollback is no longer
|
|
552
|
+
* wanted.
|
|
553
|
+
*
|
|
554
|
+
* @throws AdminApiError `data_source_not_found` (404); `pipeline_not_found`
|
|
555
|
+
* (404) — no candidate exists, or the version number is unknown.
|
|
556
|
+
* @example
|
|
557
|
+
* await admin.dataSources.drop({ slug: 'policies' }); // drops the candidate
|
|
558
|
+
*/
|
|
559
|
+
export declare function drop(ctx: AdminContext, params: DropParams): Promise<DataSourcesDropResult>;
|
|
560
|
+
export interface RmParams {
|
|
561
|
+
/** Data source slug. */
|
|
562
|
+
slug: string;
|
|
563
|
+
/** UUID of the document to remove. */
|
|
564
|
+
documentId: string;
|
|
565
|
+
}
|
|
566
|
+
/**
|
|
567
|
+
* Remove one document and its vectors from a data source.
|
|
568
|
+
*
|
|
569
|
+
* Deletes across every pipeline version, not just the active one — a document
|
|
570
|
+
* deleted mid-migration is gone from the candidate too.
|
|
571
|
+
*
|
|
572
|
+
* @throws AdminApiError `data_source_not_found` (404); `document_not_found`
|
|
573
|
+
* (404).
|
|
574
|
+
* @example
|
|
575
|
+
* await admin.dataSources.rm({ slug: 'policies', documentId });
|
|
576
|
+
*/
|
|
577
|
+
export declare function rm(ctx: AdminContext, params: RmParams): Promise<DataSourcesDocumentDeleteResult>;
|
|
578
|
+
export interface RmWhereParams {
|
|
579
|
+
/** Data source slug. */
|
|
580
|
+
slug: string;
|
|
581
|
+
filter: DataSourcesDocumentSelector;
|
|
582
|
+
}
|
|
583
|
+
/**
|
|
584
|
+
* Remove one page (up to 1,000) of the documents matching a selector, across
|
|
585
|
+
* every pipeline version, and report how many still match. Loop while
|
|
586
|
+
* `remaining > 0`; `rmWhereAll` does that.
|
|
587
|
+
*
|
|
588
|
+
* @throws AdminApiError `data_source_not_found` (404), `invalid_filter` (400),
|
|
589
|
+
* `data_source_busy` (422) while a job is in flight, `data_source_migrating`
|
|
590
|
+
* (422) during a move.
|
|
591
|
+
* @example
|
|
592
|
+
* await admin.dataSources.rmWhere({ slug: 'archive', filter: { metadata: { year: 2019 } } });
|
|
593
|
+
*/
|
|
594
|
+
export declare function rmWhere(ctx: AdminContext, params: RmWhereParams): Promise<DataSourcesDocumentDeleteManyResult>;
|
|
595
|
+
/** `rmWhere` until nothing matches. Reports each page through `onProgress`. */
|
|
596
|
+
export declare function rmWhereAll(ctx: AdminContext, params: RmWhereParams & {
|
|
597
|
+
onProgress?: (message: string) => void;
|
|
598
|
+
}): Promise<{
|
|
599
|
+
deleted: number;
|
|
600
|
+
}>;
|
|
601
|
+
/**
|
|
602
|
+
* Delete a whole data source — every version, every document, and every byte.
|
|
603
|
+
*
|
|
604
|
+
* Extraction caches survive (shared across sources by content hash), so
|
|
605
|
+
* re-ingesting the same files into a new source costs no re-extraction.
|
|
606
|
+
* Manage-plane only: running app code has no equivalent.
|
|
607
|
+
*
|
|
608
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
609
|
+
* @example
|
|
610
|
+
* const { documents, versions } = await admin.dataSources.deleteSource('policies');
|
|
611
|
+
*/
|
|
612
|
+
export declare function deleteSource(ctx: AdminContext, slug: string): Promise<DataSourcesDeleteResult>;
|
|
613
|
+
/** One dictionary entry: the app's id for a thing and the names it goes by. */
|
|
614
|
+
export interface DictionaryEntryInput {
|
|
615
|
+
id: string;
|
|
616
|
+
names: string[];
|
|
617
|
+
}
|
|
618
|
+
/**
|
|
619
|
+
* Push a source's dictionary, replacing the one it had: a stage, its pages
|
|
620
|
+
* (each retried alone), and the commit. A new version re-tags the source's
|
|
621
|
+
* passages in the background; an unchanged one commits nothing.
|
|
622
|
+
*
|
|
623
|
+
* @throws AdminApiError `invalid_dictionary` / `dictionary_name_too_short` (400)
|
|
624
|
+
* on a page, naming the entry; `dictionary_too_large` (400) at the commit.
|
|
625
|
+
* @example
|
|
626
|
+
* await admin.dataSources.pushDictionary({ slug: 'manuals', entries: [{ id: 'P-101A', names: ['P-101A', 'Main Feed Pump'] }] });
|
|
627
|
+
*/
|
|
628
|
+
export declare function pushDictionary(ctx: AdminContext, params: {
|
|
629
|
+
slug: string;
|
|
630
|
+
entries: DictionaryEntryInput[];
|
|
631
|
+
linkerVersion?: number;
|
|
632
|
+
onProgress?: (sent: number, total: number) => void;
|
|
633
|
+
}): Promise<DataSourcesDictionaryPushResult>;
|
|
634
|
+
/**
|
|
635
|
+
* A source's current dictionary, and the relinks re-tagging its versions
|
|
636
|
+
* while they run.
|
|
637
|
+
*
|
|
638
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
639
|
+
*/
|
|
640
|
+
export declare function dictionary(ctx: AdminContext, params: {
|
|
641
|
+
slug: string;
|
|
642
|
+
}): Promise<DataSourcesDictionaryStatus>;
|
|
643
|
+
/**
|
|
644
|
+
* What the source's current dictionary finds in a piece of text: each
|
|
645
|
+
* mention, in order, with the ids it tags.
|
|
646
|
+
*
|
|
647
|
+
* @throws AdminApiError `data_source_not_found` (404).
|
|
648
|
+
* @example
|
|
649
|
+
* const { mentions } = await admin.dataSources.link({ slug: 'manuals', text: 'Replaced the seal on P101A.' });
|
|
650
|
+
*/
|
|
651
|
+
export declare function link(ctx: AdminContext, params: {
|
|
652
|
+
slug: string;
|
|
653
|
+
text: string;
|
|
654
|
+
}): Promise<DataSourcesLinkResult>;
|