ml_approach_suggestion_agent 0.1.1__tar.gz

ml_approach_suggestion_agent-0.1.1/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: ml_approach_suggestion_agent
+Version: 0.1.1
+Summary: Add your description here
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic-settings
+Requires-Dist: sfn-blueprint>=0.6.15
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+
+# ml_approach_suggestion_agent
+
+An AI-powered agent that analyzes a dataset and use case to recommend the most appropriate machine learning methodology.
+
+## Description
+
+This agent takes a detailed description of a business domain, a specific use case, and information about the dataset—including column descriptions, insights, and target variable details—to suggest the best ML approach. It uses a large language model to:
+
+1.  **Analyze** the relationship between the use case and the target variable.
+2.  **Evaluate** the characteristics of the data (especially the target column).
+3.  **Recommend** the most suitable methodology from a predefined list: `Classification`, `Regression`, `Forecasting`, `Clustering`, or `No-ML`.
+4.  **Provide** a clear justification for its recommendation.
+
+This helps data scientists and analysts quickly and confidently choose the right path for their modeling efforts, saving time and reducing the risk of starting with an incorrect approach.
+
+## Key Features
+
+-   **Intelligent Use Case Analysis**: Leverages an LLM to understand the core objective of the business problem.
+-   **Target-Aware Recommendation**: Places special emphasis on the nature of the target variable to guide its decision.
+-   **Context-Driven Suggestions**: Considers the entire data context, including domain and column descriptions, to make an informed choice.
+-   **Accelerates Model Planning**: Provides a validated starting point for ML projects, ensuring alignment between the problem and the proposed solution.
+
+## Installation
+
+### Prerequisites
+
+-   [**uv**](https://docs.astral.sh/uv/getting-started/installation/) – A fast Python package and environment manager.
+    -   For a quick setup on macOS/Linux, you can use:
+        ```bash
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        ```
+-   [**Git**](https://git-scm.com/)
+
+### Steps
+
+1.  **Clone the `methodology_selection_agent` repository:**
+    ```bash
+    git clone https://github.com/stepfnAI/ml_approach_suggestion_agent.git
+    cd ml_approach_suggestion_agent
+    git switch dev
+    ```
+
+2.  **Create a virtual environment and install dependencies:**
+    This command creates a `.venv` folder in the current directory and installs all required packages.
+    ```bash
+    uv sync --extra dev
+    source .venv/bin/activate
+    ```
+
+3.  **Clone and install the `sfn_blueprint` dependency:**
+    The agent requires the `sfn_blueprint` library. The following commands clone it into a sibling directory and install it in editable mode.
+    ```bash
+    cd ../
+    git clone https://github.com/stepfnAI/sfn_blueprint.git
+    cd sfn_blueprint
+    git switch dev
+    uv pip install -e .
+    cd ../methodology_selection_agent
+    ```
+
+## Configuration
+
+You can configure the agent by creating a `.env` file in the project root or by exporting environment variables in your shell. Settings loaded via `export` will override those in a `.env` file.
+
+### Available Settings
+
+| Environment Variable            | Description                                  | Default  |
+| ------------------------------- | -------------------------------------------- | -------- |
+| `OPENAI_API_KEY`                | **(Required)** Your OpenAI API key.          | *None*   |
+| `METHODOLOGY_AI_PROVIDER`       | AI provider for methodology suggestions.     | `openai` |
+| `METHODOLOGY_AI_MODEL`          | AI model for methodology suggestions.        | `gpt-4o` |
+| `METHODOLOGY_TEMPERATURE`       | AI model temperature (e.g., `0.0` to `0.5`). | `0.3`    |
+| `METHODOLOGY_MAX_TOKENS`        | Maximum tokens for the AI response.          | `4000`   |
+
+---
+
+### Method 1: Using a `.env` File (Recommended)
+
+Create a `.env` file in the root directory to store API keys and project-wide defaults.
+
+#### Example `.env` file:
+
+```dotenv
+# .env
+
+# --- Required Settings ---
+OPENAI_API_KEY="sk-your-api-key-here"
+
+# --- Optional Overrides ---
+# Use a different model
+METHODOLOGY_AI_MODEL="gpt-4o-mini"
+
+# Use a lower temperature for more deterministic responses
+METHODOLOGY_TEMPERATURE=0.1
+```
+
+---
+
+### Method 2: Using `export` Commands
+
+Use `export` in your terminal for temporary settings or in CI/CD environments.
+
+#### Example `export` commands:
+
+```bash
+# Set the environment variables for the current terminal session
+export OPENAI_API_KEY="sk-your-api-key-here"
+export METHODOLOGY_AI_MODEL="gpt-4o-mini"
+```
+
+## Testing
+
+To run the test suite, use the following command from the root of the project directory:
+
+```bash
+pytest -s
+```
+
+## Usage
+
+### Running the Example Script
+
+To see a quick demonstration, run the provided example script. This will execute the agent with pre-defined data and print the recommended methodology.
+
+```bash
+python examples/basic_usage.py
+```
+
+### Using as a Library
+
+Integrate the `MLApproachDecisionAgent` directly into your Python applications to get methodology recommendations programmatically.
+
+```python
+import logging
+from ml_approach_suggestion_agent.agent import MLApproachDecisionAgent
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# 1. Define the domain, use case, and data context
+domain_name = "Mortgage Loan Servicing"
+domain_description = "Managing mortgage loans from post-origination to payoff, including payment collection, escrow management, and compliance for domestic and international loans."
+use_case = "To predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days using their demographic and financial data to enable proactive intervention."
+
+column_descriptions = {
+    "CreditScore": "Borrower's credit score from credit bureau sources",
+    "EmploymentStatus": "Current employment status (e.g., employed, self-employed, unemployed)",
+    # ... other column descriptions
+}
+
+column_insights = {
+  "table_info": { "row_count": 50000 },
+  "table_columns_info": {
+    "CreditScore": { "data_type": "Int64", "min_max_value": [350, 850] },
+    "EmploymentStatus": { "data_type": "string", "distinct_count": 5 },
+    # ... other column insights
+  }
+}
+
+target_column_name = "IsDelinquent"
+target_column_insights = {
+    "Target Column Description": "A binary categorical flag indicating if the borrower has missed one or more mortgage payments in the last 60 days.",
+    "Data Type": "Integer (or Boolean)",
+    "Value Distribution": {
+      "0 (Not Delinquent)": "92%",
+      "1 (Delinquent)": "8%"
+    }
+}
+
+# 2. Prepare the task data payload
+task_data = {
+    "domain_name": domain_name,
+    "domain_description": domain_description,
+    "use_case": use_case,
+    "column_descriptions": column_descriptions,
+    "column_insights": column_insights,
+    "target_column_name": target_column_name,
+    "target_column_insights": target_column_insights
+}
+
+# 3. Initialize and execute the agent
+agent = MLApproachDecisionAgent()
+result = agent(task_data)
+
+# 4. Print the suggested methodology
+if result["success"]:
+    print("Successfully suggested an approach:")
+    print(result["result"]["approach"].model_dump_json(indent=4))
+    print(f"Cost summary: {result['result']['cost_summary']}")
+else:
+    print("Failed to suggest an approach.")
+
+```
+
+### Example Output
+
+The agent returns a JSON object containing the recommended methodology and a detailed explanation for the choice.
+
+*(Note: The actual output may vary slightly based on the LLM's response.)*
+
+```json
+{
+    "recommended": "Classification",
+    "description": "The goal is to predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days. This is a binary outcome (delinquent or not delinquent), making classification the appropriate methodology. The target variable is categorical, and the available demographic and financial data can be used as features to train a classification model."
+}
+```

ml_approach_suggestion_agent-0.1.1/README.md

@@ -0,0 +1,206 @@
+# ml_approach_suggestion_agent
+
+An AI-powered agent that analyzes a dataset and use case to recommend the most appropriate machine learning methodology.
+
+## Description
+
+This agent takes a detailed description of a business domain, a specific use case, and information about the dataset—including column descriptions, insights, and target variable details—to suggest the best ML approach. It uses a large language model to:
+
+1.  **Analyze** the relationship between the use case and the target variable.
+2.  **Evaluate** the characteristics of the data (especially the target column).
+3.  **Recommend** the most suitable methodology from a predefined list: `Classification`, `Regression`, `Forecasting`, `Clustering`, or `No-ML`.
+4.  **Provide** a clear justification for its recommendation.
+
+This helps data scientists and analysts quickly and confidently choose the right path for their modeling efforts, saving time and reducing the risk of starting with an incorrect approach.
+
+## Key Features
+
+-   **Intelligent Use Case Analysis**: Leverages an LLM to understand the core objective of the business problem.
+-   **Target-Aware Recommendation**: Places special emphasis on the nature of the target variable to guide its decision.
+-   **Context-Driven Suggestions**: Considers the entire data context, including domain and column descriptions, to make an informed choice.
+-   **Accelerates Model Planning**: Provides a validated starting point for ML projects, ensuring alignment between the problem and the proposed solution.
+
+## Installation
+
+### Prerequisites
+
+-   [**uv**](https://docs.astral.sh/uv/getting-started/installation/) – A fast Python package and environment manager.
+    -   For a quick setup on macOS/Linux, you can use:
+        ```bash
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        ```
+-   [**Git**](https://git-scm.com/)
+
+### Steps
+
+1.  **Clone the `methodology_selection_agent` repository:**
+    ```bash
+    git clone https://github.com/stepfnAI/ml_approach_suggestion_agent.git
+    cd ml_approach_suggestion_agent
+    git switch dev
+    ```
+
+2.  **Create a virtual environment and install dependencies:**
+    This command creates a `.venv` folder in the current directory and installs all required packages.
+    ```bash
+    uv sync --extra dev
+    source .venv/bin/activate
+    ```
+
+3.  **Clone and install the `sfn_blueprint` dependency:**
+    The agent requires the `sfn_blueprint` library. The following commands clone it into a sibling directory and install it in editable mode.
+    ```bash
+    cd ../
+    git clone https://github.com/stepfnAI/sfn_blueprint.git
+    cd sfn_blueprint
+    git switch dev
+    uv pip install -e .
+    cd ../methodology_selection_agent
+    ```
+
+## Configuration
+
+You can configure the agent by creating a `.env` file in the project root or by exporting environment variables in your shell. Settings loaded via `export` will override those in a `.env` file.
+
+### Available Settings
+
+| Environment Variable            | Description                                  | Default  |
+| ------------------------------- | -------------------------------------------- | -------- |
+| `OPENAI_API_KEY`                | **(Required)** Your OpenAI API key.          | *None*   |
+| `METHODOLOGY_AI_PROVIDER`       | AI provider for methodology suggestions.     | `openai` |
+| `METHODOLOGY_AI_MODEL`          | AI model for methodology suggestions.        | `gpt-4o` |
+| `METHODOLOGY_TEMPERATURE`       | AI model temperature (e.g., `0.0` to `0.5`). | `0.3`    |
+| `METHODOLOGY_MAX_TOKENS`        | Maximum tokens for the AI response.          | `4000`   |
+
+---
+
+### Method 1: Using a `.env` File (Recommended)
+
+Create a `.env` file in the root directory to store API keys and project-wide defaults.
+
+#### Example `.env` file:
+
+```dotenv
+# .env
+
+# --- Required Settings ---
+OPENAI_API_KEY="sk-your-api-key-here"
+
+# --- Optional Overrides ---
+# Use a different model
+METHODOLOGY_AI_MODEL="gpt-4o-mini"
+
+# Use a lower temperature for more deterministic responses
+METHODOLOGY_TEMPERATURE=0.1
+```
+
+---
+
+### Method 2: Using `export` Commands
+
+Use `export` in your terminal for temporary settings or in CI/CD environments.
+
+#### Example `export` commands:
+
+```bash
+# Set the environment variables for the current terminal session
+export OPENAI_API_KEY="sk-your-api-key-here"
+export METHODOLOGY_AI_MODEL="gpt-4o-mini"
+```
+
+## Testing
+
+To run the test suite, use the following command from the root of the project directory:
+
+```bash
+pytest -s
+```
+
+## Usage
+
+### Running the Example Script
+
+To see a quick demonstration, run the provided example script. This will execute the agent with pre-defined data and print the recommended methodology.
+
+```bash
+python examples/basic_usage.py
+```
+
+### Using as a Library
+
+Integrate the `MLApproachDecisionAgent` directly into your Python applications to get methodology recommendations programmatically.
+
+```python
+import logging
+from ml_approach_suggestion_agent.agent import MLApproachDecisionAgent
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# 1. Define the domain, use case, and data context
+domain_name = "Mortgage Loan Servicing"
+domain_description = "Managing mortgage loans from post-origination to payoff, including payment collection, escrow management, and compliance for domestic and international loans."
+use_case = "To predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days using their demographic and financial data to enable proactive intervention."
+
+column_descriptions = {
+    "CreditScore": "Borrower's credit score from credit bureau sources",
+    "EmploymentStatus": "Current employment status (e.g., employed, self-employed, unemployed)",
+    # ... other column descriptions
+}
+
+column_insights = {
+  "table_info": { "row_count": 50000 },
+  "table_columns_info": {
+    "CreditScore": { "data_type": "Int64", "min_max_value": [350, 850] },
+    "EmploymentStatus": { "data_type": "string", "distinct_count": 5 },
+    # ... other column insights
+  }
+}
+
+target_column_name = "IsDelinquent"
+target_column_insights = {
+    "Target Column Description": "A binary categorical flag indicating if the borrower has missed one or more mortgage payments in the last 60 days.",
+    "Data Type": "Integer (or Boolean)",
+    "Value Distribution": {
+      "0 (Not Delinquent)": "92%",
+      "1 (Delinquent)": "8%"
+    }
+}
+
+# 2. Prepare the task data payload
+task_data = {
+    "domain_name": domain_name,
+    "domain_description": domain_description,
+    "use_case": use_case,
+    "column_descriptions": column_descriptions,
+    "column_insights": column_insights,
+    "target_column_name": target_column_name,
+    "target_column_insights": target_column_insights
+}
+
+# 3. Initialize and execute the agent
+agent = MLApproachDecisionAgent()
+result = agent(task_data)
+
+# 4. Print the suggested methodology
+if result["success"]:
+    print("Successfully suggested an approach:")
+    print(result["result"]["approach"].model_dump_json(indent=4))
+    print(f"Cost summary: {result['result']['cost_summary']}")
+else:
+    print("Failed to suggest an approach.")
+
+```
+
+### Example Output
+
+The agent returns a JSON object containing the recommended methodology and a detailed explanation for the choice.
+
+*(Note: The actual output may vary slightly based on the LLM's response.)*
+
+```json
+{
+    "recommended": "Classification",
+    "description": "The goal is to predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days. This is a binary outcome (delinquent or not delinquent), making classification the appropriate methodology. The target variable is categorical, and the available demographic and financial data can be used as features to train a classification model."
+}
+```

ml_approach_suggestion_agent-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ml_approach_suggestion_agent"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT" 
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10", 
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    # "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pydantic-settings",
+    "sfn-blueprint>=0.6.15",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-mock",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "."
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

ml_approach_suggestion_agent-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent/agent.py

@@ -0,0 +1,123 @@
+import json
+import logging
+from typing import Dict, Any, List, Optional, Tuple
+from datetime import datetime
+from sfn_blueprint import SFNAIHandler, self_correcting_sql, Context
+
+
+from .config import MethodologyConfig
+from .constants import format_approach_prompt
+from .models import MethodologyRecommendation
+
+
+
+class MLApproachDecisionAgent:
+    def __init__(self, config: Optional[MethodologyConfig] = None):
+        self.logger = logging.getLogger(__name__)
+        self.config = config or MethodologyConfig()
+        self.ai_handler = SFNAIHandler()
+
+    def suggest_approach(self, domain_name, domain_description, use_case, column_descriptions, column_insights, max_try=1) -> Tuple[MethodologyRecommendation, Dict[str, Any]]:
+        """
+        Suggests a machine learning approach based on the provided domain, use case, and column descriptions.
+        Args:
+            domain_name (str): The name of the domain.
+            domain_description (str): The description of the domain.
+            use_case (str): problem need to solve.
+            column_descriptions (List[str]): A list of column descriptions.
+            column_insights (List[str]): A list of column insights.
+            max_try (int, optional): The maximum number of attempts to make the API call. Defaults to 3.
+
+        Returns:
+            MethodologyRecommendation: The suggested machine learning approach.
+        
+        TODO: 
+            - USER prompt should consider those approaches which will be supported.
+            
+            
+        """
+        system_prompt, user_prompt = format_approach_prompt(domain_name=domain_name, domain_description=domain_description, use_case=use_case, column_descriptions=column_descriptions, column_insights=column_insights)
+        for _ in range(max_try):
+            try:
+                response, cost_summary = self.ai_handler.route_to(
+                    llm_provider=self.config.methodology_ai_provider,
+                    configuration={
+                        "messages": [
+                            {"role": "system", "content": system_prompt},
+                            {"role": "user", "content": user_prompt}
+                        ],
+                        "max_tokens": self.config.methodology_max_tokens,
+                        # "temperature": self.config.methodology_temperature,
+                        "text_format":MethodologyRecommendation
+                    },
+                    model=self.config.methodology_ai_model
+
+                )
+
+
+                return response, cost_summary
+
+            except Exception as e:
+                self.logger.error(f"Error while executing API call to {self.config.methodology_ai_provider}: {e}")
+
+        return {}, {}
+    
+
+
+    def execute_task(self, task_data: Dict[str, Any]) -> Dict[str, Any]:
+        self.logger.info("Executing data quality assessment task.")
+        domain_name, domain_description, use_case, column_descriptions, column_insights = (
+            task_data["domain_name"],
+            task_data["domain_description"],
+            task_data["use_case"],
+            task_data["column_descriptions"],
+            task_data["column_insights"],
+        )
+
+        # Suggest an approach
+        result, cost_summary = self.suggest_approach(
+            domain_name=domain_name,
+            domain_description=domain_description,
+            use_case=use_case,
+            column_descriptions=column_descriptions,
+            column_insights=column_insights,
+        )
+        if not result:
+            return {
+                "success": False,
+                "error": "Failed to suggest approach.",
+                "agent": self.__class__.__name__
+            }
+
+        try:
+            # Check if we have workflow storage information
+            if 'workflow_storage_path' in task_data or 'workflow_id' in task_data:
+                from sfn_blueprint import WorkflowStorageManager
+                
+                # Determine workflow storage path
+                workflow_storage_path = task_data.get('workflow_storage_path', 'outputs/workflows')
+                workflow_id = task_data.get('workflow_id', 'unknown')
+                
+                # Initialize storage manager
+                storage_manager = WorkflowStorageManager(workflow_storage_path, workflow_id)
+                storage_manager.save_agent_result(
+                    agent_name=self.__class__.__name__,
+                    step_name=" ",
+                    data={"quality_reports": result.model_dump(), "cost_summary": cost_summary},
+                    metadata={ "execution_time": datetime.now().isoformat()}
+                )
+                self.logger.info(" saved to workflow storage.")
+        except Exception as e:
+            self.logger.warning(f"Failed to save results to workflow storage: {e}")
+        
+        return {
+                "success": True,
+                "result": {
+                    "approach": result ,
+                    "cost_summary": cost_summary
+                },
+                "agent": self.__class__.__name__
+            }
+    
+    def __call__(self, task_data: Dict[str, Any]) -> Dict[str, Any]:
+        return self.execute_task(task_data)

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent/config.py

@@ -0,0 +1,20 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+
+
+class MethodologyConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file='.env',
+        env_file_encoding='utf-8',
+        case_sensitive=False,
+        extra='ignore'
+    )
+
+    methodology_ai_provider: str = Field(default="openai", description="AI provider to use")
+    methodology_ai_model: str = Field(default="gpt-4o-mini", description="AI model to use")
+    methodology_temperature: float = Field(default=0.3, ge=0.0, le=0.5, description="AI model temperature")
+    methodology_max_tokens: int = Field(default=4000, ge=100, le=8000, description="Maximum tokens for AI response")
+
+

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent/constants.py

@@ -0,0 +1,88 @@
+METHODOLOGY_SELECTION_SYSTEM_PROMPT = """You are an ML methodology advisor. Analyze the problem and select ONE methodology: binary_classification, time_series_forecasting, or not_applicable.
+
+**Simple Decision Rules:**
+
+1. **Binary Classification** - Choose when:
+   - Use case asks "predict whether", "will X happen", "classify if"
+   - Answer is YES/NO, TRUE/FALSE, or 1/0
+   - Example: "predict if machine fails", "detect fraud", "identify churn"
+
+2. **Time Series Forecasting** - Choose when:
+   - Use case asks to "forecast", "predict future value", "estimate next"
+   - Answer is a NUMERICAL value in the FUTURE
+   - Example: "forecast next month sales", "predict tomorrow's temperature"
+
+3. **Not Applicable** - Choose when:
+   - No prediction needed
+   - Just data analysis, reporting, or calculations
+   - Not enough information
+**Required Output:**
+1. Select the single best ML methodology from: binary_classification, time_series_forecasting, or not_applicable
+2. Provide a clear justification explaining:
+   - What you understand the business goal to be
+   - What type of prediction is needed (binary outcome, numerical forecast, or none)
+   - Whether temporal patterns are critical for this prediction
+   - Why the selected methodology is the best fit
+
+**Important:**
+- Having timestamps doesn't mean it's time series forecasting
+- Check WHAT is being predicted: binary outcome OR future number
+- The dataset may contain 1-4 tables - analyze all provided tables together"""
+
+
+
+METHODOLOGY_SELECTION_USER_PROMPT = """**Business Context:**
+Domain: {domain_name}
+{domain_description}
+
+**Use Case:**
+{use_case_description}
+
+**Data Overview:**
+Columns: {column_descriptions}
+
+Dataset Characteristics:
+{column_insights}
+
+"""
+
+
+def format_approach_prompt(
+    domain_name: str,
+    domain_description: str,
+    use_case: str,
+    column_descriptions: str,
+    column_insights: str
+) -> tuple[str, str]:
+    """
+    Format the methodology selection prompts for the LLM.
+    
+    Args:
+        domain_name: The domain of the data (e.g., "Healthcare", "Finance")
+        domain_description: Detailed description of the domain context
+        use_case: Description of what the user wants to achieve
+        column_descriptions: Description of the columns in the dataset
+        column_insights: Statistical insights about the columns (data types, 
+                        unique counts, distributions, etc.)
+    
+    Returns:
+        tuple[str, str]: The formatted system prompt and user prompt
+    
+    Example:
+        system_prompt, user_prompt = format_approach_prompt(
+            domain_name="E-commerce",
+            domain_description="Online retail platform with customer transactions",
+            use_case="Predict if a customer will make a purchase",
+            column_descriptions="user_id, page_views, cart_additions, timestamp",
+            column_insights="4 columns, 10000 rows, mixed types"
+        )
+    """
+    user_prompt = METHODOLOGY_SELECTION_USER_PROMPT.format(
+        domain_name=domain_name,
+        domain_description=domain_description,
+        use_case_description=use_case,
+        column_descriptions=column_descriptions,
+        column_insights=column_insights
+    )
+    
+    return METHODOLOGY_SELECTION_SYSTEM_PROMPT, user_prompt

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent/models.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, Field
+from typing import Literal
+
+class MethodologyRecommendation(BaseModel):
+    selected_methodology: Literal[ "binary_classification", "time_series_forecasting", "not_applicable"] = Field(..., description="The most appropriate ML approach for this problem")
+    
+    justification: str = Field( ..., description="Clear explanation connecting the business goal and data characteristics to the chosen methodology")

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent.egg-info/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: ml_approach_suggestion_agent
+Version: 0.1.1
+Summary: Add your description here
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic-settings
+Requires-Dist: sfn-blueprint>=0.6.15
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+
+# ml_approach_suggestion_agent
+
+An AI-powered agent that analyzes a dataset and use case to recommend the most appropriate machine learning methodology.
+
+## Description
+
+This agent takes a detailed description of a business domain, a specific use case, and information about the dataset—including column descriptions, insights, and target variable details—to suggest the best ML approach. It uses a large language model to:
+
+1.  **Analyze** the relationship between the use case and the target variable.
+2.  **Evaluate** the characteristics of the data (especially the target column).
+3.  **Recommend** the most suitable methodology from a predefined list: `Classification`, `Regression`, `Forecasting`, `Clustering`, or `No-ML`.
+4.  **Provide** a clear justification for its recommendation.
+
+This helps data scientists and analysts quickly and confidently choose the right path for their modeling efforts, saving time and reducing the risk of starting with an incorrect approach.
+
+## Key Features
+
+-   **Intelligent Use Case Analysis**: Leverages an LLM to understand the core objective of the business problem.
+-   **Target-Aware Recommendation**: Places special emphasis on the nature of the target variable to guide its decision.
+-   **Context-Driven Suggestions**: Considers the entire data context, including domain and column descriptions, to make an informed choice.
+-   **Accelerates Model Planning**: Provides a validated starting point for ML projects, ensuring alignment between the problem and the proposed solution.
+
+## Installation
+
+### Prerequisites
+
+-   [**uv**](https://docs.astral.sh/uv/getting-started/installation/) – A fast Python package and environment manager.
+    -   For a quick setup on macOS/Linux, you can use:
+        ```bash
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        ```
+-   [**Git**](https://git-scm.com/)
+
+### Steps
+
+1.  **Clone the `methodology_selection_agent` repository:**
+    ```bash
+    git clone https://github.com/stepfnAI/ml_approach_suggestion_agent.git
+    cd ml_approach_suggestion_agent
+    git switch dev
+    ```
+
+2.  **Create a virtual environment and install dependencies:**
+    This command creates a `.venv` folder in the current directory and installs all required packages.
+    ```bash
+    uv sync --extra dev
+    source .venv/bin/activate
+    ```
+
+3.  **Clone and install the `sfn_blueprint` dependency:**
+    The agent requires the `sfn_blueprint` library. The following commands clone it into a sibling directory and install it in editable mode.
+    ```bash
+    cd ../
+    git clone https://github.com/stepfnAI/sfn_blueprint.git
+    cd sfn_blueprint
+    git switch dev
+    uv pip install -e .
+    cd ../methodology_selection_agent
+    ```
+
+## Configuration
+
+You can configure the agent by creating a `.env` file in the project root or by exporting environment variables in your shell. Settings loaded via `export` will override those in a `.env` file.
+
+### Available Settings
+
+| Environment Variable            | Description                                  | Default  |
+| ------------------------------- | -------------------------------------------- | -------- |
+| `OPENAI_API_KEY`                | **(Required)** Your OpenAI API key.          | *None*   |
+| `METHODOLOGY_AI_PROVIDER`       | AI provider for methodology suggestions.     | `openai` |
+| `METHODOLOGY_AI_MODEL`          | AI model for methodology suggestions.        | `gpt-4o` |
+| `METHODOLOGY_TEMPERATURE`       | AI model temperature (e.g., `0.0` to `0.5`). | `0.3`    |
+| `METHODOLOGY_MAX_TOKENS`        | Maximum tokens for the AI response.          | `4000`   |
+
+---
+
+### Method 1: Using a `.env` File (Recommended)
+
+Create a `.env` file in the root directory to store API keys and project-wide defaults.
+
+#### Example `.env` file:
+
+```dotenv
+# .env
+
+# --- Required Settings ---
+OPENAI_API_KEY="sk-your-api-key-here"
+
+# --- Optional Overrides ---
+# Use a different model
+METHODOLOGY_AI_MODEL="gpt-4o-mini"
+
+# Use a lower temperature for more deterministic responses
+METHODOLOGY_TEMPERATURE=0.1
+```
+
+---
+
+### Method 2: Using `export` Commands
+
+Use `export` in your terminal for temporary settings or in CI/CD environments.
+
+#### Example `export` commands:
+
+```bash
+# Set the environment variables for the current terminal session
+export OPENAI_API_KEY="sk-your-api-key-here"
+export METHODOLOGY_AI_MODEL="gpt-4o-mini"
+```
+
+## Testing
+
+To run the test suite, use the following command from the root of the project directory:
+
+```bash
+pytest -s
+```
+
+## Usage
+
+### Running the Example Script
+
+To see a quick demonstration, run the provided example script. This will execute the agent with pre-defined data and print the recommended methodology.
+
+```bash
+python examples/basic_usage.py
+```
+
+### Using as a Library
+
+Integrate the `MLApproachDecisionAgent` directly into your Python applications to get methodology recommendations programmatically.
+
+```python
+import logging
+from ml_approach_suggestion_agent.agent import MLApproachDecisionAgent
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# 1. Define the domain, use case, and data context
+domain_name = "Mortgage Loan Servicing"
+domain_description = "Managing mortgage loans from post-origination to payoff, including payment collection, escrow management, and compliance for domestic and international loans."
+use_case = "To predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days using their demographic and financial data to enable proactive intervention."
+
+column_descriptions = {
+    "CreditScore": "Borrower's credit score from credit bureau sources",
+    "EmploymentStatus": "Current employment status (e.g., employed, self-employed, unemployed)",
+    # ... other column descriptions
+}
+
+column_insights = {
+  "table_info": { "row_count": 50000 },
+  "table_columns_info": {
+    "CreditScore": { "data_type": "Int64", "min_max_value": [350, 850] },
+    "EmploymentStatus": { "data_type": "string", "distinct_count": 5 },
+    # ... other column insights
+  }
+}
+
+target_column_name = "IsDelinquent"
+target_column_insights = {
+    "Target Column Description": "A binary categorical flag indicating if the borrower has missed one or more mortgage payments in the last 60 days.",
+    "Data Type": "Integer (or Boolean)",
+    "Value Distribution": {
+      "0 (Not Delinquent)": "92%",
+      "1 (Delinquent)": "8%"
+    }
+}
+
+# 2. Prepare the task data payload
+task_data = {
+    "domain_name": domain_name,
+    "domain_description": domain_description,
+    "use_case": use_case,
+    "column_descriptions": column_descriptions,
+    "column_insights": column_insights,
+    "target_column_name": target_column_name,
+    "target_column_insights": target_column_insights
+}
+
+# 3. Initialize and execute the agent
+agent = MLApproachDecisionAgent()
+result = agent(task_data)
+
+# 4. Print the suggested methodology
+if result["success"]:
+    print("Successfully suggested an approach:")
+    print(result["result"]["approach"].model_dump_json(indent=4))
+    print(f"Cost summary: {result['result']['cost_summary']}")
+else:
+    print("Failed to suggest an approach.")
+
+```
+
+### Example Output
+
+The agent returns a JSON object containing the recommended methodology and a detailed explanation for the choice.
+
+*(Note: The actual output may vary slightly based on the LLM's response.)*
+
+```json
+{
+    "recommended": "Classification",
+    "description": "The goal is to predict the likelihood of a borrower becoming delinquent on their mortgage payment within the next 60 days. This is a binary outcome (delinquent or not delinquent), making classification the appropriate methodology. The target variable is categorical, and the available demographic and financial data can be used as features to train a classification model."
+}
+```

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ml_approach_suggestion_agent/__init__.py
+src/ml_approach_suggestion_agent/agent.py
+src/ml_approach_suggestion_agent/config.py
+src/ml_approach_suggestion_agent/constants.py
+src/ml_approach_suggestion_agent/models.py
+src/ml_approach_suggestion_agent.egg-info/PKG-INFO
+src/ml_approach_suggestion_agent.egg-info/SOURCES.txt
+src/ml_approach_suggestion_agent.egg-info/dependency_links.txt
+src/ml_approach_suggestion_agent.egg-info/requires.txt
+src/ml_approach_suggestion_agent.egg-info/top_level.txt
+tests/test_agent.py

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pydantic-settings
+sfn-blueprint>=0.6.15
+
+[dev]
+pytest
+pytest-mock

ml_approach_suggestion_agent-0.1.1/src/ml_approach_suggestion_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+ml_approach_suggestion_agent

ml_approach_suggestion_agent-0.1.1/tests/test_agent.py

@@ -0,0 +1,151 @@
+
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+from collections import namedtuple
+
+from src.ml_approach_suggestion_agent.agent import MLApproachDecisionAgent
+from src.ml_approach_suggestion_agent.models import MethodologyRecommendation
+
+# Mock data for testing
+domain_obj = namedtuple("Domain", ["domain_name", "domain_description"])
+use_case_obj = namedtuple("UseCase", ["use_case_name", "use_case_description"])
+
+mock_domain = domain_obj("E-commerce", "Online retail platform")
+mock_use_case = use_case_obj("Customer Churn Prediction", "Predict which customers are likely to churn")
+mock_column_descriptions = "user_id: string, purchase_history: array, last_login: date"
+mock_column_insights = "High cardinality in user_id"
+
+
+@pytest.fixture
+def agent():
+    """Fixture for MLApproachDecisionAgent."""
+    with patch('src.ml_approach_suggestion_agent.agent.SFNAIHandler') as mock_ai_handler:
+        agent = MLApproachDecisionAgent()
+        agent.ai_handler = mock_ai_handler()
+        yield agent
+
+def test_suggest_approach_success(agent):
+    """Test successful suggestion of an ML approach."""
+    mock_response = {
+        "selected_methodology": "binary_classification",
+        "justification": "The use case is a classic classification problem."
+    }
+    cost_summary = {'prompt_tokens': 213, 'completion_tokens': 125, 'total_tokens': 338, 'total_cost_usd': 0.0018}
+    agent.ai_handler.route_to.return_value = (MethodologyRecommendation(**mock_response), cost_summary)
+    result, cost = agent.suggest_approach(mock_domain.domain_name, mock_domain.domain_description, mock_use_case, mock_column_descriptions, mock_column_insights)
+
+    assert isinstance(result, MethodologyRecommendation)
+    assert result.selected_methodology == "binary_classification"
+    assert cost == cost_summary
+
+def test_suggest_approach_failure_json(agent):
+    """Test failure due to invalid JSON response."""
+    agent.ai_handler.route_to.side_effect = Exception("Simulating JSON parsing error")
+    result, cost = agent.suggest_approach(mock_domain.domain_name, mock_domain.domain_description, mock_use_case, mock_column_descriptions, mock_column_insights, max_try=1)
+
+    assert result == {}
+    assert cost == {}
+
+def test_suggest_approach_api_error(agent):
+    """Test failure due to an API error."""
+    agent.ai_handler.route_to.side_effect = Exception("API Error")
+
+    result, cost = agent.suggest_approach(mock_domain.domain_name, mock_domain.domain_description, mock_use_case, mock_column_descriptions, mock_column_insights, max_try=1)
+
+    assert result == {}
+    assert cost == {}
+
+@patch('src.ml_approach_suggestion_agent.agent.MLApproachDecisionAgent.suggest_approach')
+def test_execute_task_success(mock_suggest_approach):
+    """Test successful execution of the task."""
+    agent = MLApproachDecisionAgent()
+    mock_response = MethodologyRecommendation(
+        selected_methodology="binary_classification",
+        justification="The use case is a classic classification problem."
+    )
+    mock_suggest_approach.return_value = (mock_response, {"cost": 0.1})
+
+    task_data = {
+        "domain_name": mock_domain.domain_name,
+        "domain_description": mock_domain.domain_description,
+        "use_case": mock_use_case,
+        "column_descriptions": mock_column_descriptions,
+        "column_insights": mock_column_insights,
+    }
+
+    result = agent.execute_task(task_data)
+
+    assert result["success"] is True
+    assert result["result"]["approach"].selected_methodology == "binary_classification"
+    assert result["result"]["cost_summary"] == {"cost": 0.1}
+    mock_suggest_approach.assert_called_once_with(
+        domain_name=mock_domain.domain_name,
+        domain_description=mock_domain.domain_description,
+        use_case=mock_use_case,
+        column_descriptions=mock_column_descriptions,
+        column_insights=mock_column_insights,
+    )
+
+@patch('src.ml_approach_suggestion_agent.agent.MLApproachDecisionAgent.suggest_approach')
+def test_execute_task_failure(mock_suggest_approach):
+    """Test failure during task execution."""
+    agent = MLApproachDecisionAgent()
+    mock_suggest_approach.return_value = (None, {})
+
+    task_data = {
+        "domain_name": mock_domain.domain_name,
+        "domain_description": mock_domain.domain_description,
+        "use_case": mock_use_case,
+        "column_descriptions": mock_column_descriptions,
+        "column_insights": mock_column_insights,
+    }
+
+    result = agent.execute_task(task_data)
+
+    assert result["success"] is False
+    assert result["error"] == "Failed to suggest approach."
+    mock_suggest_approach.assert_called_once_with(
+        domain_name=mock_domain.domain_name,
+        domain_description=mock_domain.domain_description,
+        use_case=mock_use_case,
+        column_descriptions=mock_column_descriptions,
+        column_insights=mock_column_insights,
+    )
+
+@patch('sfn_blueprint.WorkflowStorageManager')
+@patch('src.ml_approach_suggestion_agent.agent.MLApproachDecisionAgent.suggest_approach')
+def test_execute_task_with_storage(mock_suggest_approach, mock_storage_manager):
+    """Test task execution with result storage."""
+    agent = MLApproachDecisionAgent()
+    mock_response = MethodologyRecommendation(
+        selected_methodology="binary_classification",
+        justification="The use case is a classic classification problem."
+    )
+    mock_suggest_approach.return_value = (mock_response, {"cost": 0.1})
+    
+    # Mock the storage manager instance
+    mock_storage_instance = MagicMock()
+    mock_storage_manager.return_value = mock_storage_instance
+
+    task_data = {
+        "domain_name": mock_domain.domain_name,
+        "domain_description": mock_domain.domain_description,
+        "use_case": mock_use_case,
+        "column_descriptions": mock_column_descriptions,
+        "column_insights": mock_column_insights,
+        "workflow_storage_path": "/tmp/test",
+        "workflow_id": "test_workflow"
+    }
+
+    result = agent.execute_task(task_data)
+
+    assert result["success"] is True
+    mock_storage_instance.save_agent_result.assert_called_once()
+    
+    # Get the arguments passed to save_agent_result
+    _, kwargs = mock_storage_instance.save_agent_result.call_args
+    assert kwargs['agent_name'] == "MLApproachDecisionAgent"
+    assert kwargs['step_name'] == " "
+    assert kwargs['data'] == {"quality_reports": mock_response.model_dump(), "cost_summary": {"cost": 0.1}}
+