# xxii-ai/lours architecture

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

- Interactive diagram: https://gitdiagram.com/xxii-ai/lours
- Repository: https://github.com/xxii-ai/lours

## Overview

##### Main Components
a. Library Core (lours package):
- Dataset Module (lours/dataset) – Handles loading, processing, conversion, merging, and splitting of datasets. This module includes submodules for different dataset IO formats (e.g., caipy.py, coco.py, darknet.py, pascalvoc.py, etc.), helper functions (remap_presets), and schema utilities.
- Evaluation Module (lours/evaluation) – Contains evaluator classes and functions dedicated to detection, crowd detection, and possibly other forms of dataset evaluation. This includes base evaluators and utilities.
- CLI Module (lours/cli) – Offers command-line entry points (for example, caipy_to_fiftyone.py) that encapsulate calls to dataset operations and evaluation functionalities.

##### Relationships and Interactions
- The CLI is an entry layer that users interact with; it invokes specific functions in the Dataset and Evaluation modules.
- The Dataset module centrally interacts with various IO submodules to read and convert the different dataset formats, potentially orchestrating merging and splitting operations.
- The Evaluation module relies on the processed dataset objects provided by the Dataset module to run detection and crowd detection evaluations.
- Utility functions are referenced by both the Dataset and Evaluation modules to perform routine data transformations, validations, and conversions.
- Similarly, show that the Evaluation component depends on outputs from the conversion and processing layers provided by the Dataset module.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each top-level module (CLI, Dataset, Evaluation, Utils) is responsible for a specific area of functionality.
- Layered Structure: The underlying layers of IO handling in the Dataset module feed into higher-level operations like merging and evaluation.
- Reusability and Modularity: Utility functions are separated to be reusable across multiple modules, ensuring that common functionalities are centralized.

##### Relevant Technologies and Frameworks
- Python is the foundational language.
- The project is structured as a library offering both programmatic API and command-line tools.
- Testing is robust, with dedicated directories for unit tests across dataset operations and evaluation processes.

##### Final Composition
- Directly below, detail the Dataset module subdivided into its IO submodules (handling reading different formats) and the dataset operations (merging, splitting, remapping).
- Next, position the Evaluation module linked to the output of the Dataset processing layer.
- Finally, aggregate the Utility module (or components) that interact with both the Dataset and Evaluation modules.
- Testing and CI/CD aspects separately if needed, but these can be noted as peripheral to the main runtime architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    DS_CLI["CLI Module"]:::cli
    DS_Core["Dataset Module"]:::dataset
    DS_IO["Dataset IO Submodules"]:::dataset
    DS_Merge["Merging"]:::dataset
    DS_Split["Splitting"]:::dataset
    DS_Remap["Remapping Presets"]:::dataset
    DS_Eval["Evaluation Module"]:::evaluation
    DS_Util["Utility Module"]:::utility

    DS_CLI -->|"calls"| DS_Core
    DS_Core -->|"delegates_to"| DS_IO
    DS_IO -->|"processes"| DS_Merge
    DS_IO -->|"processes"| DS_Split
    DS_IO -->|"processes"| DS_Remap
    DS_Core -->|"provides_data_to"| DS_Eval
    DS_CLI -->|"calls"| DS_Eval
    DS_IO -->|"utilizes"| DS_Util
    DS_Eval -->|"utilizes"| DS_Util

    click DS_Core "https://github.com/xxii-ai/lours/tree/main/lours/dataset"
    click DS_IO "https://github.com/xxii-ai/lours/tree/main/lours/dataset/io"
    click DS_Merge "https://github.com/xxii-ai/lours/blob/main/lours/dataset/merge.py"
    click DS_Split "https://github.com/xxii-ai/lours/tree/main/lours/dataset/split"
    click DS_Remap "https://github.com/xxii-ai/lours/tree/main/lours/dataset/remap_presets"
    click DS_Eval "https://github.com/xxii-ai/lours/tree/main/lours/evaluation"
    click DS_CLI "https://github.com/xxii-ai/lours/tree/main/lours/cli"
    click DS_Util "https://github.com/xxii-ai/lours/tree/main/lours/utils"

    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef dataset fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef evaluation fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utility fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
