@agentuity/cli 3.0.0-alpha.7 → 3.0.0-beta.0

package/src/cmd/cloud/vector/search.ts

@@ -1,174 +0,0 @@
-import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createStorageAdapter } from './util';
-import { getCommand } from '../../../command-prefix';
-const VectorSearchResultSchema = z.object({
-	id: z.string().describe('Vector ID'),
-	key: z.string().describe('Vector key'),
-	similarity: z.number().describe('Similarity score (0-1)'),
-	metadata: z.record(z.string(), z.unknown()).optional().describe('Vector metadata'),
-	expiresAt: z.string().optional().describe('Expiration time as ISO 8601 timestamp'),
-});
-
-const VectorSearchResponseSchema = z.object({
-	namespace: z.string().describe('Namespace name'),
-	query: z.string().describe('Search query used'),
-	results: z.array(VectorSearchResultSchema).describe('Search results'),
-	count: z.number().describe('Number of results found'),
-});
-
-export const searchSubcommand = createCommand({
-	name: 'search',
-	aliases: ['list', 'ls'],
-	description: 'Search for vectors using semantic similarity',
-	tags: ['read-only', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true },
-	optional: { project: true },
-	idempotent: true,
-	examples: [
-		{
-			command: getCommand('vector search products "comfortable office chair"'),
-			description: 'Search for similar products',
-		},
-		{
-			command: getCommand('vector list knowledge-base "machine learning"'),
-			description: 'Search knowledge base',
-		},
-		{
-			command: getCommand('vector search docs "API documentation" --limit 5'),
-			description: 'Limit results',
-		},
-		{
-			command: getCommand('vector search products "ergonomic" --similarity 0.8'),
-			description: 'Set minimum similarity',
-		},
-		{
-			command: getCommand('vector ls embeddings "neural networks" --metadata category=ai'),
-			description: 'Filter by metadata',
-		},
-	],
-	schema: {
-		args: z.object({
-			namespace: z.string().min(1).describe('the vector storage namespace'),
-			query: z.string().min(1).describe('the search query text'),
-		}),
-		options: z.object({
-			limit: z.number().optional().describe('maximum number of results to return (default: 10)'),
-			similarity: z
-				.number()
-				.min(0)
-				.max(1)
-				.optional()
-				.describe('minimum similarity threshold (0.0-1.0)'),
-			metadata: z
-				.string()
-				.optional()
-				.describe('filter by metadata (format: key=value or key1=value1,key2=value2)'),
-		}),
-		response: VectorSearchResponseSchema,
-	},
-	webUrl: '/services/vector',
-
-	async handler(ctx) {
-		const { args, opts, options } = ctx;
-		const storage = await createStorageAdapter(ctx);
-		const started = Date.now();
-
-		// Parse metadata filter if provided
-		let metadataFilter: Record<string, unknown> | undefined;
-		if (opts.metadata) {
-			const validPairs: Record<string, unknown> = {};
-			const malformed: string[] = [];
-			const pairs = opts.metadata.split(',');
-
-			for (const pair of pairs) {
-				const trimmedPair = pair.trim();
-				if (!trimmedPair) continue;
-
-				const firstEqualIdx = trimmedPair.indexOf('=');
-				if (firstEqualIdx === -1) {
-					malformed.push(trimmedPair);
-					continue;
-				}
-
-				const key = trimmedPair.substring(0, firstEqualIdx).trim();
-				const value = trimmedPair.substring(firstEqualIdx + 1).trim();
-
-				if (!key || !value) {
-					malformed.push(trimmedPair);
-					continue;
-				}
-
-				// Try to parse as JSON for complex values, otherwise use as string
-				try {
-					validPairs[key] = JSON.parse(value);
-				} catch {
-					validPairs[key] = value;
-				}
-			}
-
-			if (malformed.length > 0) {
-				ctx.logger.warn(`Skipping malformed metadata pairs: ${malformed.join(', ')}`);
-			}
-
-			if (Object.keys(validPairs).length > 0) {
-				metadataFilter = validPairs;
-			}
-		}
-
-		const results = await storage.search(args.namespace, {
-			query: args.query,
-			limit: opts.limit,
-			similarity: opts.similarity,
-			metadata: metadataFilter,
-		});
-
-		const durationMs = Date.now() - started;
-
-		if (!options.json) {
-			if (results.length === 0) {
-				tui.info(
-					`No vectors found matching "${tui.bold(args.query)}" in ${tui.bold(args.namespace)}`
-				);
-			} else {
-				tui.info(
-					`Found ${results.length} result(s) in ${tui.bold(args.namespace)} (${durationMs}ms):`
-				);
-
-				const tableData = results.map((result) => {
-					const metadataStr = result.metadata ? JSON.stringify(result.metadata) : '-';
-					return {
-						Key: result.key,
-						ID: result.id,
-						Similarity: `${(result.similarity * 100).toFixed(1)}%`,
-						Metadata:
-							metadataStr.length > 50 ? metadataStr.substring(0, 47) + '...' : metadataStr,
-					};
-				});
-
-				tui.table(tableData, [
-					{ name: 'Key', alignment: 'left' },
-					{ name: 'ID', alignment: 'left' },
-					{ name: 'Similarity', alignment: 'right' },
-					{ name: 'Metadata', alignment: 'left' },
-				]);
-			}
-		}
-
-		return {
-			namespace: args.namespace,
-			query: args.query,
-			results: results.map((r) => ({
-				id: r.id,
-				key: r.key,
-				similarity: r.similarity,
-				metadata: r.metadata,
-				expiresAt: r.expiresAt,
-			})),
-			count: results.length,
-		};
-	},
-});
-
-export default searchSubcommand;

package/src/cmd/cloud/vector/stats.ts

@@ -1,209 +0,0 @@
-import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createStorageAdapter } from './util';
-import { getCommand } from '../../../command-prefix';
-
-const VectorItemStatsSchema = z.object({
-	embedding: z.array(z.number()).optional().describe('The embedding vector'),
-	document: z.string().optional().describe('Original document text'),
-	size: z.number().describe('Size in bytes'),
-	metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata'),
-	firstUsed: z.number().describe('First access timestamp (ms)'),
-	lastUsed: z.number().describe('Last access timestamp (ms)'),
-	count: z.number().optional().describe('Access count (only available in cloud storage)'),
-});
-
-const VectorNamespaceStatsSchema = z.object({
-	sum: z.number().describe('Total size in bytes'),
-	count: z.number().describe('Number of vectors'),
-	createdAt: z.number().optional().describe('Creation timestamp (ms)'),
-	lastUsed: z.number().optional().describe('Last used timestamp (ms)'),
-});
-
-const VectorStatsPaginatedSchema = z.object({
-	namespaces: z
-		.record(z.string(), VectorNamespaceStatsSchema)
-		.describe('Map of namespace names to their statistics'),
-	total: z.number().describe('Total number of namespaces across all pages'),
-	limit: z.number().describe('Number of namespaces requested per page'),
-	offset: z.number().describe('Number of namespaces skipped'),
-	hasMore: z.boolean().describe('Whether there are more namespaces available'),
-});
-
-const VectorStatsResponseSchema = z.union([
-	VectorNamespaceStatsSchema.extend({
-		namespace: z.string().describe('Namespace name'),
-		sampledResults: z.record(z.string(), VectorItemStatsSchema).optional(),
-	}),
-	z.record(z.string(), VectorNamespaceStatsSchema),
-	VectorStatsPaginatedSchema,
-]);
-
-export const statsSubcommand = createCommand({
-	name: 'stats',
-	description: 'Get statistics for vector storage',
-	tags: ['read-only', 'fast', 'requires-auth'],
-	requires: { auth: true, region: true },
-	optional: { project: true },
-	idempotent: true,
-	examples: [
-		{ command: getCommand('vector stats'), description: 'Show stats for all namespaces' },
-		{
-			command: getCommand('vector stats products'),
-			description: 'Show detailed stats for products namespace',
-		},
-		{ command: getCommand('vector stats embeddings'), description: 'Show stats for embeddings' },
-	],
-	schema: {
-		args: z.object({
-			name: z.string().optional().describe('the vector namespace (optional)'),
-		}),
-		options: z.object({
-			name: z.string().optional().describe('Filter namespaces by name'),
-			sort: z
-				.enum(['name', 'size', 'records', 'created', 'lastUsed'])
-				.default('name')
-				.describe('field to sort by'),
-			direction: z.enum(['asc', 'desc']).default('asc').describe('sort direction'),
-			limit: z.coerce.number().min(0).optional().describe('Maximum number of results to return'),
-			offset: z.coerce.number().min(0).optional().describe('Offset for pagination'),
-		}),
-		response: VectorStatsResponseSchema,
-	},
-	webUrl: (ctx) =>
-		ctx.args.name ? `/services/vector/${encodeURIComponent(ctx.args.name)}` : '/services/vector',
-
-	async handler(ctx) {
-		const { args, options, opts } = ctx;
-		const storage = await createStorageAdapter(ctx);
-
-		if (args.name) {
-			const stats = await storage.getStats(args.name);
-
-			if (!options.json) {
-				if (stats.count === 0 && stats.sum === 0) {
-					tui.info(`Namespace ${tui.bold(args.name)} is empty or does not exist`);
-				} else {
-					tui.header(`Statistics for ${tui.bold(args.name)}`);
-					const sizeDisplay =
-						stats.sum < 1024 * 1024
-							? `${stats.sum.toLocaleString()} bytes`
-							: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
-					const statsDetails: Record<string, unknown> = {
-						Vectors: stats.count,
-						'Total size': sizeDisplay,
-					};
-					if (stats.createdAt) {
-						statsDetails.Created = new Date(stats.createdAt).toLocaleString();
-					}
-					if (stats.lastUsed) {
-						statsDetails['Last used'] = new Date(stats.lastUsed).toLocaleString();
-					}
-					tui.table([statsDetails], undefined, { layout: 'vertical' });
-
-					if (stats.sampledResults && Object.keys(stats.sampledResults).length > 0) {
-						tui.newline();
-						tui.header(`Sample vectors (${Object.keys(stats.sampledResults).length})`);
-
-						const tableData = Object.entries(stats.sampledResults).map(([key, item]) => {
-							const docPreview = item.document
-								? item.document.length > 30
-									? item.document.substring(0, 27) + '...'
-									: item.document
-								: '-';
-							return {
-								Key: key,
-								Size: `${item.size} bytes`,
-								Accesses: item.count ?? '-',
-								'Last Used': new Date(item.lastUsed).toLocaleDateString(),
-								Document: docPreview,
-							};
-						});
-
-						tui.table(tableData, [
-							{ name: 'Key', alignment: 'left' },
-							{ name: 'Size', alignment: 'right' },
-							{ name: 'Accesses', alignment: 'right' },
-							{ name: 'Last Used', alignment: 'left' },
-							{ name: 'Document', alignment: 'left' },
-						]);
-					}
-				}
-			}
-
-			return {
-				namespace: args.name,
-				...stats,
-			};
-		} else {
-			const allStats = await storage.getAllStats({
-				...(opts?.name && { name: opts.name }),
-				...(opts?.sort && { sort: opts.sort }),
-				...(opts?.direction && { direction: opts.direction }),
-				...(opts?.limit !== undefined && { limit: opts.limit }),
-				...(opts?.offset !== undefined && { offset: opts.offset }),
-			});
-
-			// Handle both paginated and flat response formats
-			const isPaginated = allStats && typeof allStats === 'object' && 'namespaces' in allStats;
-			const namespaceMap = isPaginated
-				? (
-						allStats as {
-							namespaces: Record<
-								string,
-								{ sum: number; count: number; createdAt?: number; lastUsed?: number }
-							>;
-						}
-					).namespaces
-				: (allStats as Record<
-						string,
-						{ sum: number; count: number; createdAt?: number; lastUsed?: number }
-					>);
-			const entries = Object.entries(namespaceMap);
-
-			if (!options.json) {
-				if (entries.length === 0) {
-					tui.info('No vector namespaces found');
-				} else {
-					const totalInfo = isPaginated
-						? ` (showing ${entries.length} of ${(allStats as { total: number }).total})`
-						: '';
-					tui.info(
-						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}${totalInfo}:`
-					);
-
-					const tableData = entries.map(([name, stats]) => {
-						const sizeDisplay =
-							stats.sum < 1024 * 1024
-								? `${stats.sum.toLocaleString()} bytes`
-								: `${(stats.sum / (1024 * 1024)).toFixed(2)} MB`;
-						return {
-							Namespace: name,
-							Vectors: stats.count,
-							Size: sizeDisplay,
-							Created: stats.createdAt
-								? new Date(stats.createdAt).toLocaleDateString()
-								: '-',
-							'Last Used': stats.lastUsed
-								? new Date(stats.lastUsed).toLocaleDateString()
-								: '-',
-						};
-					});
-
-					tui.table(tableData, [
-						{ name: 'Namespace', alignment: 'left' },
-						{ name: 'Vectors', alignment: 'right' },
-						{ name: 'Size', alignment: 'right' },
-						{ name: 'Created', alignment: 'left' },
-						{ name: 'Last Used', alignment: 'left' },
-					]);
-				}
-			}
-
-			return allStats;
-		}
-	},
-});
-
-export default statsSubcommand;

package/src/cmd/cloud/vector/upsert.ts

@@ -1,244 +0,0 @@
-import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createStorageAdapter } from './util';
-import { getCommand } from '../../../command-prefix';
-import type { VectorUpsertParams } from '@agentuity/core';
-
-const VectorUpsertResponseSchema = z.object({
-	success: z.boolean().describe('Whether the operation succeeded'),
-	namespace: z.string().describe('Namespace name'),
-	count: z.number().describe('Number of vectors upserted'),
-	results: z
-		.array(
-			z.object({
-				key: z.string().describe('Vector key'),
-				id: z.string().describe('Vector ID'),
-			})
-		)
-		.describe('Upsert results with key-to-id mappings'),
-	durationMs: z.number().describe('Operation duration in milliseconds'),
-	ttl: z.number().optional().describe('TTL in seconds if set'),
-});
-
-export const upsertSubcommand = createCommand({
-	name: 'upsert',
-	aliases: ['put', 'add'],
-	description: 'Add or update vectors in the vector storage',
-	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth', 'uses-stdin'],
-	idempotent: true,
-	requires: { auth: true, region: true },
-	optional: { project: true },
-	examples: [
-		{
-			command: getCommand('vector upsert products doc1 --document "Comfortable office chair"'),
-			description: 'Upsert a single vector with document text',
-		},
-		{
-			command: getCommand(
-				'vector upsert products doc1 --document "Chair" --metadata \'{"category":"furniture"}\''
-			),
-			description: 'Upsert with metadata',
-		},
-		{
-			command: getCommand('vector upsert embeddings vec1 --embeddings "[0.1, 0.2, 0.3]"'),
-			description: 'Upsert with pre-computed embeddings',
-		},
-		{
-			command: getCommand(
-				'vector upsert products doc1 --document "Limited time offer" --ttl 86400'
-			),
-			description: 'Upsert with 24h TTL',
-		},
-		{
-			command: getCommand('vector upsert products --file vectors.json'),
-			description: 'Bulk upsert from JSON file',
-		},
-		{
-			command: `cat vectors.json | ${getCommand('vector upsert products -')}`,
-			description: 'Bulk upsert from stdin',
-		},
-	],
-	schema: {
-		args: z.object({
-			namespace: z.string().min(1).describe('the vector storage namespace'),
-			key: z
-				.string()
-				.optional()
-				.describe('the key for single vector upsert (not used with --file or stdin)'),
-		}),
-		options: z.object({
-			document: z.string().optional().describe('document text to embed'),
-			embeddings: z.string().optional().describe('pre-computed embeddings as JSON array'),
-			metadata: z.string().optional().describe('metadata as JSON object'),
-			file: z
-				.string()
-				.optional()
-				.describe('path to JSON file containing vectors, or "-" for stdin'),
-			ttl: z.coerce
-				.number()
-				.refine((val) => val >= 0, {
-					message: 'TTL must be a non-negative number of seconds',
-				})
-				.optional()
-				.describe('TTL in seconds (0 for no expiration, values 1-59 clamped to 60 by server)'),
-		}),
-		response: VectorUpsertResponseSchema,
-	},
-	webUrl: (ctx) => `/services/vector/${encodeURIComponent(ctx.args.namespace)}`,
-
-	async handler(ctx) {
-		const { args, opts, options, logger } = ctx;
-		const storage = await createStorageAdapter(ctx);
-
-		let documents: VectorUpsertParams[] = [];
-
-		// Check if reading from file or stdin
-		const fileArg = opts.file || (args.key === '-' ? '-' : undefined);
-
-		if (fileArg) {
-			let content: string;
-
-			if (fileArg === '-') {
-				// Read from stdin
-				const chunks: Uint8Array[] = [];
-				const reader = Bun.stdin.stream().getReader();
-
-				while (true) {
-					const { done, value } = await reader.read();
-					if (done) break;
-					chunks.push(value);
-				}
-
-				const decoder = new TextDecoder();
-				content = chunks.map((chunk) => decoder.decode(chunk, { stream: true })).join('');
-			} else {
-				// Read from file
-				const file = Bun.file(fileArg);
-				if (!(await file.exists())) {
-					tui.fatal(`File not found: ${fileArg}`);
-				}
-				content = await file.text();
-			}
-
-			try {
-				const parsed = JSON.parse(content.trim());
-				if (Array.isArray(parsed)) {
-					documents = parsed as VectorUpsertParams[];
-				} else {
-					documents = [parsed as VectorUpsertParams];
-				}
-			} catch {
-				tui.fatal('Invalid JSON in input file/stdin');
-			}
-
-			// Validate documents and apply TTL from command line if not set in document
-			// Handle TTL: 0 means no expiration (null in API), undefined means use default
-			const cliTtl = opts.ttl === 0 ? null : opts.ttl;
-
-			for (const doc of documents) {
-				if (!doc.key || typeof doc.key !== 'string') {
-					tui.fatal('Each document must have a non-empty "key" property');
-				}
-				if (!doc.document && !('embeddings' in doc)) {
-					tui.fatal(
-						`Document with key "${doc.key}" must have either "document" or "embeddings" property`
-					);
-				}
-				// Apply CLI TTL to documents that don't have their own TTL set
-				if (cliTtl !== undefined && doc.ttl === undefined) {
-					doc.ttl = cliTtl;
-				}
-			}
-		} else {
-			// Single vector upsert via command line arguments
-			if (!args.key) {
-				tui.fatal('Key is required for single vector upsert. Use --file for bulk upsert.');
-			}
-
-			if (!opts.document && !opts.embeddings) {
-				tui.fatal('Either --document or --embeddings is required');
-			}
-
-			if (opts.document && opts.embeddings) {
-				tui.fatal('Cannot use both --document and --embeddings');
-			}
-
-			let metadata: Record<string, unknown> | undefined;
-			if (opts.metadata) {
-				try {
-					metadata = JSON.parse(opts.metadata);
-				} catch {
-					tui.fatal('Invalid JSON in --metadata');
-				}
-			}
-
-			// Handle TTL: 0 means no expiration (null in API), undefined means use default
-			const ttl = opts.ttl === 0 ? null : opts.ttl;
-
-			if (opts.document) {
-				documents = [
-					{
-						key: args.key,
-						document: opts.document,
-						metadata,
-						ttl,
-					},
-				];
-			} else if (opts.embeddings) {
-				let embeddings: number[];
-				try {
-					embeddings = JSON.parse(opts.embeddings);
-					if (!Array.isArray(embeddings) || !embeddings.every((n) => typeof n === 'number')) {
-						throw new Error('Not an array of numbers');
-					}
-				} catch {
-					tui.fatal('Invalid embeddings: must be a JSON array of numbers');
-				}
-
-				documents = [
-					{
-						key: args.key,
-						embeddings,
-						metadata,
-						ttl,
-					},
-				];
-			}
-		}
-
-		if (documents.length === 0) {
-			tui.fatal('No documents to upsert');
-		}
-
-		const started = Date.now();
-
-		logger.debug(`Upserting ${documents.length} vector(s) to ${args.namespace}`);
-
-		const results = await storage.upsert(args.namespace, ...documents);
-		const durationMs = Date.now() - started;
-
-		if (!options.json) {
-			tui.success(
-				`Upserted ${results.length} vector(s) to ${tui.bold(args.namespace)} (${durationMs}ms)`
-			);
-
-			if (results.length <= 10) {
-				for (const result of results) {
-					tui.arrow(`${result.key} → ${result.id}`);
-				}
-			}
-		}
-
-		return {
-			success: true,
-			namespace: args.namespace,
-			count: results.length,
-			results,
-			durationMs,
-			ttl: opts.ttl,
-		};
-	},
-});
-
-export default upsertSubcommand;

package/src/cmd/cloud/vector/util.ts

@@ -1,41 +0,0 @@
-import { type Logger, VectorStorageService } from '@agentuity/core';
-import { createServerFetchAdapter } from '@agentuity/server';
-import { getCatalystUrl } from '../../../catalyst';
-import * as tui from '../../../tui';
-import type { AuthData, Config, GlobalOptions, ProjectConfig } from '../../../types';
-
-export function createStorageAdapter(
-	ctx: {
-		logger: Logger;
-		auth: AuthData;
-		region: string;
-		project?: ProjectConfig;
-		config: Config | null;
-		options: GlobalOptions;
-	},
-	explicitOrgId?: string
-) {
-	const orgId =
-		explicitOrgId ??
-		ctx.project?.orgId ??
-		ctx.options.orgId ??
-		(process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
-	if (!orgId) {
-		tui.fatal(
-			'Organization ID is required. Either run from a project directory or use --org-id flag.'
-		);
-	}
-
-	const adapter = createServerFetchAdapter(
-		{
-			headers: {
-				Authorization: `Bearer ${ctx.auth.apiKey}`,
-				'x-agentuity-orgid': orgId,
-			},
-		},
-		ctx.logger
-	);
-
-	const baseUrl = getCatalystUrl(ctx.region, ctx.config?.overrides);
-	return new VectorStorageService(baseUrl, adapter);
-}