• Stars
    star
    173
  • Rank 220,124 (Top 5 %)
  • Language
    Python
  • License
    MIT License
  • Created about 2 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Conversational AI tooling & personas built on Cohere's LLMs
################################################################################
#    ____      _                     ____                  _ _                 #
#   / ___|___ | |__   ___ _ __ ___  / ___|  __ _ _ __   __| | |__   _____  __  #
#  | |   / _ \| '_ \ / _ \ '__/ _ \ \___ \ / _` | '_ \ / _` | '_ \ / _ \ \/ /  #
#  | |__| (_) | | | |  __/ | |  __/  ___) | (_| | | | | (_| | |_) | (_) >  <   #
#   \____\___/|_| |_|\___|_|  \___| |____/ \__,_|_| |_|\__,_|_.__/ \___/_/\_\  #
#                                                                              #
# This project is part of Cohere Sandbox, Cohere's Experimental Open Source    #
# offering. This project provides a library, tooling, or demo making use of    #
# the Cohere Platform. You should expect (self-)documented, high quality code  #
# but be warned that this is EXPERIMENTAL. Therefore, also expect rough edges, #
# non-backwards compatible changes, or potential changes in functionality as   #
# the library, tool, or demo evolves. Please consider referencing a specific   #
# git commit or version if depending upon the project in any mission-critical  #
# code as part of your own projects.                                           #
#                                                                              #
# Please don't hesitate to raise issues or submit pull requests, and thanks    #
# for checking out this project!                                               #
#                                                                              #
################################################################################

Maintainer: Cohere ConvAI Team
Project maintained until at least (YYYY-MM-DD): 2023-03-01

Conversant

tests PyPI License: MIT

Build conversational AI on top of Cohere's large language models

  • ๐Ÿ—ฃ Use large language models quickly with Cohere's API
  • ๐Ÿ˜ƒ Customize personas
  • ๐Ÿ’ Leave management of chat history up to conversant
  • ๐Ÿชจ Ground conversations in your provided facts (soon!)
  • ๐Ÿ Install conversant with pip

conversant is a work-in-progress framework for building customizable dialogue agents (aka chatbots) that can answer questions and converse with users with a variety of different chatbot personas. conversant aims to be modular, flexible and extensible so you can create any kind of chatbots you want!

We provide several custom personas for you, including ๐Ÿง‘โ€๐Ÿ’ผ a client support agent, โŒš๏ธ a watch sales agent, ๐Ÿง‘โ€๐Ÿซ a math teacher, and ๐Ÿง™ a fantasy wizard. Create your own persona with just a description and some example conversations!

Read more about how conversant is part of the Cohere Sandbox on our launch blog post.

Try conversant on our Streamlit demo here! ๐ŸŽ‰

Table of Contents

  1. Installation and Usage
    1. Installation
    2. Streamlit Demo
    3. Running Your Own Streamlit Demo
    4. Creating a Custom Persona
    5. Editing a Persona on the Demo
    6. Usage
  2. How Conversant Works
  3. Documentation
  4. Get Support
  5. Contributing Guidelines
  6. License

Installation and Usage

Installation

conversant is available on PyPI, and is tested on Python 3.8+ and Cohere 2.8.0+.

pip install conversant

Streamlit Demo

Want to see it in action first? You can use conversant on a Streamlit app without installing anything here! ๐ŸŽ‰

Screenshot showing the available personas on the Streamlit demo, with the Fortune Teller persona selected by default.. Screenshot showing an exchange between a Fortune Teller chatbot and a user.

Running Your Own Streamlit Demo

Cohere uses Streamlit to create its demo applications. If youโ€™re new to Streamlit, you can install it here and read more about running Streamlit commands here.

If you would like to modify this Streamlit demo locally, we strongly recommend forking this repository rather than installing it as a library from PyPI.

If you'd like to spin up your own instance of the Streamlit demo, you will first need a COHERE_API_KEY. You can generate one by visiting dashboard.cohere.ai.

Local Streamlit apps

If you plan to run the Streamlit app locally, you can add the key to .streamlit/secrets.toml:

COHERE_API_KEY = "YOUR_API_KEY_HERE"

When running locally, Streamlit will read the secrets.toml file and silently inject these values into the environment variables. Alternatively, you may directly set the API key as an environment variable by running the following command from the command line:

export COHERE_API_KEY = "YOUR_API_KEY_HERE"

Start the Streamlit app from the command line with the following command:

streamlit run conversant/demo/streamlit_example.py

Hosted Streamlit apps

If instead you would like to create a hosted Streamlit app, add your Cohere API key to Streamlit via Secrets Management. Add the following line as a Secret:

COHERE_API_KEY = "YOUR_API_KEY_HERE"

Creating a Custom Persona

Once you have your own instance of the Streamlit app, you can begin experimenting with creating custom personas! Check out the config.json for each persona in conversant/personas directory. You'll need to create a subfolder within this directory that corresponds to your new persona and add a config.json file.

As a note, we strongly recommend forking the sandbox-conversant-lib repository rather than installing it as a library from PyPI. When you create a new persona, use the personas directory in the cloned repository. The directory structure should look like this:

conversant/personas
โ”œโ”€โ”€ fortune-teller
โ”‚   โ””โ”€โ”€ config.json
โ””โ”€โ”€ your-persona-name # new
    โ””โ”€โ”€ config.json

The config file should contain the following:

  • chatbot_config:
    • max_context_examples: The length of the chat history for the chatbot to use in reply.
    • avatar: Optional emoji shortcode or URL to image as the chatbot's avatar. Defaults to ๐Ÿค–.
  • client_config: Parameters for co.generate()
  • chat_prompt_config:
    • preamble: Description of the persona.
    • example_separator: A string that separates each example conversation.
    • headers: A name for the bot and the user.
    • examples: A few conversation examples (few-shot), or empty (zero-shot).

conversant will take care of the rest! As an example, check out fortune-teller/config.json. When you launch the Streamlit app, the new persona will appear in the drop down menu.

Running the app with a subset of custom personas

If you would like to run the app with a subset of custom personas, it's possible to create a new directory that contains only the desired ones. This is analogous to the conversant/personas directory, and needs to have the same structure:

custom-personas
โ”œโ”€โ”€ your-first-persona
โ”‚   โ””โ”€โ”€ config.json
โ””โ”€โ”€ your-second-persona
    โ””โ”€โ”€ config.json

After creating this directory, you'll need to tell the app where to look for it. In the demo Streamlit app (streamlit_example.py), one of the first lines reads CUSTOM_PERSONA_DIRECTORY = None. Change this to specify the desired persona directory, e.g. CUSTOM_PERSONA_DIRECTORY = "/Users/yourname/custom-personas".

If this is unchanged, the app will default to using the directory that contains the conversant demo personas.

Troubleshooting missing personas

If you do not see the new persona in the drop down menu, you may need to specify a custom persona directory. Follow the instructions above to tell the app where to look for the personas.

Editing a Persona on the Demo

You can also edit a persona on the Streamlit app! Screenshot showing the interface for editing a persona on the Streamlit app.

Usage

With conversant, you can create a chatbot powered by Cohere's large language models with just the following code snippet.

import cohere
import conversant

co = cohere.Client("YOUR_API_KEY_HERE")
bot = conversant.PromptChatbot.from_persona("fantasy-wizard", client=co)
print(bot.reply("Hello!"))
>>> "Well met, fair traveller. What bringest thou to mine village?"

You can also define your own persona by passing in your own ChatPrompt.

from conversant.prompts import ChatPrompt

shakespeare_config = {
    "preamble": "Below is a conversation between Shakespeare and a Literature Student.",
    "example_separator": "<CONVERSATION>\n",
    "headers": {
        "user": "Literature Student",
        "bot": "William Shakespeare",
    },
    "examples": [
        [
            {
                "user": "Who are you?",
                "bot": "Mine own nameth is Shakespeare, and I speaketh in riddles.",
            },
        ]
    ],
}
shakespeare_bot = conversant.PromptChatbot(
    client=co, prompt=ChatPrompt.from_dict(shakespeare_config)
)
print(shakespeare_bot.reply("Hello!"))
>>> "Greeteth, and welcome. I am Shakespeare, the great poet, dramatist, and playwright."

How Conversant Works

conversant uses prompt completion to define a chatbot persona with a description and a few examples. The prompt is sent as input to Cohere's co.generate() endpoint for an autoregressive language model to generate text in a few-shot manner from the examples and the current dialogue context.

Each user message and chatbot response is appended to a chat history so that future responses are conditioned on the dialogue context at that point in time.

In the future, we plan to add functionality for a chatbot to be factually grounded using text that is retrieved from a local document cache.

For more information, refer to this section in CONTRIBUTORS.md.

Documentation

Full documentation can be found here.

Get Support

If you have any questions or comments, please file an issue or reach out to us on Discord.

Contributing Guidelines

If you would like to contribute to this project, please read CONTRIBUTORS.md in this repository, and sign the Contributor License Agreement before submitting any pull requests. A link to sign the Cohere CLA will be generated the first time you make a pull request to a Cohere repository.

In addition to guidelines around submitting code to this repository, CONTRIBUTORS.md contains a walkthrough to help developers get started, as well as schematics that explain how conversant works under the hood. ๐Ÿ”ง

License

conversant has an MIT License.

More Repositories

1

cohere-toolkit

Cohere Toolkit is a collection of prebuilt components enabling users to quickly build and deploy RAG applications.
TypeScript
2,814
star
2

notebooks

Code examples and jupyter notebooks for the Cohere Platform
Jupyter Notebook
472
star
3

cohere-python

Python Library for Accessing the Cohere API
Python
294
star
4

sandbox-topically

Topic modeling helpers using managed language models from Cohere. Name text clusters using large GPT models.
Jupyter Notebook
214
star
5

DiskVectorIndex

Python
202
star
6

BinaryVectorDB

Efficient vector database for hundred millions of embeddings.
Python
198
star
7

cohere-terrarium

A simple Python sandbox for helpful LLM data agents
Python
153
star
8

quick-start-connectors

This open-source repository offers reference code for integrating workplace datastores with Cohere's LLMs, enabling developers and businesses to perform seamless retrieval-augmented generation (RAG) on their own data.
Python
140
star
9

sandbox-grounded-qa

A sandbox repo for grounded question answering with Cohere and Google Search
Python
135
star
10

magikarp

Python
125
star
11

cohere-typescript

The Cohere TypeScript SDK
TypeScript
124
star
12

sandbox-toy-semantic-search

A demonstration of how a toy (but usable!) semantic search engine can be quickly built using Cohere's platform.
Python
114
star
13

sandbox-multilingual

A demonstration of a multilingual semantic search engine you can be quickly built using Cohere's platform.
Python
59
star
14

cohere-aws

Jupyter Notebook
57
star
15

sandbox-accelerating-chatbot-training

Leveraging Cohere's models to enable zero-shot routing
Python
53
star
16

cohere-go

Go Library for Accessing the Cohere API
Go
45
star
17

samples

Sample integrations built by Cohere.
JavaScript
25
star
18

examples

Examples and Demos using the Cohere APIs
Jupyter Notebook
23
star
19

sandbox-condense

Webpage Summarizer
JavaScript
20
star
20

human-feedback-paper

Code and data from the paper 'Human Feedback is not Gold Standard'
Jupyter Notebook
18
star
21

public-demos

Public demos using the Cohere platform!
TypeScript
11
star
22

tokenizer

BPE tokenization implemented in Golang ๐Ÿ’™
Go
10
star
23

cohere-java

Cohere's Java SDK
Java
7
star
24

cohere-developer-experience

Docs, Snippets, Guides
MDX
5
star
25

co

Cohere command line tool
Shell
3
star
26

cohere-compass-sdk

Provides an SDK for interacting with Compass, and Compass Parsing
Python
2
star
27

co-cli

Shell
1
star
28

cohere-ruby

Ruby
1
star