Package: conversant
################################################################################
#    ____      _                     ____                  _ _                 #
#   / ___|___ | |__   ___ _ __ ___  / ___|  __ _ _ __   __| | |__   _____  __  #
#  | |   / _ \| '_ \ / _ \ '__/ _ \ \___ \ / _` | '_ \ / _` | '_ \ / _ \ \/ /  #
#  | |__| (_) | | | |  __/ | |  __/  ___) | (_| | | | | (_| | |_) | (_) >  <   #
#   \____\___/|_| |_|\___|_|  \___| |____/ \__,_|_| |_|\__,_|_.__/ \___/_/\_\  #
#                                                                              #
# 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 TeamProject maintained until at least (YYYY-MM-DD):2023-03-01ConversantBuild conversational AI on top ofCohere'slarge language models🗣 Use large language models quickly with Cohere'sAPI😃 Customize personas💁 Leave management of chat history up toconversant🪨 Ground conversations in your provided facts (soon!)🐍 Installconversantwith pipconversantis 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.conversantaims
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 howconversantis part of the Cohere Sandbox on ourlaunch blog post.Tryconversanton our Streamlit demohere! 🎉Table of ContentsInstallation and UsageInstallationStreamlit DemoRunning Your Own Streamlit DemoCreating a Custom PersonaEditing a Persona on the DemoUsageHow Conversant WorksDocumentationGet SupportContributing GuidelinesLicenseInstallation and UsageInstallationconversantis availableon PyPI, and is tested on Python 3.8+ andCohere2.8.0+.pip install conversantStreamlit DemoWant to see it in action first? You can useconversanton aStreamlitapp without installing anythinghere! 🎉Running Your Own Streamlit DemoCohere uses Streamlit to create its demo applications. If you’re new to Streamlit, you can install ithereand read more about running Streamlit commandshere.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 aCOHERE_API_KEY.
You can generate one by visitingdashboard.cohere.ai.Local Streamlit appsIf 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 thesecrets.tomlfile 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.pyHosted Streamlit appsIf instead you would like to create a hosted Streamlit app, add your Cohere API key to Streamlit viaSecrets Management. Add the following line as a Secret:COHERE_API_KEY = "YOUR_API_KEY_HERE"Creating a Custom PersonaOnce you have your own instance of the Streamlit app, you can begin experimenting with creating custom personas! Check out theconfig.jsonfor each persona inconversant/personasdirectory. You'll need to create a subfolder within this directory that corresponds to your new persona and add aconfig.jsonfile.As a note, we strongly recommend forking thesandbox-conversant-librepository rather than installing it as a library from PyPI. When you create a new persona, use thepersonasdirectory in the cloned repository. The directory structure should look like this:conversant/personas
├── fortune-teller
│   └── config.json
└── your-persona-name # new
    └── config.jsonThe 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 forco.generate()chat_prompt_config:preamble: Description of the persona.example_separator: A string that separates each example conversation.headers: A name for thebotand theuser.examples: A few conversation examples (few-shot), or empty (zero-shot).conversantwill take care of the rest! As an example, check outfortune-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 personasIf 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 theconversant/personasdirectory, and needs to have the same structure:custom-personas
├── your-first-persona
│   └── config.json
└── your-second-persona
    └── config.jsonAfter 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 readsCUSTOM_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 theconversantdemo personas.Troubleshooting missing personasIf you do not see the new persona in the drop down menu, you may need to specify a
custom persona directory. Followthe instructions aboveto tell the app where to look for the personas.Editing a Persona on the DemoYou can also edit a persona on the Streamlit app!UsageWithconversant, you can create a chatbot powered byCohere's large language models with just the following code snippet.importcohereimportconversantco=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 ownChatPrompt.fromconversant.promptsimportChatPromptshakespeare_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 Worksconversantuses prompt completion to define a chatbot persona with a description and a few examples. The prompt is sent as input to Cohere'sco.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 tothis section inCONTRIBUTORS.md.DocumentationFull documentation can be foundhere.Get SupportIf you have any questions or comments, please file an issue or reach out to us onDiscord.Contributing GuidelinesIf you would like to contribute to this project, please readCONTRIBUTORS.mdin 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.mdcontains a walkthrough to help developers get started, as well as schematics that explain howconversantworks under the hood. :wrench:Licenseconversanthas anMIT License.