Brkrabac/updated docs (#45)

.devcontainer/.vscode/settings.json

@@ -1,9 +1,11 @@
 {
     "cSpell.words": [
         "aarontamasfe",
+        "Codespace",
         "codespaces",
         "dbaeumer",
         "debugpy",
+        "devcontainer",
         "devcontainers",
         "epivision",
         "esbenp",

.devcontainer/README.md

@@ -40,20 +40,23 @@ For more details on using GitHub Codespaces in VS Code, see the [documentation](
 
 ### Start the app and service
 
+- Launch the [semantic-workbench.code-workspace](../semantic-workbench/v1/semantic-workbench.code-workspace) in VS Code
+  - Use the command palette: `Ctrl/Cmd+P` and type `semantic-workbench.code-workspace` to open the workspace file
+  - Click `Open Workspace` button in lower right corner to launch the workspace
 - Use VS Code > `Run and Debug` (Ctrl/Cmd+Shift+D) > `semantic-workbench` to start the project
-- Open your browser and navigate to `https://localhost:4000`
+- Open your browser and navigate to `https://127.0.0.1:4000`
   - You may receive a warning about the app not being secure; click `Advanced` and `Proceed to localhost` to continue
 - You can now interact with the app and service in the browser
 
 See the [README](../README.md) for more details on how to use the Semantic Workbench app and service.
 
 ### Next steps:
 
-- Launch an assistant service:
+- Launch an example assistant service:
   - Using the [canonical assistant](../semantic-workbench/v1/service/semantic-workbench-assistant/README.md)
     - Use VS Code > `Run and Debug` (Ctrl/Cmd+Shift+D) > `canonical-assistant` to start the canonical assistant
   - Using an [example assistant](../examples/)
-    - Use VS Code > `Run and Debug` (Ctrl/Cmd+Shift+D) > `python-example01` to start the example assistant
+    - Use VS Code > `Run and Debug` (Ctrl/Cmd+Shift+D) > `launch assistant (examples/python-01-echo-bot)` to start the example assistant
   - Or create your own assistant service by following the [Assistant Development Guide](../docs/ASSISTANT_DEVELOPMENT_GUIDE.md)
 - 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
@@ -64,7 +67,7 @@ See the [README](../README.md) for more details on how to use the Semantic Workb
 
 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.
+See the [python-01-echo-bot/README](../examples/python-01-echo-bot/README.md) for more details.
 
 ## Deleting a Codespace
 

KNOWN_ISSUES.md

@@ -4,8 +4,10 @@ You may encounter the following known issues, which may include workarounds, mit
 
 ## Semantic Workbench App
 
-### Error loading conversations: {"name":"BrowserAuthError","message":"hash_empty_error: Hash value cannot be processed because it is empty. Please verify that your redirectUri is not clearing the hash.
+### Error loading conversations: {"name":"BrowserAuthError","message":"hash_empty_error: Hash value cannot be processed because it is empty. Please verify that your redirectUri is not clearing the hash..."}
+
 This error may appear when the access token for your login has expired and is not refreshing properly. More exploration is needed for the actual fix.
 
 **Workaround**
-1. If you encouter this error when using the Semantic Workbench app, please log out of the web app (upper right corner) and log back in.
+
+1. If you encounter this error when using the Semantic Workbench app, please log out of the web app (upper right corner) and log back in.

README.md

@@ -7,16 +7,16 @@ or more assistants, configuring settings, and exposing various behaviors.
 
 The Semantic Workbench is composed of three main components:
 
-1. [Workbench Service](semantic-workbench/v1/service/README.md) (Python): The backend service that
-   handles core functionalities.
-2. [Workbench App](semantic-workbench/v1/app/README.md) (React/Typescript): The frontend web user
-   interface for interacting with workbench and assistants.
-3. Assistant Services: any number of assistant services that implement the service protocols/APIs,
-   developed using any framework and programming language of your choice.
+- [Workbench Service](semantic-workbench/v1/service/README.md) (Python): The backend service that
+  handles core functionalities.
+- [Workbench App](semantic-workbench/v1/app/README.md) (React/Typescript): The frontend web user
+  interface for interacting with workbench and assistants.
+- [Assistant Services](examples) (Python, C#, etc.): any number of assistant services that implement the service protocols/APIs,
+  developed using any framework and programming language of your choice.
 
 Designed to be agnostic of any agent framework, language, or platform, the Semantic Workbench
 facilitates experimentation, development, testing, and measurement of agent behaviors and workflows.
-Agents integrate with the workbench via a RESTful API, allowing for flexibility and broad applicability
+Assistants integrate with the workbench via a RESTful API, allowing for flexibility and broad applicability
 in various development environments.
 
 ![Semantic Workbench architecture](https://raw.githubusercontent.com/microsoft/semanticworkbench/main/docs/architecture-animation.gif)
@@ -40,54 +40,56 @@ See the [GitHub Codespaces / devcontainer README](.devcontainer/README.md) for m
 
 ![image](https://raw.githubusercontent.com/microsoft/semanticworkbench/main/docs/readme3.png)
 
-# Connecting your agents
+# Connecting your assistants
 
-To develop new agents and connect existing ones, see the [Assistant Development Guide](docs/ASSISTANT_DEVELOPMENT_GUIDE.md)
+To develop new assistants and connect existing ones, see the [Assistant Development Guide](docs/ASSISTANT_DEVELOPMENT_GUIDE.md)
 
-The repository contains a few examples that can be used to create custom agents:
+The repository contains a few examples that can be used to create custom assistants:
 
 - [Python Canonical Assistant](semantic-workbench/v1/service/semantic-workbench-assistant/semantic_workbench_assistant/canonical.py)
-- [Python example 1](examples/python-example01/README.md): a simple assistant echoing text back.
+- [Python example 1](examples/python-01-echo-bot/README.md): a simple assistant echoing text back.
+- [Python example 2](examples/python-02-simple-chatbot/README.md): a simple chatbot implementing metaprompt guardrails and content moderation.
 - [.NET example 1](examples/dotnet-01-echo-bot/README.md): a simple agent with echo and support for a basic `/say` command.
-- [.NET example 2](examples/dotnet-02-message-types-demo/README.md): a simple agents showcasing Azure AI Content Safety integration and some workbench features like Mermaid graphs.
+- [.NET example 2](examples/dotnet-02-message-types-demo/README.md): a simple assistants showcasing Azure AI Content Safety integration and some workbench features like Mermaid graphs.
 - [.NET example 3](examples/dotnet-03-simple-chatbot/README.md): a functional chatbot implementing metaprompt guardrails and content moderation.
 
-![Mermaid graph example](examples/dotnet-example02/docs/mermaid.png)
-![ABC music example](examples/dotnet-example02/docs/abc.png)
+![Mermaid graph example](examples/dotnet-02-message-types-demo/docs/mermaid.png)
+![ABC music example](examples/dotnet-02-message-types-demo/docs/abc.png)
 
 # Workbench setup
 
-1. Follow the [Service Setup Guide](semantic-workbench/v1/service/README.md)
-2. Follow the [App Setup Guide](semantic-workbench/v1/app/README.md)
+- Follow the [Service Setup Guide](semantic-workbench/v1/service/README.md)
+- Follow the [App Setup Guide](semantic-workbench/v1/app/README.md)
 
 ## Windows setup
 
 Enable long file paths on Windows.
 
-1.  Run `regedit`.
-2.  Navigate to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem`.
-3.  Find the `LongPathsEnabled` key. If it doesn’t exist, right-click on the `FileSystem` key, select `New > DWORD (32-bit) Value`, and name it `LongPathsEnabled`.
-4.  Double-click on `LongPathsEnabled`, set its value to `1`, and click OK.
+- Run `regedit`.
+- Navigate to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem`.
+- Find the `LongPathsEnabled` key. If it doesn’t exist, right-click on the `FileSystem` key, select `New > DWORD (32-bit) Value`, and name it `LongPathsEnabled`.
+- Double-click on `LongPathsEnabled`, set its value to `1`, and click OK.
 
 ## Open the Workbench and create an assistant instance
 
 Open the app in your browser at [`https://localhost:4000`](https://localhost:4000):
 
-1. Click `Sign in`
-2. Add and Assistant:
-   1. Click +Add Assistant Button
-   2. Click Instance of Assistant
-3. Give it a name.
-4. Enter the assistant service URL in the combobox, e.g. `http://127.0.0.1:3010`.
-5. Click Chat box icon.
-6. Type a message and hit send.
-7. If you see "Please set the OpenAI API key in the config."
-   1. Click Edit icon in upper right.
-   2. Paste in your OpenAI Key.
-   3. Paste in your OrgID.
-   4. Click Save.
-   5. Hit Back button in UI.
-8. Type another message and hit send.
+- Click `Sign in`
+- Add and Assistant:
+  - Click +Add Assistant Button
+  - Click Instance of Assistant
+- Give it a name.
+- Enter the assistant service URL in the combobox, e.g. `http://127.0.0.1:3010`.
+- Click the assistant name to configure the instance.
+- Create a new conversation from the assistant configuration screen, then click the conversation name to interact with the assistant.
+- Type a message and hit send.
+- If you see "Please set the OpenAI API key in the config."
+  - Click Edit icon in upper right.
+  - Paste in your OpenAI Key.
+  - Paste in your OrgID.
+  - Click Save.
+  - Hit Back button in UI.
+- Type another message and hit send.
 
 Expected: You get a response from your assistant!
 

assistant-connector/python/README.md

@@ -1,4 +1,4 @@
 To connect your python assistants and agents to Semantic Workbench, please see
 [semantic-workbench-assistant.assistant_app](../../semantic-workbench/v1/service/semantic-workbench-assistant/semantic_workbench_assistant/assistant_app/).
 
-You can also check [python example 1](../../examples/python-example01/assistant/chat.py) for a quick reference.
+You can also check [python-01-echo-bot](../../examples/python-01-echo-bot/assistant/chat.py) for a quick reference.

assistants/prospector-assistant/README.md

@@ -1,7 +1,6 @@
 # Using Semantic Workbench with python assistants
 
-This project provides an assistant to help mine artifacts for ideas, leveraging OpenAI or Azure OpenAI (or any OpenAI compatible service),
-allowing to use **Semantic Workbench** to test it.
+This project provides an assistant to help mine artifacts for ideas, leveraging OpenAI or Azure OpenAI (or any OpenAI compatible service), allowing to use **Semantic Workbench** to test it.
 
 ## Responsible AI
 
@@ -16,15 +15,24 @@ The chatbot includes some important best practices for AI development, such as:
 - **Content moderation**, via [Azure AI Content Safety](https://azure.microsoft.com/products/ai-services/ai-content-safety)
   or [OpenAI Content Moderation](https://platform.openai.com/docs/guides/moderation).
 
+See the [Responsible AI FAQ](../../RESPONSIBLE_AI_FAQ.md) for more information.
+
+# Suggested Development Environment
+
+- Use GitHub Codespaces for a quick, turn-key dev environment: [/.devcontainer/README.md](../../.devcontainer/README.md)
+- VS Code is recommended for development
+
 ## Pre-requisites
 
 - Set up your dev environment
   - SUGGESTED: Use GitHub Codespaces for a quick, easy, and consistent dev
     environment: [/.devcontainer/README.md](../../.devcontainer/README.md)
   - ALTERNATIVE: Local setup following the [main README](../../README.md#quick-start---local-development-environment)
-- Set up and verify that the workbench app and service are running
-- Stop the services and open the [assistant.code-workspace](./assistant.code-workspace) in VS Code
-  - You should always stop the services before switching workspaces, otherwise the services will not be able to start in the new workspace
+- Set up and verify that the workbench app and service are running using the [semantic-workbench.code-workspace](../../semantic-workbench/v1/semantic-workbench.code-workspace)
+- If using Azure OpenAI, set up an Azure account and create a Content Safety resource
+  - See [Azure AI Content Safety](https://azure.microsoft.com/products/ai-services/ai-content-safety) for more information
+  - Copy the `.env.example` to `.env` and update the `ASSISTANT__AZURE_CONTENT_SAFETY_ENDPOINT` value with the endpoint of your Azure Content Safety resource
+  - From VS Code > `Terminal`, run `az login` to authenticate with Azure prior to starting the assistant
 
 ## Steps
 
@@ -55,11 +63,6 @@ Copy the contents of this folder to your project.
 - The paths are already set if you put in the same repo root and relative path of `/<your_projects>/<your_assistant_name>`
 - If placed in a different location, update the references in the `pyproject.toml` to point to the appropriate locations for the `semantic-workbench-*` packages
 
-## Suggested Development Environment
-
-- Use GitHub Codespaces for a quick, turn-key dev environment: [/.devcontainer/README.md](../../.devcontainer/README.md)
-- VS Code is recommended for development
-
 ## From Development to Production
 
 It's important to highlight how Semantic Workbench is a development tool, and it's not designed to host agents in

assistants/prospector-assistant/assistant/chat.py

@@ -269,10 +269,12 @@ async def respond_to_conversation(
         )
     system_message_content += f"\n\n{assistant_config.guardrails_prompt}"
 
-    completion_messages: list[ChatCompletionMessageParam] = [{
-        "role": "system",
-        "content": system_message_content,
-    }]
+    completion_messages: list[ChatCompletionMessageParam] = [
+        {
+            "role": "system",
+            "content": system_message_content,
+        }
+    ]
 
     # add the attachment agent messages to the completion messages
     if assistant_config.agents_config.attachment_agent.include_in_response_generation:

assistants/prospector-assistant/assistant/config.py

@@ -109,9 +109,7 @@ class AzureOpenAIServiceConfig(BaseModel):
                 " be used."
             ),
         ),
-    ] = (
-        config.first_env_var("azure_openai_endpoint", "assistant__azure_openai_endpoint") or ""
-    )
+    ] = config.first_env_var("azure_openai_endpoint", "assistant__azure_openai_endpoint") or ""
 
     azure_openai_deployment: Annotated[
         str,
@@ -278,12 +276,6 @@ class AssistantConfigModel(BaseModel):
         " to download the midi file."
     )
 
-    # "You are an AI assistant that helps teams synthesize information from conversations and documents to create"
-    #     " a shared understanding of complex topics. As you do so, there are tools observing the conversation and"
-    #     " they will automatically create an outline and a document based on the conversation, you don't need to do"
-    #     " anything special to trigger this, just have a conversation with the user. Focus on assisting the user and"
-    #     " drawing out the info needed in order to bring clarity to the topic at hand."
-
     guardrails_prompt: Annotated[
         str,
         Field(

assistants/prospector-assistant/assistant/responsible_ai/azure_evaluator.py

@@ -7,8 +7,6 @@
 from azure.ai.contentsafety import ContentSafetyClient
 from azure.ai.contentsafety.models import AnalyzeTextOptions
 from azure.identity import DefaultAzureCredential
-
-
 from pydantic import BaseModel, Field
 from semantic_workbench_assistant import config
 from semantic_workbench_assistant.assistant_app import (
@@ -27,9 +25,7 @@ class AzureContentSafetyEvaluatorConfigModel(BaseModel):
             title="Azure Content Safety Service Endpoint",
             description="The endpoint to use for the Azure Content Safety service.",
         ),
-    ] = (
-        config.first_env_var("azure_content_safety_endpoint", "assistant__azure_content_safety_endpoint") or ""
-    )
+    ] = config.first_env_var("azure_content_safety_endpoint", "assistant__azure_content_safety_endpoint") or ""
 
     warn_at_severity: Annotated[
         Literal[0, 2, 4, 6],

docs/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "cSpell.words": [
+        "Codespace",
+        "Codespaces",
+        "devcontainer",
+        "devtunnel",
+        "msal",
+        "winget"
+    ]
+}