@z3rno/sdk 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -38,6 +38,15 @@ type MemoryType = z.infer<typeof MemoryType>;
 declare const RelationshipType: z.ZodEnum<["derived_from", "contradicts", "supports", "supersedes", "related_to", "caused_by"]>;
 /** Relationship type between two memories. */
 type RelationshipType = z.infer<typeof RelationshipType>;
+/**
+ * Retrieval strategy for `recall({ strategy: ... })` — Phase C.
+ *
+ * `AUTO` is the default; the server's LLM router picks one of the
+ * others when configured. Use an explicit value to bypass routing.
+ */
+declare const RetrievalStrategy: z.ZodEnum<["AUTO", "VECTOR", "LEXICAL", "GRAPH", "TRIPLET", "TRACE", "TEMPORAL", "ASK", "CYPHER"]>;
+/** Retrieval strategy enum (canonical UPPERCASE names). */
+type RetrievalStrategy = z.infer<typeof RetrievalStrategy>;
 /**
  * Schema for storing a new memory.
  *
@@ -192,6 +201,11 @@ declare const RecallResultItem: z.ZodObject<{
     created_at: z.ZodString;
     /** Arbitrary metadata attached to the memory. */
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Phase C per-source signals — e.g. `{ vector: 0.83, lexical: 0.61 }`.
+     * Optional so older servers (v0.7.x) keep parsing.
+     */
+    score_components: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     content: string;
     metadata: Record<string, unknown>;
@@ -202,6 +216,7 @@ declare const RecallResultItem: z.ZodObject<{
     memory_id: string;
     similarity_score: number;
     relevance_score: number;
+    score_components: Record<string, number>;
     summary?: string | null | undefined;
 }, {
     content: string;
@@ -214,6 +229,7 @@ declare const RecallResultItem: z.ZodObject<{
     relevance_score: number;
     metadata?: Record<string, unknown> | undefined;
     summary?: string | null | undefined;
+    score_components?: Record<string, number> | undefined;
 }>;
 /** Parsed type for a single recall result item. */
 type RecallResultItem = z.infer<typeof RecallResultItem>;
@@ -245,6 +261,11 @@ declare const RecallResponse: z.ZodObject<{
         created_at: z.ZodString;
         /** Arbitrary metadata attached to the memory. */
         metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /**
+         * Phase C per-source signals — e.g. `{ vector: 0.83, lexical: 0.61 }`.
+         * Optional so older servers (v0.7.x) keep parsing.
+         */
+        score_components: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         content: string;
         metadata: Record<string, unknown>;
@@ -255,6 +276,7 @@ declare const RecallResponse: z.ZodObject<{
         memory_id: string;
         similarity_score: number;
         relevance_score: number;
+        score_components: Record<string, number>;
         summary?: string | null | undefined;
     }, {
         content: string;
@@ -267,11 +289,20 @@ declare const RecallResponse: z.ZodObject<{
         relevance_score: number;
         metadata?: Record<string, unknown> | undefined;
         summary?: string | null | undefined;
+        score_components?: Record<string, number> | undefined;
     }>, "many">;
     /** Total number of matches (may exceed `topK`). */
     total: z.ZodNumber;
     /** The query that was searched, if any. */
     query: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Phase C: strategy that actually ran (after AUTO routing + re-rank). */
+    strategy_used: z.ZodDefault<z.ZodString>;
+    /** Phase C: AUTO's candidate list (e.g. `["AUTO->GRAPH"]`). */
+    strategies_considered: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Phase C: whether the cross-encoder re-rank ran. */
+    reranked: z.ZodDefault<z.ZodBoolean>;
+    /** Phase C: end-to-end recall latency on the server (ms). */
+    elapsed_ms: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     results: {
         content: string;
@@ -283,9 +314,14 @@ declare const RecallResponse: z.ZodObject<{
         memory_id: string;
         similarity_score: number;
         relevance_score: number;
+        score_components: Record<string, number>;
         summary?: string | null | undefined;
     }[];
     total: number;
+    strategy_used: string;
+    strategies_considered: string[];
+    reranked: boolean;
+    elapsed_ms: number;
     query?: string | null | undefined;
 }, {
     results: {
@@ -299,9 +335,14 @@ declare const RecallResponse: z.ZodObject<{
         relevance_score: number;
         metadata?: Record<string, unknown> | undefined;
         summary?: string | null | undefined;
+        score_components?: Record<string, number> | undefined;
     }[];
     total: number;
     query?: string | null | undefined;
+    strategy_used?: string | undefined;
+    strategies_considered?: string[] | undefined;
+    reranked?: boolean | undefined;
+    elapsed_ms?: number | undefined;
 }>;
 /** Parsed type for a recall response. */
 type RecallResponse = z.infer<typeof RecallResponse>;
@@ -714,6 +755,240 @@ declare const EndSessionResponse: z.ZodObject<{
 }>;
 /** Parsed type for an end-session response. */
 type EndSessionResponse = z.infer<typeof EndSessionResponse>;
+/** Response to POST /v1/ingest — the enqueue ack. */
+declare const IngestJobResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    kind: z.ZodString;
+    status: z.ZodString;
+    dataset_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enqueued_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    job_id: string;
+    kind: string;
+    enqueued_at: string;
+    dataset_id?: string | null | undefined;
+}, {
+    status: string;
+    job_id: string;
+    kind: string;
+    enqueued_at: string;
+    dataset_id?: string | null | undefined;
+}>;
+type IngestJobResponse = z.infer<typeof IngestJobResponse>;
+/** Full state from GET /v1/ingest/{job_id}. */
+declare const IngestJobStatusResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    agent_id: z.ZodString;
+    dataset_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodString;
+    status: z.ZodString;
+    source_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    content_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    filename: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_size: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    memory_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    memos_written: z.ZodDefault<z.ZodNumber>;
+    distill_job_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    codegraph_memos_written: z.ZodDefault<z.ZodNumber>;
+    codegraph_edges_written: z.ZodDefault<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    agent_id: string;
+    memory_ids: string[];
+    job_id: string;
+    kind: string;
+    memos_written: number;
+    codegraph_memos_written: number;
+    codegraph_edges_written: number;
+    warnings: Record<string, unknown>[];
+    created_at?: string | null | undefined;
+    started_at?: string | null | undefined;
+    dataset_id?: string | null | undefined;
+    source_uri?: string | null | undefined;
+    content_type?: string | null | undefined;
+    filename?: string | null | undefined;
+    file_size?: number | null | undefined;
+    distill_job_id?: string | null | undefined;
+    error?: string | null | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+}, {
+    status: string;
+    agent_id: string;
+    job_id: string;
+    kind: string;
+    created_at?: string | null | undefined;
+    memory_ids?: string[] | undefined;
+    started_at?: string | null | undefined;
+    dataset_id?: string | null | undefined;
+    source_uri?: string | null | undefined;
+    content_type?: string | null | undefined;
+    filename?: string | null | undefined;
+    file_size?: number | null | undefined;
+    memos_written?: number | undefined;
+    distill_job_id?: string | null | undefined;
+    codegraph_memos_written?: number | undefined;
+    codegraph_edges_written?: number | undefined;
+    error?: string | null | undefined;
+    warnings?: Record<string, unknown>[] | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+}>;
+type IngestJobStatusResponse = z.infer<typeof IngestJobStatusResponse>;
+/** Distill enqueue ack. */
+declare const DistillJobResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    status: z.ZodString;
+    memory_ids: z.ZodArray<z.ZodString, "many">;
+    enqueued_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    memory_ids: string[];
+    job_id: string;
+    enqueued_at: string;
+}, {
+    status: string;
+    memory_ids: string[];
+    job_id: string;
+    enqueued_at: string;
+}>;
+type DistillJobResponse = z.infer<typeof DistillJobResponse>;
+/** Full distill job state. */
+declare const DistillJobStatusResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    agent_id: z.ZodString;
+    status: z.ZodString;
+    model: z.ZodString;
+    memory_ids: z.ZodArray<z.ZodString, "many">;
+    chunk_size: z.ZodNumber;
+    chunk_overlap: z.ZodNumber;
+    max_concurrency: z.ZodNumber;
+    chunks_total: z.ZodNumber;
+    chunks_failed: z.ZodNumber;
+    entities_extracted: z.ZodNumber;
+    relationships_extracted: z.ZodNumber;
+    memos_written: z.ZodNumber;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    agent_id: string;
+    memory_ids: string[];
+    job_id: string;
+    memos_written: number;
+    model: string;
+    chunk_size: number;
+    chunk_overlap: number;
+    max_concurrency: number;
+    chunks_total: number;
+    chunks_failed: number;
+    entities_extracted: number;
+    relationships_extracted: number;
+    created_at?: string | null | undefined;
+    started_at?: string | null | undefined;
+    error?: string | null | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+}, {
+    status: string;
+    agent_id: string;
+    memory_ids: string[];
+    job_id: string;
+    memos_written: number;
+    model: string;
+    chunk_size: number;
+    chunk_overlap: number;
+    max_concurrency: number;
+    chunks_total: number;
+    chunks_failed: number;
+    entities_extracted: number;
+    relationships_extracted: number;
+    created_at?: string | null | undefined;
+    started_at?: string | null | undefined;
+    error?: string | null | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+}>;
+type DistillJobStatusResponse = z.infer<typeof DistillJobStatusResponse>;
+/** Refine enqueue ack. */
+declare const RefineJobResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    status: z.ZodString;
+    dataset_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enqueued_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    job_id: string;
+    enqueued_at: string;
+    dataset_id?: string | null | undefined;
+}, {
+    status: string;
+    job_id: string;
+    enqueued_at: string;
+    dataset_id?: string | null | undefined;
+}>;
+type RefineJobResponse = z.infer<typeof RefineJobResponse>;
+/** Full refine job state. */
+declare const RefineJobStatusResponse: z.ZodObject<{
+    job_id: z.ZodString;
+    status: z.ZodString;
+    dataset_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger: z.ZodString;
+    memos_scanned: z.ZodDefault<z.ZodNumber>;
+    memos_deduped: z.ZodDefault<z.ZodNumber>;
+    edges_reweighted: z.ZodDefault<z.ZodNumber>;
+    edges_pruned: z.ZodDefault<z.ZodNumber>;
+    feedback_drained: z.ZodDefault<z.ZodNumber>;
+    job_metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    job_id: string;
+    trigger: string;
+    memos_scanned: number;
+    memos_deduped: number;
+    edges_reweighted: number;
+    edges_pruned: number;
+    feedback_drained: number;
+    job_metadata: Record<string, unknown>;
+    created_at?: string | null | undefined;
+    started_at?: string | null | undefined;
+    dataset_id?: string | null | undefined;
+    error?: string | null | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+}, {
+    status: string;
+    job_id: string;
+    trigger: string;
+    created_at?: string | null | undefined;
+    started_at?: string | null | undefined;
+    dataset_id?: string | null | undefined;
+    error?: string | null | undefined;
+    completed_at?: string | null | undefined;
+    updated_at?: string | null | undefined;
+    memos_scanned?: number | undefined;
+    memos_deduped?: number | undefined;
+    edges_reweighted?: number | undefined;
+    edges_pruned?: number | undefined;
+    feedback_drained?: number | undefined;
+    job_metadata?: Record<string, unknown> | undefined;
+}>;
+type RefineJobStatusResponse = z.infer<typeof RefineJobStatusResponse>;
 
 /**
  * Z3rno TypeScript SDK client.
@@ -910,6 +1185,18 @@ declare class Z3rnoClient {
         filters?: Record<string, unknown>;
         topK?: number;
         similarityThreshold?: number;
+        /**
+         * Phase C: retrieval strategy. One of `AUTO | VECTOR | LEXICAL |
+         * GRAPH | TRIPLET | TRACE | TEMPORAL | ASK | CYPHER`. Default
+         * `"AUTO"` — server's LLM router picks per query.
+         */
+        strategy?: string;
+        /**
+         * Phase C: cross-encoder re-ranking. When `true`, the server
+         * re-ranks the strategy's top results. Requires
+         * `sentence-transformers` on the server side.
+         */
+        rerank?: boolean;
     }): Promise<RecallResponse>;
     /**
      * Forgets (deletes) one or more memories.
@@ -1106,6 +1393,31 @@ declare class Z3rnoClient {
         page?: number;
         pageSize?: number;
     }): Promise<AuditPageResponse>;
+    ingestText(params: {
+        agentId: string;
+        text: string;
+        datasetId?: string;
+    }): Promise<IngestJobResponse>;
+    ingestUrl(params: {
+        agentId: string;
+        url: string;
+        datasetId?: string;
+    }): Promise<IngestJobResponse>;
+    getIngestStatus(jobId: string): Promise<IngestJobStatusResponse>;
+    distill(params: {
+        agentId: string;
+        memoryIds: string[];
+        chunkSize?: number;
+        chunkOverlap?: number;
+        maxConcurrency?: number;
+        summaryStyle?: string;
+        includeSummary?: boolean;
+    }): Promise<DistillJobResponse>;
+    getDistillStatus(jobId: string): Promise<DistillJobStatusResponse>;
+    refine(params?: {
+        datasetId?: string;
+    }): Promise<RefineJobResponse>;
+    getRefineStatus(jobId: string): Promise<RefineJobStatusResponse>;
     private request;
     private sleep;
     private handleResponse;
@@ -1310,4 +1622,4 @@ declare class Z3rnoConnectionError extends Z3rnoError {
     constructor(message: string);
 }
 
-export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, EndSessionResponse, ForgetResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, ServerError, SessionResponse, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };
+export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };