### Install uv and Set Up Virtual Environment

Source: https://github.com/mloda-ai/mloda-registry/blob/main/CLAUDE.md

Installs the uv package manager, creates a virtual environment, activates it, and installs project dependencies. This is the initial setup for development if not using a devcontainer.

```bash
# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Create virtual environment
uv venv

# 3. Activate the environment
source .venv/bin/activate

# 4. Install dependencies
uv sync --all-extras
```

--------------------------------

### Development Setup with uv

Source: https://github.com/mloda-ai/mloda-registry/blob/main/README.md

Sets up the development environment using uv for virtual environment creation and dependency installation. It also includes running all checks via tox.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv && source .venv/bin/activate && uv sync --all-extras

# Run all checks via tox
uv run tox
```

--------------------------------

### Install uv

Source: https://github.com/mloda-ai/mloda-registry/blob/main/CONTRIBUTING.md

Install the uv dependency manager using the provided installation script.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv and Set Up Virtual Environment

Source: https://github.com/mloda-ai/mloda-registry/blob/main/AGENTS.md

Installs the 'uv' package manager, creates a virtual environment, activates it, and installs all project dependencies. Run 'source .venv/bin/activate' and 'uv sync --all-extras' for subsequent sessions.

```bash
# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Create virtual environment
uv venv

# 3. Activate the environment
source .venv/bin/activate

# 4. Install dependencies
uv sync --all-extras
```

```bash
source .venv/bin/activate
uv sync --all-extras
```

--------------------------------

### Set Up Virtual Environment and Install Dependencies

Source: https://github.com/mloda-ai/mloda-registry/blob/main/CONTRIBUTING.md

Create a virtual environment using uv, activate it, and install all project dependencies including extras.

```bash
uv venv
source .venv/bin/activate
uv sync --all-extras
```

--------------------------------

### Use Installed Plugins and Features

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/01-use-existing-plugin.md

Discover all installed plugins and run features using the PluginLoader and mloda.run_all. This is the standard way to execute features from installed plugins.

```python
from mloda.user import PluginLoader, mloda, Feature

# Auto-discover installed plugins
PluginLoader.all()

# Use features from the plugin
result = mloda.run_all([Feature("example_feature")])
```

--------------------------------

### Install Community Plugins

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/06-publish-to-community.md

After your plugin is merged, it can be installed using pip.

```bash
pip install mloda-community
```

--------------------------------

### Install Plugin Locally for Development

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/04-create-plugin-package.md

Install the plugin in editable mode for local development and testing. This command also installs development dependencies.

```bash
uv venv && source .venv/bin/activate && uv pip install -e ".[dev]" && tox
```

--------------------------------

### Import Plugin from Installed Subdirectory

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/05-share-with-team.md

After installing a specific subdirectory, import components from it using their respective Python paths.

```python
from acme.feature_groups.scoring import CustomerScoring
```

--------------------------------

### Complete Example: MyFramework to PyArrow Transformer

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/08-framework-transformer.md

This example demonstrates how to create a custom transformer for converting data between a hypothetical 'MyFramework' and PyArrow. It includes the necessary class methods for framework identification and bidirectional data transformation.

```python
from typing import Any
from mloda.provider import BaseTransformer

try:
    import my_framework as mf
except ImportError:
    mf = None

try:
    import pyarrow as pa
except ImportError:
    pa = None


class MyPyArrowTransformer(BaseTransformer):
    """Transformer: MyFramework ↔ PyArrow."""

    @classmethod
    def framework(cls) -> Any:
        return mf.DataFrame if mf else NotImplementedError

    @classmethod
    def other_framework(cls) -> Any:
        return pa.Table if pa else NotImplementedError

    @classmethod
    def import_fw(cls) -> None:
        import my_framework

    @classmethod
    def import_other_fw(cls) -> None:
        import pyarrow

    @classmethod
    def transform_fw_to_other_fw(cls, data: Any) -> Any:
        return data.to_arrow()  # MyFramework → PyArrow

    @classmethod
    def transform_other_fw_to_fw(cls, data: Any, framework_connection_object: Any | None = None) -> Any:
        return mf.from_arrow(data)  # PyArrow → MyFramework
```

--------------------------------

### Install Plugin Locally

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/04-create-plugin-package.md

Install the plugin locally using pip in editable mode. This is useful for testing the plugin as a dependency.

```bash
pip install -e .
```

--------------------------------

### Sessionization Usage Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/15-sessionization.md

Demonstrates how to use SessionizationFeatureGroup in Python with MLODA, specifying sessionization features and partitioning by user ID.

```python
from mloda.user import Feature, Options, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("ts__sessionize_30_minute", Options(context={"partition_by": ["user_id"]})),
]
result = mloda.run_all(features, compute_frameworks={"PandasDataFrame"})
```

--------------------------------

### Verify Published Packages

Source: https://github.com/mloda-ai/mloda-registry/blob/main/memory-bank/release-pypi.md

After publishing, run these tox environments to confirm that the packages can be installed correctly. This includes verifying core installations and any extra features.

```bash
tox -e verify-published
```

```bash
tox -e verify-extras
```

--------------------------------

### Install Individual mloda Package from Git

Source: https://github.com/mloda-ai/mloda-registry/blob/main/README.md

Installs a specific mloda package directly from a Git repository. Replace the subdirectory path with the actual location of the package within the repository.

```bash
pip install "git+https://github.com/mloda-ai/mloda-registry.git#subdirectory=mloda/community/feature_groups/example/example_b"
```

--------------------------------

### Import Community Plugin

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/06-publish-to-community.md

Once installed, users can import your plugin directly.

```python
from mloda.community.feature_groups.your_plugin import YourFeatureGroup
```

--------------------------------

### Sessionization Semantics Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/15-sessionization.md

Illustrates session ID assignment with a 30-minute threshold for a user's events, showing how gaps greater than the threshold initiate new sessions.

```text
ts | gap from prev | session
10:00 | (first) | 0
10:20 | 20 min | 0
10:50 | 30 min (== threshold) | 0
11:30 | 40 min (> threshold) | 1
11:35 | 5 min | 1
```

--------------------------------

### Activate Environment and Sync Dependencies

Source: https://github.com/mloda-ai/mloda-registry/blob/main/CLAUDE.md

Activates an existing virtual environment and synchronizes dependencies. This command is used for subsequent development sessions after the initial setup.

```bash
source .venv/bin/activate
uv sync --all-extras
```

--------------------------------

### Base Package Optional Dependencies Configuration

Source: https://github.com/mloda-ai/mloda-registry/blob/main/memory-bank/package-hierarchy.md

Example TOML configuration for a base package defining its name, dependencies, and optional dependencies for variants.

```toml
# Base package has optional aggregation
[project]
name = "mloda-community-example"
dependencies = ["mloda>=X.Y.Z"]

[project.optional-dependencies]
dev = ["mloda-testing", "pytest"]  # from defaults
all = ["mloda-community-example-a", "mloda-community-example-b"]
```

--------------------------------

### Package Configuration with Extra Optional Dependencies

Source: https://github.com/mloda-ai/mloda-registry/blob/main/memory-bank/pyproject-generation.md

Example of configuring a package with additional optional dependencies beyond the default development dependencies.

```toml
[packages.mloda-community-example]
description = "Example community plugin"
dependencies = ["mloda>=X.Y.Z"]
path = "mloda/community/feature_groups/example"
optional_dependencies = { all = ["mloda-community-example-a", "mloda-community-example-b"] }
# dev = ["mloda-testing", "pytest"] added from defaults
```

--------------------------------

### MLODA String Feature Usage Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/09-string-operations.md

Demonstrates how to define and run string operations using MLODA's Feature and mloda.run_all. No additional options are required.

```python
from mloda.user import Feature, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("name__upper"),
    Feature("description__trim"),
    Feature("name__length"),
]

result = mloda.run_all(features, compute_frameworks={"PandasDataFrame"})
```

--------------------------------

### Wire Up Framework Test Class (Pandas Example)

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/10-adding-new-operation.md

Create a test file for each framework, inheriting from the framework's test mixin and the operation's test base. This class defines the specific implementation class to be tested.

```python
# tests/test_pandas.py
from typing import Any
import pytest

pytest.importorskip("pandas")

from mloda.community.feature_groups.data_operations.{category}.{your_op}.pandas_{your_op} import (
    PandasYourOp,
)
from mloda.testing.feature_groups.data_operations.mixins.pandas import PandasTestMixin
from mloda.testing.feature_groups.data_operations.{category}.{your_op}.{your_op} import (
    YourOpTestBase,
)


class TestPandasYourOp(PandasTestMixin, YourOpTestBase):
    @classmethod
    def implementation_class(cls) -> Any:
        return PandasYourOp
```

--------------------------------

### MLODA Feature Binning Usage Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/05-binning.md

Example of how to define and run binning features using MLODA. It demonstrates creating Feature objects for both equal-width and quantile binning and executing them with the Pandas DataFrame compute framework.

```python
from mloda.user import Feature, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("value_int__bin_5"),    # equal-width, 5 bins
    Feature("value_int__qbin_4"),   # quartiles
]

result = mloda.run_all(features, compute_frameworks={"PandasDataFrame"})
```

--------------------------------

### Zero Dependency Data Format Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/04-zero-dependency.md

Illustrates the row-based data format using a list of dictionaries, suitable for zero dependency frameworks.

```python
# Row-based: List[Dict[str, Any]]
[{"col1": 1, "col2": "a"}, {"col1": 2, "col2": "b"}]
```

--------------------------------

### Multi-Table Join Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/08-links-joins.md

Combines a CustomerFeatures group with an OrderAggregation group using a left join.

```python
link = Link.left(
    left=JoinSpec(CustomerFeatures, Index(("customer_id",))),
    right=JoinSpec(OrderAggregation, Index(("customer_id",))),
)

features = [
    Feature("customer_name"),
    Feature("total_orders", link=link),
]
```

--------------------------------

### Tag a Release and Push to Origin

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/05-share-with-team.md

Tag a specific commit as a release version and push the tag to the remote repository to enable versioned installations.

```bash
git tag v1.0.0
git push origin v1.0.0
```

--------------------------------

### Resample Usage Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/14-resample.md

Demonstrates how to define and run a resample operation using Python. Requires 'ts' as the time column and 'symbol' for partitioning.

```python
from mloda.user import Feature, Options, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("price__resample_1_hour_mean", Options(context={"time_column": "ts", "partition_by": ["symbol"]})),
]
result = mloda.run_all(features, compute_frameworks={"PandasDataFrame"})
```

--------------------------------

### Implement Stateless Eager Framework

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/01-stateless-eager.md

Example of a stateless eager compute framework using a hypothetical 'my_library'. Implement `is_available`, `expected_data_framework`, `merge_engine`, `filter_engine`, and `transform` methods.

```python
from typing import Any
from mloda.provider import ComputeFramework, BaseMergeEngine, BaseFilterEngine

try:
    import my_library as ml
except ImportError:
    ml = None


class MyEagerFramework(ComputeFramework):
    """Stateless eager framework for MyLibrary."""

    @staticmethod
    def is_available() -> bool:
        return ml is not None

    @classmethod
    def expected_data_framework(cls) -> Any:
        return ml.DataFrame  # Return TYPE, not instance

    @classmethod
    def merge_engine(cls) -> type[BaseMergeEngine]:
        from my_plugin.my_merge_engine import MyMergeEngine
        return MyMergeEngine

    @classmethod
    def filter_engine(cls) -> type[BaseFilterEngine]:
        from my_plugin.my_filter_engine import MyFilterEngine
        return MyFilterEngine

    def transform(self, data: Any, feature_names: set[str]) -> Any:
        if isinstance(data, dict):
            return ml.DataFrame.from_dict(data)
        raise ValueError(f"Data type {type(data)} not supported")
```

--------------------------------

### Feature Request Examples with FeatureChainParserMixin

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/14-feature-matching.md

Illustrates how to request features when using FeatureChainParserMixin, showing both string-based extraction from the feature name and configuration-based specification via Options.

```python
# String-based: method extracted from name
Feature("input__algo_b_transformed")

# Config-based: method specified in options
Feature("my_output", Options(context={"my_method": "algo_b", "in_features": "input"}))
```

--------------------------------

### Apply Filters in Data Source Query

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/15-filter-concepts.md

Example of how a data source can dynamically build a SQL query by iterating through applied filters. This allows for predicate pushdown.

```python
@classmethod
def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
    query = "SELECT * FROM table WHERE 1=1"
    for f in features.filters:
        if f.filter_type == "equal":
            query += f" AND {f.filter_feature.name} = {f.parameter.value}"
        elif f.filter_type == "range":
            query += f" AND {f.filter_feature.name} BETWEEN {f.parameter.min_value} AND {f.parameter.max_value}"
    # Execute query...
```

--------------------------------

### Fork and Clone mloda-registry

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/07-contribute-to-official.md

Clone the mloda-registry repository to your local machine to start contributing. This command forks the repository and then clones your fork.

```bash
gh repo fork mloda-ai/mloda-registry --clone
cd mloda-registry
```

--------------------------------

### Minimal Data Operation Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/01-overview.md

This snippet demonstrates how to define and run multiple data operations, including aggregation, percentile, and string transformations, using the mloda library. It shows how to specify compute frameworks and use options like 'partition_by'.

```python
from mloda.user import Feature, Options, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("value_int__sum_agg", Options(context={"partition_by": ["region"]})),
    Feature("value_int__p95_percentile", Options(context={"partition_by": ["region"]})),
    Feature("name__upper"),
]

result = mloda.run_all(features, compute_frameworks={"PandasDataFrame"})
```

--------------------------------

### Adding Polars-Lazy Framework for Rank Operations

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/04-supported-ops.md

This example demonstrates how to add a new framework implementation (Polars-lazy) for rank operations. It includes overriding `implementation_class` and `supported_rank_types` to declare the supported rank functions.

```python
from mloda.testing.feature_groups.data_operations.mixins.polars_lazy import PolarsLazyTestMixin
from mloda.testing.feature_groups.data_operations.row_preserving.rank.rank import RankTestBase

class TestPolarsLazyRank(PolarsLazyTestMixin, RankTestBase):
    @classmethod
    def implementation_class(cls):
        return PolarsLazyRank

    @classmethod
    def supported_rank_types(cls) -> set[str]:
        return {"row_number", "rank", "dense_rank", "percent_rank"}
        # ntile_N omitted if Polars version lacks a clean NTILE equivalent
```

--------------------------------

### Basic Realtime Execution with Prepare and Run

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/24-realtime.md

Prepare the execution plan once, then run it multiple times with different input data. This is ideal for serving features repeatedly.

```python
from mloda.user import PluginLoader, mloda, Feature

PluginLoader.all()

# 1. Prepare once (expensive — builds execution plan)
session = mloda.prepare(
    [Feature("my_feature")],
    compute_frameworks=["PandasDataFrame"],
)

# 2. Run many times (cheap — reuses plan)
result_1 = session.run(api_data={"MyKey": {"col": [1, 2]}})
result_2 = session.run(api_data={"MyKey": {"col": [3, 4]}})

```

--------------------------------

### Install Specific Version of mloda Plugin

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/05-share-with-team.md

Team members can install a specific version of your mloda plugin by appending the tag to the Git URL in the pip install command.

```bash
pip install git+ssh://git@github.com/mycompany/acme-plugins.git@v1.0.0
```

--------------------------------

### Create Features: String-based vs. Configuration-based

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/03-chained-features.md

Demonstrates how to instantiate features using both the traditional string-based naming convention and the modern configuration-based approach with Options.

```python
# String-based (traditional)
Feature("income__mean_imputed")

# Configuration-based (modern) - enables complex types, dynamic creation
Feature("imputed_income", Options(context={"imputation_method": "mean", "in_features": "income"}))
```

--------------------------------

### Install Specific Subdirectory from Private Git Repository

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/05-share-with-team.md

Install a specific subdirectory or feature group from a private Git repository by specifying the subdirectory in the pip install command.

```bash
pip install "acme-scoring @ git+ssh://git@github.com/mycompany/acme-plugins.git#subdirectory=acme/feature_groups/scoring"
```

--------------------------------

### List All Compute Frameworks

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/02-discover-plugins.md

Retrieve and print documentation for all available compute frameworks, including their name, description, expected data framework, and whether they have a merge engine.

```python
from mloda.steward import get_compute_framework_docs

# Get available frameworks
for cfw in get_compute_framework_docs():
    print(f"{cfw.name}: {cfw.description}")
    print(f"  Data framework: {cfw.expected_data_framework}")
    print(f"  Has merge engine: {cfw.has_merge_engine}")
```

--------------------------------

### List All Compute Frameworks (Including Unavailable)

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/02-discover-plugins.md

Retrieve documentation for all compute frameworks, including those that are not currently available in the environment.

```python
from mloda.steward import get_compute_framework_docs

# Include unavailable frameworks
all_frameworks = get_compute_framework_docs(available_only=False)
```

--------------------------------

### Initializing DataAccessCollection with Named Handles

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/17-data-connection-matching.md

Demonstrates how to initialize `DataAccessCollection` with named resources using a dictionary for connections and files. Shows how to retrieve available handles.

```python
from mloda.user import DataAccessCollection

dac = DataAccessCollection(
    connections={"warehouse": warehouse_conn, "reporting": reporting_conn},
    files={"tx": "/data/transactions.parquet"},
)
dac.handles()  # {'warehouse': 'connection', 'reporting': 'connection', 'tx': 'file'}
```

--------------------------------

### List All Extenders

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/02-discover-plugins.md

Retrieve and print documentation for all loaded extenders, including their name, description, and what they wrap.

```python
from mloda.steward import get_extender_docs

# Get all extenders
for ext in get_extender_docs():
    print(f"{ext.name}: {ext.description}")
    print(f"  Wraps: {ext.wraps}")
```

--------------------------------

### Install mloda Plugin from Private Git Repository

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/05-share-with-team.md

Team members can install your mloda plugin directly from a private Git repository using pip. Ensure they have SSH access to the repository.

```bash
pip install git+ssh://git@github.com/mycompany/acme-plugins.git
```

--------------------------------

### Example Implementation of _extract_column_data_type

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/10-data-type-extraction.md

A practical example demonstrating how to implement _extract_column_data_type by inspecting pandas DataFrame dtypes and mapping them to mloda DataTypes. Replace placeholder predicates with actual library type checks.

```python
from typing import Any

from mloda.user import DataType


def _extract_column_data_type(self, data: Any, column_name: str) -> DataType | None:
    if column_name not in data.columns:
        return None

    dtype = data[column_name].dtype

    if _is_int32(dtype):
        return DataType.INT32
    if _is_integer(dtype):
        return DataType.INT64
    if _is_float32(dtype):
        return DataType.FLOAT
    if _is_float(dtype):
        return DataType.DOUBLE
    if _is_bool(dtype):
        return DataType.BOOLEAN
    if _is_string(dtype):
        return DataType.STRING

    return None
```

--------------------------------

### Realtime Execution with Prepared Plan

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/01-use-existing-plugin.md

Prepare an execution plan once and reuse it for repeated calls with fresh data using mloda.prepare and session.run. This optimizes performance for frequent, similar requests.

```python
from mloda.user import PluginLoader, mloda, Feature

PluginLoader.all()

session = mloda.prepare([Feature("my_feature")], compute_frameworks=["PandasDataFrame"])
result = session.run(api_data={"MyKey": {"col": [1, 2]}})
```

--------------------------------

### Running Stateful Frameworks with DuckDB Connection

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/03-stateful-connection.md

Demonstrates how to pass an active DuckDB connection object to `mloda.run_all` when utilizing stateful compute frameworks.

```python
conn = duckdb.connect()
result = mloda.run_all(
    features=[...],
    compute_frameworks=["MyStatefulFramework"],
    data_connections=[conn],
)
```

--------------------------------

### Self-Joins with Aliases

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/08-links-joins.md

Example of performing a self-join on the same FeatureGroup using aliases to distinguish sides.

```python
link = Link.inner_on(UserFeatureGroup, UserFeatureGroup,
                     self_left_alias={"side": "left"},
                     self_right_alias={"side": "right"})

features = {
    Feature("age", options={"side": "left"}),
    Feature("age", options={"side": "right"}),
}
```

--------------------------------

### Testing Framework Availability

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/09-testing-guide.md

Checks if a framework is unavailable when its required library is not installed. Uses assert_unavailable_when_import_blocked helper.

```python
from tests.test_plugins.compute_framework.base_implementations.availability_test_test_helper import (
    assert_unavailable_when_import_blocked,
)

def test_unavailable_when_not_installed():
    assert_unavailable_when_import_blocked(MyFramework, "my_lib")
```

--------------------------------

### Stateful Merge Engine with Framework Connection

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/06-merge-engine.md

Demonstrates how to implement a merge engine in frameworks that utilize stateful connections. Access the connection via `self.framework_connection` for operations like SQL-based joins.

```python
class MyStatefulMergeEngine(BaseMergeEngine):
    def merge_inner(self, left_data, right_data, left_index, right_index):
        conn = self.framework_connection  # Passed from framework
        # Use connection for SQL-based join...
```

--------------------------------

### Load All Plugins

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/02-discover-plugins.md

Load all available plugins in the MLODA environment. This should be done before using discovery APIs.

```python
from mloda.user import PluginLoader

# Load all plugins first
PluginLoader.all()
```

--------------------------------

### Sessionization Feature Name Patterns

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/15-sessionization.md

Examples of feature names used for sessionization, specifying the inactivity threshold in minutes or hours.

```text
ts__sessionize_30_minute
ts__sessionize_1_hour
```

--------------------------------

### Define Composite Key Index

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/07-index-features.md

Example of defining a composite key index using `Index` with a tuple of multiple column names.

```python
Index(("user_id", "date"))
```

--------------------------------

### List All Feature Groups

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/02-discover-plugins.md

Retrieve and print documentation for all loaded feature groups, including their name, description, version, and supported compute frameworks.

```python
from mloda.steward import get_feature_group_docs

# Get all feature groups
for fg in get_feature_group_docs():
    print(f"{fg.name}: {fg.description}")
    print(f"  Version: {fg.version}")
    print(f"  Frameworks: {fg.compute_frameworks}")
```

--------------------------------

### Define Single Column Index

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/07-index-features.md

Example of defining a single column index using `Index` with a tuple containing the column name.

```python
Index(("user_id",))
```

--------------------------------

### Defining a Linked Feature Group

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/08-links-joins.md

Example of a FeatureGroup that defines input features using an inner join between Order and Customer FeatureGroups.

```python
from typing import Any
from mloda.user import Link, JoinSpec, Index, Feature, FeatureName, Options
from mloda.provider import FeatureGroup, FeatureSet


class OrderWithCustomer(FeatureGroup):
    """Join orders with customer data."""

    def input_features(self, options: Options, feature_name: FeatureName) -> set[Feature] | None:
        link = Link.inner_on(OrderFeatureGroup, CustomerFeatureGroup)
        return {
            Feature(name="order_value", link=link),
            Feature(name="customer_name"),
        }

    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        # Data is already joined by the framework
        return data
```

--------------------------------

### Structure for Framework Implementations

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/10-adding-new-operation.md

Organize framework-specific implementations within their respective directories. Each framework should have its own file subclassing the base operation class.

```text
{category}/{your_op}/
  base.py
  pyarrow_{your_op}.py
  pandas_{your_op}.py
  polars_lazy_{your_op}.py
  duckdb_{your_op}.py
  sqlite_{your_op}.py
```

--------------------------------

### DuckDB Connection Fixture

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/09-testing-guide.md

A framework-specific pytest fixture for establishing and managing a DuckDB database connection. Includes setup and teardown logic.

```python
# DuckDB conftest.py
@pytest.pytest.fixture
def connection():
    conn = duckdb.connect()
    yield conn
    conn.close()
```

--------------------------------

### Configuration-based Feature Creation with Options

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/11-options.md

Create a feature by providing configuration options for both group and context. Group options influence feature resolution, while context options serve as metadata.

```python
from mloda.user import Feature, Options

# Configuration-based feature creation
feature = Feature("imputed_income", Options(
    group={"algorithm": "mean"},
    context={"in_features": "income"}
))

```

--------------------------------

### Run Tests with Tox

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/06-publish-to-community.md

Ensure your plugin functions correctly by running tests using tox.

```bash
tox
```

--------------------------------

### Define a Derived Feature Group

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/02-derived-features.md

Example of a derived feature group that doubles the value of a source column. It specifies its dependency and the calculation logic.

```python
from typing import Any
from mloda.provider import FeatureGroup
from mloda.user import Feature, Options, FeatureName
from mloda.provider import FeatureSet


class DoubledValue(FeatureGroup):
    """Double the source_column value."""

    def input_features(self, options: Options, feature_name: FeatureName) -> set[Feature] | None:
        return {Feature.not_typed("source_column")}

    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        return data["source_column"] * 2
```

--------------------------------

### Filter Engine Test Structure

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/09-testing-guide.md

Example of how to structure tests for a filter engine using FilterEngineTestMixin. Requires implementing three specific methods.

```python
from tests.test_plugins.compute_framework.base_implementations.filter_engine_test_mixin import FilterEngineTestMixin

class TestMyFilterEngine(FilterEngineTestMixin):
    @pytest.fixture
    def filter_engine(self) -> Any:
        return MyFilterEngine

    @pytest.fixture
    def sample_data(self) -> Any:
        return my_lib.DataFrame({"str_col": ["a", "b"], "int_col": [1, 5]})

    def get_column_values(self, result, column) -> list[Any]:
        return result[column].tolist()
```

--------------------------------

### Folder-Based Feature Group Matching

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/17-data-connection-matching.md

Match feature groups based on available folders in the DataAccessCollection. This example sets an option with the data folder path.

```python
class CsvFeature(FeatureGroup):
    @classmethod
    def match_feature_group_criteria(
        cls, feature_name: str, options: Options,
        data_access_collection: DataAccessCollection | None = None,
    ) -> bool:
        if data_access_collection is None or not data_access_collection.folders:
            return False
        # `folders` is a dict[handle, path] in mloda 0.7.0+; iterate `.values()`
        # for the path (iterating the dict directly yields handle names).
        options.set("_data_folder", next(iter(data_access_collection.folders.values())))
        return True
```

--------------------------------

### Define Multiple Index Columns

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/07-index-features.md

Example of defining multiple index columns, including primary and foreign keys, within the `index_columns()` class method.

```python
@classmethod
def index_columns(cls) -> list[Index]:
    return [
        Index(("order_id",)),       # Primary key
        Index(("customer_id",)),    # Foreign key
    ]
```

--------------------------------

### Cross-Domain Dependency Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/19-domain.md

Illustrates how domains propagate and can be overridden in feature dependencies. Features inherit the parent's domain unless an explicit domain is provided.

```python
class SalesRevenueGroup(FeatureGroup):
    @classmethod
    def get_domain(cls) -> Domain:
        return Domain("Sales")

    def input_features(self, options, feature_name):
        return {
            "base_amount",                              # Inherits "Sales"
            Feature("exchange_rate", domain="Finance"), # Uses "Finance"
        }
```

--------------------------------

### Create New Plugin Repository from Template

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/04-create-plugin-package.md

Use the GitHub CLI to create a new private repository for your plugin based on the official mloda-plugin-template.

```bash
gh repo create my-plugin --template mloda-ai/mloda-plugin-template --private
git clone git@github.com:yourname/my-plugin.git
cd my-plugin
```

--------------------------------

### Custom Validation Function Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/14-feature-matching.md

Defines property mappings with custom validation functions for integer window sizes and float thresholds. Requires `strict_validation: True`.

```python
from mloda_plugins.feature_group.experimental.default_options_key import DefaultOptionKeys

PROPERTY_MAPPING = {
    "window_size": {
        "explanation": "Number of rows in the rolling window",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: True,
        DefaultOptionKeys.validation_function: lambda x: isinstance(x, int) and x > 0,
    },
    "threshold": {
        "explanation": "Cutoff value for filtering",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: True,
        DefaultOptionKeys.validation_function: lambda x: isinstance(x, (int, float)) and 0.0 <= x <= 1.0,
    },
}
```

--------------------------------

### Convenience Join Methods with _on

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/08-links-joins.md

Shows how to use convenience methods like inner_on to automatically derive join columns from index_columns.

```python
link = Link.inner_on(UserFeatureGroup, OrderFeatureGroup)

# Select specific index position
link = Link.inner_on(UserFG, OrderFG, left_index=0, right_index=1)
```

--------------------------------

### Complete Root Feature Example

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/feature-group-patterns/01-root-features.md

Defines a root feature that loads data from an external source. It requires a custom BaseInputData subclass and implements the calculate_feature method.

```python
from typing import Any
from mloda.provider import FeatureGroup
from mloda.provider import BaseInputData, FeatureSet


class MyInputData(BaseInputData):
    """Configuration for data source."""
    pass


class MyRootFeature(FeatureGroup):
    """Load data from external source."""

    @classmethod
    def input_data(cls) -> BaseInputData | None:
        return MyInputData()

    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        return {"my_column": [1, 2, 3]}
```

--------------------------------

### Python Time Bucketization Features

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/data-operation-patterns/11-time-bucketization.md

Demonstrates how to define and use time bucketization features in Python. Features include bucketing by hour, week, day, and rounding to nearest intervals. Requires importing Feature, PluginLoader, and mloda.

```python
from mloda.user import Feature, PluginLoader, mloda

PluginLoader.all()

features = [
    Feature("event_time__floor_1_hour"),     # bucket events per hour
    Feature("event_time__floor_1_week"),     # ISO week start (Monday)
    Feature("event_time__ceil_1_day"),       # next-day boundary (idempotent on midnight)
    Feature("event_time__round_5_minute"),   # nearest 5-minute boundary, half-up
]

result = mloda.run_all(features, compute_frameworks={"PyArrowTable"})

```

--------------------------------

### Package-Specific Configuration

Source: https://github.com/mloda-ai/mloda-registry/blob/main/memory-bank/pyproject-generation.md

Defines per-package details including description, runtime dependencies, and file path.

```toml
[packages.mloda-community]
description = "All community plugins for mloda"
dependencies = ["mloda>=X.Y.Z"]
path = "mloda/community"
# Generates: package-dir = {"" = "../.."}, packages = ["mloda.community.*"]
```

--------------------------------

### Framework Merge Test Structure

Source: https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/compute-framework-patterns/09-testing-guide.md

Example of how to structure framework-level merge tests using DataFrameTestBase. Requires defining the framework class and a method to create dataframes.

```python
from tests.test_plugins.compute_framework.test_tooling.dataframe_test_base import DataFrameTestBase

class TestMyFrameworkMerge(DataFrameTestBase):
    @classmethod
    def framework_class(cls) -> type[Any]:
        return MyFramework

    def create_dataframe(self, data: dict) -> Any:
        return my_lib.DataFrame(data)

    def get_connection(self) -> Any | None:
        return None
```