# nishant4671/worldquant-pipeline- architecture

> Architecture diagram of the GitHub repository nishant4671/worldquant-pipeline-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nishant4671/worldquant-pipeline-
- Repository: https://github.com/nishant4671/worldquant-pipeline-

## Overview

This repository automates WorldQuant BRAIN alpha research: a CLI coordinates expression proposal, static validation, simulation, persistence, and Telegram review. The generator and Gemini client provide complementary proposal paths; the validator gates expressions before simulation, whose engine submits and polls BRAIN simulations and evaluates metrics. SQLite stores candidates, while Telegram sends digests and processes Submit/Skip interactions. The excerpts show the main orchestration and several calls, but not every pipeline step or storage interaction; unsampled links are omitted. The README is empty, so documented capability coverage is limited to source descriptions and the file tree.

Main entry points: [`main.py`](https://github.com/nishant4671/worldquant-pipeline-/blob/main/main.py) (Pipeline CLI), [`notifier.py`](https://github.com/nishant4671/worldquant-pipeline-/blob/main/notifier.py) (Telegram notifier), [`database.py`](https://github.com/nishant4671/worldquant-pipeline-/blob/main/database.py) (Alpha database), [`llm_client.py`](https://github.com/nishant4671/worldquant-pipeline-/blob/main/llm_client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline orchestration"]
  node_cli["Pipeline CLI<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_research["Alpha research"]
  node_templates["Expression generator<br/>[generator.py]"]
  node_gemini["LLM client<br/>[llm_client.py]"]
  node_gatekeeper["Expression validator<br/>[validator.py]"]
end

subgraph group_simulation["Simulation"]
  node_engine["Simulation engine<br/>[engine.py]"]
  node_brainclient["BRAIN API client<br/>[api_client.py]"]
end

subgraph group_review["Persistence and review"]
  node_store[("Alpha database<br/>[database.py]")]
  node_notifier["Telegram notifier<br/>[notifier.py]"]
end

subgraph group_integrations["External integrations"]
  node_brain{{"WorldQuant BRAIN"}}
  node_geminisvc{{"Google Gemini"}}
  node_telegram{{"Telegram"}}
  node_sqlite[("SQLite")]
end

node_user(("Operator"))

node_user -->|"invokes commands"| node_cli
node_cli -->|"requests expressions"| node_templates
node_cli -->|"requests proposals"| node_gemini
node_cli -->|"validates proposals"| node_gatekeeper
node_cli -->|"runs simulations"| node_engine
node_cli -->|"initializes database"| node_store
node_cli -->|"sends digest"| node_notifier
node_engine -->|"sends requests"| node_brainclient
node_brainclient -->|"authenticates and requests"| node_brain
node_gemini -->|"calls model"| node_geminisvc
node_notifier -->|"marks notified"| node_store
node_notifier -->|"sends and polls"| node_telegram
node_store -->|"reads and writes"| node_sqlite

click node_cli "https://github.com/nishant4671/worldquant-pipeline-/blob/main/main.py"
click node_settings "https://github.com/nishant4671/worldquant-pipeline-/blob/main/config.py"
click node_templates "https://github.com/nishant4671/worldquant-pipeline-/blob/main/generator.py"
click node_gemini "https://github.com/nishant4671/worldquant-pipeline-/blob/main/llm_client.py"
click node_gatekeeper "https://github.com/nishant4671/worldquant-pipeline-/blob/main/validator.py"
click node_engine "https://github.com/nishant4671/worldquant-pipeline-/blob/main/engine.py"
click node_brainclient "https://github.com/nishant4671/worldquant-pipeline-/blob/main/api_client.py"
click node_store "https://github.com/nishant4671/worldquant-pipeline-/blob/main/database.py"
click node_notifier "https://github.com/nishant4671/worldquant-pipeline-/blob/main/notifier.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_settings toneBlue
class node_templates,node_gemini,node_gatekeeper toneAmber
class node_engine,node_brainclient toneMint
class node_store,node_notifier toneRose
class node_brain,node_geminisvc,node_telegram,node_sqlite,node_user toneIndigo
```

## Components

### Pipeline orchestration

- [Pipeline CLI](https://github.com/nishant4671/worldquant-pipeline-/blob/main/main.py): `main.py`
- [Runtime settings](https://github.com/nishant4671/worldquant-pipeline-/blob/main/config.py): `config.py`

### Alpha research

- [Expression generator](https://github.com/nishant4671/worldquant-pipeline-/blob/main/generator.py): `generator.py`
- [LLM client](https://github.com/nishant4671/worldquant-pipeline-/blob/main/llm_client.py): `llm_client.py`
- [Expression validator](https://github.com/nishant4671/worldquant-pipeline-/blob/main/validator.py): `validator.py`

### Simulation

- [Simulation engine](https://github.com/nishant4671/worldquant-pipeline-/blob/main/engine.py): `engine.py`
- [BRAIN API client](https://github.com/nishant4671/worldquant-pipeline-/blob/main/api_client.py): `api_client.py`

### Persistence and review

- [Alpha database](https://github.com/nishant4671/worldquant-pipeline-/blob/main/database.py): `database.py`
- [Telegram notifier](https://github.com/nishant4671/worldquant-pipeline-/blob/main/notifier.py): `notifier.py`

### External integrations

- **WorldQuant BRAIN**
- **Google Gemini**
- **Telegram**
- **SQLite**

### Other components

- **Operator**

## Connections

- Operator → Pipeline CLI: invokes commands (evidence: `main.py`)
- Pipeline CLI → Expression generator: requests expressions (evidence: `main.py`)
- Pipeline CLI → LLM client: requests proposals (evidence: `main.py`)
- Pipeline CLI → Expression validator: validates proposals (evidence: `main.py`)
- Pipeline CLI → Simulation engine: runs simulations (evidence: `main.py`)
- Pipeline CLI → Alpha database: initializes database (evidence: `main.py`)
- Pipeline CLI → Telegram notifier: sends digest (evidence: `main.py`)
- Simulation engine → BRAIN API client: sends requests (evidence: `engine.py`)
- BRAIN API client → WorldQuant BRAIN: authenticates and requests (evidence: `api_client.py`)
- LLM client → Google Gemini: calls model (evidence: `llm_client.py`)
- Telegram notifier → Alpha database: marks notified (evidence: `notifier.py`)
- Telegram notifier → Telegram: sends and polls (evidence: `notifier.py`)
- Alpha database → SQLite: reads and writes (evidence: `database.py`)