@vertesia/client 1.0.0-dev.20260203.130115Z → 1.0.0-dev.20260227.104700Z

package/lib/esm/store/FilesApi.js

@@ -0,0 +1,231 @@
+import { ApiTopic } from "@vertesia/api-fetch-client";
+import { StreamSource } from "../StreamSource.js";
+export const MEMORIES_PREFIX = "memories";
+export const ARTIFACTS_PREFIX = "agents";
+export function getMemoryFilePath(name) {
+    const nameWithExt = name.endsWith(".tar.gz") ? name : name + ".tar.gz";
+    return `${MEMORIES_PREFIX}/${nameWithExt}`;
+}
+/**
+ * Build the storage path for an agent artifact
+ * @param runId - The workflow run ID
+ * @param name - The artifact filename
+ */
+export function getAgentArtifactPath(runId, name) {
+    return `${ARTIFACTS_PREFIX}/${runId}/${name}`;
+}
+export class FilesApi extends ApiTopic {
+    constructor(parent) {
+        super(parent, "/api/v1/files");
+    }
+    async deleteFile(path, prefix) {
+        const res = await this.delete(`/${path}`, { query: { prefix } });
+        return res.count;
+    }
+    /**
+     * get the metadata of a blob given its URI. Supported URI are:
+     * starting with s3:// and gs://.
+     * For s3 blobs use #region to specify the region. Ex: s3://bucket/key#us-west-2
+     * @param uri
+     * @returns
+     */
+    getMetadata(uri) {
+        return this.get("/metadata", {
+            query: {
+                file: uri,
+            },
+        });
+    }
+    /**
+     * Set custom metadata on a file
+     * @param file - The file path or URI
+     * @param metadata - Custom metadata key-value pairs
+     * @returns Success status
+     */
+    setFileMetadata(file, metadata) {
+        const payload = { file, metadata };
+        return this.put("/metadata", { payload });
+    }
+    /**
+     * Get or create a bucket for the project. If the bucket already exists, it does nothing.
+     * The bucket URI is returned.
+     * @returns
+     */
+    getOrCreateBucket() {
+        return this.post("/bucket");
+    }
+    getUploadUrl(payload) {
+        return this.post("/upload-url", {
+            payload,
+        });
+    }
+    // Strictly typed: provide either simple args or a full payload via a separate method
+    getDownloadUrl(file, name, disposition) {
+        const payload = { file, name, disposition };
+        return this.post("/download-url", { payload });
+    }
+    getDownloadUrlWithOptions(payload) {
+        return this.post("/download-url", { payload });
+    }
+    /**
+     * Upload content to a file and return the full path (including bucket name) of the uploaded file
+     * @param source
+     * @returns
+     */
+    async uploadFile(source) {
+        const isStream = source instanceof StreamSource;
+        const { url, id, path } = await this.getUploadUrl(source);
+        await fetch(url, {
+            method: "PUT",
+            body: isStream ? source.stream : source,
+            //@ts-ignore: duplex is not in the types. See https://github.com/node-fetch/node-fetch/issues/1769
+            duplex: isStream ? "half" : undefined,
+            headers: {
+                "Content-Type": source.type || "application/gzip",
+            },
+        })
+            .then((res) => {
+            if (res.ok) {
+                return res;
+            }
+            else {
+                console.log(res);
+                throw new Error(`Failed to upload file: ${res.statusText}`);
+            }
+        })
+            .catch((err) => {
+            console.error("Failed to upload file", { err, url, id, path });
+            throw err;
+        });
+        return id;
+    }
+    /**
+     *
+     * @param location can be a relative path in the project, a reference to a cloud storage, or a accessible HTTPS URL (typically signed URL)
+     * @returns ReadableStream
+     */
+    async downloadFile(location) {
+        //if start with HTTPS, no download url needed - assume it's signed already
+        const needSign = !location.startsWith("https:");
+        const { url } = needSign
+            ? await this.getDownloadUrl(location)
+            : { url: location };
+        const res = await fetch(url, {
+            method: "GET",
+        })
+            .then((res) => {
+            if (res.ok) {
+                return res;
+            }
+            else if (res.status === 404) {
+                throw new Error(`File at ${url} not found`); //TODO: type fetch error better with a fetch error class
+            }
+            else if (res.status === 403) {
+                throw new Error(`File at ${url} is forbidden`);
+            }
+            else {
+                console.log(res);
+                throw new Error(`Failed to download file ${location}: ${res.statusText}`);
+            }
+        })
+            .catch((err) => {
+            console.error(`Failed to download file ${location}.`, err);
+            throw err;
+        });
+        if (!res.body) {
+            throw new Error(`No body in response while downloading file ${location}`);
+        }
+        return res.body;
+    }
+    /**
+     * Copy a file to a new destination within the same bucket.
+     * @param source - Source file path (relative to project bucket)
+     * @param dest - Destination file path (relative to project bucket)
+     * @returns The destination file URI
+     */
+    async copyFile(source, dest) {
+        const response = await this.post("/copy", {
+            payload: { source, dest },
+        });
+        return response.dest;
+    }
+    async uploadMemoryPack(source) {
+        const fileId = getMemoryFilePath(source.name);
+        const nameWithExt = source.name.endsWith(".tar.gz")
+            ? source.name
+            : source.name + ".tar.gz";
+        if (source instanceof File) {
+            let file = source;
+            return this.uploadFile(new StreamSource(file.stream(), nameWithExt, file.type, fileId));
+        }
+        else {
+            return this.uploadFile(new StreamSource(source.stream, nameWithExt, source.type, fileId));
+        }
+    }
+    async downloadMemoryPack(name, gunzip = false) {
+        let stream = await this.downloadFile(getMemoryFilePath(name));
+        if (gunzip) {
+            const ds = new DecompressionStream("gzip");
+            stream = stream.pipeThrough(ds);
+        }
+        return stream;
+    }
+    // ==================== Agent Artifact Methods ====================
+    /**
+     * List files by prefix
+     * @param prefix - Path prefix to filter files
+     * @returns Array of file paths matching the prefix
+     */
+    listByPrefix(prefix) {
+        return this.get("/list", { query: { prefix } });
+    }
+    /**
+     * Upload an artifact for an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name (e.g., "output.json")
+     * @param source - File content source
+     * @returns The full path of the uploaded artifact
+     */
+    async uploadArtifact(runId, name, source) {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        if (source instanceof File) {
+            const file = source;
+            return this.uploadFile(new StreamSource(file.stream(), name, file.type, artifactPath));
+        }
+        else {
+            return this.uploadFile(new StreamSource(source.stream, name, source.type, artifactPath));
+        }
+    }
+    /**
+     * Download an artifact from an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @returns ReadableStream of the artifact content
+     */
+    async downloadArtifact(runId, name) {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        return this.downloadFile(artifactPath);
+    }
+    /**
+     * Get download URL for an artifact
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @param disposition - Content disposition (inline or attachment)
+     * @returns Signed URL response
+     */
+    getArtifactDownloadUrl(runId, name, disposition) {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        return this.getDownloadUrl(artifactPath, name, disposition);
+    }
+    /**
+     * List artifacts for an agent run
+     * @param runId - The workflow run ID
+     * @returns Array of artifact file paths
+     */
+    async listArtifacts(runId) {
+        const prefix = `${ARTIFACTS_PREFIX}/${runId}/`;
+        const result = await this.listByPrefix(prefix);
+        return result.files;
+    }
+}
+//# sourceMappingURL=FilesApi.js.map

package/lib/esm/store/FilesApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilesApi.js","sourceRoot":"","sources":["../../../src/store/FilesApi.ts"],"names":[],"mappings":"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"}

package/lib/esm/store/HiveMemoryApi.js

@@ -0,0 +1,170 @@
+import { ApiTopic } from "@vertesia/api-fetch-client";
+/**
+ * Client API for managing hive memories.
+ *
+ * Hive memory is a system for storing and retrieving agent learnings,
+ * enabling agents to learn from past runs and share knowledge.
+ */
+export class HiveMemoryApi extends ApiTopic {
+    constructor(parent) {
+        super(parent, "/api/v1/hive-memory");
+    }
+    /**
+     * List memories in the project.
+     *
+     * @param options - Optional filters and pagination
+     */
+    list(options) {
+        const params = new URLSearchParams();
+        if (options?.category)
+            params.set('category', options.category);
+        if (options?.scope)
+            params.set('scope', options.scope);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        const queryString = params.toString();
+        return this.get(queryString ? `/?${queryString}` : '/');
+    }
+    /**
+     * Retrieve a memory by ID.
+     */
+    retrieve(id) {
+        return this.get(`/${id}`);
+    }
+    /**
+     * Create a new hive memory.
+     *
+     * @param payload - Memory content including category, summary, and learnings
+     */
+    create(payload) {
+        return this.post("/", { payload });
+    }
+    /**
+     * Update an existing memory with new learnings.
+     *
+     * This merges new learnings with existing ones rather than replacing them.
+     *
+     * @param id - Memory ID
+     * @param payload - Fields to update/merge
+     */
+    update(id, payload) {
+        return this.put(`/${id}`, { payload });
+    }
+    /**
+     * Delete a memory.
+     *
+     * @param id - Memory ID
+     */
+    delete(id) {
+        return this.del(`/${id}`);
+    }
+    /**
+     * Search memories using semantic and keyword search.
+     *
+     * @param params - Search parameters including query, filters, and pagination
+     */
+    search(params) {
+        return this.post("/search", { payload: params });
+    }
+    /**
+     * Recall memories for an agent.
+     *
+     * This is the primary method for agents to retrieve relevant learnings.
+     * It searches for memories matching the task description and returns
+     * them formatted for agent consumption.
+     *
+     * @param taskDescription - Description of the current task
+     * @param options - Optional filters
+     *
+     * @example
+     * ```typescript
+     * const result = await client.hiveMemory.recall(
+     *   "Extract financial data from PDF documents",
+     *   {
+     *     tools: ["extract_text", "analyze_document"],
+     *     maxResults: 5
+     *   }
+     * );
+     * ```
+     */
+    recall(taskDescription, options) {
+        return this.post("/recall", {
+            payload: {
+                task_description: taskDescription,
+                tools: options?.tools,
+                category: options?.category,
+                max_results: options?.maxResults,
+            }
+        });
+    }
+    /**
+     * Get a memory formatted for agent consumption.
+     *
+     * @param id - Memory ID
+     */
+    getFormatted(id) {
+        return this.get(`/${id}/formatted`);
+    }
+    /**
+     * Record that a memory was used.
+     *
+     * This increments the usage count and helps track memory effectiveness.
+     *
+     * @param id - Memory ID
+     */
+    recordUsage(id) {
+        return this.post(`/${id}/usage`, {});
+    }
+    /**
+     * Get memories by category.
+     *
+     * @param category - Task category (e.g., "document-analysis", "data-extraction")
+     * @param options - Pagination options
+     */
+    getByCategory(category, options) {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        const queryString = params.toString();
+        return this.get(`/category/${category}${queryString ? `?${queryString}` : ''}`);
+    }
+    /**
+     * Get memory statistics for the project.
+     */
+    getStats() {
+        return this.get("/stats");
+    }
+    /**
+     * Apply confidence decay to unused memories.
+     *
+     * Admin operation that reduces confidence scores for memories
+     * that haven't been used recently.
+     *
+     * @param options - Decay parameters
+     */
+    applyDecay(options) {
+        return this.post("/admin/decay", {
+            payload: {
+                days_threshold: options?.daysThreshold,
+                decay_rate: options?.decayRate,
+            }
+        });
+    }
+    /**
+     * Archive memories with low confidence scores.
+     *
+     * Admin operation that removes memories below a confidence threshold.
+     *
+     * @param threshold - Confidence threshold (0-1), default 0.2
+     */
+    archiveLowConfidence(threshold) {
+        return this.post("/admin/archive", {
+            payload: { threshold }
+        });
+    }
+}
+//# sourceMappingURL=HiveMemoryApi.js.map

package/lib/esm/store/HiveMemoryApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HiveMemoryApi.js","sourceRoot":"","sources":["../../../src/store/HiveMemoryApi.ts"],"names":[],"mappings":"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"}

package/lib/esm/store/IndexingApi.js

@@ -0,0 +1,203 @@
+import { ApiTopic } from "@vertesia/api-fetch-client";
+/**
+ * API for indexing operations on content objects.
+ * Provides status, reindex, and configuration management.
+ *
+ * Internal endpoints (prefixed with /internal/) are used by Temporal workflow activities
+ * and require content_admin permission.
+ */
+export class IndexingApi extends ApiTopic {
+    constructor(parent, basePath = "/api/v1/indexing") {
+        super(parent, basePath);
+    }
+    // ========================================================================
+    // User-facing endpoints
+    // ========================================================================
+    /**
+     * Get Elasticsearch status for the current project
+     */
+    async status() {
+        return this.get("/status");
+    }
+    /**
+     * Trigger a full reindex of all documents
+     * @param recreateIndex If true, drops and recreates the index before reindexing
+     */
+    async reindex(recreateIndex) {
+        return this.post("/reindex", { payload: { recreateIndex } });
+    }
+    /**
+     * Enable indexing for this project
+     */
+    async enableIndexing() {
+        return this.post("/enable-indexing");
+    }
+    /**
+     * Disable indexing for this project
+     */
+    async disableIndexing() {
+        return this.post("/disable-indexing");
+    }
+    /**
+     * Enable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    async enableQueries() {
+        return this.post("/enable-queries");
+    }
+    /**
+     * Disable index-based queries for this project
+     * @deprecated Queries are now automatically enabled when indexing is enabled
+     */
+    async disableQueries() {
+        return this.post("/disable-queries");
+    }
+    // ========================================================================
+    // Internal endpoints - called by Temporal workflow activities
+    // ========================================================================
+    /**
+     * Index a single document to Elasticsearch
+     */
+    index(objectId, document) {
+        return this.post("/internal/index", {
+            payload: { objectId, document },
+        });
+    }
+    /**
+     * Delete a document from Elasticsearch
+     */
+    delete(objectId) {
+        return this.post("/internal/delete", {
+            payload: { objectId },
+        });
+    }
+    /**
+     * Bulk index multiple documents to Elasticsearch
+     *
+     * @param documents Array of documents to index
+     * @param targetIndex Optional explicit index name for zero-downtime reindexing
+     */
+    bulkIndex(documents, targetIndex) {
+        return this.post("/internal/bulk-index", {
+            payload: { documents, targetIndex },
+        });
+    }
+    /**
+     * Ensure Elasticsearch index exists for the project
+     *
+     * @param recreate If true, drops and recreates the index
+     */
+    ensureIndex(recreate) {
+        return this.post("/internal/ensure-index", {
+            payload: { recreate },
+        });
+    }
+    /**
+     * Create a new versioned index for reindexing (without alias)
+     * The alias will be swapped after reindexing completes via swapAlias
+     */
+    createReindexTarget() {
+        return this.post("/internal/create-reindex-target", {
+            payload: {},
+        });
+    }
+    /**
+     * Atomically swap the alias from old index to new index
+     *
+     * @param newIndexName The new index to point the alias to
+     * @param deleteOld If true, deletes the old index after swapping
+     */
+    swapAlias(newIndexName, deleteOld) {
+        return this.post("/internal/swap-alias", {
+            payload: { newIndexName, deleteOld },
+        });
+    }
+    /**
+     * Get Elasticsearch index statistics for the project
+     */
+    getStats() {
+        return this.post("/internal/stats", {
+            payload: {},
+        });
+    }
+    /**
+     * Get the _id range for reindexing (first, last, count)
+     * Used by workflow to set up cursor-based pagination
+     */
+    getReindexRange() {
+        return this.post("/internal/reindex-range", {
+            payload: {},
+        });
+    }
+    /**
+     * Fetch a batch of documents from MongoDB (without indexing)
+     * Used by pipeline approach: fetch next batch while indexing current
+     *
+     * @param cursor Cursor from previous batch (null for first batch)
+     * @param limit Maximum documents to fetch (default: 500)
+     */
+    fetchBatch(cursor, limit) {
+        return this.post("/internal/fetch-batch", {
+            payload: { cursor, limit },
+        });
+    }
+    /**
+     * Fetch and index a batch of documents (server-side)
+     * Uses cursor-based pagination for reliability
+     *
+     * @param cursor Cursor from previous batch (null for first batch)
+     * @param limit Maximum documents to process (default: 500)
+     * @param targetIndex Optional explicit index name for zero-downtime reindexing
+     * @param since Only index docs with updated_at >= this ISO timestamp (for catch-up after reindex)
+     */
+    indexBatch(cursor, limit, targetIndex, since) {
+        return this.post("/internal/index-batch", {
+            payload: { cursor, limit, targetIndex, since },
+        });
+    }
+    /**
+     * Trigger a reindex operation via Temporal workflow (internal version with more options)
+     *
+     * @param fullReindex If true, reindexes all documents in the project
+     * @param objectIds Specific object IDs to reindex (if not fullReindex)
+     * @param recreateIndex If true, recreates the index before reindexing
+     */
+    triggerReindex(options) {
+        return this.post("/internal/trigger-reindex", {
+            payload: options ?? {},
+        });
+    }
+    /**
+     * Fetch documents by their IDs from MongoDB (for retry workflow)
+     * Returns documents ready for bulk indexing
+     *
+     * @param objectIds Array of object IDs to fetch
+     */
+    fetchDocumentsByIds(objectIds) {
+        return this.post("/internal/fetch-by-ids", {
+            payload: { objectIds },
+        });
+    }
+    /**
+     * Bulk delete documents from Elasticsearch
+     *
+     * @param objectIds Array of object IDs to delete
+     */
+    bulkDelete(objectIds) {
+        return this.post("/internal/bulk-delete", {
+            payload: { objectIds },
+        });
+    }
+    /**
+     * Get detailed index configuration for the project
+     *
+     * Returns comprehensive information about the Elasticsearch index including
+     * status, embedding dimensions, field mappings, and project configuration.
+     */
+    getConfiguration() {
+        return this.post("/internal/configuration", {
+            payload: {},
+        });
+    }
+}
+//# sourceMappingURL=IndexingApi.js.map

package/lib/esm/store/IndexingApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexingApi.js","sourceRoot":"","sources":["../../../src/store/IndexingApi.ts"],"names":[],"mappings":"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"}