-
Notifications
You must be signed in to change notification settings - Fork 30
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation, assistant-base, and python example updates (#27)
* add git config autoSetupRemote to devcontainer setup * improved handling of config from env * better azure app service logging support * async keyvault api * adds recommended vscode extensions * improved documentation * additional clean up for python example
- Loading branch information
Showing
18 changed files
with
434 additions
and
201 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,23 +1,64 @@ | ||
# Using GitHub Codespaces with devcontainers for Semantic Workbench | ||
|
||
- Create app registration at https://portal.azure.com | ||
- Name: Semantic Workbench | ||
- Supported account types: Accounts in any organizational directory and personal Microsoft accounts | ||
- Redirect URI: Single-page application (SPA) & `https://<YOUR_CODESPACE_HOST>-4000.app.github.dev` | ||
- Copy the Application (client) ID from Overview | ||
- Update `constants.ts` with the Application (client) ID | ||
- Update `middleware.py` with the Application (client) ID | ||
- Use VS Code > Run and Debug > `Semantic Workbench` to start both the app and the service | ||
- After launching semantic-workbench-service, go to Ports and make 3000 public | ||
- In the VS Code terminal tab, find the semantic-workbench-app and click on the link to open the app | ||
This folder contains the configuration files for using GitHub Codespaces with devcontainers for Semantic Workbench and assistant development. | ||
|
||
## Python assistant example | ||
GitHub Codespaces is a feature of GitHub that provides a cloud-based development environment for your repository. It allows you to develop, build, and test your code in a consistent environment, without needing to install dependencies or configure your local machine. | ||
|
||
We have included an example Python assistant that echos the user's input and can serve as a starting point for your own assistant. | ||
## Why | ||
|
||
See the [Python assistant example README](../examples/python-example01/README.md) for more details. | ||
- **Consistent environment**: All developers use the same environment, regardless of their local setup. | ||
- **Platform agnostic**: Works on any system with a web browser and internet connection, including Chromebooks, tablets, and mobile devices. | ||
- **Isolated environment**: The devcontainer is isolated from the host machine, so you can install dependencies without affecting your local setup. | ||
- **Quick setup**: You can start developing in a few minutes, without needing to install dependencies or configure your environment. | ||
|
||
## TODO | ||
## How to use | ||
|
||
- [ ] Add support for reading Application (client) ID from environment variables | ||
- [ ] Improve this README with details on App Registration setup, and more detailed steps | ||
### Pre-requisites | ||
|
||
#### Create a new GitHub Codespace | ||
|
||
- Open the repository in GitHub Codespaces | ||
- Navigate to the [repository in GitHub](https://github.com/microsoft/semanticworkbench) | ||
- Click on the `Code` button and select the `Codespaces` tab | ||
- Click on the `Codespaces` > `+` button | ||
- Allow the Codespace to build and start, which may take a few minutes - you may continue to the next steps while it builds | ||
- Make a note of your Codespace host name, which is the part of the URL before `.github.dev`. | ||
|
||
#### Set up the workbench app and service | ||
|
||
While the Codespaces environment makes it easy to start developing, the hard-coded app registration details in the app and service cannot support a wildcard redirect URI. This means you will need to create your own Azure app registration and update the app and service files with the new app registration details. | ||
|
||
Follow the instructions in the [Custom app registration](../docs/CUSTOM_APP_REGISTRATION.md) guide to create a new Azure app registration and update the app and service files with the new app registration details. | ||
|
||
### Using the Codespace in VS Code | ||
|
||
#### Launch the Codespace | ||
|
||
- Open the repository in VS Code | ||
- Click on the `Code` button and select the Codespaces tab and choose the Codespace you created | ||
- Since the Codespace is available as a Progressive Web App (PWA), you can also run the Codespace as a local app (in its own window, taskbar/dock/home icon, etc.) for quicker access. See the following links for general information on installing PWAs: | ||
- [Microsoft Edge](https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/ux) | ||
- Search the internet for `install PWA on <browser/platform>` for help with other browsers/platforms | ||
|
||
#### Start the app and service | ||
|
||
- Use VS Code > `Run and Debug` (Ctrl/Cmd+Shift+D) > `Semantic Workbench` to start both the app and the service | ||
- Once `semantic-workbench-service` has launched, you will need to make it `public` | ||
- The app uses the service to fetch data and it must be accessible from the browser of the user logged into the app, which is why the service endpoint must be public. This also means it is accessible to anyone with the URL. To provide a minimal level of security, the app registration is required. Any calls to the service must include an access token from a user logged into the configured app registration. | ||
- In VS Code go to the `ports` tab (same pane as the `terminal` where the services are running) | ||
- Right-click on the `service:semantic-workbench-service` (Port 3000) and select `Port Visibility` > `Public` | ||
- In the VS Code `terminal` tab, find the `semantic-workbench-app` and click on the `Local` link to open the app | ||
- This will automatically open the app in a new browser tab, navigating to the correct Codespace host and setting the necessary header values to privately access the app | ||
- You can now interact with the app and service in the browser | ||
- Next steps: | ||
- Launch an assistant service, using an [example assistant](../examples/) or your own assistant | ||
- If launching an assistant service from within the same Codespace, it will be automatically accessible to the Semantic Workbench service | ||
- Add the assistant to the workbench app by clicking the `Add Assistant` button in the app and selecting the assistant from the list | ||
- Configure the assistant and interact with it in the app by clicking on the assistant in the list | ||
- From the assistant configuration screen, click `New Conversation` to start a new conversation with the assistant | ||
|
||
## Assistant service example | ||
|
||
We have included an example Python assistant service that echos the user's input and can serve as a starting point for your own assistant service. | ||
|
||
See the [python-example01/README](../examples/python-example01/README.md) for more details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
{ | ||
"recommendations": [ | ||
"aaron-bond.better-comments", | ||
"dbaeumer.vscode-eslint", | ||
"esbenp.prettier-vscode", | ||
"ms-python.black-formatter", | ||
"ms-python.flake8", | ||
"ms-python.python", | ||
"streetsidesoftware.code-spell-checker" | ||
] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# Custom app registration | ||
|
||
The code in this repo is intended to allow for quick-to-try usage. This includes a hard-coded app registration details in the app and service. While this works for minimal setup for development and usage in localhost environments, you will need to create your own Azure app registration and update the app and service files with the new app registration details if you want to use this in a hosted environment. | ||
|
||
**DISCLAIMER**: The security considerations of hosting a service with a public endpoint are beyond the scope of this document. Please ensure you understand the implications of hosting a service before doing so. It is **not recommended** to host a publicly available instance of the Semantic Workbench app. | ||
|
||
## Create a new Azure app registration | ||
|
||
### Prerequisites | ||
|
||
In order to complete these steps, you will need to have an Azure account. If you don't have an Azure account, you can create a free account by navigating to https://azure.microsoft.com/en-us/free. | ||
|
||
App registration is a free service, but you may need to provide a credit card for verification purposes. | ||
|
||
### Steps | ||
|
||
- Navigate to the [Azure portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) | ||
- Click on `New registration` and fill in the details | ||
- Name: `Semantic Workbench` (or any name you prefer) | ||
- Supported account types: `Accounts in any organizational directory and personal Microsoft accounts` | ||
- Redirect URI: `Single-page application (SPA)` & `https://<YOUR_HOST>` | ||
- Example (if using [Codespaces](../.devcontainer/README.md)): `https://<YOUR_CODESPACE_HOST>-4000.app.github.dev` | ||
- Click on `Register` | ||
- View the `Overview` page for the newly registered app and copy the `Application (client) ID` for the next steps | ||
|
||
## Update your app and service files with the new app registration details | ||
|
||
Edit the following files with the new app registration details: | ||
|
||
- Semantic Workbench app: [constants.ts](../semantic-workbench/v1/app/src/Constants.ts) | ||
|
||
- Update the `msal.auth.clientId` with the `Application (client) ID` | ||
|
||
- Semantic Workbench service: [middleware.py](../semantic-workbench/v1/service/semantic-workbench-service/semantic_workbench_service/middleware.py) | ||
- Update the `allowed_app_ids` with the `Application (client) ID` | ||
|
||
## TODO | ||
|
||
- [ ] Update the codebase to allow app registration details to be passed in as environment variables |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.