TaskWeaver

Converts natural language user requests into executable Python code plans through a Planner role that decomposes complex tasks into sub-steps. The Planner uses LLM prompts (defined in planner_prompt.yaml) to generate structured code snippets rather than text-based plans, enabling direct execution of analytics workflows. This approach preserves both chat history and code execution history, including in-memory data structures like DataFrames across stateful sessions.

Executes generated Python code in an isolated interpreter environment that maintains variables, DataFrames, and other in-memory objects across multiple execution cycles within a session. The CodeInterpreter role manages a persistent Python runtime where code snippets are executed sequentially, with each execution's state (local variables, imported modules, DataFrame mutations) carried forward to subsequent code runs. This is tracked via the memory/attachment.py system that serializes execution context.

Provides observability into agent execution through event-based tracing (EventEmitter pattern) that logs planning decisions, code generation, execution results, and role interactions. Execution traces include timestamps, role attribution, and detailed logs that enable debugging of agent behavior and monitoring of production deployments. Traces can be exported for analysis and are integrated with the memory system to provide full execution history.

Provides evaluation infrastructure for assessing agent performance on benchmarks and custom test cases. The framework includes evaluation datasets, metrics, and testing utilities that enable quantitative assessment of agent capabilities. Evaluation results are tracked and can be compared across different configurations or model versions, supporting iterative improvement of agent prompts and settings.

Manages agent sessions that maintain conversation history, execution context, and state across multiple user interactions. Each session has a unique identifier and persists the full interaction history including user messages, agent responses, generated code, and execution results. Sessions can be resumed, allowing users to continue conversations from previous states. Session state includes the current execution context (variables, DataFrames) and conversation history, enabling the agent to maintain continuity across interactions.

Implements a role-based architecture where specialized agents (Planner, CodeInterpreter, External Roles like WebExplorer) communicate exclusively through a central Planner mediator. Each role is defined with specific capabilities and responsibilities, and all inter-role communication flows through the Planner to ensure coordinated task execution. Roles are configured via YAML definitions that specify their prompts, capabilities, and communication protocols, enabling extensibility without modifying core framework code.

Extends TaskWeaver's capabilities through a plugin architecture where custom algorithms, APIs, and domain-specific tools are wrapped as callable functions with YAML-defined schemas. Plugins are registered with the framework and made available to the CodeInterpreter role, which can invoke them as part of generated code. Each plugin has a YAML configuration specifying function signature, parameters, return types, and documentation, enabling the LLM to understand and call plugins correctly without hardcoding integration logic.

Manages conversation history and code execution history through an attachment-based memory system (taskweaver/memory/attachment.py) that serializes execution context including variables, DataFrames, and intermediate results. Attachments are JSON-serializable objects that capture the state of the Python interpreter after each code execution, enabling the framework to reconstruct context for subsequent planning and execution cycles. This system bridges the gap between natural language conversation history and code execution state.

Abstracts LLM provider differences through a unified interface that supports OpenAI, Anthropic, and local LLM endpoints with compatible APIs. The framework decouples LLM selection from agent logic through configuration, enabling role-specific model assignment (e.g., Planner uses GPT-4, CodeInterpreter uses GPT-3.5). LLM calls are made through a provider abstraction layer that handles API differences, token counting, and response parsing, allowing seamless model switching without code changes.

Generates Python code snippets that reference variables and libraries from previous execution context, enabling the CodeInterpreter to write code that builds on prior state without re-importing or re-computing. The code generation process (driven by the CodeInterpreter role) has access to the current execution context (available variables, imported modules, DataFrames) and generates code that leverages this context. This is achieved through prompt engineering that includes context information and validation that generated code references only available symbols.

Provides two user interfaces for interacting with TaskWeaver agents: a console-based chat interface (taskweaver/chat/console/chat.py) for terminal-based interaction and a web UI for browser-based access. Both interfaces manage session state, display execution results and code, and enable users to provide feedback or corrections. The console interface uses event-driven architecture (EventEmitter) to handle asynchronous agent responses, while the web UI provides a more polished experience with code syntax highlighting and result visualization.

Extends TaskWeaver with specialized external roles (e.g., WebExplorer for web scraping, ImageReader for image analysis) that are coordinated through the Planner. External roles are implemented as separate agents with their own LLM prompts and capabilities, communicating with the Planner through the standard message-passing protocol. This enables TaskWeaver to handle tasks beyond pure data analytics by delegating to specialized agents while maintaining the code-first execution model.

Enables framework configuration through YAML files that define roles, LLM providers, plugins, and execution parameters without requiring code changes. Configuration files specify role prompts (e.g., planner_prompt.yaml), LLM endpoints, plugin registrations, and execution settings. This declarative approach allows non-developers to customize agent behavior and enables version control of agent configurations alongside code. Configuration is validated at startup to catch errors early.