Skip to content

Review main-notebooks/management.ipynb #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Review main-notebooks/management.ipynb #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions notebooks/management.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,23 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Manage Analyzers in Your Resource"
"# Managing Analyzers in Your Resource"
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Changed the heading from "Manage Analyzers in Your Resource" to "Managing Analyzers in Your Resource"
    • rationale: The revised heading uses a gerund phrase that better fits the style of section titles describing ongoing actions or processes, improving grammatical correctness.
    • impact: Enhances the readability and professionalism of the documentation by providing a clearer, more natural heading.

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This notebook demo how to create a simple analyzer and manage its lifecycle."
"This notebook demonstrates how to create a simple analyzer and manage its lifecycle."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Corrected the phrase from "demo how to create" to "demonstrates how to create"
    • rationale: Improved grammatical structure by replacing an informal or incomplete phrase with a proper verb form, making the sentence clearer and more formal
    • impact: Enhances readability and professionalism of the documentation, ensuring the purpose of the notebook is clearly communicated

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Prerequisites\n",
"1. Ensure Azure AI service is configured following [steps](../README.md#configure-azure-ai-service-resource)\n",
"2. Install the required packages to run the sample."
"1. Ensure your Azure AI service is configured following the [configuration steps](../README.md#configure-azure-ai-service-resource).\n",
"2. Install the required packages to run this sample."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]

    • change: Changed "Ensure Azure AI service is configured following [steps]" to "Ensure your Azure AI service is configured following the [configuration steps]" and added a period at the end.
    • rationale: Added "your" to personalize and specify the ownership of the Azure AI service, "configuration steps" to clarify what the link points to, and included a period for correct punctuation and completeness of the sentence.
    • impact: Improves reader understanding and creates a more polished, professional tone in the documentation.

  • categories: [Clarity, Consistency]

    • change: Changed "Install the required packages to run the sample." to "Install the required packages to run this sample."
    • rationale: Added "this" to specify which sample is being referred to, improving precision and consistency in instruction.
    • impact: Helps users clearly identify the specific context, reducing potential confusion when following the instructions.

},
{
Expand All @@ -36,16 +36,18 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Create Azure AI Content Understanding Client\n",
"## Create the Azure AI Content Understanding Client\n",
"\n",
"> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
"> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class that provides functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, this client serves as a lightweight SDK.\n",
"\n",
"> Fill the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service details.\n",
"\n",
"> ⚠️ Important:\n",
"You must update the code below to match your Azure authentication method.\n",
"Update the code below to match your Azure authentication method.\n",
"Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
"If you skip this step, the sample may not run correctly.\n",
"If you skip this step, the sample might not run correctly.\n",
"\n",
"> ⚠️ Note: Using a subscription key works, but using a token provider with Azure Active Directory (AAD) is much safer and is highly recommended for production environments."
"> ⚠️ Note: Using a subscription key works, but using Azure Active Directory (AAD) token-based authentication is more secure and highly recommended for production environments."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]

    • change: Changed header from "Create Azure AI Content Understanding Client" to "Create the Azure AI Content Understanding Client"
    • rationale: Added the definite article "the" to improve grammatical correctness and readability
    • impact: Makes the heading clearer and more natural to read

  • categories: [Clarity, Grammar]

    • change: Revised description of AzureContentUnderstandingClient from "containing functions to interact" to "provides functions to interact," and separated the explanation on filling constants into a new sentence
    • rationale: Improved sentence structure for better flow and clarity; breaking a long sentence into shorter ones enhances understanding
    • impact: Makes the purpose of the client clearer and the instructions easier to follow

  • categories: [Clarity, Formatting]

    • change: Split the instruction to fill constants into a separate line and enumerated the constants with "and" before the last item
    • rationale: Improves readability by giving focus to the important step of filling in constants, and correct list formatting improves clarity
    • impact: Users can more easily identify and understand the required configuration values

  • categories: [Clarity, Consistency]

    • change: Changed "You must update" to "Update" in the instruction about modifying the code to match Azure authentication method
    • rationale: Using imperative form ("Update") is more consistent with typical documentation style and direct instruction tone
    • impact: Makes the instruction more concise and aligned with common documentation conventions

  • categories: [Clarity, Tone]

    • change: Changed "If you skip this step, the sample may not run correctly." to "If you skip this step, the sample might not run correctly."
    • rationale: Word choice "might" sounds slightly less formal and softer, which can improve tone by reducing abruptness
    • impact: Slightly improves the readability and user-friendliness of the warning

  • categories: [Clarity, Consistency]

    • change: Changed "using a token provider with Azure Active Directory (AAD)" to "using Azure Active Directory (AAD) token-based authentication"
    • rationale: More precise and consistent wording that directly refers to the authentication method rather than a generic token provider
    • impact: Enhances clarity and provides a more accurate description of recommended authentication practice

},
{
Expand All @@ -65,13 +67,13 @@
"load_dotenv(find_dotenv())\n",
"logging.basicConfig(level=logging.INFO)\n",
"\n",
"# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
"# For authentication, you can use either token-based auth or subscription key. Use only one of these methods.\n",
"AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
"# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
"# IMPORTANT: Replace with your actual subscription key or set it in your \".env\" file if not using token auth\n",
"AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]

    • change: Replaced "and only one of them is required" with "Use only one of these methods."
    • rationale: The revised wording is clearer and more direct, improving readability and understanding.
    • impact: Helps users better understand the authentication options and usage requirements.

  • categories: [Grammar, Clarity]

    • change: Changed "set up in ".env" file" to "set it in your ".env" file".
    • rationale: The phrase "set it in your" is grammatically smoother and more conversational, enhancing clarity.
    • impact: Makes instructions easier to follow for configuring the subscription key.

"AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
"\n",
"# Add the parent directory to the path to use shared modules \n",
"# Add the parent directory to the system path to use shared modules\n",
"parent_dir = Path(Path.cwd()).parent\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Changed comment from "Add the parent directory to the path to use shared modules" to "Add the parent directory to the system path to use shared modules" (removed extra space and specified "system path").
    • rationale: The modification clarifies that the parent directory is being added specifically to the system path, improving the precision of the comment. The removal of the trailing space also corrects minor formatting.
    • impact: This change enhances the clarity and accuracy of the comment, helping readers better understand the purpose of the code.

"sys.path.append(str(parent_dir))\n",
"from python.content_understanding_client import AzureContentUnderstandingClient\n",
Expand All @@ -84,18 +86,18 @@
" api_version=AZURE_AI_API_VERSION,\n",
" # IMPORTANT: Comment out token_provider if using subscription key\n",
" token_provider=token_provider,\n",
" # IMPORTANT: Uncomment this if using subscription key\n",
" # IMPORTANT: Uncomment this line if using subscription key\n",
" # subscription_key=AZURE_AI_API_KEY,\n",
" x_ms_useragent=\"azure-ai-content-understanding-python/analyzer_management\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
" x_ms_useragent=\"azure-ai-content-understanding-python/analyzer_management\", # This header is used for sample usage telemetry. Comment out this line if you want to opt out.\n",
")"
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]

    • change: Changed "Uncomment this if using subscription key" to "Uncomment this line if using subscription key"
    • rationale: Added the word "line" to specify what exactly needs to be uncommented, improving clarity.
    • impact: Makes the instruction clearer and easier to understand for users.

  • categories: [Formatting, Grammar, Clarity]

    • change: Added an extra space before the inline comment and changed the comment from a comma-separated phrase to two sentences: "This header is used for sample usage telemetry, please comment out this line if you want to opt out." to "This header is used for sample usage telemetry. Comment out this line if you want to opt out."
    • rationale: Added space improves readability; splitting the comment into two sentences enhances grammar and clarity.
    • impact: Improves readability and makes the comment easier to follow and understand.

]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Create a simple analyzer\n",
"We first create an analyzer from a template to extract invoice fields."
"## Create a Simple Analyzer\n",
"First, we create an analyzer from a template to extract invoice fields."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Consistency, Grammar, Clarity]
    • change: Changed the heading from "Create a simple analyzer" to "Create a Simple Analyzer" and revised the sentence from "We first create an analyzer from a template to extract invoice fields." to "First, we create an analyzer from a template to extract invoice fields."
    • rationale: Capitalizing each word in the heading aligns with common documentation style for headings. Changing "We first" to "First," improves sentence flow and clarity.
    • impact: The heading is more visually consistent and professional, and the sentence reads more smoothly, enhancing overall readability.

},
{
Expand All @@ -119,14 +121,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## List all analyzers created in your resource"
"## List All Analyzers in Your Resource"
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Consistency, Formatting]
    • change: Updated the heading from "## List all analyzers created in your resource" to "## List All Analyzers in Your Resource" with capitalization of all main words.
    • rationale: To follow title case convention for section headings, improving uniformity across the documentation.
    • impact: Enhances the professional appearance and readability of the documentation by maintaining consistent heading style.

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"After the analyzer is successfully created, we can use it to analyze our input files."
"After successfully creating an analyzer, you can list all analyzers available in your resource."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Revised the sentence to shift focus from using an analyzer to listing all analyzers available in the resource after creation.
    • rationale: The new sentence clarifies the next actionable step after creating an analyzer, making the documentation more informative and task-oriented.
    • impact: This change improves the clarity of the instructions, helping users understand the functionality and available operations after analyzer creation.

},
{
Expand All @@ -137,17 +139,17 @@
"source": [
"response = client.get_all_analyzers()\n",
"print(f\"Number of analyzers in your resource: {len(response['value'])}\")\n",
"print(f\"The first 3 analyzer details: {json.dumps(response['value'][:3], indent=2)}\")\n",
"print(f\"The last analyzer details: {json.dumps(response['value'][:-1], indent=2)}\")"
"print(f\"Details of the first 3 analyzers: {json.dumps(response['value'][:3], indent=2)}\")\n",
"print(f\"Details of all analyzers except the last one: {json.dumps(response['value'][:-1], indent=2)}\")"
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]

    • change: Updated the print statement to specify "Details of the first 3 analyzers" instead of "The first 3 analyzer details."
    • rationale: Changed the phrasing to be more natural and clear, improving readability by placing the subject ("Details") before the qualifier.
    • impact: Enhances the user’s understanding of what is being printed, making the output message clearer.

  • categories: [Clarity]

    • change: Modified the print statement to say "Details of all analyzers except the last one" instead of "The last analyzer details."
    • rationale: Corrected the description to accurately reflect the data slice response['value'][:-1], which includes all analyzers except the last, rather than just the last analyzer.
    • impact: Prevents confusion by accurately describing the content being displayed, ensuring users correctly interpret the output.

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Get analyzer details with id\n",
"## Get Analyzer Details by ID\n",
"\n",
"Remember the analyzer id when you create it. You can use the id to look up detail analyzer definitions afterwards."
"Keep track of the analyzer ID when you create it. Use the ID to retrieve detailed analyzer definitions later."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity, Consistency]

    • change: Modified the section header from "## Get analyzer details with id" to "## Get Analyzer Details by ID".
    • rationale: Capitalized key words for consistency with title casing and changed wording for clearer, more formal phrasing.
    • impact: Improves readability and maintains a consistent documentation style.

  • categories: [Grammar, Clarity]

    • change: Revised the sentence from "Remember the analyzer id when you create it. You can use the id to look up detail analyzer definitions afterwards." to "Keep track of the analyzer ID when you create it. Use the ID to retrieve detailed analyzer definitions later."
    • rationale: Enhanced sentence structure, improved word choice, and capitalized "ID" for consistency.
    • impact: Provides clearer guidance and more professional tone, making the instruction easier to understand.

},
{
Expand All @@ -164,8 +166,8 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Delete Analyzer\n",
"If you don't need an analyzer anymore, delete it with its id."
"## Delete an Analyzer\n",
"If you no longer need an analyzer, delete it using its ID."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Changed heading from "Delete Analyzer" to "Delete an Analyzer" and revised the sentence from "If you don't need an analyzer anymore, delete it with its id." to "If you no longer need an analyzer, delete it using its ID."
    • rationale: Added the article "an" for grammatical correctness in the heading and rephrased the sentence for clearer, more formal language. Also capitalized "ID" to follow standard technical conventions.
    • impact: Enhances readability and professionalism of the documentation, making instructions clearer and more aligned with common writing standards.

},
{
Expand Down Expand Up @@ -199,4 +201,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
}
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Formatting]
    • change: Added a trailing newline after the closing brace }
    • rationale: Ensures the file ends with a newline character, adhering to common formatting conventions and preventing potential issues with some tools or version control systems.
    • impact: Improves consistency and compatibility with various editors and tools that expect files to end with a newline, enhancing overall codebase quality.