deepline 0.1.10 → 0.1.12

package/dist/repo/shared_libs/play-runtime/csv-rename.ts

@@ -0,0 +1,180 @@
+export type CsvRenameMap = Record<string, string | readonly string[]>;
+
+export type CsvRenameOptions = {
+  columns?: CsvRenameMap;
+  rename?: CsvRenameMap;
+  required?: readonly string[];
+};
+
+const CSV_PROJECTED_FIELDS = Symbol.for('deepline.play.csv.projected_fields');
+const CSV_PROJECTED_FIELDS_KEY = '__deeplineCsvProjectedFields';
+
+type ProjectedRow = Record<string, unknown> & {
+  [CSV_PROJECTED_FIELDS]?: ReadonlySet<string>;
+  [CSV_PROJECTED_FIELDS_KEY]?: readonly string[];
+};
+
+function normalizeCsvHeader(header: string): string {
+  return header
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function readString(value: unknown): string {
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return '';
+}
+
+function buildRowLookup(row: Record<string, unknown>): Map<string, unknown> {
+  const lookup = new Map<string, unknown>();
+  for (const [field, value] of Object.entries(row)) {
+    lookup.set(field, value);
+    lookup.set(normalizeCsvHeader(field), value);
+  }
+  return lookup;
+}
+
+function sourceAliases(target: string, aliases: string | readonly string[]) {
+  return [target, ...(Array.isArray(aliases) ? aliases : [aliases])];
+}
+
+export function applyCsvRenameProjection<T extends Record<string, unknown>>(
+  rows: readonly T[],
+  options?: CsvRenameOptions,
+): Array<T & Record<string, unknown>> {
+  const aliases = {
+    ...(options?.rename ?? {}),
+    ...(options?.columns ?? {}),
+  };
+  if (Object.keys(aliases).length === 0) {
+    return [...rows];
+  }
+
+  const required = new Set(options?.required ?? []);
+  return rows.map((row, index) => {
+    const lookup = buildRowLookup(row);
+    const projectedFields = new Set<string>();
+    const projected: Record<string, unknown> = { ...row };
+
+    for (const [target, sourceNames] of Object.entries(aliases)) {
+      let selected: unknown;
+      for (const alias of sourceAliases(target, sourceNames)) {
+        const exact = lookup.get(alias);
+        const normalized = lookup.get(normalizeCsvHeader(alias));
+        const candidate = exact ?? normalized;
+        if (readString(candidate)) {
+          selected = candidate;
+          break;
+        }
+      }
+
+      if (readString(selected)) {
+        if (!Object.prototype.hasOwnProperty.call(row, target)) {
+          Object.defineProperty(projected, target, {
+            value: selected,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+          });
+          projectedFields.add(target);
+        } else {
+          projected[target] = selected;
+        }
+      } else if (required.has(target)) {
+        throw new Error(
+          `ctx.csv(..., { rename }) row ${index + 1} is missing required column "${target}".`,
+        );
+      }
+    }
+
+    Object.defineProperty(projected, CSV_PROJECTED_FIELDS, {
+      value: projectedFields,
+      enumerable: false,
+      configurable: true,
+    });
+    return projected as T & Record<string, unknown>;
+  });
+}
+
+export function cloneCsvAliasedRow<T extends Record<string, unknown>>(
+  row: T,
+  extra?: Record<string, unknown>,
+): Record<string, unknown> {
+  const cloned: Record<string, unknown> = { ...row, ...(extra ?? {}) };
+  const projectedFields = getCsvProjectedFields(row);
+  if (!projectedFields?.size) {
+    return cloned;
+  }
+
+  const clonedProjectedFields = new Set<string>();
+  for (const field of projectedFields) {
+    if (Object.prototype.hasOwnProperty.call(cloned, field)) {
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(row, field);
+    if (descriptor) {
+      Object.defineProperty(cloned, field, {
+        ...descriptor,
+        enumerable: false,
+        configurable: true,
+      });
+    } else {
+      Object.defineProperty(cloned, field, {
+        value: row[field],
+        enumerable: false,
+        configurable: true,
+        writable: true,
+      });
+    }
+    clonedProjectedFields.add(field);
+  }
+
+  if (clonedProjectedFields.size > 0) {
+    Object.defineProperty(cloned, CSV_PROJECTED_FIELDS, {
+      value: clonedProjectedFields,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  return cloned;
+}
+
+export function stripCsvProjectedFields<T extends Record<string, unknown>>(
+  row: T,
+): T {
+  const projectedFields = getCsvProjectedFields(row);
+  if (!projectedFields?.size) return row;
+  const stripped = { ...row };
+  for (const field of projectedFields) {
+    delete stripped[field];
+  }
+  delete stripped[CSV_PROJECTED_FIELDS_KEY];
+  return stripped as T;
+}
+
+export function getCsvProjectedFields(
+  row: Record<string, unknown>,
+): ReadonlySet<string> | null {
+  const symbolFields = (row as ProjectedRow)[CSV_PROJECTED_FIELDS];
+  if (symbolFields?.size) return symbolFields;
+  const serializedFields = (row as ProjectedRow)[CSV_PROJECTED_FIELDS_KEY];
+  if (!Array.isArray(serializedFields) || serializedFields.length === 0) {
+    return null;
+  }
+  return new Set(serializedFields.filter((field) => typeof field === 'string'));
+}
+
+export function stripCsvProjectionMetadata<T extends Record<string, unknown>>(
+  row: T,
+): T {
+  if (!Object.prototype.hasOwnProperty.call(row, CSV_PROJECTED_FIELDS_KEY)) {
+    return row;
+  }
+  const stripped = { ...row };
+  delete stripped[CSV_PROJECTED_FIELDS_KEY];
+  return stripped as T;
+}

package/dist/repo/shared_libs/play-runtime/ctx-types.ts

@@ -103,6 +103,9 @@ export interface WaterfallOptions {
 
 export interface CsvOptions {
   description?: string;
+  columns?: Record<string, string | readonly string[]>;
+  rename?: Record<string, string | readonly string[]>;
+  required?: readonly string[];
 }
 
 export interface MapOptions<TItem = Record<string, unknown>> {
@@ -115,6 +118,12 @@ export interface MapOptions<TItem = Record<string, unknown>> {
    * inside the same window still hit the cache. Daily refreshes use 86400.
    */
   staleAfterSeconds?: number;
+  /**
+   * Maximum row resolvers to execute concurrently. Use 1 when a map calls a
+   * map-backed child play via ctx.runPlay, because those child tables share
+   * durable row identity.
+   */
+  concurrency?: number;
   /**
    * Optional stable key per row. When provided, row identity is derived from
    * the selected input field(s) or returned value instead of hashing the full
@@ -139,7 +148,10 @@ export type MapDefinitionOptions<TItem = Record<string, unknown>> = Omit<
   'description'
 >;
 
-export type MapRunOptions = Pick<MapOptions, 'description'>;
+export type MapRunOptions<TItem = Record<string, unknown>> = Pick<
+  MapOptions<TItem>,
+  'description' | 'staleAfterSeconds' | 'concurrency' | 'key'
+>;
 
 export interface ToolCallOptions {
   description?: string;

package/dist/repo/shared_libs/play-runtime/tool-result.ts

@@ -6,7 +6,6 @@ export type ToolResultExecutionMetadata = {
 };
 
 export type ToolResultTargetMetadata = {
-  value: unknown;
   path: string;
 };
 
@@ -16,6 +15,19 @@ export type ToolResultListMetadata = {
   keys: Record<string, string>;
 };
 
+export type ToolExtractedValue<T = unknown> = {
+  path: string;
+  get(): T | null;
+};
+
+export type ToolResultEnvelope<
+  TData = unknown,
+  TMeta = Record<string, unknown>,
+> = {
+  data: TData;
+  meta?: TMeta;
+};
+
 export type ToolResultMetadata = {
   toolId: string;
   execution: ToolResultExecutionMetadata;
@@ -30,30 +42,30 @@ export type ToolResultMetadataInput = {
   listIdentityGetters?: Record<string, readonly string[]>;
 };
 
-export type ToolExecuteResult<TResult = unknown> = {
+export type ToolExecuteResult<
+  TData = unknown,
+  TMeta = Record<string, unknown>,
+> = {
   status: string;
-  result: TResult;
-  _metadata: ToolResultMetadata;
-  get<T = unknown>(target: string): T | null;
-  getEmail(): string | null;
-  getPhone(): string | null;
-  getLinkedin(): string | null;
-  list<T = Record<string, unknown>>(name?: string): T[] | null;
-  listPick<const TKeys extends readonly string[]>(
-    keys: TKeys,
-    name?: string,
-  ): Array<Record<TKeys[number], unknown>> | null;
-  listKeys(name?: string): Record<string, string>;
+  result: ToolResultEnvelope<TData, TMeta>;
+  extracted: Record<string, ToolExtractedValue>;
+  lists: Record<
+    string,
+    ToolResultListMetadata & {
+      get(): Record<string, unknown>[];
+    }
+  >;
 };
 
 type PathSegment = string | number;
 
 const TARGET_FALLBACK_KEYS: Record<string, readonly RegExp[]> = {
-  email: [/^email$/i, /email/i],
+  email: [/^email$/i, /^address$/i, /email/i],
   phone: [/^phone$/i, /mobile/i, /phone/i, /telephone/i],
   linkedin: [/^linkedin_url$/i, /^linkedin$/i, /linkedin/i],
   domain: [/^domain$/i, /company_domain/i, /domain/i],
   status: [/^email_status$/i, /^status$/i],
+  email_status: [/^email_status$/i, /^status$/i],
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -114,6 +126,22 @@ function getAtPath(root: unknown, path: string): unknown {
   return current;
 }
 
+function asResultPath(path: string): string {
+  const normalized = path.trim().replace(/^result\./, '');
+  return normalized ? `result.${normalized}` : 'result';
+}
+
+function toResultEnvelope(value: unknown): ToolResultEnvelope {
+  if (isRecord(value) && 'data' in value) {
+    const envelope: ToolResultEnvelope = { data: value.data };
+    if ('meta' in value) {
+      envelope.meta = value.meta as Record<string, unknown>;
+    }
+    return envelope;
+  }
+  return { data: value };
+}
+
 function normalizeRows(value: unknown): Record<string, unknown>[] | null {
   if (!Array.isArray(value)) return null;
   return value.map((entry) => (isRecord(entry) ? entry : { value: entry }));
@@ -124,11 +152,13 @@ function findFirstTargetByPath(
   paths: readonly string[] | undefined,
 ): ToolResultTargetMetadata | null {
   for (const path of paths ?? []) {
-    const normalizedPath = String(path || '').trim().replace(/^result\./, '');
+    const normalizedPath = String(path || '')
+      .trim()
+      .replace(/^result\./, '');
     if (!normalizedPath) continue;
     const value = getAtPath(result, normalizedPath);
     if (isMeaningfulValue(value)) {
-      return { value, path: normalizedPath };
+      return { path: asResultPath(normalizedPath) };
     }
   }
   return null;
@@ -157,12 +187,18 @@ function findFirstTargetByKey(
     new RegExp(`^${target}$`, 'i'),
   ];
   for (const [key, value] of Object.entries(result)) {
-    if (patterns.some((pattern) => pattern.test(key)) && isMeaningfulValue(value)) {
-      return { value, path: pathToString([...path, key]) };
+    if (
+      patterns.some((pattern) => pattern.test(key)) &&
+      isMeaningfulValue(value)
+    ) {
+      return { path: asResultPath(pathToString([...path, key])) };
     }
   }
   for (const [key, value] of Object.entries(result)) {
-    const found = findFirstTargetByKey(value, target, depth + 1, [...path, key]);
+    const found = findFirstTargetByKey(value, target, depth + 1, [
+      ...path,
+      key,
+    ]);
     if (found) return found;
   }
   return null;
@@ -177,12 +213,23 @@ function resolveListRows(
     { path: string; rows: Record<string, unknown>[] }
   > = {};
   for (const rawPath of listExtractorPaths ?? []) {
-    const path = String(rawPath || '').trim().replace(/^result\./, '');
+    const path = String(rawPath || '')
+      .trim()
+      .replace(/^result\./, '');
     if (!path) continue;
-    const rows = normalizeRows(getAtPath(result, path));
+    let resolvedPath = path;
+    let rows = normalizeRows(getAtPath(result, resolvedPath));
+    if (!rows && !path.startsWith('data.')) {
+      resolvedPath = `data.${path}`;
+      rows = normalizeRows(getAtPath(result, resolvedPath));
+    }
     if (!rows) continue;
-    const name = path.split('.').filter(Boolean).at(-1)?.replace(/\[\d+\]$/, '');
-    lists[name || path] = { path, rows };
+    const name = resolvedPath
+      .split('.')
+      .filter(Boolean)
+      .at(-1)
+      ?.replace(/\[\d+\]$/, '');
+    lists[name || resolvedPath] = { path: resolvedPath, rows };
   }
   return lists;
 }
@@ -194,9 +241,15 @@ function deriveListKeys(input: {
   listIdentityGetters?: Record<string, readonly string[]>;
 }): Record<string, string> {
   const keys: Record<string, string> = {};
-  for (const [target, paths] of Object.entries(input.listIdentityGetters ?? {})) {
+  for (const [target, paths] of Object.entries(
+    input.listIdentityGetters ?? {},
+  )) {
     const firstPath = paths
-      .map((rawPath) => String(rawPath || '').trim().replace(/^result\./, ''))
+      .map((rawPath) =>
+        String(rawPath || '')
+          .trim()
+          .replace(/^result\./, ''),
+      )
       .find(Boolean);
     if (firstPath) {
       keys[target] = firstPath;
@@ -207,13 +260,19 @@ function deriveListKeys(input: {
   }
 
   const listPrefix = input.listPath.replace(/\[\d+\]$/, '');
-  for (const [target, paths] of Object.entries(input.resultIdentityGetters ?? {})) {
+  for (const [target, paths] of Object.entries(
+    input.resultIdentityGetters ?? {},
+  )) {
     for (const rawPath of paths) {
-      const path = String(rawPath || '').trim().replace(/^result\./, '');
+      const path = String(rawPath || '')
+        .trim()
+        .replace(/^result\./, '');
       if (!path) continue;
       const directPrefix = `${listPrefix}.`;
       if (path.startsWith(directPrefix)) {
-        keys[target] = path.slice(directPrefix.length).replace(/^\[\d+\]\.?/, '');
+        keys[target] = path
+          .slice(directPrefix.length)
+          .replace(/^\[\d+\]\.?/, '');
         break;
       }
       const indexedPrefix = `${listPrefix}[0].`;
@@ -249,6 +308,11 @@ function buildTargets(
     );
     if (fromMetadata) {
       targets[target] = fromMetadata;
+      continue;
+    }
+    const fallback = findFirstTargetByKey(result, target);
+    if (fallback) {
+      targets[target] = fallback;
     }
   }
   if (metadataTargets.size > 0) return targets;
@@ -268,7 +332,7 @@ function buildLists(
   const resolved = resolveListRows(result, metadata.listExtractorPaths);
   for (const [name, list] of Object.entries(resolved)) {
     lists[name] = {
-      path: list.path,
+      path: asResultPath(list.path),
       count: list.rows.length,
       keys: deriveListKeys({
         listPath: list.path,
@@ -281,80 +345,61 @@ function buildLists(
   return lists;
 }
 
+function attachDescriptorMethods<TResult>(
+  wrapper: ToolExecuteResult<TResult>,
+): ToolExecuteResult<TResult> {
+  for (const descriptor of Object.values(wrapper.extracted)) {
+    Object.defineProperty(descriptor, 'get', {
+      configurable: true,
+      enumerable: false,
+      value: () => {
+        const value = getAtPath(wrapper, descriptor.path);
+        return isMeaningfulValue(value) ? value : null;
+      },
+    });
+  }
+
+  for (const descriptor of Object.values(wrapper.lists)) {
+    Object.defineProperty(descriptor, 'get', {
+      configurable: true,
+      enumerable: false,
+      value: () => normalizeRows(getAtPath(wrapper, descriptor.path)) ?? [],
+    });
+  }
+
+  return wrapper;
+}
+
 export function createToolExecuteResult<TResult = unknown>(input: {
   status: string;
   result: TResult;
   metadata: ToolResultMetadataInput;
   execution: ToolResultExecutionMetadata;
 }): ToolExecuteResult<TResult> {
-  const targets = buildTargets(input.result, input.metadata.resultIdentityGetters);
-  const lists = buildLists(input.result, input.metadata);
-  const wrapper = {
+  void input.execution;
+  const result = toResultEnvelope(input.result) as ToolResultEnvelope<TResult>;
+  const extracted = buildTargets(result, input.metadata.resultIdentityGetters);
+  const lists = buildLists(result, input.metadata);
+  const wrapper: ToolExecuteResult<TResult> = {
     status: input.status,
-    result: input.result,
-    _metadata: {
-      toolId: input.metadata.toolId,
-      execution: input.execution,
-      targets,
-      lists,
-    },
-    get<T = unknown>(target: string): T | null {
-      return (this._metadata.targets[target]?.value as T | undefined) ?? null;
-    },
-    getEmail(): string | null {
-      const value = this.get('email');
-      return typeof value === 'string' && value.trim() ? value : null;
-    },
-    getPhone(): string | null {
-      const value = this.get('phone');
-      return typeof value === 'string' && value.trim() ? value : null;
-    },
-    getLinkedin(): string | null {
-      const value = this.get('linkedin');
-      return typeof value === 'string' && value.trim() ? value : null;
-    },
-    list<T = Record<string, unknown>>(name?: string): T[] | null {
-      const entryName = name ?? Object.keys(this._metadata.lists)[0];
-      if (!entryName) return null;
-      const list = this._metadata.lists[entryName];
-      if (!list) return null;
-      return (normalizeRows(getAtPath(this.result, list.path)) as T[] | null) ?? null;
-    },
-    listPick<const TKeys extends readonly string[]>(
-      keys: TKeys,
-      name?: string,
-    ): Array<Record<TKeys[number], unknown>> | null {
-      const entryName = name ?? Object.keys(this._metadata.lists)[0];
-      if (!entryName) return null;
-      const listMetadata = this._metadata.lists[entryName];
-      if (!listMetadata) return null;
-      const rows = normalizeRows(getAtPath(this.result, listMetadata.path));
-      if (!rows) return null;
-      return rows.map((row) => {
-        const picked: Record<string, unknown> = {};
-        for (const key of keys) {
-          const path = listMetadata.keys[key];
-          picked[key] = path ? getAtPath(row, path) ?? null : null;
-        }
-        return picked as Record<TKeys[number], unknown>;
-      });
-    },
-    listKeys(name?: string): Record<string, string> {
-      const entryName = name ?? Object.keys(this._metadata.lists)[0];
-      if (!entryName) return {};
-      return this._metadata.lists[entryName]?.keys ?? {};
-    },
-  } satisfies ToolExecuteResult<TResult>;
-  return wrapper;
+    result,
+    extracted: extracted as Record<string, ToolExtractedValue>,
+    lists: lists as ToolExecuteResult<TResult>['lists'],
+  };
+  return attachDescriptorMethods(wrapper);
 }
 
-export function isToolExecuteResult(value: unknown): value is ToolExecuteResult {
+export function isToolExecuteResult(
+  value: unknown,
+): value is ToolExecuteResult {
   return (
     isRecord(value) &&
     typeof value.status === 'string' &&
-    '_metadata' in value &&
-    isRecord(value._metadata) &&
-    'result' in value
+    'result' in value &&
+    isRecord(value.result) &&
+    'data' in value.result &&
+    'extracted' in value &&
+    isRecord(value.extracted)
   );
 }
 
@@ -362,26 +407,6 @@ export function cloneToolExecuteResultWithExecution<TResult>(
   value: ToolExecuteResult<TResult>,
   execution: ToolResultExecutionMetadata,
 ): ToolExecuteResult<TResult> {
-  return createToolExecuteResult({
-    status: value.status,
-    result: value.result,
-    metadata: {
-      toolId: value._metadata.toolId,
-      resultIdentityGetters: Object.fromEntries(
-        Object.entries(value._metadata.targets).map(([target, info]) => [
-          target,
-          [info.path],
-        ]),
-      ),
-      listExtractorPaths: Object.values(value._metadata.lists).map(
-        (list) => list.path,
-      ),
-      listIdentityGetters: Object.fromEntries(
-        Object.values(value._metadata.lists)
-          .flatMap((list) => Object.entries(list.keys))
-          .map(([target, path]) => [target, [path]]),
-      ),
-    },
-    execution,
-  });
+  void execution;
+  return attachDescriptorMethods(value);
 }