# flowchat - clean, readable, logical code.
[](https://pypi.org/project/flowchat/)
[](LICENSE.txt)
A Python library for building clean and efficient multi-step prompt chains. It is built on top of [OpenAI's Python API](https://github.com/openai/openai-python).
## What is Flowchat?
Flowchat is designed around the idea of a *chain*. Start the chain with `.anchor()`, which contains a system prompt. Use `.link()` to add additional messages.
To get a response from the LLM, use `.pull()`. Additionally, you can use `.pull(json_schema={"city": "string"})` to define a specific output response schema. This will validate the response and return a JSON object with the response. The subsequent response will be stored in an internal response variable.
When you're done one stage of your chain, you can log the chain's messages and responses with `.log()` and reset the current chat conversation messages with `.unhook()`.
Unhooking **does not** reset the internal response variable.
Instead, the idea of 'chaining' is that you can use the response from the previous stage in the next stage.
For example, when using `link` in the second stage, you can use the response from the first stage by using a lambda function: `.link(lambda response: f"Previous response: {response}")`.
You can use `.transform()` to transform the response from the previous stage into something else. For example, you can use `.transform(lambda response: response["city"])` to get the city from the response JSON object, or even map over a response list with a nested chain! You'll see more ways to use these functions in the [examples](/examples/natural_language_cli.py).
When you're finished with the entire chain, simply use `.last()` to return the last response.
Check out these [example chains](/examples) to get started!
## Installation
```bash
pip install flowchat
```
## Setup
Put your OpenAI API key in your environment variable file (eg. .env) as `OPENAI_API_KEY=sk-xxxxxx`. If you're using this as part of another project with a different name for the key (like `OPENAI_KEY` or something), simply pass that in `Chain(environ_key="OPENAI_KEY")`. Alternatively, you can simply pass the key itself when initializing the chain: `Chain(api_key="sk-xxxxxx")`.
## Example Usage
```py
from flowchat import Chain
chain = (
Chain(model="gpt-3.5-turbo") # default model for all pull() calls
.anchor("You are a historian.") # Set the first system prompt
.link("What is the capital of France?")
.pull().log().unhook() # Pull the response, log it, and reset prompts
.link(lambda desc: f"Extract the city in this statement: {desc}")
.pull(json_schema={"city": "string"}) # Pull the response and validate it
.transform(lambda city_json: city_json["city"]) # Get city from JSON
.log().unhook()
.anchor("You are an expert storyteller.")
.link(lambda city: f"Design a basic three-act point-form short story about {city}.")
.link("How long should it be?", assistant=True)
.link("Around 100 words.") # (For example) you can make multiple links!
.pull(max_tokens=512).log().unhook()
.anchor("You are a novelist. Your job is to write a novel about a story that you have heard.")
.link(lambda storyline: f"Briefly elaborate on the first act of the storyline: {storyline}")
.pull(max_tokens=256, model="gpt-4-turbo").log().unhook()
.link(lambda act: f"Summarize this act in around three words:\n{act}")
.pull(model="gpt-4")
.log_tokens() # Log token usage of the whole chain
)
print(f"Result: {chain.last()}") # >> "Artist's Dream Ignites"
```
### Natural Language CLI:
This is the short version that doesn't check if the command is possible to start. If you want to see a longer example with **nested chains**, check out the [full version](/examples/natural_language_cli.py).
```py
from flowchat import Chain, autodedent
import os
import subprocess
def execute_system_command(command):
try:
result = subprocess.run(
command, shell=True, check=True,
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
)
return result.stdout
except subprocess.CalledProcessError as e:
return e.stderr
def main():
print("Welcome to the Natural Language Command Line Interface!")
os_system_context = f"You are a shell interpreter assistant running on {os.name} operating system."
while True:
user_input = input("Please enter your command in natural language: ")
should_exit = (
Chain(model="gpt-3.5-turbo")
.link(autodedent(
"Does the user want to exit the CLI? Respond with 'YES' or 'NO'.",
user_input
)).pull(max_tokens=2).unhook().last()
)
if should_exit.lower() in ("yes", "y"):
print("Exiting the CLI.")
break
# Feed the input to flowchat
command_suggestion = (
Chain(model="gpt-4-turbo")
.anchor(os_system_context)
.link(autodedent(
"The user wants to do this: ",
user_input,
"Suggest a command that can achieve this in one line without user input or interaction."
)).pull().unhook()
.anchor(os_system_context)
.link(lambda suggestion: autodedent(
"Extract ONLY the command from this command desciption:",
suggestion
))
# define a JSON schema to extract the command from the suggestion
.pull(json_schema={"command": "echo 'Hello World!'"})
.transform(lambda command_json: command_json["command"])
.unhook().last()
)
print(f"Suggested command: {command_suggestion}")
# Execute the suggested command and get the result
command_output = execute_system_command(command_suggestion)
print(f"Command executed. Output:\n{command_output}")
if command_output != "":
description = (
Chain(model="gpt-3.5-turbo").anchor(os_system_context)
.link(f"Describe this output:\n{command_output}")
.pull().unhook().last()
)
# Logging the description
print(f"Explanation:\n{description}")
print("=" * 60)
if __name__ == "__main__":
main()
```
This project is under a MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/flatypus/flowchat",
"name": "flowchat",
"maintainer": "Hinson Chan",
"docs_url": null,
"requires_python": null,
"maintainer_email": "<yhc3141@gmail.com>",
"keywords": "openai gpt3 gpt-3 gpt4 gpt-4 chatbot ai nlp prompt prompt-engineering toolkit",
"author": "Hinson Chan",
"author_email": "<yhc3141@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6a/c1/ddb53fc9a14592da793b864db34d202c799fc8eab5340fd2dc739307c43e/flowchat-1.2.3.tar.gz",
"platform": null,
"description": "# flowchat - clean, readable, logical code.\n\n[](https://pypi.org/project/flowchat/)\n[](LICENSE.txt)\n\n\nA Python library for building clean and efficient multi-step prompt chains. It is built on top of [OpenAI's Python API](https://github.com/openai/openai-python).\n\n\n\n## What is Flowchat?\nFlowchat is designed around the idea of a *chain*. Start the chain with `.anchor()`, which contains a system prompt. Use `.link()` to add additional messages.\n\nTo get a response from the LLM, use `.pull()`. Additionally, you can use `.pull(json_schema={\"city\": \"string\"})` to define a specific output response schema. This will validate the response and return a JSON object with the response. The subsequent response will be stored in an internal response variable.\n\nWhen you're done one stage of your chain, you can log the chain's messages and responses with `.log()` and reset the current chat conversation messages with `.unhook()`.\nUnhooking **does not** reset the internal response variable. \n\nInstead, the idea of 'chaining' is that you can use the response from the previous stage in the next stage.\nFor example, when using `link` in the second stage, you can use the response from the first stage by using a lambda function: `.link(lambda response: f\"Previous response: {response}\")`. \n\nYou can use `.transform()` to transform the response from the previous stage into something else. For example, you can use `.transform(lambda response: response[\"city\"])` to get the city from the response JSON object, or even map over a response list with a nested chain! You'll see more ways to use these functions in the [examples](/examples/natural_language_cli.py).\n\nWhen you're finished with the entire chain, simply use `.last()` to return the last response.\n\nCheck out these [example chains](/examples) to get started!\n\n## Installation\n```bash\npip install flowchat\n```\n\n## Setup\nPut your OpenAI API key in your environment variable file (eg. .env) as `OPENAI_API_KEY=sk-xxxxxx`. If you're using this as part of another project with a different name for the key (like `OPENAI_KEY` or something), simply pass that in `Chain(environ_key=\"OPENAI_KEY\")`. Alternatively, you can simply pass the key itself when initializing the chain: `Chain(api_key=\"sk-xxxxxx\")`.\n\n## Example Usage\n```py\nfrom flowchat import Chain\n\nchain = (\n Chain(model=\"gpt-3.5-turbo\") # default model for all pull() calls\n .anchor(\"You are a historian.\") # Set the first system prompt\n .link(\"What is the capital of France?\")\n .pull().log().unhook() # Pull the response, log it, and reset prompts\n\n .link(lambda desc: f\"Extract the city in this statement: {desc}\")\n .pull(json_schema={\"city\": \"string\"}) # Pull the response and validate it\n .transform(lambda city_json: city_json[\"city\"]) # Get city from JSON\n .log().unhook()\n\n .anchor(\"You are an expert storyteller.\")\n .link(lambda city: f\"Design a basic three-act point-form short story about {city}.\")\n .link(\"How long should it be?\", assistant=True)\n .link(\"Around 100 words.\") # (For example) you can make multiple links!\n .pull(max_tokens=512).log().unhook()\n\n .anchor(\"You are a novelist. Your job is to write a novel about a story that you have heard.\")\n .link(lambda storyline: f\"Briefly elaborate on the first act of the storyline: {storyline}\")\n .pull(max_tokens=256, model=\"gpt-4-turbo\").log().unhook()\n\n .link(lambda act: f\"Summarize this act in around three words:\\n{act}\")\n .pull(model=\"gpt-4\")\n .log_tokens() # Log token usage of the whole chain\n)\n\nprint(f\"Result: {chain.last()}\") # >> \"Artist's Dream Ignites\"\n```\n\n### Natural Language CLI:\n\nThis is the short version that doesn't check if the command is possible to start. If you want to see a longer example with **nested chains**, check out the [full version](/examples/natural_language_cli.py).\n\n```py\nfrom flowchat import Chain, autodedent\nimport os\nimport subprocess\n\n\ndef execute_system_command(command):\n try:\n result = subprocess.run(\n command, shell=True, check=True,\n stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True\n )\n return result.stdout\n except subprocess.CalledProcessError as e:\n return e.stderr\n\n\ndef main():\n print(\"Welcome to the Natural Language Command Line Interface!\")\n os_system_context = f\"You are a shell interpreter assistant running on {os.name} operating system.\"\n\n while True:\n user_input = input(\"Please enter your command in natural language: \")\n\n should_exit = (\n Chain(model=\"gpt-3.5-turbo\")\n .link(autodedent(\n \"Does the user want to exit the CLI? Respond with 'YES' or 'NO'.\",\n user_input\n )).pull(max_tokens=2).unhook().last()\n )\n\n if should_exit.lower() in (\"yes\", \"y\"):\n print(\"Exiting the CLI.\")\n break\n\n # Feed the input to flowchat\n command_suggestion = (\n Chain(model=\"gpt-4-turbo\")\n .anchor(os_system_context)\n .link(autodedent(\n \"The user wants to do this: \",\n user_input,\n \"Suggest a command that can achieve this in one line without user input or interaction.\"\n )).pull().unhook()\n\n .anchor(os_system_context)\n .link(lambda suggestion: autodedent(\n \"Extract ONLY the command from this command desciption:\",\n suggestion\n ))\n # define a JSON schema to extract the command from the suggestion\n .pull(json_schema={\"command\": \"echo 'Hello World!'\"})\n .transform(lambda command_json: command_json[\"command\"])\n .unhook().last()\n )\n\n print(f\"Suggested command: {command_suggestion}\")\n\n # Execute the suggested command and get the result\n command_output = execute_system_command(command_suggestion)\n print(f\"Command executed. Output:\\n{command_output}\")\n\n if command_output != \"\":\n description = (\n Chain(model=\"gpt-3.5-turbo\").anchor(os_system_context)\n .link(f\"Describe this output:\\n{command_output}\")\n .pull().unhook().last()\n )\n # Logging the description\n print(f\"Explanation:\\n{description}\")\n\n print(\"=\" * 60)\n\n\nif __name__ == \"__main__\":\n main()\n```\n\nThis project is under a MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Streamlining the process of multi-prompting LLMs with chains",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/flatypus/flowchat",
"Issues": "https://github.com/flatypus/flowchat/issues",
"Repository": "https://github.com/flatypus/flowchat"
},
"split_keywords": [
"openai",
"gpt3",
"gpt-3",
"gpt4",
"gpt-4",
"chatbot",
"ai",
"nlp",
"prompt",
"prompt-engineering",
"toolkit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a29110cc938e0d60ac0bcad0f5ae5b2e81d9b2d3d08c8560b2fa51b0283774c2",
"md5": "2f645cb497561651bcdb9f45871efb41",
"sha256": "da9364cf69f73d3bf31297435dfc75eba47211032b06218d5debd3e6ac43892b"
},
"downloads": -1,
"filename": "flowchat-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f645cb497561651bcdb9f45871efb41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11513,
"upload_time": "2024-04-16T05:19:01",
"upload_time_iso_8601": "2024-04-16T05:19:01.761910Z",
"url": "https://files.pythonhosted.org/packages/a2/91/10cc938e0d60ac0bcad0f5ae5b2e81d9b2d3d08c8560b2fa51b0283774c2/flowchat-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ac1ddb53fc9a14592da793b864db34d202c799fc8eab5340fd2dc739307c43e",
"md5": "ab98939844151f04a447a23bb3408969",
"sha256": "e0dbb5a65944c936f19d4458847cb02eb2fe8ed2c09565181393135a7ac9c48b"
},
"downloads": -1,
"filename": "flowchat-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "ab98939844151f04a447a23bb3408969",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15850,
"upload_time": "2024-04-16T05:19:03",
"upload_time_iso_8601": "2024-04-16T05:19:03.286986Z",
"url": "https://files.pythonhosted.org/packages/6a/c1/ddb53fc9a14592da793b864db34d202c799fc8eab5340fd2dc739307c43e/flowchat-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-16 05:19:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flatypus",
"github_project": "flowchat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flowchat"
}
JSON
