@z3rno/sdk 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -343,6 +343,112 @@ var EndSessionResponse = zod.z.object({
   /** Number of memories created during the session. */
   memory_count: zod.z.number()
 });
+var IngestJobResponse = zod.z.object({
+  job_id: zod.z.string(),
+  kind: zod.z.string(),
+  status: zod.z.string(),
+  dataset_id: zod.z.string().nullable().optional(),
+  enqueued_at: zod.z.string()
+});
+var IngestJobStatusResponse = zod.z.object({
+  job_id: zod.z.string(),
+  agent_id: zod.z.string(),
+  dataset_id: zod.z.string().nullable().optional(),
+  kind: zod.z.string(),
+  status: zod.z.string(),
+  source_uri: zod.z.string().nullable().optional(),
+  content_type: zod.z.string().nullable().optional(),
+  filename: zod.z.string().nullable().optional(),
+  file_size: zod.z.number().nullable().optional(),
+  memory_ids: zod.z.array(zod.z.string()).default([]),
+  memos_written: zod.z.number().default(0),
+  distill_job_id: zod.z.string().nullable().optional(),
+  codegraph_memos_written: zod.z.number().default(0),
+  codegraph_edges_written: zod.z.number().default(0),
+  error: zod.z.string().nullable().optional(),
+  warnings: zod.z.array(zod.z.record(zod.z.unknown())).default([]),
+  started_at: zod.z.string().nullable().optional(),
+  completed_at: zod.z.string().nullable().optional(),
+  created_at: zod.z.string().nullable().optional(),
+  updated_at: zod.z.string().nullable().optional()
+});
+var DistillJobResponse = zod.z.object({
+  job_id: zod.z.string(),
+  status: zod.z.string(),
+  memory_ids: zod.z.array(zod.z.string()),
+  enqueued_at: zod.z.string()
+});
+var DistillJobStatusResponse = zod.z.object({
+  job_id: zod.z.string(),
+  agent_id: zod.z.string(),
+  status: zod.z.string(),
+  model: zod.z.string(),
+  memory_ids: zod.z.array(zod.z.string()),
+  chunk_size: zod.z.number(),
+  chunk_overlap: zod.z.number(),
+  max_concurrency: zod.z.number(),
+  chunks_total: zod.z.number(),
+  chunks_failed: zod.z.number(),
+  entities_extracted: zod.z.number(),
+  relationships_extracted: zod.z.number(),
+  memos_written: zod.z.number(),
+  error: zod.z.string().nullable().optional(),
+  started_at: zod.z.string().nullable().optional(),
+  completed_at: zod.z.string().nullable().optional(),
+  created_at: zod.z.string().nullable().optional(),
+  updated_at: zod.z.string().nullable().optional()
+});
+var RefineJobResponse = zod.z.object({
+  job_id: zod.z.string(),
+  status: zod.z.string(),
+  dataset_id: zod.z.string().nullable().optional(),
+  enqueued_at: zod.z.string()
+});
+var RefineJobStatusResponse = zod.z.object({
+  job_id: zod.z.string(),
+  status: zod.z.string(),
+  dataset_id: zod.z.string().nullable().optional(),
+  trigger: zod.z.string(),
+  memos_scanned: zod.z.number().default(0),
+  memos_deduped: zod.z.number().default(0),
+  edges_reweighted: zod.z.number().default(0),
+  edges_pruned: zod.z.number().default(0),
+  feedback_drained: zod.z.number().default(0),
+  job_metadata: zod.z.record(zod.z.unknown()).default({}),
+  error: zod.z.string().nullable().optional(),
+  started_at: zod.z.string().nullable().optional(),
+  completed_at: zod.z.string().nullable().optional(),
+  created_at: zod.z.string().nullable().optional(),
+  updated_at: zod.z.string().nullable().optional()
+});
+var ConversationResponse = zod.z.object({
+  id: zod.z.string(),
+  agent_id: zod.z.string(),
+  user_id: zod.z.string().nullable().optional(),
+  title: zod.z.string().nullable().optional(),
+  summary_cadence: zod.z.number(),
+  turn_count: zod.z.number(),
+  last_summary_turn: zod.z.number(),
+  metadata: zod.z.record(zod.z.unknown()).default({}),
+  created_at: zod.z.string(),
+  updated_at: zod.z.string()
+});
+var TurnAddResponse = zod.z.object({
+  turn_index: zod.z.number(),
+  needs_summary: zod.z.boolean()
+});
+var TurnResponse = zod.z.object({
+  memory_id: zod.z.string(),
+  turn_index: zod.z.number(),
+  turn_role: zod.z.string(),
+  content: zod.z.string(),
+  created_at: zod.z.string()
+});
+var TurnListResponse = zod.z.object({
+  turns: zod.z.array(TurnResponse),
+  total: zod.z.number(),
+  conversation_id: zod.z.string()
+});
 
 // src/client.ts
 var Z3rnoClient = class {
@@ -479,6 +585,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);
   }
@@ -722,6 +831,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;
@@ -839,12 +1052,166 @@ var Z3rnoClient = class {
   }
 };
 
+// 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";
+    }
+  }
+};
+
 exports.AuditEntry = AuditEntry;
 exports.AuditPageResponse = AuditPageResponse;
 exports.AuthenticationError = AuthenticationError;
 exports.BatchStoreResponse = BatchStoreResponse;
+exports.ConversationResponse = ConversationResponse;
+exports.DistillJobResponse = DistillJobResponse;
+exports.DistillJobStatusResponse = DistillJobStatusResponse;
 exports.EndSessionResponse = EndSessionResponse;
 exports.ForgetResponse = ForgetResponse;
+exports.IngestJobResponse = IngestJobResponse;
+exports.IngestJobStatusResponse = IngestJobStatusResponse;
 exports.MemoryHistoryResponse = MemoryHistoryResponse;
 exports.MemoryResponse = MemoryResponse;
 exports.MemoryType = MemoryType;
@@ -853,14 +1220,21 @@ exports.NotFoundError = NotFoundError;
 exports.RateLimitError = RateLimitError;
 exports.RecallResponse = RecallResponse;
 exports.RecallResultItem = RecallResultItem;
+exports.RefineJobResponse = RefineJobResponse;
+exports.RefineJobStatusResponse = RefineJobStatusResponse;
 exports.RelationshipType = RelationshipType;
 exports.RetrievalStrategy = RetrievalStrategy;
 exports.ServerError = ServerError;
 exports.SessionResponse = SessionResponse;
+exports.TurnAddResponse = TurnAddResponse;
+exports.TurnListResponse = TurnListResponse;
+exports.TurnResponse = TurnResponse;
 exports.ValidationError = ValidationError;
 exports.Z3rnoClient = Z3rnoClient;
 exports.Z3rnoConnectionError = Z3rnoConnectionError;
 exports.Z3rnoError = Z3rnoError;
+exports.Z3rnoMastraMemory = Z3rnoMastraMemory;
 exports.Z3rnoTimeoutError = Z3rnoTimeoutError;
+exports.Z3rnoVercelMemory = Z3rnoVercelMemory;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map