[ai-form-recognizer] Refactor DocumentModel (Azure#22488)

* [ai-form-recognizer] Diff-squash of documentmodel refactor onto main.

* Duplicate prebuilt schemas for tests (don't require dev-tool/register for tests)

* Fix lint error

* Update some docs

Author: witemple-msft

common/config/rush/pnpm-lock.yaml

@@ -4,12 +4,20 @@
 
 ### Features Added
 
+- Refactored generic `DocumentModel` support to be more robust to different kinds of models. It now supports strongly-typed results for `prebuilt-read`, `prebuilt-layout`, and `prebuilt-document`. See the "Breaking Changes" section for more information about how to replace existing usage of `PrebuiltModels` with new model code.
+
 ### Breaking Changes
 
+- Removed `PrebuiltModels` and all of its fields as well as related helper types. The strongly-typed functionality previously provided by `PrebuiltModels` is now provided by sample code that you can copy into your own project. See the [`prebuilt` samples directory](https://github.com/azure/azure-sdk-for-js/tree/main/sdk/formrecognizer/ai-form-recognizer/samples-dev/prebuilt/) for models compatible with the current Form Recognizer API.
+- Separated URL-based and file-based analysis inputs into two separate methods: `beginAnalyzeDocument` (for file stream inputs) and `beginAnalyzeDocumentFromUrl` (for URL-based inputs). Previously, both were accepted as inputs to a single `beginAnalyzeDocument` method, and a string value would be interpreted as if it were a URL, but this was confusing. The two inputs now have distinct signatures and documentation.
+- Removed the `beginExtractLayout`, `beginExtractGeneralDocument`, and `beginReadDocument` methods. Strongly-typed `DocumentModel` instances for the corresponding `prebuilt-layout`, `prebuilt-document`, and `prebuilt-read` models are located in the [`prebuilt` samples directory](https://github.com/azure/azure-sdk-for-js/tree/main/sdk/formrecognizer/ai-form-recognizer/samples-dev/prebuilt/).
+
 ### Bugs Fixed
 
 ### Other Changes
 
+- Strongly-typed analysis functionality now checks that the `DocumentAnalysisClient`'s API version now matches the assumed API version of the `DocumentModel` exactly. This ensures that a strongly-typed model can only be used with the API version it was created for, so that future changes cannot violate the model's schema.
+
 ## 4.0.0-beta.5 (2022-06-22)
 
 ### Bugs Fixed

sdk/formrecognizer/ai-form-recognizer/CHANGELOG.md

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { DocumentModelInfo } from "../src";
+import { Field } from "./utils";
+
+/**
+ * @internal
+ * Field information for the top level fields of `AnalyzeResult`.
+ */
+export const defaultResultFields: Record<string, Field> = {
+  pages: {
+    name: "pages",
+    docContents: "Extracted pages.",
+    type: "fr.DocumentPage[]",
+    optional: true,
+  },
+  tables: {
+    name: "tables",
+    docContents: "Extracted tables.",
+    type: "fr.DocumentTable[]",
+    optional: true,
+  },
+  keyValuePairs: {
+    name: "keyValuePairs",
+    docContents: "Extracted key-value pairs.",
+    type: "fr.DocumentKeyValuePair[]",
+    optional: true,
+  },
+  languages: {
+    name: "languages",
+    docContents: "Extracted text languages.",
+    type: "fr.DocumentLanguage[]",
+    optional: true,
+  },
+  styles: {
+    name: "styles",
+    docContents: "Extracted font styles.",
+    type: "fr.DocumentStyle[]",
+    optional: true,
+  },
+  documents: {
+    name: "documents",
+    docContents:
+      "Extracted documents (instances of any of the model's document types and corresponding field schemas).",
+    type: "fr.Document[]",
+    optional: true,
+  },
+  paragraphs: {
+    name: "paragraphs",
+    docContents: "Extracted document paragraphs.",
+    type: "fr.DocumentParagraph[]",
+    optional: true,
+  },
+} as const;
+
+const allFeatures = [
+  "pages",
+  "tables",
+  "keyValuePairs",
+  "languages",
+  "styles",
+  "paragraphs",
+  "_documents",
+];
+
+const textFeatures = ["pages", "paragraphs", "styles"];
+const layoutFeatures = [...textFeatures, "tables"];
+const documentFeatures = [...layoutFeatures, "keyValuePairs"];
+
+/**
+ * @internal
+ * @param model - the model to get the features of
+ * @returns the list of features supported by the model
+ */
+export function getFeatures(model: DocumentModelInfo): string[] {
+  return (
+    (model as any).features ??
+    {
+      "prebuilt-read": [...textFeatures, "languages"],
+      "prebuilt-layout": layoutFeatures,
+      "prebuilt-document": documentFeatures,
+      "prebuilt-receipt": [...textFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-invoice": [...layoutFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-idDocument": [...textFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-businessCard": [...textFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-tax.us.w2": [...textFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-vaccinationCard": [...textFeatures, "keyValuePairs", "_documents"],
+      "prebuilt-healthInsuranceCard.us": [...textFeatures, "keyValuePairs", "_documents"],
+    }[model.modelId] ??
+    (model.modelId.startsWith("prebuilt-") ? allFeatures : [...documentFeatures, "_documents"])
+  );
+}

sdk/formrecognizer/ai-form-recognizer/bin/defaultFields.ts

@@ -0,0 +1,163 @@
+#!/bin/env node
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// This file is ignored by the linter because it is impossible to move the copyright header above the shebang line.
+
+import { AzureKeyCredential, KeyCredential, TokenCredential } from "@azure/core-auth";
+import type { DefaultAzureCredential } from "@azure/identity";
+
+import { writeFile } from "fs";
+
+import { DocumentModelAdministrationClient } from "../src/documentModelAdministrationClient";
+import { writeModelCode } from "./writeModelCode";
+
+import { format } from "prettier";
+
+/**
+ * @internal
+ * Prints a help message for the gen-model command.
+ */
+function printHelp() {
+  console.error(`
+Usage:
+ gen-model [options] <model-id>
+ 
+Create a strongly-typed DocumentModel for the Azure Form Recognizer SDK for JavaScript.
+
+Options:
+ -h, --help  \tshow this help message
+ -o, --output\tdetermines where to output the model
+
+ --endpoint <endpoint>\tthe Form Recognizer resource's endpoint
+ --api-key <api-key>  \tthe Form Recognizer resource's API key
+
+Default values:
+
+If the \`--endpoint\` or \`--api-key\` options are not provided, then the values
+of the \`FORM_RECOGNIZER_ENDPOINT\` and \`FORM_RECOGNIZER_API_KEY\` environment
+variables will be used as defaults, respectively.
+
+Authentication:
+
+If an API key is available (via. the \`--api-key\` option or \`FORM_RECOGNIZER_API_KEY\`
+environment variable), then it will be used to authenticate requests to the Form
+Recognizer service.
+
+Otherwise, if the \`@azure/identity\` package is installed, the \`DefaultAzureCredential\`
+from that package will be used.
+
+One of these methods must be available to authenticate with the service.`);
+}
+
+async function tryAad(): Promise<DefaultAzureCredential> {
+  try {
+    return new (await import("@azure/identity")).DefaultAzureCredential();
+  } catch {
+    throw new Error();
+  }
+}
+
+/**
+ * @internal
+ * The main function of the gen-model command.
+ */
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  let modelId: string | undefined = undefined;
+  let endpoint = process.env.FORM_RECOGNIZER_ENDPOINT;
+  let apiKey = process.env.FORM_RECOGNIZER_API_KEY;
+  let output: string | undefined = undefined;
+
+  console.error("gen-model - create strong TypeScript types for models");
+
+  if (args.some((arg) => arg === "--help" || arg === "-h")) {
+    printHelp();
+    return;
+  }
+
+  let idx = 0;
+  while (idx < args.length) {
+    switch (args[idx]) {
+      case "--endpoint":
+        endpoint = args[(idx += 1)];
+        break;
+      case "--api-key":
+        apiKey = args[(idx += 1)];
+        break;
+      case "-o":
+      case "--output":
+        output = args[(idx += 1)];
+        break;
+      default:
+        modelId = args[idx];
+        break;
+    }
+    idx += 1;
+  }
+
+  if (idx + 1 <= args.length) {
+    console.error("warning: unused arguments:", args.slice(idx + 1).join(" "));
+  }
+
+  if (!modelId) {
+    throw new Error("no model ID provided");
+  }
+
+  if (!endpoint) {
+    throw new Error("no endpoint provided");
+  }
+
+  // We try API key-based authentication first, then AAD. If neither works, then we throw an error.
+  let credential: KeyCredential | TokenCredential;
+
+  if (apiKey) {
+    console.error("Using API key authentication.");
+    credential = new AzureKeyCredential(apiKey);
+  } else {
+    try {
+      credential = await tryAad();
+      console.error("Using Azure Active Directory authentication (DefaultAzureCredential).");
+    } catch {
+      throw new Error(
+        [
+          "no authentication method is available;",
+          "provide an API key or install and configure the `@azure/identity` package",
+          "(`npm i --save-dev @azure/identity`)",
+        ].join(" ")
+      );
+    }
+  }
+
+  const client = new DocumentModelAdministrationClient(endpoint, credential);
+
+  const modelInfo = await client.getModel(modelId);
+
+  console.error("Generating model code for:", modelInfo.modelId);
+
+  const file = await writeModelCode(modelInfo);
+
+  const data = Buffer.from(format(file, { parser: "typescript" }), "utf-8");
+
+  if (output !== undefined) {
+    // output is only refined in this context, so assigning it to "path" preserves that
+    const path = output;
+
+    await new Promise<void>((resolve, reject) => {
+      writeFile(path, data, null, (error) => {
+        if (error) reject(error);
+        else resolve();
+      });
+    });
+  } else {
+    process.stdout.write(data);
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  console.error("see `gen-model --help` for more information");
+  process.exit(1);
+});

sdk/formrecognizer/ai-form-recognizer/bin/gen-model.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * Convert a list of strings into a camelCase joined representation.
+ */
+export function camelCase(slug: string[]): string {
+  return slug.map(capitalize).join("");
+}
+
+/**
+ * Capitalize a string.
+ */
+export function capitalize(s: string): string {
+  return s.slice(0, 1).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Uncapitalize a string.
+ */
+export function uncapitalize(s: string): string {
+  return s.slice(0, 1).toLowerCase() + s.slice(1);
+}
+
+/**
+ * A simple representation of a field in an interface.
+ */
+export interface Field {
+  name: string;
+  docContents: string;
+  type: string;
+  optional?: true;
+}