featurebase-node 0.14.3 → 0.15.1

package/src/resources/training-data/training-data.ts

@@ -0,0 +1,603 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as FilesAPI from './files';
+import {
+  FileCreateParams,
+  FileDeleteParams,
+  FileDeleteResponse,
+  FileListParams,
+  FileRetrieveParams,
+  FileUpdateParams,
+  Files,
+  TrainingFile,
+  TrainingFilesCursorPage,
+} from './files';
+import * as QnaAPI from './qna';
+import {
+  Qna,
+  QnaCreateParams,
+  QnaDeleteParams,
+  QnaDeleteResponse,
+  QnaListParams,
+  QnaResource,
+  QnaRetrieveParams,
+  QnaUpdateParams,
+  QnasCursorPage,
+} from './qna';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Training data teaches the AI agent about your product beyond your public Help Center: training files (documents, policies, internal notes) and Q&A entries (question variants with the exact answer to give). Use these endpoints to keep that knowledge in sync from your own systems — for example, pushing resolved support conversations, internal runbooks, or SOP documents automatically.
+ */
+export class TrainingData extends APIResource {
+  files: FilesAPI.Files = new FilesAPI.Files(this._client);
+  qna: QnaAPI.QnaResource = new QnaAPI.QnaResource(this._client);
+
+  /**
+   * Checks a proposed Q&A without writing. Optional externalId or an existing
+   * normalized question addresses a target. Changed content is compared with that
+   * entry even if retrieval or excludeIds misses it. The judge continues past
+   * agreement to detect later contradictions; uncertainty takes precedence over
+   * agreement. Another agreeing Q&A remains visible for duplicate review.
+   *
+   * Actions: create means no overlap found in checked candidates; update_target
+   * refers to existing; update_qna refers to target; review_qna / review_article /
+   * review_file require review of the source; skip means an identical payload or
+   * already-covered answer. existing and Q&A candidates include revisions: use PATCH
+   * expectedRevision for a subsequent reviewed update.
+   *
+   * The evidence is bounded: retrieval can miss knowledge, document excerpts omit
+   * context, and checks observe changing data. checkTruncated reports verification
+   * shortlist or text limits and yields unclear unless a contradiction was found.
+   * False does not imply exhaustive coverage or factual correctness. Inspect full
+   * sources before promotion. Dependencies failing returns 503; this endpoint never
+   * writes.
+   *
+   * @example
+   * ```ts
+   * const oracle = await client.trainingData.oracle({
+   *   answer:
+   *     'You can request a refund within 30 days from **Settings → Billing**.',
+   *   questions: [
+   *     'How do I request a refund?',
+   *     'Can I get my money back?',
+   *   ],
+   * });
+   * ```
+   */
+  oracle(params: TrainingDataOracleParams, options?: RequestOptions): APIPromise<Oracle> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/training_data/oracle', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Searches one passage or claim across Q&A, training files, and live help-center
+   * articles. Returns ranked candidates and query-focused excerpts without judging
+   * or writing. Similarity is an embedding score, not factual confidence; calibrate
+   * thresholds on representative examples and retain keyword-only results
+   * (similarity null). Retrieval and excerpts can miss relevant facts. Fetch full
+   * sources for decisions. Split long documents into bounded sections and audit each
+   * section before upload. Latency and embedding work depend on query size and
+   * service load.
+   *
+   * @example
+   * ```ts
+   * const knowledgeSearch = await client.trainingData.search({
+   *   query:
+   *     'Refunds are processed within 14 days of the request.',
+   * });
+   * ```
+   */
+  search(params: TrainingDataSearchParams, options?: RequestOptions): APIPromise<KnowledgeSearch> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/training_data/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface KnowledgeSearch {
+  /**
+   * Existing items closest to the query, best first, at most `topK`. `text` is an
+   * excerpt focused on the query; `section` is the heading path inside a file when
+   * known.
+   */
+  candidates: Array<KnowledgeSearch.Candidate>;
+
+  /**
+   * Object type identifier
+   */
+  object: 'knowledge_search';
+
+  /**
+   * The query as searched (trimmed)
+   */
+  query: string;
+
+  /**
+   * Where the time went
+   */
+  timings: KnowledgeSearch.Timings;
+}
+
+export namespace KnowledgeSearch {
+  export interface Candidate {
+    /**
+     * ID of the existing item
+     */
+    id: string;
+
+    /**
+     * The item's source identity, for training files and Q&A
+     */
+    externalId: string | null;
+
+    /**
+     * What kind of knowledge item matched: a Q&A entry, a training file / crawled
+     * page, or a live help-center article.
+     */
+    kind: 'qna' | 'training_file' | 'help_center_article';
+
+    /**
+     * Question variants, for Q&A entries
+     */
+    questions: Array<string> | null;
+
+    /**
+     * Q&A revision compared by the judge; null for other kinds. Use with PATCH
+     * expectedRevision.
+     */
+    revision: number | null;
+
+    /**
+     * Heading breadcrumb of the matching section, for training files
+     */
+    section: string | null;
+
+    /**
+     * Cosine similarity between the query and item. Calibrate any threshold using
+     * representative examples; it is not a correctness or contradiction score. `null`
+     * when the item was found by keywords only. Arrays are already ordered closest
+     * first.
+     */
+    similarity: number | null;
+
+    /**
+     * The item's `source` label, for Q&A entries and training files
+     */
+    source: string | null;
+
+    /**
+     * Excerpt of the existing content the judge compared against (Q&A answer, matching
+     * document section, or article body), up to 1200 characters plus an ellipsis when
+     * cut.
+     */
+    text: string;
+
+    /**
+     * Title of the existing item
+     */
+    title: string;
+
+    /**
+     * Public URL of the item when it has one
+     */
+    url: string | null;
+  }
+
+  /**
+   * Where the time went
+   */
+  export interface Timings {
+    /**
+     * Time spent searching and loading the items
+     */
+    retrievalMs: number;
+  }
+}
+
+export interface Oracle {
+  /**
+   * Suggested next step. `create`: no overlap found in the checked candidates;
+   * verify the source before writing. `update_target`: an entry already carries one
+   * of these questions (`existing`) and should be updated with this content — use
+   * PATCH with expectedRevision from existing to bind the write to this check.
+   * `update_qna`: an existing Q&A entry already answers this with the same facts —
+   * merge into it (`target`) instead of adding a second one. `review_qna` /
+   * `review_article` / `review_file`: an existing item (`target`) contradicts this
+   * answer or the judge could not decide — a human should pick the right fact and
+   * fix the source. `skip`: the knowledge already exists (an article or file answers
+   * it, or the payload is identical to the entry that already carries the question);
+   * nothing to write.
+   */
+  action:
+    | 'create'
+    | 'update_target'
+    | 'update_qna'
+    | 'review_qna'
+    | 'review_article'
+    | 'review_file'
+    | 'skip';
+
+  /**
+   * Retrieved items and the addressed entry (first when present), at most 10.
+   * Excerpts are partial evidence.
+   */
+  candidates: Array<Oracle.Candidate>;
+
+  /**
+   * A candidate or text budget limited verification (including clipped proposed
+   * answers or Q&A answers). This yields unclear unless a contradiction was already
+   * found. False does not mean the entire workspace was exhaustively checked.
+   */
+  checkTruncated: boolean;
+
+  /**
+   * The Q&A entry addressed by externalId or a normalized question, including its
+   * checked revision, or null
+   */
+  existing: Oracle.Existing | null;
+
+  /**
+   * Per-candidate judge verdicts, in the order they were judged. Judging continues
+   * after agreement or uncertainty and stops on a contradiction. The addressed entry
+   * is always compared when its content changes. Only shortlisted candidates are
+   * judged, so this is usually shorter than `candidates`.
+   */
+  judged: Array<Oracle.Judged>;
+
+  /**
+   * Object type identifier
+   */
+  object: 'oracle';
+
+  /**
+   * One or two sentences explaining the action, from the judge when it ran
+   */
+  reason: string;
+
+  target: Oracle.Target;
+
+  /**
+   * Where the time went
+   */
+  timings: Oracle.Timings;
+
+  /**
+   * How the closest existing item relates to the entry. `same_topic`: it answers the
+   * same customer question (the entry would be a duplicate, rewording, or updated
+   * version). `contradicts`: same question, incompatible facts. `different`: a
+   * different question, even if the wording overlaps. `unclear`: the judge could not
+   * decide. `no_match`: nothing similar was found.
+   */
+  verdict: 'same_topic' | 'contradicts' | 'different' | 'unclear' | 'no_match';
+}
+
+export namespace Oracle {
+  export interface Candidate {
+    /**
+     * ID of the existing item
+     */
+    id: string;
+
+    /**
+     * The item's source identity, for training files and Q&A
+     */
+    externalId: string | null;
+
+    /**
+     * What kind of knowledge item matched: a Q&A entry, a training file / crawled
+     * page, or a live help-center article.
+     */
+    kind: 'qna' | 'training_file' | 'help_center_article';
+
+    /**
+     * Question variants, for Q&A entries
+     */
+    questions: Array<string> | null;
+
+    /**
+     * Q&A revision compared by the judge; null for other kinds. Use with PATCH
+     * expectedRevision.
+     */
+    revision: number | null;
+
+    /**
+     * Heading breadcrumb of the matching section, for training files
+     */
+    section: string | null;
+
+    /**
+     * Cosine similarity between the query and item. Calibrate any threshold using
+     * representative examples; it is not a correctness or contradiction score. `null`
+     * when the item was found by keywords only. Arrays are already ordered closest
+     * first.
+     */
+    similarity: number | null;
+
+    /**
+     * The item's `source` label, for Q&A entries and training files
+     */
+    source: string | null;
+
+    /**
+     * Excerpt of the existing content the judge compared against (Q&A answer, matching
+     * document section, or article body), up to 1200 characters plus an ellipsis when
+     * cut.
+     */
+    text: string;
+
+    /**
+     * Title of the existing item
+     */
+    title: string;
+
+    /**
+     * Public URL of the item when it has one
+     */
+    url: string | null;
+  }
+
+  /**
+   * The Q&A entry addressed by externalId or a normalized question, including its
+   * checked revision, or null
+   */
+  export interface Existing {
+    /**
+     * Q&A entry ID
+     */
+    id: string;
+
+    /**
+     * Matching question from your request, or its first question when addressed by
+     * externalId
+     */
+    question: string;
+
+    /**
+     * Revision of the addressed entry at check time. Use with PATCH expectedRevision.
+     */
+    revision: number;
+  }
+
+  export interface Judged {
+    /**
+     * ID of the judged candidate
+     */
+    candidateId: string;
+
+    /**
+     * What kind of knowledge item matched: a Q&A entry, a training file / crawled
+     * page, or a live help-center article.
+     */
+    kind: 'qna' | 'training_file' | 'help_center_article';
+
+    /**
+     * The judge's one-line explanation
+     */
+    reason: string;
+
+    /**
+     * The judge's verdict for this candidate
+     */
+    verdict: 'same_topic' | 'contradicts' | 'different' | 'unclear';
+  }
+
+  export interface Target {
+    /**
+     * ID of the existing item
+     */
+    id: string;
+
+    /**
+     * The item's source identity, for training files and Q&A
+     */
+    externalId: string | null;
+
+    /**
+     * What kind of knowledge item matched: a Q&A entry, a training file / crawled
+     * page, or a live help-center article.
+     */
+    kind: 'qna' | 'training_file' | 'help_center_article';
+
+    /**
+     * Question variants, for Q&A entries
+     */
+    questions: Array<string> | null;
+
+    /**
+     * Q&A revision compared by the judge; null for other kinds. Use with PATCH
+     * expectedRevision.
+     */
+    revision: number | null;
+
+    /**
+     * Heading breadcrumb of the matching section, for training files
+     */
+    section: string | null;
+
+    /**
+     * Cosine similarity between the query and item. Calibrate any threshold using
+     * representative examples; it is not a correctness or contradiction score. `null`
+     * when the item was found by keywords only. Arrays are already ordered closest
+     * first.
+     */
+    similarity: number | null;
+
+    /**
+     * The item's `source` label, for Q&A entries and training files
+     */
+    source: string | null;
+
+    /**
+     * Excerpt of the existing content the judge compared against (Q&A answer, matching
+     * document section, or article body), up to 1200 characters plus an ellipsis when
+     * cut.
+     */
+    text: string;
+
+    /**
+     * Title of the existing item
+     */
+    title: string;
+
+    /**
+     * Public URL of the item when it has one
+     */
+    url: string | null;
+  }
+
+  /**
+   * Where the time went
+   */
+  export interface Timings {
+    /**
+     * Number of judge calls made
+     */
+    judgeCalls: number;
+
+    /**
+     * Time spent in the judge
+     */
+    judgeMs: number;
+
+    /**
+     * Time spent searching
+     */
+    retrievalMs: number;
+  }
+}
+
+export interface TrainingDataOracleParams {
+  /**
+   * Body param: The answer the entry would give. Compared by the judge, never used
+   * as a search query.
+   */
+  answer: string;
+
+  /**
+   * Body param: Question variants this answer applies to (1–50). Phrase them the way
+   * customers ask.
+   */
+  questions: Array<string>;
+
+  /**
+   * Body param: Format of `answer`. `markdown` (default) is stored as-is; `html` is
+   * converted to markdown.
+   */
+  answerFormat?: 'markdown' | 'html';
+
+  /**
+   * Body param: Q&A entry / training file IDs to omit from retrieval. The addressed
+   * Q&A entry is still compared when its content changes.
+   */
+  excludeIds?: Array<string>;
+
+  /**
+   * Body param: Stable identity of the would-be Q&A entry. The oracle only reads; it
+   * never creates or updates it.
+   */
+  externalId?: string;
+
+  /**
+   * Body param: Short label for the would-be entry (also used as a search query)
+   */
+  title?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface TrainingDataSearchParams {
+  /**
+   * Body param: A passage, claim, or question to find existing knowledge for — for
+   * example one section of a document you are about to upload. Compared by meaning
+   * and by keywords.
+   */
+  query: string;
+
+  /**
+   * Body param: Q&A entry / training file IDs to leave out — typically the item you
+   * are about to update.
+   */
+  excludeIds?: Array<string>;
+
+  /**
+   * Body param: Restrict to some kinds of knowledge. Default: all three (Q&A
+   * entries, training files, live help-center articles).
+   */
+  kinds?: Array<'qna' | 'training_file' | 'help_center_article'>;
+
+  /**
+   * Body param: How many items to return (1–20).
+   */
+  topK?: number;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+TrainingData.Files = Files;
+TrainingData.QnaResource = QnaResource;
+
+export declare namespace TrainingData {
+  export {
+    type KnowledgeSearch as KnowledgeSearch,
+    type Oracle as Oracle,
+    type TrainingDataOracleParams as TrainingDataOracleParams,
+    type TrainingDataSearchParams as TrainingDataSearchParams,
+  };
+
+  export {
+    Files as Files,
+    type TrainingFile as TrainingFile,
+    type FileDeleteResponse as FileDeleteResponse,
+    type TrainingFilesCursorPage as TrainingFilesCursorPage,
+    type FileCreateParams as FileCreateParams,
+    type FileRetrieveParams as FileRetrieveParams,
+    type FileUpdateParams as FileUpdateParams,
+    type FileListParams as FileListParams,
+    type FileDeleteParams as FileDeleteParams,
+  };
+
+  export {
+    QnaResource as QnaResource,
+    type Qna as Qna,
+    type QnaDeleteResponse as QnaDeleteResponse,
+    type QnasCursorPage as QnasCursorPage,
+    type QnaCreateParams as QnaCreateParams,
+    type QnaRetrieveParams as QnaRetrieveParams,
+    type QnaUpdateParams as QnaUpdateParams,
+    type QnaListParams as QnaListParams,
+    type QnaDeleteParams as QnaDeleteParams,
+  };
+}

package/src/resources/training-data.ts

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