release: 0.5.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 46
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-f43814080090927ee22816c5c7f517d8a7eb7f346329ada67915608e32124321.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/contextual-ai%2Fsunrise-194878b194cd507d7c5418ff38cc0fc53441ef618f991990d334b4b75775cd8f.yml

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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)
+
+### Features
+
+* add SKIP_BREW env var to ./scripts/bootstrap ([#35](https://github.com/ContextualAI/contextual-client-node/issues/35)) ([bb0faca](https://github.com/ContextualAI/contextual-client-node/commit/bb0faca1da1cc716197e02d3a5e9b6614f2204b0))
+* **api:** update via SDK Studio ([#37](https://github.com/ContextualAI/contextual-client-node/issues/37)) ([1cc7907](https://github.com/ContextualAI/contextual-client-node/commit/1cc7907b119cb40734c3da6040feb6b999e70191))
+* **api:** update via SDK Studio ([#38](https://github.com/ContextualAI/contextual-client-node/issues/38)) ([b23a2e2](https://github.com/ContextualAI/contextual-client-node/commit/b23a2e2fa6bfcf37b61754eeb134d165c61e8d9d))
+* **client:** accept RFC6838 JSON content types ([#36](https://github.com/ContextualAI/contextual-client-node/issues/36)) ([5178d1d](https://github.com/ContextualAI/contextual-client-node/commit/5178d1ddbc4c67f035113faafcc292c0dc05f014))
+
+
+### Chores
+
+* **internal:** codegen related update ([#33](https://github.com/ContextualAI/contextual-client-node/issues/33)) ([7608b02](https://github.com/ContextualAI/contextual-client-node/commit/7608b02fa3f51ef345da11be72b90fba5018ed68))
+
 ## 0.4.0 (2025-03-03)
 
 Full Changelog: [v0.3.0...v0.4.0](https://github.com/ContextualAI/contextual-client-node/compare/v0.3.0...v0.4.0)

api.md

@@ -19,6 +19,7 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/datastores/documents.ts">CompositeMetadataFilter</a></code>
 - <code><a href="./src/resources/datastores/documents.ts">DocumentMetadata</a></code>
 - <code><a href="./src/resources/datastores/documents.ts">IngestionResponse</a></code>
 - <code><a href="./src/resources/datastores/documents.ts">ListDocumentsResponse</a></code>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextual-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The official TypeScript library for the Contextual AI API",
   "author": "Contextual AI <[email protected]>",
   "types": "dist/index.d.ts",

scripts/bootstrap

@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ]; then
   brew bundle check >/dev/null 2>&1 || {
     echo "==> Installing Homebrew dependencies…"
     brew bundle

src/core.ts

@@ -48,8 +48,8 @@ async function defaultParseResponse<T>(props: APIResponseProps): Promise<T> {
   }
 
   const contentType = response.headers.get('content-type');
-  const isJSON =
-    contentType?.includes('application/json') || contentType?.includes('application/vnd.api+json');
+  const mediaType = contentType?.split(';')[0]?.trim();
+  const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
   if (isJSON) {
     const json = await response.json();
 

src/pagination.ts

@@ -53,7 +53,7 @@ export class DatastoresPage<Item> extends AbstractPage<Item> implements Datastor
 
     return {
       params: {
-        cursor: cursor,
+        cursor,
       },
     };
   }
@@ -110,7 +110,7 @@ export class DocumentsPage<Item> extends AbstractPage<Item> implements Documents
 
     return {
       params: {
-        cursor: cursor,
+        cursor,
       },
     };
   }
@@ -167,7 +167,7 @@ export class UsersPage<Item> extends AbstractPage<Item> implements UsersPageResp
 
     return {
       params: {
-        cursor: cursor,
+        cursor,
       },
     };
   }
@@ -219,7 +219,7 @@ export class Page<Item> extends AbstractPage<Item> implements PageResponse<Item>
 
     return {
       params: {
-        cursor: cursor,
+        cursor,
       },
     };
   }

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<CreateAgentOutput> {
     return this._client.post('/agents', { body, ...options });
@@ -132,6 +137,12 @@ export interface AgentMetadata {
    */
   description?: string;
 
+  /**
+   * The prompt to an LLM which determines whether retrieved chunks are relevant to a
+   * given query and filters out irrelevant chunks. This prompt is applied per chunk.
+   */
+  filter_prompt?: string;
+
   /**
    * The model ID to use for generation. Tuned models can only be used for the agents
    * on which they were tuned. If no model is specified, the default model is used.
@@ -195,6 +206,11 @@ export namespace AgentMetadata {
      * Parameters that affect response generation
      */
     export interface GenerateResponseConfig {
+      /**
+       * This parameter controls generation of groundedness scores.
+       */
+      calculate_groundedness?: boolean;
+
       /**
        * This parameter adjusts how the model treats repeated tokens during text
        * generation.
@@ -327,6 +343,12 @@ export interface AgentCreateParams {
    */
   description?: string;
 
+  /**
+   * The prompt to an LLM which determines whether retrieved chunks are relevant to a
+   * given query and filters out irrelevant chunks.
+   */
+  filter_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
@@ -383,6 +405,11 @@ export namespace AgentCreateParams {
      * Parameters that affect response generation
      */
     export interface GenerateResponseConfig {
+      /**
+       * This parameter controls generation of groundedness scores.
+       */
+      calculate_groundedness?: boolean;
+
       /**
        * This parameter adjusts how the model treats repeated tokens during text
        * generation.
@@ -466,6 +493,12 @@ export interface AgentUpdateParams {
    */
   datastore_ids?: Array<string>;
 
+  /**
+   * The prompt to an LLM which determines whether retrieved chunks are relevant to a
+   * given query and filters out irrelevant chunks.
+   */
+  filter_prompt?: string;
+
   /**
    * The model ID to use for generation. Tuned models can only be used for the agents
    * on which they were tuned. If no model is specified, the default model is used.
@@ -529,6 +562,11 @@ export namespace AgentUpdateParams {
      * Parameters that affect response generation
      */
     export interface GenerateResponseConfig {
+      /**
+       * This parameter controls generation of groundedness scores.
+       */
+      calculate_groundedness?: boolean;
+
       /**
        * This parameter adjusts how the model treats repeated tokens during text
        * generation.

src/resources/agents/query.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../resource';
 import { isRequestOptions } from '../../core';
 import * as Core from '../../core';
+import * as DocumentsAPI from '../datastores/documents';
 
 export class Query extends APIResource {
   /**
@@ -96,6 +97,11 @@ export interface QueryResponse {
    */
   attributions?: Array<QueryResponse.Attribution>;
 
+  /**
+   * Groundedness scores for the response
+   */
+  groundedness_scores?: Array<QueryResponse.GroundednessScore>;
+
   /**
    * Response to the query request
    */
@@ -130,7 +136,7 @@ export namespace QueryResponse {
     /**
      * Format of the content, such as `pdf` or `html`
      */
-    format: 'pdf' | 'html' | 'htm';
+    format: 'pdf' | 'html' | 'htm' | 'mhtml' | 'doc' | 'docx' | 'ppt' | 'pptx';
 
     /**
      * Source type of the content. Will be `file` for any docs ingested through
@@ -180,6 +186,26 @@ export namespace QueryResponse {
     start_idx: number;
   }
 
+  /**
+   * Groundedness scores in a generated message`.
+   */
+  export interface GroundednessScore {
+    /**
+     * End index of the span in the generated message
+     */
+    end_idx: number;
+
+    /**
+     * Groundedness score for the span
+     */
+    score: number;
+
+    /**
+     * Start index of the span in the generated message
+     */
+    start_idx: number;
+  }
+
   /**
    * Response to the query request
    */
@@ -308,6 +334,44 @@ export interface QueryCreateParams {
    */
   conversation_id?: string;
 
+  /**
+   * Body param: Defines an Optional custom metadata filter, which can be a list of
+   * filters or nested filters. The expected input is a nested JSON object that can
+   * represent a single filter or a composite (logical) combination of filters.
+   *
+   * Unnested Example:
+   *
+   * ```json
+   * {
+   *   "operator": "AND",
+   *   "filters": [{ "field": "status", "operator": "equals", "value": "active" }]
+   * }
+   * ```
+   *
+   * Nested example:
+   *
+   * ```json
+   * {
+   *   "operator": "AND",
+   *   "filters": [
+   *     { "field": "status", "operator": "equals", "value": "active" },
+   *     {
+   *       "operator": "OR",
+   *       "filters": [
+   *         {
+   *           "field": "category",
+   *           "operator": "containsany",
+   *           "value": ["policy", "HR"]
+   *         },
+   *         { "field": "tags", "operator": "exists" }
+   *       ]
+   *     }
+   *   ]
+   * }
+   * ```
+   */
+  documents_filters?: QueryCreateParams.BaseMetadataFilter | DocumentsAPI.CompositeMetadataFilter;
+
   /**
    * Body param: Model ID of the specific fine-tuned or aligned LLM model to use.
    * Defaults to base model if not specified.
@@ -335,6 +399,43 @@ export namespace QueryCreateParams {
      */
     role: 'user' | 'system' | 'assistant' | 'knowledge';
   }
+
+  /**
+   * Defines a custom metadata filter. The expected input is a dict which can have
+   * different operators, fields and values. For example:
+   *
+   *     {"field": "title", "operator": "startswith", "value": "hr-"}
+   *
+   * For document_id and date_created the query is built using direct query without
+   * nesting.
+   */
+  export interface BaseMetadataFilter {
+    /**
+     * Field name to search for in the metadata
+     */
+    field: string;
+
+    /**
+     * Operator to be used for the filter.
+     */
+    operator:
+      | 'equals'
+      | 'containsany'
+      | 'exists'
+      | 'startswith'
+      | 'gt'
+      | 'gte'
+      | 'lt'
+      | 'lte'
+      | 'notequals'
+      | 'between';
+
+    /**
+     * The value to be searched for in the field. In case of exists operator, it is not
+     * needed.
+     */
+    value?: string | number | boolean | Array<string | number | boolean> | null;
+  }
 }
 
 export interface QueryFeedbackParams {
@@ -362,6 +463,11 @@ export interface QueryFeedbackParams {
 }
 
 export interface QueryMetricsParams {
+  /**
+   * Filter messages by conversation ids.
+   */
+  conversation_ids?: Array<string>;
+
   /**
    * Filters messages that are created after the specified timestamp.
    */
@@ -381,6 +487,11 @@ export interface QueryMetricsParams {
    * Offset for pagination.
    */
   offset?: number;
+
+  /**
+   * Filter messages by users.
+   */
+  user_emails?: Array<string>;
 }
 
 export interface QueryRetrievalInfoParams {

src/resources/agents/tune/jobs.ts

@@ -66,7 +66,7 @@ export interface TuneJobMetadata {
   /**
    * Metadata about the model evaluation, including status and results if completed.
    */
-  evaluation_metadata?: unknown | null;
+  evaluation_metadata?: Array<unknown>;
 
   /**
    * ID of the tuned model. Omitted if the tuning job failed or is still in progress.

src/resources/datastores/datastores.ts

@@ -5,6 +5,7 @@ import { isRequestOptions } from '../../core';
 import * as Core from '../../core';
 import * as DocumentsAPI from './documents';
 import {
+  CompositeMetadataFilter,
   DocumentDeleteResponse,
   DocumentIngestParams,
   DocumentListParams,
@@ -31,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,
@@ -180,6 +186,7 @@ export declare namespace Datastores {
 
   export {
     Documents as Documents,
+    type CompositeMetadataFilter as CompositeMetadataFilter,
     type DocumentMetadata as DocumentMetadata,
     type IngestionResponse as IngestionResponse,
     type ListDocumentsResponse as ListDocumentsResponse,