# hpcclab/action_engine architecture

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

- Interactive diagram: https://gitdiagram.com/hpcclab/action_engine
- Repository: https://github.com/hpcclab/action_engine

## Overview

##### Project Type & Purpose
- This is neither a typical web app nor a compiler; it’s an end-to-end workflow-generation **pipeline/tool** that ingests a natural language query and emits an executable, platform-agnostic FaaS workflow. It also contains extensive **evaluation and data-preparation** sub-systems.

##### Core Modules & Directory Structure
- actione_engine_reverse/: “reverse chain” LLM pipeline for alternate evaluation
- main_rae.py — entry point
- utils/ — config, LLM wrappers, module runners, data schemas
- db/ & db_old/: CSV/JSON + FAISS vector-store construction for API metadata
- utils/ (root): shared compiler, dependency analyzer, LLM abstractions, schema definitions
- eval/: ground-truth vs. predicted comparison logic, confidence intervals, plotting, Jupyter notebooks
- output_file/: compiled Argo YAML
- main.py + requirements.txt + Dockerfile: CLI orchestration, containerization

##### High-Level System Components
A. User Interface (CLI / REST)
B. Text-to-Workflow Engine
1. Configuration Loader (utils/config.py)
2. API Info Database (db/*.csv/.json + FAISS index)
3. LLM Orchestration (utils/llms.py + actione_engine_reverse/utils/llms.py)
4. Function Selector & Dependency Analyzer (utils/func_identifier.py, data_dependency.py, modules.py)
5. DAG Constructor (schemas/workflow.py, wf_optimizer.py)
6. Workflow Compiler (utils/argo_compiler.py → Argo YAML)
C. Execution Interface (API Endpoint generator, output_file/argo_workflow.yaml)
D. Evaluation Subsystem
1. Ground-truth loader (eval/data/gt)
2. Prediction loader (eval/data/predict)
3. Metrics calculators (eval/culculate.py, confidence_interval.py)
4. Plotting & Reports (eval/plot_*.py, eval/plots)

##### Component Relationships & Data Flow
- **User** → issues **natural-language query** (CLI or REST)
- → **Config Loader** reads parameters
- → **API DB + FAISS** returns candidate API functions
- → **LLM Orchestrator** calls external LLM service (GPT-4o, Qwen, etc.) with prompts (few-shot, zero-shot, tool-augmented)
- → **Function Selector** chooses functions, identifies data dependencies
- → **DAG Constructor** builds a directed graph of function calls
- → **Workflow Compiler** translates DAG into platform-independent YAML (Argo / other FaaS orchestrators)
- → **Output**: compiled workflow (output_file/) and optionally RESTful API endpoint definitions
- **Evaluation** taps ground-truth vs. predictions, computes F1, order accuracy, and renders plots

##### Architectural Patterns & Principles
- **Pipeline Pattern**: clear stage separation (selection → dependency → DAG → compile)
- **Plugin/Modular Design**: utils/ and actione_engine_reverse/utils/ define interchangeable LLM backends and compilation targets
- **Event-Driven/Eager Dataflow**: DAG-based workflow representation
- **Separation of Concerns**: distinct directories for data preparation (db/), inference (actione_engine_reverse/), evaluation (eval/)

##### Technologies & External Services
- Python 3.x, Jupyter notebooks for exploration
- FAISS vector database for semantic API retrieval
- External LLM endpoints (OpenAI GPT-4o, local quantized Qwen-GPTQ)
- Argo Workflows (YAML) for FaaS orchestration
- Docker for containerization
- Matplotlib / PDF for plots

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    UserQuery["User Query"]:::core
    click UserQuery "https://github.com/hpcclab/action_engine/blob/main/main.py"

    %% Configuration Loaders
    ConfigCore["Config Loader (core)"]:::core
    ConfigReverse["Config Loader (reverse)"]:::core
    click ConfigCore "https://github.com/hpcclab/action_engine/blob/main/utils/config.py"
    click ConfigReverse "https://github.com/hpcclab/action_engine/blob/main/actione_engine_reverse/utils/config.py"

    %% API Database
    subgraph "API Info Database" 
        style Database fill:#e0f7fa,stroke:#006064
        CSVJSON["CSV/JSON Files"]:::storage
        FAISSStore["FAISS Vector Store"]:::storage
    end
    click CSVJSON "https://github.com/hpcclab/action_engine/blob/main/db/api_info/api_information.csv"
    click CSVJSON "https://github.com/hpcclab/action_engine/blob/main/db/api_info/api_information.json"
    click FAISSStore "https://github.com/hpcclab/action_engine/blob/main/db_old/api_info/vectordb/LangChain_FAISS/api_vec.faiss"

    %% Evaluation FAISS variants
    subgraph "FAISS Eval Domains"
        EvalFAISS["*.faiss"]:::storage
    end
    click EvalFAISS "https://github.com/hpcclab/action_engine/blob/main/db_old/api_info/vectordb/LangChain_FAISS/eval_domains/*.faiss"

    %% LLM Orchestration
    LLMCore["LLM Orchestrator (core)"]:::core
    LLMReverse["LLM Orchestrator (reverse)"]:::core
    ExternalLLM["External LLM Service"]:::external
    click LLMCore "https://github.com/hpcclab/action_engine/blob/main/utils/llms.py"
    click LLMReverse "https://github.com/hpcclab/action_engine/blob/main/actione_engine_reverse/utils/llms.py"

    %% Function Selection & Dependency
    FuncSelector["Function Selector"]:::core
    click FuncSelector "https://github.com/hpcclab/action_engine/blob/main/utils/func_identifier.py"
    DataDep["Data Dependency Analyzer"]:::core
    click DataDep "https://github.com/hpcclab/action_engine/blob/main/utils/data_dependency.py"
    ReverseModules["Module Runner/Selector (reverse)"]:::core
    click ReverseModules "https://github.com/hpcclab/action_engine/blob/main/actione_engine_reverse/utils/modules.py"

    %% DAG Construction
    DAGSchemaCore["DAG Schema Definition (core)"]:::core
    DAGSchemaReverse["DAG Schema Definition (reverse)"]:::core
    click DAGSchemaCore "https://github.com/hpcclab/action_engine/blob/main/utils/schemas/workflow.py"
    click DAGSchemaReverse "https://github.com/hpcclab/action_engine/blob/main/actione_engine_reverse/utils/schemas/workflow.py"
    WorkflowOpt["Workflow Optimizer"]:::core
    click WorkflowOpt "https://github.com/hpcclab/action_engine/blob/main/utils/wf_optimizer.py"
    DAGConstructor["DAG Constructor"]:::core

    %% Workflow Compilation
    ArgoCompiler["Workflow Compiler"]:::core
    click ArgoCompiler "https://github.com/hpcclab/action_engine/blob/main/utils/argo_compiler.py"
    ArgoOutput["Argo YAML Output"]:::output
    click ArgoOutput "https://github.com/hpcclab/action_engine/blob/main/output_file/argo_workflow.yaml"
    APIEndpoint["API Endpoint Definitions"]:::output

    %% Reverse Chain Entry
    ReverseEntry["Reverse-Chain Entry Point"]:::core
    click ReverseEntry "https://github.com/hpcclab/action_engine/blob/main/actione_engine_reverse/main_rae.py"

    %% DB Creation Scripts
    DBCore["DB Creation Script (core)"]:::core
    click DBCore "https://github.com/hpcclab/action_engine/blob/main/db/create_db.py"
    DBReverse["DB Creation Script (reverse)"]:::core
    click DBReverse "https://github.com/hpcclab/action_engine/blob/main/db/create_db_reverse.py"

    %% Evaluation Subsystem
    subgraph "Evaluation Engine" 
        style Eval fill:#fff3e0,stroke:#e65100
        GTLoader["Ground-Truth Loader"]:::eval
        click GTLoader "https://github.com/hpcclab/action_engine/tree/main/eval/data/gt/"
        PredLoader["Prediction Loader"]:::eval
        click PredLoader "https://github.com/hpcclab/action_engine/tree/main/eval/data/predict/"
        MetricsCalc["Metrics Calculator"]:::eval
        click MetricsCalc "https://github.com/hpcclab/action_engine/blob/main/eval/culculate.py"
        ConfInt["Confidence Intervals"]:::eval
        click ConfInt "https://github.com/hpcclab/action_engine/blob/main/eval/data/confidence_interval.py"
        Plotting["Plotting & Reports"]:::eval
        click Plotting "https://github.com/hpcclab/action_engine/blob/main/eval/plot_linechart.py"
        click Plotting "https://github.com/hpcclab/action_engine/blob/main/eval/plot_main_all.py"
        click Plotting "https://github.com/hpcclab/action_engine/blob/main/eval/plot_param.py"
        click Plotting "https://github.com/hpcclab/action_engine/tree/main/eval/plots/"
    end

    %% Main Orchestration
    CLI["CLI / REST Interface"]:::core
    click CLI "https://github.com/hpcclab/action_engine/blob/main/main.py"
    Docker["Containerization"]:::infra
    click Docker "https://github.com/hpcclab/action_engine/tree/main/Dockerfile"

    %% Connections
    UserQuery -->|issues query| CLI
    CLI -->|loads| ConfigCore
    CLI -->|loads reverse| ConfigReverse

    ConfigCore -->|fetch metadata| CSVJSON
    ConfigCore -->|fetch metadata| FAISSStore
    ConfigCore -->|fetch metadata| EvalFAISS

    ConfigCore -->|calls| LLMCore
    ConfigReverse -->|calls| LLMReverse

    LLMCore -->|calls| ExternalLLM
    LLMReverse -->|calls| ExternalLLM

    LLMCore -->|returns candidates| FuncSelector
    LLMReverse -->|returns candidates| ReverseModules

    FuncSelector -->|identifies| DataDep
    ReverseModules -->|identifies| DataDep

    DataDep -->|feeds| DAGConstructor

    DAGConstructor -->|uses schema| DAGSchemaCore
    DAGConstructor -->|uses optimizer| WorkflowOpt
    DAGConstructor -->|uses schema reverse| DAGSchemaReverse

    DAGConstructor -->|outputs DAG| ArgoCompiler
    ArgoCompiler -->|compiles to YAML| ArgoOutput
    ArgoCompiler -->|generates| APIEndpoint

    CLI -->|orchestrates| Docker

    EvaluationInput1["Evaluation Trigger"]:::eval --> GTLoader
    EvaluationInput2["Evaluation Trigger"]:::eval --> PredLoader
    GTLoader --> MetricsCalc
    PredLoader --> MetricsCalc
    MetricsCalc --> ConfInt
    ConfInt --> Plotting

    %% Styles
    classDef core fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1
    classDef storage fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef external fill:#f1f8e9,stroke:#33691e,color:#33691e
    classDef output fill:#ede7f6,stroke:#4527a0,color:#4527a0
    classDef infra fill:#eceff1,stroke:#37474f,color:#37474f
    classDef eval fill:#fff8e1,stroke:#ff6f00,color:#e65100
```
