archgraph-argo 0.10.42 → 0.10.44

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticCheckpointStore.js

@@ -1,99 +1,99 @@
-const CHECKPOINT_LABEL = 'ArgoProductionSemanticCheckpoint';
-
-function createProductionSemanticCheckpointStore(dependencies = {}) {
-  const { driver } = dependencies;
-  if (!driver || (typeof driver.execute !== 'function' && typeof driver.session !== 'function')) {
-    throw new TypeError('driver.execute or driver.session is required');
-  }
-
-  return Object.freeze({
-    async readCheckpoint(channel) {
-      if (typeof driver.execute === 'function') {
-        const result = await driver.execute(Object.freeze({
-          kind: 'semantic-checkpoint-read',
-          channel,
-        }));
-        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : undefined;
-      }
-      return withSession(driver, dependencies.configuration, async session => {
-        const result = await executeRead(
-          session,
-          `MATCH (checkpoint:${CHECKPOINT_LABEL} {channel: $channel}) RETURN checkpoint.payload AS payload`,
-          { channel },
-        );
-        const record = result.records && result.records[0];
-        const payload = record && typeof record.get === 'function' ? record.get('payload') : record && record.payload;
-        return typeof payload === 'string' ? cloneCheckpoint(JSON.parse(payload)) : undefined;
-      });
-    },
-
-    async writeCheckpoint(checkpoint) {
-      const durableCheckpoint = cloneCheckpoint(checkpoint);
-      if (typeof driver.execute === 'function') {
-        const result = await driver.execute(Object.freeze({
-          kind: 'semantic-checkpoint-write',
-          checkpoint: durableCheckpoint,
-        }));
-        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : durableCheckpoint;
-      }
-      await withSession(driver, dependencies.configuration, session => executeWrite(
-        session,
-        [
-          `MERGE (checkpoint:${CHECKPOINT_LABEL} {channel: $channel})`,
-          'SET checkpoint.canonicalVersion = $canonicalVersion, checkpoint.payload = $payload',
-          'RETURN checkpoint.payload AS payload',
-        ].join('\n'),
-        {
-          channel: durableCheckpoint.channel,
-          canonicalVersion: durableCheckpoint.canonicalVersion,
-          payload: JSON.stringify(durableCheckpoint),
-        },
-      ));
-      return durableCheckpoint;
-    },
-
-    async close() {
-      if (typeof driver.close === 'function') {
-        await driver.close();
-      }
-    },
-  });
-}
-
-async function withSession(driver, configuration, action) {
-  const database = configuration && configuration.neo4jDatabase;
-  const session = driver.session(database === undefined ? undefined : { database });
-  try {
-    return await action(session);
-  } finally {
-    if (session && typeof session.close === 'function') {
-      await session.close();
-    }
-  }
-}
-
-function executeWrite(session, query, parameters) {
-  if (typeof session.executeWrite === 'function') {
-    return session.executeWrite(transaction => transaction.run(query, parameters));
-  }
-  return session.run(query, parameters);
-}
-
-function executeRead(session, query, parameters) {
-  if (typeof session.executeRead === 'function') {
-    return session.executeRead(transaction => transaction.run(query, parameters));
-  }
-  return session.run(query, parameters);
-}
-
-function cloneCheckpoint(checkpoint) {
-  return Object.freeze({
-    ...checkpoint,
-    completedCanonicalIdentities: Object.freeze([...(checkpoint.completedCanonicalIdentities || [])]),
-    isolatedFailures: Object.freeze((checkpoint.isolatedFailures || []).map(failure => Object.freeze({ ...failure }))),
-  });
-}
-
-module.exports = {
-  createProductionSemanticCheckpointStore,
-};
+const CHECKPOINT_LABEL = 'ArgoProductionSemanticCheckpoint';
+
+function createProductionSemanticCheckpointStore(dependencies = {}) {
+  const { driver } = dependencies;
+  if (!driver || (typeof driver.execute !== 'function' && typeof driver.session !== 'function')) {
+    throw new TypeError('driver.execute or driver.session is required');
+  }
+
+  return Object.freeze({
+    async readCheckpoint(channel) {
+      if (typeof driver.execute === 'function') {
+        const result = await driver.execute(Object.freeze({
+          kind: 'semantic-checkpoint-read',
+          channel,
+        }));
+        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : undefined;
+      }
+      return withSession(driver, dependencies.configuration, async session => {
+        const result = await executeRead(
+          session,
+          `MATCH (checkpoint:${CHECKPOINT_LABEL} {channel: $channel}) RETURN checkpoint.payload AS payload`,
+          { channel },
+        );
+        const record = result.records && result.records[0];
+        const payload = record && typeof record.get === 'function' ? record.get('payload') : record && record.payload;
+        return typeof payload === 'string' ? cloneCheckpoint(JSON.parse(payload)) : undefined;
+      });
+    },
+
+    async writeCheckpoint(checkpoint) {
+      const durableCheckpoint = cloneCheckpoint(checkpoint);
+      if (typeof driver.execute === 'function') {
+        const result = await driver.execute(Object.freeze({
+          kind: 'semantic-checkpoint-write',
+          checkpoint: durableCheckpoint,
+        }));
+        return result && result.checkpoint ? cloneCheckpoint(result.checkpoint) : durableCheckpoint;
+      }
+      await withSession(driver, dependencies.configuration, session => executeWrite(
+        session,
+        [
+          `MERGE (checkpoint:${CHECKPOINT_LABEL} {channel: $channel})`,
+          'SET checkpoint.canonicalVersion = $canonicalVersion, checkpoint.payload = $payload',
+          'RETURN checkpoint.payload AS payload',
+        ].join('\n'),
+        {
+          channel: durableCheckpoint.channel,
+          canonicalVersion: durableCheckpoint.canonicalVersion,
+          payload: JSON.stringify(durableCheckpoint),
+        },
+      ));
+      return durableCheckpoint;
+    },
+
+    async close() {
+      if (typeof driver.close === 'function') {
+        await driver.close();
+      }
+    },
+  });
+}
+
+async function withSession(driver, configuration, action) {
+  const database = configuration && configuration.neo4jDatabase;
+  const session = driver.session(database === undefined ? undefined : { database });
+  try {
+    return await action(session);
+  } finally {
+    if (session && typeof session.close === 'function') {
+      await session.close();
+    }
+  }
+}
+
+function executeWrite(session, query, parameters) {
+  if (typeof session.executeWrite === 'function') {
+    return session.executeWrite(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function executeRead(session, query, parameters) {
+  if (typeof session.executeRead === 'function') {
+    return session.executeRead(transaction => transaction.run(query, parameters));
+  }
+  return session.run(query, parameters);
+}
+
+function cloneCheckpoint(checkpoint) {
+  return Object.freeze({
+    ...checkpoint,
+    completedCanonicalIdentities: Object.freeze([...(checkpoint.completedCanonicalIdentities || [])]),
+    isolatedFailures: Object.freeze((checkpoint.isolatedFailures || []).map(failure => Object.freeze({ ...failure }))),
+  });
+}
+
+module.exports = {
+  createProductionSemanticCheckpointStore,
+};

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticProjectionStore.js

@@ -1,171 +1,171 @@
-const {
-  evaluateEmbeddingQualification,
-} = require('../embeddingQualificationGate.js');
-
-const CHANNELS = new Set(['Element', 'ArchitectureRelationship', 'View']);
-const STRING_METADATA_FIELDS = Object.freeze([
-  'canonicalIdentity',
-  'canonicalVersion',
-  'contentVersion',
-  'indexVersion',
-  'provider',
-  'model',
-  'modelVersion',
-]);
-
-function createProductionSemanticProjectionStore(dependencies = {}) {
-  const {
-    persistenceAdapter,
-    canonicalAuthority,
-    configuration,
-    qualification,
-  } = dependencies;
-  requireAdapter(persistenceAdapter);
-  if (!canonicalAuthority || typeof canonicalAuthority.assertProjectionOnly !== 'function') {
-    throw new TypeError('canonicalAuthority.assertProjectionOnly is required');
-  }
-
-  function requireReleaseGates() {
-    requireExternalConfiguration(configuration);
-    const approved = evaluateEmbeddingQualification(qualification);
-    canonicalAuthority.assertProjectionOnly();
-    return approved;
-  }
-
-  return Object.freeze({
-    async upsertRecords(records) {
-      const supplied = requireArray(records, 'records');
-      rejectRunIds(supplied);
-      const approved = requireReleaseGates();
-      const validated = supplied.map(record => validateRecord(record, approved));
-      await persistenceAdapter.upsertRecords(validated);
-      return Object.freeze({ count: validated.length });
-    },
-
-    async deleteTombstones(tombstones) {
-      const supplied = requireArray(tombstones, 'tombstones');
-      rejectRunIds(supplied);
-      requireReleaseGates();
-      const validated = supplied.map(validateTombstone);
-      await persistenceAdapter.deleteTombstones(validated);
-      return Object.freeze({ count: validated.length });
-    },
-
-    async readRecords() {
-      requireReleaseGates();
-      const records = await persistenceAdapter.readRecords();
-      return Object.freeze((records || []).map(record => Object.freeze({
-        ...record,
-        ...(Array.isArray(record.vector) ? { vector: Object.freeze([...record.vector]) } : {}),
-      })));
-    },
-
-    async close() {
-      await persistenceAdapter.close();
-    },
-  });
-}
-
-function requireAdapter(adapter) {
-  for (const method of ['upsertRecords', 'deleteTombstones', 'readRecords', 'close']) {
-    if (!adapter || typeof adapter[method] !== 'function') {
-      throw new TypeError(`persistenceAdapter.${method} is required`);
-    }
-  }
-}
-
-function requireExternalConfiguration(configuration) {
-  const supplied = configuration && typeof configuration === 'object' ? configuration : {};
-  const required = [
-    ['neo4jDatabaseUrl', 'neo4jUri'],
-    ['neo4jDatabaseUsername', 'neo4jUsername'],
-    ['neo4jDatabasePassword', 'neo4jPassword'],
-    ['embeddingCredential'],
-  ];
-  for (const alternatives of required) {
-    const value = alternatives.map(field => supplied[field]).find(isNonBlankString);
-    if (value === undefined) {
-      throw categoryError('EXTERNAL_CREDENTIALS_REQUIRED', alternatives[0]);
-    }
-  }
-}
-
-function validateRecord(record, qualification) {
-  if (!record || typeof record !== 'object') {
-    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'record');
-  }
-  for (const field of STRING_METADATA_FIELDS) {
-    if (!isNonBlankString(record[field])) {
-      throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', field);
-    }
-  }
-  if (!CHANNELS.has(record.channel)) {
-    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'channel');
-  }
-  if (!Number.isInteger(record.dimensions) || record.dimensions <= 0) {
-    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'dimensions');
-  }
-  if (
-    !Array.isArray(record.vector)
-    || record.vector.length !== record.dimensions
-    || record.vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
-  ) {
-    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'vector');
-  }
-  if (
-    record.provider !== qualification.provider
-    || record.model !== qualification.model
-    || record.modelVersion !== qualification.version
-    || record.dimensions !== qualification.dimensions
-  ) {
-    throw categoryError('SP02_SEMANTIC_RECORD_QUALIFICATION_MISMATCH', 'qualification');
-  }
-  return Object.freeze({
-    ...record,
-    vector: Object.freeze([...record.vector]),
-  });
-}
-
-function validateTombstone(tombstone) {
-  if (
-    !tombstone
-    || !isNonBlankString(tombstone.canonicalIdentity)
-    || !CHANNELS.has(tombstone.channel)
-    || !isNonBlankString(tombstone.canonicalVersion)
-  ) {
-    throw categoryError('SP02_TOMBSTONE_METADATA_INVALID', 'tombstone');
-  }
-  return Object.freeze({
-    canonicalIdentity: tombstone.canonicalIdentity.trim(),
-    channel: tombstone.channel,
-    canonicalVersion: tombstone.canonicalVersion.trim(),
-  });
-}
-
-function rejectRunIds(records) {
-  if (records.some(record => record && Object.prototype.hasOwnProperty.call(record, 'runId'))) {
-    throw categoryError('SP02_PRODUCTION_RUNID_PROHIBITED', 'runId');
-  }
-}
-
-function requireArray(value, field) {
-  if (!Array.isArray(value)) {
-    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', field);
-  }
-  return value;
-}
-
-function isNonBlankString(value) {
-  return typeof value === 'string' && value.trim() !== '';
-}
-
-function categoryError(category, field) {
-  const error = new Error(category);
-  error.category = category;
-  error.field = field;
-  return error;
-}
-
-module.exports = {
-  createProductionSemanticProjectionStore,
-};
+const {
+  evaluateEmbeddingQualification,
+} = require('../embeddingQualificationGate.js');
+
+const CHANNELS = new Set(['Element', 'ArchitectureRelationship', 'View']);
+const STRING_METADATA_FIELDS = Object.freeze([
+  'canonicalIdentity',
+  'canonicalVersion',
+  'contentVersion',
+  'indexVersion',
+  'provider',
+  'model',
+  'modelVersion',
+]);
+
+function createProductionSemanticProjectionStore(dependencies = {}) {
+  const {
+    persistenceAdapter,
+    canonicalAuthority,
+    configuration,
+    qualification,
+  } = dependencies;
+  requireAdapter(persistenceAdapter);
+  if (!canonicalAuthority || typeof canonicalAuthority.assertProjectionOnly !== 'function') {
+    throw new TypeError('canonicalAuthority.assertProjectionOnly is required');
+  }
+
+  function requireReleaseGates() {
+    requireExternalConfiguration(configuration);
+    const approved = evaluateEmbeddingQualification(qualification);
+    canonicalAuthority.assertProjectionOnly();
+    return approved;
+  }
+
+  return Object.freeze({
+    async upsertRecords(records) {
+      const supplied = requireArray(records, 'records');
+      rejectRunIds(supplied);
+      const approved = requireReleaseGates();
+      const validated = supplied.map(record => validateRecord(record, approved));
+      await persistenceAdapter.upsertRecords(validated);
+      return Object.freeze({ count: validated.length });
+    },
+
+    async deleteTombstones(tombstones) {
+      const supplied = requireArray(tombstones, 'tombstones');
+      rejectRunIds(supplied);
+      requireReleaseGates();
+      const validated = supplied.map(validateTombstone);
+      await persistenceAdapter.deleteTombstones(validated);
+      return Object.freeze({ count: validated.length });
+    },
+
+    async readRecords() {
+      requireReleaseGates();
+      const records = await persistenceAdapter.readRecords();
+      return Object.freeze((records || []).map(record => Object.freeze({
+        ...record,
+        ...(Array.isArray(record.vector) ? { vector: Object.freeze([...record.vector]) } : {}),
+      })));
+    },
+
+    async close() {
+      await persistenceAdapter.close();
+    },
+  });
+}
+
+function requireAdapter(adapter) {
+  for (const method of ['upsertRecords', 'deleteTombstones', 'readRecords', 'close']) {
+    if (!adapter || typeof adapter[method] !== 'function') {
+      throw new TypeError(`persistenceAdapter.${method} is required`);
+    }
+  }
+}
+
+function requireExternalConfiguration(configuration) {
+  const supplied = configuration && typeof configuration === 'object' ? configuration : {};
+  const required = [
+    ['neo4jDatabaseUrl', 'neo4jUri'],
+    ['neo4jDatabaseUsername', 'neo4jUsername'],
+    ['neo4jDatabasePassword', 'neo4jPassword'],
+    ['embeddingCredential'],
+  ];
+  for (const alternatives of required) {
+    const value = alternatives.map(field => supplied[field]).find(isNonBlankString);
+    if (value === undefined) {
+      throw categoryError('EXTERNAL_CREDENTIALS_REQUIRED', alternatives[0]);
+    }
+  }
+}
+
+function validateRecord(record, qualification) {
+  if (!record || typeof record !== 'object') {
+    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'record');
+  }
+  for (const field of STRING_METADATA_FIELDS) {
+    if (!isNonBlankString(record[field])) {
+      throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', field);
+    }
+  }
+  if (!CHANNELS.has(record.channel)) {
+    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'channel');
+  }
+  if (!Number.isInteger(record.dimensions) || record.dimensions <= 0) {
+    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'dimensions');
+  }
+  if (
+    !Array.isArray(record.vector)
+    || record.vector.length !== record.dimensions
+    || record.vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
+  ) {
+    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', 'vector');
+  }
+  if (
+    record.provider !== qualification.provider
+    || record.model !== qualification.model
+    || record.modelVersion !== qualification.version
+    || record.dimensions !== qualification.dimensions
+  ) {
+    throw categoryError('SP02_SEMANTIC_RECORD_QUALIFICATION_MISMATCH', 'qualification');
+  }
+  return Object.freeze({
+    ...record,
+    vector: Object.freeze([...record.vector]),
+  });
+}
+
+function validateTombstone(tombstone) {
+  if (
+    !tombstone
+    || !isNonBlankString(tombstone.canonicalIdentity)
+    || !CHANNELS.has(tombstone.channel)
+    || !isNonBlankString(tombstone.canonicalVersion)
+  ) {
+    throw categoryError('SP02_TOMBSTONE_METADATA_INVALID', 'tombstone');
+  }
+  return Object.freeze({
+    canonicalIdentity: tombstone.canonicalIdentity.trim(),
+    channel: tombstone.channel,
+    canonicalVersion: tombstone.canonicalVersion.trim(),
+  });
+}
+
+function rejectRunIds(records) {
+  if (records.some(record => record && Object.prototype.hasOwnProperty.call(record, 'runId'))) {
+    throw categoryError('SP02_PRODUCTION_RUNID_PROHIBITED', 'runId');
+  }
+}
+
+function requireArray(value, field) {
+  if (!Array.isArray(value)) {
+    throw categoryError('SP02_SEMANTIC_RECORD_METADATA_INVALID', field);
+  }
+  return value;
+}
+
+function isNonBlankString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function categoryError(category, field) {
+  const error = new Error(category);
+  error.category = category;
+  error.field = field;
+  return error;
+}
+
+module.exports = {
+  createProductionSemanticProjectionStore,
+};

package/argo/scripts/graph-rag/semanticOperatorError.js

@@ -1,38 +1,38 @@
-function semanticOperatorErrorPayload(error) {
-  return Object.freeze({
-    category: typeof error.category === 'string' ? error.category : 'SEMANTIC_OPERATOR_ERROR',
-    state: typeof error.state === 'string' ? error.state : null,
-    verified: error.verified === true,
-    canonicalVersion: typeof error.canonicalVersion === 'string' ? error.canonicalVersion : null,
-    contentVersion: typeof error.contentVersion === 'string' ? error.contentVersion : null,
-    indexVersion: typeof error.indexVersion === 'string' ? error.indexVersion : null,
-    completedChannels: Array.isArray(error.completedChannels) ? [...error.completedChannels] : [],
-    missingChannels: Array.isArray(error.missingChannels) ? [...error.missingChannels] : [],
-    mismatchedChannels: Array.isArray(error.mismatchedChannels) ? [...error.mismatchedChannels] : [],
-    fullSnapshotFallback: false,
-    action: typeof error.action === 'string' ? error.action : 'Correct readiness and retry',
-    ...(typeof error.field === 'string' ? { field: error.field } : {}),
-  });
-}
-
-function semanticOperatorErrorResult(error) {
-  const payload = Object.freeze({
-    status: 'failed',
-    error: semanticOperatorErrorPayload(error),
-  });
-  return Object.freeze({
-    ...payload,
-    content: Object.freeze([
-      Object.freeze({
-        type: 'text',
-        text: JSON.stringify(payload),
-      }),
-    ]),
-    isError: true,
-  });
-}
-
-module.exports = {
-  semanticOperatorErrorPayload,
-  semanticOperatorErrorResult,
-};
+function semanticOperatorErrorPayload(error) {
+  return Object.freeze({
+    category: typeof error.category === 'string' ? error.category : 'SEMANTIC_OPERATOR_ERROR',
+    state: typeof error.state === 'string' ? error.state : null,
+    verified: error.verified === true,
+    canonicalVersion: typeof error.canonicalVersion === 'string' ? error.canonicalVersion : null,
+    contentVersion: typeof error.contentVersion === 'string' ? error.contentVersion : null,
+    indexVersion: typeof error.indexVersion === 'string' ? error.indexVersion : null,
+    completedChannels: Array.isArray(error.completedChannels) ? [...error.completedChannels] : [],
+    missingChannels: Array.isArray(error.missingChannels) ? [...error.missingChannels] : [],
+    mismatchedChannels: Array.isArray(error.mismatchedChannels) ? [...error.mismatchedChannels] : [],
+    fullSnapshotFallback: false,
+    action: typeof error.action === 'string' ? error.action : 'Correct readiness and retry',
+    ...(typeof error.field === 'string' ? { field: error.field } : {}),
+  });
+}
+
+function semanticOperatorErrorResult(error) {
+  const payload = Object.freeze({
+    status: 'failed',
+    error: semanticOperatorErrorPayload(error),
+  });
+  return Object.freeze({
+    ...payload,
+    content: Object.freeze([
+      Object.freeze({
+        type: 'text',
+        text: JSON.stringify(payload),
+      }),
+    ]),
+    isError: true,
+  });
+}
+
+module.exports = {
+  semanticOperatorErrorPayload,
+  semanticOperatorErrorResult,
+};