Skip to content

Commit 44ef45b

Browse files
jlowinjlowin
authored
Merge pull request #28 from jlowin/mintlify
Try mintlify for docs
2 parents c1369e5 + 722fac4 commit 44ef45b

File tree

11 files changed

+262
-4
lines changed

11 files changed

+262
-4
lines changed

‎examples/multi_agent_conversation.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from controlflow import Agent, Task, flow
2-
from controlflow.core.controller.moderators import Moderator
2+
3+
# from controlflow.core.controller.moderators import Moderator
34

45
jerry = Agent(
56
name="Jerry",
@@ -70,7 +71,7 @@ def demo():
7071
agents=[jerry, george, elaine, kramer, newman],
7172
context=dict(topic=topic),
7273
)
73-
task.run(moderator=Moderator())
74+
task.run()
7475

7576

7677
demo()

‎mintlify/concepts.mdx

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Core Concepts
3+
---
4+
5+
**ControlFlow is built on three core concepts** that are essential to understanding how the framework works. These concepts are designed to make it easy to build and manage complex AI workflows, while also providing a clear structure for developers to follow.
6+
7+
## 🚦 Task
8+
**Tasks are the building blocks of ControlFlow workflows**. Each task represents a discrete objective for agents to solve, such as generating text, classifying data, or extracting information from a document. In addition, tasks can specify instructions, tools for agents to use, a schema for the expected output, and more.
9+
10+
Tasks can depend on each other in various ways, creating complex workflows that are easy to understand and manage:
11+
- **sequential** dependencies: one task must be completed before another can start
12+
- **context** dependencies: the result of one task is used as input for another
13+
- **subtask** dependencies: a task has subtasks that must be completed before the task can be considered done
14+
15+
By specifying the parameters of each task and how they relate to each other, developers can create complex workflows that are easy to understand and manage.
16+
17+
## 🌊 Flow
18+
**A flow represents an entire agentic workflow.** It is a "container" for the workflow that maintains consistent context and state across all tasks and agents. Each flow executes on a different thread, meaning all agents in the flow see the same state and can communicate with each other.
19+
20+
## 🤖 Agent
21+
**Agents are the AI "workers" that complete tasks.** Each agent can have distinct instructions, personality, and capabilities, and they are responsible for completing any tasks assigned to them. Agents can be specialized for specific tasks or more general-purpose, depending on the requirements of the workflow.

‎mintlify/concepts/flows.mdx

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Flows
2+
3+
In the ControlFlow framework, a `Flow` represents a container for an AI-enhanced workflow. It serves as the top-level object that encapsulates tasks, agents, tools, and context, providing a structured environment for AI-powered applications.
4+
5+
## The Role of Flows
6+
7+
Flows play a crucial role in organizing and managing the execution of AI-powered workflows. They provide a high-level abstraction for defining the overall structure and dependencies of tasks, agents, and tools, allowing developers to focus on the desired outcomes rather than the low-level details of agent coordination and communication.
8+
9+
Key aspects of flows include:
10+
11+
- **Task Management**: Flows contain a collection of tasks that define the discrete objectives and goals of the workflow. Tasks can be added to a flow explicitly or implicitly through the use of the `@ai_task` decorator or the `Task` class.
12+
13+
- **Agent Coordination**: Flows manage the assignment and orchestration of agents to tasks. By default, flows are initialized with a default agent, but custom agents can be specified to handle specific tasks or parts of the workflow.
14+
15+
- **Tool Management**: Flows provide a centralized place to define and manage tools that are available to agents throughout the workflow. Tools can be functions or callable objects that agents can use to perform specific actions or computations.
16+
17+
- **Context Sharing**: Flows maintain a consistent context across tasks and agents, allowing for seamless sharing of information and state throughout the workflow. The flow's context can be accessed and modified by tasks and agents, enabling dynamic and adaptive behavior.
18+
19+
## Creating a Flow
20+
21+
To create a flow, you can use the `@flow` decorator on a Python function. The decorated function becomes the entry point for the AI-powered workflow.
22+
23+
```python
24+
from controlflow import flow
25+
26+
@flow
27+
def my_flow():
28+
# Define tasks, agents, and tools here
29+
...
30+
```
31+
32+
Alternatively, you can create a flow object directly using the `Flow` class:
33+
34+
```python
35+
from controlflow import Flow
36+
37+
flow = Flow()
38+
```
39+
40+
## Flow Properties
41+
42+
Flows have several key properties that define their behavior and capabilities:
43+
44+
- `thread` (Thread): The thread associated with the flow, which stores the conversation history and context.
45+
- `tools` (list[AssistantTool | Callable]): A list of tools that are available to all agents in the flow.
46+
- `agents` (list[Agent]): The default agents for the flow, which are used for tasks that do not specify agents explicitly.
47+
- `context` (dict): Additional context or information that is shared across tasks and agents in the flow.
48+
49+
## Running a Flow
50+
51+
To run a flow, you can simply call the decorated function:
52+
53+
```python
54+
@flow
55+
def my_flow():
56+
# Define tasks, agents, and tools here
57+
...
58+
59+
my_flow()
60+
```
61+
62+
When a flow is run, it executes the defined tasks, assigning agents and tools as needed. The flow manages the context across agents.
63+
64+
## Conclusion
65+
66+
Flows are a fundamental concept in the ControlFlow framework, providing a structured and flexible way to define, organize, and execute AI-powered workflows. By encapsulating tasks, agents, tools, and context within a flow, developers can create complex and dynamic applications that leverage the power of AI while maintaining a clear and maintainable structure.
67+
68+
Flows abstract away the low-level details of agent coordination and communication, allowing developers to focus on defining the desired outcomes and objectives of their workflows. With the `@flow` decorator and the `Flow` class, creating and running AI-powered workflows becomes a straightforward and intuitive process.

‎docs/concepts/tasks.md renamed to ‎mintlify/concepts/tasks.mdx

File renamed without changes.

‎mintlify/favicon.jpeg

6.97 KB
Loading

‎mintlify/installation.mdx

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Requirements
2+
3+
ControlFlow requires Python 3.9 or greater, as well as Prefect 3.0.
4+
5+
## Installation
6+
7+
Install ControlFlow with your preferred package manager:
8+
<CodeGroup>
9+
10+
```bash pip
11+
pip install controlflow
12+
```
13+
14+
```bash uv
15+
uv pip install controlflow
16+
```
17+
</CodeGroup>
18+
19+
ControlFlow is under active development, so we recommend frequently updating to the latest version to access new features and bug fixes. To upgrade, pass the `-U` flag when installing.
20+
21+
22+
### Install for development
23+
24+
To install ControlFlow for development, clone the repository and create an editable install with development dependencies:
25+
26+
```bash
27+
git clone https://github.com/jlowin/controlflow.git
28+
cd controlflow
29+
pip install -e ".[dev]"
30+
```
31+
32+
## Next steps
33+
34+
Check out the [quickstart](/quickstart) guide for a step-by-step walkthrough of creating your first ControlFlow workflow.
35+

‎mintlify/introduction.mdx

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Why ControlFlow?
3+
---
4+
5+
**ControlFlow is a framework for building agentic LLM workflows.**
6+
<Tip>
7+
An **agentic workflow** is a process that delegates at least some of its work to an LLM agent. An agent is an autonomous entity that is invoked repeatedly to make decisions and perform complex tasks.
8+
</Tip>
9+
10+
LLMs are powerful AI models that can understand and generate human-like text, enabling them to perform a wide range of tasks. However, building applications with LLMs can be challenging due to their complexity, unpredictability, and potential for hallucinating or generating irrelevant outputs.
11+
12+
ControlFlow provides a structured and intuitive way to create sophisticated agentic workflows while adhereing to traditional software engineering best practices. The resulting applications are observable, controllable, and easy to trust.
13+
14+
15+
16+
## Design principles
17+
ControlFlow's design is informed by a strong opinion: LLMs are powerful tools, but they are most effective when applied to small, well-defined tasks within a structured workflow. This approach mitigates many of the challenges associated with LLMs, such as hallucinations, biases, and unpredictable behavior, while also making it easier to debug, monitor, and control the application.
18+
19+
This belief leads to three core design principles that underpin ControlFlow's architecture:
20+
21+
### 🛠️ Specialized over generalized
22+
ControlFlow advocates for the use of **specialized, single-purpose LLMs** rather than monolithic models that try to do everything. By assigning specific tasks to purpose-built models, ControlFlow ensures that the right tool is used for each job, leading to more efficient, cost-effective, and higher-quality results.
23+
24+
### 🎯 Outcome over process
25+
ControlFlow embraces a **declarative approach to defining AI workflows**, allowing developers to focus on the desired outcomes rather than the intricacies of steering LLM behavior. By specifying tasks and their requirements using intuitive constructs, developers can express what needs to be done without worrying about the details of how it will be accomplished.
26+
27+
### 🎛️ Control over autonomy
28+
ControlFlow recognizes the importance of balancing AI capabilities with traditional software development practices. Instead of relying on end-to-end AI systems that make all workflow decisions autonomously, ControlFlow allows as much or as little AI participation as needed, ensuring that developers **maintain visibility and control** over their applications.
29+
30+
31+
32+
## Key features
33+
The three design principles of ControlFlow lead to a number of key features that make it a powerful tool for building AI-powered applications:
34+
35+
### 🧩 Task-centric architecture
36+
ControlFlow breaks down AI workflows into discrete, self-contained tasks, each with a specific objective and set of requirements. This declarative, modular approach lets developers focus on the high-level logic of their applications while allowing the framework to manage the details of coordinating agents and data flow between tasks.
37+
38+
### 🕵️ Agent orchestration
39+
ControlFlow's runtime engine handles the orchestration of specialized AI agents, assigning tasks to the most appropriate models and managing the flow of data between them. This orchestration layer abstracts away the complexities of coordinating multiple AI components, allowing developers to focus on the high-level logic of their applications.
40+
41+
### 🔍 Native debugging and observability
42+
ControlFlow prioritizes transparency and ease of debugging by providing native tools for monitoring and inspecting the execution of AI tasks. Developers can easily track the progress of their workflows, identify bottlenecks or issues, and gain insights into the behavior of individual agents, ensuring that their AI applications are functioning as intended.
43+
44+
### 🤝 Seamless integration
45+
ControlFlow is designed to integrate seamlessly with existing Python codebases, treating AI tasks as first-class citizens in the application logic. The `Task` class provides a clean interface for defining the inputs, outputs, and requirements of each task, making it easy to incorporate AI capabilities into traditional software workflows. This seamless integration allows for a gradual and controlled adoption of AI, reducing the risk and complexity of introducing AI into existing systems.
46+
47+
Together, these features make ControlFlow a powerful and flexible framework for building AI-powered applications that are transparent, maintainable, and aligned with software engineering best practices.
48+
49+
50+
51+
## Why not "super-agents"?
52+
53+
Many agentic LLM frameworks rely on monolithic "super-agents": powerful, unconstrained models that are expected to achieve their goals by autonomously handling a wide range of tasks, tools, and behaviors. The resulting workflows are opaque, unpredictable, and difficult to debug.
54+
55+
This approach naively assumes that the technology is more advanced than it actually is. LLMs feel like magic because they can perform a wide variety of non-algorithmic tasks, but they are still fundamentally limited when it comes to generalizing beyond their traning data and techniques. Moreover, the failure modes of agentic LLMs are difficult to identify, let alone fix, making them difficult to trust in production environments or with mission-critical tasks.
56+
57+
In contrast to these "super-agent" approaches, ControlFlow promotes a modular, decoupled architecture where specialized agents are orchestrated to perform well-defined tasks, after which traditional software regains control of the application. This approach results in workflows that are more transparent, controllable, and debuggable, setting ControlFlow apart from other frameworks.
58+

‎mintlify/logo/logo.jpeg

6.97 KB
Loading

‎mintlify/mint.json

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"$schema": "https://mintlify.com/schema.json",
3+
"anchors": [
4+
{
5+
"icon": "book-open-cover",
6+
"name": "Documentation",
7+
"url": "https://mintlify.com/docs"
8+
},
9+
{
10+
"icon": "slack",
11+
"name": "Community",
12+
"url": "https://mintlify.com/community"
13+
},
14+
{
15+
"icon": "newspaper",
16+
"name": "Blog",
17+
"url": "https://mintlify.com/blog"
18+
}
19+
],
20+
"colors": {
21+
"anchors": {
22+
"from": "#0D9373",
23+
"to": "#07C983"
24+
},
25+
"dark": "#0D9373",
26+
"light": "#07C983",
27+
"primary": "#0D9373"
28+
},
29+
"favicon": "/favicon.jpeg",
30+
"footerSocials": {
31+
"github": "https://github.com/mintlify",
32+
"linkedin": "https://www.linkedin.com/company/mintsearch",
33+
"x": "https://x.com/mintlify"
34+
},
35+
"logo": {
36+
"dark": "/logo/logo.svg",
37+
"light": "/logo/logo.svg"
38+
},
39+
"name": "ControlFlow",
40+
"navigation": [
41+
{
42+
"group": "Get Started",
43+
"pages": [
44+
"introduction",
45+
"concepts",
46+
"installation",
47+
"quickstart"
48+
]
49+
},
50+
{
51+
"group": "Concepts",
52+
"pages": [
53+
"concepts/tasks",
54+
"concepts/flows"
55+
]
56+
}
57+
],
58+
"tabs": [
59+
{
60+
"name": "API Reference",
61+
"url": "api-reference"
62+
}
63+
],
64+
"topbarCtaButton": {
65+
"name": "Dashboard",
66+
"url": "https://dashboard.mintlify.com"
67+
},
68+
"topbarLinks": [
69+
{
70+
"name": "Support",
71+
"url": "mailto:hi@mintlify.com"
72+
}
73+
]
74+
}

‎mintlify/quickstart.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# TODO

‎mkdocs.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ theme:
1111
features:
1212
- navigation.instant
1313
- navigation.instant.progress
14-
- navigation.tabs
14+
# - navigation.tabs
1515
- navigation.tracking
16-
# - navigation.sections
16+
- navigation.sections
1717
- search.suggest
1818
- search.highlight
1919
# - toc.integrate

0 commit comments

Comments
 (0)