_đ¨đ§ Please note that ControlFlow is under active development ahead of its initial public release!đ§đ¨_
# ControlFlow
**ControlFlow is a Python framework for building agentic AI workflows.**
ControlFlow provides a structured, developer-focused framework for defining workflows and delegating work to LLMs, without sacrificing control or transparency:
- Create discrete, observable [tasks](https://controlflow.ai/concepts/tasks) for an AI to solve.
- Assign one or more specialized AI [agents](https://controlflow.ai/concepts/agents) to each task.
- Combine tasks into a [flow](https://controlflow.ai/concepts/flows) to orchestrate more complex behaviors.
This task-centric approach allows you to harness the power of AI for complex workflows while maintaining fine-grained control. By defining clear objectives and constraints for each task, you can balance AI autonomy with precise oversight, letting you build sophisticated AI-powered applications with confidence.
## Installation
Install ControlFlow with `pip`:
```bash
pip install controlflow
```
You'll also need to configure your LLM provider. ControlFlow's default provider is OpenAI, which requires an API key via the `OPENAI_API_KEY` environment variable:
```
export OPENAI_API_KEY=your-api-key
```
You can also configure a [different LLM provider](https://controlflow.ai/guides/llms).
## Example
```python
import controlflow as cf
from pydantic import BaseModel
# create an agent to write a research report
author = cf.Agent(
name="Deep Thought",
instructions="Use a formal tone and clear language",
)
class ResearchTopic(BaseModel):
title: str
keywords: list[str]
@cf.flow
def research_workflow() -> str:
# Task 1: the default agent will work with the user to choose a topic
topic = cf.Task(
"Work with the user to come up with a research topic",
result_type=ResearchTopic,
user_access=True,
)
# Task 2: the default agent will create an outline based on the topic
outline = cf.Task("Create an outline", context=dict(topic=topic))
# Task 3: the author agent will write a first draft
draft = cf.Task(
"Write a first draft",
context=dict(outline=outline),
agents=[author]
)
return draft
# run the workflow
result = research_workflow()
print(result)
```
ControlFlow is built on Prefect 3.0, so you can follow your flow's execution in the Prefect UI:
<img width="1427" alt="Prefect UI showing ControlFlow execution" src="https://github.com/PrefectHQ/ControlFlow/assets/153965/2dfdfb43-3afa-4709-9ec3-c66840084087">
## Why ControlFlow?
ControlFlow is designed to address the challenges of building AI-powered applications that are both powerful and predictable:
### 𧊠Task-Centric Architecture
Break complex AI workflows into manageable, observable steps. This approach ensures that AI agents operate within well-defined boundaries, making it easier to reason about and manage complex workflows.
```python
topic = cf.Task("Generate a research topic", result_type=ResearchTopic)
outline = cf.Task("Create an outline", context=dict(topic=topic))
draft = cf.Task("Write a first draft", context=dict(outline=outline))
```
### đ Structured Results
Bridge the gap between AI and traditional software with type-safe outputs. By using Pydantic models, you ensure that AI-generated content always matches your application's requirements.
```python
class ResearchTopic(BaseModel):
title: str
keywords: list[str]
topic_task = cf.Task("Generate a topic", result_type=ResearchTopic)
```
### đ¤ Specialized Agents
Deploy task-specific AI agents for efficient problem-solving. Agents can have their own instructions, tools, and even be backed by different LLM models.
```python
researcher = cf.Agent(name="Researcher", instructions="Conduct thorough research")
writer = cf.Agent(name="Writer", instructions="Write clear, concise content")
topic_task = cf.Task("Research topic", agents=[researcher])
draft_task = cf.Task("Write draft", agents=[writer])
```
### đ Ecosystem Integration
Seamlessly work with your existing code, tools, and the broader AI ecosystem. ControlFlow supports a wide range of LangChain models and tools, making it easy to incorporate cutting-edge AI capabilities.
```python
from langchain.tools import WikipediaQueryRun
research_task = cf.Task("Research topic", tools=[WikipediaQueryRun()])
```
### đī¸ Flexible Control
Continuously tune the balance of control and autonomy in your agentic workflows. Adjust the scope and oversight of your tasks dynamically throughout the process.
```python
with cf.instructions("Be creative"):
brainstorm_task.run()
with cf.instructions("Follow APA style strictly"):
formatting_task.run()
```
### đšī¸ Multi-Agent Orchestration
Coordinate multiple AI agents within a single workflow - or a single task. This allows you to create complex, multi-step AI processes that leverage the strengths of different models and approaches.
```python
@cf.flow
def research_paper():
topic = cf.Task("Choose topic", agents=[researcher])
outline = cf.Task("Create outline", agents=[researcher, writer])
draft = cf.Task("Write draft", agents=[writer])
return draft
```
### đ Native Observability and Debugging
Built on Prefect 3.0, ControlFlow allows you to combine agentic and traditional workflows and monitor them all in one place. This observability is crucial for debugging, optimizing performance, and ensuring that your AI applications function as intended.
```python
@cf.flow(retries=2)
def enhance_data():
data = etl_pipeline()
enhanced_data = cf.Task("Add topics to data", context=dict(data=data))
return enhanced_data
```
ControlFlow empowers you to build AI workflows with confidence, maintaining control and visibility throughout the process. It offers a powerful and flexible framework for creating AI-powered applications that are transparent, maintainable, and aligned with software engineering best practices.
## Development
To install for development:
```bash
git clone https://github.com/PrefectHQ/ControlFlow.git
cd controlflow
pip install -e ".[dev]"
```
To run tests:
```bash
cd controlflow
pytest -vv
```
The ControlFlow documentation is built with [Mintlify](https://mintlify.com/). To build the documentation, first install `mintlify`:
```bash
npm i -g mintlify
```
Then run the local build:
```bash
cd controlflow/docs
mintlify dev
```
Raw data
{
"_id": null,
"home_page": null,
"name": "controlflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, chatbot, llm, ai orchestration, llm orchestration, agentic workflows, flow engineering, prefect, workflow, orchestration, python, GPT, openai, assistant, agents, AI agents, natural language processing",
"author": null,
"author_email": "Jeremiah Lowin <153965+jlowin@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/42/33/296839a3d16cca64075d3418b6c02a9e58f4745a2b0ec5fb8bd25697c8ab/controlflow-0.8.1.tar.gz",
"platform": null,
"description": "\n\n\n_\ud83d\udea8\ud83d\udea7 Please note that ControlFlow is under active development ahead of its initial public release!\ud83d\udea7\ud83d\udea8_\n\n# ControlFlow\n\n**ControlFlow is a Python framework for building agentic AI workflows.**\n\nControlFlow provides a structured, developer-focused framework for defining workflows and delegating work to LLMs, without sacrificing control or transparency:\n\n- Create discrete, observable [tasks](https://controlflow.ai/concepts/tasks) for an AI to solve.\n- Assign one or more specialized AI [agents](https://controlflow.ai/concepts/agents) to each task.\n- Combine tasks into a [flow](https://controlflow.ai/concepts/flows) to orchestrate more complex behaviors.\n\nThis task-centric approach allows you to harness the power of AI for complex workflows while maintaining fine-grained control. By defining clear objectives and constraints for each task, you can balance AI autonomy with precise oversight, letting you build sophisticated AI-powered applications with confidence.\n\n\n## Installation\n\nInstall ControlFlow with `pip`:\n\n```bash\npip install controlflow\n```\n\nYou'll also need to configure your LLM provider. ControlFlow's default provider is OpenAI, which requires an API key via the `OPENAI_API_KEY` environment variable:\n```\nexport OPENAI_API_KEY=your-api-key\n```\nYou can also configure a [different LLM provider](https://controlflow.ai/guides/llms).\n\n## Example\n\n```python\nimport controlflow as cf\nfrom pydantic import BaseModel\n\n\n# create an agent to write a research report\nauthor = cf.Agent(\n name=\"Deep Thought\",\n instructions=\"Use a formal tone and clear language\",\n)\n\n\nclass ResearchTopic(BaseModel):\n title: str\n keywords: list[str]\n\n\n@cf.flow\ndef research_workflow() -> str:\n # Task 1: the default agent will work with the user to choose a topic\n topic = cf.Task(\n \"Work with the user to come up with a research topic\",\n result_type=ResearchTopic,\n user_access=True,\n )\n\n # Task 2: the default agent will create an outline based on the topic\n outline = cf.Task(\"Create an outline\", context=dict(topic=topic))\n \n # Task 3: the author agent will write a first draft \n draft = cf.Task(\n \"Write a first draft\", \n context=dict(outline=outline),\n agents=[author]\n )\n \n return draft\n\n\n# run the workflow\nresult = research_workflow()\nprint(result)\n```\n\nControlFlow is built on Prefect 3.0, so you can follow your flow's execution in the Prefect UI:\n\n<img width=\"1427\" alt=\"Prefect UI showing ControlFlow execution\" src=\"https://github.com/PrefectHQ/ControlFlow/assets/153965/2dfdfb43-3afa-4709-9ec3-c66840084087\">\n\n## Why ControlFlow?\n\nControlFlow is designed to address the challenges of building AI-powered applications that are both powerful and predictable:\n\n### \ud83e\udde9 Task-Centric Architecture\n\nBreak complex AI workflows into manageable, observable steps. This approach ensures that AI agents operate within well-defined boundaries, making it easier to reason about and manage complex workflows.\n\n```python\ntopic = cf.Task(\"Generate a research topic\", result_type=ResearchTopic)\noutline = cf.Task(\"Create an outline\", context=dict(topic=topic))\ndraft = cf.Task(\"Write a first draft\", context=dict(outline=outline))\n```\n\n### \ud83d\udd12 Structured Results\n\nBridge the gap between AI and traditional software with type-safe outputs. By using Pydantic models, you ensure that AI-generated content always matches your application's requirements.\n\n```python\nclass ResearchTopic(BaseModel):\n title: str\n keywords: list[str]\n\ntopic_task = cf.Task(\"Generate a topic\", result_type=ResearchTopic)\n```\n\n### \ud83e\udd16 Specialized Agents\n\nDeploy task-specific AI agents for efficient problem-solving. Agents can have their own instructions, tools, and even be backed by different LLM models.\n\n```python\nresearcher = cf.Agent(name=\"Researcher\", instructions=\"Conduct thorough research\")\nwriter = cf.Agent(name=\"Writer\", instructions=\"Write clear, concise content\")\n\ntopic_task = cf.Task(\"Research topic\", agents=[researcher])\ndraft_task = cf.Task(\"Write draft\", agents=[writer])\n```\n\n### \ud83d\udd17 Ecosystem Integration\n\nSeamlessly work with your existing code, tools, and the broader AI ecosystem. ControlFlow supports a wide range of LangChain models and tools, making it easy to incorporate cutting-edge AI capabilities.\n\n```python\nfrom langchain.tools import WikipediaQueryRun\n\nresearch_task = cf.Task(\"Research topic\", tools=[WikipediaQueryRun()])\n```\n\n### \ud83c\udf9b\ufe0f Flexible Control\n\nContinuously tune the balance of control and autonomy in your agentic workflows. Adjust the scope and oversight of your tasks dynamically throughout the process.\n\n```python\nwith cf.instructions(\"Be creative\"):\n brainstorm_task.run()\n\nwith cf.instructions(\"Follow APA style strictly\"):\n formatting_task.run()\n```\n\n### \ud83d\udd79\ufe0f Multi-Agent Orchestration\n\nCoordinate multiple AI agents within a single workflow - or a single task. This allows you to create complex, multi-step AI processes that leverage the strengths of different models and approaches.\n\n```python\n@cf.flow\ndef research_paper():\n topic = cf.Task(\"Choose topic\", agents=[researcher])\n outline = cf.Task(\"Create outline\", agents=[researcher, writer])\n draft = cf.Task(\"Write draft\", agents=[writer])\n return draft\n```\n\n### \ud83d\udd0d Native Observability and Debugging\n\nBuilt on Prefect 3.0, ControlFlow allows you to combine agentic and traditional workflows and monitor them all in one place. This observability is crucial for debugging, optimizing performance, and ensuring that your AI applications function as intended.\n\n```python\n@cf.flow(retries=2)\ndef enhance_data():\n data = etl_pipeline()\n enhanced_data = cf.Task(\"Add topics to data\", context=dict(data=data))\n return enhanced_data\n```\n\nControlFlow empowers you to build AI workflows with confidence, maintaining control and visibility throughout the process. It offers a powerful and flexible framework for creating AI-powered applications that are transparent, maintainable, and aligned with software engineering best practices.\n\n## Development\n\nTo install for development:\n\n```bash\ngit clone https://github.com/PrefectHQ/ControlFlow.git\ncd controlflow\npip install -e \".[dev]\"\n```\n\nTo run tests:\n\n```bash\ncd controlflow\npytest -vv\n```\n\nThe ControlFlow documentation is built with [Mintlify](https://mintlify.com/). To build the documentation, first install `mintlify`:\n```bash\nnpm i -g mintlify\n```\nThen run the local build:\n```bash\ncd controlflow/docs\nmintlify dev\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A framework for building agentic LLM workflows",
"version": "0.8.1",
"project_urls": {
"Code": "https://github.com/PrefectHQ/ControlFlow"
},
"split_keywords": [
"ai",
" chatbot",
" llm",
" ai orchestration",
" llm orchestration",
" agentic workflows",
" flow engineering",
" prefect",
" workflow",
" orchestration",
" python",
" gpt",
" openai",
" assistant",
" agents",
" ai agents",
" natural language processing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c1244de765165771364afbd8187615bd84be21b47c0730d274dea7492a921172",
"md5": "031296c73cc2ce93d4b31c679a23a956",
"sha256": "1ef192314e1df14c1840ce133caa3bc6a892fe325ebd608c3d8175a96dfad8f4"
},
"downloads": -1,
"filename": "controlflow-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "031296c73cc2ce93d4b31c679a23a956",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 75868,
"upload_time": "2024-06-25T21:59:02",
"upload_time_iso_8601": "2024-06-25T21:59:02.740838Z",
"url": "https://files.pythonhosted.org/packages/c1/24/4de765165771364afbd8187615bd84be21b47c0730d274dea7492a921172/controlflow-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4233296839a3d16cca64075d3418b6c02a9e58f4745a2b0ec5fb8bd25697c8ab",
"md5": "2ea2d6cac136d929917a5a4a60db52f9",
"sha256": "b62b6be4737467a4ba04b461bd8d46bf276580d8a11c597e55f5b80db47bef88"
},
"downloads": -1,
"filename": "controlflow-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "2ea2d6cac136d929917a5a4a60db52f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1266466,
"upload_time": "2024-06-25T21:59:04",
"upload_time_iso_8601": "2024-06-25T21:59:04.989231Z",
"url": "https://files.pythonhosted.org/packages/42/33/296839a3d16cca64075d3418b6c02a9e58f4745a2b0ec5fb8bd25697c8ab/controlflow-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-25 21:59:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrefectHQ",
"github_project": "ControlFlow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "controlflow"
}
JSON
