# sintel-dev/sigllm architecture

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

- Interactive diagram: https://gitdiagram.com/sintel-dev/sigllm
- Repository: https://github.com/sintel-dev/sigllm

## Overview

##### Project type and purpose
- SigLLM is a Python library (an open-source tool) for detecting anomalies in time series data by orchestrating Large Language Models (LLMs).
- It provides two main pipelines—“detector” (forecast-then-compare) and “prompter” (direct prompt)—built on top of Orion primitives.

##### File structure
- Top-level:
- sigllm/             ← the runtime package
- sigllm/pipelines/   ← JSON-driven pipeline definitions (detector & prompter)
- sigllm/primitives/  ← reusable components (forecasting, prompting, transformation, postprocessing)
- sigllm/core.py      ← the SigLLM class that ties everything together
- sigllm/data.py      ← data ingestion & helper routines
- tasks.py            ← command-line or build tasks
- tutorial, docs, tests, benchmark folders → usage examples, documentation, CI, and performance scripts

##### README for technical stack
- Python 3.9–3.11
- Depends on Orion library, Pandas, OpenAI/HuggingFace APIs
- Pipelines configured by JSON files living under sigllm/pipelines and sigllm/primitives/jsons

a. User Application Script
– Imports SigLLM, loads time series (CSV or DataFrame)
b. SigLLM Core (sigllm/core.py)
– Initializes with “pipeline” choice, decimal, hyperparameters
– Loads pipeline definition (JSON) & primitive graph
c. Data Ingestion (sigllm/data.py)
– Reads CSV, validates schema (timestamp + value)
d. Pipeline Engine
– “Detector” pipeline:
- Forecasting primitives → generate forecasted series
- Comparison logic → compute anomalies
– “Prompter” pipeline:
- Prompting primitives → format time series & steer LLM prompt
- LLM call → raw anomaly positions
e. Primitives Subsystem (sigllm/primitives/)
– Forecasting (custom, GPT, HuggingFace)
– Prompting (gpt.py, huggingface.py, anomalies, preprocessing)
– Transformation (format conversions)
– Postprocessing (aggregation, filtering)
– JSON schemas drive edges & parameters
f. External Services
– OpenAI API or HuggingFace endpoint
g. Output
– Pandas DataFrame of anomalies (start, end, severity)

##### Architectural patterns & design principles
- Pipeline Pattern: sequence of primitive operations configured by JSON
- Plugin/Extension: new primitives or pipelines added simply by dropping JSON + code
- Single-entry orchestrator (SigLLM class) decouples user API from primitive implementations
- Separation of concerns: data, core logic, primitives, configurations

##### Elements
- Clear component names (e.g., SigLLM Core, Detector Pipeline, Forecasting Primitive)

Capture all layers—from user entry point down to individual primitives—and show how JSON configs drive the pipeline graph. Keep it detailed but avoid unnecessary low-level file listings.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    UserApp["User Application Script"]:::data
    UserApp -->|"imports SigLLM & DataFrame"| Core["SigLLM Core"]:::module

    %% Orchestration Layer
    Core -->|"loads pipeline JSON config"| DetectorConfig["Detector Pipeline JSONs"]:::config
    Core -->|"loads pipeline JSON config"| PrompterConfig["Prompter Pipeline JSONs"]:::config
    Core -->|"invokes"| DataIngestion["Data Ingestion"]:::module
    DataIngestion -->|"DataFrame"| Engine["Pipeline Engine"]:::module

    %% Pipeline Configurations
    subgraph "Pipeline Configurations" 
        direction TB
        DetectorConfig
        PrompterConfig
    end

    %% Processing Engine
    Engine -->|"runs detector sequence"| Forecasting["Forecasting Primitives"]:::module
    Engine -->|"runs prompter sequence"| Prompting["Prompting Primitives"]:::module
    Forecasting -->|"formatted series"| Transformation["Transformation Primitives"]:::module
    Prompting -->|"formatted prompt"| Transformation
    Transformation -->|"transformed data"| Forecasting
    Transformation -->|"transformed data"| Prompting
    Forecasting -->|"forecast results"| Comparison["Comparison Logic"]:::module
    Comparison --> Postprocessing["Postprocessing Primitives"]:::module
    Postprocessing -->|"anomaly DataFrame"| Core

    %% External Services
    subgraph "External LLM Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        HF["HuggingFace API"]:::external
    end
    Forecasting -->|"API request/response"| OpenAI
    Forecasting -->|"API request/response"| HF
    Prompting -->|"API request/response"| OpenAI
    Prompting -->|"API request/response"| HF
    OpenAI --> Forecasting
    HF --> Forecasting
    OpenAI --> Prompting
    HF --> Prompting

    %% Output
    Core -->|"returns anomalies"| Output["Anomalies DataFrame"]:::data

    %% Click Events
    click UserApp "https://github.com/sintel-dev/sigllm/blob/master/tutorials/Simple Time Series Example.ipynb"
    click Core "https://github.com/sintel-dev/sigllm/blob/master/sigllm/core.py"
    click DataIngestion "https://github.com/sintel-dev/sigllm/blob/master/sigllm/data.py"
    click DetectorConfig "https://github.com/sintel-dev/sigllm/tree/master/sigllm/pipelines/detector/"
    click PrompterConfig "https://github.com/sintel-dev/sigllm/tree/master/sigllm/pipelines/prompter/"
    click Forecasting "https://github.com/sintel-dev/sigllm/tree/master/sigllm/primitives/forecasting/"
    click Prompting "https://github.com/sintel-dev/sigllm/tree/master/sigllm/primitives/prompting/"
    click Transformation "https://github.com/sintel-dev/sigllm/blob/master/sigllm/primitives/transformation.py"
    click Postprocessing "https://github.com/sintel-dev/sigllm/blob/master/sigllm/primitives/postprocessing.py"

    %% Styles
    classDef module fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef data fill:#ffe0b2,stroke:#e65100,color:#e65100,shape:cylinder;
    classDef config fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef external fill:#ffd54f,stroke:#ff6f00,color:#ff6f00;
    classDef module stroke-width:2px;
    classDef data stroke-width:2px;
    classDef config stroke-width:2px;
    classDef external stroke-width:2px;
```
