hebbrix 2.0.2 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hebbrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,6 +14,7 @@ Official TypeScript/JavaScript SDK for the Hebbrix api - **the only memory API w
 - ✅ **Procedural Memory** - Store and execute learned skills
 - ✅ **Working Memory** - Short-term context buffer for conversations
 - ✅ **Memory Consolidation** - Automatic compression of episodic memories
+- ✅ **ProofLoop** - Learn from outcomes with automatic, verifiable evidence receipts
 - ✅ **Promise-based** - Native async/await support
 - ✅ **Type-safe** - Complete TypeScript type definitions
 - ✅ **Universal** - Works in Node.js and browsers
@@ -73,6 +74,28 @@ const main = async () => {
 main();
 ```
 
+## ProofLoop: search → decision → outcome → proof
+
+```typescript
+const search = await client.searchWithProof({
+  query: 'What should the agent do next?',
+  collection_id: 'collection-42',
+  user_id: 'customer-7',
+});
+const decision = await client.proofloop.decide({
+  policy_key: 'agent.next_action',
+  candidates: [{ action_key: 'act' }, { action_key: 'ask' }],
+  collection_id: 'collection-42',
+  user_id: 'customer-7',
+  proof_context: search.proof_context,
+});
+await client.proofloop.recordOutcome(decision.decision_id, {
+  success: true,
+  idempotency_key: 'run-123-result',
+});
+const proof = await client.proofloop.proof(decision.decision_id);
+```
+
 ## 📚 Complete API Guide
 
 ### 1. Authentication

package/dist/index.d.mts

@@ -17,7 +17,7 @@ interface User {
     full_name: string;
     is_active: boolean;
     is_verified: boolean;
-    tier: 'free' | 'starter' | 'pro' | 'enterprise';
+    tier: "free" | "starter" | "pro" | "enterprise";
 }
 interface Collection {
     id: string;
@@ -57,6 +57,49 @@ interface SearchResponse {
     total: number;
     search_type: string;
     processing_time_ms: number;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
+    proof_context?: ProofContext;
+}
+interface GroundingReceipt {
+    status: string;
+    reason?: string;
+    contract_version?: string;
+    [key: string]: unknown;
+}
+interface EvidenceClaim {
+    memory_id: string;
+    claims: Record<string, unknown>;
+}
+interface ProofContext {
+    schema_version: "proofloop-context-v1";
+    context_id: string;
+    token: string;
+    manifest_digest: string;
+    evidence_manifest: Record<string, any>;
+    trace_id?: string;
+    issued_at: string;
+    expires_at: string;
+}
+interface ProofLoopCandidate {
+    action_key: string;
+    description?: string;
+    features?: Record<string, any>;
+}
+interface ProofLoopDecisionParams {
+    policy_key: string;
+    candidates: ProofLoopCandidate[];
+    proof_context?: ProofContext | string;
+    collection_id?: string;
+    user_id?: string;
+    [key: string]: any;
 }
 interface ReasoningSource {
     memory_id: string;
@@ -64,9 +107,18 @@ interface ReasoningSource {
     score: number;
 }
 interface ReasoningResponse {
-    answer: string;
+    answer: string | null;
     sources: ReasoningSource[];
     metadata: Record<string, any>;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
     reasoning_context?: Record<string, any>;
 }
 interface CreateCollectionParams {
@@ -80,35 +132,137 @@ interface UpdateCollectionParams {
     metadata?: Record<string, any>;
 }
 interface CreateMemoryParams {
-    collection_id: string;
-    content: string;
+    collection_id?: string;
+    content?: string;
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
     importance?: number;
     source_type?: string;
     source_reference?: string;
     metadata?: Record<string, any>;
+    infer?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    app_id?: string;
+    namespace?: string;
+    wait_for_index?: boolean;
+    async_dispatch?: boolean;
+    title?: string;
+    tags?: string[];
+    source?: string;
+    /** Stable retry key sent as the Idempotency-Key transport header. */
+    idempotency_key?: string;
+}
+interface MemoryAddResult {
+    id: string;
+    memory_id?: string;
+    event: "ADD" | "UPDATE" | "NOOP" | string;
+    memory?: string;
+    reason?: string;
+}
+interface MemoryAddResponse {
+    results: MemoryAddResult[];
+    collection_id?: string;
+    processing_status: string;
+    searchable: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
+    job_id?: string;
+    created_count: number;
+    updated_count: number;
+    skipped_count: number;
 }
 interface UpdateMemoryParams {
     content?: string;
     importance?: number;
     metadata?: Record<string, any>;
+    wait_for_index?: boolean;
 }
 interface SearchParams {
     query: string;
     collection_id?: string;
     limit?: number;
-    search_type?: 'hybrid' | 'vector' | 'bm25' | 'graph';
+    search_type?: "hybrid" | "vector" | "bm25" | "graph";
     filters?: Record<string, any>;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    fast?: boolean;
+    threshold?: number;
+    include_low_confidence?: boolean;
+    group_by_source?: boolean;
+    debug?: boolean;
 }
 interface ReasonParams {
     query: string;
     collection_id?: string;
-    provider?: 'gemini' | 'openai' | 'anthropic';
+    provider?: "gemini" | "openai" | "anthropic";
     include_steps?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    facets?: string[];
 }
 interface ListParams {
     skip?: number;
     limit?: number;
 }
+interface MemoryListParams {
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    scope?: "all";
+    cursor?: string;
+    limit?: number;
+    include_superseded?: boolean;
+}
+interface CursorPage<T> {
+    items: T[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    total_count: number;
+}
+interface MemoryJobReceipt {
+    job_id?: string;
+    status: string;
+    [key: string]: any;
+}
+interface CorrectionCreateParams {
+    corrected_content: string;
+    correction_type?: "preference" | "factual" | "procedural" | string;
+    original_content?: string;
+    context?: string;
+    memory_id?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    confidence?: number;
+    metadata?: Record<string, any>;
+    idempotency_key?: string;
+}
+interface CorrectionSearchParams {
+    query: string;
+    correction_type?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    include_global?: boolean;
+    limit?: number;
+}
+interface ProofLoopMetricParams {
+    policy_key: string;
+    metric_key: string;
+    name: string;
+    min_value: number;
+    max_value: number;
+    collection_id?: string;
+    user_id?: string;
+    [key: string]: any;
+}
 interface APIKeyResponse {
     id: string;
     name: string;
@@ -169,13 +323,13 @@ declare class MemoriesResource extends BaseResource {
     /**
      * Create a new memory
      */
-    create(params: CreateMemoryParams): Promise<Memory>;
+    create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
     /**
      * List memories
      */
-    list(params?: ListParams & {
-        collection_id?: string;
-    }): Promise<Memory[]>;
+    listPage(params?: MemoryListParams): Promise<CursorPage<Memory>>;
+    /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+    list(params?: MemoryListParams): Promise<Memory[]>;
     /**
      * Get a specific memory
      */
@@ -189,11 +343,26 @@ declare class MemoriesResource extends BaseResource {
      */
     delete(memoryId: string): Promise<void>;
 }
+declare class MemoryJobsResource extends BaseResource {
+    get(jobId: string): Promise<MemoryJobReceipt>;
+    wait(jobId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<MemoryJobReceipt>;
+}
+declare class CorrectionsResource extends BaseResource {
+    create(params: CorrectionCreateParams): Promise<Record<string, any>>;
+    relevant(params: CorrectionSearchParams): Promise<Array<Record<string, any>>>;
+    get(correctionId: string): Promise<Record<string, any>>;
+    delete(correctionId: string): Promise<Record<string, any>>;
+}
 declare class SearchResource extends BaseResource {
     /**
      * Search memories
      */
     search(params: SearchParams): Promise<SearchResult[]>;
+    /** Search while preserving the automatic ProofLoop evidence context. */
+    searchWithProof(params: SearchParams): Promise<SearchResponse>;
     /**
      * Find similar memories
      */
@@ -203,6 +372,36 @@ declare class SearchResource extends BaseResource {
      */
     reason(params: ReasonParams): Promise<ReasoningResponse>;
 }
+declare class ProofLoopResource extends BaseResource {
+    /** Create a causal decision bound to search/chat evidence automatically. */
+    decide(params: ProofLoopDecisionParams): Promise<Record<string, any>>;
+    recordOutcome(decisionId: string, body: {
+        observations?: Record<string, any>[];
+        reward?: number;
+        success?: boolean;
+        idempotency_key?: string;
+    }): Promise<Record<string, any>>;
+    getDecision(decisionId: string): Promise<Record<string, any>>;
+    defineMetric(params: ProofLoopMetricParams): Promise<Record<string, any>>;
+    listMetrics(params?: {
+        policy_key?: string;
+        collection_id?: string;
+        user_id?: string;
+    }): Promise<Record<string, any>>;
+    policyInsights(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        action_keys?: string[];
+        context?: Record<string, any>;
+    }): Promise<Record<string, any>>;
+    evaluatePolicy(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        limit?: number;
+    }): Promise<Record<string, any>>;
+    proof(decisionId: string): Promise<Record<string, any>>;
+    publicKey(keyId?: string): Promise<Record<string, any>>;
+}
 declare class RLResource extends BaseResource {
     /**
      * Train the Memory Manager agent using RL
@@ -372,10 +571,6 @@ declare class WorldModelResource extends BaseResource {
     plan(goal: string, collectionId?: string): Promise<any>;
 }
 
-/**
- * Main Hebbrix client
- */
-
 declare class MemoryClient {
     private apiKey?;
     private baseUrl;
@@ -383,6 +578,8 @@ declare class MemoryClient {
     auth: AuthResource;
     collections: CollectionsResource;
     memories: MemoriesResource;
+    memoryJobs: MemoryJobsResource;
+    corrections: CorrectionsResource;
     private searchResource;
     rl: RLResource;
     procedural: ProceduralResource;
@@ -391,6 +588,7 @@ declare class MemoryClient {
     consolidation: ConsolidationResource;
     memoryTools: MemoryToolsResource;
     worldModel: WorldModelResource;
+    proofloop: ProofLoopResource;
     constructor(config?: ClientConfig);
     private getHeaders;
     private handleError;
@@ -400,6 +598,7 @@ declare class MemoryClient {
     patch<T = any>(path: string, body?: any): Promise<T>;
     delete<T = any>(path: string): Promise<T>;
     search(params: SearchParams): Promise<SearchResult[]>;
+    searchWithProof(params: SearchParams): Promise<SearchResponse>;
     reason(params: ReasonParams): Promise<ReasoningResponse>;
 }
 
@@ -427,4 +626,24 @@ declare class ServerError extends HebbrixError {
     constructor(message?: string);
 }
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CreateCollectionParams, type CreateMemoryParams, HebbrixError, type ListParams, MemoriesResource, type Memory, MemoryClient, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource };
+interface SafetyEnvelope {
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: unknown[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validate the API-owned grounding receipt before exposing evidence to an agent.
+ * A malformed, degraded, abstaining, or ungrounded response is converted into
+ * one deterministic no-match envelope. This prevents SDK/API contract drift
+ * from turning a nearest neighbour into verified evidence.
+ */
+declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
+
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, type EvidenceClaim, type GroundingReceipt, HebbrixError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource, enforceSearchSafety };