{"id":15175438,"url":"https://github.com/cohere-ai/sandbox-conversant-lib","last_synced_at":"2025-04-05T22:06:39.113Z","repository":{"id":62612990,"uuid":"556790910","full_name":"cohere-ai/sandbox-conversant-lib","owner":"cohere-ai","description":"Conversational AI tooling \u0026 personas built on Cohere's LLMs","archived":false,"fork":false,"pushed_at":"2023-08-14T23:10:55.000Z","size":1907,"stargazers_count":174,"open_issues_count":12,"forks_count":33,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-29T21:07:54.571Z","etag":null,"topics":["chatbot","chatbot-framework","chatbots","cohere","conversational-agent","conversational-ai","conversational-bots","dialogue-generation","dialogue-systems","large-language-models","llm","nlp"],"latest_commit_sha":null,"homepage":"https://discord.gg/co-mmunity","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cohere-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-24T14:17:36.000Z","updated_at":"2025-02-26T20:51:24.000Z","dependencies_parsed_at":"2024-12-03T17:43:37.963Z","dependency_job_id":"9315fccb-332b-406f-a4bf-1da9e5dbdff9","html_url":"https://github.com/cohere-ai/sandbox-conversant-lib","commit_stats":{"total_commits":73,"total_committers":13,"mean_commits":5.615384615384615,"dds":"0.36986301369863017","last_synced_commit":"eeb7c808c2ab59f553f3500b90681019f79365be"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohere-ai%2Fsandbox-conversant-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohere-ai%2Fsandbox-conversant-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohere-ai%2Fsandbox-conversant-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohere-ai%2Fsandbox-conversant-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cohere-ai","download_url":"https://codeload.github.com/cohere-ai/sandbox-conversant-lib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406088,"owners_count":20933803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chatbot-framework","chatbots","cohere","conversational-agent","conversational-ai","conversational-bots","dialogue-generation","dialogue-systems","large-language-models","llm","nlp"],"created_at":"2024-09-27T12:37:19.726Z","updated_at":"2025-04-05T22:06:39.084Z","avatar_url":"https://github.com/cohere-ai.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"```\n################################################################################\n# ____ _ ____ _ _ #\n# / ___|___ | |__ ___ _ __ ___ / ___| __ _ _ __ __| | |__ _____ __ #\n# | | / _ \\| '_ \\ / _ \\ '__/ _ \\ \\___ \\ / _` | '_ \\ / _` | '_ \\ / _ \\ \\/ / #\n# | |__| (_) | | | | __/ | | __/ ___) | (_| | | | | (_| | |_) | (_) \u003e \u003c #\n# \\____\\___/|_| |_|\\___|_| \\___| |____/ \\__,_|_| |_|\\__,_|_.__/ \\___/_/\\_\\ #\n# #\n# This project is part of Cohere Sandbox, Cohere's Experimental Open Source #\n# offering. This project provides a library, tooling, or demo making use of #\n# the Cohere Platform. You should expect (self-)documented, high quality code #\n# but be warned that this is EXPERIMENTAL. Therefore, also expect rough edges, #\n# non-backwards compatible changes, or potential changes in functionality as #\n# the library, tool, or demo evolves. Please consider referencing a specific #\n# git commit or version if depending upon the project in any mission-critical #\n# code as part of your own projects. #\n# #\n# Please don't hesitate to raise issues or submit pull requests, and thanks #\n# for checking out this project! #\n# #\n################################################################################\n```\n\n**Maintainer:** [Cohere ConvAI Team](mailto:convai@cohere.com) \\\n**Project maintained until at least (YYYY-MM-DD):** 2023-03-01\n\n# Conversant\n[![tests](https://github.com/cohere-ai/sandbox-conversant-lib/actions/workflows/run_tests.yaml/badge.svg)](https://github.com/cohere-ai/sandbox-conversant-lib/actions/workflows/run_tests.yaml/badge.svg)\n[![PyPI](https://img.shields.io/pypi/v/conversant.svg)](https://img.shields.io/pypi/v/conversant.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\nBuild conversational AI on top of [Cohere](https://cohere.ai/)'s [large language models](https://docs.cohere.ai/generate-reference/)\n- πŸ—£ Use large language models quickly with Cohere's [API](https://docs.cohere.ai/api-reference/)\n- πŸ˜ƒ Customize personas\n- πŸ’ Leave management of chat history up to `conversant`\n- πŸͺ¨ Ground conversations in your provided facts (soon!)\n- 🐍 Install `conversant` with pip\n\n`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\nto be modular, flexible and extensible so you can create any kind of chatbots you want!\n\nWe 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!\n\nRead more about how `conversant` is part of the Cohere Sandbox on our [launch blog post](https://txt.cohere.ai/introducing-sandbox-coheres-experimental-open-source-initiative/).\n\nTry `conversant` on our Streamlit demo [here](https://conversant.streamlit.app/)! πŸŽ‰\n\n## Table of Contents\n1. [Installation and Usage](#installation-and-usage)\n 1. [Installation](#installation)\n 2. [Streamlit Demo](#streamlit-demo)\n 3. [Running Your Own Streamlit Demo](#running-your-own-streamlit-demo)\n 4. [Creating a Custom Persona](#creating-a-custom-persona)\n 5. [Editing a Persona on the Demo](#editing-a-persona-on-the-demo)\n 6. [Usage](#usage)\n2. [How Conversant Works](#how-conversant-works)\n3. [Documentation](#documentation)\n4. [Get Support](#get-support)\n5. [Contributing Guidelines](#contributing-guidelines)\n6. [License](#license)\n\n## Installation and Usage\n\n### Installation\n\n`conversant` is available [on PyPI](https://pypi.org/project/conversant/), and is tested on Python 3.8+ and [Cohere](https://pypi.org/project/cohere/) 2.8.0+.\n```\npip install conversant\n```\n### Streamlit Demo\n\nWant to see it in action first? You can use `conversant` on a [Streamlit](https://docs.streamlit.io/) app without installing anything [here](https://conversant.streamlit.app/)! πŸŽ‰\n\n\u003cp float=\"none\"\u003e\n \u003cimg src=\"https://github.com/cohere-ai/sandbox-conversant-lib/raw/main/static/fortune-teller-setup.png\" alt=\"Screenshot showing the available personas on the Streamlit demo, with the Fortune Teller persona selected by default..\" height=\"550\"/\u003e\n \u003cimg src=\"https://github.com/cohere-ai/sandbox-conversant-lib/raw/main/static/fortune-teller-chat.png\" alt=\"Screenshot showing an exchange between a Fortune Teller chatbot and a user.\" height=\"550\"/\u003e\n\u003c/p\u003e\n\n### Running Your Own Streamlit Demo\n\nCohere uses Streamlit to create its demo applications. If you’re new to Streamlit, you can install it [here](https://docs.streamlit.io/library/get-started/installation) and read more about running Streamlit commands [here](https://docs.streamlit.io/library/get-started/main-concepts).\n\nIf you would like to modify this Streamlit demo locally, we strongly recommend forking this repository rather than installing it as a library from PyPI.\n\nIf you'd like to spin up your own instance of the Streamlit demo, you will first need a `COHERE_API_KEY`. \nYou can generate one by visiting [dashboard.cohere.ai](https://dashboard.cohere.ai/welcome/register?utm_source=github\u0026utm_medium=content\u0026utm_campaign=sandbox\u0026utm_content=conversant). \n\n#### Local Streamlit apps\nIf you plan to run the Streamlit app locally, you can add the key to `.streamlit/secrets.toml`:\n```\nCOHERE_API_KEY = \"YOUR_API_KEY_HERE\"\n```\n\nWhen 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:\n```\nexport COHERE_API_KEY = \"YOUR_API_KEY_HERE\"\n```\n\nStart the Streamlit app from the command line with the following command:\n```\nstreamlit run conversant/demo/streamlit_example.py\n```\n\n#### Hosted Streamlit apps\nIf instead you would like to create a hosted Streamlit app, add your Cohere API key to Streamlit via [Secrets Management](https://docs.streamlit.io/streamlit-cloud/get-started/deploy-an-app/connect-to-data-sources/secrets-management). Add the following line as a Secret:\n```\nCOHERE_API_KEY = \"YOUR_API_KEY_HERE\"\n```\n\n### Creating a Custom Persona\nOnce 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`](https://github.com/cohere-ai/sandbox-conversant-lib/tree/main/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. \n\nAs 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:\n\n```\nconversant/personas\nβ”œβ”€β”€ fortune-teller\nβ”‚ └── config.json\n└── your-persona-name # new\n └── config.json\n```\n\nThe config file should contain the following:\n- `chatbot_config`: \n - `max_context_examples`: The length of the chat history for the chatbot to use in reply.\n - `avatar`: Optional emoji shortcode or URL to image as the chatbot's avatar. Defaults to πŸ€–.\n- `client_config`: Parameters for [`co.generate()`](https://docs.cohere.ai/generate-reference)\n- `chat_prompt_config`: \n - `preamble`: Description of the persona.\n - `example_separator`: A string that separates each example conversation.\n - `headers`: A name for the `bot` and the `user`.\n - `examples`: A few conversation examples (few-shot), or empty (zero-shot).\n\n`conversant` will take care of the rest! As an example, check out [`fortune-teller/config.json`](https://github.com/cohere-ai/sandbox-conversant-lib/blob/main/conversant/personas/fortune-teller/config.json). When you launch the Streamlit app, the new persona will appear in the drop down menu.\n\n#### Running the app with a subset of custom personas\n\nIf 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:\n```\ncustom-personas\nβ”œβ”€β”€ your-first-persona\nβ”‚ └── config.json\n└── your-second-persona\n └── config.json\n``` \n\nAfter 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 \nfirst lines reads `CUSTOM_PERSONA_DIRECTORY = None`. Change this to specify the desired \npersona directory, e.g. `CUSTOM_PERSONA_DIRECTORY = \"/Users/yourname/custom-personas\"`.\n\nIf this is unchanged, the app will default to using the directory that contains the \n`conversant` demo personas.\n\n#### Troubleshooting missing personas\n\nIf you do not see the new persona in the drop down menu, you may need to specify a \ncustom persona directory. Follow [the instructions above](#running-the-app-with-a-subset-of-custom-personas) to tell the app where to look for the personas.\n\n### Editing a Persona on the Demo\nYou can also edit a persona on the Streamlit app!\n\u003cimg src=\"https://github.com/cohere-ai/sandbox-conversant-lib/raw/main/static/fortune-teller-edit.png\" alt=\"Screenshot showing the interface for editing a persona on the Streamlit app.\"/\u003e\n\n### Usage\n\nWith `conversant`, you can create a chatbot powered by [Cohere](https://cohere.ai/)'s large language models with just the following code snippet.\n```python\nimport cohere\nimport conversant\n\nco = cohere.Client(\"YOUR_API_KEY_HERE\")\nbot = conversant.PromptChatbot.from_persona(\"fantasy-wizard\", client=co)\nprint(bot.reply(\"Hello!\"))\n\u003e\u003e\u003e \"Well met, fair traveller. What bringest thou to mine village?\"\n```\n\nYou can also define your own persona by passing in your own `ChatPrompt`. \n```python\nfrom conversant.prompts import ChatPrompt\n\nshakespeare_config = {\n \"preamble\": \"Below is a conversation between Shakespeare and a Literature Student.\",\n \"example_separator\": \"\u003cCONVERSATION\u003e\\n\",\n \"headers\": {\n \"user\": \"Literature Student\",\n \"bot\": \"William Shakespeare\",\n },\n \"examples\": [\n [\n {\n \"user\": \"Who are you?\",\n \"bot\": \"Mine own nameth is Shakespeare, and I speaketh in riddles.\",\n },\n ]\n ],\n}\nshakespeare_bot = conversant.PromptChatbot(\n client=co, prompt=ChatPrompt.from_dict(shakespeare_config)\n)\nprint(shakespeare_bot.reply(\"Hello!\"))\n\u003e\u003e\u003e \"Greeteth, and welcome. I am Shakespeare, the great poet, dramatist, and playwright.\"\n```\n\n\u003c!-- From here, it's also possible to talk to your chatbot using the [Streamlit](https://docs.streamlit.io/) app! This will launch the demo with your chatbot persona pre-selected. For this to work, `COHERE_API_KEY` needs to be set as an environment variable.\n```python\nfrom conversant.utils import demo_utils\ndemo_utils.launch_streamlit(shakespeare_bot)\n``` --\u003e\n## How Conversant Works\n`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()`](https://docs.cohere.ai/generate-reference/) endpoint for an autoregressive language model to generate text in a few-shot manner from the examples and the current dialogue context. \n\nEach 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.\n\nIn the future, we plan to add functionality for a chatbot to be factually grounded using text that is retrieved from a local document cache.\n\nFor more information, refer to [this section in `CONTRIBUTORS.md`](https://github.com/cohere-ai/sandbox-conversant-lib/blob/main/CONTRIBUTORS.md#conversant-schematic).\n\n## Documentation\nFull documentation can be found [here](https://cohere-ai.github.io/sandbox-conversant-lib/).\n\n## Get Support\n\nIf you have any questions or comments, please file an issue or reach out to us on [Discord](https://discord.gg/co-mmunity).\n\n## Contributing Guidelines\nIf you would like to contribute to this project, please read [`CONTRIBUTORS.md`](https://github.com/cohere-ai/sandbox-conversant-lib/blob/main/CONTRIBUTORS.md)\nin this repository, and sign the Contributor License Agreement before submitting\nany pull requests. A link to sign the Cohere CLA will be generated the first time \nyou make a pull request to a Cohere repository.\n\nIn addition to guidelines around submitting code to this repository, [`CONTRIBUTORS.md`](https://github.com/cohere-ai/sandbox-conversant-lib/blob/main/CONTRIBUTORS.md) contains a walkthrough to help developers get started, as well as schematics that explain how `conversant` works under the hood. :wrench:\n\n## License\n`conversant` has an [MIT License](https://github.com/cohere-ai/sandbox-conversant-lib/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohere-ai%2Fsandbox-conversant-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcohere-ai%2Fsandbox-conversant-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohere-ai%2Fsandbox-conversant-lib/lists"}