Support streaming events

[jlowin]

This pull request introduces a new streaming feature to the ControlFlow library, allowing for real-time processing of events during task execution. It also includes significant updates to the documentation and several codebase improvements to support this new functionality.

import controlflow as cf

for event, snapshot, delta in cf.run("Write a poem about AI", stream=True):
    # For complete events, snapshot contains the full content
    if event.event == "agent-content":
        print(f"Agent wrote: {snapshot}")
    
    # For delta events, delta contains just what's new
    elif event.event == "agent-content-delta":
        print(delta, end="", flush=True)

To automatically filter for common event types, use the stream flags

import controlflow as cf

for event, snapshot, delta in cf.run(
    "Write a poem",
    stream=cf.Stream.CONTENT | cf.Stream.TOOLS,
):
    print(delta if delta else snapshot)

New Streaming Feature:

• docs/patterns/running-tasks.mdx: Added a new section on streaming, explaining how to enable and use the streaming feature in ControlFlow.
• docs/patterns/streaming-tasks.mdx: Created a new document detailing the streaming feature, including examples and explanations of different event types and handlers.
• src/controlflow/__init__.py: Exported the Stream class from the run module to make it available for import.

Codebase Enhancements:

• src/controlflow/agents/agent.py: Updated the run and run_async methods to support the new stream parameter, allowing tasks to be executed with streaming enabled. [1] [2]
• src/controlflow/events/events.py: Modified methods to handle optional content and content deltas, ensuring they only return events when content is present. [1] [2]

Documentation Updates:

• docs/mint.json: Added the new patterns/streaming-tasks document to the list of documentation patterns.

Event Handling Improvements:

• src/controlflow/events/orchestrator_events.py: Added orchestrator event definitions to handle the start and end of orchestration processes.
• src/controlflow/events/task_events.py: Added task event definitions to handle various task lifecycle events such as start, success, failure, and skipped.

These changes collectively enhance the ControlFlow library by introducing real-time event streaming capabilities, improving the documentation, and refining the event handling mechanisms.