@xyo-network/diviner-indexing 2.79.0

package/dist/node/index.mjs

@@ -0,0 +1,204 @@
+// src/Schema.ts
+var IndexingDivinerSchema = "network.xyo.diviner.indexing";
+
+// src/Config.ts
+var IndexingDivinerConfigSchema = `${IndexingDivinerSchema}.config`;
+
+// src/Diviner.ts
+import { assertEx } from "@xylabs/assert";
+import { AbstractDiviner } from "@xyo-network/abstract-diviner";
+import { ArchivistWrapper } from "@xyo-network/archivist-wrapper";
+import { BoundWitnessBuilder } from "@xyo-network/boundwitness-builder";
+import { isBoundWitness } from "@xyo-network/boundwitness-model";
+import { BoundWitnessDivinerQuerySchema } from "@xyo-network/diviner-boundwitness-model";
+import { asDivinerInstance, DivinerConfigSchema } from "@xyo-network/diviner-model";
+import { DivinerWrapper } from "@xyo-network/diviner-wrapper";
+import { isModuleState, ModuleStateSchema } from "@xyo-network/module-model";
+import { PayloadBuilder } from "@xyo-network/payload-builder";
+var moduleName = "IndexingDiviner";
+var IndexingDiviner = class extends AbstractDiviner {
+  static configSchemas = [IndexingDivinerConfigSchema, DivinerConfigSchema];
+  _lastState;
+  _pollId;
+  get payloadDivinerLimit() {
+    return this.config.payloadDivinerLimit ?? 1e3;
+  }
+  get pollFrequency() {
+    return this.config.pollFrequency ?? 1e4;
+  }
+  /**
+   * Works via batched iteration of the source archivist to populate the index.
+   * @returns A promise that resolves when the background process is complete
+   */
+  backgroundDivine = async () => {
+    const lastState = await this.retrieveState();
+    const indexCandidateDiviner = await this.getIndexingDivinerStage("stateToIndexCandidateDiviner");
+    const results = lastState ? await indexCandidateDiviner.divine([lastState]) : await indexCandidateDiviner.divine();
+    const nextState = results.find(isModuleState);
+    const indexCandidates = results.filter((x) => !isModuleState(x));
+    const toIndexTransformDiviner = await this.getIndexingDivinerStage("indexCandidateToIndexDiviner");
+    const indexes = await toIndexTransformDiviner.divine(indexCandidates);
+    const indexArchivist = await this.getArchivistForStore("indexStore");
+    await indexArchivist.insert(indexes);
+    if (nextState) {
+      await this.commitState(nextState);
+    }
+  };
+  /**
+   * Commit the internal state of the Diviner process. This is similar
+   * to a transaction completion in a database and should only be called
+   * when results have been successfully persisted to the appropriate
+   * external stores.
+   * @param nextState The state to commit
+   */
+  async commitState(nextState) {
+    var _a;
+    if (nextState.state.offset === ((_a = this._lastState) == null ? void 0 : _a.state.offset))
+      return;
+    this._lastState = nextState;
+    const archivist = await this.getArchivistForStore("stateStore");
+    const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build();
+    await archivist.insert([bw, nextState]);
+  }
+  async divineHandler(payloads = []) {
+    const indexPayloadDiviner = await this.getPayloadDivinerForStore("indexStore");
+    const divinerQueryToIndexQueryDiviner = await this.getIndexingDivinerStage("divinerQueryToIndexQueryDiviner");
+    const indexQueryResponseToDivinerQueryResponseDiviner = await this.getIndexingDivinerStage("indexQueryResponseToDivinerQueryResponseDiviner");
+    const results = (await Promise.all(
+      payloads.map(async (payload) => {
+        const indexQuery = await divinerQueryToIndexQueryDiviner.divine([payload]);
+        const indexedResults = await indexPayloadDiviner.divine(indexQuery);
+        const response = await Promise.all(
+          indexedResults.flat().map((indexedResult) => indexQueryResponseToDivinerQueryResponseDiviner.divine([payload, indexedResult]))
+        );
+        return response.flat();
+      })
+    )).flat();
+    return results;
+  }
+  /**
+   * Retrieves the archivist for the specified store
+   * @param store The store to retrieve the archivist for
+   * @returns The archivist for the specified store
+   */
+  async getArchivistForStore(store) {
+    var _a, _b;
+    const name = assertEx((_b = (_a = this.config) == null ? void 0 : _a[store]) == null ? void 0 : _b.archivist, () => `${moduleName}: Config for ${store}.archivist not specified`);
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.archivist`);
+    return ArchivistWrapper.wrap(mod, this.account);
+  }
+  /**
+   * Retrieves the BoundWitness Diviner for the specified store
+   * @param store The store to retrieve the BoundWitness Diviner for
+   * @returns The BoundWitness Diviner for the specified store
+   */
+  async getBoundWitnessDivinerForStore(store) {
+    var _a, _b;
+    const name = assertEx((_b = (_a = this.config) == null ? void 0 : _a[store]) == null ? void 0 : _b.boundWitnessDiviner, () => `${moduleName}: Config for ${store}.boundWitnessDiviner not specified`);
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.boundWitnessDiviner`);
+    return DivinerWrapper.wrap(mod, this.account);
+  }
+  /**
+   * Gets the Diviner for the supplied Indexing Diviner stage
+   * @param transform The Indexing Diviner stage
+   * @returns The diviner corresponding to the Indexing Diviner stage
+   */
+  async getIndexingDivinerStage(transform) {
+    var _a, _b;
+    const nameOrAddress = assertEx(
+      (_b = (_a = this.config) == null ? void 0 : _a.indexingDivinerStages) == null ? void 0 : _b[transform],
+      () => `${moduleName}: Config for indexingDivinerStages.${transform} not specified`
+    );
+    const mod = await this.resolve(nameOrAddress);
+    return assertEx(asDivinerInstance(mod), () => `${moduleName}: Failed to resolve indexing diviner stage for ${transform}`);
+  }
+  /**
+   * Retrieves the Payload Diviner for the specified store
+   * @param store The store to retrieve the Payload Diviner for
+   * @returns The Payload Diviner for the specified store
+   */
+  async getPayloadDivinerForStore(store) {
+    var _a, _b;
+    const name = assertEx((_b = (_a = this.config) == null ? void 0 : _a[store]) == null ? void 0 : _b.payloadDiviner, () => `${moduleName}: Config for ${store}.payloadDiviner not specified`);
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.payloadDiviner`);
+    return DivinerWrapper.wrap(mod, this.account);
+  }
+  /**
+   * Retrieves the last state of the Diviner process. Used to recover state after
+   * preemptions, reboots, etc.
+   */
+  async retrieveState() {
+    if (this._lastState)
+      return this._lastState;
+    let hash = "";
+    const diviner = await this.getBoundWitnessDivinerForStore("stateStore");
+    const query = new PayloadBuilder({ schema: BoundWitnessDivinerQuerySchema }).fields({
+      address: this.account.address,
+      limit: 1,
+      offset: 0,
+      order: "desc",
+      payload_schemas: [ModuleStateSchema]
+    }).build();
+    const boundWitnesses = await diviner.divine([query]);
+    if (boundWitnesses.length > 0) {
+      const boundWitness = boundWitnesses[0];
+      if (isBoundWitness(boundWitness)) {
+        hash = boundWitness.addresses.map((address, index) => ({ address, index })).filter(({ address }) => address === this.account.address).reduce(
+          (prev, curr) => {
+            var _a;
+            return ((_a = boundWitness.payload_schemas) == null ? void 0 : _a[curr == null ? void 0 : curr.index]) === ModuleStateSchema ? boundWitness.payload_hashes[curr == null ? void 0 : curr.index] : prev;
+          },
+          ""
+        );
+      }
+    }
+    if (hash) {
+      const archivist = await this.getArchivistForStore("stateStore");
+      const payload = (await archivist.get([hash])).find(isModuleState);
+      if (payload) {
+        return payload;
+      }
+    }
+    return void 0;
+  }
+  async startHandler() {
+    await super.startHandler();
+    this.poll();
+    return true;
+  }
+  async stopHandler(_timeout) {
+    if (this._pollId) {
+      clearTimeout(this._pollId);
+      this._pollId = void 0;
+    }
+    return await super.stopHandler();
+  }
+  /**
+   * Runs the background divine process on a loop with a delay
+   * specified by the `config.pollFrequency`
+   */
+  poll() {
+    this._pollId = setTimeout(async () => {
+      try {
+        await this.backgroundDivine();
+      } catch (e) {
+        console.log(e);
+      } finally {
+        if (this._pollId)
+          clearTimeout(this._pollId);
+        this._pollId = void 0;
+        this.poll();
+      }
+    }, this.pollFrequency);
+  }
+};
+
+// src/Stage.ts
+var DivinerStageSchema = "network.xyo.diviner.stage";
+export {
+  DivinerStageSchema,
+  IndexingDiviner,
+  IndexingDivinerConfigSchema,
+  IndexingDivinerSchema
+};
+//# sourceMappingURL=index.mjs.map

package/dist/node/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/Schema.ts","../../src/Config.ts","../../src/Diviner.ts","../../src/Stage.ts"],"sourcesContent":["export const IndexingDivinerSchema = 'network.xyo.diviner.indexing' as const\nexport type ImageThumbnailDivinerSchema = typeof IndexingDivinerSchema\n","import { DivinerConfig } from '@xyo-network/diviner-model'\n\nimport { IndexingDivinerSchema } from './Schema'\nimport { SearchableStorage } from './SearchableStorage'\nimport { IndexingDivinerStageConfig } from './Stage'\n\nexport const IndexingDivinerConfigSchema = `${IndexingDivinerSchema}.config` as const\nexport type IndexingDivinerConfigSchema = typeof IndexingDivinerConfigSchema\n\nexport type IndexingDivinerConfig = DivinerConfig<{\n  /**\n   * Where the diviner should store it's index\n   */\n  indexStore?: SearchableStorage\n  /**\n   * Config section for individual indexing diviner stages\n   */\n  indexingDivinerStages: IndexingDivinerStageConfig\n  /**\n   * The maximum number of payloads to index at a time\n   */\n  payloadDivinerLimit?: number\n  /**\n   * How often to poll for new payloads to index\n   */\n  pollFrequency?: number\n  /**\n   * The schema for the Diviner config\n   */\n  schema: IndexingDivinerConfigSchema\n  /**\n   * Where the diviner should persist its internal state\n   */\n  stateStore?: SearchableStorage\n}>\n","import { assertEx } from '@xylabs/assert'\nimport { AbstractDiviner } from '@xyo-network/abstract-diviner'\nimport { ArchivistWrapper } from '@xyo-network/archivist-wrapper'\nimport { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'\nimport { isBoundWitness } from '@xyo-network/boundwitness-model'\nimport { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'\nimport { asDivinerInstance, DivinerConfigSchema, DivinerModule, DivinerModuleEventData } from '@xyo-network/diviner-model'\nimport { DivinerWrapper } from '@xyo-network/diviner-wrapper'\nimport { isModuleState, ModuleState, ModuleStateSchema } from '@xyo-network/module-model'\nimport { PayloadBuilder } from '@xyo-network/payload-builder'\nimport { Payload } from '@xyo-network/payload-model'\n\nimport { IndexingDivinerConfig, IndexingDivinerConfigSchema } from './Config'\nimport { IndexingDivinerParams } from './Params'\nimport { IndexingDivinerStage } from './Stage'\nimport { IndexingDivinerState } from './State'\n\ntype ConfigStoreKey = 'indexStore' | 'stateStore'\n\ntype ConfigStore = Extract<keyof IndexingDivinerConfig, ConfigStoreKey>\n\nconst moduleName = 'IndexingDiviner'\n\nexport class IndexingDiviner<\n  TParams extends IndexingDivinerParams = IndexingDivinerParams,\n  TIn extends Payload = Payload,\n  TOut extends Payload = Payload,\n  TEventData extends DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut> = DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut>,\n> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {\n  static override readonly configSchemas = [IndexingDivinerConfigSchema, DivinerConfigSchema]\n\n  private _lastState?: ModuleState<IndexingDivinerState>\n  private _pollId?: string | number | NodeJS.Timeout\n\n  get payloadDivinerLimit() {\n    return this.config.payloadDivinerLimit ?? 1_000\n  }\n\n  get pollFrequency() {\n    return this.config.pollFrequency ?? 10_000\n  }\n\n  /**\n   * Works via batched iteration of the source archivist to populate the index.\n   * @returns A promise that resolves when the background process is complete\n   */\n  protected backgroundDivine = async (): Promise<void> => {\n    // Load last state\n    const lastState = await this.retrieveState()\n    // Get next batch of results\n    const indexCandidateDiviner = await this.getIndexingDivinerStage('stateToIndexCandidateDiviner')\n    const results = lastState ? await indexCandidateDiviner.divine([lastState]) : await indexCandidateDiviner.divine()\n    // Filter next state out from results\n    const nextState = results.find(isModuleState<IndexingDivinerState>)\n    const indexCandidates = results.filter((x) => !isModuleState(x))\n    // Transform candidates to indexes\n    const toIndexTransformDiviner = await this.getIndexingDivinerStage('indexCandidateToIndexDiviner')\n    const indexes = await toIndexTransformDiviner.divine(indexCandidates)\n    // Insert index results\n    const indexArchivist = await this.getArchivistForStore('indexStore')\n    await indexArchivist.insert(indexes)\n    // Update state\n    if (nextState) {\n      await this.commitState(nextState)\n    }\n  }\n\n  /**\n   * Commit the internal state of the Diviner process. This is similar\n   * to a transaction completion in a database and should only be called\n   * when results have been successfully persisted to the appropriate\n   * external stores.\n   * @param nextState The state to commit\n   */\n  protected async commitState(nextState: ModuleState<IndexingDivinerState>) {\n    // Don't commit state if no state has changed\n    if (nextState.state.offset === this._lastState?.state.offset) return\n    this._lastState = nextState\n    const archivist = await this.getArchivistForStore('stateStore')\n    const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()\n    await archivist.insert([bw, nextState])\n  }\n\n  protected override async divineHandler(payloads: TIn[] = []): Promise<TOut[]> {\n    const indexPayloadDiviner = await this.getPayloadDivinerForStore('indexStore')\n    const divinerQueryToIndexQueryDiviner = await this.getIndexingDivinerStage('divinerQueryToIndexQueryDiviner')\n    const indexQueryResponseToDivinerQueryResponseDiviner = await this.getIndexingDivinerStage('indexQueryResponseToDivinerQueryResponseDiviner')\n    const results = (\n      await Promise.all(\n        payloads.map(async (payload) => {\n          const indexQuery = await divinerQueryToIndexQueryDiviner.divine([payload])\n          // Divine the results\n          const indexedResults = await indexPayloadDiviner.divine(indexQuery)\n          // Transform the results to the response shape\n          const response = await Promise.all(\n            indexedResults.flat().map((indexedResult) => indexQueryResponseToDivinerQueryResponseDiviner.divine([payload, indexedResult])),\n          )\n          return response.flat()\n        }),\n      )\n    ).flat()\n    // TODO: Infer this type over casting to this type\n    return results as TOut[]\n  }\n\n  /**\n   * Retrieves the archivist for the specified store\n   * @param store The store to retrieve the archivist for\n   * @returns The archivist for the specified store\n   */\n  protected async getArchivistForStore(store: ConfigStore) {\n    const name = assertEx(this.config?.[store]?.archivist, () => `${moduleName}: Config for ${store}.archivist not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.archivist`)\n    return ArchivistWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Retrieves the BoundWitness Diviner for the specified store\n   * @param store The store to retrieve the BoundWitness Diviner for\n   * @returns The BoundWitness Diviner for the specified store\n   */\n  protected async getBoundWitnessDivinerForStore(store: ConfigStore) {\n    const name = assertEx(this.config?.[store]?.boundWitnessDiviner, () => `${moduleName}: Config for ${store}.boundWitnessDiviner not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.boundWitnessDiviner`)\n    return DivinerWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Gets the Diviner for the supplied Indexing Diviner stage\n   * @param transform The Indexing Diviner stage\n   * @returns The diviner corresponding to the Indexing Diviner stage\n   */\n  protected async getIndexingDivinerStage(transform: IndexingDivinerStage) {\n    const nameOrAddress = assertEx(\n      this.config?.indexingDivinerStages?.[transform],\n      () => `${moduleName}: Config for indexingDivinerStages.${transform} not specified`,\n    )\n    const mod = await this.resolve(nameOrAddress)\n    return assertEx(asDivinerInstance(mod), () => `${moduleName}: Failed to resolve indexing diviner stage for ${transform}`)\n  }\n\n  /**\n   * Retrieves the Payload Diviner for the specified store\n   * @param store The store to retrieve the Payload Diviner for\n   * @returns The Payload Diviner for the specified store\n   */\n  protected async getPayloadDivinerForStore(store: ConfigStore) {\n    const name = assertEx(this.config?.[store]?.payloadDiviner, () => `${moduleName}: Config for ${store}.payloadDiviner not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.payloadDiviner`)\n    return DivinerWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Retrieves the last state of the Diviner process. Used to recover state after\n   * preemptions, reboots, etc.\n   */\n  protected async retrieveState(): Promise<ModuleState<IndexingDivinerState> | undefined> {\n    if (this._lastState) return this._lastState\n    let hash: string = ''\n    const diviner = await this.getBoundWitnessDivinerForStore('stateStore')\n    const query = new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })\n      .fields({\n        address: this.account.address,\n        limit: 1,\n        offset: 0,\n        order: 'desc',\n        payload_schemas: [ModuleStateSchema],\n      })\n      .build()\n    const boundWitnesses = await diviner.divine([query])\n    if (boundWitnesses.length > 0) {\n      const boundWitness = boundWitnesses[0]\n      if (isBoundWitness(boundWitness)) {\n        // Find the index for this address in the BoundWitness that is a ModuleState\n        hash = boundWitness.addresses\n          .map((address, index) => ({ address, index }))\n          .filter(({ address }) => address === this.account.address)\n          .reduce(\n            (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),\n            '',\n          )\n      }\n    }\n\n    // If we able to located the last state\n    if (hash) {\n      // Get last state\n      const archivist = await this.getArchivistForStore('stateStore')\n      const payload = (await archivist.get([hash])).find(isModuleState<IndexingDivinerState>)\n      if (payload) {\n        return payload\n      }\n    }\n    return undefined\n  }\n\n  protected override async startHandler(): Promise<boolean> {\n    await super.startHandler()\n    this.poll()\n    return true\n  }\n\n  protected override async stopHandler(_timeout?: number | undefined): Promise<boolean> {\n    if (this._pollId) {\n      clearTimeout(this._pollId)\n      this._pollId = undefined\n    }\n    return await super.stopHandler()\n  }\n\n  /**\n   * Runs the background divine process on a loop with a delay\n   * specified by the `config.pollFrequency`\n   */\n  private poll() {\n    this._pollId = setTimeout(async () => {\n      try {\n        await this.backgroundDivine()\n      } catch (e) {\n        console.log(e)\n      } finally {\n        if (this._pollId) clearTimeout(this._pollId)\n        this._pollId = undefined\n        this.poll()\n      }\n    }, this.pollFrequency)\n  }\n}\n","export type DivinerStageSchema = 'network.xyo.diviner.stage'\nexport const DivinerStageSchema: DivinerStageSchema = 'network.xyo.diviner.stage'\n\n/**\n * The diviners for each stage of an indexing diviner\n */\nexport type IndexingDivinerStage =\n  /**\n   * Transforms a diviner query into an index query\n   */\n  | 'divinerQueryToIndexQueryDiviner'\n  /**\n   * Transforms the index candidates into indexes\n   */\n  | 'indexCandidateToIndexDiviner'\n  /**\n   * Transforms an index query response into a diviner divine query response\n   */\n  | 'indexQueryResponseToDivinerQueryResponseDiviner'\n  /**\n   * Uses the current state to determine the next batch of index candidates\n   */\n  | 'stateToIndexCandidateDiviner'\n\n/**\n * Config section for declaring each indexing diviner stage\n */\nexport type IndexingDivinerStageConfig = {\n  [key in IndexingDivinerStage]: string\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@xyo-network/diviner-indexing",
+  "author": {
+    "email": "support@xyo.network",
+    "name": "XYO Development Team",
+    "url": "https://xyo.network"
+  },
+  "bugs": {
+    "email": "support@xyo.network",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-client-js/issues"
+  },
+  "dependencies": {
+    "@xylabs/assert": "^2.13.3",
+    "@xyo-network/abstract-diviner": "~2.79.0",
+    "@xyo-network/archivist-wrapper": "~2.79.0",
+    "@xyo-network/boundwitness-builder": "~2.79.0",
+    "@xyo-network/boundwitness-model": "~2.79.0",
+    "@xyo-network/diviner-boundwitness-model": "~2.79.0",
+    "@xyo-network/diviner-model": "~2.79.0",
+    "@xyo-network/diviner-wrapper": "~2.79.0",
+    "@xyo-network/module-model": "~2.79.0",
+    "@xyo-network/payload-builder": "~2.79.0",
+    "@xyo-network/payload-model": "~2.79.0"
+  },
+  "devDependencies": {
+    "@xylabs/ts-scripts-yarn3": "^3.1.21",
+    "@xylabs/tsconfig": "^3.1.21",
+    "typescript": "^5.2.2"
+  },
+  "description": "Primary SDK for using XYO Protocol 2.0",
+  "docs": "dist/docs.json",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "require": {
+          "types": "./dist/browser/index.d.cts",
+          "default": "./dist/browser/index.cjs"
+        },
+        "import": {
+          "types": "./dist/browser/index.d.mts",
+          "default": "./dist/browser/index.js"
+        }
+      },
+      "node": {
+        "require": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "import": {
+          "types": "./dist/node/index.d.mts",
+          "default": "./dist/node/index.mjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/node/index.js",
+  "module": "dist/node/index.mjs",
+  "homepage": "https://xyo.network",
+  "license": "LGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-client-js.git"
+  },
+  "sideEffects": false,
+  "version": "2.79.0"
+}

package/src/Config.ts

@@ -0,0 +1,35 @@
+import { DivinerConfig } from '@xyo-network/diviner-model'
+
+import { IndexingDivinerSchema } from './Schema'
+import { SearchableStorage } from './SearchableStorage'
+import { IndexingDivinerStageConfig } from './Stage'
+
+export const IndexingDivinerConfigSchema = `${IndexingDivinerSchema}.config` as const
+export type IndexingDivinerConfigSchema = typeof IndexingDivinerConfigSchema
+
+export type IndexingDivinerConfig = DivinerConfig<{
+  /**
+   * Where the diviner should store it's index
+   */
+  indexStore?: SearchableStorage
+  /**
+   * Config section for individual indexing diviner stages
+   */
+  indexingDivinerStages: IndexingDivinerStageConfig
+  /**
+   * The maximum number of payloads to index at a time
+   */
+  payloadDivinerLimit?: number
+  /**
+   * How often to poll for new payloads to index
+   */
+  pollFrequency?: number
+  /**
+   * The schema for the Diviner config
+   */
+  schema: IndexingDivinerConfigSchema
+  /**
+   * Where the diviner should persist its internal state
+   */
+  stateStore?: SearchableStorage
+}>

package/src/Diviner.ts

@@ -0,0 +1,228 @@
+import { assertEx } from '@xylabs/assert'
+import { AbstractDiviner } from '@xyo-network/abstract-diviner'
+import { ArchivistWrapper } from '@xyo-network/archivist-wrapper'
+import { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'
+import { isBoundWitness } from '@xyo-network/boundwitness-model'
+import { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'
+import { asDivinerInstance, DivinerConfigSchema, DivinerModule, DivinerModuleEventData } from '@xyo-network/diviner-model'
+import { DivinerWrapper } from '@xyo-network/diviner-wrapper'
+import { isModuleState, ModuleState, ModuleStateSchema } from '@xyo-network/module-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import { Payload } from '@xyo-network/payload-model'
+
+import { IndexingDivinerConfig, IndexingDivinerConfigSchema } from './Config'
+import { IndexingDivinerParams } from './Params'
+import { IndexingDivinerStage } from './Stage'
+import { IndexingDivinerState } from './State'
+
+type ConfigStoreKey = 'indexStore' | 'stateStore'
+
+type ConfigStore = Extract<keyof IndexingDivinerConfig, ConfigStoreKey>
+
+const moduleName = 'IndexingDiviner'
+
+export class IndexingDiviner<
+  TParams extends IndexingDivinerParams = IndexingDivinerParams,
+  TIn extends Payload = Payload,
+  TOut extends Payload = Payload,
+  TEventData extends DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut> = DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut>,
+> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {
+  static override readonly configSchemas = [IndexingDivinerConfigSchema, DivinerConfigSchema]
+
+  private _lastState?: ModuleState<IndexingDivinerState>
+  private _pollId?: string | number | NodeJS.Timeout
+
+  get payloadDivinerLimit() {
+    return this.config.payloadDivinerLimit ?? 1_000
+  }
+
+  get pollFrequency() {
+    return this.config.pollFrequency ?? 10_000
+  }
+
+  /**
+   * Works via batched iteration of the source archivist to populate the index.
+   * @returns A promise that resolves when the background process is complete
+   */
+  protected backgroundDivine = async (): Promise<void> => {
+    // Load last state
+    const lastState = await this.retrieveState()
+    // Get next batch of results
+    const indexCandidateDiviner = await this.getIndexingDivinerStage('stateToIndexCandidateDiviner')
+    const results = lastState ? await indexCandidateDiviner.divine([lastState]) : await indexCandidateDiviner.divine()
+    // Filter next state out from results
+    const nextState = results.find(isModuleState<IndexingDivinerState>)
+    const indexCandidates = results.filter((x) => !isModuleState(x))
+    // Transform candidates to indexes
+    const toIndexTransformDiviner = await this.getIndexingDivinerStage('indexCandidateToIndexDiviner')
+    const indexes = await toIndexTransformDiviner.divine(indexCandidates)
+    // Insert index results
+    const indexArchivist = await this.getArchivistForStore('indexStore')
+    await indexArchivist.insert(indexes)
+    // Update state
+    if (nextState) {
+      await this.commitState(nextState)
+    }
+  }
+
+  /**
+   * Commit the internal state of the Diviner process. This is similar
+   * to a transaction completion in a database and should only be called
+   * when results have been successfully persisted to the appropriate
+   * external stores.
+   * @param nextState The state to commit
+   */
+  protected async commitState(nextState: ModuleState<IndexingDivinerState>) {
+    // Don't commit state if no state has changed
+    if (nextState.state.offset === this._lastState?.state.offset) return
+    this._lastState = nextState
+    const archivist = await this.getArchivistForStore('stateStore')
+    const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()
+    await archivist.insert([bw, nextState])
+  }
+
+  protected override async divineHandler(payloads: TIn[] = []): Promise<TOut[]> {
+    const indexPayloadDiviner = await this.getPayloadDivinerForStore('indexStore')
+    const divinerQueryToIndexQueryDiviner = await this.getIndexingDivinerStage('divinerQueryToIndexQueryDiviner')
+    const indexQueryResponseToDivinerQueryResponseDiviner = await this.getIndexingDivinerStage('indexQueryResponseToDivinerQueryResponseDiviner')
+    const results = (
+      await Promise.all(
+        payloads.map(async (payload) => {
+          const indexQuery = await divinerQueryToIndexQueryDiviner.divine([payload])
+          // Divine the results
+          const indexedResults = await indexPayloadDiviner.divine(indexQuery)
+          // Transform the results to the response shape
+          const response = await Promise.all(
+            indexedResults.flat().map((indexedResult) => indexQueryResponseToDivinerQueryResponseDiviner.divine([payload, indexedResult])),
+          )
+          return response.flat()
+        }),
+      )
+    ).flat()
+    // TODO: Infer this type over casting to this type
+    return results as TOut[]
+  }
+
+  /**
+   * Retrieves the archivist for the specified store
+   * @param store The store to retrieve the archivist for
+   * @returns The archivist for the specified store
+   */
+  protected async getArchivistForStore(store: ConfigStore) {
+    const name = assertEx(this.config?.[store]?.archivist, () => `${moduleName}: Config for ${store}.archivist not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.archivist`)
+    return ArchivistWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Retrieves the BoundWitness Diviner for the specified store
+   * @param store The store to retrieve the BoundWitness Diviner for
+   * @returns The BoundWitness Diviner for the specified store
+   */
+  protected async getBoundWitnessDivinerForStore(store: ConfigStore) {
+    const name = assertEx(this.config?.[store]?.boundWitnessDiviner, () => `${moduleName}: Config for ${store}.boundWitnessDiviner not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.boundWitnessDiviner`)
+    return DivinerWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Gets the Diviner for the supplied Indexing Diviner stage
+   * @param transform The Indexing Diviner stage
+   * @returns The diviner corresponding to the Indexing Diviner stage
+   */
+  protected async getIndexingDivinerStage(transform: IndexingDivinerStage) {
+    const nameOrAddress = assertEx(
+      this.config?.indexingDivinerStages?.[transform],
+      () => `${moduleName}: Config for indexingDivinerStages.${transform} not specified`,
+    )
+    const mod = await this.resolve(nameOrAddress)
+    return assertEx(asDivinerInstance(mod), () => `${moduleName}: Failed to resolve indexing diviner stage for ${transform}`)
+  }
+
+  /**
+   * Retrieves the Payload Diviner for the specified store
+   * @param store The store to retrieve the Payload Diviner for
+   * @returns The Payload Diviner for the specified store
+   */
+  protected async getPayloadDivinerForStore(store: ConfigStore) {
+    const name = assertEx(this.config?.[store]?.payloadDiviner, () => `${moduleName}: Config for ${store}.payloadDiviner not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve ${store}.payloadDiviner`)
+    return DivinerWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Retrieves the last state of the Diviner process. Used to recover state after
+   * preemptions, reboots, etc.
+   */
+  protected async retrieveState(): Promise<ModuleState<IndexingDivinerState> | undefined> {
+    if (this._lastState) return this._lastState
+    let hash: string = ''
+    const diviner = await this.getBoundWitnessDivinerForStore('stateStore')
+    const query = new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })
+      .fields({
+        address: this.account.address,
+        limit: 1,
+        offset: 0,
+        order: 'desc',
+        payload_schemas: [ModuleStateSchema],
+      })
+      .build()
+    const boundWitnesses = await diviner.divine([query])
+    if (boundWitnesses.length > 0) {
+      const boundWitness = boundWitnesses[0]
+      if (isBoundWitness(boundWitness)) {
+        // Find the index for this address in the BoundWitness that is a ModuleState
+        hash = boundWitness.addresses
+          .map((address, index) => ({ address, index }))
+          .filter(({ address }) => address === this.account.address)
+          .reduce(
+            (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),
+            '',
+          )
+      }
+    }
+
+    // If we able to located the last state
+    if (hash) {
+      // Get last state
+      const archivist = await this.getArchivistForStore('stateStore')
+      const payload = (await archivist.get([hash])).find(isModuleState<IndexingDivinerState>)
+      if (payload) {
+        return payload
+      }
+    }
+    return undefined
+  }
+
+  protected override async startHandler(): Promise<boolean> {
+    await super.startHandler()
+    this.poll()
+    return true
+  }
+
+  protected override async stopHandler(_timeout?: number | undefined): Promise<boolean> {
+    if (this._pollId) {
+      clearTimeout(this._pollId)
+      this._pollId = undefined
+    }
+    return await super.stopHandler()
+  }
+
+  /**
+   * Runs the background divine process on a loop with a delay
+   * specified by the `config.pollFrequency`
+   */
+  private poll() {
+    this._pollId = setTimeout(async () => {
+      try {
+        await this.backgroundDivine()
+      } catch (e) {
+        console.log(e)
+      } finally {
+        if (this._pollId) clearTimeout(this._pollId)
+        this._pollId = undefined
+        this.poll()
+      }
+    }, this.pollFrequency)
+  }
+}

package/src/Labels.ts

@@ -0,0 +1,13 @@
+import { Labels } from '@xyo-network/module-model'
+
+import { DivinerStageSchema, IndexingDivinerStage } from './Stage'
+
+/**
+ * Labels for Indexing Diviner Stage Diviners
+ */
+export type IndexingDivinerStageLabels = Labels & {
+  /**
+   * Labels for the stage of the Indexing Diviner Stage Diviner
+   */
+  [key in DivinerStageSchema]: IndexingDivinerStage
+}

package/src/Params.ts

@@ -0,0 +1,6 @@
+import { DivinerParams } from '@xyo-network/diviner-model'
+import { AnyConfigSchema } from '@xyo-network/module-model'
+
+import { IndexingDivinerConfig } from './Config'
+
+export type IndexingDivinerParams = DivinerParams<AnyConfigSchema<IndexingDivinerConfig>>

package/src/Schema.ts

@@ -0,0 +1,2 @@
+export const IndexingDivinerSchema = 'network.xyo.diviner.indexing' as const
+export type ImageThumbnailDivinerSchema = typeof IndexingDivinerSchema

package/src/SearchableStorage.ts

@@ -0,0 +1,9 @@
+/**
+ * Describes an Archivist/Diviner combination
+ * that enables searching signed payloads
+ */
+export interface SearchableStorage {
+  archivist: string
+  boundWitnessDiviner: string
+  payloadDiviner: string
+}

package/src/Stage.ts

@@ -0,0 +1,30 @@
+export type DivinerStageSchema = 'network.xyo.diviner.stage'
+export const DivinerStageSchema: DivinerStageSchema = 'network.xyo.diviner.stage'
+
+/**
+ * The diviners for each stage of an indexing diviner
+ */
+export type IndexingDivinerStage =
+  /**
+   * Transforms a diviner query into an index query
+   */
+  | 'divinerQueryToIndexQueryDiviner'
+  /**
+   * Transforms the index candidates into indexes
+   */
+  | 'indexCandidateToIndexDiviner'
+  /**
+   * Transforms an index query response into a diviner divine query response
+   */
+  | 'indexQueryResponseToDivinerQueryResponseDiviner'
+  /**
+   * Uses the current state to determine the next batch of index candidates
+   */
+  | 'stateToIndexCandidateDiviner'
+
+/**
+ * Config section for declaring each indexing diviner stage
+ */
+export type IndexingDivinerStageConfig = {
+  [key in IndexingDivinerStage]: string
+}

package/src/State.ts

@@ -0,0 +1,5 @@
+import { StateDictionary } from '@xyo-network/module-model'
+
+export type IndexingDivinerState = StateDictionary & {
+  offset: number
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './Config'
+export * from './Diviner'
+export * from './Labels'
+export * from './Params'
+export * from './Schema'
+export * from './SearchableStorage'
+export * from './Stage'

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}