mloda 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

mloda/core/abstract_plugins/components/{feature_group_version.py → base_feature_group_version.py}

@@ -7,7 +7,7 @@ from typing import Any, Type
 from abc import ABC
 
 
-class FeatureGroupVersion(ABC):
+class BaseFeatureGroupVersion(ABC):
     @classmethod
     def mloda_version(cls) -> str:
         """

mloda/core/abstract_plugins/compute_framework.py

@@ -383,7 +383,7 @@ Example:
         )
     }}
 
-    mlodaAPI.run_all(
+    mlodamloda.run_all(
         features=[Feature.int32_of("{feature_name}")],
         links=links,
         ...

mloda/core/abstract_plugins/feature_group.py

@@ -8,7 +8,7 @@ from mloda.core.abstract_plugins.components.data_access_collection import DataAc
 from mloda.core.abstract_plugins.components.data_types import DataType
 
 from mloda.core.abstract_plugins.components.domain import Domain
-from mloda.core.abstract_plugins.components.feature_group_version import FeatureGroupVersion
+from mloda.core.abstract_plugins.components.base_feature_group_version import BaseFeatureGroupVersion
 from mloda.core.abstract_plugins.components.feature_name import FeatureName
 from mloda.core.abstract_plugins.components.input_data.api.api_input_data import ApiInputData
 from mloda.core.abstract_plugins.components.input_data.base_input_data import BaseInputData
@@ -68,9 +68,9 @@ class FeatureGroup(ABC):
         making it easier to detect changes, manage compatibility, and debug issues.
 
         If you need to change the version of the feature group, you can do so by subclassing
-        FeatureGroupVersion and overriding the version method. This allows you to create a new version system.
+        BaseFeatureGroupVersion and overriding the version method. This allows you to create a new version system.
         """
-        return FeatureGroupVersion.version(cls)
+        return BaseFeatureGroupVersion.version(cls)
 
     @classmethod
     def input_data(cls) -> Optional[BaseInputData]:

mloda/core/api/feature_config/__init__.py

@@ -0,0 +1,15 @@
+"""Feature configuration loading from JSON.
+
+This module provides utilities for loading feature configurations from JSON files.
+"""
+
+from mloda.core.api.feature_config.loader import load_features_from_config
+from mloda.core.api.feature_config.models import FeatureConfig, feature_config_schema
+from mloda.core.api.feature_config.parser import parse_json
+
+__all__ = [
+    "load_features_from_config",
+    "FeatureConfig",
+    "feature_config_schema",
+    "parse_json",
+]

{mloda_plugins/config/feature → mloda/core/api/feature_config}/loader.py

@@ -6,10 +6,10 @@ to mloda Feature instances.
 """
 
 from typing import List, Union, Dict, Any
-from mloda import Feature
-from mloda import Options
-from mloda_plugins.config.feature.parser import parse_json
-from mloda_plugins.config.feature.models import FeatureConfig
+from mloda.user import Feature
+from mloda.user import Options
+from mloda.core.api.feature_config.parser import parse_json
+from mloda.core.api.feature_config.models import FeatureConfig
 from mloda_plugins.feature_group.experimental.default_options_key import DefaultOptionKeys
 
 
@@ -34,20 +34,18 @@ def process_nested_features(options: Dict[str, Any]) -> Dict[str, Any]:
             nested_options = value.get("options", {})
             processed_nested_options = process_nested_features(nested_options)
 
-            # Handle nested mloda_sources (can also be a dict)
-            mloda_sources = value.get("mloda_sources")
-            if mloda_sources:
-                if isinstance(mloda_sources, list):
+            # Handle nested in_features (can also be a dict)
+            in_features = value.get("in_features")
+            if in_features:
+                if isinstance(in_features, list):
                     # For list, convert each to string (single sources) or keep as-is
-                    processed_nested_options["in_features"] = (
-                        mloda_sources if len(mloda_sources) > 1 else mloda_sources[0]
-                    )
-                elif isinstance(mloda_sources, dict):
-                    # Recursively create Feature for mloda_sources
-                    in_features = process_nested_features({"in_features": mloda_sources})["in_features"]
+                    processed_nested_options["in_features"] = in_features if len(in_features) > 1 else in_features[0]
+                elif isinstance(in_features, dict):
+                    # Recursively create Feature for in_features
+                    in_features = process_nested_features({"in_features": in_features})["in_features"]
                     processed_nested_options["in_features"] = in_features
                 else:
-                    processed_nested_options["in_features"] = mloda_sources
+                    processed_nested_options["in_features"] = in_features
 
             # Create the Feature object
             processed[key] = Feature(name=feature_name, options=processed_nested_options)
@@ -63,10 +61,6 @@ def process_nested_features(options: Dict[str, Any]) -> Dict[str, Any]:
 def load_features_from_config(config_str: str, format: str = "json") -> List[Union[Feature, str]]:
     """Load features from a configuration string.
 
-    Uses a two-pass strategy to support feature references:
-    - Pass 1: Create all Feature objects and build a name registry
-    - Pass 2: Resolve @feature_name references to actual Feature objects
-
     Args:
         config_str: Configuration string in the specified format
         format: Configuration format (currently only "json" is supported)
@@ -79,16 +73,11 @@ def load_features_from_config(config_str: str, format: str = "json") -> List[Uni
 
     config_items = parse_json(config_str)
 
-    # Pass 1: Create all Feature objects and build registry
     features: List[Union[Feature, str]] = []
-    feature_registry: Dict[str, Feature] = {}
 
     for item in config_items:
         if isinstance(item, str):
-            # Create a Feature object for string entries so they can be referenced
-            feature = Feature(name=item, options={})
             features.append(item)
-            feature_registry[item] = feature
         elif isinstance(item, FeatureConfig):
             # Build feature name with column index suffix if present
             feature_name = item.name
@@ -99,60 +88,28 @@ def load_features_from_config(config_str: str, format: str = "json") -> List[Uni
             if item.group_options is not None or item.context_options is not None:
                 # Use new Options architecture with group/context separation
                 context = item.context_options or {}
-                # Handle mloda_sources if present
-                if item.mloda_sources:
+                # Handle in_features if present
+                if item.in_features:
                     # Always convert to frozenset for consistency
-                    context[DefaultOptionKeys.in_features] = frozenset(item.mloda_sources)
+                    context[DefaultOptionKeys.in_features] = frozenset(item.in_features)
                 options = Options(group=item.group_options or {}, context=context)
                 feature = Feature(name=feature_name, options=options)
                 features.append(feature)
-                feature_registry[feature_name] = feature
-            # Check if mloda_sources exists and create Options accordingly
-            elif item.mloda_sources:
+            # Check if in_features exists and create Options accordingly
+            elif item.in_features:
                 # Process nested features in options before creating Feature
                 processed_options = process_nested_features(item.options)
                 # Always convert to frozenset for consistency (even single items)
-                source_value = frozenset(item.mloda_sources)
+                source_value = frozenset(item.in_features)
                 options = Options(group=processed_options, context={DefaultOptionKeys.in_features: source_value})
                 feature = Feature(name=feature_name, options=options)
                 features.append(feature)
-                feature_registry[feature_name] = feature
             else:
                 # Process nested features in options before creating Feature
                 processed_options = process_nested_features(item.options)
                 feature = Feature(name=feature_name, options=processed_options)
                 features.append(feature)
-                feature_registry[feature_name] = feature
         else:
             raise ValueError(f"Unexpected config item type: {type(item)}")
 
-    # Pass 2: Resolve @feature_name references to Feature objects
-    for feat in features:
-        if isinstance(feat, Feature):
-            mloda_source = feat.options.context.get(DefaultOptionKeys.in_features)
-            if mloda_source:
-                # Handle both single string and frozenset of strings
-                if isinstance(mloda_source, str) and mloda_source.startswith("@"):
-                    # Single reference string
-                    referenced_name = mloda_source[1:]
-                    if referenced_name in feature_registry:
-                        feat.options.context[DefaultOptionKeys.in_features] = feature_registry[referenced_name]
-                    else:
-                        raise ValueError(f"Feature reference '@{referenced_name}' not found in configuration")
-                elif isinstance(mloda_source, frozenset):
-                    # Frozenset of sources - resolve any @ references
-                    resolved_sources = []
-                    for source in mloda_source:
-                        if isinstance(source, str) and source.startswith("@"):
-                            referenced_name = source[1:]
-                            if referenced_name in feature_registry:
-                                resolved_sources.append(feature_registry[referenced_name])
-                            else:
-                                raise ValueError(f"Feature reference '@{referenced_name}' not found in configuration")
-                        else:
-                            resolved_sources.append(source)
-                    # Only replace if we actually resolved any references
-                    if any(isinstance(s, str) and s.startswith("@") for s in mloda_source):
-                        feat.options.context[DefaultOptionKeys.in_features] = frozenset(resolved_sources)
-
     return features

{mloda_plugins/config/feature → mloda/core/api/feature_config}/models.py

@@ -15,7 +15,7 @@ class FeatureConfig:
 
     name: str
     options: Dict[str, Any] = field(default_factory=dict)
-    mloda_sources: Optional[List[str]] = None
+    in_features: Optional[List[str]] = None
     group_options: Optional[Dict[str, Any]] = None
     context_options: Optional[Dict[str, Any]] = None
     column_index: Optional[int] = None
@@ -37,7 +37,7 @@ def feature_config_schema() -> Dict[str, Any]:
         "properties": {
             "name": {"type": "string"},
             "options": {"type": "object", "default": {}},
-            "mloda_sources": {"type": "array", "items": {"type": "string"}},
+            "in_features": {"type": "array", "items": {"type": "string"}},
             "group_options": {"type": "object"},
             "context_options": {"type": "object"},
             "column_index": {"type": "integer"},

{mloda_plugins/config/feature → mloda/core/api/feature_config}/parser.py

@@ -6,7 +6,7 @@ This module provides parsers for configuration files in JSON format.
 
 import json
 from typing import List
-from mloda_plugins.config.feature.models import FeatureConfig, FeatureConfigItem
+from mloda.core.api.feature_config.models import FeatureConfig, FeatureConfigItem
 
 
 def parse_json(config_str: str) -> List[FeatureConfigItem]:

mloda/core/api/request.py

@@ -20,6 +20,11 @@ from mloda_plugins.feature_group.experimental.default_options_key import Default
 
 
 class mlodaAPI:
+    """Main API for executing mloda feature requests.
+
+    For JSON-based feature configuration, see `load_features_from_config()`.
+    """
+
     def __init__(
         self,
         requested_features: Union[Features, list[Union[Feature, str]]],
@@ -112,7 +117,7 @@ class mlodaAPI:
             List of computed results.
 
         Example:
-            result = mlodaAPI.run_all(
+            result = mlodamloda.run_all(
                 features,
                 api_data={"UserQuery": {"row_index": [0], "query": ["hello"]}}
             )

mloda/provider/__init__.py

@@ -2,7 +2,7 @@
 from mloda.core.abstract_plugins.feature_group import FeatureGroup as FeatureGroup
 
 # Versioning
-from mloda.core.abstract_plugins.components.feature_group_version import FeatureGroupVersion
+from mloda.core.abstract_plugins.components.base_feature_group_version import BaseFeatureGroupVersion
 from mloda.core.abstract_plugins.compute_framework import ComputeFramework as ComputeFramework
 
 # Utilities
@@ -60,7 +60,7 @@ __all__ = [
     # Base classes
     "FeatureGroup",
     # Versioning
-    "FeatureGroupVersion",
+    "BaseFeatureGroupVersion",
     "ComputeFramework",
     # Utilities
     "HashableDict",

mloda/user/__init__.py

@@ -1,5 +1,7 @@
 # API
-from mloda.core.api.request import mlodaAPI as API
+from mloda.core.api.request import mlodaAPI
+
+mloda = mlodaAPI
 
 # Features
 from mloda.core.abstract_plugins.components.feature import Feature
@@ -28,9 +30,13 @@ from mloda.core.abstract_plugins.components.parallelization_modes import Paralle
 from mloda.core.abstract_plugins.plugin_loader.plugin_loader import PluginLoader
 from mloda.core.abstract_plugins.components.plugin_option.plugin_collector import PluginCollector
 
+# Config loading
+from mloda.core.api.feature_config.loader import load_features_from_config
+
 __all__ = [
     # API
-    "API",
+    "mlodaAPI",
+    "mloda",
     # Features
     "Feature",
     "Features",
@@ -54,4 +60,6 @@ __all__ = [
     # Plugin discovery
     "PluginLoader",
     "PluginCollector",
+    # Config loading
+    "load_features_from_config",
 ]

mloda-0.4.3.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: mloda
+Version: 0.4.3
+Summary: mloda: One Data Access for ML and AI
+Author-email: Tom Kaltofen <info@mloda.ai>
+License: Apache-2.0
+Project-URL: Bug Tracker, https://github.com/mloda-ai/mloda/issues
+Project-URL: Documentation, https://mloda-ai.github.io/mloda/
+Project-URL: Source Code, https://github.com/mloda-ai/mloda
+Project-URL: PyPI, https://pypi.org/project/mloda/
+Project-URL: Homepage, https://mloda.ai
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.TXT
+License-File: NOTICE.md
+Requires-Dist: pyarrow
+Dynamic: license-file
+
+# [mloda.ai](https://mloda.ai): Open Data Access for ML & AI
+
+[![Website](https://img.shields.io/badge/website-mloda.ai-blue.svg)](https://mloda.ai)
+[![Documentation](https://img.shields.io/badge/docs-github.io-blue.svg)](https://mloda-ai.github.io/mloda/)
+[![PyPI version](https://badge.fury.io/py/mloda.svg)](https://badge.fury.io/py/mloda)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mloda-ai/mloda/blob/main/LICENSE.TXT)
+[![Tests](https://img.shields.io/badge/tests-1500%2B-green.svg)](https://github.com/mloda-ai/mloda)
+
+> **Declarative data access for AI agents. Describe what you need - mloda delivers it.**
+
+```bash
+pip install mloda
+```
+
+## 30-Second Example
+
+Your AI describes what it needs. mloda figures out how to get it:
+
+```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]
+    }}
+)
+```
+
+Copy, paste, run. mloda resolves dependencies, chains plugins, delivers data.
+
+---
+
+## What mloda Does
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      DATA USERS                                 │
+│  AI Agents  •  ML Pipelines  •  Data Science  •  Analytics      │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ describe what they need
+                            ▼
+                    ┌───────────────┐
+                    │     mloda     │  ← resolves HOW from WHAT
+                    │   [Plugins]   │
+                    └───────────────┘
+                            │ delivers trusted data
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     DATA SOURCES                                │
+│  Databases  •  APIs  •  Files  •  Any source via plugins        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Why mloda?
+
+| You want to... | mloda gives you... |
+|----------------|-------------------|
+| Give AI agents data access | Declarative API - agents describe WHAT, not HOW |
+| Trace every result | Built-in lineage back to source |
+| Reuse across projects | Plugins work anywhere - notebook to production |
+| Mix data sources | One interface for DBs, APIs, files, anything |
+
+---
+
+## AI Use Case: LLM Tool Function
+
+Let LLMs request data without writing code:
+
+```python
+# LLM generates this JSON
+llm_request = '["customer_id", {"name": "income__sum_aggr"}]'
+
+# mloda executes it
+from mloda.user import load_features_from_config
+features = load_features_from_config(llm_request, format="json")
+result = mloda.run_all(
+    features=features,
+    compute_frameworks=["PandasDataFrame"],
+    api_data={"SampleData": {"customer_id": ["C001", "C002"], "income": [50000, 75000]}}
+)
+```
+
+More patterns: [Context Window Assembly](#2-context-window-assembly) • [RAG Pipelines](#3-rag-with-feature-chaining)
+
+---
+
+## How mloda is Different
+
+mloda separates **WHAT** you need from **HOW** to get it - through plugins. Existing tools solve parts of this, but none bridge the full gap:
+
+| Category | Products | What it does | Why it's not enough |
+|----------|----------|--------------|---------------------|
+| Feature Stores | Feast, Tecton, Featureform | Store + serve features | Infrastructure-tied, storage-only |
+| Semantic Layers | dbt Semantic Layer, Cube | Declarative metrics | SQL-only, centralized |
+| DAG Frameworks | Hamilton, Kedro | Dataflows as code | Function-first, no plugin abstraction |
+| Data Catalogs | DataHub, Atlan | Metadata & discovery | No execution, no contracts |
+| ORMs | SQLAlchemy, Django ORM | Database abstraction | Single database, no ML lifecycle |
+
+**mloda is the connection layer** - separating WHAT you compute from HOW you compute it. Plugins define transformations. Users describe requirements. mloda resolves the pipeline.
+
+---
+
+## Plugins: The Building Blocks
+
+mloda's architecture follows three roles: **providers** (define plugins), **users** (access data), and **stewards** (govern execution). The module structure reflects this: `mloda.provider`, `mloda.user`, `mloda.steward`.
+
+mloda uses three types of plugins:
+
+| Type | What it does |
+|------|--------------|
+| **FeatureGroup** | Defines data transformations |
+| **ComputeFramework** | Execution backend (Pandas, Spark, etc.) |
+| **Extender** | Hooks for logging, validation, monitoring |
+
+Most of the time, you'll work with **FeatureGroups** - Python classes that define how to access and transform data (see Quick Example above).
+
+**Why plugins?**
+- **Steps, not pipelines** - Build transformations. mloda wires them together.
+- **Small and testable** - Each plugin is a focused unit. Easy to test, easy to debug.
+- **AI-friendly** - Small, template-like structures. Let AI generate plugins for you.
+- **Share what isn't secret** - Your pipeline runs steps a,b,c,d. Steps b,c,d have no proprietary logic? Share them across projects, teams, even organizations.
+- **Experiment to production** - Same plugins in your notebook and your cluster. No rewrite.
+- **Stand on shoulders** - Combine community plugins with your own. Build on what exists.
+
+---
+
+## AI Use Case Patterns
+
+### 1. LLM Tool Function
+
+Give LLMs deterministic data access - they declare what, mloda handles how:
+
+```python
+from mloda.user import PluginLoader, load_features_from_config, mloda
+PluginLoader.all()
+
+# LLM generates this JSON (no Python code needed)
+llm_output = '''
+[
+    "customer_id",
+    {"name": "income__sum_aggr"},
+    {"name": "age__avg_aggr"},
+    {"name": "total_spend", "options": {"aggregation_type": "sum", "in_features": "income"}}
+]
+'''
+
+# mloda parses JSON into Feature objects
+features = load_features_from_config(llm_output, format="json")
+
+result = mloda.run_all(
+    features=features,
+    compute_frameworks=["PandasDataFrame"],
+    api_data={"SampleData": {
+        "customer_id": ["C001", "C002", "C003"],
+        "income": [50000, 75000, 90000],
+        "age": [25, 35, 45]
+    }}
+)
+```
+
+**LLM-friendly:** The agent only declares what it needs - mloda handles the rest.
+
+### 2. Context Window Assembly
+
+Gather context from multiple sources declaratively - mloda validates and delivers. Why not let an AI agent do it?
+
+*Example: This shows the API pattern. Requires custom FeatureGroup implementations for your data sources.*
+
+```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
+```
+
+### 3. RAG with Feature Chaining
+
+Build RAG pipelines declaratively - mloda chains the steps for you.
+
+*Example: This shows the chaining syntax. Requires custom FeatureGroup implementations for retrieval and processing.*
+
+```python
+# String-based chaining: query -> validate -> retrieve -> redact
+Feature(name="user_query__injection_checked__retrieved__pii_redacted")
+
+# Configuration-based chaining: explicit pipeline
+Feature(
+    name="safe_context",
+    options=Options(context={
+        "in_features": "documents__retrieved__pii_redacted",
+        "redact_types": ["email", "phone", "ssn"]
+    })
+)
+```
+
+mloda resolves the full chain - you declare the end result, not the steps.
+
+**Automatic dependency resolution:** You only declare what you need. If `pii_redacted` depends on `retrieved` which depends on `documents`, just ask for `pii_redacted` - mloda traces back and resolves the full chain.
+
+---
+
+## Compute Frameworks
+
+Mix multiple backends in a single pipeline - mloda routes each feature to the right framework:
+
+```python
+result = mloda.run_all(
+    features=[...],
+    compute_frameworks=["PandasDataFrame", "PolarsDataFrame", "SparkFramework"]
+)
+
+# Results may come from different frameworks based on plugin compatibility
+```
+
+Add your own frameworks - mloda is extensible.
+
+---
+
+## Extenders
+
+Wrap plugin execution for logging, validation, or lineage tracking:
+
+```python
+import time
+from mloda.steward import Extender, ExtenderHook
+
+class LogExecutionTime(Extender):
+    def wraps(self):
+        return {ExtenderHook.FEATURE_GROUP_CALCULATE_FEATURE}
+
+    def __call__(self, func, *args, **kwargs):
+        start = time.time()
+        result = func(*args, **kwargs)
+        print(f"Took {time.time() - start:.2f}s")
+        return result
+
+# Use it
+result = mloda.run_all(features, function_extender={LogExecutionTime()})
+```
+
+Built-in and custom extenders give you full lineage - trace any result back to its source.
+
+---
+
+## When to Use mloda
+
+**Use mloda when:**
+- Your agents need data from multiple sources
+- You want consistent, validated data access
+- You need traceability (audit, debugging)
+- Multiple agents share the same data patterns
+
+**Don't use mloda for:**
+- Single database, simple queries → use an ORM
+- One-off scripts → just write the code
+- Real-time streaming (<5ms) → use Kafka/Flink
+
+---
+
+## Documentation
+
+- **[Getting Started](https://mloda-ai.github.io/mloda/chapter1/installation/)** - Installation and first steps
+- **[Plugin Development](https://mloda-ai.github.io/mloda/chapter1/feature-groups/)** - Build your own plugins
+- **[API Reference](https://mloda-ai.github.io/mloda/in_depth/mloda-api/)** - Complete API docs
+
+---
+
+## Contributing
+
+We welcome contributions! Build plugins, improve docs, or add features.
+
+- **[GitHub Issues](https://github.com/mloda-ai/mloda/issues/)** - Report bugs or request features
+- **[Development Guide](https://mloda-ai.github.io/mloda/development/)** - How to contribute