metainsight-context-engine 0.0.1

package/dist/cos-bootstrap.d.ts

@@ -0,0 +1,221 @@
+/**
+ * COS Bootstrap — Infrastructure Initialization
+ *
+ * Ensures all preconditions for the Cloud Context Engine are met before
+ * the engine starts processing requests:
+ *
+ *   1. COS SDK instance is initialized (SecretId / SecretKey auth)
+ *   2. Target bucket exists (headBucket → putBucket if missing)
+ *   3. For each dataset definition:
+ *      a. Dataset exists (GET /dataset → POST /dataset if missing)
+ *      b. Dataset ↔ Bucket binding exists (GET /datasetbinding → POST /datasetbinding if missing)
+ *
+ * The module supports **multiple datasets** per bucket — each dataset has its
+ * own COS path prefix and CI template. The default setup includes a "memory"
+ * dataset (DocSearch) and an "image" dataset (ImageSearch) for multimodal
+ * retrieval. Users can extend it with "knowledge" or any custom datasets.
+ *
+ * **Multi-agent isolation**: When `agentId` is set, the default cosPrefix
+ * becomes `openclaw-{agentId}/workspace/memory/`. This allows multiple
+ * agents to share the same bucket without data collisions.
+ *
+ * The module also exposes a generic `sendCIRequest()` helper for CI API
+ * calls (used by cos-operations.ts for hybridsearch, upload, etc.).
+ *
+ * Supported regions: ap-beijing, ap-shanghai, ap-chengdu
+ *
+ * @example
+ * ```ts
+ * // Minimal — uses default datasets (memory)
+ * bootstrap({ secretId, secretKey, appId: '1253311026' }, logger);
+ *
+ * // Extended — add a custom knowledge dataset alongside defaults
+ * bootstrap({
+ *   secretId, secretKey,
+ *   appId: '1253311026',
+ *   datasets: [
+ *     { name: 'my-memory',    cosPrefix: 'memory/',    templateId: 'Official:DocSearch' },
+ *     { name: 'my-knowledge', cosPrefix: 'knowledge/', templateId: 'Official:DocSearch' },
+ *   ],
+ * }, logger);
+ * ```
+ */
+import COS from 'cos-nodejs-sdk-v5';
+/**
+ * Definition for a single dataset that should be bootstrapped.
+ *
+ * - `name`        — CI dataset name (unique within the APPID scope)
+ * - `cosPrefix`   — COS key prefix the binding should cover (e.g. "memory/")
+ * - `templateId`  — CI dataset template (default: "Official:DocSearch")
+ * - `description` — Human-readable description used when auto-creating
+ */
+export interface DatasetDefinition {
+    /** CI dataset name (e.g. "openclaw-memory"). */
+    name: string;
+    /**
+     * COS key prefix that the binding covers.
+     * Must end with "/" (e.g. "memory/").
+     */
+    cosPrefix: string;
+    /** CI dataset template (default: "Official:DocSearch"). */
+    templateId?: string;
+    /** Description applied when auto-creating the dataset. */
+    description?: string;
+}
+export interface CosBootstrapConfig {
+    secretId: string;
+    secretKey: string;
+    /**
+     * Tencent Cloud APPID (e.g. "1253311026").
+     * Obtain from https://console.cloud.tencent.com/cam/capi
+     */
+    appId: string;
+    /**
+     * Agent ID for multi-agent isolation within a single bucket.
+     *
+     * When set, the default cosPrefix becomes:
+     *   `openclaw-{agentId}/workspace/memory/`
+     *
+     * Typically resolved by the plugin entry point (index.ts) with priority:
+     *   1. User-configured cfg.agentId
+     *   2. Hook ctx.agentId (auto-detected at runtime)
+     *   3. Fallback: 'main'
+     *
+     * When omitted here, the legacy flat prefix `memory/` is used
+     * (only happens if the caller does not resolve agentId beforehand).
+     */
+    agentId?: string;
+    /** COS bucket short name without APPID suffix (e.g. "openclaw-metainsight"). */
+    bucket?: string;
+    /** COS region — only ap-beijing / ap-shanghai / ap-chengdu are supported. */
+    region?: string;
+    /**
+     * Dataset definitions to bootstrap.
+     *
+     * When omitted, three default datasets are created:
+     * ```
+     * [
+     *   { name: "openclaw-memory",   cosPrefix: "memory/",  templateId: "Official:DocSearch" },
+     *   { name: "openclaw-image",    cosPrefix: "asset/",   templateId: "Official:ImageSearch" },
+     *   { name: "openclaw-document", cosPrefix: "asset/",   templateId: "Official:DocSearch" },
+     * ]
+     * ```
+     *
+     * When `agentId` is set and datasets are omitted, the defaults become:
+     * ```
+     * [
+     *   { name: "openclaw-memory-{agentId}",   cosPrefix: "openclaw-{agentId}/workspace/", ... },
+     *   { name: "openclaw-{agentId}-image",     cosPrefix: "openclaw-{agentId}/asset/",     ... },
+     *   { name: "openclaw-{agentId}-document",  cosPrefix: "openclaw-{agentId}/asset/",     ... },
+     * ]
+     * ```
+     *
+     * To add more datasets (e.g. knowledge), supply the full array:
+     * ```
+     * [
+     *   { name: "openclaw-memory",    cosPrefix: "memory/" },
+     *   { name: "openclaw-image",     cosPrefix: "asset/", templateId: "Official:ImageSearch" },
+     *   { name: "openclaw-document",  cosPrefix: "asset/" },
+     *   { name: "openclaw-knowledge", cosPrefix: "knowledge/" },
+     * ]
+     * ```
+     */
+    datasets?: DatasetDefinition[];
+}
+export interface ResolvedDataset {
+    /** CI dataset name. */
+    name: string;
+    /** COS key prefix the binding covers (e.g. "memory/"). */
+    cosPrefix: string;
+    /** CI dataset template. */
+    templateId: string;
+    /** Dataset description. */
+    description: string;
+}
+export interface ResolvedCosConfig {
+    secretId: string;
+    secretKey: string;
+    appId: string;
+    /** Agent ID for multi-agent isolation (undefined = legacy flat layout). */
+    agentId?: string;
+    /** Full bucket name in COS format: "{shortName}-{APPID}" */
+    bucket: string;
+    region: string;
+    /** All datasets to bootstrap (always ≥ 1). */
+    datasets: ResolvedDataset[];
+}
+/** Subset of Dataset info returned by CI API. */
+export interface DatasetInfo {
+    DatasetName?: string;
+    Description?: string;
+    TemplateId?: string;
+    [key: string]: unknown;
+}
+/** Subset of Binding info returned by CI API. */
+export interface DatasetBinding {
+    DatasetName?: string;
+    URI?: string;
+    State?: string;
+    [key: string]: unknown;
+}
+interface Logger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+}
+/**
+ * Get (or create) the COS SDK singleton.
+ */
+export declare function getCOSInstance(secretId: string, secretKey: string): COS;
+/**
+ * Merge user-provided config with defaults, validate region.
+ *
+ * The bucket name is automatically resolved to COS format: `{shortName}-{APPID}`.
+ * If the user-provided bucket already contains the APPID suffix, it is used as-is.
+ *
+ * When `datasets` is omitted, three default datasets are created (memory, image, document).
+ * Each dataset's `cosPrefix` is normalized to end with "/".
+ */
+export declare function resolveConfig(input: CosBootstrapConfig): ResolvedCosConfig;
+/**
+ * Send a request to the COS CI API with automatic SDK signing.
+ *
+ * @param cos    COS SDK instance
+ * @param bucket Bucket name
+ * @param region COS region
+ * @param method HTTP method (GET / POST / PUT / DELETE)
+ * @param endpoint  CI API endpoint path (e.g. "dataset", "datasetbinding", "datasetquery/hybridsearch")
+ * @param body   Optional JSON request body
+ * @param query  Optional query string parameters
+ * @returns Parsed JSON response
+ */
+export declare function sendCIRequest(cos: COS, bucket: string, region: string, method: string, endpoint: string, body?: Record<string, unknown>, query?: Record<string, string>): Promise<unknown>;
+/** Per-dataset bootstrap result. */
+export interface DatasetOutcome {
+    name: string;
+    cosPrefix: string;
+    datasetCreated: boolean;
+    bindingCreated: boolean;
+}
+export interface BootstrapOutcome {
+    success: boolean;
+    cos: COS;
+    config: ResolvedCosConfig;
+    bucketCreated: boolean;
+    /** Per-dataset results (one entry per dataset in config.datasets). */
+    datasetOutcomes: DatasetOutcome[];
+    error?: string;
+}
+/**
+ * Run the full bootstrap sequence:
+ *   1. Initialize COS SDK
+ *   2. Ensure bucket exists
+ *   3. For each dataset in config.datasets:
+ *      a. Ensure dataset exists (GET → POST if missing)
+ *      b. Ensure binding exists (GET → POST if missing), bound to `cos://{bucket}/{cosPrefix}`
+ *
+ * Returns a {@link BootstrapOutcome} with the COS instance and resolved config,
+ * ready for use by `CloudClient`.
+ */
+export declare function bootstrap(input: CosBootstrapConfig, logger: Logger): Promise<BootstrapOutcome>;
+export {};
+//# sourceMappingURL=cos-bootstrap.d.ts.map

package/dist/cos-bootstrap.d.ts.map

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