# idsia/sacred architecture

> Architecture diagram of the GitHub repository idsia/sacred, 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/idsia/sacred
- Repository: https://github.com/idsia/sacred

## Overview

##### Main Components
- Experiment Engine: The core part of Sacred that runs the experiments. Key files include sacred/experiment.py, sacred/run.py, and modules for configuration management (in sacred/config/…) and command-line parsing (sacred/arg_parser.py and sacred/commandline_options.py).
- Configuration Management: Handles the use of config scopes, captured functions, configuration injection, and custom containers. All of these components reside in the sacred/config directory (and related modules such as sacred/config/config_dict.py, sacred/config/config_files.py, etc.).
- Observers: Modular logging components that save experiment metadata and results into various storage systems. They can log to file storage, MongoDB, Google Cloud Storage, S3, SQL databases, or third-party tools via integrations. Look into sacred/observers/ for the various observer implementations.
- Command-Line Interface (CLI): Provides a powerful way to launch experiments and adjust their parameters. This functionality is spread between sacred/arg_parser.py, sacred/commandline_options.py, and integrated within sacred/run.py.
- Utilities and Support: Additional modules—such as randomness control (sacred/randomness.py), logging (sacred/metrics_logger.py), and utilities to capture standard output—support the overall functionality.

##### Relationships and Interactions
- The User (or developer) initiates an experiment via the CLI.
- The CLI parses parameters and passes them to the Experiment Engine.
- The Experiment Engine loads the experiment configuration using the config management modules (leveraging config scopes and the injection mechanism).
- During execution, the Experiment Engine interacts with one or more Observer components to record metadata, configurations, metrics, and results. These observers can be thought of as pluggable “loggers” that forward data to external systems and dashboards.
- When necessary, utilities like randomness controls ensure that experiments are reproducible.

##### Architectural Patterns and Design Principles
- Modularity & Extensibility: Sacred’s architecture is designed with modular components (the core experiment engine, configuration management, and multiple observers) that can be extended or replaced based on user needs.
- Separation of Concerns: The configuration system, experiment runner, and logging/observation modules are clearly separated, which aids in maintainability and testability.
- Injection & Dynamic Configuration: The system extensively uses dependency injection (particularly with configuration parameters) to keep experiment functions decoupled from the infrastructure needed to run them.
- Plugin (Observer) Architecture: Allows for flexible logging; new observers for different data stores or front-ends (like Omniboard, Incense, Sacredboard) can be added independently.

##### Relevant Technologies, Frameworks, or Libraries
- Python (core language)
- Optional dependencies: numpy and pymongo (for randomness control and MongoDB logging)
- External Frontends/Dashboards: Omniboard, Incense, Sacredboard, Neptune, etc.
- Testing Frameworks: pytest and tox (for automated testing across multiple Python versions)

##### Specific Elements to Be Included
- Clear Labels for Each Component:
- “CLI/Command-Line Parser”
- “Experiment Engine”
- “Configuration Manager”
- “Observers” (with sub-labels for File, MongoDB, etc.)
- “Utilities (Randomness, Metrics, etc.)”
- From CLI to Experiment Engine (input parameters)
- From Experiment Engine to Configuration Manager (request for config injection)
- From Experiment Engine to Observers (sending log data, metadata, and results)
- Feedback loops (if any) between Observers and Experiment Engine (e.g., error handling or dynamic adjustments)
- Visual Distinctions:
- Annotations:
- Brief notes beside each component explaining its primary function.
- Design patterns (like dependency injection for configuration and plugin architecture for observers).

##### Final Assembly
- Flow downward into the core experiment engine which incorporates configuration management.
- Branch off to a collection of observer components that “listen” to the experiment’s execution and record details.
- Optionally, annotate external systems (like MongoDB, file systems, or external dashboards) that connect through observers.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User/Developer"):::user

    %% CLI Subgraph
    subgraph "CLI/Command-Line Interface"
        CLI_ARG("CLI: arg_parser.py"):::cli
        CLI_OPTIONS("CLI: commandline_options.py"):::cli
        CLI_ARG --> CLI_OPTIONS
    end

    %% Experiment Engine Subgraph
    subgraph "Experiment Engine"
        EXPERIMENT("Engine: experiment.py"):::engine
        RUN("Engine: run.py"):::engine
        COMMANDS("Engine: commands.py"):::engine
        EXPERIMENT --> RUN
        RUN --> COMMANDS
    end

    %% Configuration Management Subgraph
    subgraph "Configuration Management"
        CONFIG_DIR("Config Directory"):::config
        CONFIG_DICT("config_dict.py"):::config
        CONFIG_FILES("config_files.py"):::config
        CONFIG_SCOPE("config_scope.py"):::config
        CONFIG_SUMMARY("config_summary.py"):::config
        CUSTOM_CONTAINERS("custom_containers.py"):::config
        SIGNATURE("signature.py"):::config
        CONFIG_UTILS("utils.py"):::config
        CONFIG_DIR --> CONFIG_DICT
        CONFIG_DICT --> CONFIG_FILES
        CONFIG_FILES --> CONFIG_SCOPE
        CONFIG_SCOPE --> CONFIG_SUMMARY
        CONFIG_SUMMARY --> CUSTOM_CONTAINERS
        CUSTOM_CONTAINERS --> SIGNATURE
        SIGNATURE --> CONFIG_UTILS
    end

    %% Observers Subgraph
    subgraph "Observers"
        OBS_DIR("Observers Directory"):::observer
        FILE_STORAGE("file_storage.py"):::observer
        GCS_OBSERVER("gcs_observer.py"):::observer
        MONGO("mongo.py"):::observer
        S3_OBSERVER("s3_observer.py"):::observer
        SQL("sql.py"):::observer
        OBS_DIR --> FILE_STORAGE
        FILE_STORAGE --> GCS_OBSERVER
        GCS_OBSERVER --> MONGO
        MONGO --> S3_OBSERVER
        S3_OBSERVER --> SQL
    end

    %% Utilities Subgraph
    subgraph "Utilities and Support"
        RANDOMNESS("randomness.py"):::utility
        METRICS_LOGGER("metrics_logger.py"):::utility
        STDOUT("stdout_capturing.py"):::utility
        RANDOMNESS --> METRICS_LOGGER
        METRICS_LOGGER --> STDOUT
    end

    %% External Connections
    User --> CLI_ARG
    CLI_OPTIONS --> EXPERIMENT
    EXPERIMENT --> CONFIG_DIR
    EXPERIMENT --> OBS_DIR
    EXPERIMENT --> RANDOMNESS

    %% Click Events
    click CLI_ARG "https://github.com/idsia/sacred/blob/master/sacred/arg_parser.py"
    click CLI_OPTIONS "https://github.com/idsia/sacred/blob/master/sacred/commandline_options.py"
    click EXPERIMENT "https://github.com/idsia/sacred/blob/master/sacred/experiment.py"
    click RUN "https://github.com/idsia/sacred/blob/master/sacred/run.py"
    click COMMANDS "https://github.com/idsia/sacred/blob/master/sacred/commands.py"
    click CONFIG_DIR "https://github.com/idsia/sacred/tree/master/sacred/config/"
    click CONFIG_DICT "https://github.com/idsia/sacred/blob/master/sacred/config/config_dict.py"
    click CONFIG_FILES "https://github.com/idsia/sacred/blob/master/sacred/config/config_files.py"
    click CONFIG_SCOPE "https://github.com/idsia/sacred/blob/master/sacred/config/config_scope.py"
    click CONFIG_SUMMARY "https://github.com/idsia/sacred/blob/master/sacred/config/config_summary.py"
    click CUSTOM_CONTAINERS "https://github.com/idsia/sacred/blob/master/sacred/config/custom_containers.py"
    click SIGNATURE "https://github.com/idsia/sacred/blob/master/sacred/config/signature.py"
    click CONFIG_UTILS "https://github.com/idsia/sacred/blob/master/sacred/config/utils.py"
    click OBS_DIR "https://github.com/idsia/sacred/tree/master/sacred/observers/"
    click FILE_STORAGE "https://github.com/idsia/sacred/blob/master/sacred/observers/file_storage.py"
    click GCS_OBSERVER "https://github.com/idsia/sacred/blob/master/sacred/observers/gcs_observer.py"
    click MONGO "https://github.com/idsia/sacred/blob/master/sacred/observers/mongo.py"
    click S3_OBSERVER "https://github.com/idsia/sacred/blob/master/sacred/observers/s3_observer.py"
    click SQL "https://github.com/idsia/sacred/blob/master/sacred/observers/sql.py"
    click RANDOMNESS "https://github.com/idsia/sacred/blob/master/sacred/randomness.py"
    click METRICS_LOGGER "https://github.com/idsia/sacred/blob/master/sacred/metrics_logger.py"
    click STDOUT "https://github.com/idsia/sacred/blob/master/sacred/stdout_capturing.py"

    %% Styles
    classDef user fill:#FFD580,stroke:#333,stroke-width:2px;
    classDef cli fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef engine fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef observer fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef utility fill:#D5DBDB,stroke:#333,stroke-width:2px;
```
