refactor setup, ch4, ch18 - for consistency in assignments

.env.copy

@@ -1,10 +1,12 @@
-# Azure OpenAI configuration
-AZURE_OPENAI_ENDPOINT='<add your endpoint here>'
-AZURE_OPENAI_DEPLOYMENT='<add your deployment name here>' 
-AZURE_OPENAI_KEY='<add your key here>'
-AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your deployment name here>'
+# OpenAI Provider
+OPENAI_API_KEY='<add your OpenAI API key here>'
 
+## Azure OpenAI
+AZURE_OPENAI_API_VERSION='2024-02-01' # Default is set!
+AZURE_OPENAI_API_KEY='<add your AOAI key here>'
+AZURE_OPENAI_ENDPOINT='<add your AOIA service endpoint here>'
+AZURE_OPENAI_DEPLOYMENT='<add your chat completion model name here>' 
+AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model name here>'
 
-# OpenAI Configuration
-
-OPENAI_API_KEY='<add your OpenAI key here>'
+## Hugging Face
+HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

00-course-setup/SETUP.md

@@ -1,54 +1,100 @@
 # Setup Your Dev Environment
 
-We have setup this repository and course with a _dev container_ that comes with a Python 3 runtime. Open the repo in GitHub Codespaces or on your local Docker Desktop, to activate the runtime automatically. Then open th Jupyter notebook and select the Python 3.x kernel to prepare the Notebook for execution.
+We setup this repository and course with a [development container](https://containers.dev?WT.mc_id=academic-105485-koreyst) that has a Universal runtime that can support Python3, .NET, Node.js and Java development. The related configuration is defined in the `devcontainer.json` file located in the `.devcontainer/` folder at the root of this repository.
 
-## 1. Create `.env` file
+To activate the dev container, launch it in [GitHub Codespaces](https://docs.github.com/en/codespaces/overview?WT.mc_id=academic-105485-koreyst) (for a cloud-hosted runtime) or in [Docker Desktop](https://docs.docker.com/desktop/?WT.mc_id=academic-105485-koreyst) (for a local device-hosted runtime). Read [this documentation](https://code.visualstudio.com/docs/devcontainers/containers?WT.mc_id=academic-105485-koreyst) for more details on how dev containers work within VS Code.  
 
-The default notebook (identified by the 'aoai-' suffix) is set up for use with an [Azure OpenAI service resource](https://learn.microsoft.com/azure/ai-services/openai?WT.mc_id=academic-105485-koreyst). However, you have the option to run your assignments by using non-Azure openAI endpoints (choose the 'oai-' prefixed notebooks in this case).
+> [!TIP]  
+> We recommend using GitHub Codespaces for a quick start with minimal effort. It provides a generous [free usage quota](https://docs.github.com/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts) for personal accounts. Configure [timeouts](https://docs.github.com/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) to stop or delete inactive codespaces to maximize your quota usage.
 
-To configure this, we need to setup local environment variables for Azure as follows:
 
-1. Look in the root folder for a `.env.copy` file. It should contain a list of name-value pairs like this:
+## 1. Executing Assignments
+
+Each lesson will have _optional_ assignments that may be provided in one or more programming languages including: Python, .NET/C#, Java and JavaScript/TypeScript. This section provides general guidance related to executing those assignments.
+
+### 1.1 Python Assignments
+
+Python assignments are provided either as applications (`.py` files) or Jupyter notebooks (`.ipynb` files). 
+- To run the notebook, open it in Visual Studio Code then click _Select Kernel_ (at top right) and select the default Python 3 option shown. You can now _Run All_ to execute the notebook.
+- To run Python applications from command-line, follow assignment-specific instructions to ensure you select the right files and provide required arguments
+
+## 2. Configuring Providers
+
+Assignments **may** also be setup to work against one or more Large Language Model (LLM) deployments through a supported service provider like OpenAI, Azure or Hugging Face. These provide a _hosted endpoint_ (API) that we can access programmatically with the right credentials (API key or token). In this course, we discuss these providers:
+
+ - [OpenAI](https://platform.openai.com/docs/models) with diverse models including the core GPT series.
+ - [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/) for OpenAI models with enterprise readiness in focus
+ - [Hugging Face](https://huggingface.co/docs/hub/index) for open-source models and inference server
+
+**You will need to use your own accounts for these exercises**. Assignments are optional so you can choose to setup one, all - or none - of the providers based on your interests. Some guidance for signup:
+
+| Signup | Cost | API Key | Playground | Comments |
+|:---|:---|:---|:---|:---|
+| [OpenAI](https://platform.openai.com/signup)| [Pricing](https://openai.com/pricing#language-models)| [Project-based](https://platform.openai.com/api-keys) | [No-Code, Web](https://platform.openai.com/playground) | Multiple Models Available |
+| [Azure](https://aka.ms/azure/free)| [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)| [SDK Quickstart](https://learn.microsoft.com/azure/ai-services/openai/quickstart?tabs=command-line%2Cpython-new&pivots=programming-language-python#retrieve-key-and-endpoint)| [Studio Quickstart](https://learn.microsoft.com/azure/ai-services/openai/quickstart?tabs=command-line%2Cpython-new&pivots=programming-language-studio#playground) |  [Must Apply Ahead For Access](https://learn.microsoft.com/azure/ai-services/openai/)|
+| [Hugging Face](https://huggingface.co/join) | [Pricing](https://huggingface.co/pricing) | [Access Tokens](https://huggingface.co/docs/hub/security-tokens) | [Hugging Chat](https://huggingface.co/chat/)| [Hugging Chat has limited models](https://huggingface.co/chat/models) |
+| | | | | |
+
+Follow the directions below to _configure_ this repository for use with different providers. Assignments that require a specific provider will contain one of these tags in their filename:
+ - `aoai` - requires Azure OpenAI endpoint, key
+ - `oai` - requires OpenAI endpoint, key
+ - `hf` - requires Hugging Face token
+
+You can configure one, none, or all providers. Related assignments will simply error out on missing credentials.
+
+###  2.1. Create `.env` file
+
+We assume that you have already read the guidance above and signed up with the relevant provider, and obtained the required authentication credentials (API_KEY or token). In the case of Azure OpenAI, we assume you also have a valid deployment of an Azure OpenAI service (endpoint) with at least one GPT model deployed for chat completion.
+
+The next step is to configure your **local environment variables** as follows:
+
+
+1. Look in the root folder for a `.env.copy` file that should have contents like this:
 
    ```bash
-   AZURE_OPENAI_ENDPOINT='<add your endpoint here>'
-   AZURE_OPENAI_DEPLOYMENT='<add your deployment name here>'
-   AZURE_OPENAI_KEY='<add your key here>'
-   AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your deployment name here>'
+   # OpenAI Provider
+   OPENAI_API_KEY='<add your OpenAI API key here>'
+
+   ## Azure OpenAI
+   AZURE_OPENAI_API_VERSION='2024-02-01' # Default is set!
+   AZURE_OPENAI_API_KEY='<add your AOAI key here>'
+   AZURE_OPENAI_ENDPOINT='<add your AOIA service endpoint here>'
+   AZURE_OPENAI_DEPLOYMENT='<add your chat completion model name here>' 
+   AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model name here>'
+
+   ## Hugging Face
+   HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'
    ```
 
-2. Make a copy of that file called `.env` using a command like this at the terminal:
+2. Copy that file to `.env` using the command below. This file is _gitignore-d_, keeping secrets safe.
 
    ```bash
    cp .env.copy .env
    ```
 
-   This should create an identical copy _except that this file is .gitignore-d and will never get checked into source control_. We can now populate **this .env file** with the environment variable values (secrets) without fear of them being checked in accidentally. You can now move to the next section to start populating these variables.
+3. Fill in the values (replace placeholders on right side of `=`) as described in the next section.
 
 3. (Option) If you use GitHub Codespaces, you have the option to save environment variables as _Codespaces secrets_ associated with this repository. In that case, you won't need to setup a local .env file. **However, note that this option works only if you use GitHub Codespaces.** You will still need to setup the .env file if you use Docker Desktop instead.
 
-The above steps should be executed also if you are using the non-Azure OpenAI endpoints. In that case, you will need to populate the .env file with the appropriate values for the OpenAI service.
-
-```bash
-OPENAI_API_KEY='<add your OpenAI key here>'
-```
 
-## 2. Populate `.env` file
+### 2.2. Populate `.env` file
 
 Let's take a quick look at the variable names to understand what they represent:
 
-| Variable                           | Description                                                                        |
-| :--------------------------------- | :--------------------------------------------------------------------------------- |
-| AZURE_OPENAI_ENDPOINT              | This is the deployed endpoint for an Azure OpenAI resource                         |
-| AZURE_OPENAI_KEY                   | This is the authorization key for using that service                               |
-| OPENAI_API_KEY                     | This is the authorization key for using the service for non-Azure OpenAI endpoints |
-| AZURE_OPENAI_DEPLOYMENT            | This is the _text generation_ model deployment endpoint                            |
-| AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT | This is the _text embeddings_ model deployment endpoint                            |
-|                                    |                                                                                    |
+| Variable  | Description  |
+| :--- | :--- |
+| HUGGING_FACE_API_KEY | This is the user access token you setup in your profile |
+| OPENAI_API_KEY | This is the authorization key for using the service for non-Azure OpenAI endpoints |
+| AZURE_OPENAI_KEY | This is the authorization key for using that service |
+| AZURE_OPENAI_ENDPOINT | This is the deployed endpoint for an Azure OpenAI resource |
+| AZURE_OPENAI_DEPLOYMENT | This is the _text generation_ model deployment endpoint |
+| AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT | This is the _text embeddings_ model deployment endpoint |
+| | |
+
+Note: The last two Azure OpenAI variables reflect a default model for chat completion (text generation) and vector search (embeddings) respectively. Instructions for setting them will be defined in relevant assignments.
 
-For context, the last two variables refer to specific models that are used in chat completion (text generation model) and vector search (embeddings model) activities that are frequently used in generative AI applications. In the following sections, we'll locate the _values_ for these variables and set them in `.env` (replacing the content within the `' '`, but preserving the quotes).
 
-### 2.1 Use Azure Portal
+### 2.3 Configure Azure: From Portal
 
 The Azure OpenAI endpoint and key values will be found in the [Azure Portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst) so let's start there.
 
@@ -65,7 +111,7 @@ Next, we need the endpoints for the specific models we've deployed.
 
 This will take you to the Azure OpenAI Studio website, where we'll find the other values as described below.
 
-### 2.2 Use Azure OpenAI Studio
+### 2.4 Configure Azure: From Studio
 
 1. Navigate to [Azure OpenAI Studio](https://oai.azure.com?WT.mc_id=academic-105485-koreyst) **from your resource** as described above.
 1. Click the **Deployments** tab (sidebar, left) to view currently deployed models.
@@ -82,6 +128,10 @@ AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-ada-002'
 
 **Don't forget to save the .env file when done**. You can now exit the file and return to the instructions for running the notebook.
 
-### 2.3 Use OpenAI Public API
+### 2.5 Configure OpenAI: From Profile
 
 Your OpenAI API key can be found in your [OpenAI account](https://platform.openai.com/api-keys?WT.mc_id=academic-105485-koreyst). If you don't have one, you can sign up for an account and create an API key. Once you have the key, you can use it to populate the `OPENAI_API_KEY` variable in the `.env` file.
+
+### 2.6 Configure Hugging Face: From Profile
+
+Your Hugging Face token can be found in your profile under [Access Tokens](https://huggingface.co/settings/tokens). Don't post or share these publicly. Instead, create a new token for this project usage and copy that into the `.env` file under the `HUGGING_FACE_API_KEY` variable. _Note:_ This is technically not an API key but is used for authentication so we are keeping that naming convention for consistency.

04-prompt-engineering-fundamentals/README.md

@@ -29,7 +29,7 @@ The Jupyter Notebook accompanying this lesson provides a _sandbox_ environment w
 
 1. **An Azure OpenAI API key** - the service endpoint for a deployed LLM.
 2. **A Python Runtime** - in which the Notebook can be executed.
-3. **Local Env Variables** - _complete the [SETUP](SETUP.md) steps now to get ready_.
+3. **Local Env Variables** - _complete the [SETUP](./../00-course-setup/SETUP.md) steps now to get ready_.
 
 The notebook comes with _starter_ exercises - but you are encouraged to add your own _Markdown_ (description) and _Code_ (prompt requests) sections to try out more examples or ideas - and build your intuition for prompt design.