graphor 0.12.2 → 0.14.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 (96) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +320 -31
  3. package/client.d.mts +3 -6
  4. package/client.d.mts.map +1 -1
  5. package/client.d.ts +3 -6
  6. package/client.d.ts.map +1 -1
  7. package/client.js +15 -20
  8. package/client.js.map +1 -1
  9. package/client.mjs +15 -20
  10. package/client.mjs.map +1 -1
  11. package/internal/qs/formats.d.mts +7 -0
  12. package/internal/qs/formats.d.mts.map +1 -0
  13. package/internal/qs/formats.d.ts +7 -0
  14. package/internal/qs/formats.d.ts.map +1 -0
  15. package/internal/qs/formats.js +13 -0
  16. package/internal/qs/formats.js.map +1 -0
  17. package/internal/qs/formats.mjs +9 -0
  18. package/internal/qs/formats.mjs.map +1 -0
  19. package/internal/qs/index.d.mts +10 -0
  20. package/internal/qs/index.d.mts.map +1 -0
  21. package/internal/qs/index.d.ts +10 -0
  22. package/internal/qs/index.d.ts.map +1 -0
  23. package/internal/qs/index.js +14 -0
  24. package/internal/qs/index.js.map +1 -0
  25. package/internal/qs/index.mjs +10 -0
  26. package/internal/qs/index.mjs.map +1 -0
  27. package/internal/qs/stringify.d.mts +3 -0
  28. package/internal/qs/stringify.d.mts.map +1 -0
  29. package/internal/qs/stringify.d.ts +3 -0
  30. package/internal/qs/stringify.d.ts.map +1 -0
  31. package/internal/qs/stringify.js +277 -0
  32. package/internal/qs/stringify.js.map +1 -0
  33. package/internal/qs/stringify.mjs +274 -0
  34. package/internal/qs/stringify.mjs.map +1 -0
  35. package/internal/qs/types.d.mts +57 -0
  36. package/internal/qs/types.d.mts.map +1 -0
  37. package/internal/qs/types.d.ts +57 -0
  38. package/internal/qs/types.d.ts.map +1 -0
  39. package/internal/qs/types.js +3 -0
  40. package/internal/qs/types.js.map +1 -0
  41. package/internal/qs/types.mjs +2 -0
  42. package/internal/qs/types.mjs.map +1 -0
  43. package/internal/qs/utils.d.mts +15 -0
  44. package/internal/qs/utils.d.mts.map +1 -0
  45. package/internal/qs/utils.d.ts +15 -0
  46. package/internal/qs/utils.d.ts.map +1 -0
  47. package/internal/qs/utils.js +230 -0
  48. package/internal/qs/utils.js.map +1 -0
  49. package/internal/qs/utils.mjs +217 -0
  50. package/internal/qs/utils.mjs.map +1 -0
  51. package/internal/tslib.js +17 -17
  52. package/internal/utils/query.d.mts +2 -0
  53. package/internal/utils/query.d.mts.map +1 -0
  54. package/internal/utils/query.d.ts +2 -0
  55. package/internal/utils/query.d.ts.map +1 -0
  56. package/internal/utils/query.js +10 -0
  57. package/internal/utils/query.js.map +1 -0
  58. package/internal/utils/query.mjs +6 -0
  59. package/internal/utils/query.mjs.map +1 -0
  60. package/internal/utils.d.mts +1 -0
  61. package/internal/utils.d.ts +1 -0
  62. package/internal/utils.js +1 -0
  63. package/internal/utils.js.map +1 -1
  64. package/internal/utils.mjs +1 -0
  65. package/package.json +1 -1
  66. package/resources/index.d.mts +1 -1
  67. package/resources/index.d.mts.map +1 -1
  68. package/resources/index.d.ts +1 -1
  69. package/resources/index.d.ts.map +1 -1
  70. package/resources/index.js.map +1 -1
  71. package/resources/index.mjs.map +1 -1
  72. package/resources/sources.d.mts +496 -332
  73. package/resources/sources.d.mts.map +1 -1
  74. package/resources/sources.d.ts +496 -332
  75. package/resources/sources.d.ts.map +1 -1
  76. package/resources/sources.js +200 -236
  77. package/resources/sources.js.map +1 -1
  78. package/resources/sources.mjs +200 -236
  79. package/resources/sources.mjs.map +1 -1
  80. package/src/client.ts +52 -40
  81. package/src/internal/qs/LICENSE.md +13 -0
  82. package/src/internal/qs/README.md +3 -0
  83. package/src/internal/qs/formats.ts +10 -0
  84. package/src/internal/qs/index.ts +13 -0
  85. package/src/internal/qs/stringify.ts +385 -0
  86. package/src/internal/qs/types.ts +71 -0
  87. package/src/internal/qs/utils.ts +265 -0
  88. package/src/internal/utils/query.ts +7 -0
  89. package/src/internal/utils.ts +1 -0
  90. package/src/resources/index.ts +17 -8
  91. package/src/resources/sources.ts +617 -367
  92. package/src/version.ts +1 -1
  93. package/version.d.mts +1 -1
  94. package/version.d.ts +1 -1
  95. package/version.js +1 -1
  96. package/version.mjs +1 -1
@@ -1,6 +1,7 @@
1
1
  // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
2
  import { APIResource } from "../core/resource.mjs";
3
3
  import { multipartFormRequestOptions } from "../internal/uploads.mjs";
4
+ import { path } from "../internal/utils/path.mjs";
4
5
  export class Sources extends APIResource {
5
6
  /**
6
7
  * List all sources in the project's knowledge graph.
@@ -10,12 +11,17 @@ export class Sources extends APIResource {
10
11
  * type, origin) along with its current processing status and a human-readable
11
12
  * status message.
12
13
  *
14
+ * **Query parameters:**
15
+ *
16
+ * - **file_ids** (list, optional): If provided, only sources whose file_id is in
17
+ * this list are returned. Repeat the param for multiple IDs (e.g.
18
+ * ?file_ids=id1&file_ids=id2).
19
+ *
13
20
  * **Status messages returned per source:**
14
21
  *
15
22
  * - `"completed"` → _"Source processed successfully"_
16
23
  * - `"processing"` → _"Source is being processed"_
17
24
  * - `"failed"` → _"Source processing failed"_
18
- * - `"new"` → _"Source uploaded, awaiting processing"_
19
25
  *
20
26
  * **Returns** a JSON array of `PublicSourceResponse` objects.
21
27
  *
@@ -28,8 +34,8 @@ export class Sources extends APIResource {
28
34
  * const publicSources = await client.sources.list();
29
35
  * ```
30
36
  */
31
- list(options) {
32
- return this._client.get('/sources', options);
37
+ list(query = {}, options) {
38
+ return this._client.get('/sources', { query, ...options });
33
39
  }
34
40
  /**
35
41
  * Delete a source from the project's knowledge graph and all associated data.
@@ -161,332 +167,290 @@ export class Sources extends APIResource {
161
167
  return this._client.post('/sources/run-extraction', { body, ...options });
162
168
  }
163
169
  /**
164
- * Retrieve the parsed elements (chunks/partitions) of a specific source with
165
- * pagination.
166
- *
167
- * Returns the individual document partitions (text chunks) that were generated
168
- * during ingestion for a given source. This is useful for inspecting how a file
169
- * was segmented, reviewing chunk content, or building custom retrieval logic on
170
- * top of the raw partitions.
171
- *
172
- * **Parameters (JSON body):**
173
- *
174
- * - **file_id** (str, optional — preferred): The unique identifier of the source
175
- * whose elements to retrieve.
176
- * - **file_name** (str, optional — deprecated): The display name of the source.
177
- * Use `file_id` when possible. At least one of `file_id` or `file_name` must be
178
- * provided.
179
- * - **page** (int, optional): The 1-based page number for pagination.
180
- * - **page_size** (int, optional): The number of elements per page. Both `page`
181
- * and `page_size` must be provided together to enable pagination.
182
- * - **filter** (object, optional): An optional filter object with:
183
- * - `type` filter by element type.
184
- * - `page_numbers` restrict to specific source page numbers.
185
- * - `elementsToRemove` list of element types to exclude.
186
- *
187
- * **Returns** a `PaginatedResponse[Document]` containing:
188
- *
189
- * - `items` list of `Document` objects (LangChain format) with `page_content`
190
- * and `metadata`.
191
- * - `total` — total number of matching elements.
192
- * - `page`, `page_size`, `total_pages` pagination metadata.
170
+ * Return the status and optional parsed elements for an async build identified by
171
+ * `build_id`.
172
+ *
173
+ * Use this endpoint to poll the result of an async ingestion or re-process
174
+ * request. The `build_id` is returned in the response of:
175
+ *
176
+ * - `POST /v2/sources/upload` (async file upload)
177
+ * - `POST /v2/sources/upload-url-source` (async URL ingestion)
178
+ * - `POST /v2/sources/upload-github-source` (async GitHub ingestion)
179
+ * - `POST /v2/sources/upload-youtube-source` (async YouTube ingestion)
180
+ * - `POST /v2/sources/process` (async re-process)
181
+ *
182
+ * **Path parameter:**
183
+ *
184
+ * - **build_id** (str, required): The build identifier returned when the job was
185
+ * scheduled.
186
+ *
187
+ * **Query parameters:**
188
+ *
189
+ * - **suppress_elements** (bool, default `false`): When `true`, elements are
190
+ * omitted from the response. When `false` (default), the response includes the
191
+ * parsed elements (chunks/partitions) for the build if it completed
192
+ * successfully. Same structure as `POST /sources/elements` (each element has
193
+ * `page_content` and `metadata`). If `page` and `page_size` are not passed, all
194
+ * elements are returned.
195
+ * - **suppress_img_base64** (bool, default `false`): When `true`, `img_base64` is
196
+ * omitted from each element (useful to reduce payload size when images are not
197
+ * needed).
198
+ * - **page** (int, optional): 1-based page number. Only used when
199
+ * `suppress_elements=false` and pagination is used (pass either `page` or
200
+ * `page_size` to enable pagination).
201
+ * - **page_size** (int, optional): Number of elements per page (max 100). Only
202
+ * used when `suppress_elements=false` and pagination is used.
203
+ *
204
+ * **Response fields:**
205
+ *
206
+ * - **build_id**: The requested build identifier.
207
+ * - **status**: SourceNodeStatus value when history exists (e.g. Processed,
208
+ * Processing, Processing failed). `not_found` when no history exists (build in
209
+ * progress or invalid id).
210
+ * - **success**: `true` only when `status == "Completed"`
211
+ * (SourceNodeStatus.COMPLETED).
212
+ * - **file_id**, **file_name**: Source identifiers; present when the build has
213
+ * been persisted (history exists).
214
+ * - **error**: Error message from the pipeline when the build failed.
215
+ * - **method**, **total_partitions**, **total_pages**: Build metadata when history
216
+ * exists.
217
+ * - **created_at**, **updated_at**: ISO8601 timestamps when history exists.
218
+ * - **message**: Human-readable message (e.g. when status is `not_found`).
219
+ * - **elements**: List of `{ page_content, metadata }` when
220
+ * `suppress_elements=false` and the build completed successfully.
221
+ * - **total_elements**, **page**, **page_size**, **total_pages_elements**:
222
+ * Pagination metadata for `elements` when `suppress_elements=false`.
193
223
  *
194
224
  * **Error responses:**
195
225
  *
196
- * - `400` — Invalid input (e.g. neither identifier provided).
197
- * - `404` — Source file not found.
198
226
  * - `500` — Unexpected internal error.
199
227
  *
200
228
  * @example
201
229
  * ```ts
202
- * const response = await client.sources.loadElements();
230
+ * const response = await client.sources.getBuildStatus(
231
+ * 'build_id',
232
+ * );
203
233
  * ```
204
234
  */
205
- loadElements(body, options) {
206
- return this._client.post('/sources/elements', { body, ...options });
235
+ getBuildStatus(buildID, query = {}, options) {
236
+ return this._client.get(path `/sources/builds/${buildID}`, { query, ...options });
207
237
  }
208
238
  /**
209
- * Re-process (re-parse) an existing source that has already been uploaded.
210
- *
211
- * Use this endpoint to re-run the data-ingestion pipeline on a source that is
212
- * already present in the knowledge graph for example, after changing the
213
- * partitioning strategy. The endpoint locates the source node, sets its status to
214
- * `PROCESSING`, applies the requested partition method, and executes the full
215
- * ingestion pipeline synchronously (partitioning, chunking, embedding, and graph
216
- * persistence).
217
- *
218
- * **Parameters (JSON body):**
219
- *
220
- * - **file_id** (str, optional — preferred): The unique identifier of the source
221
- * to re-process.
222
- * - **file_name** (str, optional — deprecated): The display name of the source.
223
- * Use `file_id` instead when possible. At least one of `file_id` or `file_name`
224
- * must be provided.
225
- * - **partition_method** (str, default `"basic"`): The partitioning strategy to
226
- * apply. One of: `basic` (Fast), `hi_res` (Balanced), `hi_res_ft` (Accurate),
227
- * `mai` (VLM), `graphorlm` (Agentic).
228
- *
229
- * **Returns** a `PublicSourceResponse` with the updated source metadata.
230
- *
231
- * **Error responses:**
232
- *
233
- * - `404` — Source node not found for the given identifier.
234
- * - `500` — Processing or unexpected internal error.
239
+ * Retrieve the parsed elements (chunks/partitions) of a source in the same format
240
+ * as get_build_status.
241
+ *
242
+ * Returns elements with explicit fields: element_id, element_type, text, markdown,
243
+ * html, img_base64 (optional), position, page_number, bounding_box, page_layout,
244
+ * etc.
245
+ *
246
+ * **Query parameters:**
247
+ *
248
+ * - **file_id** (str, required): Unique identifier of the source.
249
+ * - **page** (int, optional): 1-based page number. Use with page_size to enable
250
+ * pagination.
251
+ * - **page_size** (int, optional): Number of elements per page (max 100).
252
+ * - **suppress_img_base64** (bool, default false): When true, img_base64 is
253
+ * omitted from each element.
254
+ * - **type** (str, optional): Filter by element type (e.g. NarrativeText, Title,
255
+ * Table).
256
+ * - **page_numbers** (list, optional): Restrict to specific page numbers (repeat
257
+ * param for multiple).
258
+ * - **elementsToRemove** (list, optional): Element types to exclude (repeat param
259
+ * for multiple).
260
+ *
261
+ * **Returns** Paginated response with items as BuildStatusElement list (same shape
262
+ * as GET /builds/{build_id} elements).
235
263
  *
236
264
  * @example
237
265
  * ```ts
238
- * const publicSource = await client.sources.parse();
266
+ * const response = await client.sources.getElements({
267
+ * file_id: 'file_id',
268
+ * });
239
269
  * ```
240
270
  */
241
- parse(body, options) {
242
- return this._client.post('/sources/process', { body, ...options });
271
+ getElements(query, options) {
272
+ return this._client.get('/sources/get-elements', { query, ...options });
243
273
  }
244
274
  /**
245
- * Retrieve relevant document chunks from the prebuilt RAG vector store.
275
+ * Upload a local file and schedule ingestion in the background.
246
276
  *
247
- * Performs a semantic similarity search over the project's prebuilt RAG store
248
- * using Google File Search with grounding. Returns the most relevant text chunks
249
- * along with their source metadata (file name, page number, relevance score). This
250
- * is a pure retrieval endpoint — it does **not** generate an answer; use
251
- * `/ask-sources` for Q&A.
252
- *
253
- * **Parameters (JSON body):**
277
+ * Accepts **`multipart/form-data`** with the file. Validates size (max 100 MB) and
278
+ * extension, stores the file, then schedules the full data-ingestion pipeline in
279
+ * the background. Returns immediately with a `build_id` to poll for status.
254
280
  *
255
- * - **query** (str, required): The natural-language search query used to find
256
- * relevant chunks.
257
- * - **file_ids** (list[str], optional — preferred): Restrict retrieval to specific
258
- * source file IDs.
259
- * - **file_names** (list[str], optional — deprecated): Restrict retrieval to
260
- * specific source file names. Use `file_ids` when possible.
261
- *
262
- * **Returns** a `PublicRetrieveResponse` containing:
263
- *
264
- * - `query` — the original search query.
265
- * - `chunks` — a list of `PublicRetrieveChunk` objects, each with `text`,
266
- * `file_name`, `page_number`, `score`, and additional `metadata`.
267
- * - `total` — the total number of chunks returned.
281
+ * **Parameters:**
268
282
  *
269
- * **Error responses:**
283
+ * - **file** (`multipart/form-data`): The file to upload. Must include
284
+ * `Content-Length` and have a supported extension (pdf, doc, docx, csv, txt, md,
285
+ * etc.).
286
+ * - **method** (`form`, optional): Partitioning strategy. One of: `fast`,
287
+ * `balanced`, `accurate`, `vlm`, `agentic`. Default when omitted.
270
288
  *
271
- * - `500` Unexpected internal error during retrieval.
289
+ * **Returns** `AsyncIngestResponse` with `build_id`. Use it to check processing
290
+ * status.
272
291
  *
273
292
  * @example
274
293
  * ```ts
275
- * const response = await client.sources.retrieveChunks({
276
- * query: 'query',
294
+ * const response = await client.sources.ingestFile({
295
+ * file: fs.createReadStream('path/to/file'),
277
296
  * });
278
297
  * ```
279
298
  */
280
- retrieveChunks(body, options) {
281
- return this._client.post('/sources/prebuilt-rag', { body, ...options });
299
+ ingestFile(body, options) {
300
+ return this._client.post('/sources/ingest-file', multipartFormRequestOptions({ body, ...options }, this._client));
282
301
  }
283
302
  /**
284
- * Upload a local file and ingest it as a source into the project's knowledge
285
- * graph.
286
- *
287
- * This endpoint accepts a **`multipart/form-data`** request containing the file to
288
- * upload. It validates the file size (max 100 MB) and extension against the list
289
- * of allowed types, stores the file, and then runs the full data-ingestion
290
- * pipeline synchronously — including partitioning, chunking, embedding, and graph
291
- * persistence.
292
- *
293
- * **Usage via SDK (AI agent / MCP context):**
294
- *
295
- * The SDK executes code in a **remote sandboxed container** that does **not** have
296
- * access to the local filesystem. Because of this, `fs.createReadStream()` with a
297
- * local file path will **not work** — the file does not exist inside the
298
- * container.
299
- *
300
- * For **text-based files** (md, txt, csv, html, etc.), you can read the file
301
- * content with a local tool (e.g. IDE file-read) and create a `File` object in
302
- * memory:
303
- *
304
- * ```
305
- * const content = `...file contents read locally...`;
306
- * const file = new File([content], "my-document.md", { type: "text/markdown" });
307
- * const result = await client.sources.upload({ file });
308
- * ```
309
- *
310
- * For **binary files** (pdf, docx, images, video, audio, etc.), the in-memory
311
- * approach is impractical. Instead, use **`curl`** or **`subprocess`** to call the
312
- * upload endpoint directly from the local machine, where the file is accessible:
313
- *
314
- * ```
315
- * import { execSync } from "child_process";
316
- *
317
- * const result = execSync(`
318
- * curl -s -X POST "{base_url}/source/upload" \
319
- * -H "Authorization: Bearer {access_key}" \
320
- * -F "file=@/local/path/to/document.pdf" \
321
- * -F "partition_method=graphorlm"
322
- * `).toString();
323
- * ```
303
+ * Ingest a GitHub repository as a source into the project's knowledge graph.
324
304
  *
325
- * Or with Python `subprocess`:
305
+ * Schedules the ingestion in the background and returns immediately with a
306
+ * `build_id`. Use the returned `build_id` to poll for processing status.
326
307
  *
327
- * ```
328
- * import subprocess, json
329
- *
330
- * result = subprocess.run([
331
- * "curl", "-s", "-X", "POST", "{base_url}/source/upload",
332
- * "-H", "Authorization: Bearer {access_key}",
333
- * "-F", "file=@/local/path/to/document.pdf",
334
- * "-F", "partition_method=graphorlm",
335
- * ], capture_output=True, text=True)
336
- * response = json.loads(result.stdout)
337
- * ```
308
+ * **Parameters (JSON body):**
338
309
  *
339
- * **Important:** Do NOT use `fs.createReadStream("/local/path")` inside the SDK
340
- * code — it will fail because the execution environment cannot access local paths.
341
- * Always prefer `curl`/`requests` executed locally for binary uploads.
310
+ * - **url** (str, required): The GitHub repository URL to ingest (e.g.
311
+ * `https://github.com/owner/repo`).
342
312
  *
343
- * **Usage via curl:**
313
+ * **Returns** `AsyncIngestResponse` with `build_id`.
344
314
  *
315
+ * @example
316
+ * ```ts
317
+ * const response = await client.sources.ingestGitHub({
318
+ * url: 'url',
319
+ * });
345
320
  * ```
346
- * curl -X POST "{base_url}/source/upload" \
347
- * -H "Authorization: Bearer {access_key}" \
348
- * -F "file=@/path/to/document.pdf" \
349
- * -F "partition_method=graphorlm"
350
- * ```
321
+ */
322
+ ingestGitHub(body, options) {
323
+ return this._client.post('/sources/ingest-github', { body, ...options });
324
+ }
325
+ /**
326
+ * Ingest a web page (or a set of crawled pages) as a source into the project's
327
+ * knowledge graph.
351
328
  *
352
- * **Usage via Python `requests`:**
329
+ * Unlike the synchronous version, this endpoint schedules the ingestion in the
330
+ * background and returns immediately with a `processing` status. The source will
331
+ * be fully available once background processing completes.
353
332
  *
354
- * ```
355
- * import requests
356
- *
357
- * with open("document.pdf", "rb") as f:
358
- * response = requests.post(
359
- * "{base_url}/source/upload",
360
- * headers={"Authorization": "Bearer {access_key}"},
361
- * files={"file": ("document.pdf", f, "application/pdf")},
362
- * data={"partition_method": "graphorlm"}, # optional
363
- * )
364
- * ```
333
+ * If the URL points directly to a downloadable file (detected via URL path
334
+ * extension or HTTP Content-Type), the file is first downloaded and uploaded to
335
+ * storage synchronously, then the partition/embedding pipeline runs in the
336
+ * background.
365
337
  *
366
- * **Parameters:**
338
+ * **Parameters (JSON body):**
367
339
  *
368
- * - **file** (`multipart/form-data`): The file to upload. Must include a
369
- * `Content-Length` header and have one of the supported extensions: pdf, doc,
370
- * docx, odt, ppt, pptx, csv, tsv, xls, xlsx, txt, text, md, html, htm, png, jpg,
371
- * jpeg, tiff, bmp, heic, mp4, mov, avi, mkv, webm, mp3, wav, m4a, ogg, flac.
372
- * - **partition_method** (`form`, optional): The partitioning strategy to apply.
373
- * One of: `basic` (Fast), `hi_res` (Balanced), `hi_res_ft` (Accurate), `mai`
374
- * (VLM), `graphorlm` (Agentic). When omitted, the system default is used.
340
+ * - **url** (str, required): The web page URL to ingest.
341
+ * - **crawlUrls** (bool, optional, default `false`): When `true`, the system will
342
+ * also follow and ingest links found on the page. Ignored when the URL resolves
343
+ * to a file.
344
+ * - **method** (str, optional): The partitioning strategy to use. One of: `fast`,
345
+ * `balanced`, `accurate`, `vlm`, `agentic`. When omitted the system default is
346
+ * applied.
375
347
  *
376
- * **Returns** a `PublicSourceResponse` with the resulting source metadata (file
377
- * ID, name, size, type, source origin, partition method, and processing status).
348
+ * **Returns** a `PublicSourceResponse` with `status: "processing"` immediately.
349
+ * Poll the source status endpoint using the returned `file_id` to track
350
+ * completion.
378
351
  *
379
352
  * **Error responses:**
380
353
  *
381
- * - `400` — Unsupported file type or missing file name.
382
- * - `411` — Missing `Content-Length` header (file size cannot be determined).
383
- * - `413` — File exceeds the 100 MB size limit.
384
- * - `403` — Permission denied.
385
- * - `404` — File not found during processing.
386
- * - `500` — Unexpected internal error.
354
+ * - `400` — Unsupported file type detected from a file URL.
355
+ * - `500` — Unexpected internal error during URL processing.
387
356
  *
388
357
  * @example
389
358
  * ```ts
390
- * const publicSource = await client.sources.upload({
391
- * file: fs.createReadStream('path/to/file'),
359
+ * const response = await client.sources.ingestURL({
360
+ * url: 'url',
392
361
  * });
393
362
  * ```
394
363
  */
395
- upload(body, options) {
396
- return this._client.post('/sources/upload', multipartFormRequestOptions({ body, ...options }, this._client));
364
+ ingestURL(body, options) {
365
+ return this._client.post('/sources/ingest-url', { body, ...options });
397
366
  }
398
367
  /**
399
- * Ingest a GitHub repository as a source into the project's knowledge graph.
368
+ * Ingest a YouTube video as a source into the project's knowledge graph.
400
369
  *
401
- * The endpoint clones or fetches the repository at the given URL, extracts its
402
- * text-based files, partitions them using the system default method, generates
403
- * embeddings, and persists everything in the knowledge graph synchronously.
370
+ * Schedules the ingestion in the background and returns immediately with a
371
+ * `build_id`. The endpoint will download the transcript/captions and process them
372
+ * in the background. Use the returned `build_id` to poll for processing status.
404
373
  *
405
374
  * **Parameters (JSON body):**
406
375
  *
407
- * - **url** (str, required): The GitHub repository URL to ingest (e.g.
408
- * `https://github.com/owner/repo`).
409
- *
410
- * **Returns** a `PublicSourceResponse` with the resulting source metadata (file
411
- * ID, name, size, type, source origin, partition method, and processing status).
412
- *
413
- * **Error responses:**
376
+ * - **url** (str, required): The YouTube video URL to ingest (e.g.
377
+ * `https://www.youtube.com/watch?v=...`).
414
378
  *
415
- * - `500` Unexpected internal error during GitHub source processing.
379
+ * **Returns** `AsyncIngestResponse` with `build_id`.
416
380
  *
417
381
  * @example
418
382
  * ```ts
419
- * const publicSource = await client.sources.uploadGitHub({
383
+ * const response = await client.sources.ingestYoutube({
420
384
  * url: 'url',
421
385
  * });
422
386
  * ```
423
387
  */
424
- uploadGitHub(body, options) {
425
- return this._client.post('/sources/upload-github-source', { body, ...options });
388
+ ingestYoutube(body, options) {
389
+ return this._client.post('/sources/ingest-youtube', { body, ...options });
426
390
  }
427
391
  /**
428
- * Ingest a web page (or a set of crawled pages) as a source into the project's
429
- * knowledge graph.
392
+ * Re-process (re-parse) an existing source in the background.
430
393
  *
431
- * The endpoint fetches the content at the given URL, optionally crawls linked
432
- * pages (when `crawlUrls` is `true`), partitions the resulting HTML/text,
433
- * generates embeddings, and persists everything in the knowledge graph
434
- * synchronously.
394
+ * Schedules the data-ingestion pipeline (partitioning, chunking, embedding) for an
395
+ * existing source and returns immediately with a `build_id`. Use it to poll for
396
+ * status.
435
397
  *
436
398
  * **Parameters (JSON body):**
437
399
  *
438
- * - **url** (str, required): The web page URL to ingest.
439
- * - **crawlUrls** (bool, optional, default `false`): When `true`, the system will
440
- * also follow and ingest links found on the page.
441
- * - **partition_method** (str, optional): The partitioning strategy to use. One
442
- * of: `basic` (Fast), `hi_res` (Balanced), `hi_res_ft` (Accurate), `mai` (VLM),
443
- * `graphorlm` (Agentic). When omitted the system default is applied.
444
- *
445
- * **Returns** a `PublicSourceResponse` with the resulting source metadata (file
446
- * ID, name, size, type, source origin, partition method, and processing status).
400
+ * - **file_id** (str, required): Unique identifier of the source to re-process.
401
+ * - **method** (str, default `"fast"`): Partitioning strategy. One of: `fast`,
402
+ * `balanced`, `accurate`, `vlm`, `agentic`.
447
403
  *
448
- * **Error responses:**
449
- *
450
- * - `500` — Unexpected internal error during URL processing.
404
+ * **Returns** `AsyncIngestResponse` with `build_id`.
451
405
  *
452
406
  * @example
453
407
  * ```ts
454
- * const publicSource = await client.sources.uploadURL({
455
- * url: 'url',
408
+ * const response = await client.sources.reprocess({
409
+ * file_id: 'file_id',
456
410
  * });
457
411
  * ```
458
412
  */
459
- uploadURL(body, options) {
460
- return this._client.post('/sources/upload-url-source', { body, ...options });
413
+ reprocess(body, options) {
414
+ return this._client.post('/sources/reprocess', { body, ...options });
461
415
  }
462
416
  /**
463
- * Ingest a YouTube video as a source into the project's knowledge graph.
417
+ * Retrieve relevant document chunks from the prebuilt RAG vector store.
464
418
  *
465
- * The endpoint downloads the transcript/captions of the given YouTube video,
466
- * partitions the text using the system default method, generates embeddings, and
467
- * persists everything in the knowledge graph synchronously.
419
+ * Performs a semantic similarity search over the project's prebuilt RAG store
420
+ * using Google File Search with grounding. Returns the most relevant text chunks
421
+ * along with their source metadata (file name, page number, relevance score). This
422
+ * is a pure retrieval endpoint — it does **not** generate an answer; use
423
+ * `/ask-sources` for Q&A.
468
424
  *
469
425
  * **Parameters (JSON body):**
470
426
  *
471
- * - **url** (str, required): The YouTube video URL to ingest (e.g.
472
- * `https://www.youtube.com/watch?v=...`).
427
+ * - **query** (str, required): The natural-language search query used to find
428
+ * relevant chunks.
429
+ * - **file_ids** (list[str], optional — preferred): Restrict retrieval to specific
430
+ * source file IDs.
431
+ * - **file_names** (list[str], optional — deprecated): Restrict retrieval to
432
+ * specific source file names. Use `file_ids` when possible.
473
433
  *
474
- * **Returns** a `PublicSourceResponse` with the resulting source metadata (file
475
- * ID, name, size, type, source origin, partition method, and processing status).
434
+ * **Returns** a `PublicRetrieveResponse` containing:
435
+ *
436
+ * - `query` — the original search query.
437
+ * - `chunks` — a list of `PublicRetrieveChunk` objects, each with `text`,
438
+ * `file_name`, `page_number`, `score`, and additional `metadata`.
439
+ * - `total` — the total number of chunks returned.
476
440
  *
477
441
  * **Error responses:**
478
442
  *
479
- * - `500` — Unexpected internal error during YouTube source processing.
443
+ * - `500` — Unexpected internal error during retrieval.
480
444
  *
481
445
  * @example
482
446
  * ```ts
483
- * const publicSource = await client.sources.uploadYoutube({
484
- * url: 'url',
447
+ * const response = await client.sources.retrieveChunks({
448
+ * query: 'query',
485
449
  * });
486
450
  * ```
487
451
  */
488
- uploadYoutube(body, options) {
489
- return this._client.post('/sources/upload-youtube-source', { body, ...options });
452
+ retrieveChunks(body, options) {
453
+ return this._client.post('/sources/prebuilt-rag', { body, ...options });
490
454
  }
491
455
  }
492
456
  //# sourceMappingURL=sources.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"sources.mjs","sourceRoot":"","sources":["../src/resources/sources.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"sources.mjs","sourceRoot":"","sources":["../src/resources/sources.ts"],"names":[],"mappings":"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"}