Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some Sidekick quickstart edits. #281

Closed
wants to merge 2 commits into from
Closed

Some Sidekick quickstart edits. #281

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1407b9b
Some edits on the quickstart.
Sep 13, 2023
d22526f
Update packages/docs/docs/sidekicks-quickstart.md
benlower Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 102 additions & 114 deletions packages/docs/docs/sidekicks-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,17 @@ import Step3Profit from '../static/img/step-3-profit.png'

# Quickstart: Fixie Sidekicks

This is a quickstart guide to building and deploying a Fixie Sidekick. A sidekick is an embeddable, conversational
assistant built using AI.JSX. Sidekicks harness the power of [DocsQA](/docsQA), [Tools](/tools), and [GenUI](/genUI) and bring everything together in a seamless experience.
One of the best use cases for AI.JSX is to build a **Sidekick**, an AI-powered chatbot that is embedded in a web page or app and is able to answer questions, call APIs,
and more. AI.JSX makes it easy to build Sidekicks with a rich UI, access to
documents, and the ability to fetch live data and take action via API calls.

_(TODO -> Matt, I'm thinking we might want to remove this last sentence since those pages are not yet built out. Or we can populate them with content.)_
Sidekicks can be built and deployed in minutes. This quickstart will walk you through
the entire process of building and deploying your own Sidekick.

This tutorial relies on both AI.JSX as well as the [Fixie](https://fixie.ai) cloud
platform, which provides a suite of APIs and tools for hosting and managing
Sidekicks. It is possible to build and deploy Sidekicks without Fixie, but
using Fixie makes the process much easier.

:::info What You Will Do
At the end of this quickstart you will:
benlower marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -27,212 +34,193 @@ At the end of this quickstart you will:

:::warning Prerequisites
Before you get started, you will need to have a free Fixie developer account and have some tools installed on your machine. You will also need a text editor. If you don't have a preferred text editor, we recommend [Visual Studio Code](https://code.visualstudio.com/).

If you don't want to fuss with installing things on your machine, you can sign-up for a free DevZero account and use the pre-configured template for Fixie Sidekicks.
:::

:::tip On Windows? Use WSL.
If you are using a Windows machine, we highly recommend using the Windows Subsystem for Linux (WSL) for development with Node.js. This is optional. If you want to use WSL, follow [this guide](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl) which will get you set-up with WSL, Node, and VSCode (for your text editor).
:::

### a) Sign-up for Fixie
### a) Get a Fixie developer account

We will use [Fixie](https://fixie.ai) for hosting our Sidekick. Sign-up for a free Fixie developer account:
We will use [Fixie](https://fixie.ai) for hosting and managing our Sidekick.
Sign up for a free Fixie developer account:

1. Go to the [Fixie sign-up page](https://console.fixie.ai).
1. Go to the [Fixie console page](https://console.fixie.ai).
1. Create an account using either a Google or GitHub account.
1. Navigate to your [profile page](https://console.fixie.ai/profile).

<img src={FixieProfileAPIKey} alt="Fixie profile page where you can get your API key." width="600"/>

Keep this page open as we will come back to this in Step 2 to grab our API key which is required for deployment.
The Fixie Console is where you will test and manage your Sidekick once it's built.
For now, the main thing you need is your Fixie API Key, which is found on your
[profile page](https://console.fixie.ai/profile).

### b) Install Node.js

Install the current [LTS version of Node.js](https://nodejs.org/en).
Sidekicks are based on AI.JSX, which in turn relies on Node.js, a JavaScript
runtime. Install the current [LTS version of Node.js](https://nodejs.org/en).

### c) Install the Fixie CLI

In your terminal execute the following:
The Fixie command-line interface is provided by the [fixie](https://www.npmjs.com/package/fixie) package in npm. Install it by running:

```terminal
npm install -g @fixieai/fixie@latest
$ npm install -g fixie@latest
benlower marked this conversation as resolved.
Show resolved Hide resolved
```

_TODO: Matt, should this be install and configure CLI? i.e. should we include auth/API key here?_

## Step 1: Get Template Code
This will install the `fixie` binary.

We are going to start with some demo code.

- In your terminal navigate to a folder where you want to save the template code. For example, someplace like `Documents\GitHub\` or just `Documents\`.
- Enter the following command. This will clone the template code into a directory named `fixie-sidekick-template` in the current folder.
### d) Authenticate the Fixie CLI

To configure the Fixie CLI to login to the Fixie service, just run:

```terminal
git clone https://github.com/fixie-ai/fixie-sidekick-template.git
$ fixie auth
```

If this command fails you may need to [install Git](https://github.com/fixie-ai/fixie-sidekick-template.git).

You can also download the code directly from [the source](https://github.com/fixie-ai/fixie-sidekick-template). While you're there, give us a star! 🦊

## Step 2: Deploy Sidekick

OK. Set-up is out of the way. Now is when we really start moving!

### a) Open Project in VS Code
This will open a browser tab to authenticate to the Fixie console. The Fixie
CLI should now be configured to work with your Fixie account.

Open Visual Studio Code (or your favorite text editor). Open the folder where you saved the template code (e.g. `Documents\GitHub\fixie-sidekick-template`)
## Step 1: Clone the Sidekick template repository

### b) Populate Fixie API Key
Now that we have the prerequisites out of the way, let's download and deploy
the Fixie Sidekick template.

Go back to the web page we left open above when signing up for a Fixie account. If you can't find it, it's [here](https://console.fixie.ai/profile).
Clone the `fixie-sidekick-template` repository from GitHub:

<img src={FixieProfileAPIKey} alt="Fixie profile page where you can get your API key." width="600"/>

- Click on the clipboard icon (the one on the far right of the API token) to copy your API key.
- The key looks something like `FmEEMtjcHLfNGPrLhRQwQfwG9Li...` and is 175 characters long.
- Back in your text editor, open the file named `.env`. Add your key:

```javascript
FIXIE_API_KEY = YOUR_KEY_HERE;
```terminal
git clone https://github.com/fixie-ai/fixie-sidekick-template.git
```

This should look something like this:

```javascript
FIXIE_API_KEY=FmEEMtjcHLfNGPrLhRQwQfwG9Li...[continues]
```
If this command fails you may need to [install Git](https://github.com/fixie-ai/fixie-sidekick-template.git).

_TODO: Matt: right now the .env file is in the .gitignore which means they would have to create it. thoughts on the best route here? don't want to set ppl up to accidentally commit secrets._
You can also download the code directly from [the source](https://github.com/fixie-ai/fixie-sidekick-template). While you're there, give us a star! 🦊

### c) Deploy Sidekick to Fixie
## Step 2: Build the Sidekick code

The moment of truth has arrived! Let's deploy our sidekick to Fixie!
> TODO(matt): We need to set up a public Corpus ID that the template Sidekick can
> use out of the box without the user having to create one. I am prioritizing this!
benlower marked this conversation as resolved.
Show resolved Hide resolved

#### Deploying for Development (`fixie serve`)
The Sidekick is implement in TypeScript with AI.JSX, so you need to
benlower marked this conversation as resolved.
Show resolved Hide resolved
build it before it can be deployed. To do this, in the `fixie-sidekick-template`
directory, run:

```terminal
$ npm install
$ npm run build
```
The resulting JavaScript code should now be in the `dist/` subdirectory.

When developing or updating a Sidekick, we most likely will be making many changes and testing things as we go. In this case, we want
to deploy things as quickly as possible.
## Step 3: Deploy the Sidekick

From the directory where you have your sidekick code, execute the following in your terminal:
In the `fixie-sidekick-template` directory, simply run:

```terminal
npx @fixieai/fixie@latest serve
$ fixie deploy
benlower marked this conversation as resolved.
Show resolved Hide resolved
```

This uses the latest version of the fixie CLI and serves everything from your machine. For example, if our Fixie user is "sarah" and she is deploying a sidekick named "sidekick-acme", then we would expect to see something like this:
This will deploy the Sidekick to the Fixie cloud service. It takes a couple of
minutes, but once the process is done, you will see a link to the Sidekick's
page on the Fixie Console. For example:

```terminal
sarah@computer sidekick-acme % npx @fixieai/fixie@latest serve
🦊 Serving agent sarah/sidekick-acme...
🌱 Starting local agent process on port 8181...
🌱 Running: npx --package=@fixieai/sdk fixie-serve-bin --packagePath ./dist/index.js --port 8181
🌱 Agent stdout: AI.JSX agent listening on http://0.0.0.0:8181.

🦊 Creating new agent sarah/sidekick-acme...
🚇 Starting tunnel process...
🥡 Serving agent at https://3fa8367c27e1337.lhr.life
🥡 Revision a1a29ee1 was deployed to https://console.fixie.ai/agents/sarah/sidekick-acme
❯ fixie deploy
🦊 Deploying agent mdw/fixie-sidekick-template...
🦊 Creating new agent mdw/fixie-sidekick-template...
⠋ 🚀 Deploying... (hang tight, this takes a minute or two!)
✔ Agent fixie-sidekick-template is running at: https://console.fixie.ai/agents/mdw/fixie-sidekick-template
```

As we make changes to our sidekick, we can simply stop serving our sidekick with `Control+C` and then serve up our new changes with the `serve` command as we did above.
<img src={Step3Profit} alt="Step 3: Profit." width="300"/>
benlower marked this conversation as resolved.
Show resolved Hide resolved

_TODO Matt: i think we need something here about serve vs. deploy and when to do each, considerations, etc._
## Step 4: Try it out!

#### Deploying to Production (`fixie deploy`)
Surf on over to the Sidekick URL shown by the `fixie deploy` command. You should
now be able to chat directly with your Sidekick!

Once we are done with our development, we can deploy the Sidekick to Fixie with the `deploy` command.
> TODO: Add more information about the kinds of queries you can ask of the template
> Sidekick based on whatever the public corpus ends up being.

From your terminal:
## Local Development and Testing

```terminal
npx @fixieai/fixie deploy
```
The `fixie deploy` step can take a couple of minutes to build and deploy your
Sidekick to the cloud, which is a real bummer when you're testing things locally.
Fortunately, you can run your Sidekick locally, without needing to deploy it to
the cloud.

Deploying takes up to a couple of minutes. While deployment is running you will see status messages in your terminal. For example, if our Fixie user is "sarah" and she is deploying a sidekick named "sidekick-acme", then we would expect to see something like this:
Instead of `fixie deploy`, you run:

```terminal
sarah@computer % FIXIE_API_URL='https://console.fixie.ai' npx @fixieai/fixie deploy
🦊 Deploying agent sarah/sidekick-acme...
👽 Updating agent sarah/sidekick-acme...
$ fixie serve
```

Once complete deployment completes, we would expect to see something like this:
This starts up the Sidekick running on your local machine, and sets
up a tunnel allowing the Fixie service to connect into your local
Sidekick. When you quit the `fixie serve` command (for example, by
hitting Ctrl-C), the Sidekick reverts back to the most recently
benlower marked this conversation as resolved.
Show resolved Hide resolved
deployed version (from `fixie deploy`). Note that you need to `fixie
deploy` your Sidekick in order for it to run in the cloud.

```terminal
sarah@computer % FIXIE_API_URL='https://console.fixie.ai' npx @fixieai/fixie deploy
🦊 Deploying agent sarah/sidekick-acme...
👽 Updating agent sarah/sidekick-acme...
✔ Revision a9b5e04c was deployed to https://console.fixie.ai/agents/sarah/sidekick-acme
```

#### Troubleshooting: Verify the Sidekick Builds

If the above deploy step failed for some reason, it is a good idea to build our sidekick locally to see if there are any errors raised. Building is done from the terminal:

```terminal
npm build
```

_TODO Matt: Is this still needed?_
As we make changes to our sidekick, we can simply stop serving our sidekick with `Control+C` and then serve up our new changes with the `serve` command as we did above.
benlower marked this conversation as resolved.
Show resolved Hide resolved

## Step 3: Converse with Sidekick

<img src={Step3Profit} alt="Fixie profile page where you can get your API key." width="300"/>
## Sending messages to your Sidekick

We've got our Sidekick deployed. Let's test it out to see what it can do!
The Fixie Console page gives you a simple web interface to interact with your
Sidekick, but you're not limited to this interface. You can chat with your
Sidekick directly via a REST API, or embed the Sidekick chat UI in your own
web app.

We are going to test the sidekick using four different methods.
### Method 1: Via the REST API

### Method 1: Via curl
> TODO(matt): Figure out the right invocation for this.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://github.com/fixie-ai/fixie/blob/5452e48b739f9941e3facabaad9a2f1d4f59f49c/src/generic-sidekick-frontend/lib/fixie-api.ts for an example of how this API is used.


First up, let's ask our Sidekick a question using curl. From your terminal:
First up, let's ask our Sidekick a question through the Fixie REST API, using
`curl`. From your terminal:

```bash
curl 'https://console.fixie.ai/api/agents/<your user name>/<your sidekick name>' \
-d '{ "message": {"text": "What can you do?" }}' \
-H 'Authorization: Bearer <your Fixie API key>' \
-H 'Content-Type: application/json'
```

-- For example:
For example:

curl 'https://console.fixie.ai/api/agents/sarah/sidekick-acme' \
```bash
curl 'https://console.fixie.ai/api/agents/sarah/fixie-sidekick-template' \
-d '{ "message": {"text": "What can you do?" }}' \
-H 'Authorization: Bearer FmEEMtjcHLfNGPrLhRQwQfwG9Li...' \
-H 'Content-Type: application/json'
```

_TODO Matt: this is currently broken. not sure what the plan is to fix._

This should display something like this:

TODO

### Method 2: Via the Fixie Dashboard
### Method 2: Via the Fixie Console

- In your browser navigate to the [Fixie dashboard](https://console.fixie.ai/).
benlower marked this conversation as resolved.
Show resolved Hide resolved
- Click on your agent.
- Enter a question for the sidekick. e.g. "What can you do?"
- Click on your Sidekick.
- Enter a question for the Sidekick. e.g. "What can you do?"

Note: you can also access your agent directly at:
You can also access your agent directly at:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section feels redundant. I don't think we need to both provide a direct link to the dev console, and also tell people how to go to the front door of the dev console and then click through it.


```terminal
https://console.fixie.ai/agents/<your user name>/<your sidekick name>
```

### Method 3: Via Embedding in Another Web App

TODO could we just include a simple web page in the template code that can be served up locally?

_TODO Matt: need to figure out if we add this or not_
> TODO(matt): Figure out what the right thing to do here is.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would punt on this for now

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok removing the part about embedding for now. opened issue #284 to track the work for doing this in future.


<img src={FoxieSidekick} alt="Foxie, the Fixie mascot, doing a sidekick!" width="400"/>

## Additional Resources and Next Steps

You've got a template Sidekick deployed to Fixie. So what's next? Here are some suggestions:

> TODO(ben/matt): We should figure out if we have time to write more complete
benlower marked this conversation as resolved.
Show resolved Hide resolved
> documentation on creating Corpora, using tools, etc. or just want to tell
> people how to do it live. At minimum, we should explain the concept of Corpora
> and that you need to feed a Corpus ID into your Sidekick's code.

### Create your own Document Collection

This will enable you to provide your Sidekick with specialized knowledge about your company, product, or organization. Create your own collection [here](https://console.fixie.ai/documents).
Expand Down