Skip to content

Commit

Permalink
[repo] docs: revamp getting started docs (#1127)
Browse files Browse the repository at this point in the history 
## Linked issues

closes: #733 #1126 #732  (issue number)

Adding: @corinagum, @Carter425 as contributors since I rephrased and
relocated docs written by them.

## Details

**Added the following sections**
- Overview - Introduction to the getting started docs
- Quickstart - Step by step instructions to get the echo bot set up.
- Samples - Overview of all the samples in the sdk and supported
language.
- Migration (Overview, JS, C#) - How to migrate a BF SDK app to Teams AI
app.

**Tweaked the following sections**
- C#, JS package readme's migration section has been merged into the
getting started docs
- Samples folder readme now points to the getting started docs "sample"
section.

**Removed the following sections from the existing getting started
docs**
- dotnet/*
- js/*
- 00.PROMPTs - 05.TURNS
- README.md (replaced by 00.OVERVIEW.md)

## Attestation Checklist

- [x] My code follows the style guidelines of this project

- I have checked for/fixed spelling, linting, and other errors
- I have commented my code for clarity
- I have made corresponding changes to the documentation (we use
[TypeDoc](https://typedoc.org/) to document our code)
- My changes generate no new warnings
- I have added tests that validates my changes, and provides sufficient
test coverage. I have tested with:
  - Local testing
  - E2E testing in Teams
- New and existing unit tests pass locally with my changes
  • Loading branch information
@singhk97
singhk97 authored Jan 8, 2024
1 parent c30ce61 commit fc320ea
Show file tree
Hide file tree
Showing 50 changed files with 1,246 additions and 4,276 deletions.
154 changes: 5 additions & 149 deletions dotnet/packages/Microsoft.TeamsAI/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,157 +7,13 @@ This SDK is specifically designed to assist you in creating bots capable of inte
Requirements:

* [.NET 6.0 SDK](https://dotnet.microsoft.com/download/dotnet/6.0)
* [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) resource or an account with [OpenAI](https://platform.openai.com/)
* (Optional) [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) resource or an account with [OpenAI](https://platform.openai.com/)

## Getting Started: Migration vs New Project

If you're migrating an existing project, switching to add on the Teams AI Library layer is quick and simple. For a more-detailed walkthrough, see the [migration guide](https://github.com/microsoft/teams-ai/blob/main/getting-started/dotnet/00.MIGRATION.md). The basics are listed below.
## Getting Started

### Migration
### *IMPORTANT Migration code & steps below needs to be updated for C#

In your existing Teams bot, you'll need to add the Teams AI Library SDK package and import it into your bot code.

```bash
dotnet add package Microsoft.TeamsAI
```

Replace `BotActivityHandler` and `ApplicationTurnState` in your bot. Note that here, `TurnState` is constructed to include `ConversationState`, but can also have `UserState` and `TempState`.

`State.cs`:

```c#
namespace Application {
public class ApplicationTurnState : TurnState
{
public ApplicationTurnState()
{
ScopeDefaults[CONVERSATION_SCOPE] = new ConversationState();
}

public new ConversationState Conversation
{
get
{
TurnStateEntry? scope = GetScope(CONVERSATION_SCOPE);

if (scope == null)
{
throw new ArgumentException("TurnState hasn't been loaded. Call LoadStateAsync() first.");
}

return (ConversationState)scope.Value!;
}
set
{
TurnStateEntry? scope = GetScope(CONVERSATION_SCOPE);

if (scope == null)
{
throw new ArgumentException("TurnState hasn't been loaded. Call LoadStateAsync() first.");
}

scope.Replace(value!);
}
}
}

public class ConversationState : Record
{
public int Count
{
get => Get<int>("count");
set => Set("count", value);
}
}
}
```

`Program.cs`

```c#
using Application;

...

Application<ApplicationTurnState> app = new(new())
{
Storage = new MemoryStorage()
};
```

The rest of the code stays the same.

That's it!

Run your bot (with ngrok) and sideload your manifest to test.

For migrating specific features such as Message Extension and Adaptive Card capabilities, please see the [Migration Guide](https://github.com/microsoft/teams-ai/blob/main/getting-started/dotnet/00.MIGRATION.md).

### New Project

If you are starting a new project, you can use the [Teams AI Library SDK echobot sample](https://github.com/microsoft/teams-ai/tree/main/dotnet/samples/01.messaging.echoBot) as a starting point. You don't need to make any changes to the sample to get it running, but you can use it as your base setup. Echo Bot supports the Teams AI Library SDK out of the box.

You can either copy-paste the code into your own project, or clone the repo and run the Teams Toolkit features to explore.

### Optional ApplicationBuilder Class

You may also use the `ApplicationBuilder` class to instantiate your `Application` instance. This option provides greater readability and separates the management of the various configuration options (e.g., storage, turn state, AI module options, etc).

`Program.cs`:

```c#
// Old method:
// Application<ApplicationTurnState> app = new()
// {
// storage
// };
var app = new ApplicationBuilder<ApplicationTurnState>()
.WithStorage(storage)
.Build(); // this function internally calls the Application constructor
```

## AI Setup

The detailed steps for setting up your bot to use AI are in the [AI Setup Guide](https://github.com/microsoft/teams-ai/blob/main/getting-started/dotnet/01.AI-SETUP.md).

On top of your Microsoft App Id and password, you will need an OpenAI API key or an Azure OpenAI key and endpoint. You can get one from the [OpenAI platform](https://platform.openai.com/) or from [Azure OpenAI Service](https://azure.microsoft.com/en-us/products/ai-services/openai-service). Once you have your key, add it to `appsettings.Development.json` or `appsettings.json`.

### AI Prompt Manager
### *IMPORTANT AI Prompt Manager code needs to be updated to C#

```c#
PromptManager prompts = new(new()
{
PromptFolder = "./Prompts"
});

ActionPlanner<ApplicationTurnState> planner = new(
options: new(
model: sp.GetService<OpenAIModel>()!,
prompts: prompts,
defaultPrompt: async (context, state, planner) =>
{
PromptTemplate template = prompts.GetPrompt("default");
return await Task.FromResult(template);
}
)
{ LogRepairs = true }
);

// Define storage and application
// - Note that we're not passing a prompt for our AI options as we won't be chatting with the app.
MemoryStorage storage = new();
Application<ApplicationTurnState> app = new()
{
Storage = storage,
AI: new(planner)
};
```

For more information on how to create and use prompts, see [PROMPTS](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/teams%20conversational%20ai/how-conversation-ai-get-started?tabs=javascript4%2Cjavascript1%2Cjavascript3%2Cjavascript2#:~:text=VectraDataSource%20and%20OpenAIEmbeddings%3A-,Prompt,-Prompts%20are%20pieces) and look at the [samples](https://github.com/microsoft/teams-ai/tree/main/dotnet/samples) numbered `04._.xxx`.

Happy coding!
To get started, take a look at the [getting started docs](https://github.com/microsoft/teams-ai/blob/main/getting-started/README.md).

## Migration

If you're migrating an existing project, switching to add on the Teams AI Library layer is quick and simple. See the [migration guide](https://github.com/microsoft/teams-ai/blob/main/getting-started/MIGRATION/DOTNET.md).
62 changes: 2 additions & 60 deletions dotnet/samples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ There are a few ways to get the application up and running. The latest way is us
#### Steps

1. Open the solution in Visual Studio. (For example `EchoBot.sln`).
- Ensure that you set the appropriate config values (ex Azure OpenAI API key). You can find specific instructions in the sample readme under the `Set up instructions` section. If you can't find this section, then it means that the bot does not need them.
- Ensure that you set the appropriate config values (ex Azure OpenAI API key). You can find specific instructions in the sample readme under the `Set up instructions` section. If you can't find this section, then it means there is no required config values to set.
2. In the debug dropdown menu, select `Dev Tunnels > Create A Tunnel` (Tunnel type: `Persistent` & Access: `Public`) or select an existing public dev tunnel.

![image](https://github.com/microsoft/teams-ai/assets/115390646/d7246d38-8276-4b2a-bc22-b72f36aa41b9)
Expand Down Expand Up @@ -96,65 +96,7 @@ There are a few ways to get the application up and running. The latest way is us
## List of Samples
Follow the above instructions to run the C# .NET samples. Here's a list of the samples:

### Basic Conversational Experience

#### [Echo Bot](/dotnet/samples/01.echoBot/)

A conversational bot that listens for specific commands and offers a simple conversational flow: echoing the user's message back to them.
This sample illustrates basic conversational bot behavior in Microsoft Teams and shows the Teams AI SDK's ability to scaffold conversational bot components.

#### [Search Command](/dotnet/samples/02.messageExtensions.a.searchCommand/)

A Message Extension (ME) built to search NuGet for a specific package and return the result as an Adaptive Card.

This sample illustrates the Teams AI SDK's ability to scaffold search-based Message Extensions and return Adaptive Card components.
#### [Type Ahead Bot](/dotnet/samples/03.adaptiveCards.a.typeAheadBot/)
A conversational bot that uses dynamic search to generate Adaptive Cards in Microsoft Teams.
This sample illustrates the Teams AI SDK's ability to scaffold conversational bot and Adaptive Card components.

### AI-Powered Experiences

#### [Chef Bot](/dotnet/samples/04.ai.a.teamsChefBot/)

A conversational bot for Microsoft Teams, designed as a helper bot for building Teams app. The bot uses the text-davinci-003 model to chat with Teams users and respond in a polite and respectful manner, staying within the scope of the conversation.

This sample illustrates basic conversational bot behavior in Microsoft Teams. The bot is built to allow GPT to facilitate the conversation on its behalf, using only a natural language prompt file to guide it.

#### [GPT ME](/dotnet/samples/04.ai.b.messageExtensions.gptME/)

A Message Extension (ME) for Microsoft Teams that leverages the text-davinci-003 model to help users generate and update posts. The extension is designed to assist users in creating posts that are appropriate for a business environment.

This sample illustrates basic ME behavior in Microsoft Teams. The ME is built to allow GPT to facilitate the conversation by generating posts based on what the user requires. e.g., "Make my post sound more professional."

#### [Light Bot](/dotnet/samples/04.ai.c.actionMapping.lightBot/)

A conversational bot for Microsoft Teams, designed as an AI assistant. The bot connects to a third-party service to turn a light on or off.

This sample illustrates more complex conversational bot behavior in Microsoft Teams. The bot is built to allow GPT to facilitate the conversation on its behalf as well as manually defined responses, and maps user intents to user defined actions.

#### [List Generator AI Assistant](/dotnet/samples/04.ai.d.chainedActions.listBot/)

Similar to the Light On/Off sample, this is a conversational bot for Microsoft Teams, designed as an AI assistant. This bot showcases how to map intents to actions, but instead of returning text, it generates dynamically created Adaptive Cards as a response.

This sample illustrates complex conversational bot behavior in Microsoft Teams and showcases the richness of possibilities for responses.

#### [DevOps AI Assistant](/dotnet/samples/04.ai.e.chainedActions.devOpsBot/)

Similar to the List Generator AI Assistant sample, this is a conversational bot for Microsoft Teams, designed as an AI assistant. This bot showcases how to map intents to actions, but instead of returning text, it generates dynamically created Adaptive Cards as a response.

This sample illustrates complex conversational bot behavior in Microsoft Teams and showcases the richness of possibilities for responses.

#### [Twenty Questions](/dotnet/samples/04.e.twentyQuestions/)

A conversational bot for Microsoft Teams, designed as an AI assistant of the Ultimate Guessing Game!

This sample showcases the incredible capabilities of language models and the concept of user intent. Challenge your skills as the human player and try to guess a secret within 20 questions, while the AI-powered bot answers your queries about the secret.
You can find the list of samples in the [getting started docs](../../getting-started/SAMPLES.md).
## Miscellanous Resources
Expand Down
Loading

0 comments on commit fc320ea

Please sign in to comment.