@aiqa/sdk 1.3.0 → 1.4.0

package/README.md

@@ -138,6 +138,16 @@ Adds a fact to the active application (Promise-based).
   ```typescript
   {
     id: string;
+    /**
+     * Optional. Stable identifier for the underlying question, shared across
+     * applications and conversations. When provided it is used to look up (or
+     * create) the matching question row in the database instead of `id`. When
+     * omitted, `id` is used (legacy behavior).
+     *
+     * Keep this consistent across calls for the "same" question — see
+     * "Question identity and questionId" below.
+     */
+    questionId?: string;
     question: string;
     expected_answer: any;
     answer_format: { type: "STRING" }
@@ -158,6 +168,7 @@ Adds a fact to the active application (Promise-based).
 ```typescript
 const isMatched = await sdk.addFact({
   id: "fact-123",
+  questionId: "agreement-q",
   question: "Do you agree?",
   expected_answer: "Yes",
   answer_format: { type: "STRING" },
@@ -165,6 +176,37 @@ const isMatched = await sdk.addFact({
 });
 ```
 
+##### Question identity and `questionId`
+
+`id` identifies an instance of a fact within a single conversation. `questionId`
+is an optional field that identifies the underlying question across every
+application and conversation that asks it. They're separated so you can give
+each fact instance its own `id` (e.g. a per-call uuid) while still pointing at a
+stable question identity.
+
+Two server-side features are scoped per question identity:
+
+- **Accuracy improvements.** Per-question signals (flags, model tweaks, fuzzy
+  matches) accumulate against the question row. Splitting the same logical
+  question across multiple identities splits these signals and resets the
+  accuracy gains you've already earned.
+- **Remaps from the management dashboard.** When an operator remaps a question
+  in the dashboard, the remap is stored on the question row. A subsequent call
+  with a different identity won't pick up the remap.
+
+The "question identity" the server uses is `questionId` if you sent one,
+otherwise `id`. So:
+
+- If your `id` is already stable across calls for the same logical question,
+  omitting `questionId` is fine — both features above still work, just keyed off
+  `id`.
+- If your `id` varies per call (per-call uuid, ephemeral instance id, etc.),
+  send a stable `questionId`. Otherwise each call looks like a new question and
+  you lose the features above.
+- Once you've picked an identity for a question, don't change it. If you must
+  rename, coordinate with the team owning the dashboard so remaps and
+  historical signals can be migrated.
+
 #### `getFacts()`
 
 Retrieves all facts for the application (Promise-based). Each fact includes a `metadata` field containing whatever was passed to `addFact()`. Facts added without `metadata` return `{}`.
@@ -289,6 +331,16 @@ type ApplicationFact = ApplicationFactInput & {
 ```typescript
 type ApplicationFactInput = {
   id: string;
+  /**
+   * Optional. Stable identifier for the underlying question, shared across
+   * applications and conversations. Used to look up (or create) the matching
+   * question row in the database when provided. When omitted, `id` is used.
+   *
+   * Keep this consistent across calls — accuracy improvements and remaps
+   * configured in the management dashboard are scoped per `questionId`. See
+   * "Question identity and questionId" under `addFact()`.
+   */
+  questionId?: string;
   question: string;
   expected_answer: any;
   answer_format: {

package/dist/browser/browser.d.ts

@@ -54,6 +54,14 @@ type ApplicationFactAnswerFormat = {
 };
 type ApplicationFactInput = {
     id: string;
+    /**
+     * Stable identifier for the underlying question, shared across applications and
+     * conversations. When provided it is used to look up (or create) the matching
+     * question row in the database instead of `id`. Keep this consistent across
+     * calls — accuracy improvements and remaps configured in the management
+     * dashboard are scoped per `questionId`.
+     */
+    questionId?: string;
     question: string;
     expected_answer: any;
     answer_format: ApplicationFactAnswerFormat;

package/dist/browser/browser.js

@@ -3396,7 +3396,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "1.2.0",
+  version: "1.4.0-develop.1",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",