@z3rno/sdk 0.3.0 → 0.5.0

package/dist/index.js

@@ -341,6 +341,112 @@ var EndSessionResponse = z.object({
   /** Number of memories created during the session. */
   memory_count: z.number()
 });
+var IngestJobResponse = z.object({
+  job_id: z.string(),
+  kind: z.string(),
+  status: z.string(),
+  dataset_id: z.string().nullable().optional(),
+  enqueued_at: z.string()
+});
+var IngestJobStatusResponse = z.object({
+  job_id: z.string(),
+  agent_id: z.string(),
+  dataset_id: z.string().nullable().optional(),
+  kind: z.string(),
+  status: z.string(),
+  source_uri: z.string().nullable().optional(),
+  content_type: z.string().nullable().optional(),
+  filename: z.string().nullable().optional(),
+  file_size: z.number().nullable().optional(),
+  memory_ids: z.array(z.string()).default([]),
+  memos_written: z.number().default(0),
+  distill_job_id: z.string().nullable().optional(),
+  codegraph_memos_written: z.number().default(0),
+  codegraph_edges_written: z.number().default(0),
+  error: z.string().nullable().optional(),
+  warnings: z.array(z.record(z.unknown())).default([]),
+  started_at: z.string().nullable().optional(),
+  completed_at: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional()
+});
+var DistillJobResponse = z.object({
+  job_id: z.string(),
+  status: z.string(),
+  memory_ids: z.array(z.string()),
+  enqueued_at: z.string()
+});
+var DistillJobStatusResponse = z.object({
+  job_id: z.string(),
+  agent_id: z.string(),
+  status: z.string(),
+  model: z.string(),
+  memory_ids: z.array(z.string()),
+  chunk_size: z.number(),
+  chunk_overlap: z.number(),
+  max_concurrency: z.number(),
+  chunks_total: z.number(),
+  chunks_failed: z.number(),
+  entities_extracted: z.number(),
+  relationships_extracted: z.number(),
+  memos_written: z.number(),
+  error: z.string().nullable().optional(),
+  started_at: z.string().nullable().optional(),
+  completed_at: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional()
+});
+var RefineJobResponse = z.object({
+  job_id: z.string(),
+  status: z.string(),
+  dataset_id: z.string().nullable().optional(),
+  enqueued_at: z.string()
+});
+var RefineJobStatusResponse = z.object({
+  job_id: z.string(),
+  status: z.string(),
+  dataset_id: z.string().nullable().optional(),
+  trigger: z.string(),
+  memos_scanned: z.number().default(0),
+  memos_deduped: z.number().default(0),
+  edges_reweighted: z.number().default(0),
+  edges_pruned: z.number().default(0),
+  feedback_drained: z.number().default(0),
+  job_metadata: z.record(z.unknown()).default({}),
+  error: z.string().nullable().optional(),
+  started_at: z.string().nullable().optional(),
+  completed_at: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional()
+});
+var ConversationResponse = z.object({
+  id: z.string(),
+  agent_id: z.string(),
+  user_id: z.string().nullable().optional(),
+  title: z.string().nullable().optional(),
+  summary_cadence: z.number(),
+  turn_count: z.number(),
+  last_summary_turn: z.number(),
+  metadata: z.record(z.unknown()).default({}),
+  created_at: z.string(),
+  updated_at: z.string()
+});
+var TurnAddResponse = z.object({
+  turn_index: z.number(),
+  needs_summary: z.boolean()
+});
+var TurnResponse = z.object({
+  memory_id: z.string(),
+  turn_index: z.number(),
+  turn_role: z.string(),
+  content: z.string(),
+  created_at: z.string()
+});
+var TurnListResponse = z.object({
+  turns: z.array(TurnResponse),
+  total: z.number(),
+  conversation_id: z.string()
+});
 
 // src/client.ts
 var Z3rnoClient = class {
@@ -477,6 +583,9 @@ var Z3rnoClient = class {
       strategy: params.strategy ?? "AUTO",
       rerank: params.rerank ?? false
     };
+    if (params.conversationId) {
+      body.conversation_id = params.conversationId;
+    }
     const resp = await this.request("POST", "/v1/memories/recall", body);
     return RecallResponse.parse(resp);
   }
@@ -720,6 +829,110 @@ var Z3rnoClient = class {
     const resp = await this.request("GET", path);
     return AuditPageResponse.parse(resp);
   }
+  // --- Forge: ingest / distill / refine -------------------------------
+  //
+  // Wrap the server's POST /v1/ingest, /v1/distill, /v1/refine plus the
+  // matching GET status endpoints. The server gates each verb behind an
+  // operator flag (INGEST_ENABLED / DISTILL_ENABLED / REFINE_ENABLED);
+  // when off, these methods throw NotFoundError.
+  async ingestText(params) {
+    const body = {
+      kind: "text",
+      agent_id: params.agentId,
+      text: params.text
+    };
+    if (params.datasetId) body.dataset_id = params.datasetId;
+    const resp = await this.request("POST", "/v1/ingest", body);
+    return IngestJobResponse.parse(resp);
+  }
+  async ingestUrl(params) {
+    const body = {
+      kind: "url",
+      agent_id: params.agentId,
+      url: params.url
+    };
+    if (params.datasetId) body.dataset_id = params.datasetId;
+    const resp = await this.request("POST", "/v1/ingest", body);
+    return IngestJobResponse.parse(resp);
+  }
+  async getIngestStatus(jobId) {
+    const resp = await this.request("GET", `/v1/ingest/${jobId}`);
+    return IngestJobStatusResponse.parse(resp);
+  }
+  async distill(params) {
+    const body = {
+      agent_id: params.agentId,
+      memory_ids: params.memoryIds,
+      include_summary: params.includeSummary ?? true
+    };
+    if (params.chunkSize !== void 0) body.chunk_size = params.chunkSize;
+    if (params.chunkOverlap !== void 0)
+      body.chunk_overlap = params.chunkOverlap;
+    if (params.maxConcurrency !== void 0)
+      body.max_concurrency = params.maxConcurrency;
+    if (params.summaryStyle !== void 0)
+      body.summary_style = params.summaryStyle;
+    const resp = await this.request("POST", "/v1/distill", body);
+    return DistillJobResponse.parse(resp);
+  }
+  async getDistillStatus(jobId) {
+    const resp = await this.request("GET", `/v1/distill/${jobId}`);
+    return DistillJobStatusResponse.parse(resp);
+  }
+  async refine(params) {
+    const body = {};
+    if (params?.datasetId) body.dataset_id = params.datasetId;
+    const resp = await this.request("POST", "/v1/refine", body);
+    return RefineJobResponse.parse(resp);
+  }
+  async getRefineStatus(jobId) {
+    const resp = await this.request("GET", `/v1/refine/${jobId}`);
+    return RefineJobStatusResponse.parse(resp);
+  }
+  // --- Conversations (Phase G slice 2) ---
+  /**
+   * Open a new conversation. Returns the conversation row including
+   * the assigned `id`, which subsequent `recall`s and `addTurn`s
+   * reference. The `summaryCadence` controls how often the server
+   * flags the conversation for summarization.
+   */
+  async createConversation(params) {
+    const body = {
+      agent_id: params.agentId,
+      summary_cadence: params.summaryCadence ?? 10
+    };
+    if (params.userId) body.user_id = params.userId;
+    if (params.title) body.title = params.title;
+    if (params.metadata) body.metadata = params.metadata;
+    const resp = await this.request("POST", "/v1/conversations", body);
+    return ConversationResponse.parse(resp);
+  }
+  async getConversation(conversationId) {
+    const resp = await this.request("GET", `/v1/conversations/${conversationId}`);
+    return ConversationResponse.parse(resp);
+  }
+  /**
+   * Stamp an existing Memo as the next turn of the conversation.
+   * Returns the assigned `turn_index` plus `needs_summary` — when
+   * `true`, the conversation has crossed its cadence threshold.
+   */
+  async addTurn(conversationId, params) {
+    const resp = await this.request(
+      "POST",
+      `/v1/conversations/${conversationId}/turns`,
+      { memory_id: params.memoryId, turn_role: params.turnRole }
+    );
+    return TurnAddResponse.parse(resp);
+  }
+  async listTurns(conversationId, params) {
+    const query = new URLSearchParams();
+    if (params?.afterTurn !== void 0)
+      query.set("after_turn", String(params.afterTurn));
+    query.set("limit", String(params?.limit ?? 50));
+    const path = `/v1/conversations/${conversationId}/turns?${query.toString()}`;
+    const resp = await this.request("GET", path);
+    return TurnListResponse.parse(resp);
+  }
   // --- HTTP layer ---
   async request(method, path, body) {
     let lastError;
@@ -837,6 +1050,155 @@ var Z3rnoClient = class {
   }
 };
 
-export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, EndSessionResponse, ForgetResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, ValidationError, Z3rnoClient, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };
+// src/integrations/vercel-ai.ts
+var Z3rnoVercelMemory = class {
+  client;
+  agentId;
+  conversationId;
+  topK;
+  constructor(options) {
+    this.client = options.client;
+    this.agentId = options.agentId;
+    this.conversationId = options.conversationId;
+    this.topK = options.topK ?? 50;
+  }
+  async messages() {
+    if (this.conversationId) {
+      const page = await this.client.listTurns(this.conversationId, {
+        limit: this.topK
+      });
+      return page.turns.map((t) => ({
+        role: this.normaliseRole(t.turn_role),
+        content: t.content
+      }));
+    }
+    const resp = await this.client.recall({
+      agentId: this.agentId,
+      topK: this.topK,
+      memoryType: "episodic"
+    });
+    const reversed = [...resp.results].reverse();
+    return reversed.map((r) => ({
+      role: this.normaliseRole(
+        (r.metadata ?? {})["role"]
+      ),
+      content: r.content
+    }));
+  }
+  async appendUserMessage(content) {
+    await this.append(content, "user");
+  }
+  async appendAssistantMessage(content) {
+    await this.append(content, "assistant");
+  }
+  async appendToolMessage(content) {
+    await this.append(content, "tool");
+  }
+  async append(content, role) {
+    const memory = await this.client.store({
+      agentId: this.agentId,
+      content,
+      memoryType: "episodic",
+      metadata: { role },
+      relationships: []
+    });
+    if (this.conversationId) {
+      await this.client.addTurn(this.conversationId, {
+        memoryId: memory.id,
+        turnRole: role
+      });
+    }
+  }
+  normaliseRole(raw) {
+    switch (raw) {
+      case "assistant":
+      case "ai":
+        return "assistant";
+      case "system":
+        return "system";
+      case "tool":
+        return "tool";
+      default:
+        return "user";
+    }
+  }
+};
+
+// src/integrations/mastra.ts
+var Z3rnoMastraMemory = class {
+  client;
+  agentId;
+  conversationId;
+  topK;
+  constructor(options) {
+    this.client = options.client;
+    this.agentId = options.agentId;
+    this.conversationId = options.conversationId;
+    this.topK = options.topK ?? 50;
+  }
+  /** Mastra contract: return ordered prior messages for the thread. */
+  async getMessages(_args) {
+    const limit = _args?.limit ?? this.topK;
+    if (this.conversationId) {
+      const page = await this.client.listTurns(this.conversationId, { limit });
+      return page.turns.map((t) => ({
+        role: this.normaliseRole(t.turn_role),
+        content: t.content,
+        threadId: this.conversationId
+      }));
+    }
+    const resp = await this.client.recall({
+      agentId: this.agentId,
+      topK: limit,
+      memoryType: "episodic"
+    });
+    const reversed = [...resp.results].reverse();
+    return reversed.map((r) => ({
+      role: this.normaliseRole(
+        (r.metadata ?? {})["role"]
+      ),
+      content: r.content
+    }));
+  }
+  /** Mastra contract: persist one message. */
+  async addMessage(message) {
+    const memory = await this.client.store({
+      agentId: this.agentId,
+      content: message.content,
+      memoryType: "episodic",
+      metadata: { role: message.role },
+      relationships: []
+    });
+    if (this.conversationId) {
+      await this.client.addTurn(this.conversationId, {
+        memoryId: memory.id,
+        turnRole: message.role
+      });
+    }
+  }
+  /**
+   * Mastra `clear()` — deliberate no-op. Z3rno keeps the source of
+   * truth and recall is already scoped per conversation; flushing
+   * the thread would risk losing audit-relevant history.
+   */
+  async clear() {
+    return;
+  }
+  normaliseRole(raw) {
+    switch (raw) {
+      case "assistant":
+      case "ai":
+        return "assistant";
+      case "system":
+        return "system";
+      case "tool":
+        return "tool";
+      default:
+        return "user";
+    }
+  }
+};
+
+export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, ConversationResponse, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, TurnAddResponse, TurnListResponse, TurnResponse, ValidationError, Z3rnoClient, Z3rnoConnectionError, Z3rnoError, Z3rnoMastraMemory, Z3rnoTimeoutError, Z3rnoVercelMemory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map