Skip to content

Latest commit

 

History

History
66 lines (45 loc) · 4.7 KB

ASSISTANT_DEVELOPMENT_GUIDE.md

File metadata and controls

66 lines (45 loc) · 4.7 KB
Raw

Semantic Workbench Assistant Development Guide

Overview

For assistants to be instantiated in Semantic Workbench, you need to implement an assistant service that the workbench can talk with via http.

We provide several python base classes to make this easier: semantic-workbench-assistant

Example assistant services:

Top level concepts

RECOMMENDED FOR PYTHON: Use the semantic-workbench-assistant classes to create your assistant service. These classes provide a lot of the boilerplate code for you.

See the semantic-workbench-assistant.assistant_app.AssistantApp for the classes and the Python python-01-echo-bot for an example of how to use them.

assistant_service.FastAPIAssistantService

Your main job is to implement a service that supports all the Semantic Workbench methods. The Canonical assistant example demonstrates a minimal implementation.

It implements an assistant service that inherits from FastAPIAssistantService:

class CanonicalAssistant(assistant_service.FastAPIAssistantService):

This service is now a FastAPIAssistantService containing all the assistant methods that can be overridden as desired.

Assistant service development: general steps

  • Create a fork of this repository by clicking the "Fork" button at the top right of the repository page
  • Set up your dev environment
  • Create a directory for your projects. If you create this in the repo root, any assistant example projects will already have the correct relative paths set up to access the semantic-workbench-* packages or libraries.
  • Create a project for your new assistant in your projects directory, e.g. /<your_projects>/<your_assistant_name>
  • Getting started with the assistant service
    • Copy skeleton of an existing project: e.g. one of the projects from the examples directory
      • Alternatively, consider using the canonical assistant as a starting point if you want to implement a new custom base
    • Follow the README.md in the example project to get started
    • If the project has a .env.example file, copy it to .env and update the values as needed
  • Build and Launch assistant. Run workbench service. Run workbench app. Add assistant local url to workbench via UI.
  • NOTE: See additional documentation in /workbench-app/docs regarding app features that can be used in the assistant service.

Assistant service deployment

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.

If you want to deploy your assistant service to a public endpoint, you will need to create your own Azure app registration and update the app and service files with the new app registration details. See the Custom app registration guide for more information.

Deployment steps

TODO: Add more detailed steps, this is a high-level overview

  • Create a new Azure app registration
  • Update your app and service files with the new app registration details
  • Deploy your service to an endpoint accessible by your web browser
  • Update the workbench app with the new service URL
  • Deploy your assistant service to an endpoint that the workbench service can access
    • Suggested: limit access to the assistant service to only the workbench service using a private network or other security measures
  • Deploy the workbench app to an endpoint that users can access
    • Suggested: limit access to the workbench app to only trusted users