# bogoconic1/qgentic-ai architecture

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

- Interactive diagram: https://gitdiagram.com/bogoconic1/qgentic-ai
- Repository: https://github.com/bogoconic1/qgentic-ai

## Overview

##### Project type and purpose
- This is neither a web app nor a typical library but a research-and-development automation “pipeline” or “agentic R&D stack.”
- Purpose: Fully autonomous iteration on Kaggle competitions via collaborating LLM-driven agents (Starter, Researcher, ModelRecommender, Developer, Ensembler) under the control of an Orchestrator. It handles data ingestion, plan generation, code synthesis, execution, evaluation, and refinement.

##### File structure
- Top-level entrypoints:
- launch_agent.py (CLI)
- crawl_website.py / create_metadata.py (data prep)
- install.sh / node_install.sh (setup)
- project_config.py, config.yaml (configuration)
- agents/ : core agent logic (starter.py, researcher.py, model_recommender.py, developer.py, ensembler.py, orchestrator.py)
- prompts/, schemas/ : prompt templates and message schemas per agent
- tools/, guardrails/, utils/ : shared helper code (code execution, LLM tool calls, OOM retry, resource management, guardrail checks)
- task/ (runtime) : dynamic directory for competition bundles, intermediate outputs, logs, code artifacts
- tests/ : unit tests for each agent and tool

##### README for additional insights
- Provides a high-level “Architecture at a Glance” describing each agent’s responsibilities
- Lists key external integrations (Kaggle API, LLM endpoints, WandB, NVIDIA MIG, CPU affinity)
- Details on parallel baseline execution via ThreadPoolExecutor and resource pools

##### Detail without over-complication
- Every agent and its major interactions
- Concurrency model (parallel baselines)
- Two-stage DeveloperAgent flow (red-flags then SOTA) and how it loops
- Don’t fragment into too many micro-components; group helper modules under “Tools & Guardrails”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entrypoint
    subgraph "CLI / Entrypoint"
        launchAgent["launch_agent.py"]:::compute
        projectConfig["project_config.py"]:::compute
        configYaml["config.yaml"]:::compute
    end

    %% Orchestrator
    subgraph "Orchestrator"
        orchestrator["Orchestrator\n(agents/orchestrator.py)"]:::compute
        resourcePools["Resource Pools\n(CPU cores, NVIDIA MIG)"]:::compute
        computeEnv["Compute Environment\n(Conda envs, GPU/MIG, CPU affinity)"]:::compute
    end

    %% Agents Pipeline
    subgraph "Agents Pipeline"
        starterAgent["Starter Agent"]:::compute
        researcherAgent["Researcher Agent"]:::compute
        modelRecommenderAgent["ModelRecommender Agent"]:::compute
        developerAgent["Developer Agent"]:::compute
        ensemblerAgent["Ensembling Agent"]:::compute
    end

    %% Tools & Guardrails
    subgraph "Tools & Guardrails"
        tools["Tools"]:::shared
        guardrails["Guardrails"]:::shared
    end

    %% Data Store
    dataStore["Task Bundle\n(task/<slug>/)"]:::data

    %% External Services
    subgraph "External Services"
        llmAPIs["LLM APIs\n(OpenAI, Anthropic, VertexAI)"]:::external
        kaggleAPI["Kaggle API\n/meta-kaggle"]:::external
        wandb["WandB / Weave"]:::external
    end

    %% Relationships
    launchAgent -->|starts| orchestrator
    projectConfig -->|configures| orchestrator
    configYaml -->|configures| orchestrator

    orchestrator -->|allocates| resourcePools
    resourcePools -->|provides| computeEnv

    orchestrator -->|launches| starterAgent
    starterAgent -->|next| researcherAgent
    researcherAgent -->|next| modelRecommenderAgent
    modelRecommenderAgent -->|next| developerAgent
    developerAgent -->|next| ensemblerAgent

    %% Agents interactions
    starterAgent -->|uses| tools
    researcherAgent -->|uses| tools
    modelRecommenderAgent -->|uses| tools
    developerAgent -->|uses| tools
    ensemblerAgent -->|uses| tools

    starterAgent -->|enforced by| guardrails
    researcherAgent -->|enforced by| guardrails
    modelRecommenderAgent -->|enforced by| guardrails
    developerAgent -->|enforced by| guardrails
    ensemblerAgent -->|enforced by| guardrails

    starterAgent -->|calls| llmAPIs
    researcherAgent -->|calls| llmAPIs
    modelRecommenderAgent -->|calls| llmAPIs
    developerAgent -->|calls| llmAPIs
    ensemblerAgent -->|calls| llmAPIs

    starterAgent -->|writes| dataStore
    researcherAgent -->|writes| dataStore
    modelRecommenderAgent -->|writes| dataStore
    developerAgent -->|writes| dataStore
    ensemblerAgent -->|writes| dataStore

    starterAgent -->|logs| wandb
    researcherAgent -->|logs| wandb
    modelRecommenderAgent -->|logs| wandb
    developerAgent -->|logs| wandb
    ensemblerAgent -->|logs| wandb

    orchestrator -->|orchestrates| researchParallel[Parallel Developer/Ensembler Runs]:::compute
    researchParallel --> developerAgent
    researchParallel --> ensemblerAgent

    %% Click Events
    click launchAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/launch_agent.py"
    click projectConfig "https://github.com/bogoconic1/qgentic-ai/blob/main/project_config.py"
    click configYaml "https://github.com/bogoconic1/qgentic-ai/blob/main/config.yaml"
    click orchestrator "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/orchestrator.py"
    click starterAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/starter.py"
    click researcherAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/researcher.py"
    click modelRecommenderAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/model_recommender.py"
    click developerAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/developer.py"
    click ensemblerAgent "https://github.com/bogoconic1/qgentic-ai/blob/main/agents/ensembler.py"
    click tools "https://github.com/bogoconic1/qgentic-ai/blob/main/tools/__init__.py"
    click guardrails "https://github.com/bogoconic1/qgentic-ai/blob/main/guardrails/developer.py"
    click dataStore "https://github.com/bogoconic1/qgentic-ai/tree/main/task/"
    click llmAPIs "https://github.com/bogoconic1/qgentic-ai/blob/main/constants.py"
    click kaggleAPI "https://github.com/bogoconic1/qgentic-ai/blob/main/crawl_website.py"
    click wandb "https://github.com/bogoconic1/qgentic-ai/blob/main/utils/grade.py"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000
    classDef data fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef shared fill:#D3D3D3,stroke:#000
```
