Merge pull request #29 from jlowin/glossary

Add glossary

docs/guides/best_practices.md

@@ -3,6 +3,9 @@
 ## Designing workflows
 - Break down sequences into discrete tasks, even if they could be sent as a single prompt to an LLM. This forces the LLM to output intermediate results, which enhance the quality of the final output. This is akin to implementing "chain of thoughts" or similar techniques, but in a more controllable way.
 - Use the task objective to describe the desired output; use task instructions to provide context and constraints. This helps the LLM understand the goal and the constraints it should adhere to.
+- If your workflow will be provided to another agent as a tool, make sure to run it in a separate flow. Otherwise, it will attempt to interact with the main thread, which is locked by the calling agent.
+
+## Designing tasks
 
 ## Agents
 - An agent's `name` and `description` are visible to all other agents; its `instructions` are private and only visible to itself.

mintlify/glossary/agentic-workflow.mdx

@@ -0,0 +1,7 @@
+Agentic workflows refer to the use of large language models (LLMs) as autonomous agents capable of performing tasks independently by making decisions, retrieving information, and interacting with external systems. This approach leverages the model's ability to understand context, reason, and execute actions without continuous human intervention.
+
+In agentic workflows, the LLM is designed to act as an intelligent agent that can initiate and manage processes. For example, it can autonomously handle tasks such as scheduling meetings, processing customer queries, or even conducting research by interacting with APIs and databases. The model uses contextual understanding to navigate these tasks, making decisions based on the information it processes in real-time.
+
+Unlike [prompt engineering](/glossary/prompt-engineering), which relies on a single prompt to guide the model's response, and [flow engineering](/glossary/flow-engineering), which involves a structured, multi-step refinement process, agentic workflows emphasize the model's ability to operate independently over extended periods. This autonomy allows the model to adapt to dynamic environments and make real-time adjustments based on the evolving context of the task.
+
+Agentic workflows are particularly useful in scenarios requiring continuous operation and decision-making, such as virtual assistants, automated customer service, and dynamic content generation. By empowering LLMs to function autonomously, agentic workflows expand the potential applications of AI, enabling more sophisticated and efficient interactions between humans and machines.

mintlify/glossary/flow-engineering.mdx

@@ -0,0 +1,7 @@
+Flow engineering in the context of large language models (LLMs) is a methodology designed to optimize how these models handle tasks by implementing a structured, multi-step process. Unlike [prompt engineering](/glossary/prompt-engineering), which relies on crafting a precise single prompt to elicit a desired response, flow engineering involves breaking down the problem into smaller components and generating diverse test cases to cover various scenarios. This allows for a thorough analysis and a more comprehensive approach to problem-solving.
+
+The iterative refinement process in flow engineering sets it apart. The model generates initial solutions, tests them against predefined cases, identifies errors, and makes necessary adjustments. This loop continues until the model produces a robust solution. This method ensures higher accuracy and reliability, especially for complex tasks like code generation, where multiple iterations and refinements are crucial.
+
+In contrast, prompt engineering focuses on finding the right input to achieve the desired output in a single step. While effective for simpler tasks, it often falls short in handling nuanced and complex scenarios that benefit from an iterative process. Prompt engineering's reliance on one-off prompts can lead to limitations in producing high-quality results for intricate problems.
+
+Flow engineering also contrasts with [agentic workflows](/glossary/agentic-workflows), where models operate as autonomous agents capable of making decisions and performing actions independently. While agentic workflows excel in dynamic decision-making and real-time interactions, flow engineering is ideal for tasks that require meticulous, step-by-step refinement. By combining the strengths of iterative refinement from flow engineering with the precision of prompt engineering and the autonomy of agentic workflows, developers can harness the full potential of LLMs across a wide range of applications.

mintlify/glossary/flow-orchestration.mdx

@@ -0,0 +1,8 @@
+---
+title: Flow (Orchestration)
+---
+
+<Info>
+This glossary entry is about the term "flow" in the context of workflow orchestration. For ControlFlow flows specifically, see the [Flow](/glossary/flow) entry.
+
+</Info>

mintlify/glossary/flow.mdx

@@ -0,0 +1,2 @@
+
+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. 

mintlify/glossary/glossary.mdx

@@ -0,0 +1,4 @@
+---
+title: Welcome
+---
+Welcome to the ControlFlow Glossary! This glossary provides definitions and explanations for key concepts in ControlFlow, as well as related topics in modern AI. Whether you're new to ControlFlow or looking to deepen your understanding, this resource is designed to help you navigate the terminology and concepts that are essential for working with LLMS and AI workflows.

mintlify/glossary/prompt-engineering.mdx

@@ -0,0 +1,5 @@
+Prompt engineering is the practice of crafting precise and effective input prompts to elicit desired responses from large language models (LLMs). This method focuses on designing the exact wording, structure, and context of the prompt to guide the model towards generating specific outputs. It requires an understanding of the model’s capabilities and the nuances of language to maximize the quality and relevance of the responses.
+
+Unlike [flow engineering](/glossary/flow-engineering), which involves a multi-step, iterative process to refine outputs, prompt engineering aims to achieve the desired result with a single, well-constructed input. This approach is particularly useful for straightforward tasks where the model's initial response is expected to be accurate and sufficient. However, it can be limited in handling complex problems that require deeper analysis and iterative refinement.
+
+Prompt engineering is essential in scenarios where quick, efficient responses are needed, and the task complexity is manageable with a single input. It is a critical skill for developers and users who interact with LLMs, enabling them to harness the model's full potential by providing clear and concise prompts that lead to high-quality outputs.

mintlify/glossary/task-orchestration.mdx

@@ -0,0 +1,8 @@
+---
+title: Task (Orchestration)
+---
+
+<Info>
+This glossary entry is about the term "task" in the context of workflow orchestration. For ControlFlow tasks specifically, see the [Task](/glossary/task) entry.
+
+</Info>

mintlify/glossary/task.mdx

@@ -0,0 +1,9 @@
+
+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. 
+
+Tasks can depend on each other in various ways, creating complex workflows that are easy to understand and manage:
+- **sequential** dependencies: one task must be completed before another can start
+- **context** dependencies: the result of one task is used as input for another
+- **subtask** dependencies: a task has subtasks that must be completed before the task can be considered done
+
+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.

mintlify/glossary/workflow.mdx

@@ -0,0 +1,5 @@
+A workflow is a sequence of interconnected tasks or steps that represent a specific business process or operation. In the context of orchestration, a workflow defines the order and dependencies of these tasks, ensuring that they are executed in a coordinated and efficient manner.
+
+Workflows are commonly used in complex systems to automate and streamline processes, such as data processing, application deployment, or service orchestration. They provide a high-level view of the entire process, allowing developers and operators to define, manage, and monitor the execution of tasks.
+
+In an orchestration system, a workflow typically consists of multiple activities, each representing a specific task or operation. These activities can be executed sequentially, in parallel, or based on certain conditions, enabling the system to handle complex scenarios and adapt to changing requirements.

mintlify/mint.json

@@ -10,11 +10,6 @@
             "icon": "slack",
             "name": "Community",
             "url": "https://mintlify.com/community"
-        },
-        {
-            "icon": "newspaper",
-            "name": "Blog",
-            "url": "https://mintlify.com/blog"
         }
     ],
     "colors": {
@@ -53,17 +48,50 @@
                 "concepts/tasks",
                 "concepts/flows"
             ]
+        },
+        {
+            "group": "Overview",
+            "pages": [
+                "glossary/glossary"
+            ]
+        },
+        {
+            "group": "LLMs",
+            "pages": [
+                "glossary/prompt-engineering",
+                "glossary/flow-engineering",
+                "glossary/agentic-workflow"
+            ]
+        },
+        {
+            "group": "ControlFlow",
+            "pages": [
+                "glossary/task",
+                "glossary/flow"
+            ]
+        },
+        {
+            "group": "Orchestration",
+            "pages": [
+                "glossary/task-orchestration",
+                "glossary/flow-orchestration",
+                "glossary/workflow"
+            ]
         }
     ],
     "tabs": [
         {
             "name": "API Reference",
             "url": "api-reference"
+        },
+        {
+            "name": "Glossary",
+            "url": "glossary"
         }
     ],
     "topbarCtaButton": {
-        "name": "Dashboard",
-        "url": "https://dashboard.mintlify.com"
+        "type": "github",
+        "url": "https://github.com/jlowin/controlflow"
     },
     "topbarLinks": [
         {

src/controlflow/core/controller/instruction_template.py

@@ -73,8 +73,10 @@ class TasksTemplate(Template):
         instruction will not update until your next turn; refer to the results
         of task-related tools to see the latest task status at any time.
         
-        {% for task in tasks %} #### Task {{ task.id }} {{
-        task.model_dump_json() }}
+        {% for task in tasks %} 
+        #### Task {{ task.id }} 
+        
+        {{task.model_dump_json() }}
         
         {% endfor %}
 
@@ -98,7 +100,7 @@ class TasksTemplate(Template):
         
         You can only mark a task successful when all of its dependencies and
         subtasks have been completed. Subtasks may be marked as skipped without
-        providing a result.
+        providing a result. All else equal, prioritize older tasks over newer ones.
 
         ### Providing a result