hebbrix 2.1.0 → 2.2.1

package/dist/index.mjs

@@ -1,3 +1,57 @@
+// src/safety.ts
+var REQUIRED_FIELDS = [
+  "no_match",
+  "abstain_recommended",
+  "query_confidence",
+  "grounding",
+  "evidence_ids",
+  "safety_contract_version"
+];
+function enforceSearchSafety(response, rowsKey = "results") {
+  const data = { ...response };
+  const rawRows = data[rowsKey];
+  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const missing = REQUIRED_FIELDS.filter(
+    (field) => !Object.prototype.hasOwnProperty.call(data, field)
+  );
+  let reason;
+  if (missing.length > 0) {
+    reason = `missing_safety_fields:${missing.join(",")}`;
+  } else if (typeof data.no_match !== "boolean" || typeof data.abstain_recommended !== "boolean") {
+    reason = "invalid_abstention_fields";
+  } else if (typeof data.query_confidence !== "number" || !Number.isFinite(data.query_confidence) || data.query_confidence < 0 || data.query_confidence > 1) {
+    reason = "invalid_query_confidence";
+  } else if (typeof data.grounding !== "object" || data.grounding === null || Array.isArray(data.grounding)) {
+    reason = "invalid_grounding_receipt";
+  } else if (!Array.isArray(data.evidence_ids)) {
+    reason = "invalid_evidence_ids";
+  } else {
+    const evidenceIds = new Set(data.evidence_ids.map(String));
+    const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
+    if (rowIds.some((value) => !evidenceIds.has(value))) {
+      reason = "rows_not_bound_to_evidence_ids";
+    } else if (data.no_match && (rowIds.length > 0 || evidenceIds.size > 0)) {
+      reason = "no_match_contains_evidence";
+    }
+  }
+  if (reason || data.no_match === true) {
+    data[rowsKey] = [];
+    if (rowsKey === "results") data.total = 0;
+    data.no_match = true;
+    data.abstain_recommended = true;
+    data.query_confidence = 0;
+    data.evidence_ids = [];
+    data.evidence_claims = [];
+    if (reason) {
+      data.sdk_safety_reason = reason;
+      data.grounding = { status: "no_grounded_match", reason };
+    }
+  } else if (data.degraded === true || data.abstain_recommended === true) {
+    data.sdk_safety_reason = "degraded_evidence_preserved";
+  }
+  return data;
+}
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -77,14 +131,104 @@ var MemoriesResource = class extends BaseResource {
    * Create a new memory
    */
   async create(params) {
-    return this.client.post("/v1/memories", params);
+    if (!params.content?.trim() && !params.messages?.length) {
+      throw new TypeError("content or messages must be provided");
+    }
+    const { idempotency_key, ...input } = params;
+    return this.client.request("POST", "/v1/memories", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        source_type: "text",
+        metadata: {},
+        infer: false,
+        wait_for_index: false,
+        ...input
+      })
+    });
+  }
+  /**
+   * Create up to 100 memories with one unambiguous readiness contract.
+   * `wait_for_index=true` resolves only for a fully searchable batch; a server
+   * deadline or indexing failure rejects the request instead of returning a
+   * successful processing receipt.
+   */
+  async createBatch(params) {
+    if (!params.memories?.length || params.memories.length > 100) {
+      throw new TypeError("memories must contain between 1 and 100 items");
+    }
+    if (params.memories.some((item) => !item.content?.trim())) {
+      throw new TypeError("every batch memory must contain non-empty content");
+    }
+    const { idempotency_key, signal, ...body } = params;
+    const receipt = await this.client.request(
+      "POST",
+      "/v1/memories/batch",
+      {
+        headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+        body: JSON.stringify({ wait_for_index: false, ...body }),
+        signal
+      }
+    );
+    if (params.wait_for_index && !(receipt.searchable === true && receipt.processing_status === "completed")) {
+      throw new Error(
+        "wait_for_index batch response was not fully searchable; retry with the same Idempotency-Key"
+      );
+    }
+    return receipt;
+  }
+  /** Poll every item in an asynchronous batch receipt until it is searchable. */
+  async waitForBatchSearchable(receipt, options = {}) {
+    const ids = [...new Set(receipt.memory_ids || [])];
+    if (!ids.length) {
+      throw new Error("batch receipt does not contain memory_ids");
+    }
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      if (options.signal?.aborted) {
+        throw options.signal.reason || new Error("batch readiness polling was aborted");
+      }
+      const rows = await Promise.all(ids.map((id) => this.get(id)));
+      const terminal = rows.find(
+        (row) => ["failed", "cancelled", "canceled"].includes(
+          String(row.processing_status || "").toLowerCase()
+        )
+      );
+      if (terminal) {
+        throw new Error(
+          `memory ${terminal.id} indexing reached terminal state ${terminal.processing_status}`
+        );
+      }
+      if (rows.every((row) => row.searchable === true)) {
+        return {
+          ...receipt,
+          processing_status: "completed",
+          searchable: true,
+          results: ids.map((id) => ({
+            id,
+            memory_id: id,
+            processing_status: "completed"
+          }))
+        };
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`batch was not searchable within ${timeoutMs}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
   }
   /**
    * List memories
    */
-  async list(params = {}) {
+  async listPage(params = {}) {
     return this.client.get("/v1/memories", params);
   }
+  /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+  async list(params = {}) {
+    const page = await this.listPage(params);
+    return page.items;
+  }
   /**
    * Get a specific memory
    */
@@ -104,30 +248,79 @@ var MemoriesResource = class extends BaseResource {
     await this.client.delete(`/v1/memories/${memoryId}`);
   }
 };
+var MemoryJobsResource = class extends BaseResource {
+  async get(jobId) {
+    return this.client.get(`/v1/memory-jobs/${jobId}`);
+  }
+  async wait(jobId, options = {}) {
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const receipt = await this.get(jobId);
+      const status = String(receipt.status || "").toLowerCase();
+      if (["completed", "failed", "cancelled", "canceled"].includes(status)) {
+        return receipt;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`memory job ${jobId} did not finish in ${timeoutMs}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+};
+var CorrectionsResource = class extends BaseResource {
+  async create(params) {
+    const { idempotency_key, ...body } = params;
+    return this.client.request("POST", "/v1/corrections", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        correction_type: "preference",
+        confidence: 1,
+        ...body
+      })
+    });
+  }
+  async relevant(params) {
+    return this.client.get("/v1/corrections/relevant", {
+      include_global: false,
+      limit: 10,
+      ...params
+    });
+  }
+  async get(correctionId) {
+    return this.client.get(`/v1/corrections/${correctionId}`);
+  }
+  async delete(correctionId) {
+    return this.client.delete(`/v1/corrections/${correctionId}`);
+  }
+};
 var SearchResource = class extends BaseResource {
   /**
    * Search memories
    */
   async search(params) {
-    const response = await this.client.post("/v1/search", {
-      query: params.query,
-      collection_id: params.collection_id,
-      limit: params.limit || 10,
-      search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
-    });
+    const response = await this.searchWithProof(params);
     return response.results;
   }
   /** Search while preserving the automatic ProofLoop evidence context. */
   async searchWithProof(params) {
-    return this.client.post("/v1/search", {
+    const response = await this.client.post("/v1/search", {
       query: params.query,
       collection_id: params.collection_id,
       user_id: params.user_id,
+      agent_id: params.agent_id,
+      run_id: params.run_id,
       limit: params.limit || 10,
       search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
+      filters: params.filters || {},
+      fast: params.fast,
+      threshold: params.threshold,
+      include_low_confidence: params.include_low_confidence ?? false,
+      group_by_source: params.group_by_source ?? true,
+      debug: params.debug ?? false
     });
+    return enforceSearchSafety(response);
   }
   /**
    * Find similar memories
@@ -143,12 +336,20 @@ var SearchResource = class extends BaseResource {
    * Perform reasoning over memories
    */
   async reason(params) {
-    return this.client.post("/v1/search/reason", {
-      query: params.query,
-      collection_id: params.collection_id,
-      provider: params.provider,
-      include_steps: params.include_steps || false
-    });
+    const response = await this.client.post(
+      "/v1/search/reason",
+      {
+        query: params.query,
+        collection_id: params.collection_id,
+        provider: params.provider,
+        include_steps: params.include_steps ?? false,
+        user_id: params.user_id,
+        agent_id: params.agent_id,
+        run_id: params.run_id,
+        facets: params.facets ?? []
+      }
+    );
+    return enforceSearchSafety(response, "sources");
   }
 };
 var ProofLoopResource = class extends BaseResource {
@@ -168,11 +369,37 @@ var ProofLoopResource = class extends BaseResource {
       ...body
     });
   }
+  async getDecision(decisionId) {
+    return this.client.get(`/v1/learning/decisions/${decisionId}`);
+  }
+  async defineMetric(params) {
+    return this.client.post("/v1/learning/metrics", params);
+  }
+  async listMetrics(params = {}) {
+    return this.client.get("/v1/learning/metrics", params);
+  }
+  async policyInsights(policyKey, params = {}) {
+    return this.client.get(`/v1/learning/policies/${policyKey}/insights`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      action_key: params.action_keys,
+      context: params.context ? JSON.stringify(params.context) : void 0
+    });
+  }
+  async evaluatePolicy(policyKey, params = {}) {
+    return this.client.post(`/v1/learning/policies/${policyKey}/evaluate`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      limit: params.limit ?? 500
+    });
+  }
   async proof(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}/proof`);
   }
-  async publicKey() {
-    return this.client.get("/v1/learning/proof-key");
+  async publicKey(keyId) {
+    return this.client.get("/v1/learning/proof-key", {
+      key_id: keyId
+    });
   }
 };
 var RLResource = class extends BaseResource {
@@ -213,56 +440,78 @@ var RLResource = class extends BaseResource {
   }
 };
 var ProceduralResource = class extends BaseResource {
+  unwrapProcedure(response) {
+    if (response?.procedure) return response.procedure;
+    if (response?.procedure_id && !response?.id) {
+      return { ...response, id: response.procedure_id };
+    }
+    return response;
+  }
   /**
    * Create a new procedure
    */
   async create(params) {
-    return this.client.post("/procedural", {
+    const response = await this.client.post("/v1/procedures", {
       name: params.name,
       description: params.description,
-      trigger_condition: params.trigger_condition,
-      action_sequence: params.action_sequence,
+      condition: { expression: params.trigger_condition },
+      action: { steps: params.action_sequence },
       collection_id: params.collection_id,
       category: params.category,
-      metadata: params.metadata || {}
+      parameters: params.metadata || {}
     });
+    return this.unwrapProcedure(response);
   }
   /**
    * List procedures
    */
   async list(params) {
-    return this.client.get("/procedural", {
+    const response = await this.client.get("/v1/procedures", {
       collection_id: params?.collection_id,
       category: params?.category,
       skip: params?.skip || 0,
       limit: params?.limit || 100
     });
+    return Array.isArray(response) ? response : response?.procedures || [];
   }
   /**
    * Get a specific procedure
    */
   async get(procedureId) {
-    return this.client.get(`/procedural/${procedureId}`);
+    const response = await this.client.get(`/v1/procedures/${procedureId}`);
+    return this.unwrapProcedure(response);
   }
   /**
    * Execute a procedure
    */
   async execute(procedureId, context) {
-    return this.client.post(`/procedural/${procedureId}/execute`, {
-      context: context || {}
+    const response = await this.client.post(`/v1/procedures/${procedureId}/execute`, {
+      input_state: context || {}
     });
+    return response?.execution_result || response;
   }
   /**
    * Update a procedure
    */
   async update(procedureId, params) {
-    return this.client.patch(`/procedural/${procedureId}`, params);
+    const body = {};
+    if (params.name !== void 0) body.name = params.name;
+    if (params.description !== void 0) body.description = params.description;
+    if (params.trigger_condition !== void 0) {
+      body.condition = { expression: params.trigger_condition };
+    }
+    if (params.action_sequence !== void 0) {
+      body.action = { steps: params.action_sequence };
+    }
+    if (params.metadata !== void 0) body.parameters = params.metadata;
+    const response = await this.client.patch(`/v1/procedures/${procedureId}`, body);
+    return this.unwrapProcedure(response);
   }
   /**
    * Delete a procedure
    */
   async delete(procedureId) {
-    await this.client.delete(`/procedural/${procedureId}`);
+    await this.client.delete(`/v1/procedures/${procedureId}`);
   }
 };
 var TemporalResource = class extends BaseResource {
@@ -301,6 +550,10 @@ var TemporalResource = class extends BaseResource {
       entity
     });
   }
+  /** Permanently delete a tenant-scoped temporal fact by stable ID. */
+  async deleteFact(factId) {
+    return this.client.delete(`/temporal/facts/${factId}`);
+  }
 };
 var WorkingMemoryResource = class extends BaseResource {
   /**
@@ -469,6 +722,8 @@ var MemoryClient = class {
     this.auth = new AuthResource(this);
     this.collections = new CollectionsResource(this);
     this.memories = new MemoriesResource(this);
+    this.memoryJobs = new MemoryJobsResource(this);
+    this.corrections = new CorrectionsResource(this);
     this.searchResource = new SearchResource(this);
     this.rl = new RLResource(this);
     this.procedural = new ProceduralResource(this);
@@ -482,7 +737,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.1.0"
+      "User-Agent": "hebbrix-typescript/2.2.1"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -491,7 +746,8 @@ var MemoryClient = class {
   }
   handleError(response, data) {
     const statusCode = response.status;
-    const message = data?.error?.message || data?.detail || response.statusText;
+    const detail = data?.detail;
+    const message = data?.error?.message || (typeof detail === "string" ? detail : detail?.message) || response.statusText;
     if (statusCode === 401) {
       throw new AuthenticationError(message);
     } else if (statusCode === 404) {
@@ -509,21 +765,29 @@ var MemoryClient = class {
   }
   async request(method, path, options = {}) {
     const url = `${this.baseUrl}${path}`;
+    const { headers: requestHeaders, signal: requestSignal, ...requestOptions } = options;
     const response = await fetch(url, {
+      ...requestOptions,
       method,
       headers: {
         ...this.getHeaders(),
-        ...options.headers || {}
+        ...requestHeaders || {}
       },
-      ...options,
-      signal: AbortSignal.timeout(this.timeout)
+      signal: requestSignal || AbortSignal.timeout(this.timeout)
     });
-    let data;
+    let data = void 0;
     const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      data = await response.json();
-    } else {
-      data = await response.text();
+    const responseText = await response.text();
+    if (responseText) {
+      if (contentType?.includes("application/json")) {
+        try {
+          data = JSON.parse(responseText);
+        } catch {
+          data = { detail: responseText };
+        }
+      } else {
+        data = responseText;
+      }
     }
     if (!response.ok) {
       this.handleError(response, data);
@@ -536,7 +800,11 @@ var MemoryClient = class {
       const searchParams = new URLSearchParams();
       Object.entries(params).forEach(([key, value]) => {
         if (value !== void 0 && value !== null) {
-          searchParams.append(key, String(value));
+          if (Array.isArray(value)) {
+            value.forEach((item) => searchParams.append(key, String(item)));
+          } else {
+            searchParams.append(key, String(value));
+          }
         }
       });
       url += `?${searchParams.toString()}`;
@@ -572,9 +840,11 @@ export {
   AuthenticationError,
   CollectionsResource,
   ConsolidationResource,
+  CorrectionsResource,
   HebbrixError,
   MemoriesResource,
   MemoryClient,
+  MemoryJobsResource,
   MemoryToolsResource,
   NotFoundError,
   ProceduralResource,
@@ -586,5 +856,6 @@ export {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource
+  WorldModelResource,
+  enforceSearchSafety
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hebbrix",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Advanced Memory API for AI Agents with Reinforcement Learning - TypeScript/JavaScript SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,12 +14,13 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "jest",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "prepublishOnly": "npm run build"