From 67be5c7f62052e4d8d4ca960acf5d741f626103e Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 11 Mar 2025 18:12:32 +0000 Subject: [PATCH 01/29] feat(api): update via SDK Studio (#40) --- .stats.yml | 2 +- src/resources/agents/query.ts | 2 +- src/resources/datastores/documents.ts | 2 +- src/resources/generate.ts | 3 ++- src/resources/rerank.ts | 34 ++++++++++----------------- 5 files changed, 18 insertions(+), 25 deletions(-) diff --git a/.stats.yml b/.stats.yml index 50cd37d..2ce9447 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-194878b194cd507d7c5418ff38cc0fc53441ef618f991990d334b4b75775cd8f.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-e20c18e11af76caf98794e68406fc556cf91d13e8e27a3b1d1909a4f8c2d3eb5.yml diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index 1abad48..83706be 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -434,7 +434,7 @@ export namespace QueryCreateParams { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | number | boolean | Array | null; + value?: string | (string & {}) | number | boolean | Array | Array; } } diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 9ade45c..94b125c 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -153,7 +153,7 @@ export namespace CompositeMetadataFilter { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | number | boolean | Array | null; + value?: string | (string & {}) | number | boolean | Array | Array; } } diff --git a/src/resources/generate.ts b/src/resources/generate.ts index 7d97052..74b9252 100644 --- a/src/resources/generate.ts +++ b/src/resources/generate.ts @@ -44,7 +44,8 @@ export interface GenerateCreateParams { messages: Array; /** - * The version of the Contextual's GLM to use. Currently, we just have "v1". + * The version of the Contextual's GLM to use. Currently, we just have + * "ctxl-rerank-en-v1-instruct". */ model: string; diff --git a/src/resources/rerank.ts b/src/resources/rerank.ts index 98f9ed8..f1661bc 100644 --- a/src/resources/rerank.ts +++ b/src/resources/rerank.ts @@ -5,14 +5,10 @@ import * as Core from '../core'; export class Rerank extends APIResource { /** - * Rank a list of documents according to their relevance to a query and your custom - * instructions about how to prioritize retrievals. We evaluated the model on - * instructions for recency, document type, source, and metadata, and it can - * generalize to other instructions as well. + * Rank a list of documents according to their relevance to a query. * - * The total request cannot exceed 400,000 tokens. The combined length of the - * query, instruction and any document with its metadata must not exceed 8,000 - * tokens. Email + * The total request cannot exceed 400,000 tokens. The combined length of any + * document, instruction and the query must not exceed 4,000 tokens. Email * [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any * feedback or questions. */ @@ -56,14 +52,12 @@ export namespace RerankCreateResponse { export interface RerankCreateParams { /** - * The texts to be reranked according to their relevance to the query and the - * optional instruction + * The texts to be reranked according to their relevance to the query */ documents: Array; /** - * The version of the reranker to use. Currently, we just have - * "ctxl-rerank-en-v1-instruct". + * The version of the reranker to use. Currently, we just have "v1". */ model: string; @@ -73,21 +67,19 @@ export interface RerankCreateParams { query: string; /** - * Instructions that the reranker references when ranking retrievals. We evaluated - * the model on instructions for recency, document type, source, and metadata, and - * it can generalize to other instructions as well. Note that we do not guarantee - * that the reranker will follow these instructions exactly. Examples: "Prioritize - * internal sales documents over market analysis reports. More recent documents - * should be weighted higher. Enterprise portal content supersedes distributor - * communications." and "Emphasize forecasts from top-tier investment banks. Recent - * analysis should take precedence. Disregard aggregator sites and favor detailed - * research notes over news summaries." + * Instructions that the reranker references when ranking retrievals. Note that we + * do not guarantee that the reranker will follow these instructions exactly. + * Examples: "Prioritize internal sales documents over market analysis reports. + * More recent documents should be weighted higher. Enterprise portal content + * supersedes distributor communications." and "Emphasize forecasts from top-tier + * investment banks. Recent analysis should take precedence. Disregard aggregator + * sites and favor detailed research notes over news summaries." */ instruction?: string; /** * Metadata for documents being passed to the reranker. Must be the same length as - * the documents list. If a document does not have metadata, add an empty string. + * the documents list. */ metadata?: Array; From a20be255eccdd3d73b8b82215ed1bb4f5ca2e010 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 11 Mar 2025 18:14:16 +0000 Subject: [PATCH 02/29] feat(api): update via SDK Studio (#42) --- .stats.yml | 2 +- src/resources/agents/query.ts | 2 +- src/resources/datastores/documents.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.stats.yml b/.stats.yml index 2ce9447..73b6d94 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-e20c18e11af76caf98794e68406fc556cf91d13e8e27a3b1d1909a4f8c2d3eb5.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-9ab0280b104bf117a95934b45a46cbae3e498eef6c7e29935ce6d9f5c6cfe73c.yml diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index 83706be..261b462 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -434,7 +434,7 @@ export namespace QueryCreateParams { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | (string & {}) | number | boolean | Array | Array; + value?: string | (string & {}) | number | boolean | Array | Array; } } diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 94b125c..7e83b8f 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -153,7 +153,7 @@ export namespace CompositeMetadataFilter { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | (string & {}) | number | boolean | Array | Array; + value?: string | (string & {}) | number | boolean | Array | Array; } } From 14c74c15ebcef0871e7325453eb1ed02d12a7306 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 11 Mar 2025 18:26:24 +0000 Subject: [PATCH 03/29] feat(api): update via SDK Studio (#43) --- .stats.yml | 2 +- src/resources/agents/query.ts | 11 ++++++++++- src/resources/datastores/documents.ts | 11 ++++++++++- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/.stats.yml b/.stats.yml index 73b6d94..9eb17a5 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-9ab0280b104bf117a95934b45a46cbae3e498eef6c7e29935ce6d9f5c6cfe73c.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-a1e925a06906199ea147a4e0fe2d763425765bea27d6c2d3b51111b45fcffabd.yml diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index 261b462..850d4ab 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -434,7 +434,16 @@ export namespace QueryCreateParams { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | (string & {}) | number | boolean | Array | Array; + value?: + | string + | (string & {}) + | number + | boolean + | Array + | Array + | Array + | Array + | Array; } } diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 7e83b8f..410e2e3 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -153,7 +153,16 @@ export namespace CompositeMetadataFilter { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: string | (string & {}) | number | boolean | Array | Array; + value?: + | string + | (string & {}) + | number + | boolean + | Array + | Array + | Array + | Array + | Array; } } From 94cf64d933f96e05b70757122a22871109190014 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 11 Mar 2025 18:29:49 +0000 Subject: [PATCH 04/29] feat(api): update via SDK Studio (#44) --- .stats.yml | 2 +- src/resources/agents/query.ts | 10 +++++----- src/resources/datastores/documents.ts | 10 +++++----- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.stats.yml b/.stats.yml index 9eb17a5..0eccad1 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-a1e925a06906199ea147a4e0fe2d763425765bea27d6c2d3b51111b45fcffabd.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-9c21ec8adeab592ce943fdce106e59fb5b70f6d78dea86e637ce89840e3c9edf.yml diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index 850d4ab..a3b82da 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -439,11 +439,11 @@ export namespace QueryCreateParams { | (string & {}) | number | boolean - | Array - | Array - | Array - | Array - | Array; + | Array + | Array + | Array + | Array + | Array; } } diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 410e2e3..29de1b7 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -158,11 +158,11 @@ export namespace CompositeMetadataFilter { | (string & {}) | number | boolean - | Array - | Array - | Array - | Array - | Array; + | Array + | Array + | Array + | Array + | Array; } } From 6f3896383295cdfbdec9a65a5a470abf3379410c Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 13 Mar 2025 05:59:02 +0000 Subject: [PATCH 05/29] feat(api): update via SDK Studio (#45) --- .stats.yml | 2 +- src/resources/agents/agents.ts | 5 ----- src/resources/agents/query.ts | 11 +---------- src/resources/datastores/datastores.ts | 5 ----- src/resources/datastores/documents.ts | 11 +---------- 5 files changed, 3 insertions(+), 31 deletions(-) diff --git a/.stats.yml b/.stats.yml index 0eccad1..0e43806 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,2 @@ configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-9c21ec8adeab592ce943fdce106e59fb5b70f6d78dea86e637ce89840e3c9edf.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-c978f14e96782dd2ca8a8dbfdd822941e52df70306cb99d93218c61363460f03.yml diff --git a/src/resources/agents/agents.ts b/src/resources/agents/agents.ts index ed66df4..fa39882 100644 --- a/src/resources/agents/agents.ts +++ b/src/resources/agents/agents.ts @@ -41,11 +41,6 @@ export class Agents extends APIResource { * If no `datastore_id` is provided in the configuration, this API automatically * creates an empty `Datastore` and configures the `Agent` to use the newly created * `Datastore`. - * - * > Note that self-serve users are currently required to create agents through our - * > UI. Otherwise, they will receive the following message: "This endpoint is - * > disabled as you need to go through checkout. Please use the UI to make this - * > request." */ create(body: AgentCreateParams, options?: Core.RequestOptions): Core.APIPromise { return this._client.post('/agents', { body, ...options }); diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index a3b82da..1abad48 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -434,16 +434,7 @@ export namespace QueryCreateParams { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: - | string - | (string & {}) - | number - | boolean - | Array - | Array - | Array - | Array - | Array; + value?: string | number | boolean | Array | null; } } diff --git a/src/resources/datastores/datastores.ts b/src/resources/datastores/datastores.ts index acd0c9f..ff21ce9 100644 --- a/src/resources/datastores/datastores.ts +++ b/src/resources/datastores/datastores.ts @@ -32,11 +32,6 @@ export class Datastores extends APIResource { * relevant data. This flexible many-to-many relationship allows `Agents` to draw * from multiple sources of information. This linkage of `Datastore` to `Agent` is * done through the `Create Agent` or `Edit Agent` APIs. - * - * > Note that self-serve users are currently required to create datastores through - * > our UI. Otherwise, they will receive the following message: "This endpoint is - * > disabled as you need to go through checkout. Please use the UI to make this - * > request." */ create( body: DatastoreCreateParams, diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 29de1b7..9ade45c 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -153,16 +153,7 @@ export namespace CompositeMetadataFilter { * The value to be searched for in the field. In case of exists operator, it is not * needed. */ - value?: - | string - | (string & {}) - | number - | boolean - | Array - | Array - | Array - | Array - | Array; + value?: string | number | boolean | Array | null; } } From bf1f16c174c4d6caf5d120cdfe4da281a2398a8a Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Fri, 14 Mar 2025 03:56:19 +0000 Subject: [PATCH 06/29] chore(internal): remove extra empty newlines (#46) --- .github/workflows/ci.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e3530dc..0312165 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,4 +63,3 @@ jobs: - name: Run tests run: ./scripts/test - From e530478fe8da3337643d66f4eb6cb98fb715cc16 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Fri, 14 Mar 2025 04:07:28 +0000 Subject: [PATCH 07/29] fix(exports): ensure resource imports don't require /index (#47) --- src/resources/agents.ts | 3 +++ src/resources/agents/datasets.ts | 3 +++ src/resources/agents/evaluate.ts | 3 +++ src/resources/agents/tune.ts | 3 +++ src/resources/datastores.ts | 3 +++ 5 files changed, 15 insertions(+) create mode 100644 src/resources/agents.ts create mode 100644 src/resources/agents/datasets.ts create mode 100644 src/resources/agents/evaluate.ts create mode 100644 src/resources/agents/tune.ts create mode 100644 src/resources/datastores.ts diff --git a/src/resources/agents.ts b/src/resources/agents.ts new file mode 100644 index 0000000..0c43db0 --- /dev/null +++ b/src/resources/agents.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './agents/index'; diff --git a/src/resources/agents/datasets.ts b/src/resources/agents/datasets.ts new file mode 100644 index 0000000..4b86aa0 --- /dev/null +++ b/src/resources/agents/datasets.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './datasets/index'; diff --git a/src/resources/agents/evaluate.ts b/src/resources/agents/evaluate.ts new file mode 100644 index 0000000..74e2612 --- /dev/null +++ b/src/resources/agents/evaluate.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './evaluate/index'; diff --git a/src/resources/agents/tune.ts b/src/resources/agents/tune.ts new file mode 100644 index 0000000..bd81324 --- /dev/null +++ b/src/resources/agents/tune.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './tune/index'; diff --git a/src/resources/datastores.ts b/src/resources/datastores.ts new file mode 100644 index 0000000..f128d39 --- /dev/null +++ b/src/resources/datastores.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './datastores/index'; From b204f8a909d95f11e4cf795d68a96b7eaf362c67 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 20 Mar 2025 03:53:36 +0000 Subject: [PATCH 08/29] chore(exports): cleaner resource index imports (#48) --- src/resources.ts | 1 + 1 file changed, 1 insertion(+) create mode 100644 src/resources.ts diff --git a/src/resources.ts b/src/resources.ts new file mode 100644 index 0000000..b283d57 --- /dev/null +++ b/src/resources.ts @@ -0,0 +1 @@ +export * from './resources/index'; From b0bed50ab202f8b80636db662c063a9094c3de16 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 20 Mar 2025 03:54:46 +0000 Subject: [PATCH 09/29] chore(exports): stop using path fallbacks (#49) --- package.json | 35 +++++++---------------------------- 1 file changed, 7 insertions(+), 28 deletions(-) diff --git a/package.json b/package.json index 5d81b27..6c0ba62 100644 --- a/package.json +++ b/package.json @@ -107,38 +107,17 @@ "default": "./dist/index.mjs" }, "./*.mjs": { - "types": [ - "./dist/*.d.ts", - "./dist/*/index.d.ts" - ], - "default": [ - "./dist/*.mjs", - "./dist/*/index.mjs" - ] + "types": "./dist/*.d.ts", + "default": "./dist/*.mjs" }, "./*.js": { - "types": [ - "./dist/*.d.ts", - "./dist/*/index.d.ts" - ], - "default": [ - "./dist/*.js", - "./dist/*/index.js" - ] + "types": "./dist/*.d.ts", + "default": "./dist/*.js" }, "./*": { - "types": [ - "./dist/*.d.ts", - "./dist/*/index.d.ts" - ], - "require": [ - "./dist/*.js", - "./dist/*/index.js" - ], - "default": [ - "./dist/*.mjs", - "./dist/*/index.mjs" - ] + "types": "./dist/*.d.ts", + "require": "./dist/*.js", + "default": "./dist/*.mjs" } } } From 91cd06af830f4ef13bda0cea76908afaeb03ec19 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Sat, 22 Mar 2025 03:27:06 +0000 Subject: [PATCH 10/29] fix: avoid type error in certain environments (#50) --- src/core.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/core.ts b/src/core.ts index 058bd17..ff16890 100644 --- a/src/core.ts +++ b/src/core.ts @@ -395,7 +395,7 @@ export abstract class APIClient { !headers ? {} : Symbol.iterator in headers ? Object.fromEntries(Array.from(headers as Iterable).map((header) => [...header])) - : { ...headers } + : { ...(headers as any as Record) } ); } From aeb2d364202df2017ef1a470d1d892995f48a877 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 27 Mar 2025 02:52:08 +0000 Subject: [PATCH 11/29] codegen metadata --- .stats.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.stats.yml b/.stats.yml index 0e43806..c1b7080 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,2 +1,4 @@ configured_endpoints: 46 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-c978f14e96782dd2ca8a8dbfdd822941e52df70306cb99d93218c61363460f03.yml +openapi_spec_hash: 57aec46adc855c43bcd349940fbc247d +config_hash: 47781a5702123e4592e019351ce8cf45 From 7f0bfddede9817da316a849511cfa112191c8bef Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Fri, 28 Mar 2025 03:05:26 +0000 Subject: [PATCH 12/29] fix(internal): work around https://github.com/vercel/next.js/issues/76881 (#51) --- src/_shims/index-deno.ts | 2 ++ src/_shims/index.d.ts | 2 ++ src/_shims/index.js | 6 +++++- src/_shims/index.mjs | 6 +++++- src/core.ts | 5 +++++ 5 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/_shims/index-deno.ts b/src/_shims/index-deno.ts index ce6ff50..12bb727 100644 --- a/src/_shims/index-deno.ts +++ b/src/_shims/index-deno.ts @@ -108,3 +108,5 @@ export declare class FsReadStream extends Readable { const _ReadableStream = ReadableStream; type _ReadableStream = ReadableStream; export { _ReadableStream as ReadableStream }; + +export const init = () => {}; diff --git a/src/_shims/index.d.ts b/src/_shims/index.d.ts index 55d08db..a4264d7 100644 --- a/src/_shims/index.d.ts +++ b/src/_shims/index.d.ts @@ -79,3 +79,5 @@ export function fileFromPath(path: string, options?: FileFromPathOptions): Promi export function fileFromPath(path: string, filename?: string, options?: FileFromPathOptions): Promise; export function isFsReadStream(value: any): value is FsReadStream; + +export const init: () => void; diff --git a/src/_shims/index.js b/src/_shims/index.js index c598b59..80e4786 100644 --- a/src/_shims/index.js +++ b/src/_shims/index.js @@ -3,7 +3,9 @@ */ const shims = require('./registry'); const auto = require('contextual-client/_shims/auto/runtime'); -if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true }); +exports.init = () => { + if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true }); +}; for (const property of Object.keys(shims)) { Object.defineProperty(exports, property, { get() { @@ -11,3 +13,5 @@ for (const property of Object.keys(shims)) { }, }); } + +exports.init(); diff --git a/src/_shims/index.mjs b/src/_shims/index.mjs index 50a3a37..7708dbe 100644 --- a/src/_shims/index.mjs +++ b/src/_shims/index.mjs @@ -3,5 +3,9 @@ */ import * as shims from './registry.mjs'; import * as auto from 'contextual-client/_shims/auto/runtime'; -if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true }); +export const init = () => { + if (!shims.kind) shims.setShims(auto.getRuntime(), { auto: true }); +}; export * from './registry.mjs'; + +init(); diff --git a/src/core.ts b/src/core.ts index ff16890..6f1537f 100644 --- a/src/core.ts +++ b/src/core.ts @@ -16,7 +16,12 @@ import { type RequestInit, type Response, type HeadersInit, + init, } from './_shims/index'; + +// try running side effects outside of _shims/index to workaround https://github.com/vercel/next.js/issues/76881 +init(); + export { type Response }; import { BlobLike, isBlobLike, isMultipartBody } from './uploads'; export { From 94fba4c76050b7471c7dbb50391cd8196278cac2 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 3 Apr 2025 04:49:45 +0000 Subject: [PATCH 13/29] fix(client): send `X-Stainless-Timeout` in seconds (#52) --- src/core.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/core.ts b/src/core.ts index 6f1537f..8f1fa07 100644 --- a/src/core.ts +++ b/src/core.ts @@ -371,7 +371,7 @@ export abstract class APIClient { getHeader(headers, 'x-stainless-timeout') === undefined && options.timeout ) { - reqHeaders['x-stainless-timeout'] = String(options.timeout); + reqHeaders['x-stainless-timeout'] = String(Math.trunc(options.timeout / 1000)); } this.validateHeaders(reqHeaders, headers); From 3fcab5f1e451d41b1c3c3f399fe170c3fccb895a Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 3 Apr 2025 05:19:25 +0000 Subject: [PATCH 14/29] chore(internal): add aliases for Record and Array (#53) --- src/core.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/core.ts b/src/core.ts index 8f1fa07..781da4a 100644 --- a/src/core.ts +++ b/src/core.ts @@ -33,6 +33,20 @@ export { export type Fetch = (url: RequestInfo, init?: RequestInit) => Promise; +/** + * An alias to the builtin `Array` type so we can + * easily alias it in import statements if there are name clashes. + */ +type _Array = Array; + +/** + * An alias to the builtin `Record` type so we can + * easily alias it in import statements if there are name clashes. + */ +type _Record = Record; + +export type { _Array as Array, _Record as Record }; + type PromiseOrValue = T | Promise; type APIResponseProps = { From bd2f8ab3d2cc796201c530c5e85e4485ac337506 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Fri, 4 Apr 2025 06:01:01 +0000 Subject: [PATCH 15/29] fix(api): improve type resolution when importing as a package (#54) --- packages/mcp-server/src/tools.ts | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/mcp-server/src/tools.ts diff --git a/packages/mcp-server/src/tools.ts b/packages/mcp-server/src/tools.ts new file mode 100644 index 0000000..7e516de --- /dev/null +++ b/packages/mcp-server/src/tools.ts @@ -0,0 +1 @@ +export * from './tools/index'; From 119ec6fb6eff339fa9dd08481d527ca46674485f Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Sat, 5 Apr 2025 02:14:10 +0000 Subject: [PATCH 16/29] fix(mcp): remove unused tools.ts (#55) --- packages/mcp-server/src/tools.ts | 1 - 1 file changed, 1 deletion(-) delete mode 100644 packages/mcp-server/src/tools.ts diff --git a/packages/mcp-server/src/tools.ts b/packages/mcp-server/src/tools.ts deleted file mode 100644 index 7e516de..0000000 --- a/packages/mcp-server/src/tools.ts +++ /dev/null @@ -1 +0,0 @@ -export * from './tools/index'; From ba02a4a584975a100a61610e0cb819a7f345f01f Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 10 Apr 2025 02:23:17 +0000 Subject: [PATCH 17/29] chore(internal): upload builds and expand CI branch coverage --- .github/workflows/ci.yml | 36 ++++++++++++++++++++++---------- scripts/utils/upload-artifact.sh | 25 ++++++++++++++++++++++ 2 files changed, 50 insertions(+), 11 deletions(-) create mode 100755 scripts/utils/upload-artifact.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0312165..7f7dfc0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,19 +1,18 @@ name: CI on: push: - branches: - - main - pull_request: - branches: - - main - - next + branches-ignore: + - 'generated' + - 'codegen/**' + - 'integrated/**' + - 'preview-head/**' + - 'preview-base/**' + - 'preview/**' jobs: lint: name: lint runs-on: ubuntu-latest - - steps: - uses: actions/checkout@v4 @@ -31,8 +30,9 @@ jobs: build: name: build runs-on: ubuntu-latest - - + permissions: + contents: read + id-token: write steps: - uses: actions/checkout@v4 @@ -46,10 +46,24 @@ jobs: - name: Check build run: ./scripts/build + + - name: Get GitHub OIDC Token + if: github.repository == 'stainless-sdks/sunrise-node' + id: github-oidc + uses: actions/github-script@v6 + with: + script: core.setOutput('github_token', await core.getIDToken()); + + - name: Upload tarball + if: github.repository == 'stainless-sdks/sunrise-node' + env: + URL: https://pkg.stainless.com/s + AUTH: ${{ steps.github-oidc.outputs.github_token }} + SHA: ${{ github.sha }} + run: ./scripts/utils/upload-artifact.sh test: name: test runs-on: ubuntu-latest - steps: - uses: actions/checkout@v4 diff --git a/scripts/utils/upload-artifact.sh b/scripts/utils/upload-artifact.sh new file mode 100755 index 0000000..1c5eabf --- /dev/null +++ b/scripts/utils/upload-artifact.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +set -exuo pipefail + +RESPONSE=$(curl -X POST "$URL" \ + -H "Authorization: Bearer $AUTH" \ + -H "Content-Type: application/json") + +SIGNED_URL=$(echo "$RESPONSE" | jq -r '.url') + +if [[ "$SIGNED_URL" == "null" ]]; then + echo -e "\033[31mFailed to get signed URL.\033[0m" + exit 1 +fi + +UPLOAD_RESPONSE=$(tar -cz dist | curl -v -X PUT \ + -H "Content-Type: application/gzip" \ + --data-binary @- "$SIGNED_URL" 2>&1) + +if echo "$UPLOAD_RESPONSE" | grep -q "HTTP/[0-9.]* 200"; then + echo -e "\033[32mUploaded build to Stainless storage.\033[0m" + echo -e "\033[32mInstallation: npm install 'https://pkg.stainless.com/s/sunrise-node/$SHA'\033[0m" +else + echo -e "\033[31mFailed to upload artifact.\033[0m" + exit 1 +fi From 82a1e3f2cd28208a6de65145a62614a16b25c5da Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 10 Apr 2025 02:27:08 +0000 Subject: [PATCH 18/29] chore(internal): reduce CI branch coverage --- .github/workflows/ci.yml | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7f7dfc0..0c2d76a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,13 +1,12 @@ name: CI on: push: - branches-ignore: - - 'generated' - - 'codegen/**' - - 'integrated/**' - - 'preview-head/**' - - 'preview-base/**' - - 'preview/**' + branches: + - main + pull_request: + branches: + - main + - next jobs: lint: From 321469aec2485d12c95fdf34308ed61714d3cdfd Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 15 Apr 2025 02:33:27 +0000 Subject: [PATCH 19/29] chore(client): minor internal fixes --- src/core.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/core.ts b/src/core.ts index 781da4a..57e9e88 100644 --- a/src/core.ts +++ b/src/core.ts @@ -296,10 +296,10 @@ export abstract class APIClient { } buildRequest( - options: FinalRequestOptions, + inputOptions: FinalRequestOptions, { retryCount = 0 }: { retryCount?: number } = {}, ): { req: RequestInit; url: string; timeout: number } { - options = { ...options }; + const options = { ...inputOptions }; const { method, path, query, headers: headers = {} } = options; const body = @@ -327,8 +327,8 @@ export abstract class APIClient { } if (this.idempotencyHeader && method !== 'get') { - if (!options.idempotencyKey) options.idempotencyKey = this.defaultIdempotencyKey(); - headers[this.idempotencyHeader] = options.idempotencyKey; + if (!inputOptions.idempotencyKey) inputOptions.idempotencyKey = this.defaultIdempotencyKey(); + headers[this.idempotencyHeader] = inputOptions.idempotencyKey; } const reqHeaders = this.buildHeaders({ options, headers, contentLength, retryCount }); From b6b2a07f2bd01f34336c5a4964efe4a07a004f68 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 23 Apr 2025 02:58:51 +0000 Subject: [PATCH 20/29] chore(ci): add timeout thresholds for CI jobs --- .github/workflows/ci.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c2d76a..fc3c1e9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,6 +10,7 @@ on: jobs: lint: + timeout-minutes: 10 name: lint runs-on: ubuntu-latest steps: @@ -27,6 +28,7 @@ jobs: run: ./scripts/lint build: + timeout-minutes: 5 name: build runs-on: ubuntu-latest permissions: @@ -61,6 +63,7 @@ jobs: SHA: ${{ github.sha }} run: ./scripts/utils/upload-artifact.sh test: + timeout-minutes: 10 name: test runs-on: ubuntu-latest steps: From f3cadb2de612e13ed00fb7971af8d4676b11db33 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 24 Apr 2025 02:25:17 +0000 Subject: [PATCH 21/29] chore(internal): codegen related update --- .github/workflows/ci.yml | 18 +++++++++--------- .github/workflows/publish-npm.yml | 2 +- .github/workflows/release-doctor.yml | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fc3c1e9..806ecaa 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,18 +1,18 @@ name: CI on: push: - branches: - - main - pull_request: - branches: - - main - - next + branches-ignore: + - 'generated' + - 'codegen/**' + - 'integrated/**' + - 'stl-preview-head/**' + - 'stl-preview-base/**' jobs: lint: timeout-minutes: 10 name: lint - runs-on: ubuntu-latest + runs-on: depot-ubuntu-24.04 steps: - uses: actions/checkout@v4 @@ -30,7 +30,7 @@ jobs: build: timeout-minutes: 5 name: build - runs-on: ubuntu-latest + runs-on: depot-ubuntu-24.04 permissions: contents: read id-token: write @@ -65,7 +65,7 @@ jobs: test: timeout-minutes: 10 name: test - runs-on: ubuntu-latest + runs-on: depot-ubuntu-24.04 steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index b001c9a..8457829 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -11,7 +11,7 @@ on: jobs: publish: name: publish - runs-on: ubuntu-latest + runs-on: depot-ubuntu-24.04 steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml index 73c7639..cac9ff4 100644 --- a/.github/workflows/release-doctor.yml +++ b/.github/workflows/release-doctor.yml @@ -8,7 +8,7 @@ on: jobs: release_doctor: name: release doctor - runs-on: ubuntu-latest + runs-on: depot-ubuntu-24.04 if: github.repository == 'ContextualAI/contextual-client-node' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next') steps: From 873ba2f355fca96db4bcbcad1ef92e0597fa9bd3 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 24 Apr 2025 02:25:52 +0000 Subject: [PATCH 22/29] chore(ci): only use depot for staging repos --- .github/workflows/ci.yml | 6 +++--- .github/workflows/publish-npm.yml | 2 +- .github/workflows/release-doctor.yml | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 806ecaa..aec9433 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: lint: timeout-minutes: 10 name: lint - runs-on: depot-ubuntu-24.04 + runs-on: ${{ github.repository == 'stainless-sdks/sunrise-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} steps: - uses: actions/checkout@v4 @@ -30,7 +30,7 @@ jobs: build: timeout-minutes: 5 name: build - runs-on: depot-ubuntu-24.04 + runs-on: ${{ github.repository == 'stainless-sdks/sunrise-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} permissions: contents: read id-token: write @@ -65,7 +65,7 @@ jobs: test: timeout-minutes: 10 name: test - runs-on: depot-ubuntu-24.04 + runs-on: ${{ github.repository == 'stainless-sdks/sunrise-node' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 8457829..b001c9a 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -11,7 +11,7 @@ on: jobs: publish: name: publish - runs-on: depot-ubuntu-24.04 + runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml index cac9ff4..73c7639 100644 --- a/.github/workflows/release-doctor.yml +++ b/.github/workflows/release-doctor.yml @@ -8,7 +8,7 @@ on: jobs: release_doctor: name: release doctor - runs-on: depot-ubuntu-24.04 + runs-on: ubuntu-latest if: github.repository == 'ContextualAI/contextual-client-node' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next') steps: From 3ab3596376577889a370fc1b2c9a98b1e71b3bce Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 1 May 2025 03:10:05 +0000 Subject: [PATCH 23/29] docs(readme): fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a392cbf..db698e4 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ async function main() { main(); ``` -Error codes are as followed: +Error codes are as follows: | Status Code | Error Type | | ----------- | -------------------------- | From 5d04e11485d0379d5ff7db1dedb7f25c26db4498 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 7 May 2025 04:03:22 +0000 Subject: [PATCH 24/29] chore(ci): bump node version for release workflows --- .github/workflows/ci.yml | 2 +- .github/workflows/publish-npm.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aec9433..af03700 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,7 +72,7 @@ jobs: - name: Set up Node uses: actions/setup-node@v4 with: - node-version: '18' + node-version: '20' - name: Bootstrap run: ./scripts/bootstrap diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index b001c9a..0176df4 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -19,7 +19,7 @@ jobs: - name: Set up Node uses: actions/setup-node@v3 with: - node-version: '18' + node-version: '20' - name: Install dependencies run: | From c6635f95de77157c6fa97545bd9b6a215ae56bab Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 7 May 2025 19:52:35 +0000 Subject: [PATCH 25/29] feat(api): update via SDK Studio --- .stats.yml | 8 +- api.md | 23 +- src/index.ts | 29 ++ src/resources/agents/agents.ts | 240 +++++++++- src/resources/agents/evaluate/evaluate.ts | 11 + src/resources/agents/evaluate/jobs.ts | 31 +- src/resources/agents/index.ts | 2 + src/resources/agents/query.ts | 47 +- src/resources/agents/tune/tune.ts | 51 ++ src/resources/datastores/datastores.ts | 33 ++ src/resources/datastores/documents.ts | 24 +- src/resources/datastores/index.ts | 1 + src/resources/generate.ts | 11 +- src/resources/index.ts | 13 + src/resources/parse.ts | 443 ++++++++++++++++++ src/resources/rerank.ts | 42 +- src/resources/users.ts | 132 ++---- tests/api-resources/agents/agents.test.ts | 35 +- .../agents/evaluate/evaluate.test.ts | 2 + tests/api-resources/agents/query.test.ts | 6 +- tests/api-resources/agents/tune/tune.test.ts | 9 + .../datastores/datastores.test.ts | 18 + .../datastores/documents.test.ts | 2 +- tests/api-resources/parse.test.ts | 108 +++++ tests/api-resources/users.test.ts | 20 +- 25 files changed, 1186 insertions(+), 155 deletions(-) create mode 100644 src/resources/parse.ts create mode 100644 tests/api-resources/parse.test.ts diff --git a/.stats.yml b/.stats.yml index c1b7080..ce51d3c 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 46 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-c978f14e96782dd2ca8a8dbfdd822941e52df70306cb99d93218c61363460f03.yml -openapi_spec_hash: 57aec46adc855c43bcd349940fbc247d -config_hash: 47781a5702123e4592e019351ce8cf45 +configured_endpoints: 52 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-1ec5b5b63e3fe6f99de6eae32dc51fde7c2bc960703b43c99e58fdfe4e3b4c21.yml +openapi_spec_hash: e75e261b83ee7c3d524a3c28c949d227 +config_hash: f0c8dfba598e8ad313dc6b95c7b34df6 diff --git a/api.md b/api.md index c7a7a59..7737695 100644 --- a/api.md +++ b/api.md @@ -7,6 +7,7 @@ Types: - DatastoreMetadata - ListDatastoresResponse - DatastoreDeleteResponse +- DatastoreResetResponse Methods: @@ -14,6 +15,7 @@ Methods: - client.datastores.list({ ...params }) -> DatastoresDatastoresPage - client.datastores.delete(datastoreId) -> unknown - client.datastores.metadata(datastoreId) -> DatastoreMetadata +- client.datastores.reset(datastoreId) -> unknown ## Documents @@ -43,6 +45,8 @@ Types: - ListAgentsResponse - AgentUpdateResponse - AgentDeleteResponse +- AgentMetadataResponse +- AgentResetResponse Methods: @@ -50,7 +54,8 @@ Methods: - client.agents.update(agentId, { ...params }) -> unknown - client.agents.list({ ...params }) -> AgentsPage - client.agents.delete(agentId) -> unknown -- client.agents.metadata(agentId) -> AgentMetadata +- client.agents.metadata(agentId) -> AgentMetadataResponse +- client.agents.reset(agentId) -> unknown ## Query @@ -210,3 +215,19 @@ Types: Methods: - client.generate.create({ ...params }) -> GenerateCreateResponse + +# Parse + +Types: + +- ParseCreateResponse +- ParseJobResultsResponse +- ParseJobStatusResponse +- ParseJobsResponse + +Methods: + +- client.parse.create({ ...params }) -> ParseCreateResponse +- client.parse.jobResults(jobId, { ...params }) -> ParseJobResultsResponse +- client.parse.jobStatus(jobId) -> ParseJobStatusResponse +- client.parse.jobs({ ...params }) -> ParseJobsResponse diff --git a/src/index.ts b/src/index.ts index 03a0813..623d0ab 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,6 +19,16 @@ import * as Uploads from './uploads'; import * as API from './resources/index'; import { Generate, GenerateCreateParams, GenerateCreateResponse } from './resources/generate'; import { LMUnit, LMUnitCreateParams, LMUnitCreateResponse } from './resources/lmunit'; +import { + Parse, + ParseCreateParams, + ParseCreateResponse, + ParseJobResultsParams, + ParseJobResultsResponse, + ParseJobStatusResponse, + ParseJobsParams, + ParseJobsResponse, +} from './resources/parse'; import { Rerank, RerankCreateParams, RerankCreateResponse } from './resources/rerank'; import { InviteUsersResponse, @@ -39,6 +49,8 @@ import { AgentDeleteResponse, AgentListParams, AgentMetadata, + AgentMetadataResponse, + AgentResetResponse, AgentUpdateParams, AgentUpdateResponse, Agents, @@ -53,6 +65,7 @@ import { DatastoreDeleteResponse, DatastoreListParams, DatastoreMetadata, + DatastoreResetResponse, Datastores, DatastoresDatastoresPage, ListDatastoresResponse, @@ -177,6 +190,7 @@ export class ContextualAI extends Core.APIClient { lmUnit: API.LMUnit = new API.LMUnit(this); rerank: API.Rerank = new API.Rerank(this); generate: API.Generate = new API.Generate(this); + parse: API.Parse = new API.Parse(this); protected override defaultQuery(): Core.DefaultQuery | undefined { return this._options.defaultQuery; @@ -227,6 +241,7 @@ ContextualAI.ListUsersResponseUsersUsersPage = ListUsersResponseUsersUsersPage; ContextualAI.LMUnit = LMUnit; ContextualAI.Rerank = Rerank; ContextualAI.Generate = Generate; +ContextualAI.Parse = Parse; export declare namespace ContextualAI { export type RequestOptions = Core.RequestOptions; @@ -255,6 +270,7 @@ export declare namespace ContextualAI { type DatastoreMetadata as DatastoreMetadata, type ListDatastoresResponse as ListDatastoresResponse, type DatastoreDeleteResponse as DatastoreDeleteResponse, + type DatastoreResetResponse as DatastoreResetResponse, DatastoresDatastoresPage as DatastoresDatastoresPage, type DatastoreCreateParams as DatastoreCreateParams, type DatastoreListParams as DatastoreListParams, @@ -268,6 +284,8 @@ export declare namespace ContextualAI { type ListAgentsResponse as ListAgentsResponse, type AgentUpdateResponse as AgentUpdateResponse, type AgentDeleteResponse as AgentDeleteResponse, + type AgentMetadataResponse as AgentMetadataResponse, + type AgentResetResponse as AgentResetResponse, AgentsPage as AgentsPage, type AgentCreateParams as AgentCreateParams, type AgentUpdateParams as AgentUpdateParams, @@ -305,6 +323,17 @@ export declare namespace ContextualAI { type GenerateCreateResponse as GenerateCreateResponse, type GenerateCreateParams as GenerateCreateParams, }; + + export { + Parse as Parse, + type ParseCreateResponse as ParseCreateResponse, + type ParseJobResultsResponse as ParseJobResultsResponse, + type ParseJobStatusResponse as ParseJobStatusResponse, + type ParseJobsResponse as ParseJobsResponse, + type ParseCreateParams as ParseCreateParams, + type ParseJobResultsParams as ParseJobResultsParams, + type ParseJobsParams as ParseJobsParams, + }; } export { toFile, fileFromPath } from './uploads'; diff --git a/src/resources/agents/agents.ts b/src/resources/agents/agents.ts index fa39882..82ff57d 100644 --- a/src/resources/agents/agents.ts +++ b/src/resources/agents/agents.ts @@ -41,6 +41,11 @@ export class Agents extends APIResource { * If no `datastore_id` is provided in the configuration, this API automatically * creates an empty `Datastore` and configures the `Agent` to use the newly created * `Datastore`. + * + * > Note that self-serve users are currently required to create agents through our + * > UI. Otherwise, they will receive the following message: "This endpoint is + * > disabled as you need to go through checkout. Please use the UI to make this + * > request." */ create(body: AgentCreateParams, options?: Core.RequestOptions): Core.APIPromise { return this._client.post('/agents', { body, ...options }); @@ -84,9 +89,16 @@ export class Agents extends APIResource { /** * Get metadata and configuration of a given `Agent`. */ - metadata(agentId: string, options?: Core.RequestOptions): Core.APIPromise { + metadata(agentId: string, options?: Core.RequestOptions): Core.APIPromise { return this._client.get(`/agents/${agentId}/metadata`, options); } + + /** + * Reset a given `Agent` to default configuration. + */ + reset(agentId: string, options?: Core.RequestOptions): Core.APIPromise { + return this._client.put(`/agents/${agentId}/reset`, options); + } } export class AgentsPage extends Page {} @@ -127,6 +139,11 @@ export interface AgentMetadata { */ agent_configs?: AgentMetadata.AgentConfigs; + /** + * Total API request counts for the agent. + */ + agent_usages?: AgentMetadata.AgentUsages | null; + /** * Description of the agent */ @@ -145,6 +162,12 @@ export interface AgentMetadata { */ llm_model_id?: string; + /** + * Instructions on how the agent should respond when there are no relevant + * retrievals that can be used to answer a query. + */ + no_retrieval_system_prompt?: string; + /** * These queries will show up as suggestions in the Contextual UI when users load * the agent. We recommend including common queries that users will ask, as well as @@ -191,6 +214,25 @@ export namespace AgentMetadata { * Parameters that affect filtering and reranking of retrieved knowledge */ export interface FilterAndRerankConfig { + /** + * Instructions that the reranker references when ranking retrievals. Note that we + * do not guarantee that the reranker will follow these instructions exactly. + * Examples: "Prioritize internal sales documents over market analysis reports. + * More recent documents should be weighted higher. Enterprise portal content + * supersedes distributor communications." and "Emphasize forecasts from top-tier + * investment banks. Recent analysis should take precedence. Disregard aggregator + * sites and favor detailed research notes over news summaries." + */ + rerank_instructions?: string; + + /** + * If the reranker relevance score associated with a chunk is below this threshold, + * then the chunk will be filtered out and not used for generation. Scores are + * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 + * to disable the reranker score filtering. + */ + reranker_score_filter_threshold?: number; + /** * The number of highest ranked chunks after reranking to be used */ @@ -201,6 +243,15 @@ export namespace AgentMetadata { * Parameters that affect response generation */ export interface GenerateResponseConfig { + /** + * Flag to indicate whether the model should avoid providing additional commentary + * in responses. Commentary is conversational in nature and does not contain + * verifiable claims; therefore, commentary is not strictly grounded in available + * context. However, commentary may provide useful context which improves the + * helpfulness of responses. + */ + avoid_commentary?: boolean; + /** * This parameter controls generation of groundedness scores. */ @@ -254,6 +305,12 @@ export namespace AgentMetadata { * Enables reranking of retrieved chunks */ enable_rerank?: boolean; + + /** + * Enables checking if retrieval is needed for the query. This feature is currently + * experimental and will be improved. + */ + should_check_retrieval_need?: boolean; } /** @@ -261,12 +318,14 @@ export namespace AgentMetadata { */ export interface RetrievalConfig { /** - * The weight of lexical search during retrieval + * The weight of lexical search during retrieval. Must sum to 1 with + * semantic_alpha. */ lexical_alpha?: number; /** - * The weight of semantic search during retrieval + * The weight of semantic search during retrieval. Must sum to 1 with + * lexical_alpha. */ semantic_alpha?: number; @@ -276,6 +335,26 @@ export namespace AgentMetadata { top_k_retrieved_chunks?: number; } } + + /** + * Total API request counts for the agent. + */ + export interface AgentUsages { + /** + * eval request count + */ + eval: number; + + /** + * query request count + */ + query: number; + + /** + * tune request count + */ + tune: number; + } } /** @@ -317,6 +396,67 @@ export type AgentUpdateResponse = unknown; export type AgentDeleteResponse = unknown; +/** + * Response to GET Agent request + */ +export type AgentMetadataResponse = AgentMetadata | AgentMetadataResponse.GetTwilightAgentResponse; + +export namespace AgentMetadataResponse { + /** + * Response to GET Agent request + */ + export interface GetTwilightAgentResponse { + /** + * The IDs of the datastore(s) associated with the agent + */ + datastore_ids: Array; + + /** + * Name of the agent + */ + name: string; + + /** + * The following advanced parameters are experimental and subject to change. + */ + agent_configs?: unknown; + + /** + * Total API request counts for the agent. + */ + agent_usages?: GetTwilightAgentResponse.AgentUsages | null; + + /** + * Description of the agent + */ + description?: string; + } + + export namespace GetTwilightAgentResponse { + /** + * Total API request counts for the agent. + */ + export interface AgentUsages { + /** + * eval request count + */ + eval: number; + + /** + * query request count + */ + query: number; + + /** + * tune request count + */ + tune: number; + } + } +} + +export type AgentResetResponse = unknown; + export interface AgentCreateParams { /** * Name of the agent @@ -344,6 +484,12 @@ export interface AgentCreateParams { */ filter_prompt?: string; + /** + * Instructions on how the agent should respond when there are no relevant + * retrievals that can be used to answer a query. + */ + no_retrieval_system_prompt?: string; + /** * These queries will show up as suggestions in the Contextual UI when users load * the agent. We recommend including common queries that users will ask, as well as @@ -390,6 +536,25 @@ export namespace AgentCreateParams { * Parameters that affect filtering and reranking of retrieved knowledge */ export interface FilterAndRerankConfig { + /** + * Instructions that the reranker references when ranking retrievals. Note that we + * do not guarantee that the reranker will follow these instructions exactly. + * Examples: "Prioritize internal sales documents over market analysis reports. + * More recent documents should be weighted higher. Enterprise portal content + * supersedes distributor communications." and "Emphasize forecasts from top-tier + * investment banks. Recent analysis should take precedence. Disregard aggregator + * sites and favor detailed research notes over news summaries." + */ + rerank_instructions?: string; + + /** + * If the reranker relevance score associated with a chunk is below this threshold, + * then the chunk will be filtered out and not used for generation. Scores are + * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 + * to disable the reranker score filtering. + */ + reranker_score_filter_threshold?: number; + /** * The number of highest ranked chunks after reranking to be used */ @@ -400,6 +565,15 @@ export namespace AgentCreateParams { * Parameters that affect response generation */ export interface GenerateResponseConfig { + /** + * Flag to indicate whether the model should avoid providing additional commentary + * in responses. Commentary is conversational in nature and does not contain + * verifiable claims; therefore, commentary is not strictly grounded in available + * context. However, commentary may provide useful context which improves the + * helpfulness of responses. + */ + avoid_commentary?: boolean; + /** * This parameter controls generation of groundedness scores. */ @@ -453,6 +627,12 @@ export namespace AgentCreateParams { * Enables reranking of retrieved chunks */ enable_rerank?: boolean; + + /** + * Enables checking if retrieval is needed for the query. This feature is currently + * experimental and will be improved. + */ + should_check_retrieval_need?: boolean; } /** @@ -460,12 +640,14 @@ export namespace AgentCreateParams { */ export interface RetrievalConfig { /** - * The weight of lexical search during retrieval + * The weight of lexical search during retrieval. Must sum to 1 with + * semantic_alpha. */ lexical_alpha?: number; /** - * The weight of semantic search during retrieval + * The weight of semantic search during retrieval. Must sum to 1 with + * lexical_alpha. */ semantic_alpha?: number; @@ -501,6 +683,12 @@ export interface AgentUpdateParams { */ llm_model_id?: string; + /** + * Instructions on how the agent should respond when there are no relevant + * retrievals that can be used to answer a query. + */ + no_retrieval_system_prompt?: string; + /** * These queries will show up as suggestions in the Contextual UI when users load * the agent. We recommend including common queries that users will ask, as well as @@ -547,6 +735,25 @@ export namespace AgentUpdateParams { * Parameters that affect filtering and reranking of retrieved knowledge */ export interface FilterAndRerankConfig { + /** + * Instructions that the reranker references when ranking retrievals. Note that we + * do not guarantee that the reranker will follow these instructions exactly. + * Examples: "Prioritize internal sales documents over market analysis reports. + * More recent documents should be weighted higher. Enterprise portal content + * supersedes distributor communications." and "Emphasize forecasts from top-tier + * investment banks. Recent analysis should take precedence. Disregard aggregator + * sites and favor detailed research notes over news summaries." + */ + rerank_instructions?: string; + + /** + * If the reranker relevance score associated with a chunk is below this threshold, + * then the chunk will be filtered out and not used for generation. Scores are + * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 + * to disable the reranker score filtering. + */ + reranker_score_filter_threshold?: number; + /** * The number of highest ranked chunks after reranking to be used */ @@ -557,6 +764,15 @@ export namespace AgentUpdateParams { * Parameters that affect response generation */ export interface GenerateResponseConfig { + /** + * Flag to indicate whether the model should avoid providing additional commentary + * in responses. Commentary is conversational in nature and does not contain + * verifiable claims; therefore, commentary is not strictly grounded in available + * context. However, commentary may provide useful context which improves the + * helpfulness of responses. + */ + avoid_commentary?: boolean; + /** * This parameter controls generation of groundedness scores. */ @@ -610,6 +826,12 @@ export namespace AgentUpdateParams { * Enables reranking of retrieved chunks */ enable_rerank?: boolean; + + /** + * Enables checking if retrieval is needed for the query. This feature is currently + * experimental and will be improved. + */ + should_check_retrieval_need?: boolean; } /** @@ -617,12 +839,14 @@ export namespace AgentUpdateParams { */ export interface RetrievalConfig { /** - * The weight of lexical search during retrieval + * The weight of lexical search during retrieval. Must sum to 1 with + * semantic_alpha. */ lexical_alpha?: number; /** - * The weight of semantic search during retrieval + * The weight of semantic search during retrieval. Must sum to 1 with + * lexical_alpha. */ semantic_alpha?: number; @@ -650,6 +874,8 @@ export declare namespace Agents { type ListAgentsResponse as ListAgentsResponse, type AgentUpdateResponse as AgentUpdateResponse, type AgentDeleteResponse as AgentDeleteResponse, + type AgentMetadataResponse as AgentMetadataResponse, + type AgentResetResponse as AgentResetResponse, AgentsPage as AgentsPage, type AgentCreateParams as AgentCreateParams, type AgentUpdateParams as AgentUpdateParams, diff --git a/src/resources/agents/evaluate/evaluate.ts b/src/resources/agents/evaluate/evaluate.ts index efb2917..b1c105d 100644 --- a/src/resources/agents/evaluate/evaluate.ts +++ b/src/resources/agents/evaluate/evaluate.ts @@ -73,6 +73,17 @@ export interface EvaluateCreateParams { * ID of the model to evaluate. Uses the default model if not specified. */ llm_model_id?: string; + + /** + * User notes for the evaluation job. + */ + notes?: string; + + /** + * Override the configuration for the query. This will override the configuration + * for the agent during evaluation. + */ + override_configuration?: string; } Evaluate.Jobs = Jobs; diff --git a/src/resources/agents/evaluate/jobs.ts b/src/resources/agents/evaluate/jobs.ts index 5432d84..38a4978 100644 --- a/src/resources/agents/evaluate/jobs.ts +++ b/src/resources/agents/evaluate/jobs.ts @@ -60,7 +60,18 @@ export interface EvaluationJobMetadata { /** * Status of the evaluation round */ - status: 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'; + status: + | 'pending' + | 'processing' + | 'retrying' + | 'completed' + | 'failed' + | 'cancelled' + | 'failed_to_provision' + | 'generating_data' + | 'training_in_progress' + | 'failed_to_generate_data' + | 'provisioning'; } export namespace EvaluationJobMetadata { @@ -119,7 +130,18 @@ export namespace ListEvaluationJobsResponse { /** * Status of the evaluation round */ - status: 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'; + status: + | 'pending' + | 'processing' + | 'retrying' + | 'completed' + | 'failed' + | 'cancelled' + | 'failed_to_provision' + | 'generating_data' + | 'training_in_progress' + | 'failed_to_generate_data' + | 'provisioning'; /** * Email of the user who launched the evaluation round @@ -131,6 +153,11 @@ export namespace ListEvaluationJobsResponse { */ finished_at?: string; + /** + * User notes for the evaluation job + */ + notes?: string; + /** * Number of predictions that failed during the evaluation round */ diff --git a/src/resources/agents/index.ts b/src/resources/agents/index.ts index 63cbb88..729a05e 100644 --- a/src/resources/agents/index.ts +++ b/src/resources/agents/index.ts @@ -9,6 +9,8 @@ export { type ListAgentsResponse, type AgentUpdateResponse, type AgentDeleteResponse, + type AgentMetadataResponse, + type AgentResetResponse, type AgentCreateParams, type AgentUpdateParams, type AgentListParams, diff --git a/src/resources/agents/query.ts b/src/resources/agents/query.ts index 1abad48..b3a383e 100644 --- a/src/resources/agents/query.ts +++ b/src/resources/agents/query.ts @@ -160,6 +160,11 @@ export namespace QueryResponse { */ page?: number; + /** + * Score of the retrieval, if applicable + */ + score?: number; + /** * URL of the source content, if applicable */ @@ -226,11 +231,13 @@ export interface RetrievalInfoResponse { /** * List of content metadatas. */ - content_metadatas?: Array; + content_metadatas?: Array< + RetrievalInfoResponse.UnstructuredContentMetadata | RetrievalInfoResponse.StructuredContentMetadata + >; } export namespace RetrievalInfoResponse { - export interface ContentMetadata { + export interface UnstructuredContentMetadata { /** * Id of the content. */ @@ -280,6 +287,22 @@ export namespace RetrievalInfoResponse { * Y coordinate of the bottom right corner on the bounding box. */ y1: number; + + content_type?: 'unstructured'; + } + + export interface StructuredContentMetadata { + /** + * Id of the content. + */ + content_id: string; + + /** + * Text of the content. + */ + content_text: unknown; + + content_type?: 'structured'; } } @@ -382,6 +405,11 @@ export interface QueryCreateParams { * Body param: Set to `true` to receive a streamed response */ stream?: boolean; + + /** + * Body param: Custom output structure format. + */ + structured_output?: QueryCreateParams.StructuredOutput; } export namespace QueryCreateParams { @@ -436,6 +464,21 @@ export namespace QueryCreateParams { */ value?: string | number | boolean | Array | null; } + + /** + * Custom output structure format. + */ + export interface StructuredOutput { + /** + * The output json structure. + */ + json_schema: unknown; + + /** + * Type of the structured output. The default is JSON + */ + type?: 'JSON'; + } } export interface QueryFeedbackParams { diff --git a/src/resources/agents/tune/tune.ts b/src/resources/agents/tune/tune.ts index 78cf52b..af7846f 100644 --- a/src/resources/agents/tune/tune.ts +++ b/src/resources/agents/tune/tune.ts @@ -71,6 +71,57 @@ export interface CreateTuneResponse { } export interface TuneCreateParams { + /** + * Controls how quickly the model adapts to the training data. Must be greater than + * 0 and less than or equal to 0.1. + */ + 'hyperparams[learning_rate]'?: number; + + /** + * Scaling factor that controls the magnitude of LoRA updates. Higher values lead + * to stronger adaptation effects. The effective learning strength is determined by + * the ratio of lora_alpha/lora_rank. Must be one of: 8, 16, 32, 64 or 128 + */ + 'hyperparams[lora_alpha]'?: 8 | 16 | 32 | 64 | 128; + + /** + * LoRA dropout randomly disables connections during training to prevent + * overfitting and improve generalization when fine-tuning language models with + * Low-Rank Adaptation. Must be between 0 and 1 (exclusive). + */ + 'hyperparams[lora_dropout]'?: number; + + /** + * Controls the capacity of the LoRA adapters. Must be one of: 8, 16, 32, or 64. + */ + 'hyperparams[lora_rank]'?: 8 | 16 | 32 | 64; + + /** + * Number of complete passes through the training dataset. + */ + 'hyperparams[num_epochs]'?: number; + + /** + * Fraction of training steps used for learning rate warmup. Must be between 0 and + * 1 (exclusive). + */ + 'hyperparams[warmup_ratio]'?: number; + + /** + * Optional. Metadata file to use for synthetic data pipeline. + */ + metadata_file?: Core.Uploadable; + + /** + * Runs the SDP pipeline only if set to True. + */ + sdp_only?: boolean; + + /** + * Optional. Whether to generate synthetic data for training + */ + synth_data?: boolean; + /** * Optional. `Dataset` to use for testing model checkpoints, created through the * `/datasets/evaluate` API. diff --git a/src/resources/datastores/datastores.ts b/src/resources/datastores/datastores.ts index ff21ce9..8610c46 100644 --- a/src/resources/datastores/datastores.ts +++ b/src/resources/datastores/datastores.ts @@ -32,6 +32,11 @@ export class Datastores extends APIResource { * relevant data. This flexible many-to-many relationship allows `Agents` to draw * from multiple sources of information. This linkage of `Datastore` to `Agent` is * done through the `Create Agent` or `Edit Agent` APIs. + * + * > Note that self-serve users are currently required to create datastores through + * > our UI. Otherwise, they will receive the following message: "This endpoint is + * > disabled as you need to go through checkout. Please use the UI to make this + * > request." */ create( body: DatastoreCreateParams, @@ -80,6 +85,14 @@ export class Datastores extends APIResource { metadata(datastoreId: string, options?: Core.RequestOptions): Core.APIPromise { return this._client.get(`/datastores/${datastoreId}/metadata`, options); } + + /** + * Reset the give `Datastore`. This operation is irreversible and it deletes all + * the documents associated with the datastore. + */ + reset(datastoreId: string, options?: Core.RequestOptions): Core.APIPromise { + return this._client.put(`/datastores/${datastoreId}/reset`, options); + } } export class DatastoresDatastoresPage extends DatastoresPage {} @@ -126,6 +139,23 @@ export interface DatastoreMetadata { * Name of the datastore */ name: string; + + /** + * Datastore usage + */ + datastore_usages?: DatastoreMetadata.DatastoreUsages; +} + +export namespace DatastoreMetadata { + /** + * Datastore usage + */ + export interface DatastoreUsages { + /** + * Actual size of the datastore in GB + */ + size_gb: number; + } } export interface ListDatastoresResponse { @@ -148,6 +178,8 @@ export interface ListDatastoresResponse { export type DatastoreDeleteResponse = unknown; +export type DatastoreResetResponse = unknown; + export interface DatastoreCreateParams { /** * Name of the datastore @@ -174,6 +206,7 @@ export declare namespace Datastores { type DatastoreMetadata as DatastoreMetadata, type ListDatastoresResponse as ListDatastoresResponse, type DatastoreDeleteResponse as DatastoreDeleteResponse, + type DatastoreResetResponse as DatastoreResetResponse, DatastoresDatastoresPage as DatastoresDatastoresPage, type DatastoreCreateParams as DatastoreCreateParams, type DatastoreListParams as DatastoreListParams, diff --git a/src/resources/datastores/documents.ts b/src/resources/datastores/documents.ts index 9ade45c..f1c7b2a 100644 --- a/src/resources/datastores/documents.ts +++ b/src/resources/datastores/documents.ts @@ -228,7 +228,19 @@ export interface DocumentListParams extends DocumentsPageParams { * Filters documents whose ingestion job status matches (one of) the provided * status(es). */ - ingestion_job_status?: Array<'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'>; + ingestion_job_status?: Array< + | 'pending' + | 'processing' + | 'retrying' + | 'completed' + | 'failed' + | 'cancelled' + | 'failed_to_provision' + | 'generating_data' + | 'training_in_progress' + | 'failed_to_generate_data' + | 'provisioning' + >; /** * Filters documents uploaded at or after specified timestamp. @@ -258,13 +270,11 @@ export interface DocumentIngestParams { * **Example Metadata JSON:** * * ```json - * { - * "metadata": { + * metadata = { * "custom_metadata": { - * "customKey1": "value3", - * "_filterKey": "filterValue3" - * } - * } + * "field1": "value1", + * "field2": "value2" + * } * } * ``` */ diff --git a/src/resources/datastores/index.ts b/src/resources/datastores/index.ts index 4f96cde..c341e07 100644 --- a/src/resources/datastores/index.ts +++ b/src/resources/datastores/index.ts @@ -8,6 +8,7 @@ export { type DatastoreMetadata, type ListDatastoresResponse, type DatastoreDeleteResponse, + type DatastoreResetResponse, type DatastoreCreateParams, type DatastoreListParams, } from './datastores'; diff --git a/src/resources/generate.ts b/src/resources/generate.ts index 74b9252..71ddabd 100644 --- a/src/resources/generate.ts +++ b/src/resources/generate.ts @@ -10,9 +10,11 @@ export class Generate extends APIResource { * parametric knowledge to reduce hallucinations in Retrieval-Augmented Generation * and agentic use cases. * - * The total request cannot exceed 32,000 tokens. See more details and code - * examples in our - * [our blog post](https://contextual.ai/blog/introducing-grounded-language-model/). + * The total request cannot exceed 32,000 tokens. + * + * See our + * [blog post](https://contextual.ai/blog/introducing-grounded-language-model/) and + * [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb). * Email [glm-feedback@contextual.ai](mailto:glm-feedback@contextual.ai) with any * feedback or questions. */ @@ -44,8 +46,7 @@ export interface GenerateCreateParams { messages: Array; /** - * The version of the Contextual's GLM to use. Currently, we just have - * "ctxl-rerank-en-v1-instruct". + * The version of the Contextual's GLM to use. Currently, we just have "v1". */ model: string; diff --git a/src/resources/index.ts b/src/resources/index.ts index e7428ea..bd0f200 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -9,6 +9,8 @@ export { type ListAgentsResponse, type AgentUpdateResponse, type AgentDeleteResponse, + type AgentMetadataResponse, + type AgentResetResponse, type AgentCreateParams, type AgentUpdateParams, type AgentListParams, @@ -21,6 +23,7 @@ export { type DatastoreMetadata, type ListDatastoresResponse, type DatastoreDeleteResponse, + type DatastoreResetResponse, type DatastoreCreateParams, type DatastoreListParams, } from './datastores/datastores'; @@ -39,4 +42,14 @@ export { type UserDeactivateParams, type UserInviteParams, } from './users'; +export { + Parse, + type ParseCreateResponse, + type ParseJobResultsResponse, + type ParseJobStatusResponse, + type ParseJobsResponse, + type ParseCreateParams, + type ParseJobResultsParams, + type ParseJobsParams, +} from './parse'; export { Rerank, type RerankCreateResponse, type RerankCreateParams } from './rerank'; diff --git a/src/resources/parse.ts b/src/resources/parse.ts new file mode 100644 index 0000000..d1c3bd9 --- /dev/null +++ b/src/resources/parse.ts @@ -0,0 +1,443 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../resource'; +import { isRequestOptions } from '../core'; +import * as Core from '../core'; + +export class Parse extends APIResource { + /** + * Parse a file into a structured Markdown representation. The file size must be + * less than 100MB and the number of pages must be less than 400. + * + * Email [parse-feedback@contextual.ai](mailto:parse-feedback@contextual.ai) with + * any feedback or questions. + */ + create(body: ParseCreateParams, options?: Core.RequestOptions): Core.APIPromise { + return this._client.post('/parse', Core.multipartFormRequestOptions({ body, ...options })); + } + + /** + * Get the results of a parse job. + * + * Parse job results are retained for up to 30 days after job creation. Fetching + * results for a parse job that is older than 30 days will return a 404 error. + */ + jobResults( + jobId: string, + query?: ParseJobResultsParams, + options?: Core.RequestOptions, + ): Core.APIPromise; + jobResults(jobId: string, options?: Core.RequestOptions): Core.APIPromise; + jobResults( + jobId: string, + query: ParseJobResultsParams | Core.RequestOptions = {}, + options?: Core.RequestOptions, + ): Core.APIPromise { + if (isRequestOptions(query)) { + return this.jobResults(jobId, {}, query); + } + return this._client.get(`/parse/jobs/${jobId}/results`, { query, ...options }); + } + + /** + * Get the status of a parse job. + * + * Parse job results are retained for up to 30 days after job creation. Fetching a + * status for a parse job that is older than 30 days will return a 404 error. + */ + jobStatus(jobId: string, options?: Core.RequestOptions): Core.APIPromise { + return this._client.get(`/parse/jobs/${jobId}/status`, options); + } + + /** + * Get list of parse jobs, sorted from most recent to oldest. + * + * Returns all jobs from the last 30 days, or since the optional `uploaded_after` + * timestamp. + */ + jobs(query?: ParseJobsParams, options?: Core.RequestOptions): Core.APIPromise; + jobs(options?: Core.RequestOptions): Core.APIPromise; + jobs( + query: ParseJobsParams | Core.RequestOptions = {}, + options?: Core.RequestOptions, + ): Core.APIPromise { + if (isRequestOptions(query)) { + return this.jobs({}, query); + } + return this._client.get('/parse/jobs', { query, ...options }); + } +} + +/** + * /parse response object. + */ +export interface ParseCreateResponse { + /** + * Unique ID of the parse job + */ + job_id: string; +} + +/** + * /parse results reponse object. + */ +export interface ParseJobResultsResponse { + /** + * The name of the file that was uploaded for parsing + */ + file_name: string; + + /** + * The current status of the parse job + */ + status: 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'; + + /** + * The parsed, structured Markdown of the input file. Only present if + * `markdown-document` was among the requested output types. + */ + markdown_document?: string; + + /** + * Per-page parse results, containing per-page Markdown (if `markdown-per-page` was + * requested) and/or per-page `ParsedBlock`s (if `blocks-per-page` was requested). + */ + pages?: Array; + + /** + * The table of contents representing the document's heading hierarchy. Only + * present if `enable_document_hierarchy` was set to true in the parse request. + */ + table_of_contents?: ParseJobResultsResponse.TableOfContents; +} + +export namespace ParseJobResultsResponse { + /** + * Per-page parse results. + */ + export interface Page { + /** + * The index of the parsed page (zero-indexed) + */ + index: number; + + /** + * The parsed, structured blocks of this page. Present if `blocks-per-page` was + * among the requested output types. + */ + blocks?: Array; + + /** + * The parsed, structured Markdown of this page. Present if `markdown-per-page` was + * among the requested output types. + */ + markdown?: string; + } + + export namespace Page { + /** + * One logical block of content from a parsed page. + */ + export interface Block { + /** + * Unique ID of the block + */ + id: string; + + /** + * The normalized bounding box of the block, as relative percentages of the page + * width and height + */ + bounding_box: Block.BoundingBox; + + /** + * The Markdown representation of the block + */ + markdown: string; + + /** + * The type of the block + */ + type: 'heading' | 'text' | 'table' | 'figure'; + + /** + * The confidence level of this block categorized as 'low', 'medium', or 'high'. + * Only available for blocks of type 'table' currently. + */ + confidence_level?: 'low' | 'medium' | 'high'; + + /** + * The level of the block in the document hierarchy, starting at 0 for the + * root-level title block. Only present if `enable_document_hierarchy` was set to + * true in the request. + */ + hierarchy_level?: number; + + /** + * The page (0-indexed) that this block belongs to. Only set for heading blocks + * that are returned in the table of contents. + */ + page_index?: number; + + /** + * The IDs of the parent in the document hierarchy, sorted from root-level to + * bottom. For root-level heading blocks, this will be an empty list. Only present + * if `enable_document_hierarchy` was set to true in the request. + */ + parent_ids?: Array; + } + + export namespace Block { + /** + * The normalized bounding box of the block, as relative percentages of the page + * width and height + */ + export interface BoundingBox { + /** + * The x-coordinate of the top-left corner of the bounding box + */ + x0: number; + + /** + * The x-coordinate of the bottom-right corner of the bounding box + */ + x1: number; + + /** + * The y-coordinate of the top-left corner of the bounding box + */ + y0: number; + + /** + * The y-coordinate of the bottom-right corner of the bounding box + */ + y1: number; + } + } + } + + /** + * The table of contents representing the document's heading hierarchy. Only + * present if `enable_document_hierarchy` was set to true in the parse request. + */ + export interface TableOfContents { + /** + * Heading blocks that define the hierarchy of the document + */ + blocks?: Array; + + /** + * Markdown representation of the table of contents that can be pre-pended to the + * markdown document. + */ + markdown?: string; + } + + export namespace TableOfContents { + /** + * One logical block of content from a parsed page. + */ + export interface Block { + /** + * Unique ID of the block + */ + id: string; + + /** + * The normalized bounding box of the block, as relative percentages of the page + * width and height + */ + bounding_box: Block.BoundingBox; + + /** + * The Markdown representation of the block + */ + markdown: string; + + /** + * The type of the block + */ + type: 'heading' | 'text' | 'table' | 'figure'; + + /** + * The confidence level of this block categorized as 'low', 'medium', or 'high'. + * Only available for blocks of type 'table' currently. + */ + confidence_level?: 'low' | 'medium' | 'high'; + + /** + * The level of the block in the document hierarchy, starting at 0 for the + * root-level title block. Only present if `enable_document_hierarchy` was set to + * true in the request. + */ + hierarchy_level?: number; + + /** + * The page (0-indexed) that this block belongs to. Only set for heading blocks + * that are returned in the table of contents. + */ + page_index?: number; + + /** + * The IDs of the parent in the document hierarchy, sorted from root-level to + * bottom. For root-level heading blocks, this will be an empty list. Only present + * if `enable_document_hierarchy` was set to true in the request. + */ + parent_ids?: Array; + } + + export namespace Block { + /** + * The normalized bounding box of the block, as relative percentages of the page + * width and height + */ + export interface BoundingBox { + /** + * The x-coordinate of the top-left corner of the bounding box + */ + x0: number; + + /** + * The x-coordinate of the bottom-right corner of the bounding box + */ + x1: number; + + /** + * The y-coordinate of the top-left corner of the bounding box + */ + y0: number; + + /** + * The y-coordinate of the bottom-right corner of the bounding box + */ + y1: number; + } + } + } +} + +/** + * /parse status reponse object. + */ +export interface ParseJobStatusResponse { + /** + * The name of the file that was uploaded for parsing + */ + file_name: string; + + /** + * The current status of the parse job + */ + status: 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'; +} + +/** + * /parse list jobs object. + */ +export interface ParseJobsResponse { + /** + * List of parse jobs + */ + jobs: Array; + + /** + * Total number of parse jobs + */ + total_jobs: number; +} + +export namespace ParseJobsResponse { + export interface Job { + /** + * Unique ID of the parse job + */ + id: string; + + /** + * The name of the file that was uploaded for parsing + */ + file_name: string; + + /** + * The current status of the parse job + */ + status: 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled'; + } +} + +export interface ParseCreateParams { + /** + * The file to be parsed. The file type must be PDF, DOC / DOCX, PPT / PPTX. + */ + raw_file: Core.Uploadable; + + /** + * Controls parsing heading levels (e.g. H1, H2, H3) at higher quality. Adds a + * table of contents to the output with the structure of the entire parsed + * document. Not permitted in 'basic' parsing_mode, or if page_range is not + * continuous and/or does not start from page zero. + */ + enable_document_hierarchy?: boolean; + + /** + * Controls whether tables are split into multiple tables by row with the headers + * propagated. Use for improving LLM comprehension of very large tables. Not + * permitted in 'basic' parsing_mode. + */ + enable_split_tables?: boolean; + + /** + * Controls how thorough figure captions are. 'concise' is short and minimizes + * chances of hallucinations. 'detailed' is more thorough and can include + * commentary. Not permitted in 'basic' parsing_mode. + */ + figure_caption_mode?: 'concise' | 'detailed'; + + /** + * Threshold number of table cells beyond which large tables are split if + * `enable_split_tables` is True. Not permitted in 'basic' parsing_mode. + */ + max_split_table_cells?: number; + + /** + * Optional string representing page range to be parsed. Format: comma-separated + * indexes (0-based) e.g. '0,1,2,5,6' or ranges (inclusive of both ends) e.g. + * '0-2,5,6' + */ + page_range?: string; + + /** + * The settings to use for parsing. 'basic' is for simple, text-only documents. + * 'standard' is for complex documents with images, complex hierarchy, and/or no + * natively encoded textual data (e.g. for scanned documents). + */ + parse_mode?: 'basic' | 'standard'; +} + +export interface ParseJobResultsParams { + /** + * The desired output format(s) of the parsed file. Must be `markdown-document`, + * `markdown-per-page`, and/or `blocks-per-page`. `markdown-document` parses the + * whole document into a single concatenated markdown output. `markdown-per-page` + * provides markdown output per page. `blocks-per-page` provides a structured JSON + * representation of the content blocks on each page, sorted by reading order. + * Specify multiple values to get multiple formats in the response. + */ + output_types?: Array<'markdown-document' | 'markdown-per-page' | 'blocks-per-page'>; +} + +export interface ParseJobsParams { + uploaded_after?: string; +} + +export declare namespace Parse { + export { + type ParseCreateResponse as ParseCreateResponse, + type ParseJobResultsResponse as ParseJobResultsResponse, + type ParseJobStatusResponse as ParseJobStatusResponse, + type ParseJobsResponse as ParseJobsResponse, + type ParseCreateParams as ParseCreateParams, + type ParseJobResultsParams as ParseJobResultsParams, + type ParseJobsParams as ParseJobsParams, + }; +} diff --git a/src/resources/rerank.ts b/src/resources/rerank.ts index f1661bc..ac2fc3d 100644 --- a/src/resources/rerank.ts +++ b/src/resources/rerank.ts @@ -5,12 +5,21 @@ import * as Core from '../core'; export class Rerank extends APIResource { /** - * Rank a list of documents according to their relevance to a query. + * Rank a list of documents according to their relevance to a query primarily and + * your custom instructions secondarily. We evaluated the model on instructions for + * recency, document type, source, and metadata, and it can generalize to other + * instructions as well. * - * The total request cannot exceed 400,000 tokens. The combined length of any - * document, instruction and the query must not exceed 4,000 tokens. Email - * [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any - * feedback or questions. + * The total request cannot exceed 400,000 tokens. The combined length of the + * query, instruction and any document with its metadata must not exceed 8,000 + * tokens. + * + * See our + * [blog post](https://contextual.ai/blog/introducing-instruction-following-reranker/) + * and + * [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). + * Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with + * any feedback or questions. */ create(body: RerankCreateParams, options?: Core.RequestOptions): Core.APIPromise { return this._client.post('/rerank', { body, ...options }); @@ -52,12 +61,14 @@ export namespace RerankCreateResponse { export interface RerankCreateParams { /** - * The texts to be reranked according to their relevance to the query + * The texts to be reranked according to their relevance to the query and the + * optional instruction */ documents: Array; /** - * The version of the reranker to use. Currently, we just have "v1". + * The version of the reranker to use. Currently, we just have + * "ctxl-rerank-en-v1-instruct". */ model: string; @@ -67,19 +78,20 @@ export interface RerankCreateParams { query: string; /** - * Instructions that the reranker references when ranking retrievals. Note that we - * do not guarantee that the reranker will follow these instructions exactly. - * Examples: "Prioritize internal sales documents over market analysis reports. - * More recent documents should be weighted higher. Enterprise portal content - * supersedes distributor communications." and "Emphasize forecasts from top-tier - * investment banks. Recent analysis should take precedence. Disregard aggregator - * sites and favor detailed research notes over news summaries." + * Instructions that the reranker references when ranking documents, after + * considering relevance. We evaluated the model on instructions for recency, + * document type, source, and metadata, and it can generalize to other instructions + * as well. For instructions related to recency and timeframe, specify the + * timeframe (e.g., instead of saying "this year") because the reranker doesn't + * know the current date. Example: "Prioritize internal sales documents over market + * analysis reports. More recent documents should be weighted higher. Enterprise + * portal content supersedes distributor communications." */ instruction?: string; /** * Metadata for documents being passed to the reranker. Must be the same length as - * the documents list. + * the documents list. If a document does not have metadata, add an empty string. */ metadata?: Array; diff --git a/src/resources/users.ts b/src/resources/users.ts index 3619c18..38ce661 100644 --- a/src/resources/users.ts +++ b/src/resources/users.ts @@ -93,43 +93,37 @@ export namespace ListUsersResponse { email: string; /** - * Flag indicating if the user is a tenant admin + * The effective roles of the user. */ - is_tenant_admin?: boolean; + effective_roles?: Array< + | 'VISITOR' + | 'AGENT_USER' + | 'CUSTOMER_INTERNAL_USER' + | 'CONTEXTUAL_STAFF_USER' + | 'CONTEXTUAL_EXTERNAL_STAFF_USER' + | 'CONTEXTUAL_INTERNAL_STAFF_USER' + | 'TENANT_ADMIN' + | 'SUPER_ADMIN' + >; /** - * Per agent level roles for the user. If a user is granted any role under `roles`, - * then the user has that role for all the agents. Only the roles that need to be - * updated should be part of this. + * Flag indicating if the user is a tenant admin */ - per_agent_roles?: Array; + is_tenant_admin?: boolean; /** * The user level roles of the user. */ - roles?: Array<'AGENT_USER'>; - } - - export namespace User { - /** - * The schema used to capture agent level roles - */ - export interface PerAgentRole { - /** - * ID of the agent on which to grant/revoke the role. - */ - agent_id: string; - - /** - * When set to true, the roles will be granted o/w revoked. - */ - grant: boolean; - - /** - * The roles that are granted/revoked - */ - roles: Array<'AGENT_USER'>; - } + roles?: Array< + | 'VISITOR' + | 'AGENT_USER' + | 'CUSTOMER_INTERNAL_USER' + | 'CONTEXTUAL_STAFF_USER' + | 'CONTEXTUAL_EXTERNAL_STAFF_USER' + | 'CONTEXTUAL_INTERNAL_STAFF_USER' + | 'TENANT_ADMIN' + | 'SUPER_ADMIN' + >; } } @@ -148,39 +142,19 @@ export interface NewUser { */ is_tenant_admin?: boolean; - /** - * Per agent level roles for the user. If a user is granted any role under `roles`, - * then the user has that role for all the agents. Only the roles that need to be - * updated should be part of this. - */ - per_agent_roles?: Array; - /** * The user level roles of the user. */ - roles?: Array<'AGENT_USER'>; -} - -export namespace NewUser { - /** - * The schema used to capture agent level roles - */ - export interface PerAgentRole { - /** - * ID of the agent on which to grant/revoke the role. - */ - agent_id: string; - - /** - * When set to true, the roles will be granted o/w revoked. - */ - grant: boolean; - - /** - * The roles that are granted/revoked - */ - roles: Array<'AGENT_USER'>; - } + roles?: Array< + | 'VISITOR' + | 'AGENT_USER' + | 'CUSTOMER_INTERNAL_USER' + | 'CONTEXTUAL_STAFF_USER' + | 'CONTEXTUAL_EXTERNAL_STAFF_USER' + | 'CONTEXTUAL_INTERNAL_STAFF_USER' + | 'TENANT_ADMIN' + | 'SUPER_ADMIN' + >; } export type UserUpdateResponse = unknown; @@ -198,39 +172,19 @@ export interface UserUpdateParams { */ is_tenant_admin?: boolean; - /** - * Per agent level roles for the user. If a user is granted any role under `roles`, - * then the user has that role for all the agents. Only the roles that need to be - * updated should be part of this. - */ - per_agent_roles?: Array; - /** * The user level roles of the user. */ - roles?: Array<'AGENT_USER'>; -} - -export namespace UserUpdateParams { - /** - * The schema used to capture agent level roles - */ - export interface PerAgentRole { - /** - * ID of the agent on which to grant/revoke the role. - */ - agent_id: string; - - /** - * When set to true, the roles will be granted o/w revoked. - */ - grant: boolean; - - /** - * The roles that are granted/revoked - */ - roles: Array<'AGENT_USER'>; - } + roles?: Array< + | 'VISITOR' + | 'AGENT_USER' + | 'CUSTOMER_INTERNAL_USER' + | 'CONTEXTUAL_STAFF_USER' + | 'CONTEXTUAL_EXTERNAL_STAFF_USER' + | 'CONTEXTUAL_INTERNAL_STAFF_USER' + | 'TENANT_ADMIN' + | 'SUPER_ADMIN' + >; } export interface UserListParams extends UsersPageParams { diff --git a/tests/api-resources/agents/agents.test.ts b/tests/api-resources/agents/agents.test.ts index 2d47dbc..35e5685 100644 --- a/tests/api-resources/agents/agents.test.ts +++ b/tests/api-resources/agents/agents.test.ts @@ -24,8 +24,13 @@ describe('resource agents', () => { const response = await client.agents.create({ name: 'xxx', agent_configs: { - filter_and_rerank_config: { top_k_reranked_chunks: 0 }, + filter_and_rerank_config: { + rerank_instructions: 'rerank_instructions', + reranker_score_filter_threshold: 0, + top_k_reranked_chunks: 0, + }, generate_response_config: { + avoid_commentary: true, calculate_groundedness: true, frequency_penalty: 0, max_new_tokens: 0, @@ -33,12 +38,18 @@ describe('resource agents', () => { temperature: 0, top_p: 0, }, - global_config: { enable_filter: true, enable_multi_turn: true, enable_rerank: true }, + global_config: { + enable_filter: true, + enable_multi_turn: true, + enable_rerank: true, + should_check_retrieval_need: true, + }, retrieval_config: { lexical_alpha: 0, semantic_alpha: 0, top_k_retrieved_chunks: 0 }, }, datastore_ids: ['182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'], - description: 'xxx', + description: 'description', filter_prompt: 'filter_prompt', + no_retrieval_system_prompt: 'no_retrieval_system_prompt', suggested_queries: ['string'], system_prompt: 'system_prompt', }); @@ -115,4 +126,22 @@ describe('resource agents', () => { client.agents.metadata('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: '/_stainless_unknown_path' }), ).rejects.toThrow(ContextualAI.NotFoundError); }); + + test('reset', async () => { + const responsePromise = client.agents.reset('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('reset: request options instead of params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.agents.reset('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: '/_stainless_unknown_path' }), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); }); diff --git a/tests/api-resources/agents/evaluate/evaluate.test.ts b/tests/api-resources/agents/evaluate/evaluate.test.ts index 966109e..e8bb513 100644 --- a/tests/api-resources/agents/evaluate/evaluate.test.ts +++ b/tests/api-resources/agents/evaluate/evaluate.test.ts @@ -28,6 +28,8 @@ describe('resource evaluate', () => { evalset_file: await toFile(Buffer.from('# my file contents'), 'README.md'), evalset_name: 'evalset_name', llm_model_id: 'llm_model_id', + notes: 'notes', + override_configuration: 'override_configuration', }); }); }); diff --git a/tests/api-resources/agents/query.test.ts b/tests/api-resources/agents/query.test.ts index b815104..371e6c7 100644 --- a/tests/api-resources/agents/query.test.ts +++ b/tests/api-resources/agents/query.test.ts @@ -28,9 +28,13 @@ describe('resource query', () => { include_retrieval_content_text: true, retrievals_only: true, conversation_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', - documents_filters: { field: 'field', operator: 'equals', value: 'string' }, + documents_filters: { + filters: [{ field: 'field1', operator: 'equals', value: 'value1' }], + operator: 'AND', + }, llm_model_id: 'llm_model_id', stream: true, + structured_output: { json_schema: {}, type: 'JSON' }, }); }); diff --git a/tests/api-resources/agents/tune/tune.test.ts b/tests/api-resources/agents/tune/tune.test.ts index 4f42e28..592ddce 100644 --- a/tests/api-resources/agents/tune/tune.test.ts +++ b/tests/api-resources/agents/tune/tune.test.ts @@ -33,6 +33,15 @@ describe('resource tune', () => { client.agents.tune.create( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { + 'hyperparams[learning_rate]': 2, + 'hyperparams[lora_alpha]': 8, + 'hyperparams[lora_dropout]': 0, + 'hyperparams[lora_rank]': 8, + 'hyperparams[num_epochs]': 1, + 'hyperparams[warmup_ratio]': 0, + metadata_file: await toFile(Buffer.from('# my file contents'), 'README.md'), + sdp_only: true, + synth_data: true, test_dataset_name: 'test_dataset_name', test_file: await toFile(Buffer.from('# my file contents'), 'README.md'), train_dataset_name: 'train_dataset_name', diff --git a/tests/api-resources/datastores/datastores.test.ts b/tests/api-resources/datastores/datastores.test.ts index a977195..f16cfd2 100644 --- a/tests/api-resources/datastores/datastores.test.ts +++ b/tests/api-resources/datastores/datastores.test.ts @@ -89,4 +89,22 @@ describe('resource datastores', () => { }), ).rejects.toThrow(ContextualAI.NotFoundError); }); + + test('reset', async () => { + const responsePromise = client.datastores.reset('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('reset: request options instead of params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.datastores.reset('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: '/_stainless_unknown_path' }), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); }); diff --git a/tests/api-resources/datastores/documents.test.ts b/tests/api-resources/datastores/documents.test.ts index 2b07163..999c790 100644 --- a/tests/api-resources/datastores/documents.test.ts +++ b/tests/api-resources/datastores/documents.test.ts @@ -87,7 +87,7 @@ describe('resource documents', () => { test('ingest: required and optional params', async () => { const response = await client.datastores.documents.ingest('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { file: await toFile(Buffer.from('# my file contents'), 'README.md'), - metadata: 'metadata', + metadata: '{"field1": "value1", "field2": "value2"}}', }); }); diff --git a/tests/api-resources/parse.test.ts b/tests/api-resources/parse.test.ts new file mode 100644 index 0000000..0f3db3e --- /dev/null +++ b/tests/api-resources/parse.test.ts @@ -0,0 +1,108 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextualAI, { toFile } from 'contextual-client'; +import { Response } from 'node-fetch'; + +const client = new ContextualAI({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource parse', () => { + test('create: only required params', async () => { + const responsePromise = client.parse.create({ + raw_file: await toFile(Buffer.from('# my file contents'), 'README.md'), + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('create: required and optional params', async () => { + const response = await client.parse.create({ + raw_file: await toFile(Buffer.from('# my file contents'), 'README.md'), + enable_document_hierarchy: true, + enable_split_tables: false, + figure_caption_mode: 'concise', + max_split_table_cells: 100, + page_range: '0,1,2,5,6', + parse_mode: 'standard', + }); + }); + + test('jobResults', async () => { + const responsePromise = client.parse.jobResults('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('jobResults: request options instead of params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.parse.jobResults('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: '/_stainless_unknown_path' }), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); + + test('jobResults: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.parse.jobResults( + '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', + { output_types: ['markdown-document'] }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); + + test('jobStatus', async () => { + const responsePromise = client.parse.jobStatus('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('jobStatus: request options instead of params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.parse.jobStatus('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { path: '/_stainless_unknown_path' }), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); + + test('jobs', async () => { + const responsePromise = client.parse.jobs(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('jobs: request options instead of params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect(client.parse.jobs({ path: '/_stainless_unknown_path' })).rejects.toThrow( + ContextualAI.NotFoundError, + ); + }); + + test('jobs: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.parse.jobs({ uploaded_after: '2019-12-27T18:11:19.117Z' }, { path: '/_stainless_unknown_path' }), + ).rejects.toThrow(ContextualAI.NotFoundError); + }); +}); diff --git a/tests/api-resources/users.test.ts b/tests/api-resources/users.test.ts index dd0ae65..ea67a4d 100644 --- a/tests/api-resources/users.test.ts +++ b/tests/api-resources/users.test.ts @@ -21,14 +21,7 @@ describe('resource users', () => { }); test('update: required and optional params', async () => { - const response = await client.users.update({ - email: 'email', - is_tenant_admin: true, - per_agent_roles: [ - { agent_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', grant: true, roles: ['AGENT_USER'] }, - ], - roles: ['AGENT_USER'], - }); + const response = await client.users.update({ email: 'email', is_tenant_admin: true, roles: ['VISITOR'] }); }); test('list', async () => { @@ -90,16 +83,7 @@ describe('resource users', () => { test('invite: required and optional params', async () => { const response = await client.users.invite({ - new_users: [ - { - email: 'email', - is_tenant_admin: true, - per_agent_roles: [ - { agent_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', grant: true, roles: ['AGENT_USER'] }, - ], - roles: ['AGENT_USER'], - }, - ], + new_users: [{ email: 'email', is_tenant_admin: true, roles: ['VISITOR'] }], tenant_short_name: 'tenant_short_name', }); }); From 638c221e29de165338262f4c2fd0302cd32807bb Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 8 May 2025 20:51:14 +0000 Subject: [PATCH 26/29] codegen metadata --- .stats.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.stats.yml b/.stats.yml index ce51d3c..7dab385 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 52 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-1ec5b5b63e3fe6f99de6eae32dc51fde7c2bc960703b43c99e58fdfe4e3b4c21.yml -openapi_spec_hash: e75e261b83ee7c3d524a3c28c949d227 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-ba129149413e8ce01de053816ba37b9c745240a56d3e257fefc0a496692d9290.yml +openapi_spec_hash: f47fe886b2f39b910ed991c74fba9f96 config_hash: f0c8dfba598e8ad313dc6b95c7b34df6 From fd67b96723a0234588545d4b45dfbb939c8de7bf Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 8 May 2025 20:59:51 +0000 Subject: [PATCH 27/29] feat(api): update via SDK Studio --- .stats.yml | 4 ++-- tests/api-resources/agents/tune/tune.test.ts | 2 +- tests/api-resources/parse.test.ts | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.stats.yml b/.stats.yml index 7dab385..9f1507e 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 52 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-ba129149413e8ce01de053816ba37b9c745240a56d3e257fefc0a496692d9290.yml -openapi_spec_hash: f47fe886b2f39b910ed991c74fba9f96 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-17bdb8a33fb4fcade827bba868bd65cd30c64b1d09b4a6d83c3e37a8439ed37f.yml +openapi_spec_hash: bc325b52f3b20d8c56e0be5de88f2dc3 config_hash: f0c8dfba598e8ad313dc6b95c7b34df6 diff --git a/tests/api-resources/agents/tune/tune.test.ts b/tests/api-resources/agents/tune/tune.test.ts index 592ddce..d3bf7f5 100644 --- a/tests/api-resources/agents/tune/tune.test.ts +++ b/tests/api-resources/agents/tune/tune.test.ts @@ -33,7 +33,7 @@ describe('resource tune', () => { client.agents.tune.create( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { - 'hyperparams[learning_rate]': 2, + 'hyperparams[learning_rate]': 1, 'hyperparams[lora_alpha]': 8, 'hyperparams[lora_dropout]': 0, 'hyperparams[lora_rank]': 8, diff --git a/tests/api-resources/parse.test.ts b/tests/api-resources/parse.test.ts index 0f3db3e..2734ec0 100644 --- a/tests/api-resources/parse.test.ts +++ b/tests/api-resources/parse.test.ts @@ -26,10 +26,10 @@ describe('resource parse', () => { const response = await client.parse.create({ raw_file: await toFile(Buffer.from('# my file contents'), 'README.md'), enable_document_hierarchy: true, - enable_split_tables: false, + enable_split_tables: true, figure_caption_mode: 'concise', - max_split_table_cells: 100, - page_range: '0,1,2,5,6', + max_split_table_cells: 0, + page_range: 'page_range', parse_mode: 'standard', }); }); From d6ff47c58dd8b0cb4f142951d0e3043b8487bcdd Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 8 May 2025 21:14:21 +0000 Subject: [PATCH 28/29] feat(api): update via SDK Studio --- .stats.yml | 2 +- api.md | 5 + src/index.ts | 10 + src/resources/agents/agents.ts | 621 +++++++++------------------------ src/resources/agents/index.ts | 5 + src/resources/index.ts | 5 + 6 files changed, 184 insertions(+), 464 deletions(-) diff --git a/.stats.yml b/.stats.yml index 9f1507e..525d18c 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 52 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-17bdb8a33fb4fcade827bba868bd65cd30c64b1d09b4a6d83c3e37a8439ed37f.yml openapi_spec_hash: bc325b52f3b20d8c56e0be5de88f2dc3 -config_hash: f0c8dfba598e8ad313dc6b95c7b34df6 +config_hash: 1ecef0ff4fd125bbc00eec65e3dd4798 diff --git a/api.md b/api.md index 7737695..79bb2fa 100644 --- a/api.md +++ b/api.md @@ -40,9 +40,14 @@ Methods: Types: - Agent +- AgentConfigs - AgentMetadata - CreateAgentOutput +- FilterAndRerankConfig +- GenerateResponseConfig +- GlobalConfig - ListAgentsResponse +- RetrievalConfig - AgentUpdateResponse - AgentDeleteResponse - AgentMetadataResponse diff --git a/src/index.ts b/src/index.ts index 623d0ab..f17be44 100644 --- a/src/index.ts +++ b/src/index.ts @@ -45,6 +45,7 @@ import { } from './resources/users'; import { Agent as AgentsAPIAgent, + AgentConfigs, AgentCreateParams, AgentDeleteResponse, AgentListParams, @@ -56,7 +57,11 @@ import { Agents, AgentsPage, CreateAgentOutput, + FilterAndRerankConfig, + GenerateResponseConfig, + GlobalConfig, ListAgentsResponse, + RetrievalConfig, } from './resources/agents/agents'; import { CreateDatastoreResponse, @@ -279,9 +284,14 @@ export declare namespace ContextualAI { export { Agents as Agents, type AgentsAPIAgent as Agent, + type AgentConfigs as AgentConfigs, type AgentMetadata as AgentMetadata, type CreateAgentOutput as CreateAgentOutput, + type FilterAndRerankConfig as FilterAndRerankConfig, + type GenerateResponseConfig as GenerateResponseConfig, + type GlobalConfig as GlobalConfig, type ListAgentsResponse as ListAgentsResponse, + type RetrievalConfig as RetrievalConfig, type AgentUpdateResponse as AgentUpdateResponse, type AgentDeleteResponse as AgentDeleteResponse, type AgentMetadataResponse as AgentMetadataResponse, diff --git a/src/resources/agents/agents.ts b/src/resources/agents/agents.ts index 82ff57d..1189cdc 100644 --- a/src/resources/agents/agents.ts +++ b/src/resources/agents/agents.ts @@ -120,6 +120,31 @@ export interface Agent { name: string; } +/** + * Response to configs for different components + */ +export interface AgentConfigs { + /** + * Parameters that affect filtering and reranking of retrieved knowledge + */ + filter_and_rerank_config?: FilterAndRerankConfig; + + /** + * Parameters that affect response generation + */ + generate_response_config?: GenerateResponseConfig; + + /** + * Parameters that affect the agent's overall RAG workflow + */ + global_config?: GlobalConfig; + + /** + * Parameters that affect how the agent retrieves from datastore(s) + */ + retrieval_config?: RetrievalConfig; +} + /** * Response to GET Agent request */ @@ -137,7 +162,7 @@ export interface AgentMetadata { /** * The following advanced parameters are experimental and subject to change. */ - agent_configs?: AgentMetadata.AgentConfigs; + agent_configs?: AgentConfigs; /** * Total API request counts for the agent. @@ -184,158 +209,6 @@ export interface AgentMetadata { } export namespace AgentMetadata { - /** - * The following advanced parameters are experimental and subject to change. - */ - export interface AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - filter_and_rerank_config?: AgentConfigs.FilterAndRerankConfig; - - /** - * Parameters that affect response generation - */ - generate_response_config?: AgentConfigs.GenerateResponseConfig; - - /** - * Parameters that affect the agent's overall RAG workflow - */ - global_config?: AgentConfigs.GlobalConfig; - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - retrieval_config?: AgentConfigs.RetrievalConfig; - } - - export namespace AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - export interface FilterAndRerankConfig { - /** - * Instructions that the reranker references when ranking retrievals. Note that we - * do not guarantee that the reranker will follow these instructions exactly. - * Examples: "Prioritize internal sales documents over market analysis reports. - * More recent documents should be weighted higher. Enterprise portal content - * supersedes distributor communications." and "Emphasize forecasts from top-tier - * investment banks. Recent analysis should take precedence. Disregard aggregator - * sites and favor detailed research notes over news summaries." - */ - rerank_instructions?: string; - - /** - * If the reranker relevance score associated with a chunk is below this threshold, - * then the chunk will be filtered out and not used for generation. Scores are - * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 - * to disable the reranker score filtering. - */ - reranker_score_filter_threshold?: number; - - /** - * The number of highest ranked chunks after reranking to be used - */ - top_k_reranked_chunks?: number; - } - - /** - * Parameters that affect response generation - */ - export interface GenerateResponseConfig { - /** - * Flag to indicate whether the model should avoid providing additional commentary - * in responses. Commentary is conversational in nature and does not contain - * verifiable claims; therefore, commentary is not strictly grounded in available - * context. However, commentary may provide useful context which improves the - * helpfulness of responses. - */ - avoid_commentary?: boolean; - - /** - * This parameter controls generation of groundedness scores. - */ - calculate_groundedness?: boolean; - - /** - * This parameter adjusts how the model treats repeated tokens during text - * generation. - */ - frequency_penalty?: number; - - /** - * The maximum number of tokens the model can generate in a response. - */ - max_new_tokens?: number; - - /** - * This parameter controls the randomness of how the model selects the next tokens - * during text generation. - */ - seed?: number; - - /** - * The sampling temperature, which affects the randomness in the response. - */ - temperature?: number; - - /** - * A parameter for nucleus sampling, an alternative to `temperature` which also - * affects the randomness of the response. - */ - top_p?: number; - } - - /** - * Parameters that affect the agent's overall RAG workflow - */ - export interface GlobalConfig { - /** - * Enables filtering of retrieved chunks with a separate LLM - */ - enable_filter?: boolean; - - /** - * Enables multi-turn conversations. This feature is currently experimental and - * will be improved. - */ - enable_multi_turn?: boolean; - - /** - * Enables reranking of retrieved chunks - */ - enable_rerank?: boolean; - - /** - * Enables checking if retrieval is needed for the query. This feature is currently - * experimental and will be improved. - */ - should_check_retrieval_need?: boolean; - } - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - export interface RetrievalConfig { - /** - * The weight of lexical search during retrieval. Must sum to 1 with - * semantic_alpha. - */ - lexical_alpha?: number; - - /** - * The weight of semantic search during retrieval. Must sum to 1 with - * lexical_alpha. - */ - semantic_alpha?: number; - - /** - * The maximum number of retrieved chunks from the datastore. - */ - top_k_retrieved_chunks?: number; - } - } - /** * Total API request counts for the agent. */ @@ -374,6 +247,109 @@ export interface CreateAgentOutput { datastore_ids: Array; } +/** + * Captures Filter and Rerank configurations for an Agent + */ +export interface FilterAndRerankConfig { + /** + * Instructions that the reranker references when ranking retrievals. Note that we + * do not guarantee that the reranker will follow these instructions exactly. + * Examples: "Prioritize internal sales documents over market analysis reports. + * More recent documents should be weighted higher. Enterprise portal content + * supersedes distributor communications." and "Emphasize forecasts from top-tier + * investment banks. Recent analysis should take precedence. Disregard aggregator + * sites and favor detailed research notes over news summaries." + */ + rerank_instructions?: string; + + /** + * If the reranker relevance score associated with a chunk is below this threshold, + * then the chunk will be filtered out and not used for generation. Scores are + * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 + * to disable the reranker score filtering. + */ + reranker_score_filter_threshold?: number; + + /** + * The number of highest ranked chunks after reranking to be used + */ + top_k_reranked_chunks?: number; +} + +/** + * Captures advance LLM configurations for an Agent + */ +export interface GenerateResponseConfig { + /** + * Flag to indicate whether the model should avoid providing additional commentary + * in responses. Commentary is conversational in nature and does not contain + * verifiable claims; therefore, commentary is not strictly grounded in available + * context. However, commentary may provide useful context which improves the + * helpfulness of responses. + */ + avoid_commentary?: boolean; + + /** + * This parameter controls generation of groundedness scores. + */ + calculate_groundedness?: boolean; + + /** + * This parameter adjusts how the model treats repeated tokens during text + * generation. + */ + frequency_penalty?: number; + + /** + * The maximum number of tokens the model can generate in a response. + */ + max_new_tokens?: number; + + /** + * This parameter controls the randomness of how the model selects the next tokens + * during text generation. + */ + seed?: number; + + /** + * The sampling temperature, which affects the randomness in the response. + */ + temperature?: number; + + /** + * A parameter for nucleus sampling, an alternative to `temperature` which also + * affects the randomness of the response. + */ + top_p?: number; +} + +/** + * Captures global configs + */ +export interface GlobalConfig { + /** + * Enables filtering of retrieved chunks with a separate LLM + */ + enable_filter?: boolean; + + /** + * Enables multi-turn conversations. This feature is currently experimental and + * will be improved. + */ + enable_multi_turn?: boolean; + + /** + * Enables reranking of retrieved chunks + */ + enable_rerank?: boolean; + + /** + * Enables checking if retrieval is needed for the query. This feature is currently + * experimental and will be improved. + */ + should_check_retrieval_need?: boolean; +} + export interface ListAgentsResponse { /** * Total number of available agents @@ -392,6 +368,28 @@ export interface ListAgentsResponse { next_cursor?: string; } +/** + * Captures Retrieval configurations for an Agent + */ +export interface RetrievalConfig { + /** + * The weight of lexical search during retrieval. Must sum to 1 with + * semantic_alpha. + */ + lexical_alpha?: number; + + /** + * The weight of semantic search during retrieval. Must sum to 1 with + * lexical_alpha. + */ + semantic_alpha?: number; + + /** + * The maximum number of retrieved chunks from the datastore. + */ + top_k_retrieved_chunks?: number; +} + export type AgentUpdateResponse = unknown; export type AgentDeleteResponse = unknown; @@ -466,7 +464,7 @@ export interface AgentCreateParams { /** * The following advanced parameters are experimental and subject to change. */ - agent_configs?: AgentCreateParams.AgentConfigs; + agent_configs?: AgentConfigs; /** * The IDs of the datastore to associate with this agent. @@ -505,165 +503,11 @@ export interface AgentCreateParams { system_prompt?: string; } -export namespace AgentCreateParams { - /** - * The following advanced parameters are experimental and subject to change. - */ - export interface AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - filter_and_rerank_config?: AgentConfigs.FilterAndRerankConfig; - - /** - * Parameters that affect response generation - */ - generate_response_config?: AgentConfigs.GenerateResponseConfig; - - /** - * Parameters that affect the agent's overall RAG workflow - */ - global_config?: AgentConfigs.GlobalConfig; - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - retrieval_config?: AgentConfigs.RetrievalConfig; - } - - export namespace AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - export interface FilterAndRerankConfig { - /** - * Instructions that the reranker references when ranking retrievals. Note that we - * do not guarantee that the reranker will follow these instructions exactly. - * Examples: "Prioritize internal sales documents over market analysis reports. - * More recent documents should be weighted higher. Enterprise portal content - * supersedes distributor communications." and "Emphasize forecasts from top-tier - * investment banks. Recent analysis should take precedence. Disregard aggregator - * sites and favor detailed research notes over news summaries." - */ - rerank_instructions?: string; - - /** - * If the reranker relevance score associated with a chunk is below this threshold, - * then the chunk will be filtered out and not used for generation. Scores are - * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 - * to disable the reranker score filtering. - */ - reranker_score_filter_threshold?: number; - - /** - * The number of highest ranked chunks after reranking to be used - */ - top_k_reranked_chunks?: number; - } - - /** - * Parameters that affect response generation - */ - export interface GenerateResponseConfig { - /** - * Flag to indicate whether the model should avoid providing additional commentary - * in responses. Commentary is conversational in nature and does not contain - * verifiable claims; therefore, commentary is not strictly grounded in available - * context. However, commentary may provide useful context which improves the - * helpfulness of responses. - */ - avoid_commentary?: boolean; - - /** - * This parameter controls generation of groundedness scores. - */ - calculate_groundedness?: boolean; - - /** - * This parameter adjusts how the model treats repeated tokens during text - * generation. - */ - frequency_penalty?: number; - - /** - * The maximum number of tokens the model can generate in a response. - */ - max_new_tokens?: number; - - /** - * This parameter controls the randomness of how the model selects the next tokens - * during text generation. - */ - seed?: number; - - /** - * The sampling temperature, which affects the randomness in the response. - */ - temperature?: number; - - /** - * A parameter for nucleus sampling, an alternative to `temperature` which also - * affects the randomness of the response. - */ - top_p?: number; - } - - /** - * Parameters that affect the agent's overall RAG workflow - */ - export interface GlobalConfig { - /** - * Enables filtering of retrieved chunks with a separate LLM - */ - enable_filter?: boolean; - - /** - * Enables multi-turn conversations. This feature is currently experimental and - * will be improved. - */ - enable_multi_turn?: boolean; - - /** - * Enables reranking of retrieved chunks - */ - enable_rerank?: boolean; - - /** - * Enables checking if retrieval is needed for the query. This feature is currently - * experimental and will be improved. - */ - should_check_retrieval_need?: boolean; - } - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - export interface RetrievalConfig { - /** - * The weight of lexical search during retrieval. Must sum to 1 with - * semantic_alpha. - */ - lexical_alpha?: number; - - /** - * The weight of semantic search during retrieval. Must sum to 1 with - * lexical_alpha. - */ - semantic_alpha?: number; - - /** - * The maximum number of retrieved chunks from the datastore. - */ - top_k_retrieved_chunks?: number; - } - } -} - export interface AgentUpdateParams { /** * The following advanced parameters are experimental and subject to change. */ - agent_configs?: AgentUpdateParams.AgentConfigs; + agent_configs?: AgentConfigs; /** * IDs of the datastore to associate with the agent. @@ -704,160 +548,6 @@ export interface AgentUpdateParams { system_prompt?: string; } -export namespace AgentUpdateParams { - /** - * The following advanced parameters are experimental and subject to change. - */ - export interface AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - filter_and_rerank_config?: AgentConfigs.FilterAndRerankConfig; - - /** - * Parameters that affect response generation - */ - generate_response_config?: AgentConfigs.GenerateResponseConfig; - - /** - * Parameters that affect the agent's overall RAG workflow - */ - global_config?: AgentConfigs.GlobalConfig; - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - retrieval_config?: AgentConfigs.RetrievalConfig; - } - - export namespace AgentConfigs { - /** - * Parameters that affect filtering and reranking of retrieved knowledge - */ - export interface FilterAndRerankConfig { - /** - * Instructions that the reranker references when ranking retrievals. Note that we - * do not guarantee that the reranker will follow these instructions exactly. - * Examples: "Prioritize internal sales documents over market analysis reports. - * More recent documents should be weighted higher. Enterprise portal content - * supersedes distributor communications." and "Emphasize forecasts from top-tier - * investment banks. Recent analysis should take precedence. Disregard aggregator - * sites and favor detailed research notes over news summaries." - */ - rerank_instructions?: string; - - /** - * If the reranker relevance score associated with a chunk is below this threshold, - * then the chunk will be filtered out and not used for generation. Scores are - * between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 - * to disable the reranker score filtering. - */ - reranker_score_filter_threshold?: number; - - /** - * The number of highest ranked chunks after reranking to be used - */ - top_k_reranked_chunks?: number; - } - - /** - * Parameters that affect response generation - */ - export interface GenerateResponseConfig { - /** - * Flag to indicate whether the model should avoid providing additional commentary - * in responses. Commentary is conversational in nature and does not contain - * verifiable claims; therefore, commentary is not strictly grounded in available - * context. However, commentary may provide useful context which improves the - * helpfulness of responses. - */ - avoid_commentary?: boolean; - - /** - * This parameter controls generation of groundedness scores. - */ - calculate_groundedness?: boolean; - - /** - * This parameter adjusts how the model treats repeated tokens during text - * generation. - */ - frequency_penalty?: number; - - /** - * The maximum number of tokens the model can generate in a response. - */ - max_new_tokens?: number; - - /** - * This parameter controls the randomness of how the model selects the next tokens - * during text generation. - */ - seed?: number; - - /** - * The sampling temperature, which affects the randomness in the response. - */ - temperature?: number; - - /** - * A parameter for nucleus sampling, an alternative to `temperature` which also - * affects the randomness of the response. - */ - top_p?: number; - } - - /** - * Parameters that affect the agent's overall RAG workflow - */ - export interface GlobalConfig { - /** - * Enables filtering of retrieved chunks with a separate LLM - */ - enable_filter?: boolean; - - /** - * Enables multi-turn conversations. This feature is currently experimental and - * will be improved. - */ - enable_multi_turn?: boolean; - - /** - * Enables reranking of retrieved chunks - */ - enable_rerank?: boolean; - - /** - * Enables checking if retrieval is needed for the query. This feature is currently - * experimental and will be improved. - */ - should_check_retrieval_need?: boolean; - } - - /** - * Parameters that affect how the agent retrieves from datastore(s) - */ - export interface RetrievalConfig { - /** - * The weight of lexical search during retrieval. Must sum to 1 with - * semantic_alpha. - */ - lexical_alpha?: number; - - /** - * The weight of semantic search during retrieval. Must sum to 1 with - * lexical_alpha. - */ - semantic_alpha?: number; - - /** - * The maximum number of retrieved chunks from the datastore. - */ - top_k_retrieved_chunks?: number; - } - } -} - export interface AgentListParams extends PageParams {} Agents.AgentsPage = AgentsPage; @@ -869,9 +559,14 @@ Agents.Tune = Tune; export declare namespace Agents { export { type Agent as Agent, + type AgentConfigs as AgentConfigs, type AgentMetadata as AgentMetadata, type CreateAgentOutput as CreateAgentOutput, + type FilterAndRerankConfig as FilterAndRerankConfig, + type GenerateResponseConfig as GenerateResponseConfig, + type GlobalConfig as GlobalConfig, type ListAgentsResponse as ListAgentsResponse, + type RetrievalConfig as RetrievalConfig, type AgentUpdateResponse as AgentUpdateResponse, type AgentDeleteResponse as AgentDeleteResponse, type AgentMetadataResponse as AgentMetadataResponse, diff --git a/src/resources/agents/index.ts b/src/resources/agents/index.ts index 729a05e..96668a4 100644 --- a/src/resources/agents/index.ts +++ b/src/resources/agents/index.ts @@ -4,9 +4,14 @@ export { AgentsPage, Agents, type Agent, + type AgentConfigs, type AgentMetadata, type CreateAgentOutput, + type FilterAndRerankConfig, + type GenerateResponseConfig, + type GlobalConfig, type ListAgentsResponse, + type RetrievalConfig, type AgentUpdateResponse, type AgentDeleteResponse, type AgentMetadataResponse, diff --git a/src/resources/index.ts b/src/resources/index.ts index bd0f200..d60a1a9 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -4,9 +4,14 @@ export { AgentsPage, Agents, type Agent, + type AgentConfigs, type AgentMetadata, type CreateAgentOutput, + type FilterAndRerankConfig, + type GenerateResponseConfig, + type GlobalConfig, type ListAgentsResponse, + type RetrievalConfig, type AgentUpdateResponse, type AgentDeleteResponse, type AgentMetadataResponse, From bc0d711ceb10cc7f724300f6f2d4366c9431b6a9 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 8 May 2025 21:14:48 +0000 Subject: [PATCH 29/29] release: 0.6.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 45 +++++++++++++++++++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 48 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f1c1e58..bcd0522 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.5.0" + ".": "0.6.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index f50f6cb..f3c3723 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,50 @@ # Changelog +## 0.6.0 (2025-05-08) + +Full Changelog: [v0.5.0...v0.6.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.5.0...v0.6.0) + +### Features + +* **api:** update via SDK Studio ([d6ff47c](https://github.com/ContextualAI/contextual-client-node/commit/d6ff47c58dd8b0cb4f142951d0e3043b8487bcdd)) +* **api:** update via SDK Studio ([fd67b96](https://github.com/ContextualAI/contextual-client-node/commit/fd67b96723a0234588545d4b45dfbb939c8de7bf)) +* **api:** update via SDK Studio ([c6635f9](https://github.com/ContextualAI/contextual-client-node/commit/c6635f95de77157c6fa97545bd9b6a215ae56bab)) +* **api:** update via SDK Studio ([#40](https://github.com/ContextualAI/contextual-client-node/issues/40)) ([67be5c7](https://github.com/ContextualAI/contextual-client-node/commit/67be5c7f62052e4d8d4ca960acf5d741f626103e)) +* **api:** update via SDK Studio ([#42](https://github.com/ContextualAI/contextual-client-node/issues/42)) ([a20be25](https://github.com/ContextualAI/contextual-client-node/commit/a20be255eccdd3d73b8b82215ed1bb4f5ca2e010)) +* **api:** update via SDK Studio ([#43](https://github.com/ContextualAI/contextual-client-node/issues/43)) ([14c74c1](https://github.com/ContextualAI/contextual-client-node/commit/14c74c15ebcef0871e7325453eb1ed02d12a7306)) +* **api:** update via SDK Studio ([#44](https://github.com/ContextualAI/contextual-client-node/issues/44)) ([94cf64d](https://github.com/ContextualAI/contextual-client-node/commit/94cf64d933f96e05b70757122a22871109190014)) +* **api:** update via SDK Studio ([#45](https://github.com/ContextualAI/contextual-client-node/issues/45)) ([6f38963](https://github.com/ContextualAI/contextual-client-node/commit/6f3896383295cdfbdec9a65a5a470abf3379410c)) + + +### Bug Fixes + +* **api:** improve type resolution when importing as a package ([#54](https://github.com/ContextualAI/contextual-client-node/issues/54)) ([bd2f8ab](https://github.com/ContextualAI/contextual-client-node/commit/bd2f8ab3d2cc796201c530c5e85e4485ac337506)) +* avoid type error in certain environments ([#50](https://github.com/ContextualAI/contextual-client-node/issues/50)) ([91cd06a](https://github.com/ContextualAI/contextual-client-node/commit/91cd06af830f4ef13bda0cea76908afaeb03ec19)) +* **client:** send `X-Stainless-Timeout` in seconds ([#52](https://github.com/ContextualAI/contextual-client-node/issues/52)) ([94fba4c](https://github.com/ContextualAI/contextual-client-node/commit/94fba4c76050b7471c7dbb50391cd8196278cac2)) +* **exports:** ensure resource imports don't require /index ([#47](https://github.com/ContextualAI/contextual-client-node/issues/47)) ([e530478](https://github.com/ContextualAI/contextual-client-node/commit/e530478fe8da3337643d66f4eb6cb98fb715cc16)) +* **internal:** work around https://github.com/vercel/next.js/issues/76881 ([#51](https://github.com/ContextualAI/contextual-client-node/issues/51)) ([7f0bfdd](https://github.com/ContextualAI/contextual-client-node/commit/7f0bfddede9817da316a849511cfa112191c8bef)) +* **mcp:** remove unused tools.ts ([#55](https://github.com/ContextualAI/contextual-client-node/issues/55)) ([119ec6f](https://github.com/ContextualAI/contextual-client-node/commit/119ec6fb6eff339fa9dd08481d527ca46674485f)) + + +### Chores + +* **ci:** add timeout thresholds for CI jobs ([b6b2a07](https://github.com/ContextualAI/contextual-client-node/commit/b6b2a07f2bd01f34336c5a4964efe4a07a004f68)) +* **ci:** bump node version for release workflows ([5d04e11](https://github.com/ContextualAI/contextual-client-node/commit/5d04e11485d0379d5ff7db1dedb7f25c26db4498)) +* **ci:** only use depot for staging repos ([873ba2f](https://github.com/ContextualAI/contextual-client-node/commit/873ba2f355fca96db4bcbcad1ef92e0597fa9bd3)) +* **client:** minor internal fixes ([321469a](https://github.com/ContextualAI/contextual-client-node/commit/321469aec2485d12c95fdf34308ed61714d3cdfd)) +* **exports:** cleaner resource index imports ([#48](https://github.com/ContextualAI/contextual-client-node/issues/48)) ([b204f8a](https://github.com/ContextualAI/contextual-client-node/commit/b204f8a909d95f11e4cf795d68a96b7eaf362c67)) +* **exports:** stop using path fallbacks ([#49](https://github.com/ContextualAI/contextual-client-node/issues/49)) ([b0bed50](https://github.com/ContextualAI/contextual-client-node/commit/b0bed50ab202f8b80636db662c063a9094c3de16)) +* **internal:** add aliases for Record and Array ([#53](https://github.com/ContextualAI/contextual-client-node/issues/53)) ([3fcab5f](https://github.com/ContextualAI/contextual-client-node/commit/3fcab5f1e451d41b1c3c3f399fe170c3fccb895a)) +* **internal:** codegen related update ([f3cadb2](https://github.com/ContextualAI/contextual-client-node/commit/f3cadb2de612e13ed00fb7971af8d4676b11db33)) +* **internal:** reduce CI branch coverage ([82a1e3f](https://github.com/ContextualAI/contextual-client-node/commit/82a1e3f2cd28208a6de65145a62614a16b25c5da)) +* **internal:** remove extra empty newlines ([#46](https://github.com/ContextualAI/contextual-client-node/issues/46)) ([bf1f16c](https://github.com/ContextualAI/contextual-client-node/commit/bf1f16c174c4d6caf5d120cdfe4da281a2398a8a)) +* **internal:** upload builds and expand CI branch coverage ([ba02a4a](https://github.com/ContextualAI/contextual-client-node/commit/ba02a4a584975a100a61610e0cb819a7f345f01f)) + + +### Documentation + +* **readme:** fix typo ([3ab3596](https://github.com/ContextualAI/contextual-client-node/commit/3ab3596376577889a370fc1b2c9a98b1e71b3bce)) + ## 0.5.0 (2025-03-11) Full Changelog: [v0.4.0...v0.5.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.4.0...v0.5.0) diff --git a/package.json b/package.json index 6c0ba62..5f52497 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "contextual-client", - "version": "0.5.0", + "version": "0.6.0", "description": "The official TypeScript library for the Contextual AI API", "author": "Contextual AI ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 1f5d158..30c2817 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.5.0'; // x-release-please-version +export const VERSION = '0.6.0'; // x-release-please-version