# gair-nlp/asi-arch architecture

> Architecture diagram of the GitHub repository gair-nlp/asi-arch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gair-nlp/asi-arch
- Repository: https://github.com/gair-nlp/asi-arch

## Overview

##### Project Type and Purpose
- This repository implements a full-stack, multi-agent autonomous research framework for discovering novel linear‐attention architectures.
- It consists of three loosely coupled subsystems:
1. **Autonomous Architecture Discovery Pipeline** (pipeline/)
2. **Architecture Database Service** (database/)
3. **Cognition Base Knowledge Service** (cognition_base/)
- The goal is to continuously generate, evaluate, analyze, and store new model architectures guided by scientific literature.

##### File Structure
- Top-level:
- README.md, requirements.txt, LICENSE, images/, index.html
- cognition_base/ – RAG knowledge service + Docker compose + raw JSON corpus
- database/ – MongoDB + FastAPI service + scripts
- pipeline/ – Four agent modules (evolve, eval, analyse, plus helpers) and orchestration script
- data/, resources/ – sample data dumps and documentation
- Each subfolder includes its own requirements.txt or Docker compose for independent deployment.

##### README for Architecture Insights
- The README describes a continuous loop:
Sample candidate → Evolve (Planner, Checker, Deduper) → Evaluate (Trainer, Debugger) → Analyse (Analyzer) → Update database.
- Two backend services (Database & Cognition Base) run as containers or Python APIs.
- Pipeline agents communicate with both services via REST endpoints.

##### Detail
- Both Docker Compose orchestration and standalone Python APIs.
- Technology stack (Python, FastAPI, Flask, FAISS, MongoDB)
- Workflow steps (Sample → Evolve → Evaluate → Analyse → Update)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline Layer
    subgraph "Pipeline Engine" 
        direction TB
        Orchestrator["Orchestrator\n(pipeline.py)"]:::pipeline
        Evolve["Evolve Agent\n(interface.py)"]:::pipeline
        Eval["Eval Agent\n(interface.py)"]:::pipeline
        Analyse["Analyse Agent\n(interface.py)"]:::pipeline
        Helpers["Helpers & Tools"]:::pipeline
    end

    %% Database Layer
    subgraph "Architecture Database Service"
        direction TB
        DBAPI["FastAPI API\n(mongodb_api.py)"]:::database
        MongoDB["MongoDB\nInstance"]:::database
        CandidateMgr["Candidate Manager\n(candidate_manager.py)"]:::database
        FAISS["FAISS Vector Store\n(faiss_manager.py)"]:::database
        Embedding["Embedding Service\n(embedding_service.py)"]:::database
        DBUtils["Utilities & Scripts"]:::database
    end

    %% Cognition Layer
    subgraph "Cognition Base Service"
        direction TB
        RAGAPI["RAG REST API\n(rag_api.py)"]:::cognition
        RAGService["RAG Service\n(rag_service.py)"]:::cognition
        Corpus["Raw JSON Corpus\n(cognition/)"]:::cognition
    end

    %% External Dependencies
    GPU["CUDA GPU"]:::external
    Docker["Docker & Compose"]:::external
    PythonEnv["Conda/Python"]:::external

    %% Pipeline orchestration
    Orchestrator -->|"orchestrates"| Evolve
    Orchestrator -->|"orchestrates"| Eval
    Orchestrator -->|"orchestrates"| Analyse

    %% Agents to Database
    Evolve -->|"POST /candidates"| DBAPI
    Eval -->|"POST /train\nGET /metrics"| DBAPI
    Analyse -->|"POST /analysis"| DBAPI

    %% Agents to Cognition
    Evolve -->|"GET /query"| RAGAPI
    Eval -->|"GET /query"| RAGAPI
    Analyse -->|"GET /query"| RAGAPI

    %% Eval agent GPU interaction
    Eval -->|"runs jobs on"| GPU
    GPU -->|"returns results"| Eval

    %% Database internals
    DBAPI -->|"CRUD"| MongoDB
    DBAPI -->|"uses"| CandidateMgr
    CandidateMgr -->|"queries"| FAISS
    DBAPI -->|"embeddings via"| Embedding
    DBUtils -->|"scripts"| DBAPI

    %% Cognition internals
    RAGAPI -->|"invokes"| RAGService
    RAGService -->|"reads corpus"| Corpus

    %% Orchestration dependencies
    Orchestrator -->|"deploys via"| Docker
    Orchestrator -->|"runs on"| PythonEnv

    %% Click Events - Pipeline
    click Orchestrator "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/pipeline.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/interface.py"
    click Eval "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/eval/interface.py"
    click Analyse "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/analyse/interface.py"
    click Helpers "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/tools/tools.py"
    click Helpers "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/utils/agent_logger.py"
    click Helpers "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/utils/log_viewer.py"

    %% Click Events - Evolve internals
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/model/planner.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/prompt/planner.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/model/checker.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/prompt/checker.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/model/deduplication.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/prompt/deduplication.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/model/motivation.py"
    click Evolve "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/evolve/prompt/motivation.py"

    %% Click Events - Eval internals
    click Eval "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/eval/model/trainer.py"
    click Eval "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/eval/model/debugger.py"
    click Eval "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/eval/prompts/debugger.py"

    %% Click Events - Analyse internals
    click Analyse "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/analyse/model/analyzer.py"
    click Analyse "https://github.com/gair-nlp/asi-arch/blob/main/pipeline/analyse/prompts/analyzer.py"

    %% Click Events - Database
    click DBAPI "https://github.com/gair-nlp/asi-arch/blob/main/database/mongodb_api.py"
    click DBAPI "https://github.com/gair-nlp/asi-arch/blob/main/database/mongodb_database.py"
    click DBAPI "https://github.com/gair-nlp/asi-arch/blob/main/database/candidate_manager.py"
    click DBAPI "https://github.com/gair-nlp/asi-arch/blob/main/database/faiss_manager.py"
    click DBAPI "https://github.com/gair-nlp/asi-arch/blob/main/database/embedding_service.py"
    click DBUtils "https://github.com/gair-nlp/asi-arch/blob/main/database/util.py"
    click DBUtils "https://github.com/gair-nlp/asi-arch/blob/main/database/reset_dataset.py"
    click DBUtils "https://github.com/gair-nlp/asi-arch/blob/main/database/start_api.sh"
    click DBUtils "https://github.com/gair-nlp/asi-arch/blob/main/database/docker-compose.yml"

    %% Click Events - Cognition
    click RAGAPI "https://github.com/gair-nlp/asi-arch/blob/main/cognition_base/rag_api.py"
    click RAGService "https://github.com/gair-nlp/asi-arch/blob/main/cognition_base/rag_service.py"
    click Corpus "https://github.com/gair-nlp/asi-arch/tree/main/cognition_base/cognition/"
    click RAGService "https://github.com/gair-nlp/asi-arch/blob/main/cognition_base/docker-compose.yml"
    click RAGService "https://github.com/gair-nlp/asi-arch/blob/main/cognition_base/requirements.txt"

    classDef pipeline fill:#e6ffe6,stroke:#2e7d32,stroke-width:2px
    classDef database fill:#e6f0ff,stroke:#1565c0,stroke-width:2px
    classDef cognition fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef external fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px
```
