# gc-os-ai/pyaptamer architecture

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

- Interactive diagram: https://gitdiagram.com/gc-os-ai/pyaptamer
- Repository: https://github.com/gc-os-ai/pyaptamer

## Overview

##### Project type and purpose
- pyaptamer is an open-source Python library for AI-driven aptamer design.
- It provides algorithms, data loaders, feature extractors, and pipelines to build, train, and evaluate aptamer discovery models.

##### File structure
- Top-level modules under `pyaptamer/`:
- `aptanet` — neural-network–based aptamer design (NN models, feature classifiers, end-to-end pipeline).
- `aptatrans` — transformer-based model layers, model and pipeline.
- `datasets` — data-loader interfaces for PDB/online sources, sample data.
- `experiments` — orchestrators for running end-to-end aptamer design experiments.
- `mcts` — Monte Carlo Tree Search algorithm implementations for sequence search.
- `pseaac` — feature extraction utilities (physicochemical features).
- `utils` — low-level helpers (PDB parsing, sequence conversions, shared utilities).
- Tests accompany each module in parallel `tests` sub-folders.
- Build-and-CI scripts reside under `.github`, `build_tools`, and `pyproject.toml`.

##### Key insights from the README
- Emphasizes “scikit-learn–like API” and “easily extendable with plugins.”
- Mentions dependencies: Biopython, scikit-learn, minimal other packages.

##### Main components
a. User Application / API Layer
- Entry point for users: import classes/functions from pyaptamer.
b. Data Ingestion & Loaders (`pyaptamer.datasets`)
- Loads PDB files or online databank entries into structured objects.
c. Feature Extraction
- pseaac module computes sequence/protein features.
- aptanet utils + pseaac utils.
d. Model Components
- aptanet NN modules (`_aptanet_nn.py`, `_feature_classifier.py`).
- aptatrans transformer layers and full model (`model.py`).
e. Pipelines
- `aptanet.pipeline` and `aptatrans.pipeline` orchestrate data → features → model → predictions.
f. Search & Optimization
- MCTS algorithm module (`mcts/_algorithm.py`) for sequence optimization loops.
- Experiments module orchestrates end-to-end runs combining pipelines and search.
g. Utilities
- Low-level helpers in `utils` (file I/O, conversion, shared code).
h. External Dependencies
- Biopython, scikit-learn, PyTorch/NumPy, PDB source or web API.

##### Relationships & data flow
- Experiments module coordinates batches of these loops and records results.
- Utilities support every stage (parsing, conversion).

##### Architectural patterns & design principles
- Layered design: data layer, feature layer, model layer, orchestration layer.
- Pluggable pipelines: interchangeable pipeline modules for NN vs transformer.
- Test-first structure: each module has its own test suite.
- Minimal external dependencies and standardized API (scikit-learn style).

##### Diagramming recommendations
- Clear labels for each module/component.
- Data → Loaders → Feature Extractors → Pipelines → Models → Results
- Results → MCTS → Pipelines (optimization loop)
- Blue for data and I/O,
- Green for feature extraction,
- Orange for models,
- Purple for orchestration/search,
- Gray for utilities.

##### Final advice
- Document external dependencies and configuration entry points (e.g., `pyproject.toml`, CLI scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User layer
    User["User Application / API Layer"]:::external
    click User "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/__init__.py"

    %% Data Layer
    subgraph "Data Ingestion & Loaders"
        direction TB
        Datasets["Datasets (pyaptamer.datasets)"]:::data
    end
    click Datasets "https://github.com/gc-os-ai/pyaptamer/tree/main/pyaptamer/datasets/_loaders/"

    %% Feature Extraction Layer
    subgraph "Feature Extraction"
        direction TB
        PseAAC["PseAAC Features"]:::feature
    end
    click PseAAC "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/pseaac/_features.py"
    click PseAAC "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/pseaac/_props.py"

    %% Pipelines
    subgraph "Pipelines"
        direction TB
        PipelineNN["AptaNet Pipeline"]:::pipeline
        PipelineTrans["AptaTrans Pipeline"]:::pipeline
    end
    click PipelineNN "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptanet/_pipeline.py"
    click PipelineTrans "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptatrans/pipeline.py"

    %% Models
    subgraph "Model Components"
        direction TB
        subgraph "AptaNet (NN)" 
            direction TB
            NN["_aptanet_nn.py"]:::model
            Classifier["_feature_classifier.py"]:::model
        end
        subgraph "AptaTrans (Transformer)"
            direction TB
            TransModel["model.py"]:::model
            ConvLayer["_convolutional.py"]:::model
            Encoder["_encoder.py"]:::model
            Interaction["_interaction_map.py"]:::model
        end
    end
    click NN "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptanet/_aptanet_nn.py"
    click Classifier "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptanet/_feature_classifier.py"
    click TransModel "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptatrans/model.py"
    click ConvLayer "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptatrans/layers/_convolutional.py"
    click Encoder "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptatrans/layers/_encoder.py"
    click Interaction "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/aptatrans/layers/_interaction_map.py"

    %% Optimization/Search
    MCTS["MCTS Algorithm"]:::orchestration
    click MCTS "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/mcts/_algorithm.py"

    %% Experiment Orchestration
    Experiments["Experiments Orchestration"]:::orchestration
    click Experiments "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/experiments/_aptamer.py"

    %% Utilities
    subgraph "Utilities"
        direction TB
        UtilsApta["_aptanet_utils.py"]:::utils
        UtilsPseaac["_pseaac_utils.py"]:::utils
        UtilsRNA["_rna.py"]:::utils
        UtilsPDB["pdb_to_struct.py"]:::utils
        UtilsStruct["struct_to_aaseq.py"]:::utils
    end
    click UtilsApta "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/utils/_aptanet_utils.py"
    click UtilsPseaac "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/utils/_pseaac_utils.py"
    click UtilsRNA "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/utils/_rna.py"
    click UtilsPDB "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/utils/pdb_to_struct.py"
    click UtilsStruct "https://github.com/gc-os-ai/pyaptamer/blob/main/pyaptamer/utils/struct_to_aaseq.py"

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Biopython["Biopython"]:::external
        SKLearn["scikit-learn"]:::external
        Torch["PyTorch/NumPy"]:::external
        PDBSource["PDB/Web API"]:::external
    end

    %% Data flow
    User -->|"import/load"| Datasets -->|"load_pdb() / fetch()"| PseAAC -->|"compute features"| PipelineNN
    PseAAC -->|"compute features"| PipelineTrans
    PipelineNN -->|"fit()/predict()"| NN
    PipelineNN --> Classifier
    PipelineTrans --> TransModel
    PipelineTrans --> ConvLayer
    PipelineTrans --> Encoder
    PipelineTrans --> Interaction
    NN -->|"predictions"| Results["Predictions"]:::external
    TransModel --> Results
    Results -->|"sequence candidates"| MCTS -->|"refined data"| PipelineNN
    Results -->|"sequence candidates"| MCTS -->|"refined data"| PipelineTrans
    Experiments --> Datasets
    Experiments --> PipelineNN
    Experiments --> PipelineTrans
    Experiments --> MCTS
    Experiments --> Results

    %% Utilities support
    UtilsApta --> Datasets
    UtilsPseaac --> PseAAC
    UtilsRNA --> Datasets
    UtilsPDB --> Datasets
    UtilsStruct --> Datasets

    %% External deps
    Biopython --> Datasets
    SKLearn --> PipelineNN
    Torch --> PipelineNN
    Torch --> PipelineTrans
    PDBSource --> Datasets

    %% Styles
    classDef data fill:#add8e6,stroke:#333;
    classDef feature fill:#90ee90,stroke:#333;
    classDef model fill:#ffa500,stroke:#333;
    classDef orchestration fill:#dda0dd,stroke:#333;
    classDef pipeline fill:#ffdead,stroke:#333,stroke-dasharray: 5 5,stroke-width:2px;
    classDef utils fill:#d3d3d3,stroke:#333;
    classDef external fill:#f0e68c,stroke:#333;
```
