hebbrix 2.0.2 → 2.2.0

package/dist/index.mjs

@@ -1,3 +1,55 @@
+// 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.degraded === true || data.no_match === true || data.abstain_recommended === 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 };
+    }
+  }
+  return data;
+}
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -77,14 +129,32 @@ 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
+      })
+    });
   }
   /**
    * 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,19 +174,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.searchWithProof(params);
+    return response.results;
+  }
+  /** Search while preserving the automatic ProofLoop evidence context. */
+  async searchWithProof(params) {
     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 response.results;
+    return enforceSearchSafety(response);
   }
   /**
    * Find similar memories
@@ -132,11 +262,69 @@ var SearchResource = class extends BaseResource {
    * Perform reasoning over memories
    */
   async reason(params) {
-    return this.client.post("/v1/search/reason", {
-      query: params.query,
+    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 {
+  /** Create a causal decision bound to search/chat evidence automatically. */
+  async decide(params) {
+    const context = params.proof_context;
+    const token = typeof context === "string" ? context : context?.token;
+    const { proof_context: _context, ...body } = params;
+    return this.client.post("/v1/learning/decisions", {
+      ...body,
+      ...token ? { proof_context_token: token } : {}
+    });
+  }
+  async recordOutcome(decisionId, body) {
+    return this.client.post(`/v1/learning/decisions/${decisionId}/outcomes`, {
+      observations: [],
+      ...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,
-      provider: params.provider,
-      include_steps: params.include_steps || false
+      user_id: params.user_id,
+      limit: params.limit ?? 500
+    });
+  }
+  async proof(decisionId) {
+    return this.client.get(`/v1/learning/decisions/${decisionId}/proof`);
+  }
+  async publicKey(keyId) {
+    return this.client.get("/v1/learning/proof-key", {
+      key_id: keyId
     });
   }
 };
@@ -434,6 +622,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);
@@ -442,11 +632,12 @@ var MemoryClient = class {
     this.consolidation = new ConsolidationResource(this);
     this.memoryTools = new MemoryToolsResource(this);
     this.worldModel = new WorldModelResource(this);
+    this.proofloop = new ProofLoopResource(this);
   }
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.0.0"
+      "User-Agent": "hebbrix-typescript/2.2.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -500,7 +691,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()}`;
@@ -524,6 +719,9 @@ var MemoryClient = class {
   async search(params) {
     return this.searchResource.search(params);
   }
+  async searchWithProof(params) {
+    return this.searchResource.searchWithProof(params);
+  }
   async reason(params) {
     return this.searchResource.reason(params);
   }
@@ -533,12 +731,15 @@ export {
   AuthenticationError,
   CollectionsResource,
   ConsolidationResource,
+  CorrectionsResource,
   HebbrixError,
   MemoriesResource,
   MemoryClient,
+  MemoryJobsResource,
   MemoryToolsResource,
   NotFoundError,
   ProceduralResource,
+  ProofLoopResource,
   RLResource,
   RateLimitError,
   SearchResource,
@@ -546,5 +747,6 @@ export {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource
+  WorldModelResource,
+  enforceSearchSafety
 };

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "hebbrix",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Advanced Memory API for AI Agents with Reinforcement Learning - TypeScript/JavaScript SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [
@@ -19,7 +19,7 @@
   "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"
@@ -47,12 +47,15 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/hebbrix/hebbrix-typescript.git"
+    "url": "git+https://github.com/Hebbrix/hebbrix-typescript.git"
   },
   "bugs": {
     "url": "https://github.com/hebbrix/hebbrix-typescript/issues"
   },
   "homepage": "https://hebbrix.com",
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
     "@types/node": "^20.10.0",
     "@typescript-eslint/eslint-plugin": "^6.15.0",