graphor 0.18.0 → 0.20.0

package/src/resources/sources.ts

@@ -125,7 +125,7 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.ask({
-   *   question: 'question',
+   *   question: "What was the company's revenue in 2025?",
    * });
    * ```
    */
@@ -169,8 +169,9 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.extract({
-   *   output_schema: { foo: 'bar' },
-   *   user_instruction: 'user_instruction',
+   *   output_schema: { properties: 'bar', type: 'bar' },
+   *   user_instruction:
+   *     'Extract all invoice line items including product name, quantity, unit price, and total.',
    * });
    * ```
    */
@@ -296,6 +297,52 @@ export class Sources extends APIResource {
     return this._client.get('/sources/get-elements', { query, ...options });
   }
 
+  /**
+   * Render a single page of a source file as a base64-encoded PNG screenshot.
+   *
+   * Use this endpoint to lazily fetch the visual preview of a citation returned by
+   * `/ask-sources` without paying the payload cost of inlining base64 in the answer.
+   * Supports PDFs, image files (`page_number` must be 1), and Office documents
+   * (doc/docx/ppt/pptx/odt — rendered from the converted PDF).
+   *
+   * **Path parameters:**
+   *
+   * - **file_id** (str): UUID of the source file.
+   * - **page_number** (int): 1-based page number.
+   *
+   * **Query parameters:**
+   *
+   * - **max_width** (int, optional, default `900`): Pixel width cap. Clamped to the
+   *   300-1600 range.
+   *
+   * **Returns** a `PublicPageScreenshotResponse` containing:
+   *
+   * - `file_id`, `file_name`, `page_number` — identifying metadata.
+   * - `mime_type` — always `"image/png"`.
+   * - `width`, `height` — rendered image dimensions in pixels.
+   * - `image_base64` — the base64-encoded PNG bytes.
+   *
+   * **Error responses:**
+   *
+   * - `404` — File not found, unsupported file type, or invalid page number.
+   * - `500` — Unexpected internal error while rendering.
+   *
+   * @example
+   * ```ts
+   * const response = await client.sources.getPageScreenshot(0, {
+   *   file_id: 'file_id',
+   * });
+   * ```
+   */
+  getPageScreenshot(
+    pageNumber: number,
+    params: SourceGetPageScreenshotParams,
+    options?: RequestOptions,
+  ): APIPromise<SourceGetPageScreenshotResponse> {
+    const { file_id, ...query } = params;
+    return this._client.get(path`/sources/${file_id}/pages/${pageNumber}/screenshot`, { query, ...options });
+  }
+
   /**
    * Upload a local file and schedule ingestion in the background.
    *
@@ -309,7 +356,7 @@ export class Sources extends APIResource {
    *   `Content-Length` and have a supported extension (pdf, doc, docx, csv, txt, md,
    *   etc.).
    * - **method** (`form`, optional): Partitioning strategy. One of: `fast`,
-   *   `balanced`, `accurate`, `vlm`, `agentic`. Default when omitted.
+   *   `balanced`, `accurate`, `vlm`, `agentic`, `auto`. Default when omitted.
    *
    * **Returns** `AsyncIngestResponse` with `build_id`. Use it to check processing
    * status.
@@ -344,7 +391,7 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.ingestGitHub({
-   *   url: 'url',
+   *   url: 'https://github.com/langchain-ai/langchain',
    * });
    * ```
    */
@@ -375,8 +422,8 @@ export class Sources extends APIResource {
    *   also follow and ingest links found on the page. Ignored when the URL resolves
    *   to a file.
    * - **method** (str, optional): The partitioning strategy to use. One of: `fast`,
-   *   `balanced`, `accurate`, `vlm`, `agentic`. When omitted the system default is
-   *   applied.
+   *   `balanced`, `accurate`, `vlm`, `agentic`, `auto`. When omitted the system
+   *   default is applied.
    *
    * **Returns** a `PublicSourceResponse` with `status: "processing"` immediately.
    * Poll the source status endpoint using the returned `file_id` to track
@@ -390,7 +437,7 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.ingestURL({
-   *   url: 'url',
+   *   url: 'https://example.com/blog/ai-trends-2025',
    * });
    * ```
    */
@@ -415,7 +462,7 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.ingestYoutube({
-   *   url: 'url',
+   *   url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    * });
    * ```
    */
@@ -437,14 +484,14 @@ export class Sources extends APIResource {
    *
    * - **file_id** (str, required): Unique identifier of the source to re-process.
    * - **method** (str, default `"fast"`): Partitioning strategy. One of: `fast`,
-   *   `balanced`, `accurate`, `vlm`, `agentic`.
+   *   `balanced`, `accurate`, `vlm`, `agentic`, `auto`.
    *
    * **Returns** `AsyncIngestResponse` with `build_id`.
    *
    * @example
    * ```ts
    * const response = await client.sources.reprocess({
-   *   file_id: 'file_id',
+   *   file_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    * });
    * ```
    */
@@ -484,7 +531,7 @@ export class Sources extends APIResource {
    * @example
    * ```ts
    * const response = await client.sources.retrieveChunks({
-   *   query: 'query',
+   *   query: "What was the company's net income in 2025?",
    * });
    * ```
    */
@@ -607,10 +654,10 @@ export interface Element {
  * - fast → basic
  * - balanced → hi_res
  * - accurate → hi_res_ft
- * - vlm → mai
  * - agentic → graphorlm
+ * - auto → auto
  */
-export type Method = 'fast' | 'balanced' | 'accurate' | 'vlm' | 'agentic';
+export type Method = 'fast' | 'balanced' | 'accurate' | 'agentic' | 'auto';
 
 export interface PublicSource {
   /**
@@ -661,7 +708,7 @@ export interface PublicSource {
 
   /**
    * Partitioning strategy used during ingestion. V1 API: basic, hi_res, hi_res_ft,
-   * mai, graphorlm. V2 API: fast, balanced, accurate, vlm, agentic.
+   * mai, graphorlm, auto. V2 API: fast, balanced, accurate, agentic, auto.
    */
   method?: string | null;
 }
@@ -704,10 +751,18 @@ export interface SourceAskResponse {
   /**
    * The answer to the question. When output_schema is provided, this will be a short
    * status message and the structured data will be in structured_output (and the raw
-   * JSON-text in raw_json).
+   * JSON-text in raw_json). Inline citations appear as `[N]` markers; use the
+   * `citations` field to resolve each marker to its source.
    */
   answer: string;
 
+  /**
+   * Structured citations extracted from the `[N]` markers in `answer`. When the
+   * request includes `include_citation_images=true`, each entry carries a
+   * base64-encoded PNG screenshot of the cited page in `image_base64`.
+   */
+  citations?: Array<SourceAskResponse.Citation> | null;
+
   /**
    * Conversation identifier used to maintain memory context
    */
@@ -737,6 +792,57 @@ export interface SourceAskResponse {
 }
 
 export namespace SourceAskResponse {
+  /**
+   * A structured citation extracted from the inline `[N]` markers in the answer.
+   *
+   * Each citation corresponds to one `[N]` marker in the `answer` text. Use the
+   * `index` field to map between the marker and the citation entry.
+   */
+  export interface Citation {
+    /**
+     * Optional element identifier within the page/section (e.g. a specific paragraph
+     * or table).
+     */
+    element_id?: string | null;
+
+    /**
+     * The unique identifier of the source file the citation refers to.
+     */
+    file_id?: string | null;
+
+    /**
+     * Display name of the source file.
+     */
+    file_name?: string | null;
+
+    /**
+     * Base64-encoded PNG screenshot of the cited page. Only populated when the request
+     * was made with `include_citation_images=true`. May be null if the underlying
+     * source is not visualizable (e.g. plain text).
+     */
+    image_base64?: string | null;
+
+    /**
+     * The 1-based citation number that appears as `[N]` in the answer text.
+     */
+    index?: number | null;
+
+    /**
+     * 1-based page number where the cited content appears.
+     */
+    page_number?: number | null;
+
+    /**
+     * Optional section number within the page.
+     */
+    section_number?: number | null;
+
+    /**
+     * Short text excerpt around the cited content, useful for quick context.
+     */
+    text_preview?: string | null;
+  }
+
   /**
    * Token usage breakdown for this request.
    */
@@ -861,8 +967,8 @@ export interface SourceGetBuildStatusResponse {
    * - fast → basic
    * - balanced → hi_res
    * - accurate → hi_res_ft
-   * - vlm → mai
    * - agentic → graphorlm
+   * - auto → auto
    */
   method?: Method | null;
 
@@ -931,6 +1037,46 @@ export interface SourceGetElementsResponse {
   total_pages?: number | null;
 }
 
+/**
+ * Base64-encoded PNG screenshot of a page from a source file.
+ */
+export interface SourceGetPageScreenshotResponse {
+  /**
+   * The unique identifier of the source file.
+   */
+  file_id: string;
+
+  /**
+   * Base64-encoded PNG image bytes.
+   */
+  image_base64: string;
+
+  /**
+   * 1-based page number that was rendered.
+   */
+  page_number: number;
+
+  /**
+   * Display name of the source file.
+   */
+  file_name?: string | null;
+
+  /**
+   * Pixel height of the rendered image.
+   */
+  height?: number | null;
+
+  /**
+   * MIME type of the encoded image (always image/png).
+   */
+  mime_type?: string;
+
+  /**
+   * Pixel width of the rendered image.
+   */
+  width?: number | null;
+}
+
 export interface SourceIngestFileResponse {
   /**
    * The ID of the build. This ID can be used to check the status of the request.
@@ -1109,6 +1255,25 @@ export interface SourceAskParams {
    */
   file_names?: Array<string> | null;
 
+  /**
+   * When true, the response's `citations` entries are populated with a
+   * base64-encoded PNG screenshot of each cited page in `image_base64`. Increases
+   * payload size and latency — leave false (the default) when not needed and fetch
+   * screenshots on demand via
+   * `GET /sources/{file_id}/pages/{page_number}/screenshot`.
+   */
+  include_citation_images?: boolean | null;
+
+  /**
+   * When true, the `answer` field keeps the structured citation markup
+   * `[N](file_id|pX|sY|eZ|fNAME)` emitted by the agent. When false (default), the
+   * markup is stripped to plain `[N]` markers and the structured data is exposed via
+   * `citations` instead. Note: the markup format is an implementation detail and may
+   * change in future versions — prefer the `citations` field for stable parsing. Has
+   * no effect when `output_schema` is set.
+   */
+  include_citation_markup?: boolean | null;
+
   /**
    * Optional JSON Schema for requesting structured output. When provided, the answer
    * field will contain a short status message and the structured data will be in
@@ -1122,10 +1287,10 @@ export interface SourceAskParams {
   reset?: boolean | null;
 
   /**
-   * Controls model and thinking budget: 'fast' (cheapest/fastest), 'balanced', or
-   * 'accurate' (most thorough)
+   * Controls model and thinking budget: 'fast' (cheapest/fastest), 'balanced',
+   * 'accurate', or 'max' (most thorough)
    */
-  thinking_level?: 'fast' | 'balanced' | 'accurate' | null;
+  thinking_level?: 'fast' | 'balanced' | 'accurate' | 'max' | null;
 }
 
 export interface SourceExtractParams {
@@ -1151,10 +1316,10 @@ export interface SourceExtractParams {
   file_names?: Array<string> | null;
 
   /**
-   * Controls model and thinking budget: 'fast' (cheapest/fastest), 'balanced', or
-   * 'accurate' (most thorough)
+   * Controls model and thinking budget: 'fast' (cheapest/fastest), 'balanced',
+   * 'accurate', or 'max' (most thorough)
    */
-  thinking_level?: 'fast' | 'balanced' | 'accurate' | null;
+  thinking_level?: 'fast' | 'balanced' | 'accurate' | 'max' | null;
 }
 
 export interface SourceGetBuildStatusParams {
@@ -1209,6 +1374,18 @@ export interface SourceGetElementsParams {
   type?: string | null;
 }
 
+export interface SourceGetPageScreenshotParams {
+  /**
+   * Path param
+   */
+  file_id: string;
+
+  /**
+   * Query param: Pixel width cap for the rendered image (clamped to 300-1600).
+   */
+  max_width?: number;
+}
+
 export interface SourceIngestFileParams {
   file: Uploadable;
 
@@ -1220,8 +1397,8 @@ export interface SourceIngestFileParams {
    * - fast → basic
    * - balanced → hi_res
    * - accurate → hi_res_ft
-   * - vlm → mai
    * - agentic → graphorlm
+   * - auto → auto
    */
   method?: Method | null;
 }
@@ -1252,8 +1429,8 @@ export interface SourceIngestURLParams {
    * - fast → basic
    * - balanced → hi_res
    * - accurate → hi_res_ft
-   * - vlm → mai
    * - agentic → graphorlm
+   * - auto → auto
    */
   method?: Method | null;
 }
@@ -1273,7 +1450,7 @@ export interface SourceReprocessParams {
   file_id: string;
 
   /**
-   * Partitioning strategy. One of: fast, balanced, accurate, vlm, agentic.
+   * Partitioning strategy. One of: fast, balanced, accurate, agentic, auto.
    */
   method?: Method;
 }
@@ -1307,6 +1484,7 @@ export declare namespace Sources {
     type SourceExtractResponse as SourceExtractResponse,
     type SourceGetBuildStatusResponse as SourceGetBuildStatusResponse,
     type SourceGetElementsResponse as SourceGetElementsResponse,
+    type SourceGetPageScreenshotResponse as SourceGetPageScreenshotResponse,
     type SourceIngestFileResponse as SourceIngestFileResponse,
     type SourceIngestGitHubResponse as SourceIngestGitHubResponse,
     type SourceIngestURLResponse as SourceIngestURLResponse,
@@ -1319,6 +1497,7 @@ export declare namespace Sources {
     type SourceExtractParams as SourceExtractParams,
     type SourceGetBuildStatusParams as SourceGetBuildStatusParams,
     type SourceGetElementsParams as SourceGetElementsParams,
+    type SourceGetPageScreenshotParams as SourceGetPageScreenshotParams,
     type SourceIngestFileParams as SourceIngestFileParams,
     type SourceIngestGitHubParams as SourceIngestGitHubParams,
     type SourceIngestURLParams as SourceIngestURLParams,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.18.0'; // x-release-please-version
+export const VERSION = '0.20.0'; // x-release-please-version

package/uploads.d.mts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.mjs";
 //# sourceMappingURL=uploads.d.mts.map

package/uploads.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.d.mts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.d.mts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,mCAA+B"}

package/uploads.d.ts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.js";
 //# sourceMappingURL=uploads.d.ts.map

package/uploads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,kCAA+B"}

package/uploads.mjs

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/uploads instead */
 export * from "./core/uploads.mjs";
 //# sourceMappingURL=uploads.mjs.map

package/uploads.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"uploads.mjs","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}
+{"version":3,"file":"uploads.mjs","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,mCAA+B"}

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.20.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.20.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.18.0'; // x-release-please-version
+exports.VERSION = '0.20.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.18.0'; // x-release-please-version
+export const VERSION = '0.20.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map