algomancy-quickstart 0.7.0__py3-none-any.whl

algomancy_quickstart/templates/etl_factory.py.jinja

@@ -0,0 +1,108 @@
+"""
+ETL (Extract, Transform, Load) Factory for {{ project_name }}.
+
+This module wires the data-processing pipeline:
+
+1. **Extract** — read data from files (defaults are picked from the schema
+   registry based on ``(extension, schema_type)``; hand-wire only when a
+   file needs non-default arguments, e.g. a custom CSV separator).
+2. **Validate** — schema, required-columns, and primary-key checks are
+   included by default. Override and call ``super()`` to add extras.
+3. **Transform** — clean / join / cascade-drop as needed.
+4. **Load** — :class:`DataSourceLoader` is the inherited default; only
+   override if you need a custom container.
+"""
+
+from typing import Dict
+
+from algomancy_data import ETLFactory, File, ValidationSequence
+from algomancy_data.extractor import ExtractionSequence
+
+# Uncomment the imports you actually use below.
+# from algomancy_data import (
+#     MissingValueValidator,
+#     UniqueValueValidator,
+#     ValidationSeverity,
+# )
+# from algomancy_data.extractor import CSVSingleExtractor
+# from algomancy_data.transformer import (
+#     CascadeDropTransformer,
+#     CleanTransformer,
+#     TransformationSequence,
+# )
+
+
+class {{ class_name }}ETLFactory(ETLFactory):
+    """
+    Factory for the {{ project_name }} ETL pipeline.
+
+    Demonstrates the post-M4 minimal pattern: call ``super()`` for each
+    stage to inherit the framework defaults, and only customise the bits
+    that are specific to this project.
+
+    TODO: Adapt each stage to your data.
+    """
+
+    def create_extraction_sequence(
+        self, files: Dict[str, File]
+    ) -> ExtractionSequence:
+        """
+        Default extraction defers to the schema registry: each registered
+        ``(extension, schema_type)`` pair maps to an extractor class, and
+        ``super()`` builds them straight from your schemas.
+
+        Override only for files that need non-default extractor parameters
+        (custom CSV separator, explicit XLSX sheet, …):
+
+            sequence = super().create_extraction_sequence(default_files)
+            sequence.add_extractor(
+                CSVSingleExtractor(
+                    file=files["my_file"],
+                    schema=self.get_schema("my_file"),
+                    separator=";",
+                    logger=self.logger,
+                )
+            )
+            return sequence
+        """
+        return super().create_extraction_sequence(files)
+
+    def create_validation_sequence(self) -> ValidationSequence:
+        """
+        ``super()`` already adds ``RequiredColumnsValidator`` +
+        ``SchemaValidator`` (+ ``PrimaryKeyValidator`` when any schema
+        declares a primary key). Add project-specific validators here.
+
+        Example:
+
+            sequence = super().create_validation_sequence()
+            sequence.add_validator(
+                MissingValueValidator(
+                    table="my_table",
+                    columns=["name", "email"],
+                    severity=ValidationSeverity.ERROR,
+                )
+            )
+            return sequence
+        """
+        return super().create_validation_sequence()
+
+    # def create_transformation_sequence(self) -> TransformationSequence:
+    #     """Default is a single ``NoopTransformer``. Override to add
+    #     project-specific transformations.
+    #
+    #     Example with the M7 cascade-drop transformer (use together with
+    #     ``foreign_key=("parent", "id")`` on the child schema column —
+    #     orphan child rows and, with ``parent_requires_child=True``,
+    #     childless parent rows are dropped):
+    #
+    #         sequence = TransformationSequence(logger=self.logger)
+    #         sequence.add_transformer(CleanTransformer(self.logger))
+    #         sequence.add_transformer(
+    #             CascadeDropTransformer(
+    #                 schemas=self.schemas, logger=self.logger
+    #             )
+    #         )
+    #         return sequence
+    #     """
+    #     return super().create_transformation_sequence()

algomancy_quickstart/templates/etl_factory_generated.py.jinja

@@ -0,0 +1,82 @@
+"""
+ETL Factory for {{ project_name }} with auto-generated extractors.
+
+This file was generated by algomancy-quickstart based on detected data files.
+Files that work with the schema registry's default extractors are wired
+via ``super().create_extraction_sequence(...)``; files needing custom
+extractor parameters (CSV separator, XLSX sheet name) are hand-wired.
+"""
+
+from typing import Dict
+
+from algomancy_data import (
+    ETLFactory,
+    File,
+    ValidationSequence,
+)
+from algomancy_data.extractor import (
+    ExtractionSequence,
+{% if needs_csv_extractor %}    CSVSingleExtractor,
+{% endif %}{% if needs_xlsx_single_extractor %}    XLSXSingleExtractor,
+{% endif %})
+
+# Import generated schemas
+from src.data_handling.generated_schemas import all_schemas  # noqa: F401
+
+
+class {{ class_name }}ETLFactory(ETLFactory):
+    """
+    ETL Factory with auto-generated extractors for detected data files.
+
+    Detected {{ file_count }} data file(s):
+    {% for file_info in files %}
+    - {{ file_info.file_name }} ({{ file_info.extension.value }})
+    {% endfor %}
+    """
+
+    def create_extraction_sequence(
+        self, files: Dict[str, File]
+    ) -> ExtractionSequence:
+        """Wire extractors for every detected file.
+
+        Files that match the registry's default ``(extension, schema_type)``
+        extractor are delegated to ``super()``; the rest are hand-wired.
+        """
+        # Registry-default extractors handle these files via ``super()``.
+        default_files = {
+            {% for file_info in default_files %}
+            "{{ file_info.file_name }}": files["{{ file_info.file_name }}"],
+            {% endfor %}
+        }
+        sequence = super().create_extraction_sequence(default_files)
+        {% for file_info in custom_files %}
+
+        # {{ file_info.file_name }} — non-default extractor parameters.
+        {% if file_info.extension.name == 'CSV' %}
+        sequence.add_extractor(
+            CSVSingleExtractor(
+                file=files["{{ file_info.file_name }}"],
+                schema=self.get_schema("{{ file_info.file_name }}"),
+                separator="{{ file_info.csv_separator }}",
+                logger=self.logger,
+            )
+        )
+        {% elif file_info.extension.name == 'XLSX' %}
+        sequence.add_extractor(
+            XLSXSingleExtractor(
+                file=files["{{ file_info.file_name }}"],
+                schema=self.get_schema("{{ file_info.file_name }}"),
+                sheet_name="{{ file_info.sheets_to_extract[0] }}",
+                logger=self.logger,
+            )
+        )
+        {% endif %}
+        {% endfor %}
+        return sequence
+
+    def create_validation_sequence(self) -> ValidationSequence:
+        """Inherit ``RequiredColumnsValidator + SchemaValidator
+        (+ PrimaryKeyValidator``) from the base class. Add custom validators
+        here, e.g. ``MissingValueValidator`` or ``UniqueValueValidator``.
+        """
+        return super().create_validation_sequence()

algomancy_quickstart/templates/generated_schemas.py.jinja

@@ -0,0 +1,55 @@
+"""
+Auto-generated schema definitions for {{ project_name }}.
+
+This file was generated by algomancy-quickstart based on detected data files.
+Edit freely — columns are declared with :class:`Column` (and
+:class:`ColumnGroup` for multi-sheet files), so adding ``optional=True``,
+``nullable=True``, ``unique=True``, or ``foreign_key=("table", "col")``
+to any column works out of the box.
+"""
+
+from algomancy_data import Column, ColumnGroup, DataType, FileExtension, Schema
+from algomancy_data.schema import SchemaType
+
+{% for file_info in files %}
+
+class {{ file_info.class_name }}Schema(Schema):
+    """
+    Schema for {{ file_info.file_name }} data file.
+
+    File: {{ file_info.file_path.name }}
+    Type: {{ file_info.extension.value }}
+    {% if file_info.is_multi_sheet %}Sheets: {{ file_info.sheet_names|join(', ') }}{% endif %}
+
+    Detected {{ file_info.total_columns }} column(s).
+    """
+
+    _FILENAME = "{{ file_info.file_name }}"
+    _EXTENSION = FileExtension.{{ file_info.extension.name }}
+    _SCHEMA_TYPE = SchemaType.{{ 'MULTI' if file_info.is_multi_sheet else 'SINGLE' }}
+
+    {% if file_info.is_multi_sheet %}
+    {% for sheet_name, columns in file_info.inferred_schemas.items() %}
+    {{ sheet_name|upper|replace(' ', '_')|replace('-', '_')|replace('.', '_') }} = ColumnGroup(
+        "{{ sheet_name }}",
+        [
+            {% for column_name, data_type in columns.items() %}
+            Column("{{ column_name }}", dtype=DataType.{{ data_type.name }}{% if column_name in file_info.primary_key_columns.get(sheet_name, []) %}, primary_key=True{% endif %}),
+            {% endfor %}
+        ],
+    )
+    {% endfor %}
+    {% else %}
+    {% for column_name, data_type in file_info.inferred_schemas['default'].items() %}
+    {{ column_name|upper|replace(' ', '_')|replace('-', '_')|replace('.', '_') }} = Column("{{ column_name }}", dtype=DataType.{{ data_type.name }}{% if column_name in file_info.primary_key_columns.get('default', []) %}, primary_key=True{% endif %})
+    {% endfor %}
+    {% endif %}
+
+{% endfor %}
+
+# All generated schemas — passed to ``CoreConfig(schemas=...)``.
+all_schemas = [
+    {% for file_info in files %}
+    {{ file_info.class_name }}Schema,
+    {% endfor %}
+]

algomancy_quickstart/templates/home_page.py.jinja

@@ -0,0 +1,65 @@
+"""
+Custom home page template for {{ project_name }}.
+
+This module defines a custom home page that can be tailored to provide
+a project-specific landing experience.
+"""
+
+from dash import html
+from algomancy_content import BaseHomePage
+
+
+class {{ class_name }}HomePage(BaseHomePage):
+    """
+    Custom home page implementation for {{ project_name }}.
+
+    TODO: Customize the home page layout and content.
+    """
+
+    @staticmethod
+    def create_content() -> html.Div:
+        """
+        Define the layout and static content of the home page.
+
+        Returns:
+            A Dash html.Div containing the page content.
+
+        TODO: Implement your custom landing page layout.
+        """
+        return html.Div(
+            [
+                html.H1("Welcome to {{ project_name }} Dashboard"),
+                html.P(
+                    "This is a custom home page generated by the Algomancy Quickstart."
+                ),
+                html.Hr(),
+                html.Div(
+                    [
+                        html.H3("Getting Started"),
+                        html.Ul(
+                            [
+                                html.Li("Customize this page in src/pages/home_page.py"),
+                                html.Li("Define your data schemas in src/data_handling/schemas.py"),
+                                html.Li("Implement your algorithm in src/templates/algorithm/"),
+                                html.Li("Configure KPIs in src/templates/kpi/"),
+                            ]
+                        ),
+                    ]
+                ),
+                # TODO: Add more components like graphs, summary statistics, or navigation links
+            ],
+            style={"padding": "20px"},
+        )
+
+    @staticmethod
+    def register_callbacks() -> None:
+        """
+        Register Dash callbacks for this page if needed.
+
+        TODO: Add any interactive behavior for the home page.
+        """
+        # Example:
+        # @app.callback(...)
+        # def update_something(...):
+        #     pass
+        pass

algomancy_quickstart/templates/kpi.py.jinja

@@ -0,0 +1,76 @@
+"""
+KPI (Key Performance Indicator) definitions for {{ project_name }}.
+
+This module defines the metrics used to evaluate algorithm performance.
+"""
+
+from algomancy_scenario import (
+    ImprovementDirection,
+    BaseKPI,
+    ScenarioResult,
+)
+from algomancy_utils import QUANTITIES, BaseMeasurement
+
+
+# Define measurement units
+# Available units: percentage, currency, dimensionless, time, etc.
+percent = QUANTITIES["percentage"]
+percent_measurement = BaseMeasurement(
+    percent["%"],
+    min_digits=1,
+    max_digits=3,
+    decimals=1
+)
+
+
+class {{ class_name }}KPI(BaseKPI):
+    """
+    KPI implementation for {{ project_name }}.
+
+    This class calculates a key performance metric from scenario results.
+
+    TODO: Customize the KPI calculation logic.
+    """
+
+    def __init__(self):
+        """
+        Initialize the KPI.
+
+        Args (passed to parent):
+            name: Display name for this KPI
+            direction: ImprovementDirection.HIGHER or ImprovementDirection.LOWER
+            measurement: BaseMeasurement defining the unit and format
+
+        TODO: Customize the name, direction, and measurement unit.
+        """
+        super().__init__(
+            "{{ class_name }} Metric",  # TODO: Set your KPI name
+            ImprovementDirection.HIGHER,  # TODO: Set HIGHER or LOWER
+            percent_measurement  # TODO: Choose appropriate measurement unit
+        )
+
+    def compute(self, result: ScenarioResult) -> float:
+        """
+        Calculate the KPI value from a scenario result.
+
+        Args:
+            result: The result object from an algorithm run.
+
+        Returns:
+            The computed KPI value as a float.
+
+        TODO: Implement your KPI calculation logic here.
+
+        Tips:
+        - Access result data via result.data_id
+        - You can load the data source if needed
+        - Return a single numeric value
+
+        Example:
+            data = DataSource.load(result.data_id)
+            # Calculate something from the data
+            return calculated_value
+        """
+        # TODO: Replace this with your actual KPI calculation
+        # Placeholder implementation:
+        return 50.0  # Return a dummy value

algomancy_quickstart/templates/main.py.jinja

@@ -0,0 +1,42 @@
+from algomancy_data import DataSource
+from algomancy_gui.configuration.appconfig import AppConfig
+from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
+from algomancy_gui.configuration.featureconfig import FeatureConfig
+from algomancy_gui.configuration.pageconfig import PageConfig
+from algomancy_gui.configuration.serverconfig import ServerConfig
+from algomancy_gui.configuration.stylingconfig import StylingConfig
+from algomancy_gui.gui_launcher import GuiLauncher
+from algomancy_scenario.core_configuration import CoreConfig
+from algomancy_content import (
+    PlaceholderETLFactory,
+    PlaceholderAlgorithm,
+    PlaceholderKPI,
+    PlaceholderSchema,
+)
+
+
+def main() -> None:
+    app_cfg = AppConfig(
+        core_config=CoreConfig(
+            etl_factory=PlaceholderETLFactory,
+            schemas=[PlaceholderSchema()],
+            kpi_templates={"placeholder": PlaceholderKPI},
+            algo_templates={"placeholder": PlaceholderAlgorithm},
+            data_object_type=DataSource,
+            autocreate=False,
+            autorun=False,
+            title="{{ title }}",
+        ),
+        server_config=ServerConfig(host="{{ host }}", port={{ port }}),
+        page_config=PageConfig(),
+        compare_page_config=ComparePageConfig(),
+        styling_config=StylingConfig(assets_path="assets"),
+        feature_config=FeatureConfig(),
+    )
+
+    app = GuiLauncher.build(app_cfg)
+    GuiLauncher.run(app=app, host=app_cfg.server.host, port=app_cfg.server.port)
+
+
+if __name__ == "__main__":
+    main()

algomancy_quickstart/templates/main_custom.py.jinja

@@ -0,0 +1,55 @@
+from algomancy_data import DataSource
+from algomancy_gui.configuration.appconfig import AppConfig
+from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
+from algomancy_gui.configuration.featureconfig import FeatureConfig
+from algomancy_gui.configuration.pageconfig import PageConfig
+from algomancy_gui.configuration.serverconfig import ServerConfig
+from algomancy_gui.configuration.stylingconfig import StylingConfig
+from algomancy_gui.gui_launcher import GuiLauncher
+from algomancy_scenario.core_configuration import CoreConfig
+
+# Import custom implementations
+from src.data_handling.etl_factory import {{ class_name }}ETLFactory
+from src.data_handling.schemas import all_schemas
+from src.templates.algorithm.{{ filename }}_algorithm import {{ class_name }}Algorithm
+from src.templates.kpi.{{ filename }}_kpi import {{ class_name }}KPI
+from src.pages.home_page import {{ class_name }}HomePage
+from src.pages.data_page import {{ class_name }}DataPage
+from src.pages.scenario_page import {{ class_name }}ScenarioPage
+from src.pages.compare_page import {{ class_name }}ComparePage
+from src.pages.overview_page import {{ class_name }}OverviewPage
+
+
+def main() -> None:
+    """Main entry point for the {{ title }} application."""
+
+    app_cfg = AppConfig(
+        core_config=CoreConfig(
+            etl_factory={{ class_name }}ETLFactory,
+            kpi_templates={"{{ filename }}": {{ class_name }}KPI},
+            algo_templates={"{{ class_name }}": {{ class_name }}Algorithm},
+            schemas=all_schemas,
+            data_object_type=DataSource,
+            autocreate=False,
+            autorun=False,
+            title="{{ title }}",
+        ),
+        server_config=ServerConfig(host="{{ host }}", port={{ port }}),
+        page_config=PageConfig(
+            home_page={{ class_name }}HomePage(),
+            data_page={{ class_name }}DataPage(),
+            scenario_page={{ class_name }}ScenarioPage(),
+            compare_page={{ class_name }}ComparePage(),
+#           overview_page={{ class_name }}OverviewPage(),  # uncomment to use {{ class_name }}OverviewPage
+        ),
+        compare_page_config=ComparePageConfig(),
+        styling_config=StylingConfig(assets_path="assets"),
+        feature_config=FeatureConfig(),
+    )
+
+    app = GuiLauncher.build(app_cfg)
+    GuiLauncher.run(app=app, host=app_cfg.server.host, port=app_cfg.server.port)
+
+
+if __name__ == "__main__":
+    main()

algomancy_quickstart/templates/main_generated_etl.py.jinja

@@ -0,0 +1,72 @@
+from algomancy_data import DataSource
+from algomancy_gui.configuration.appconfig import AppConfig
+from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
+from algomancy_gui.configuration.featureconfig import FeatureConfig
+from algomancy_gui.configuration.pageconfig import PageConfig
+from algomancy_gui.configuration.serverconfig import ServerConfig
+from algomancy_gui.configuration.stylingconfig import StylingConfig
+from algomancy_gui.gui_launcher import GuiLauncher
+from algomancy_scenario.core_configuration import CoreConfig
+
+# Import generated ETL factory and schemas
+from src.data_handling.etl_factory import {{ class_name }}ETLFactory
+from src.data_handling.generated_schemas import all_schemas
+
+{% if has_custom_implementations %}
+# Import custom implementations
+from src.templates.algorithm.{{ filename }}_algorithm import {{ class_name }}Algorithm
+from src.templates.kpi.{{ filename }}_kpi import {{ class_name }}KPI
+from src.pages.home_page import {{ class_name }}HomePage
+from src.pages.data_page import {{ class_name }}DataPage
+from src.pages.scenario_page import {{ class_name }}ScenarioPage
+from src.pages.compare_page import {{ class_name }}ComparePage
+from src.pages.overview_page import {{ class_name }}OverviewPage
+{% else %}
+# Import placeholder KPI and Algorithm
+# TODO: Update these imports when you create custom implementations
+from algomancy_content import PlaceholderKPI, PlaceholderAlgorithm
+{% endif %}
+
+
+def main() -> None:
+    """Main entry point for the {{ title }} application."""
+
+    app_cfg = AppConfig(
+        core_config=CoreConfig(
+            etl_factory={{ class_name }}ETLFactory,
+            schemas=all_schemas,
+            {% if has_custom_implementations %}
+            kpi_templates={"{{ filename }}": {{ class_name }}KPI},
+            algo_templates={"{{ class_name }}": {{ class_name }}Algorithm},
+            {% else %}
+            kpi_templates={"placeholder": PlaceholderKPI},
+            algo_templates={"placeholder": PlaceholderAlgorithm},
+            {% endif %}
+            data_object_type=DataSource,
+            autocreate=False,
+            autorun=False,
+            title="{{ title }}",
+        ),
+        server_config=ServerConfig(host="{{ host }}", port={{ port }}),
+        {% if has_custom_implementations %}
+        page_config=PageConfig(
+            home_page={{ class_name }}HomePage(),
+            data_page={{ class_name }}DataPage(),
+            scenario_page={{ class_name }}ScenarioPage(),
+            compare_page={{ class_name }}ComparePage(),
+#           overview_page={{ class_name }}OverviewPage(),  # uncomment to use {{ class_name }}OverviewPage
+        ),
+        {% else %}
+        page_config=PageConfig(),
+        {% endif %}
+        compare_page_config=ComparePageConfig(),
+        styling_config=StylingConfig(assets_path="assets"),
+        feature_config=FeatureConfig(),
+    )
+
+    app = GuiLauncher.build(app_cfg)
+    GuiLauncher.run(app=app, host=app_cfg.server.host, port=app_cfg.server.port)
+
+
+if __name__ == "__main__":
+    main()

algomancy_quickstart/templates/main_with_styling.py.jinja

@@ -0,0 +1,83 @@
+from algomancy_data import DataSource
+from algomancy_gui.configuration.appconfig import AppConfig
+from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
+from algomancy_gui.configuration.featureconfig import FeatureConfig
+from algomancy_gui.configuration.pageconfig import PageConfig
+from algomancy_gui.configuration.serverconfig import ServerConfig
+from algomancy_gui.gui_launcher import GuiLauncher
+from algomancy_scenario.core_configuration import CoreConfig
+
+{% if has_generated_etl %}
+# Import generated ETL factory and schemas
+from src.data_handling.etl_factory import {{ class_name }}ETLFactory
+from src.data_handling.generated_schemas import all_schemas
+{% else %}
+# Import placeholder implementations
+from algomancy_content import PlaceholderETLFactory, PlaceholderSchema
+{% endif %}
+
+{% if has_custom_implementations %}
+# Import custom implementations
+from src.templates.algorithm.{{ filename }}_algorithm import {{ class_name }}Algorithm
+from src.templates.kpi.{{ filename }}_kpi import {{ class_name }}KPI
+from src.pages.home_page import {{ class_name }}HomePage
+from src.pages.data_page import {{ class_name }}DataPage
+from src.pages.scenario_page import {{ class_name }}ScenarioPage
+from src.pages.compare_page import {{ class_name }}ComparePage
+from src.pages.overview_page import {{ class_name }}OverviewPage
+{% else %}
+# Import placeholder KPI and Algorithm
+from algomancy_content import PlaceholderKPI, PlaceholderAlgorithm
+{% endif %}
+
+# Import styling configuration
+from src.styling_config import app_styling
+
+
+def main() -> None:
+    """Main entry point for the {{ title }} application."""
+
+    app_cfg = AppConfig(
+        core_config=CoreConfig(
+            {% if has_generated_etl %}
+            etl_factory={{ class_name }}ETLFactory,
+            schemas=all_schemas,
+            {% else %}
+            etl_factory=PlaceholderETLFactory,
+            schemas=[PlaceholderSchema()],
+            {% endif %}
+            {% if has_custom_implementations %}
+            kpi_templates={"{{ filename }}": {{ class_name }}KPI},
+            algo_templates={"{{ class_name }}": {{ class_name }}Algorithm},
+            {% else %}
+            kpi_templates={"placeholder": PlaceholderKPI},
+            algo_templates={"placeholder": PlaceholderAlgorithm},
+            {% endif %}
+            data_object_type=DataSource,
+            autocreate=False,
+            autorun=False,
+            title="{{ title }}",
+        ),
+        server_config=ServerConfig(host="{{ host }}", port={{ port }}),
+        {% if has_custom_implementations %}
+        page_config=PageConfig(
+            home_page={{ class_name }}HomePage(),
+            data_page={{ class_name }}DataPage(),
+            scenario_page={{ class_name }}ScenarioPage(),
+            compare_page={{ class_name }}ComparePage(),
+#           overview_page={{ class_name }}OverviewPage(),  # uncomment to use {{ class_name }}OverviewPage
+        ),
+        {% else %}
+        page_config=PageConfig(),
+        {% endif %}
+        compare_page_config=ComparePageConfig(),
+        styling_config=app_styling,
+        feature_config=FeatureConfig(),
+    )
+
+    app = GuiLauncher.build(app_cfg)
+    GuiLauncher.run(app=app, host=app_cfg.server.host, port=app_cfg.server.port)
+
+
+if __name__ == "__main__":
+    main()