# microsoft/timecraft architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack research framework (“TimeCraft”) for synthetic time-series generation, combining three complementary modules:
a. TimeDP (cross-domain diffusion with prototype prompts)
b. BRIDGE (text-based control via multi-agent LLM pipelines)
c. TarDiff (target-aware diffusion guided by downstream model gradients)
- It also contains related baseline code (DiGA, diffusion) and data/processing utilities.

##### High-Level Architecture
At the highest level, TimeCraft accepts up to three inputs—few-shot time series examples, free-form text prompts, downstream task model & data—and produces synthetic time series via a unified diffusion engine enhanced by:
- Prototype Assignment Module (PAM) for cross-domain prompts
- Multi-Agent Text System (BRIDGE) for text descriptions
- Influence-Guidance Module (TarDiff) for task-aware adaptation

##### Main Components
A. Data Ingestion & Preprocessing
- Scripts: TimeDP/utils/prepare_datasets.py, process/*, TarDiff/data_preprocess/*
- Actions: download raw datasets → cleaning/concatenation → sliding-window segmentation → .npy/.csv outputs

B. Prototype Learning & Assignment (TimeDP)
- Modules: TimeDP/ldm/models, TimeDP/ldm/modules, TimeDP/main_train.py
- Role: learn a shared “prototype dictionary” of temporal patterns; at inference, PAM uses few-shot examples to compute domain prompts

C. Diffusion Backbone
- Modules: TimeDP/ldm, TarDiff/ldm (variants), diffusion/ldm
- Role: core denoising steps; configurable via YAML (e.g., diffusion/configs, TimeDP/configs)

D. Text-Control Subsystem (BRIDGE)
- Modules: BRIDGE/llm_agents (agent orchestration, LLM calls), BRIDGE/self_refine (iterative feedback), template_extractor.py, ts_to_text.py
- Role: generate high-quality text descriptions of time series → hybrid prompt fed into diffusion cross-attention

E. Target-Aware Guidance (TarDiff)
- Modules: TarDiff/classifier (downstream model), TarDiff/guidance_generation.py, TarDiff/train_main.py
- Role: compute gradients of downstream loss → inject into each denoising step via Guidance Module

F. Training & Orchestration
- Entrypoints: main.py (umbrella trainer), TimeDP/main_train.py, TarDiff/train_main.py, diffusion/main.py, DiGA/train.py
- Configs: environment.yml, multiple .yaml under configs/

G. Inference & Visualization
- Inputs: domain prompts, text prompts, guidance set & downstream model
- Outputs: synthetic series, evaluation metrics, visualizations

##### Component Interactions & Data Flow
1. Raw data → Preprocessing → segmented series files
2. For prototype branch: preprocessed series → prototype learner → prototype dictionary
3. Few-shot examples → PAM → domain prompt
4. For text branch: segmented series → ts_to_text → multi-agent LLM pipelines → text descriptions → hybrid prompt
5. Downstream branch: preprocessed series + labels → train downstream model → gradients during inference
6. Inference pipeline: (prototype prompt, text prompt, guidance gradients) → diffusion backbone → synthetic time series
7. Post-process & evaluate with metrics modules (TimeDP/utils, TarDiff/utils)

##### Architectural Patterns & Design Principles
- Modular monorepo: each major capability isolated under its own top-level folder
- Plugin-style YAML configs for reproducibility and easy extension
- Separation of concerns: data prep, model training, inference, evaluation, visualization
- Hybrid conditioning: cross-attention for text & prototypes + gradient steering for tasks

##### Technologies & Frameworks
- Python 3.x, Conda environment (environment.yml)
- PyTorch (diffusion models, classifiers, RNNs)
- HuggingFace-style LLM wrappers (BRIDGE/llm_agents/tools)
- YAML for configuration, shell scripts for quick runs (`*.sh`)
- External services: Zenodo data downloads, web search tools for BRIDGE

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% External Data Sources
    subgraph "External Data & Services"
        direction TB
        Zenodo["Zenodo (Raw Data)"]:::external
        MIMIC["MIMIC-III (Raw Data)"]:::external
        LLMAPI["LLM APIs"]:::external
    end

    %% Preprocessing
    subgraph "Data Ingestion & Preprocessing" 
        direction TB
        Raw["Raw Data"]:::external
        Preprocess["Preprocessing\n(process/, TarDiff/data_preprocess/, TimeDP/utils/prepare_datasets.py)"]:::data
    end

    Zenodo --> Raw
    MIMIC --> Raw
    Raw --> Preprocess
    click Preprocess "https://github.com/microsoft/timecraft/tree/main/process/"
    click Preprocess "https://github.com/microsoft/timecraft/tree/main/TarDiff/data_preprocess/"
    click Preprocess "https://github.com/microsoft/timecraft/blob/main/TimeDP/utils/prepare_datasets.py"

    %% Prototype Lane
    subgraph "Prototype (TimeDP)"
        direction TB
        SegSeries["Segmented Series"]:::data
        PrototypeLearner["Prototype Learning\n(TimeDP/ldm/models/, TimeDP/ldm/modules/, TimeDP/main_train.py)"]:::model
        PAM["Prototype Assignment Module\n(PAM computes domain prompt)"]:::model
    end

    Preprocess --> SegSeries
    SegSeries --> PrototypeLearner
    PrototypeLearner --> PAM
    click PrototypeLearner "https://github.com/microsoft/timecraft/blob/main/TimeDP/ldm/models/autoencoder.py"
    click PrototypeLearner "https://github.com/microsoft/timecraft/blob/main/TimeDP/ldm/models/ddim_time.py"
    click PrototypeLearner "https://github.com/microsoft/timecraft/blob/main/TimeDP/ldm/models/ddpm_time.py"
    click PrototypeLearner "https://github.com/microsoft/timecraft/blob/main/TimeDP/ldm/modules/attention.py"
    click PrototypeLearner "https://github.com/microsoft/timecraft/blob/main/TimeDP/main_train.py"

    %% Text Lane
    subgraph "Text (BRIDGE)"
        direction TB
        TS2Text["ts_to_text\n(BRIDGE/ts_to_text.py)"]:::data
        MultiAgent["Multi-Agent LLM System\n(BRIDGE/llm_agents/, BRIDGE/self_refine/)"]:::text
        TemplateExt["Template Extractor\n(BRIDGE/template_extractor.py)"]:::text
    end

    SegSeries --> TS2Text
    TS2Text --> MultiAgent
    MultiAgent --> TemplateExt
    click TS2Text "https://github.com/microsoft/timecraft/blob/main/BRIDGE/ts_to_text.py"
    click MultiAgent "https://github.com/microsoft/timecraft/blob/main/BRIDGE/llm_agents/agent.py"
    click MultiAgent "https://github.com/microsoft/timecraft/blob/main/BRIDGE/self_refine_main.py"
    click TemplateExt "https://github.com/microsoft/timecraft/blob/main/BRIDGE/template_extractor.py"

    %% Task-Aware Lane
    subgraph "Task-Aware (TarDiff)"
        direction TB
        PretrainedModel["Downstream Model Training\n(TarDiff/classifier/)"]:::model
        GuidanceGen["Guidance Generation\n(TarDiff/guidance_generation.py)"]:::guidance
    end

    Preprocess --> PretrainedModel
    PretrainedModel --> GuidanceGen
    click PretrainedModel "https://github.com/microsoft/timecraft/blob/main/TarDiff/classifier/model.py"
    click GuidanceGen "https://github.com/microsoft/timecraft/blob/main/TarDiff/guidance_generation.py"

    %% Shared Diffusion Engine
    subgraph "Diffusion Engine" 
        direction TB
        DiffBackbone["Core Denoising Steps\n(diffusion/ldm/, TimeDP/ldm/, TarDiff/ldm/)"]:::model
        Configs["YAML Configs"]:::external
    end

    PAM --> DiffBackbone
    TemplateExt --> DiffBackbone
    GuidanceGen --> DiffBackbone
    click DiffBackbone "https://github.com/microsoft/timecraft/blob/main/diffusion/ldm/data/tsg_dataset.py"
    click DiffBackbone "https://github.com/microsoft/timecraft/blob/main/TarDiff/ldm/data/tsg_dataset.py"

    %% Inference & Visualization
    subgraph "Inference & Visualization"
        direction TB
        Inference["Inference Pipeline\n(inference.py, diffusion/inference.py)"]:::model
        Visualize["Visualization\n(TimeDP/visualize.py, diffusion/visualize.py)"]:::model
    end

    DiffBackbone --> Inference
    Inference --> Visualize
    click Inference "https://github.com/microsoft/timecraft/blob/main/inference.py"
    click Inference "https://github.com/microsoft/timecraft/blob/main/diffusion/inference.py"
    click Visualize "https://github.com/microsoft/timecraft/blob/main/TimeDP/visualize.py"

    %% Training & Orchestration
    subgraph "Training & Orchestration"
        direction TB
        Umbrella["Umbrella Trainer\n(main.py)"]:::external
        DiffTrain["Diffusion Train\n(diffusion/main.py)"]:::external
        TimeDPTrain["TimeDP Train\n(TimeDP/main_train.py)"]:::external
        TarDiffTrain["TarDiff Train\n(TarDiff/train_main.py)"]:::external
        DiGATrain["DiGA Train & Gen\n(DiGA/train.py, DiGA/generate.py)"]:::external
    end

    Umbrella --> DiffTrain
    Umbrella --> TimeDPTrain
    Umbrella --> TarDiffTrain
    Umbrella --> DiGATrain
    click Umbrella "https://github.com/microsoft/timecraft/blob/main/main.py"
    click DiffTrain "https://github.com/microsoft/timecraft/blob/main/diffusion/main.py"
    click TimeDPTrain "https://github.com/microsoft/timecraft/blob/main/TimeDP/main_train.py"
    click TarDiffTrain "https://github.com/microsoft/timecraft/blob/main/TarDiff/train_main.py"
    click DiGATrain "https://github.com/microsoft/timecraft/blob/main/DiGA/train.py"

    %% Outputs
    subgraph "Outputs"
        direction TB
        Synthetic["Synthetic Time Series"]:::data
        Metrics["Evaluation Metrics"]:::external
    end

    VisualizationEnd[Visualize] --> Synthetic
    VisualizationEnd --> Metrics

    %% Styles
    classDef data fill:#add8e6,stroke:#000,stroke-width:1px
    classDef model fill:#90ee90,stroke:#000,stroke-width:1px
    classDef text fill:#ffa500,stroke:#000,stroke-width:1px
    classDef guidance fill:#f08080,stroke:#000,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
```
