Adds navigator assistant (#535)

- updates to workbench-service and ConversationContext to allow
assistants to query the available assistant services
- assistant services advertise their descriptions for the navigator
service, by providing a special key in their metadata
- the descriptions for the project-assistant, codespace-assistant, and
document-assistant have been created and are advertised by the
respective services

Additionally:
- includes the full message object in the debug panel, in addition to
the debug data (so you can see the message type and other metadata)

Author: markwaddle

.github/workflows/assistants-navigator-assistant.yml

@@ -0,0 +1,82 @@
+name: navigator-assistant continuous integration
+
+on:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "assistants/navigator-assistant/**"
+      - "libraries/python/**"
+      - "tools/docker/**"
+      - ".github/workflows/assistants-navigator-assistant.yml"
+
+  push:
+    branches: ["main"]
+    paths:
+      - "assistants/navigator-assistant/**"
+      - "libraries/python/**"
+      - "tools/docker/**"
+      - ".github/workflows/assistants-navigator-assistant.yml"
+
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: assistants/navigator-assistant
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: test
+        run: |
+          make test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: docker-build
+        run: |
+          make docker-build
+
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      id-token: write # for OIDC login
+      contents: read
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    needs: [build, test]
+    if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main' && vars.DEPLOYMENT_ENABLED == 'true' }}
+    env:
+      DOCKER_IMAGE_TAG: ${{ github.sha }}
+      DOCKER_REGISTRY_NAME: ${{ secrets.AZURE_CONTAINER_REGISTRY_NAME }}
+      AZURE_WEBSITE_RESOURCE_GROUP: ${{ secrets.AZURE_WEBSITE_RESOURCE_GROUP }}
+      AZURE_WEBSITE_SUBSCRIPTION: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: docker-push
+        run: |
+          make docker-push
+
+      - name: docker-deploy
+        run: |
+          make docker-deploy

assistants/codespace-assistant/assistant/chat.py

@@ -10,7 +10,7 @@
 from typing import Any
 
 import deepmerge
-from assistant_extensions import attachments, dashboard_card, document_editor, mcp
+from assistant_extensions import attachments, dashboard_card, document_editor, mcp, navigator
 from content_safety.evaluators import CombinedContentSafetyEvaluator
 from semantic_workbench_api_model.workbench_model import (
     ConversationEvent,
@@ -103,6 +103,10 @@ async def content_evaluator_factory(context: ConversationContext) -> ContentSafe
                 ),
             ),
         ),
+        **navigator.metadata_for_assistant_navigator({
+            "default": helpers.load_text_include("codespace_assistant_info.md"),
+            "context_transfer": helpers.load_text_include("context_transfer_assistant_info.md"),
+        }),
     },
 )
 

assistants/codespace-assistant/assistant/text_includes/codespace_assistant_info.md

@@ -0,0 +1,62 @@
+# Codespace Assistant
+
+## Overview
+
+The Codespace Assistant is an AI-powered coding companion designed to help developers work effectively within development environments. It provides intelligent code assistance, project guidance, and insights about your codespace to accelerate development tasks and enhance productivity.
+
+## Key Features
+
+- **Contextual code understanding**: Analyzes your codebase to provide relevant suggestions and answers.
+- **Code generation and recommendations**: Helps write, modify, and refactor code across multiple files.
+- **Project navigation**: Assists with exploring repositories and finding relevant files.
+- **Development workflow guidance**: Suggests approaches for common development tasks like building, testing, and debugging.
+- **Multi-language support**: Works across various programming languages and frameworks.
+- **VS Code integration**: Provides suggestions related to VS Code extensions and tools.
+
+## How to Use the Codespace Assistant
+
+### Getting Started
+
+1. **Start a conversation**: Create a new conversation and add the Codespace Assistant.
+2. **Describe your project**: Tell the assistant about what you're working on to get contextual help.
+3. **Ask development questions**: Get information about code, architecture, or development practices.
+4. **Request coding assistance**: Ask for help with writing code, fixing bugs, or implementing features.
+
+### Project Exploration
+
+- **Code search**: Ask the assistant to find specific code patterns or functionality in your project.
+- **Repository understanding**: Request explanations of project structure, dependencies, or configuration.
+- **File navigation**: Get help locating relevant files for specific features or components.
+- **Dependency analysis**: Understand package dependencies and version requirements.
+
+### Coding Support
+
+- **Code generation**: Request new code to implement specific functionality.
+- **Bug fixing**: Get help identifying and fixing issues in your code.
+- **Refactoring assistance**: Improve code structure and quality with guided refactoring.
+- **Code reviews**: Get feedback on your implementation approaches.
+- **Testing support**: Generate unit tests and validate code functionality.
+
+### Development Guidance
+
+- **Build process recommendations**: Get guidance on compiling, building, or packaging your code.
+- **Application configuration**: Receive help with configuring and understanding applications.
+- **Environment setup advice**: Get suggestions for development environments and tools.
+- **Debugging guidance**: Troubleshoot issues and interpret error messages.
+
+## Workflow Integration
+
+- **Work alongside your normal development**: The assistant complements your existing development workflow rather than replacing it.
+- **Interactive help**: Ask specific questions when you get stuck rather than spending time searching for answers.
+- **Contextual awareness**: The assistant understands your project context and provides relevant suggestions.
+- **Continuous learning**: As you interact with the assistant, it better understands your project and preferences.
+
+## Common Use Cases
+
+- **New project exploration**: Quickly understand unfamiliar codebases and architecture.
+- **Feature implementation**: Get help implementing specific functionality in your codebase.
+- **Bug investigation**: Identify and fix issues more efficiently with guided troubleshooting.
+- **Development setup**: Configure development environments and toolchains.
+- **Learning new technologies**: Get explanations and examples for frameworks or languages you're learning.
+
+The Codespace Assistant is designed to be a responsive partner in your development process, adapting to your needs and helping you work more efficiently in your coding environment.

assistants/codespace-assistant/assistant/text_includes/context_transfer_assistant_info.md

@@ -0,0 +1,71 @@
+# Context Transfer Assistant
+
+## Overview
+
+The Context Transfer Assistant specializes in capturing, organizing, and sharing knowledge between users. It helps document and transfer complex information about any subject matter, making it easier to onboard team members, share expertise, or provide detailed guidance across various domains.
+
+## Key Features
+
+- **Knowledge capture and organization**: Records and structures detailed information about any topic or subject area.
+- **Contextual understanding**: Analyzes shared files, documents, and conversations to build comprehensive knowledge representation.
+- **Guided context sharing**: Helps structure information to make it accessible and actionable for recipients.
+- **Domain-aware explanations**: Provides explanations grounded in the specific context being discussed.
+- **Interactive guidance**: Adapts explanations based on the recipient's questions and expertise level.
+- **Visual representation**: Creates diagrams and visual aids to explain complex concepts when helpful.
+- **Knowledge persistence**: Maintains shared knowledge through a centralized whiteboard that all participants can access, ensuring consistent information across team conversations.
+
+## How to Use the Context Transfer Assistant
+
+### For Context Owners (Sharers)
+
+1. **Start by defining the context**: Explain what information you want to share and who will be using it.
+2. **Share relevant artifacts**: Upload or reference key documents, files, or resources.
+3. **Provide structural overview**: Describe the system, domain, or topic structure and key components.
+4. **Define processes**: Explain important workflows, procedures, or methodologies.
+5. **Refine knowledge representation**: Answer the assistant's questions to clarify details.
+
+### For Context Recipients
+
+1. **Review shared context**: Explore the information that has been shared with you.
+2. **Ask clarifying questions**: Request more details about specific aspects of the topic or materials.
+3. **Request practical examples**: Ask for concrete examples of concepts or procedures.
+4. **Apply knowledge assistance**: Get help applying the shared knowledge to specific tasks.
+5. **Seek procedural guidance**: Get step-by-step instructions for workflows or processes.
+
+## Knowledge Transfer Process
+
+1. **Context Definition**:
+
+   - Define the domain or subject matter to be shared
+   - Establish the recipient's background and expertise level
+   - Determine the goals of the knowledge transfer
+
+2. **Knowledge Capture**:
+
+   - Share relevant documents and resources
+   - Provide structural and organizational descriptions
+   - Explain key concepts and relationships
+   - Document important processes and procedures
+
+3. **Context Organization**:
+
+   - The assistant structures the information for clarity
+   - Complex concepts are broken down into digestible components
+   - Visual diagrams may be created for conceptual understanding
+   - Information is organized within the conversation history for reference
+
+4. **Interactive Knowledge Sharing**:
+   - Recipients explore the shared context
+   - The assistant answers questions based on the captured knowledge
+   - Explanations are adapted to the recipient's understanding
+   - Additional context is gathered when knowledge gaps are identified
+
+## Common Use Cases
+
+- **Team member onboarding**: Transfer comprehensive knowledge to new members.
+- **Knowledge handover**: Document complex systems or processes when transitioning between teams.
+- **Expert consultation**: Preserve and share the knowledge of subject matter experts.
+- **Cross-team collaboration**: Share context between teams working on different aspects of a project.
+- **Process documentation**: Guide others through setting up or following specific procedures.
+
+The Context Transfer Assistant bridges the gap between experts and knowledge recipients, making complex information more accessible, organized, and actionable across teams and individuals.

assistants/document-assistant/assistant/chat.py

@@ -11,7 +11,7 @@
 from typing import Any
 
 import deepmerge
-from assistant_extensions import dashboard_card
+from assistant_extensions import dashboard_card, navigator
 from assistant_extensions.mcp import MCPServerConfig
 from content_safety.evaluators import CombinedContentSafetyEvaluator
 from semantic_workbench_api_model.workbench_model import (
@@ -90,6 +90,11 @@ async def content_evaluator_factory(context: ConversationContext) -> ContentSafe
                 ),
             )
         ),
+        **navigator.metadata_for_assistant_navigator({
+            "default": (pathlib.Path(__file__).parent / "text_includes" / "document_assistant_info.md").read_text(
+                "utf-8"
+            ),
+        }),
     },
 )
 

assistants/document-assistant/assistant/text_includes/document_assistant_info.md

@@ -0,0 +1,61 @@
+# Document Assistant
+
+## Overview
+
+The Document Assistant is an AI assistant focused on document creation and editing within the Semantic Workbench. It provides a seamless environment for creating, editing, and managing Markdown documents with side-by-side editing capabilities, guided assistance, and integration with external tools.
+
+## Key Features
+
+- **Side-by-side document editing**: Work on your documents with a split view showing both the editor and conversation, enabling real-time collaboration and feedback.
+- **Document management**: Create, view, and edit multiple Markdown documents within the same workspace.
+- **Generated UI elements**: Get visual guidance through dynamically generated UI components that help organize your document workflow.
+- **Autonomous tool execution**: The assistant can perform document-related tasks on your behalf, freeing you to focus on content creation.
+- **MCP server integration**: Connects with Model Context Protocol (MCP) servers for extended functionality, particularly the filesystem and filesystem-edit servers.
+- **Local-only Office integration**: Optional integration with Microsoft Office applications through MCP (when enabled).
+
+## How to Use the Document Assistant
+
+### Getting Started
+
+1. **Create a new conversation** in the Semantic Workbench and add the Document Assistant.
+2. **Create a new document** by asking the assistant to create one for you. Example: "Create a new document about project requirements."
+3. **Edit existing documents** by mentioning the document you want to work on. The document will appear in the side panel editor.
+
+### Document Management
+
+- **Switch between documents**: Use the Documents tab in the inspector panel to see all available documents and switch between them.
+- **Edit document content**: Make changes directly in the document editor panel, or ask the assistant to make specific edits for you.
+- **Upload files**: Upload Markdown files to add them to your workspace, making them available for editing.
+
+### Advanced Features
+
+- **Format documents**: Ask the assistant to format your document, create sections, add lists, tables, or other Markdown elements.
+- **Collaborative editing**: The document locking mechanism ensures that only one editing operation happens at a time, preventing conflicts.
+- **Document transformations**: Request content transformations like summarization, expansion, or style changes.
+
+## Integration with Other Tools
+
+When configured, the Document Assistant can work with:
+
+- **MCP filesystem server**: For reading and writing files in the workspace.
+- **MCP filesystem-edit server**: For advanced document editing capabilities.
+- **Office integration**: When enabled, allows working with Microsoft Office documents.
+- **Additional MCP servers**: Can be enabled for search, research, and other extended features.
+
+## Tips for Effective Use
+
+1. **Be specific in your requests**: Clearly state what changes you want to make to documents.
+2. **Use the document editor for quick edits**: Make direct changes in the editor for smaller modifications.
+3. **Ask the assistant for complex transformations**: Let the AI handle more complex document restructuring or content generation.
+4. **Switch between documents as needed**: Use the Documents tab to manage multiple files in your workspace.
+5. **Save often**: While documents are automatically saved, it's a good practice to confirm important changes.
+
+## Common Use Cases
+
+- Creating technical documentation and reports
+- Drafting and editing business documents
+- Organizing research notes and findings
+- Creating structured content like tutorials or guides
+- Collaborative document editing and review
+
+The Document Assistant is designed to be intuitive and helpful for all users, making document creation and editing a more efficient and guided experience.

assistants/navigator-assistant/.env.example

@@ -0,0 +1,11 @@
+# Description: Example of .env file
+# Usage: Copy this file to .env and set the values
+
+# NOTE:
+# - Environment variables in the host environment will take precedence over values in this file.
+# - When running with VS Code, you must 'stop' and 'start' the process for changes to take effect.
+#   It is not enough to just use the VS Code 'restart' button
+
+# Assistant Service
+ASSISTANT__AZURE_OPENAI_ENDPOINT=https://<YOUR-RESOURCE-NAME>.openai.azure.com/
+ASSISTANT__AZURE_CONTENT_SAFETY_ENDPOINT=https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/

assistants/navigator-assistant/.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "debugpy",
+      "request": "launch",
+      "name": "assistants: navigator-assistant",
+      "cwd": "${workspaceFolder}",
+      "module": "semantic_workbench_assistant.start",
+      "consoleTitle": "${workspaceFolderBasename}",
+      "justMyCode": false // Set to false to debug external libraries
+    }
+  ]
+}