### Serve MkDocs Documentation Locally

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/development.md

Build and preview local documentation changes. Ensure `mloda[docs]` is installed for example notebook execution.

```bash
mkdocs serve --config-file docs/mkdocs.yml
```

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

### Setup MLODA Development Environment

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

Instructions for setting up the MLODA development environment, including cloning the repository, installing dependencies, and running the test suite.

```bash
git clone https://github.com/mloda-ai/mloda.git
cd mloda
uv sync --all-extras
source .venv/bin/activate
tox  # full test, lint, type-check, and security suite
```

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

### Install Development Dependencies

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

Install all necessary dependencies for development, including optional extras, using uv.

```bash
uv sync --all-extras
```

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

### Example: Load, List, and Display Plugins

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/plugin-loader.md

A comprehensive example showing how to create a loader, load all plugins, list the loaded modules, and display the plugin dependency graph.

```python
# Create loader and load plugins
loader = PluginLoader()
loader.load_all_plugins()

# List loaded modules
modules = loader.list_loaded_modules()

# Show dependencies
graph = loader.display_plugin_graph()
```

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

### Edit Marimo Example Notebook

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/development.md

Open and edit marimo notebooks, which are stored as plain Python files. Ensure marimo is installed.

```bash
marimo edit docs/docs/examples/base_usage.py
```

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

### MLODA Quick Start Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/installation.md

A brief example demonstrating how to use MLODA to run features with specified compute frameworks and API data. The `api_data` parameter allows passing inline data, where each top-level key serves as a label for related columns.

```python
from mloda.user import mloda, PluginLoader
PluginLoader.all()

result = mloda.run_all(
    features=["customer_id", "income", "income__sum_aggr"],
    compute_frameworks=["PandasDataFrame"],
    api_data={
        "SampleData": {
            "customer_id": ["C001", "C002", "C003"],
            "income": [50000, 75000, 90000]
        }
    }
)
```

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

### DAC Example with SQLite

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/named-data-access-handles.md

A runnable example demonstrating DAC initialization with in-memory SQLite connections and file resources. Asserts the registered handles and their types.

```python
import sqlite3
from mloda.user import DataAccessCollection

primary = sqlite3.connect(":memory:")
secondary = sqlite3.connect(":memory:")

dac = DataAccessCollection(
    connections={"primary": primary, "secondary": secondary},
    files={"users": "/tmp/users.csv"},
)

assert dac.handles() == {
    "primary": "connection",
    "secondary": "connection",
    "users": "file",
}
```

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

### Quick Start: Load All and Specific Groups

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/plugin-loader.md

Demonstrates how to initialize PluginLoader and load all available plugins, or load plugins from a specific group.

```python
from mloda.user import PluginLoader

# Load all plugins
loader = PluginLoader.all()

# Or load specific groups
loader = PluginLoader()
loader.load_group("feature_group")
```

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

### Install Test Dependencies

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/techContext.md

Installs necessary packages for running tests and using tox for environment management.

```bash
pip install -r tests/requirements-test.txt && pip install tox
```

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

### Complete MLODA Feature Configuration and Execution Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

This example demonstrates loading features from a configuration string, including basic features, aggregated features with context options, and features using column indexing. It then runs all features using the PandasDataFrame compute framework.

```python
from mloda.user import load_features_from_config, mloda

config = '''
[
    "customer_id",
    {
        "name": "sales_aggregated",
        "in_features": ["daily_sales"],
        "context_options": {
            "aggregation_type": "sum",
            "window_days": 7
        }
    },
    {
        "name": "encoded_category",
        "in_features": ["category"],
        "column_index": 0
    }
]
'''

features = load_features_from_config(config)

result = mloda.run_all(
    features,
    compute_frameworks=["PandasDataFrame"],
    api_data={"customer_data": {"customer_id": [1, 2, 3]}}
)
```

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

### Validation Examples

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/property-mapping.md

Shows examples of valid and invalid options based on PROPERTY_MAPPING configurations, including strict and flexible validation scenarios.

```python
# Valid - "sum" is in mapping
Options(context={"operation_type": "sum"})

# Invalid with strict validation - "custom" not in mapping  
Options(context={"operation_type": "custom"})  # Raises ValueError

# Valid with flexible validation - any value allowed
Options(context={"in_features": "any_feature_name"})
```

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

### ApiData Setup for Request-Time Data Input

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/access-feature-data.md

Demonstrates the basic setup for `ApiData`, which allows data to be provided to MLODA at request time. This is useful for use cases like web requests or real-time prediction.

```python
from typing import List

from mloda.user import mloda
from mloda_plugins.compute_framework.base_implementations.pandas.dataframe import PandasDataFrame

```

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

### JSON Configuration: Simple Options

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Example of using the `options` field for simple key-value configuration within a feature object.

```json
[
    {
        "name": "my_feature",
        "options": {
            "window_size": 7,
            "aggregation": "sum"
        }
    }
]
```

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

### Input Data and Filter Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/filter_data.md

Defines the initial dataset and the filtering condition used across various pipeline flow examples.

```text
Input:
    region | status   | value
    A      | active   |  10
    A      | inactive |  20
    B      | active   |  30
    B      | inactive |  40

Filter: status == "active"
```

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

### Get Compute Framework Documentation

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

Use get_compute_framework_docs to get documentation for available compute frameworks. Can optionally include unavailable frameworks.

```python
from mloda.steward import get_compute_framework_docs

# Get all available frameworks
frameworks = get_compute_framework_docs()

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

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

### Install MLODA from Git Repository

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/installation.md

Clone the MLODA repository from GitHub and install it from the local source. This is useful for development or when needing the latest unreleased features.

```bash
git clone https://github.com/mloda-ai/mloda.git
cd mloda
pip install .
```

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

### Activate Virtual Environment

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

Activate the Python virtual environment created during the setup process.

```bash
source .venv/bin/activate
```

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

### Example Output of Loaded Feature Data

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/access-feature-data.md

This is the expected output when running the `ReadFileFeature` example, showing the loaded data as a Pandas DataFrame with the 'AExample' column.

```python
[  AExample
0   Value1
1   Value2]
```

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

### Custom Transformer Implementation Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/framework-transformers.md

Demonstrates how to create a custom transformer by subclassing BaseTransformer and implementing required methods for framework conversion.

```python
from typing import Any, Optional

class CustomTransformer(BaseTransformer):
    @classmethod
    def framework(cls) -> Any:
        return CustomFramework

    @classmethod
    def other_framework(cls) -> Any:
        return OtherFramework

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

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

    @classmethod
    def transform_fw_to_other_fw(cls, data: Any) -> Any:
        # Convert from CustomFramework to OtherFramework
        return other_framework.from_custom(data)

    @classmethod
    def transform_other_fw_to_fw(cls, data: Any, framework_connection_object: Optional[Any] = None) -> Any:
        # Convert from OtherFramework to CustomFramework
        return custom_framework.from_other(data)
```

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

### JSON Configuration: Group and Context Options

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Example using `group_options` and `context_options` for explicit parameter separation. Note that `options` is mutually exclusive with these.

```json
[
    {
        "name": "my_feature",
        "group_options": {
            "data_source": "production"
        },
        "context_options": {
            "aggregation_type": "sum"
        }
    }
]
```

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

### Producer and Consumer Example Flow

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/feature_groups.md

Demonstrates the typical workflow for using FeatureGroup utilities. Shows how a producer creates multi-column output using `apply_naming_convention` and how a consumer discovers these columns with `resolve_multi_column_feature`.

```python
# Producer creates multi-column output
result = encoder.transform(data)  # 2D array
named_cols = cls.apply_naming_convention(result, "state__onehot_encoded")
# Returns: {"state__onehot_encoded~0": [data], "~1": [data], "~2": [data]}

# Consumer discovers columns automatically
cols = cls.resolve_multi_column_feature("state__onehot_encoded", data.columns)
# Returns: ["state__onehot_encoded~0", "~1", "~2"]

# Process all discovered columns
for col in cols:
    process(data[col])
```

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

### Install MLODA using pip

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/installation.md

Use this command to install the MLODA library directly from the Python Package Index.

```bash
pip install mloda
```

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

### Parameter Classification Examples

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/property-mapping.md

Illustrates how to classify parameters as context, group, or order-by using DefaultOptionKeys. Context parameters do not affect Feature Group splitting.

```python
# Context parameter (doesn't affect Feature Group splitting)
"aggregation_type": {
    "sum": "Sum aggregation",
    DefaultOptionKeys.context: True,
}

# Group parameter (affects Feature Group splitting)
"data_source": {
    "production": "Production data",
    DefaultOptionKeys.group: True,
}

# Order-by parameter (defines sort order for sequential operations)
DefaultOptionKeys.order_by: {
    "explanation": "Column(s) controlling row order for rank, offset, or frame_aggregate",
    DefaultOptionKeys.context: True,
    DefaultOptionKeys.strict_validation: False,
}
```

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

### Run Full Test Suite

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

Execute the complete test suite using tox to verify your setup and ensure all checks pass. This should be run before submitting a pull request.

```bash
tox
```

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

### Feature Domain Inheritance Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/domain.md

Demonstrates how string-based features and features within a group inherit the parent's domain.

```python
Feature("Revenue", domain="Sales")

class SalesRevenueGroup(FeatureGroup):
    def input_features(self, options, feature_name):
        return {"base_amount", "currency"}  # Both inherit "Sales"
```

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

### Basic Data Access with mloda

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

This example demonstrates a basic data access request using mloda. It shows how to specify features, compute frameworks, and provide API data.

```python
from mloda.user import PluginLoader, mloda
PluginLoader.all()

result = mloda.run_all(
    features=["customer_id", "income", "income__sum_aggr", "age__avg_aggr"],
    compute_frameworks=["PandasDataFrame"],
    api_data={"SampleData": {
        "customer_id": ["C001", "C002", "C003", "C004", "C005"],
        "age": [25, 35, 45, 30, 50],
        "income": [50000, 75000, 90000, 60000, 85000]
    }})

```

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

### Resolve Resources with and without Hints

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/named-data-access-handles.md

Example showing how DAC resolves resources. It demonstrates successful resolution using a specific handle hint and raises ValueErrors for ambiguous or missing resources.

```python
import sqlite3
import pytest
from mloda.user import DataAccessCollection

dac = DataAccessCollection(
    connections={
        "primary": sqlite3.connect(":memory:"),
        "secondary": sqlite3.connect(":memory:"),
    },
)

assert dac.resolve("connection", hint="primary") is not None

with pytest.raises(ValueError) as excinfo:
    dac.resolve("connection")
assert "data_access_handle" in str(excinfo.value)
assert "'primary'" in str(excinfo.value) and "'secondary'" in str(excinfo.value)

with pytest.raises(ValueError) as excinfo:
    dac.resolve("connection", hint="missing")
assert "missing" in str(excinfo.value)
```

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

### Feature Type Declaration Example

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/feature_groups.md

Demonstrates how to declare optional type constraints for features using typed constructors like Feature.int32_of() and Feature.str_of().

```python
Feature.int32_of("amount")
Feature.str_of("name")
```

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

### PROPERTY_MAPPING Configuration Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-matching.md

Defines how configuration-based features are validated, including aggregation types and input features with optional context and strict validation settings.

```python
PROPERTY_MAPPING = {
    "aggregation_type": {
        "sum": "Sum aggregation",
        "avg": "Average aggregation",
        "max": "Maximum aggregation",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: True,
    },
    DefaultOptionKeys.in_features: {
        "explanation": "Source feature for aggregation",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: False,
    },
}
```

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

### Specify compute framework using specific feature configuration

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/compute-frameworks.md

This example demonstrates how to configure an individual feature to use a specific compute framework, in this case, PyArrowTable, by passing options within the Feature definition.

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

feature = Feature("id", options={"compute_framework": "PyArrowTable"})

result = mloda.run_all(
    [feature],
    data_access_collection=data_access_collection
)
result[0]
```

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

### Feature Chaining Example

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/feature_groups.md

Visualizes a complex feature creation process through chaining multiple transformations: imputation, time window, and aggregation. This demonstrates how features can be composed sequentially.

```mermaid
graph LR
    price --> |impute| imp[price__mean_imputed]
    imp --> |window| win[price__mean_imputed__sum_7_day_window]
    win --> |aggregate| final[price__mean_imputed__sum_7_day_window__max_aggr]

    style price fill:#ffd,stroke:#333
    style final fill:#dfd,stroke:#333,stroke-width:2px
```

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

### Modern Feature Group Matching Examples

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-matching.md

Illustrates how features are matched in a modern feature group, showing both string-based matching using a pattern and configuration-based matching via PROPERTY_MAPPING validation.

```python
# String-based matching
feature = Feature("sales__sum_aggr")  # Matches via pattern

# Configuration-based matching
feature = Feature(
    "placeholder",
    Options(context={
        "aggregation_type": "sum",
        "in_features": "sales"
    })
)  # Matches via PROPERTY_MAPPING validation
```

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

### Python Manual Column Access Example (Legacy)

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

Illustrates the legacy method of manually specifying or accessing individual columns from multi-column features using explicit naming conventions with '~N' suffixes.

```python
# Manual specification of specific columns
base_feature = "category__onehot_encoded"  # Creates all columns
specific_column = "category__onehot_encoded~0"  # Access first column
another_column = "category__onehot_encoded~1"  # Access second column
```

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

### Context Window Assembly: Declarative Feature Gathering

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

This example shows how to declaratively assemble context from multiple sources for LLM applications. It requires custom FeatureGroup implementations for specific data sources and demonstrates how mloda validates and delivers the complete context.

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

# Build complete context from multiple sources
features = [
    Feature(name="system_instructions", options={"template": "support_agent"}),
    Feature(name="user_profile", options={"user_id": user_id, "include_preferences": True}),
    Feature(name="knowledge_base", options={"query": user_query, "top_k": 5}),
    Feature(name="conversation_history", options={"limit": 20, "summarize_old": True}),
    Feature(name="available_tools", options={"category": "customer_service"}),
    Feature(name="output_format", options={"format": "markdown", "max_length": 500}),
]

result = mloda.run_all(
    features=features,
    compute_frameworks=["PythonDictFramework"],
    api_data={"UserQuery": {"query": [user_query]}})

# Each feature resolved via its plugin, validated

```

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

### Using Spark with mloda API

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/framework-connection-object.md

Illustrates the integration of mloda with Apache Spark. This example shows how to create a SparkSession, configure it, and then use it with the mloda API for distributed computing tasks via the SparkFramework.

```python
from mloda.user import mloda
from mloda.user import DataAccessCollection
from pyspark.sql import SparkSession

# Create SparkSession
spark = SparkSession.builder \
    .appName("MLoda-Spark-Application") \
    .master("local[*]") \
    .config("spark.sql.adaptive.enabled", "true") \
    .getOrCreate()

# Set up data access
data_access_collection = DataAccessCollection(connections={spark})

# Run with Spark framework
result = mloda.run_all(
    ["feature1", "feature2"],
    compute_frameworks=["SparkFramework"],
    data_access_collection=data_access_collection
)
```

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

### mloda API call with PyArrowTable compute framework

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/compute-frameworks.md

This example demonstrates how to specify the PyArrowTable compute framework when making an mlodaAPI call. This is the recommended approach for clarity and to avoid ambiguity.

```python
from mloda.user import mloda
from mloda.user import DataAccessCollection

file_path = "tests/test_plugins/feature_group/src/dataset/creditcard_2023_short.csv"
data_access_collection = DataAccessCollection(files={file_path})

feature_list = ["id","V1","V2","V3"]

mloda.run_all(
    feature_list,
    data_access_collection=data_access_collection,
    compute_frameworks=["PyArrowTable"]
)
```

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

### Custom Validation Function Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-matching.md

Shows how to implement custom validation logic for parameters like 'window_size' using a lambda function to ensure integer values greater than zero.

```python
PROPERTY_MAPPING = {
    "window_size": {
        "explanation": "Size of the time window",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: True,
        DefaultOptionKeys.validation_function: lambda x: isinstance(x, int) and x > 0,
    },
}
```

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

### Execute Request with Custom Feature Group

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/feature-groups.md

Runs a mloda request using the custom 'Example' feature group. Features are referenced with the 'Example_' prefix, and mloda automatically handles dependency resolution.

```python
from mloda.user import mloda

result = mloda.run_all(
            example_feature_list, 
            compute_frameworks=["PyArrowTable"], 
            data_access_collection=data_access_collection
        )
result[0]

```

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

### Import Modules and Set File References

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/feature-groups.md

Imports necessary modules from pyarrow and mloda, and sets up data access for a CSV file. This is the initial setup for defining and using custom feature groups.

```python
import pyarrow.compute as pc
import pyarrow as pa

from mloda.provider import FeatureGroup
from mloda.user import DataAccessCollection

file_path = "tests/test_plugins/feature_group/src/dataset/creditcard_2023_short.csv"
data_access_collection = DataAccessCollection(files={file_path})

feature_list = ["id","V1","V2","V3"]
example_feature_list = [f"Example_{f}" for f in feature_list]

```

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

### Define a Custom Feature for Reading Files

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/access-feature-data.md

This example defines a `ReadFileFeature` that inherits from `FeatureGroup` and uses `ReadFile` with a `CsvReader` to load data. It demonstrates how to implement custom input data handling for features.

```python
# This feature is already implemented as plugin, so do not run it again. This will raise intentional errors.
class ReadFileFeature(FeatureGroup):
    @classmethod
    def input_data(cls) -> Optional[BaseInputData]:
        return ReadFile()

    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        reader = cls.input_data()
        if reader is not None:
            data = reader.load(features)
            return data
        raise ValueError(f"Reading file failed for feature {features.get_name_of_one_feature()}.")
```

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

### Define PROPERTY_MAPPING for Feature Group Configuration

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

This example demonstrates the modern approach to defining feature group configurations using `PROPERTY_MAPPING`. It includes mapping for specific parameters like 'operation_type' and 'in_features', specifying their validation rules and context usage.

```python
from mloda.provider import FeatureGroup
from mloda.user import FeatureName
from mloda.provider import DefaultOptionKeys

class MyFeatureGroup(FeatureGroup):
    PREFIX_PATTERN = r"__([a-zA-Z_]+)_operation$"

    PROPERTY_MAPPING = {
        # Feature-specific parameter
        "operation_type": {
            "sum": "Sum aggregation",
            "avg": "Average aggregation", 
            "max": "Maximum aggregation",
            DefaultOptionKeys.context: True,  # Context parameter
            DefaultOptionKeys.strict_validation: True,  # Strict validation
        },
        # Source feature parameter
        DefaultOptionKeys.in_features: {
            "explanation": "Source feature for the operation",
            DefaultOptionKeys.context: True,  # Context parameter
            DefaultOptionKeys.strict_validation: False,  # Flexible validation
        },
    }
```

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

### Two-Phase Execution with prepare() and run()

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/mloda-api.md

Splits configuration and execution for real-time or inference use cases. Prepare the execution plan once with prepare(), then execute it multiple times with run() using fresh data.

```python
from mloda.user import mloda

# 1. Prepare once
session = mloda.prepare(
    ["MyFeature"],
    compute_frameworks=["PandasDataFrame"],
    api_data=initial_api_data,
)

# 2. Run multiple times with different data
result_1 = session.run(api_data={"MyKey": {"col": [1, 2]}})
result_2 = session.run(api_data={"MyKey": {"col": [3, 4]}})
```

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

### Verify MLODA Installation

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/installation.md

Run this Python code to check if MLODA has been installed correctly by printing its version number.

```python
from importlib import metadata
print(metadata.version("mloda"))
```

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

### JSON Configuration: Window, Rank, and Percentile Features

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Demonstrates how to configure window, rank, and percentile features using `context_options` for partition and order parameters.

```json
[
    {
        "name": "steps__sum_window",
        "context_options": {"partition_by": ["subject_id"]}
    },
    {
        "name": "price__last_window",
        "context_options": {"partition_by": ["region"], "order_by": "timestamp"}
    },
    {
        "name": "sales__row_number_ranked",
        "context_options": {"partition_by": ["region"], "order_by": "sales"}
    },
    {
        "name": "sales__p95_percentile",
        "context_options": {"partition_by": ["region"]}
    }
]
```

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

### Initialize and Use DataAccessCollection

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/access-feature-data.md

Demonstrates how to create a DataAccessCollection, add file paths, folder paths, credentials, and connection objects, and then use it with mloda.run_all.

```python
data_access = DataAccessCollection()

# Add file paths, folder paths, credentials, and connection objects
data_access.add_file('path/to/folder/text.txt')
data_access.add_folder('path/to/folder/')
data_access.add_credentials({'host': 'example.com', 'password': 'example'})
data_access.add_connection('InitializedDBConnection')

mloda.run_all(
    feature_list,
    data_access_collection=data_access)
```

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

### Prepare Once for Realtime Use Cases

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/api-request.md

Prepare the mloda session once at startup to avoid repeated planning overhead in latency-sensitive scenarios. This allows for cheap per-request execution.

```python
# 1. Prepare once (e.g. at server startup)
session = mloda.prepare(feature_list, compute_frameworks=["PyArrowTable"], data_access_collection=data_access_collection)

# 2. Execute per request with fresh data
result = session.run(api_data={"MyKey": {"col": [1, 2]}})
```

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

### Initialize DataAccessCollection with Resources

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/named-data-access-handles.md

Create a DAC instance by providing dictionaries of connections, files, folders, and credentials. Handle names are arbitrary strings and must be unique across kinds.

```python
DataAccessCollection(
    connections={"warehouse": warehouse_conn, "analytics": analytics_conn},
    files={"transactions": "/data/tx.parquet", "users": "/data/users.csv"},
    folders={"raw": "/data/raw/"},
    credentials={"pg-prod": {"host": "...", "user": "..."}, "snowflake-dev": {...}},
)
```

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

### Feature Initialization: String-based vs. Configuration-based

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/feature_groups.md

Shows two methods for initializing a Feature object: the legacy string-based approach and the modern configuration-based approach using Options.

```python
# String-based (Legacy)
feature = Feature("sales__sum_aggr")

# Configuration-based (Modern)
feature = Feature(
    "placeholder",
    Options(context={
        "aggregation_type": "sum",
        DefaultOptionKeys.in_features: "sales"
    })
)
```

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

### Strict Validation Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-matching.md

Illustrates strict validation where parameter values must exist within the defined mapping. This example shows a successful match and a failing one.

```python
# This will match
options = Options(context={"aggregation_type": "sum"})  # "sum" is in mapping

# This will fail validation
options = Options(context={"aggregation_type": "custom"})  # "custom" not in mapping
```

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

### Create Feature using Configuration-Based Approach

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

Illustrates creating a feature using the modern configuration-based approach with the Options architecture, where placeholder is replaced during processing.

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

# Traditional string-based approach:
feature = Feature("sales__sum_aggr")

# Modern configuration-based approach:
feature = Feature(
    "placeholder",  # Will be replaced during processing
    Options(
        context={
            "aggregation_type": "sum",
            "in_features": "sales"
        }
    )
)
```

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

### Get Extender Documentation

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

Use get_extender_docs to retrieve documentation for extenders. Supports filtering by the type of function they wrap.

```python
from mloda.steward import get_extender_docs

# Get all extenders
extenders = get_extender_docs()

# Filter by wrapped function type
extenders = get_extender_docs(wraps="formula")
```

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

### Run Feature with PythonDictFramework

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/compute-frameworks.md

Demonstrates running a feature using the PythonDictFramework, which returns results as a List[Dict[str, Any]]. This framework has zero dependencies.

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

feature = Feature("id", options={"compute_framework": "PythonDictFramework"})

result = mloda.run_all(
    [feature],
    data_access_collection=data_access_collection
)
result[0]  # Returns List[Dict[str, Any]]
```

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

### JSON Configuration: Feature Chaining with Multiple Sources

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Example of defining a dependent feature using `in_features` with multiple source features.

```json
[
    {
        "name": "distance_feature",
        "in_features": ["point_a", "point_b"]
    }
]
```

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

### JSON Configuration: Feature Chaining with Single Source

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Example of defining a dependent feature using `in_features` with a single source feature.

```json
[
    {
        "name": "aggregated_sales",
        "in_features": ["raw_sales"],
        "context_options": {
            "aggregation_type": "sum"
        }
    }
]
```

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

### Flexible Validation Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-matching.md

Demonstrates flexible validation, where any value is accepted for parameters like 'in_features' when strict validation is disabled (default).

```python
# Both will match
options = Options(context={"in_features": "sales"})      # Any value OK
options = Options(context={"in_features": "custom_feature"})  # Any value OK
```

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

### Micro-batch loop with prepare() and run()

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/streaming.md

This pattern is recommended for continuous processing. It involves preparing the execution plan once and then looping `run()` for each micro-batch from a data source.

```python3
from mloda.user import mloda

def data_source():
    """Yields micro-batches from any source (Kafka, WebSocket, file watcher, generator)."""
    yield {"SensorData": {"timestamp": [1, 2], "value": [10.5, 11.2]}}
    yield {"SensorData": {"timestamp": [3, 4], "value": [9.8, 10.1]}}

# Prepare once with a representative schema
session = mloda.prepare(
    ["ProcessedSensor"],
    api_data={"SensorData": {"timestamp": [0], "value": [0.0]}},
)

# Process micro-batches
for batch in data_source():
    results = session.run(api_data=batch)
    for result in results:
        consume(result)
```

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

### Get Feature Group Documentation

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

Use get_feature_group_docs to retrieve documentation for available feature groups. Supports filtering by name or compute framework.

```python
from mloda.steward import get_feature_group_docs

# Get all feature groups
all_fgs = get_feature_group_docs()

# Filter by name
fgs = get_feature_group_docs(name="timestamp")

# Filter by compute framework
fgs = get_feature_group_docs(compute_framework="PandasDataframe")
```

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

### Micro-batch loop with prepare() and stream_run()

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/streaming.md

Combines plan reuse with per-group streaming. Call `prepare()` once, then `stream_run()` for each micro-batch. Each feature group's result is yielded as soon as it completes.

```python3
from mloda.user import mloda

def sensor_source():
    yield {
        "Sensors": {
            "timestamp": [1, 2, 3],
            "temperature": [22.1, 22.5, 23.0],
            "pressure": [1013, 1012, 1014],
            "vibration": [0.01, 0.02, 0.015],
        }
    }

features = ["TemperatureStats", "PressureAnomaly", "VibrationFFT"]

session = mloda.prepare(
    features,
    api_data={"Sensors": {"timestamp": [0], "temperature": [0.0], "pressure": [0], "vibration": [0.0]}},
)

for batch in sensor_source():
    for result in session.stream_run(api_data=batch):
        # Each panel updates as its feature group completes
        dashboard.update_panel(result)
```

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

### Introspect Data Access Handles

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/named-data-access-handles.md

Use `DataAccessCollection.handles()` to get a map of registered handles and their kinds. This is useful for auditing, logging, or displaying available resources.

```python
dac.handles()
# {"warehouse": "connection", "analytics": "connection",
#  "transactions": "file", "users": "file",
#  "raw": "folder", "pg-prod": "credentials"}
```

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

### Get Feature Group Documentation

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/mloda-api.md

Retrieve documentation for feature groups. Supports filtering by name, search terms in description, compute framework, and version.

```python
all_fgs = get_feature_group_docs()

# Filter by name
fgs = get_feature_group_docs(name="timestamp")

# Filter by compute framework
fgs = get_feature_group_docs(compute_framework="PandasDataframe")
```

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

### Run MLODA with a custom Extender

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/extender.md

Demonstrates how to run MLODA's `run_all` function with a custom DokuExtender to monitor the execution time of feature calculations.

```python
from mloda.user import mloda
from mloda.user import DataAccessCollection

file_path = "tests/test_plugins/feature_group/src/dataset/creditcard_2023_short.csv"
data_access_collection = DataAccessCollection(files={file_path})

feature_list = ["id","V1","V2","V3"]


example_feature_list = [f"ExampleB_{f}" for f in feature_list]


mloda.run_all(
    feature_list,
    compute_frameworks={"PyArrowTable"},
    data_access_collection=data_access_collection,
    function_extender={DokuExtender()}
)
```

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

### Simple Validator for Output Features

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/data-quality.md

Implement a basic validator for output features by defining a `validate_output_features` class method. This example checks the length of the output data.

```python
from mloda.user import mloda
from mloda.provider import BaseInputData, DataCreator, FeatureGroup, FeatureSet
from mloda.user import Options


class DocBaseValidateOutputFeaturesBase(FeatureGroup):
    @classmethod
    def input_data(cls) -> Optional[BaseInputData]:
        return DataCreator({cls.get_class_name()})

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

    @classmethod
    def validate_output_features(cls, data: Any, config: Options) -> None:
        """This function should be used to validate the output data."""

        if len(data[cls.get_class_name()]) != 3:
            raise ValueError("Data should have 3 elements")

results = mloda.run_all(
            ["DocBaseValidateOutputFeaturesBase"], {PyArrowTable}
        )
results
```

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

### Define Options with Group and Context Parameters

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

Demonstrates the new Options architecture, separating parameters into group parameters that affect Feature Group resolution and context parameters that are metadata.

```python
from mloda.user import Options
from typing import Optional

# New Options architecture
options = Options(
    group={
        "data_source": "production",  # Affects Feature Group splitting
    },
    context={
        "aggregation_type": "sum",    # Doesn't affect splitting
        "in_features": "sales"
    }
)
```

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

### Error handling example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/data-type-enforcement.md

Type mismatches during mloda execution raise a DataTypeMismatchError, which can be caught to provide specific feedback on the feature name and its declared vs. actual types.

```python
from mloda.user import mloda
from mloda.user import Feature
from mloda.provider import DataTypeMismatchError

try:
    result = mloda.run_all([Feature.str_of("numeric_column")])
except DataTypeMismatchError as e:
    print(f"Feature '{e.feature_name}': declared {e.declared.name}, got {e.actual.name}")
```

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

### Create Single and Multi-Column Indexes

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/join_data.md

Demonstrates how to create Index objects for single and multiple columns, which are used as keys for merging datasets. Includes checks for multi-index status and subset relationships.

```python
from mloda.user import Index

# Create an Index with a single column
single_column_index = Index(('user_id',))

# Create an Index with multiple columns (multi-index)
multi_column_index = Index(('user_id', 'timestamp'))

# Check if an index is a multi-index
is_multi = multi_column_index.is_multi_index()  # Returns True

# Check if single column is a part of a composite index
is_a_part_of = single_column_index.is_a_part_of(multi_column_index) # Returns True
```

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

### Custom Feature Group with FeatureChainParserMixin

Source: https://github.com/mloda-ai/mloda/blob/main/memory-bank/feature_groups.md

Example of creating a custom feature group inheriting from FeatureChainParserMixin and FeatureGroup. Demonstrates setting prefix patterns and input feature constraints.

```python
from mloda.provider import FeatureGroup, FeatureChainParserMixin

class MyFeatureGroup(FeatureChainParserMixin, FeatureGroup):
    PREFIX_PATTERN = r".*__my_operation$"

    # In-feature constraints
    MIN_IN_FEATURES = 1
    MAX_IN_FEATURES = 1  # Or None for unlimited

    PROPERTY_MAPPING = {...}

    # input_features() inherited from FeatureChainParserMixin
    # match_feature_group_criteria() inherited from FeatureChainParserMixin
```

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

### Pandera Validator for Failing Output Features

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/data-quality.md

Demonstrates a failing output feature validation using Pandera. This example defines validation rules that are expected to cause an error.

```python
class DocBaseValidateOutputFeaturesBaseNegativePandera(DocBaseValidateOutputFeaturesBase):
    """Pandera example test case. This one is related to the pandera testcase for validate_input_features."""

    @classmethod
    def validate_output_features(cls, data: Any, features: FeatureSet) -> None:
        """This function should be used to validate the output data."""

        validation_rules = {
            cls.get_class_name(): Column(int, Check.in_range(1, 2)),
        }
        validator = DocExamplePanderaValidator(validation_rules, features.get_options_key("ValidationLevel"))
        validator.validate(data)

results = mloda.run_all(
            ["DocBaseValidateOutputFeaturesBaseNegativePandera"], {PyArrowTable}
        )
```

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

### Log Input Feature Validation Time with Extender

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/data-quality.md

Use an Extender to log the time taken for input feature validation. This example demonstrates wrapping the VALIDATE_INPUT_FEATURE hook.

```python
from mloda.user import mloda
from mloda.steward import Extender, ExtenderHook
from mloda.user import Feature
import time


class DokuValidateInputFeatureExtender(Extender):
    def wraps(self) -> Set[ExtenderHook]:
        return {ExtenderHook.VALIDATE_INPUT_FEATURE}

    def __call__(self, func: Any, *args: Any, **kwargs: Any) -> Any:
        start = time.time()
        result = func(*args, **kwargs)
        print(f"Time taken: {time.time() - start}")
        return result

example_feature = Feature("DocCustomValidateInputFeatures", {"ValidationLevel": "warning"})

results = mloda.run_all(
            [example_feature], {PyArrowTable}, function_extender={DokuValidateInputFeatureExtender()}
        )
```

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

### Python Producer: Creating Multi-Column Outputs

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

Demonstrates how to use `apply_naming_convention` in a producer class to automatically name columns generated by a feature transformation, such as from a one-hot encoder.

```python
from mloda.provider import FeatureGroup, FeatureSet

class MultiColumnProducer(FeatureGroup):
    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        # Compute results (e.g., from sklearn OneHotEncoder)
        result = encoder.transform(data)  # Returns 2D numpy array (n_samples, n_features)

        # Automatically apply naming convention
        feature_name = str(features.get_name_of_one_feature())
        named_columns = cls.apply_naming_convention(result, feature_name)
        # Returns: {"category__onehot_encoded~0": data, "~1": data, "~2": data}

        return named_columns
```

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

### BaseInputData Implementation for File Reading

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/data-access-patterns.md

Example of a FeatureGroup implementing the BaseInputData pattern to load data from files. It defines how to access input data and calculate features based on it.

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

class ReadFileFeature(FeatureGroup):
    @classmethod
    def input_data(cls) -> Optional[BaseInputData]:
        return ReadFile()  # BaseInputData implementation
    
    @classmethod
    def calculate_feature(cls, data: Any, features: FeatureSet) -> Any:
        reader = cls.input_data()
        if reader is not None:
            data = reader.load(features)
            return data
        raise ValueError("Reading file failed.")
```

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

### Get Composite Version Identifier

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-group-version.md

This class method returns a composite version identifier for a feature group, combining package version, module name, and source code hash.

```python
import typing as t

from mloda.feature_group.base import BaseFeatureGroupVersion


class FeatureGroupA(BaseFeatureGroupVersion):
    @classmethod
    def version(cls) -> str:
        """
        Returns a composite version identifier for this feature group.
        """
        return BaseFeatureGroupVersion.version(cls)

```

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

### Python Validation Function Example

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-chain-parser.md

Defines a validation function for a 'dimension' property, ensuring it's a positive integer. This is useful for complex validation beyond simple value lists.

```python
PROPERTY_MAPPING = {
    "dimension": {
        "explanation": "Number of dimensions for reduction",
        DefaultOptionKeys.context: True,
        DefaultOptionKeys.strict_validation: True,
        DefaultOptionKeys.validation_function: lambda x: isinstance(x, int) and x > 0,
    },
}
```

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

### Add Named and Unnamed Resources

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/named-data-access-handles.md

Demonstrates adding files to DAC, both with explicit handles and implicitly. Unnamed resources are auto-handled, useful until ambiguity requires explicit naming.

```python
dac.add_file("/data/tx.parquet")                       # auto-named
dac.add_file("tx", "/data/tx.parquet")                 # named (when you need a handle)
```

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

### Using DuckDB with mloda API

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/framework-connection-object.md

Demonstrates how to set up and use the mloda API with a DuckDB framework. It involves creating a DuckDB connection, initializing DataAccessCollection with it, and then running computations using the DuckDBFramework.

```python
from mloda.user import mloda
from mloda.user import DataAccessCollection
import duckdb

# Create DuckDB connection
connection = duckdb.connect()

# Set up data access
data_access_collection = DataAccessCollection(connections={connection})

# Run with DuckDB framework
result = mloda.run_all(
    ["feature1", "feature2"],
    compute_frameworks=["DuckDBFramework"],
    data_access_collection=data_access_collection
)
```

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

### DuckDBPyarrowTransformer Implementation

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/framework-connection-object.md

Provides an example of a DuckDB transformer that requires a connection object. It includes type checking to ensure a valid DuckDB connection is provided for PyArrow to DuckDB transformations.

```python
class DuckDBPyarrowTransformer(BaseTransformer):
    @classmethod
    def transform_other_fw_to_fw(cls, data: Any, framework_connection_object: Optional[Any] = None) -> Any:
        """Transform a PyArrow Table to a DuckDB relation."""
        if framework_connection_object is None:
            raise ValueError("A DuckDB connection object is required for this transformation.")
        
        if not isinstance(framework_connection_object, duckdb.DuckDBPyConnection):
            raise ValueError(f"Expected a DuckDB connection object, got {type(framework_connection_object)}")
        
        return framework_connection_object.from_arrow(data)
```

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

### Load Features from JSON Configuration

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/in_depth/feature-config.md

Demonstrates basic usage of `load_features_from_config` to load features defined in a JSON string and run them.

```python
from mloda.user import load_features_from_config, mloda

config = '''
[
    "simple_feature",
    {"name": "configured_feature", "options": {"param": "value"}}
]
'''

features = load_features_from_config(config)
result = mloda.run_all(features, compute_frameworks=["PandasDataFrame"])
```

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

### Initialize DuckDB Connection for DuckDBFramework

Source: https://github.com/mloda-ai/mloda/blob/main/docs/docs/chapter1/compute-frameworks.md

Sets up a DuckDB connection, which is a prerequisite for using the DuckDBFramework for analytical workloads and SQL-based transformations.

```python
from mloda.user import mloda
from mloda.user import Feature, DataAccessCollection
import duckdb

# Create DuckDB connection
connection = duckdb.connect()
```