TaskWeaver

Transforms natural language user requests into executable Python code snippets through a Planner role that decomposes tasks into sub-steps. The Planner uses LLM prompts (planner_prompt.yaml) to generate structured code rather than text-only plans, maintaining awareness of available plugins and code execution history. This approach preserves both chat history and code execution state (including in-memory DataFrames) across multiple interactions, enabling stateful multi-turn task orchestration.

Implements a role-based architecture where specialized agents (Planner, CodeInterpreter, External Roles like WebExplorer) communicate exclusively through the Planner as a central hub. Each role has a specific responsibility: the Planner orchestrates, CodeInterpreter generates/executes Python code, and External Roles handle domain-specific tasks. Communication flows through a message-passing system that ensures controlled conversation flow and prevents direct agent-to-agent coupling.

Provides comprehensive logging and tracing of agent execution, including LLM prompts/responses, code generation, execution results, and inter-role communication. Tracing is implemented via an event emitter system (event_emitter.py) that captures execution events at each stage. Logs can be exported for debugging, auditing, and performance analysis. Integration with observability platforms (e.g., OpenTelemetry) is supported for production monitoring.

Externalizes agent configuration (LLM provider, plugins, roles, execution limits) into YAML files, enabling users to customize behavior without code changes. The configuration system includes validation to ensure required settings are present and correct (e.g., API keys, plugin paths). Configuration is loaded at startup and can be reloaded without restarting the agent. Supports environment variable substitution for sensitive values (API keys).

Provides tools for evaluating agent performance on benchmark tasks and testing agent behavior. The evaluation framework includes pre-built datasets (e.g., data analytics tasks) and metrics for measuring success (task completion, code correctness, execution time). Testing utilities enable unit testing of individual components (Planner, CodeInterpreter, plugins) and integration testing of full workflows. Results are aggregated and reported for comparison across LLM providers or agent configurations.

Provides utilities for parsing, validating, and manipulating JSON data throughout the agent workflow. JSON is used for inter-role communication (messages), plugin definitions, configuration, and execution results. The JSON processing layer handles serialization/deserialization of Python objects (DataFrames, custom types) to/from JSON, with support for custom encoders/decoders. Validation ensures JSON conforms to expected schemas.

The CodeInterpreter role generates executable Python code based on task requirements and executes it in an isolated runtime environment. Code generation is LLM-driven and context-aware, with access to plugin definitions that wrap custom algorithms as callable functions. The Code Execution Service sandboxes execution, captures output/errors, and returns results back to the Planner. Plugins are defined via YAML configs that specify function signatures, enabling the LLM to generate correct function calls.

Extends TaskWeaver's functionality by wrapping custom algorithms and tools into callable functions via a plugin architecture. Plugins are defined declaratively in YAML configs that specify function names, parameters, return types, and descriptions. The plugin system registers these definitions with the CodeInterpreter, enabling the LLM to generate correct function calls with proper argument passing. Plugins can wrap Python functions, external APIs, or domain-specific tools (e.g., data validation, ML model inference).

Manages session lifecycle and preserves execution state across multiple user interactions. Sessions maintain both chat history (text messages) and code execution history (generated code, results, variable state). The Session Manager handles session creation, persistence, and cleanup. Memory is implemented via an Attachment system that stores DataFrames, variables, and other Python objects in-memory, enabling subsequent code generations to reference previous results without serialization.

Abstracts LLM interactions behind a provider interface that supports multiple LLM backends (OpenAI, Anthropic, local models via Ollama, Keywords AI, etc.). The LLM Integration layer handles API calls, prompt formatting, token counting, and response parsing. Configuration is externalized (YAML), allowing users to switch LLM providers without code changes. Supports both chat-based and completion-based LLM APIs with consistent error handling and retry logic.

Provides a sandboxed runtime environment for executing generated Python code. The Code Execution Service spawns a Python kernel, executes code snippets, captures stdout/stderr, handles exceptions, and returns results. Execution is isolated from the main agent process to prevent crashes or security issues. Supports timeout limits to prevent runaway code. Results (return values, variable state) are captured and made available to subsequent code generations.

Enables integration of specialized external roles (e.g., WebExplorer for web search, ImageReader for image analysis) that handle domain-specific tasks outside the core Planner/CodeInterpreter loop. External roles communicate with the Planner via the same message-passing interface, allowing them to be composed into workflows. Each external role implements a specific capability (web search, image processing, database queries) and returns results that can be consumed by the CodeInterpreter.

Provides multiple user interfaces for interacting with TaskWeaver agents: a console CLI for terminal-based interaction and a web UI for browser-based access. Both interfaces handle session management, display chat history and code execution results, and allow users to provide feedback or corrections. The web UI includes visualization of task decomposition and execution flow. Interfaces are decoupled from the core agent logic via a session API.

The Planner decomposes complex user requests into executable sub-tasks while maintaining awareness of the execution history (previous code, results, variables). Decomposition is LLM-driven and uses prompts (planner_prompt.yaml) that include context about available plugins, previous executions, and task dependencies. The Planner generates a task plan as code, executes it via the CodeInterpreter, and iteratively refines the plan based on execution results.