# microsoft/taskweaver architecture

> Architecture diagram of the GitHub repository microsoft/taskweaver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/taskweaver
- Repository: https://github.com/microsoft/taskweaver

## Overview

##### Project Type and Purpose
- TaskWeaver is a code-first agent framework that uses natural language and code snippets to plan and execute complex data analytics tasks. It is designed to preserve both chat and code execution histories, interfaces with various plugins (e.g., for anomaly detection, forecasting, etc.), and is integrated with multiple LLMs.
- The framework supports both CLI and web UI interactions and leverages containerized code execution. Its design shows a focus on stateful execution, planning, reflection on execution, and easy extension through plugins.

##### Main Components to Highlight
- Core Engine (TaskWeaver Library):
- The core functionalities reside in the “taskweaver” directory. Illustrate subcomponents for executing and planning:
- App & Session management (taskweaver/app/)
- Code interpreter components (taskweaver/code_interpreter/)
- Planner (taskweaver/planner/)
- Plugins handling (taskweaver/plugin/ and project/plugins/)
- Memory/State management (taskweaver/memory/)
- LLM integration (taskweaver/llm/)
- Role and external role definitions (taskweaver/role/ & taskweaver/ext_role/)
- Configuration management (taskweaver/config/)

- Plugin System:
- How plugins enable domain-specific functionalities (anomaly detection, SQL pulling, etc.) and are invoked by the engine.

- External Interfaces:
- CLI Interface (taskweaver/cli/) and Chat UI (taskweaver/chat/console/ and playground/UI).
- Integration with web UIs via the “playground” and “website” directories.
- Container integration (see “docker” folder) that supports “container” mode for code execution.

- Containerization and Deployment:
- Docker-based container modules (docker/all_in_one_container, docker/ces_container).
- That containerization is used for secure and isolated code execution.

- Testing & Evaluation:
- Test suite (tests/unit_tests/), which validates various aspects such as session, plugins, and code generation.

- Auto Evaluation Framework:
- “auto_eval” directory, which contains cases for evaluating features (e.g., anomaly detection, plugin selection, code execution in container, etc.) and scripts for da benchmark / ds1000 evaluations.

##### Relationships and Interactions
- Core Flow:
- The “taskweaver” core receives a user’s request (via CLI, WebUI, or library import) and passes it through a planning stage (taskweaver/planner) before delegating specific analytic tasks to various plugins.
- LLM integration (llm/) as a service that powers planning, code generation, and verification.
- Data flows where:
- The session manager preserves chat and code execution history.
- LLM outputs pass to the code interpreter, invoking plugins.
- Code and results are stored and possibly passed back to a session component.

- Plugin Communication:
- How plugins get invoked (information flow from prompts to plugin code, then return data such as DataFrames or files).

- Container Execution:
- A path that shows code being executed in containerized environments. For example, container calls (docker) are triggered by the core executor.

- External Interactions:
- Different modules (CLI, web UI, external LLM APIs) interact with the core logic.
- Database access and other external services are orchestrated via plugins (like the “sql_pull_data” plugin example).

##### Architectural Patterns and Principles
- Separation of concerns: The core framework is modularized into task management, memory management, LLM integration, and plugin orchestration.
- Leverage a plug-in architecture to allow extensibility and easy addition of new functionality.
- A microservice-like containerized execution for isolation and security.
- Stateful execution and persistence of both conversation and code execution history for enhanced operations such as reflective execution.

## Diagram (Mermaid)

```mermaid
graph TD
  %% User Interface Layer
  subgraph "User Interface Layer"
    cliUI["CLI Interface"]:::ui
    chatUI["Chat UI Interface"]:::ui
  end

  %% Application Core Layer
  subgraph "Application Core Layer"
    subgraph "App & Session Management"
      SessionManager["Session Manager"]:::core
      SessionStore["Session Store"]:::core
      SessionManager --> SessionStore
    end

    subgraph "Code Execution Pipeline"
      CodeExecutor["Code Executor"]:::core
      Interpreter["Interpreter"]:::core
      CodeExecutor --> Interpreter
    end

    Planner["Planner"]:::core
    LLMIntegration["LLM Integration"]:::core
    MemoryManager["Memory Manager"]:::core
    ConfigManager["Configuration Manager"]:::core
    InternalRoles["Internal Role Definitions"]:::core
    ExternalRoles["External Role Definitions"]:::core
  end

  %% Plugin & External Services Layer
  subgraph "Plugin & External Services Layer"
    EnginePlugins["Engine Plugin Manager"]:::plugin
    ExternalPlugins["External Plugin Manager"]:::plugin
  end

  %% Infrastructure Layer
  subgraph "Infrastructure Layer"
    AllInOne["All-In-One Container"]:::infra
    CESContainer["CES Container"]:::infra
    TestingSuite["Test Suite"]:::infra
    AutoEval["Auto Evaluation Framework"]:::infra
  end

  %% Data Flow Connections
  cliUI -->|"sends request"| SessionManager
  chatUI -->|"sends request"| SessionManager
  SessionManager -->|"initiates"| Planner
  Planner -->|"uses"| LLMIntegration
  LLMIntegration -->|"generates"| Interpreter
  Interpreter -->|"executes code"| EnginePlugins
  Planner -->|"selects plugins"| EnginePlugins
  EnginePlugins -->|"delegates tasks"| ExternalPlugins
  ExternalPlugins -->|"returns data"| MemoryManager
  MemoryManager -->|"updates state"| SessionManager
  CodeExecutor -->|"runs in"| AllInOne
  CodeExecutor -->|"runs in"| CESContainer
  Interpreter -->|"saves results"| MemoryManager
  ConfigManager -->|"configures"| Planner
  InternalRoles -->|"defines roles for"| Planner
  ExternalRoles -->|"defines roles for"| Planner

  %% Class Definitions
  classDef ui fill:#AEDFF7,stroke:#333,stroke-width:2px;
  classDef core fill:#C3F7C3,stroke:#333,stroke-width:2px;
  classDef plugin fill:#FFFFCC,stroke:#333,stroke-width:2px;
  classDef infra fill:#E5E5E5,stroke:#333,stroke-width:2px;

  %% Click Events
  click cliUI "https://github.com/microsoft/taskweaver/tree/main/taskweaver/cli"
  click chatUI "https://github.com/microsoft/taskweaver/tree/main/taskweaver/chat/console"
  click SessionManager "https://github.com/microsoft/taskweaver/blob/main/taskweaver/app/session_manager.py"
  click SessionStore "https://github.com/microsoft/taskweaver/blob/main/taskweaver/app/session_store.py"
  click CodeExecutor "https://github.com/microsoft/taskweaver/blob/main/taskweaver/code_interpreter/code_executor.py"
  click Interpreter "https://github.com/microsoft/taskweaver/blob/main/taskweaver/code_interpreter/interpreter.py"
  click Planner "https://github.com/microsoft/taskweaver/blob/main/taskweaver/planner/planner.py"
  click EnginePlugins "https://github.com/microsoft/taskweaver/tree/main/taskweaver/plugin"
  click ExternalPlugins "https://github.com/microsoft/taskweaver/tree/main/project/plugins"
  click MemoryManager "https://github.com/microsoft/taskweaver/tree/main/taskweaver/memory"
  click LLMIntegration "https://github.com/microsoft/taskweaver/tree/main/taskweaver/llm"
  click InternalRoles "https://github.com/microsoft/taskweaver/tree/main/taskweaver/role"
  click ExternalRoles "https://github.com/microsoft/taskweaver/tree/main/taskweaver/ext_role"
  click ConfigManager "https://github.com/microsoft/taskweaver/tree/main/taskweaver/config"
  click AllInOne "https://github.com/microsoft/taskweaver/tree/main/docker/all_in_one_container"
  click CESContainer "https://github.com/microsoft/taskweaver/tree/main/docker/ces_container"
  click TestingSuite "https://github.com/microsoft/taskweaver/tree/main/tests/unit_tests"
  click AutoEval "https://github.com/microsoft/taskweaver/tree/main/auto_eval"
```
