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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.0.0-dev.20260128.144200",
+  "version": "1.0.0-dev.20260203.130115Z",
   "type": "module",
   "types": "./lib/types/index.d.ts",
   "files": [
@@ -22,9 +22,9 @@
   },
   "dependencies": {
     "eventsource": "^3.0.6",
-    "@vertesia/api-fetch-client": "1.0.0-dev.20260128.144200",
-    "@vertesia/common": "1.0.0-dev.20260128.144200",
-    "@llumiverse/common": "1.0.0-dev.20260128.144200"
+    "@vertesia/api-fetch-client": "1.0.0-dev.20260203.130115Z",
+    "@llumiverse/common": "1.0.0-dev.20260202.145450Z",
+    "@vertesia/common": "1.0.0-dev.20260203.130115Z"
   },
   "ts_dual_module": {
     "outDir": "lib"

package/src/store/HiveMemoryApi.ts

@@ -0,0 +1,231 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    CreateHiveMemoryPayload,
+    FormattedMemoryForAgent,
+    HiveMemory,
+    HiveMemorySearchParams,
+    HiveMemorySearchResult,
+    UpdateHiveMemoryPayload,
+} from "@vertesia/common";
+
+/**
+ * Statistics about hive memories in the project
+ */
+export interface HiveMemoryStats {
+    total_memories: number;
+    by_category: Array<{
+        category: string;
+        count: number;
+        avg_confidence: number;
+        total_usage: number;
+    }>;
+    overall: {
+        avgConfidence: number;
+        avgUsage: number;
+        totalContributions: number;
+    };
+}
+
+/**
+ * Result from recall endpoint
+ */
+export interface RecallResult {
+    memories: FormattedMemoryForAgent[];
+    count: number;
+}
+
+/**
+ * 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: ClientBase) {
+        super(parent, "/api/v1/hive-memory");
+    }
+
+    /**
+     * List memories in the project.
+     *
+     * @param options - Optional filters and pagination
+     */
+    list(options?: {
+        category?: string;
+        scope?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<HiveMemory[]> {
+        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: string): Promise<HiveMemory> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Create a new hive memory.
+     *
+     * @param payload - Memory content including category, summary, and learnings
+     */
+    create(payload: CreateHiveMemoryPayload): Promise<HiveMemory> {
+        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: string, payload: UpdateHiveMemoryPayload): Promise<HiveMemory> {
+        return this.put(`/${id}`, { payload });
+    }
+
+    /**
+     * Delete a memory.
+     *
+     * @param id - Memory ID
+     */
+    delete(id: string): Promise<{ id: string; deleted: boolean }> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Search memories using semantic and keyword search.
+     *
+     * @param params - Search parameters including query, filters, and pagination
+     */
+    search(params: HiveMemorySearchParams): Promise<HiveMemorySearchResult> {
+        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: string,
+        options?: {
+            tools?: string[];
+            category?: string;
+            maxResults?: number;
+        }
+    ): Promise<RecallResult> {
+        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: string): Promise<FormattedMemoryForAgent> {
+        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: string): Promise<{ success: boolean }> {
+        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: string,
+        options?: { limit?: number; offset?: number }
+    ): Promise<HiveMemory[]> {
+        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(): Promise<HiveMemoryStats> {
+        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?: {
+        daysThreshold?: number;
+        decayRate?: number;
+    }): Promise<{ modified_count: number }> {
+        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?: number): Promise<{ archived_count: number }> {
+        return this.post("/admin/archive", {
+            payload: { threshold }
+        });
+    }
+}

package/src/store/IndexingAdminApi.ts

@@ -0,0 +1,336 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+
+/**
+ * Document data structure for Elasticsearch indexing
+ */
+export interface ElasticsearchDocumentData {
+    name?: string;
+    text?: string;
+    properties?: Record<string, unknown>;
+    status?: string;
+    type?: {
+        id?: string;
+        name?: string;
+    };
+    security?: {
+        'content:read'?: string[];
+        'content:write'?: string[];
+        'content:delete'?: string[];
+    };
+    revision?: {
+        head?: boolean;
+        root?: string;
+    };
+    embeddings_text?: number[];
+    embeddings_image?: number[];
+    embeddings_properties?: number[];
+    created_at?: Date | string;
+    updated_at?: Date | string;
+}
+
+/**
+ * Result from bulk indexing
+ */
+export interface BulkIndexResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Result from creating a reindex target
+ */
+export interface CreateReindexTargetResult {
+    created: boolean;
+    indexName: string;
+    aliasName: string;
+    version: number;
+}
+
+/**
+ * Result from getting reindex range
+ */
+export interface ReindexRangeResult {
+    first: string | null;
+    last: string | null;
+    count: number;
+}
+
+/**
+ * Result from fetching a batch
+ */
+export interface FetchBatchResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from indexing a batch
+ */
+export interface IndexBatchResult {
+    successful: number;
+    failed: number;
+    processed: number;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from triggering a reindex
+ */
+export interface TriggerReindexResult {
+    status: string;
+    workflow?: string;
+    workflowId?: string;
+    runId?: string;
+    objectCount?: number;
+    reason?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Elasticsearch index statistics
+ */
+export interface ElasticsearchIndexStats {
+    enabled: boolean;
+    exists?: boolean;
+    documentCount?: number;
+    sizeInBytes?: number;
+    indexName?: string;
+    aliasName?: string;
+}
+
+/**
+ * Embedding configuration for a single type
+ */
+export interface EmbeddingTypeConfig {
+    environment?: string;
+    dimensions?: number;
+    model?: string;
+    provider?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Detailed index configuration
+ */
+export interface IndexConfiguration {
+    enabled: boolean;
+    exists?: boolean;
+    indexName?: string;
+    aliasName?: string;
+    version?: number;
+    documentCount?: number;
+    sizeInBytes?: number;
+    embeddingDimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    fieldMappings?: Record<string, unknown>;
+    projectEmbeddingsConfig?: {
+        text?: EmbeddingTypeConfig;
+        image?: EmbeddingTypeConfig;
+        properties?: EmbeddingTypeConfig;
+    };
+    createdAt?: Date | null;
+}
+
+/**
+ * Result from fetching documents by IDs
+ */
+export interface FetchDocumentsByIdsResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    notFound: string[];
+}
+
+/**
+ * Result from bulk delete
+ */
+export interface BulkDeleteResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Admin API for Elasticsearch operations
+ *
+ * These methods are called by Temporal workflow activities to perform
+ * Elasticsearch operations. They require content admin permissions.
+ */
+export class IndexingAdminApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/admin/elasticsearch") {
+        super(parent, basePath);
+    }
+
+    /**
+     * Index a single document to Elasticsearch
+     */
+    index(objectId: string, document: ElasticsearchDocumentData): Promise<{ status: string; objectId: string }> {
+        return this.post("/index", {
+            payload: { objectId, document },
+        });
+    }
+
+    /**
+     * Delete a document from Elasticsearch
+     */
+    delete(objectId: string): Promise<{ status: string; objectId: string }> {
+        return this.post("/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: Array<{ id: string; document: ElasticsearchDocumentData }>,
+        targetIndex?: string
+    ): Promise<BulkIndexResult> {
+        return this.post("/bulk-index", {
+            payload: { documents, targetIndex },
+        });
+    }
+
+    /**
+     * Ensure Elasticsearch index exists for the project
+     *
+     * @param recreate If true, drops and recreates the index
+     */
+    ensureIndex(recreate?: boolean): Promise<{ created: boolean; recreated?: boolean; existed?: boolean }> {
+        return this.post("/ensure-index", {
+            payload: { recreate },
+        });
+    }
+
+    /**
+     * Create a new versioned index for reindexing (without alias)
+     * The alias will be swapped after reindexing completes via swapAlias
+     */
+    createReindexTarget(): Promise<CreateReindexTargetResult> {
+        return this.post("/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: string, deleteOld?: boolean): Promise<{ swapped: boolean; aliasName?: string; newIndexName?: string }> {
+        return this.post("/swap-alias", {
+            payload: { newIndexName, deleteOld },
+        });
+    }
+
+    /**
+     * Get Elasticsearch index statistics for the project
+     */
+    getStats(): Promise<ElasticsearchIndexStats> {
+        return this.post("/stats", {
+            payload: {},
+        });
+    }
+
+    /**
+     * Get the _id range for reindexing (first, last, count)
+     * Used by workflow to set up cursor-based pagination
+     */
+    getReindexRange(): Promise<ReindexRangeResult> {
+        return this.post("/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?: string | null, limit?: number): Promise<FetchBatchResult> {
+        return this.post("/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
+     */
+    indexBatch(cursor?: string | null, limit?: number, targetIndex?: string): Promise<IndexBatchResult> {
+        return this.post("/index-batch", {
+            payload: { cursor, limit, targetIndex },
+        });
+    }
+
+    /**
+     * Trigger a reindex operation via Temporal workflow
+     *
+     * @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?: {
+        fullReindex?: boolean;
+        objectIds?: string[];
+        recreateIndex?: boolean;
+    }): Promise<TriggerReindexResult> {
+        return this.post("/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: string[]): Promise<FetchDocumentsByIdsResult> {
+        return this.post("/fetch-by-ids", {
+            payload: { objectIds },
+        });
+    }
+
+    /**
+     * Bulk delete documents from Elasticsearch
+     *
+     * @param objectIds Array of object IDs to delete
+     */
+    bulkDelete(objectIds: string[]): Promise<BulkDeleteResult> {
+        return this.post("/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(): Promise<IndexConfiguration> {
+        return this.post("/configuration", {
+            payload: {},
+        });
+    }
+}

package/src/store/IndexingApi.ts

@@ -0,0 +1,62 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    IndexingStatusResponse,
+    GenericCommandResponse,
+} from "@vertesia/common";
+
+/**
+ * API for indexing operations on content objects.
+ * Provides status, reindex, and configuration management.
+ */
+export class IndexingApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/indexing") {
+        super(parent, basePath);
+    }
+
+    /**
+     * Get Elasticsearch status for the current project
+     */
+    async status(): Promise<IndexingStatusResponse> {
+        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?: boolean): Promise<GenericCommandResponse> {
+        return this.post("/reindex", { payload: { recreateIndex } });
+    }
+
+    /**
+     * Enable indexing for this project
+     */
+    async enableIndexing(): Promise<GenericCommandResponse> {
+        return this.post("/enable-indexing");
+    }
+
+    /**
+     * Disable indexing for this project
+     */
+    async disableIndexing(): Promise<GenericCommandResponse> {
+        return this.post("/disable-indexing");
+    }
+
+    /**
+     * Enable index-based queries for this project
+     * (routes searches to index instead of Atlas Search)
+     */
+    async enableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/enable-queries");
+    }
+
+    /**
+     * Disable index-based queries for this project
+     * (routes searches back to Atlas Search)
+     */
+    async disableQueries(): Promise<GenericCommandResponse> {
+        return this.post("/disable-queries");
+    }
+
+}