bem-ai-sdk 0.26.0 → 0.28.0

package/src/resources/entities/synonyms.ts

@@ -0,0 +1,140 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Manage the human-readable surface forms (synonyms) attached to a canonical
+ * entity. Synonyms feed the matcher's exact-match path, so adding the right
+ * synonyms improves cross-document entity resolution.
+ *
+ * - **`POST /v3/entities/{id}/synonyms`** attaches a `customer_defined`
+ *   synonym. If the same normalized form already exists as an `extracted`
+ *   synonym, it is upgraded to `customer_defined` (so the matcher weights it
+ *   higher); an existing customer/SME synonym is returned unchanged.
+ * - **`DELETE /v3/entities/{id}/synonyms/{synonymID}`** soft-deletes a
+ *   synonym. Only `customer_defined` and `sme_approved` synonyms are
+ *   deletable; `extracted` synonyms are resolver-owned and the request is
+ *   rejected with `409 Conflict`.
+ *
+ * A merged-away entity id transparently resolves to its surviving canonical
+ * entity, so a synonym added to a stale id lands on the entity that persists.
+ */
+export class Synonyms extends APIResource {
+  /**
+   * Add a Synonym to an Entity
+   *
+   * @example
+   * ```ts
+   * const response = await client.entities.synonyms.add('id', {
+   *   text: 'ACME Corporation',
+   *   locale: 'en-US',
+   * });
+   * ```
+   */
+  add(id: string, params: SynonymAddParams, options?: RequestOptions): APIPromise<SynonymAddResponse> {
+    const { bucket, ...body } = params;
+    return this._client.post(path`/v3/entities/${id}/synonyms`, { query: { bucket }, body, ...options });
+  }
+
+  /**
+   * Remove a Synonym from an Entity
+   *
+   * @example
+   * ```ts
+   * await client.entities.synonyms.remove('synonymID', {
+   *   id: 'id',
+   * });
+   * ```
+   */
+  remove(synonymID: string, params: SynonymRemoveParams, options?: RequestOptions): APIPromise<void> {
+    const { id, bucket } = params;
+    return this._client.delete(path`/v3/entities/${id}/synonyms/${synonymID}`, {
+      query: { bucket },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * One synonym attached to an entity.
+ */
+export interface SynonymAddResponse {
+  /**
+   * Creation timestamp of the synonym (RFC 3339).
+   */
+  createdAt: string;
+
+  /**
+   * Lowercased, whitespace-folded form of `text`.
+   */
+  normalizedText: string;
+
+  /**
+   * Provenance of the synonym. `customer_defined` and `sme_approved` synonyms are
+   * deletable; `extracted` synonyms are resolver-owned and cannot be deleted.
+   */
+  source: 'extracted' | 'customer_defined' | 'sme_approved';
+
+  /**
+   * Stable public identifier for the synonym (`esn_...`).
+   */
+  synonymID: string;
+
+  /**
+   * The human-readable synonym as authored.
+   */
+  text: string;
+
+  /**
+   * Optional BCP 47 locale tag, when one was supplied.
+   */
+  locale?: string;
+}
+
+export interface SynonymAddParams {
+  /**
+   * Body param: The human-readable synonym surface form to attach (e.g. `Acme Corp`,
+   * `ACME`). It is normalized (lowercased, whitespace-folded) for the uniqueness key
+   * and the matcher's exact-match path.
+   */
+  text: string;
+
+  /**
+   * Query param: Optional bucket public ID (`bkt_...`) to scope the entity lookup to
+   * one bucket. Omit for the unscoped (all account+environment) view.
+   */
+  bucket?: string;
+
+  /**
+   * Body param: Optional BCP 47 locale tag (e.g. `en-US`) for language-specific
+   * synonyms.
+   */
+  locale?: string;
+}
+
+export interface SynonymRemoveParams {
+  /**
+   * Path param: Entity public ID (`ent_...`). A merged-away id resolves to the
+   * surviving entity.
+   */
+  id: string;
+
+  /**
+   * Query param: Optional bucket public ID (`bkt_...`) to scope the entity lookup to
+   * one bucket. Omit for the unscoped (all account+environment) view.
+   */
+  bucket?: string;
+}
+
+export declare namespace Synonyms {
+  export {
+    type SynonymAddResponse as SynonymAddResponse,
+    type SynonymAddParams as SynonymAddParams,
+    type SynonymRemoveParams as SynonymRemoveParams,
+  };
+}

package/src/resources/entities.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './entities/index';

package/src/resources/entity-types/entity-types.ts

@@ -0,0 +1,396 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ReviewersAPI from './reviewers';
+import {
+  ReviewerAssignParams,
+  ReviewerAssignResponse,
+  ReviewerListResponse,
+  ReviewerRemoveParams,
+  Reviewers,
+} from './reviewers';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Entity Types are the customer-defined taxonomy for the knowledge graph,
+ * scoped to an account+environment. Each type has a unique, immutable name
+ * and can be organised into hierarchies via `parentTypeID`. A type may
+ * carry per-type structured attribute metadata in `attributeSchema` (for
+ * example `{"unit": "mg", "range": [0, 100]}`).
+ *
+ * Use these endpoints to create, list, fetch, update, and delete entity
+ * types:
+ *
+ * - **`POST /v3/entity-types`** creates a type, optionally under a parent.
+ * - **`GET /v3/entity-types`** lists types with cursor pagination
+ *   (`startingAfter` / `endingBefore` over `typeID`) and an optional
+ *   `parentTypeId` filter for direct children.
+ * - **`PATCH /v3/entity-types/{typeID}`** updates `description`,
+ *   `parentTypeID`, and/or `attributeSchema`. The `name` is immutable.
+ * - **`DELETE /v3/entity-types/{typeID}`** soft-deletes a type. The request
+ *   is rejected with `409 Conflict` while any live entity is assigned to
+ *   the type or any live child type points at it.
+ */
+export class EntityTypes extends APIResource {
+  reviewers: ReviewersAPI.Reviewers = new ReviewersAPI.Reviewers(this._client);
+
+  /**
+   * Create an Entity Type
+   *
+   * @example
+   * ```ts
+   * const entityType = await client.entityTypes.create({
+   *   name: 'Drug',
+   *   description: 'A pharmaceutical compound',
+   * });
+   * ```
+   */
+  create(body: EntityTypeCreateParams, options?: RequestOptions): APIPromise<EntityTypeCreateResponse> {
+    return this._client.post('/v3/entity-types', { body, ...options });
+  }
+
+  /**
+   * Get an Entity Type
+   *
+   * @example
+   * ```ts
+   * const entityType = await client.entityTypes.retrieve(
+   *   'typeID',
+   * );
+   * ```
+   */
+  retrieve(typeID: string, options?: RequestOptions): APIPromise<EntityTypeRetrieveResponse> {
+    return this._client.get(path`/v3/entity-types/${typeID}`, options);
+  }
+
+  /**
+   * Update an Entity Type
+   *
+   * @example
+   * ```ts
+   * const entityType = await client.entityTypes.update(
+   *   'typeID',
+   * );
+   * ```
+   */
+  update(
+    typeID: string,
+    body: EntityTypeUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<EntityTypeUpdateResponse> {
+    return this._client.patch(path`/v3/entity-types/${typeID}`, { body, ...options });
+  }
+
+  /**
+   * List Entity Types
+   *
+   * @example
+   * ```ts
+   * const entityTypes = await client.entityTypes.list();
+   * ```
+   */
+  list(
+    query: EntityTypeListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EntityTypeListResponse> {
+    return this._client.get('/v3/entity-types', { query, ...options });
+  }
+
+  /**
+   * Delete an Entity Type
+   *
+   * @example
+   * ```ts
+   * await client.entityTypes.delete('typeID');
+   * ```
+   */
+  delete(typeID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v3/entity-types/${typeID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * An EntityType is a customer-defined type in the knowledge-graph taxonomy, scoped
+ * to an account+environment. Types may be organised into hierarchies via
+ * `parentTypeID`, and may carry per-type structured attribute metadata in
+ * `attributeSchema` (for example `{"unit": "mg", "range": [0, 100]}`).
+ */
+export interface EntityTypeCreateResponse {
+  /**
+   * Creation timestamp (RFC 3339).
+   */
+  createdAt: string;
+
+  /**
+   * Optional human-facing note about the type.
+   */
+  description: string;
+
+  /**
+   * Human-facing type name. Unique within an account+environment, and immutable once
+   * set.
+   */
+  name: string;
+
+  /**
+   * Public ID (`ety_...`) of the parent type, or an empty string when the type is
+   * top-level.
+   */
+  parentTypeID: string;
+
+  /**
+   * Stable public identifier for the entity type (`ety_...`).
+   */
+  typeID: string;
+
+  /**
+   * Last-update timestamp (RFC 3339).
+   */
+  updatedAt: string;
+
+  /**
+   * Optional per-type structured attribute metadata.
+   */
+  attributeSchema?: unknown;
+}
+
+/**
+ * An EntityType is a customer-defined type in the knowledge-graph taxonomy, scoped
+ * to an account+environment. Types may be organised into hierarchies via
+ * `parentTypeID`, and may carry per-type structured attribute metadata in
+ * `attributeSchema` (for example `{"unit": "mg", "range": [0, 100]}`).
+ */
+export interface EntityTypeRetrieveResponse {
+  /**
+   * Creation timestamp (RFC 3339).
+   */
+  createdAt: string;
+
+  /**
+   * Optional human-facing note about the type.
+   */
+  description: string;
+
+  /**
+   * Human-facing type name. Unique within an account+environment, and immutable once
+   * set.
+   */
+  name: string;
+
+  /**
+   * Public ID (`ety_...`) of the parent type, or an empty string when the type is
+   * top-level.
+   */
+  parentTypeID: string;
+
+  /**
+   * Stable public identifier for the entity type (`ety_...`).
+   */
+  typeID: string;
+
+  /**
+   * Last-update timestamp (RFC 3339).
+   */
+  updatedAt: string;
+
+  /**
+   * Optional per-type structured attribute metadata.
+   */
+  attributeSchema?: unknown;
+}
+
+/**
+ * An EntityType is a customer-defined type in the knowledge-graph taxonomy, scoped
+ * to an account+environment. Types may be organised into hierarchies via
+ * `parentTypeID`, and may carry per-type structured attribute metadata in
+ * `attributeSchema` (for example `{"unit": "mg", "range": [0, 100]}`).
+ */
+export interface EntityTypeUpdateResponse {
+  /**
+   * Creation timestamp (RFC 3339).
+   */
+  createdAt: string;
+
+  /**
+   * Optional human-facing note about the type.
+   */
+  description: string;
+
+  /**
+   * Human-facing type name. Unique within an account+environment, and immutable once
+   * set.
+   */
+  name: string;
+
+  /**
+   * Public ID (`ety_...`) of the parent type, or an empty string when the type is
+   * top-level.
+   */
+  parentTypeID: string;
+
+  /**
+   * Stable public identifier for the entity type (`ety_...`).
+   */
+  typeID: string;
+
+  /**
+   * Last-update timestamp (RFC 3339).
+   */
+  updatedAt: string;
+
+  /**
+   * Optional per-type structured attribute metadata.
+   */
+  attributeSchema?: unknown;
+}
+
+/**
+ * Response body for listing entity types.
+ */
+export interface EntityTypeListResponse {
+  entityTypes: Array<EntityTypeListResponse.EntityType>;
+
+  /**
+   * Total number of entity types matching the query, ignoring pagination.
+   */
+  totalCount: number;
+}
+
+export namespace EntityTypeListResponse {
+  /**
+   * An EntityType is a customer-defined type in the knowledge-graph taxonomy, scoped
+   * to an account+environment. Types may be organised into hierarchies via
+   * `parentTypeID`, and may carry per-type structured attribute metadata in
+   * `attributeSchema` (for example `{"unit": "mg", "range": [0, 100]}`).
+   */
+  export interface EntityType {
+    /**
+     * Creation timestamp (RFC 3339).
+     */
+    createdAt: string;
+
+    /**
+     * Optional human-facing note about the type.
+     */
+    description: string;
+
+    /**
+     * Human-facing type name. Unique within an account+environment, and immutable once
+     * set.
+     */
+    name: string;
+
+    /**
+     * Public ID (`ety_...`) of the parent type, or an empty string when the type is
+     * top-level.
+     */
+    parentTypeID: string;
+
+    /**
+     * Stable public identifier for the entity type (`ety_...`).
+     */
+    typeID: string;
+
+    /**
+     * Last-update timestamp (RFC 3339).
+     */
+    updatedAt: string;
+
+    /**
+     * Optional per-type structured attribute metadata.
+     */
+    attributeSchema?: unknown;
+  }
+}
+
+export interface EntityTypeCreateParams {
+  /**
+   * Type name. Required and unique within the account+environment.
+   */
+  name: string;
+
+  /**
+   * Optional per-type structured attribute metadata.
+   */
+  attributeSchema?: unknown;
+
+  /**
+   * Optional description.
+   */
+  description?: string;
+
+  /**
+   * Optional public ID (`ety_...`) of the parent type. Must belong to the same
+   * account+environment.
+   */
+  parentTypeID?: string;
+}
+
+export interface EntityTypeUpdateParams {
+  /**
+   * New per-type structured attribute metadata.
+   */
+  attributeSchema?: unknown;
+
+  /**
+   * New description.
+   */
+  description?: string;
+
+  /**
+   * New parent type public ID (`ety_...`), or an empty string to clear the parent
+   * (promote to top-level). Must belong to the same account+environment and may not
+   * be the type itself.
+   */
+  parentTypeID?: string;
+}
+
+export interface EntityTypeListParams {
+  /**
+   * Cursor: return types whose `typeID` sorts before this value.
+   */
+  endingBefore?: string;
+
+  /**
+   * Maximum number of entity types to return (default 50, max 200).
+   */
+  limit?: number;
+
+  /**
+   * Filter to the direct children of this parent type (`ety_...`).
+   */
+  parentTypeId?: string;
+
+  /**
+   * Cursor: return types whose `typeID` sorts after this value.
+   */
+  startingAfter?: string;
+}
+
+EntityTypes.Reviewers = Reviewers;
+
+export declare namespace EntityTypes {
+  export {
+    type EntityTypeCreateResponse as EntityTypeCreateResponse,
+    type EntityTypeRetrieveResponse as EntityTypeRetrieveResponse,
+    type EntityTypeUpdateResponse as EntityTypeUpdateResponse,
+    type EntityTypeListResponse as EntityTypeListResponse,
+    type EntityTypeCreateParams as EntityTypeCreateParams,
+    type EntityTypeUpdateParams as EntityTypeUpdateParams,
+    type EntityTypeListParams as EntityTypeListParams,
+  };
+
+  export {
+    Reviewers as Reviewers,
+    type ReviewerListResponse as ReviewerListResponse,
+    type ReviewerAssignResponse as ReviewerAssignResponse,
+    type ReviewerAssignParams as ReviewerAssignParams,
+    type ReviewerRemoveParams as ReviewerRemoveParams,
+  };
+}

package/src/resources/entity-types/index.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  EntityTypes,
+  type EntityTypeCreateResponse,
+  type EntityTypeRetrieveResponse,
+  type EntityTypeUpdateResponse,
+  type EntityTypeListResponse,
+  type EntityTypeCreateParams,
+  type EntityTypeUpdateParams,
+  type EntityTypeListParams,
+} from './entity-types';
+export {
+  Reviewers,
+  type ReviewerListResponse,
+  type ReviewerAssignResponse,
+  type ReviewerAssignParams,
+  type ReviewerRemoveParams,
+} from './reviewers';