Create Technical_README.md

Technical_README.md

@@ -0,0 +1,1726 @@
+# **Agentic Machine Learning Engineer (Traditional ML Engineering) - Qwen3-Coder-30B-A3B-Instruct**
+
+#### Note 1: Do not upload confidential, regulated, proprietary, customer, or personally identifiable production data into a public Hugging Face Space
+
+#### Note 2: This project is an automated traditional machine learning engineering experiment focused on supervised classification and regression workflows
+
+#### Note 3: This project uses a bounded single-agent function-calling / tool-use loop rather than an unlimited autonomous agent
+---
+### (this) Bounded Tool-Calling Agent vs Open-Ended Autonomous Agent
+
+**Bounded Tool-Calling Agent (my agent)**
+
+> “Reason about the task, call the available ML tools when needed, and stop within a controlled number of steps.”
+
+**Open-Ended Autonomous Agent**
+
+> “Continue deciding and acting until the broader goal is achieved.”
+
+|                           | Bounded Tool-Calling Agent                          | Open-Ended Autonomous Agent                 |
+| ------------------------- | --------------------------------------------------- | ------------------------------------------- |
+| **Consistency**           | higher because tools and loop limits are controlled | can vary more between runs                  |
+| **Traceability**          | tool calls and observations are exposed             | can become harder to trace across long runs |
+| **Resource control**      | hard max agent-step limit                       | may require additional stopping logic       |
+| **Decision-making**       | dynamic tool selection within a constrained toolset | can make broader autonomous decisions       |
+| **Flexibility**           | controlled                                          | higher                                      |
+| **Risk of runaway loops** | reduced through `MAX_AGENT_STEPS` param                   | higher without explicit limits              |
+
+bounded agent **decides which ML operation to perform inside a controlled tool loop**, while a fully open-ended autonomous agent may continue planning and acting without the same fixed execution boundary.
+
+---
+
+### Agent Goals:
+
+* agentic machine learning engineering app for profiling datasets, automated supervised-learning modeling, preprocessing data, training baseline models, comparing algorithms, evaluating real model performance, and generating reusable scikit-learn pipelines
+
+* agent loads a real-world dataset, creates the modeling context, gives a Qwen3-Coder agent access to machine-learning tools, and allows the model to decide which tools to call before producing a final ML assessment and reusable pipeline code
+
+* reduce repetitive setup work when starting supervised machine learning experiments
+
+* ground model-performance claims in actual scikit-learn execution
+
+* expose tool calls and observations for auditability
+
+* demonstrate how an LLM can orchestrate traditional machine learning workflows without performing the numerical fitting itself
+
+---
+
+### Machine Learning Agent - Tasks
+
+Machine Learning Agent can analyze datasets and execute supervised-learning workflows by first understanding the dataset, target, feature types, and modeling objective.
+
+#### Dataset inspection
+
+`inspect_dataset` tool can analyze:
+
+* **Shape**: number of rows and columns
+* **Columns**: available feature / target candidates
+* **Types**: pandas data types
+* **Numeric features**: identified numerical columns
+* **Categorical features**: identified categorical columns
+* **Nulls**: missing-value information
+* **Cardinality**: number of unique values per column
+* **Examples**: representative values from each column
+* **Targets**: possible prediction-target columns
+
+#### Modeling tasks
+
+the ML workflow can:
+
+* inspect the dataset
+* identify a prediction target
+* infer classification vs regression
+* separate numeric and categorical features
+* construct preprocessing transformations
+* train baseline estimators
+* calculate holdout metrics
+* compare compatible algorithms
+* inspect feature importance / coefficients where supported
+* generate reusable scikit-learn pipeline code
+* export fitted pipelines as Joblib artifacts
+
+findings can then be converted into:
+
+```text
+ Dataset assessment
+        ↓
+Recommended modeling setup
+        ↓
+Preprocessing pipeline
+        ↓
+ Model training
+        ↓
+Holdout evaluation
+        ↓
+Algorithm comparison
+        ↓
+Reusable scikit-learn pipeline
+```
+
+## **What, Why, and General Objectives**
+
+### What
+
+Tool-using Machine Learning Engineering AI agent that profiles datasets, determines supervised-learning setup, trains real scikit-learn models, compares algorithms, evaluates model performance, and generates reusable ML pipelines.
+
+### Why
+
+Machine learning engineers repeatedly perform the same early-stage workflow when starting supervised learning related tasks/projects:
+
+```text
+load dataset
+     ↓
+inspect features + target
+     ↓
+determine problem type
+     ↓
+build preprocessing
+     ↓
+select algorithm
+     ↓
+train model
+     ↓
+evaluate performance
+     ↓
+compare alternatives
+     ↓
+generate reusable pipeline
+```
+
+automating this workflow reduces repetitive machine learning setup, baseline experimentation, preprocessing, evaluation, and pipeline-generation work
+
+### General Objectives
+
+* automate traditional ML modeling
+
+* make model evaluation traceable through tool outputs
+
+* provide a consistent preprocessing and model-training workflow
+
+* compare baseline algorithms quickly
+
+* calculate metrics from real fitted models rather than LLM estimates
+
+* generate reusable scikit-learn pipeline code
+
+* expose tool calls and observations for auditability
+
+* demonstrate how an LLM agent can orchestrate traditional machine learning tools
+
+* keep local ML execution lightweight enough for Hugging Face Spaces
+
+## **LLM / Agent Stack**
+
+* **Agent LLM:** [**Qwen/Qwen3-Coder-30B-A3B-Instruct**](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct)
+
+* **Inference:** `huggingface_hub.InferenceClient`
+
+* **Provider routing:** Hugging Face Inference Providers using `provider="auto"` by default
+
+* **Agent pattern:** bounded single-agent function-calling / tool-use loop
+
+* **Tool routing:** `tool_choice="auto"`
+
+* **Maximum agent steps:** `4` by default
+
+  * **Prevent Infinite Loops:** keeps the agent from repeatedly calling the same tool or getting stuck in an unsuccessful reasoning loop
+
+  * **Control Costs:** limits unnecessary inference-provider requests and token usage
+
+  * **Manage Context Windows:** prevents tool observations from growing indefinitely inside the conversation context
+
+  * **Reduce Latency:** prevents unnecessarily long tool-calling runs
+
+  * **Improve Debuggability:** provides a predictable execution boundary when analyzing the tool trace
+
+* **Local ML execution:** scikit-learn
+
+* **Dataset processing:** pandas
+
+* **Model artifact export:** Joblib
+
+* **Parquet support:** PyArrow
+
+* **Excel support:** OpenPyXL
+
+* **HF sample dataset:** `scikit-learn/adult-census-income`
+
+
+## **Goal:**
+
+machine learning engineering is not only model generation
+
+a usable supervised ML workflow requires:
+
+* understanding the dataset
+
+* selecting a prediction target
+
+* deciding whether the task is classification or regression
+
+* identifying numerical and categorical features
+
+* preprocessing missing and categorical data
+
+* selecting an estimator
+
+* training models on real data
+
+* calculating ML evaluation metrics
+
+* comparing alternatives options (ML models)
+
+* packaging preprocessing + model logic into reusable code
+
+doing this manually for every new dataset creates repetitive experimentation and setup work.
+
+this Machine Learning Engineering Agent is designed to:
+
+* reduce time spent manually inspecting new datasets
+
+* establish a consistent supervised-learning baseline workflow
+
+* identify numerical and categorical feature requirements
+
+* infer or use a selected classification / regression problem type
+
+* allow the LLM to call machine-learning execution functions
+
+* train real models through scikit-learn
+
+* calculate real holdout evaluation metrics
+
+* compare compatible baseline algorithms
+
+* generate production-oriented scikit-learn pipelines
+
+* export fitted pipelines as Joblib artifacts
+
+* expose the agent's tool calls through a trace for auditability
+
+goal of the app is to combine:
+
+```text
+LLM reasoning
+      +
+ML execution
+      +
+tool calling
+      +
+reusable pipeline generation
+```
+
+## **Agentic Workflow:**
+
+```text
+Dataset
+   ↓
+ app.py
+   ↓
+Dataset loading + session state
+   ↓
+Dataset profile
+   ↓
+Target selection
+   ↓
+Problem-type inference / selection
+   ↓
+Algorithm selection
+   ↓
+MachineLearningAgent
+   ↓
+Qwen3-Coder-30B-A3B-Instruct
+   ↓
+HF InferenceClient
+   ↓
+tool_choice="auto"
+   ↓
+Agent decides which ML tool(s) to call
+   ↓
+┌──────────────────────────────────────────────┐
+│ inspect_dataset                              │
+│ recommend_modeling_setup                     │
+│ train_candidate_model                        │
+│ compare_algorithms                           │
+│ generate_pipeline_code                       │
+└──────────────────────────────────────────────┘
+   ↓
+Tool observations returned to Qwen
+   ↓
+Agent evaluates whether another tool is needed
+   ↓
+Bounded tool-use loop
+   ↓
+ML assessment
+   ↓
+Modeling risks
+   ↓
+Recommended modeling setup
+   ↓
+Evaluation findings
+   ↓
+Model comparison
+   ↓
+Generated scikit-learn pipeline
+   ↓
+Tool Trace + Diagnostics
+```
+
+## **Agent Loop Type**
+
+### **Bounded Single-Agent Function-Calling / Tool-Use Loop**
+
+* agentic pattern where one AI agent can autonomously choose from external ML tools, process their outputs, and repeat the process inside a strictly defined step limit
+
+* unlike open-ended agents that can continue indefinitely, this bounded loop places a hard-fixed limit on execution
+
+* the project uses a **single agent**, not a multi-agent architecture
+
+### **Architecture:**
+
+**observe task → choose tool → execute ML operation → return observation → repeat if needed → synthesize final answer**
+
+the LLM does not directly calculate every machine learning result itself
+
+`MachineLearningAgent` exposes Python / scikit-learn tools to Qwen through Hugging Face function calling
+
+the model receives:
+
+* system instructions
+
+* user machine learning task
+
+* dataset profile
+
+* selected target
+
+* inferred or selected problem type
+
+* selected algorithm
+
+* available tool definitions
+
+the model can then request one or more tool calls.
+
+### Example Input Workflow
+
+```text
+Qwen
+  ↓
+inspect_dataset()
+  ↓
+dataset profile returned to Qwen
+  ↓
+recommend_modeling_setup()
+  ↓
+recommended setup returned to Qwen
+  ↓
+train_candidate_model()
+  ↓
+real training metrics returned to Qwen
+  ↓
+compare_algorithms()
+  ↓
+algorithm leaderboard returned to Qwen
+  ↓
+generate_pipeline_code()
+  ↓
+scikit-learn pipeline code returned to Qwen
+  ↓
+Final ML response
+```
+
+loop is bounded by:
+
+```text
+MAX_AGENT_STEPS = 4
+```
+
+if the model does not finish within the configured tool loop, the application moves toward final response synthesis rather than allowing unlimited additional tool calls.
+
+this makes the architecture a controlled **bounded tool-calling machine learning agent**.
+
+## **Agent Architecture:**
+
+```text
+                         USER
+                           │
+                           ▼
+                  ┌─────────────────┐
+                  │     app.py      │
+                  │   Gradio UI     │
+                  │ Session state   │
+                  │ Dataset loading │
+                  └────────┬────────┘
+                           │
+                           │ task + dataset + target
+                           ▼
+               ┌────────────────────────┐
+               │ MachineLearningAgent   │
+               │       agent.py         │
+               └────────────┬───────────┘
+                            │
+                            ▼
+               ┌────────────────────────┐
+               │ Qwen3-Coder 30B A3B    │
+               │ HF InferenceClient     │
+               │ tool_choice="auto"     │
+               └────────────┬───────────┘
+                            │
+                     decides which tool
+                        to execute
+                            │
+        ┌───────────────────┼────────────────────┐
+        │                   │                    │
+        ▼                   ▼                    ▼
+ inspect_dataset   recommend_modeling_setup   train_candidate_model
+        │                   │                    │
+        └───────────────────┼────────────────────┘
+                            │
+                            ▼
+                    compare_algorithms
+                            │
+                            ▼
+                  generate_pipeline_code
+                            │
+                            ▼
+                     Tool observation
+                            │
+                            ▼
+               ┌────────────────────────┐
+               │ Observation added back │
+               │    to LLM context      │
+               └────────────┬───────────┘
+                            │
+                            ▼
+                     More tools needed?
+                       /           \
+                     yes            no
+                      │              │
+                      └──────┐       │
+                             │       │
+                             ▼       ▼
+                         Tool loop   Final synthesis
+                                         │
+                                         ▼
+                                  ML assessment
+                                  Modeling risks
+                                  Recommended setup
+                                  Evaluation findings
+                                  Model comparison
+                                  Pipeline code
+                                  Tool trace
+```
+
+
+### **Core Architectural Pattern:**
+
+```text
+app.py
+   ↓
+agent.py
+   ↓
+MachineLearningAgent
+   ↓
+Qwen3-Coder + HF tool calling
+   ↓
+ml_engine.py
+   ↓
+ML operations
+   ↓
+tool observations
+   ↓
+agent.py
+   ↓
+final ML assessment + pipeline code
+```
+
+
+## **Agent Tools**
+
+### **1. `inspect_dataset`**
+
+analyzes the loaded dataset and returns structural information used by the agent before modeling
+
+typical outputs include:
+
+* source
+
+* row count
+
+* column count
+
+* column names
+
+* feature types
+
+* pandas dtypes
+
+* null information
+
+* unique-value information
+
+* possible target columns
+
+* example values
+
+used when the agent needs to understand the structure of the dataset before recommending a modeling approach
+
+---
+
+### **2. `recommend_modeling_setup`**
+
+evaluates the dataset and selected target to recommend a supervised-learning configuration
+
+recommendation can include:
+
+* target column
+
+* inferred problem type
+
+* candidate algorithms
+
+* dataset characteristics relevant to modeling
+
+* preprocessing expectations
+
+* numerical feature information
+
+* categorical feature information
+
+goal: setup a reasonable baseline modeling configuration before training
+
+---
+
+### **3. `train_candidate_model`**
+
+builds and trains the selected scikit-learn pipeline using the actual loaded dataset
+
+training workflow:
+
+```text
+dataset
+   ↓
+feature / target split
+   ↓
+train / holdout split
+   ↓
+numeric preprocessing
+   ↓
+categorical preprocessing
+   ↓
+selected estimator
+   ↓
+  fit
+   ↓
+holdout prediction
+   ↓
+holdout evaluation
+```
+
+the agent receives metrics produced by the trained model
+
+the agent is instructed not to invent performance values
+
+---
+
+### **4. `compare_algorithms`**
+
+trains compatible baseline algorithms and returns a comparison leaderboard based on real holdout results.
+
+classification, candidate algorithms include:
+
+* Logistic Regression
+
+* Random Forest Classifier
+
+* SGD Classifier
+
+* Linear SVM Classifier
+
+for regression, candidate algorithms include:
+
+* Ridge Regression
+
+* Random Forest Regressor
+
+* SGD Regressor
+
+this allows the agent to compare alternatives using actual evaluation results instead of guessing which model performs best.
+
+---
+
+### **5. `generate_pipeline_code`**
+
+generates reusable scikit-learn pipeline code grounded in:
+
+* loaded dataset
+
+* target column
+
+* problem type
+
+* selected algorithm
+
+* numeric features
+
+* categorical features
+
+generated code includes preprocessing and estimator construction so the workflow can be moved beyond the interactive application.
+
+## **App Fallback**
+
+app also includes a non-agent fallback path.
+
+```text
+HF_TOKEN configured?
+        │
+    ┌───┴───┐
+    │       │
+   yes      no
+    │       │
+    ▼       ▼
+Qwen agent  fallback
+tool loop      │
+    │          ├── inspect dataset
+    │          ├── infer modeling setup
+    │          ├── train baseline model
+    │          ├── calculate real metrics
+    │          └── generate pipeline code
+    │
+    └──────────┬──────────
+               ▼
+            UI output
+```
+
+fallback can also be used if the Hugging Face model request fails.
+
+this means the application can still:
+
+* profile the dataset
+
+* infer a modeling setup
+
+* train the selected baseline
+
+* calculate real holdout metrics
+
+* generate scikit-learn pipeline code
+
+without requiring the Qwen agent to successfully complete the tool-calling workflow.
+
+## **Dataset Support**
+
+app can preload a public Hugging Face dataset or accept a user-uploaded dataset.
+
+uploaded dataset files can include:
+
+1. CSV
+2. Parquet
+3. JSON
+4. JSONL
+5. XLSX
+6. XLS
+
+the app profiles the dataset before exposing it to the ML workflow.
+
+### **Hugging Face Example Dataset**
+
+default public example dataset:
+
+```text
+scikit-learn/adult-census-income
+```
+
+default prediction target:
+
+```text
+income
+```
+
+the sample dataset is intended for binary classification.
+
+users can replace the preloaded example with their own supported dataset through the upload interface.
+
+
+## **Preprocessing Pipeline**
+
+the scikit-learn workflow separates numerical and categorical processing.
+
+```text
+numeric features
+      ↓
+median imputation
+      ↓
+scaling when appropriate
+
+
+categorical features
+      ↓
+most-frequent imputation
+      ↓
+one-hot encoding
+
+
+numeric + categorical features
+      ↓
+ColumnTransformer
+      ↓
+selected estimator
+      ↓
+trained Pipeline
+```
+
+this keeps preprocessing and model inference inside the same reusable scikit-learn pipeline.
+
+
+## **Model Lab**
+
+### **Classification Algorithms**
+
+* Logistic Regression
+
+* Random Forest Classifier
+
+* SGD Classifier
+
+* Linear SVM Classifier
+
+### **Regression Algorithms**
+
+* Ridge Regression
+
+* Random Forest Regressor
+
+* SGD Regressor
+
+the selected algorithm is trained locally through automated scikit-learn pipelines.
+
+
+## **Evaluation**
+
+### **Classification Metrics**
+
+classification evaluation can include:
+
+* [accuracy](https://www.geeksforgeeks.org/machine-learning/metrics-for-machine-learning-model/)
+
+* [weighted precision](https://www.geeksforgeeks.org/machine-learning/metrics-for-machine-learning-model/)
+
+* [weighted recall](https://www.geeksforgeeks.org/machine-learning/metrics-for-machine-learning-model/)
+
+* [weighted F1](https://www.geeksforgeeks.org/machine-learning/metrics-for-machine-learning-model/)
+
+* [ROC-AUC](https://www.geeksforgeeks.org/machine-learning/metrics-for-machine-learning-model/)
+
+### **Regression Metrics**
+
+regression evaluation includes:
+
+* [**MAE**](https://www.datacamp.com/tutorial/mean-absolute-error)
+   * ml regression evaluation metric used to measure the average magnitude of prediction errors in machine learning regression models
+
+* [**RMSE**](https://c3.ai/resources/glossary/data-science/root-mean-square-error-rmse)
+   * ml regression evaluation metric used to measure the average magnitude of error in regression machine learning models
+
+* [**R²**](https://www.geeksforgeeks.org/machine-learning/ml-r-squared-in-regression-analysis/)
+   * ml regression evaluation metric that measures the goodness of fit for a regression model by showing the proportion of variance in the dependent target variable that is explained by the independent features
+
+**note:** evaluation values are produced by the local scikit-learn execution layer rather than estimated by the LLM.
+
+## **Agent Outputs**
+
+final agent response is designed to contain:
+
+1. ML assessment
+2. Modeling risks
+3. Recommended modeling setup
+4. Evaluation findings
+5. Model comparison
+6. Pipeline recommendation
+7. Generated scikit-learn code
+8. Tool trace
+
+app separately exposes structured modeling outputs such as:
+
+* metrics
+
+* leaderboard
+
+* feature importance / coefficients
+
+* pipeline code
+
+* model artifact
+
+* tool trace
+
+* runtime diagnostics
+
+
+## **Agent Metrics / UI**
+
+### **1. Dataset Workspace**
+
+dataset workspace shows:
+
+**Dataset source**
+
+* Hugging Face example-dataset loading
+
+* local file upload
+
+**Data preview**
+
+* preview of the currently loaded dataset
+
+**Inferred schema / feature information**
+
+* column
+
+* pandas dtype
+
+* numeric / categorical feature information
+
+* null information
+
+* unique-value information
+
+* example values
+
+* possible target columns
+
+---
+
+### **2. Model Lab**
+
+model workspace allows the user to configure:
+
+**Target column**
+
+* selected prediction target
+
+**Problem type**
+
+* classification
+
+* regression
+
+**Algorithmic Selection:**
+
+classification:
+
+* [**Logistic Regression**](https://www.geeksforgeeks.org/machine-learning/understanding-logistic-regression/)
+   * classification based supervised ML algorithm used to predict the probability of a categorical target variable
+
+* [**Random Forest Classifier**](https://www.geeksforgeeks.org/random-forest-classifier-using-scikit-learn/)
+   * ensemble ML algorithm that builds multiple decision trees and combines their predictions to improve accuracy and reduce overfitting
+
+* [**SGD Classifier**](https://scikit-learn.org/stable/modules/sgd.html)
+   * efficient ML estimator that optimizes regularized linear models using a first-order optimization routine. Instead of a distinct machine learning algorithm itself, it represents an optimization methodology used to train traditional linear models like Support Vector Machines (SVM) or Logistic Regression
+
+* [**Linear SVM Classifier**](https://www.geeksforgeeks.org/machine-learning/support-vector-machine-algorithm/)
+   * supervised ML algorithm used to sort data into discrete categories by drawing a straight decision boundary
+
+regression:
+
+* [**Ridge Regression**](https://www.geeksforgeeks.org/machine-learning/what-is-ridge-regression/)
+   * L2 regularization, is a modified version of linear regression designed to improve a model's stability and prevent overfitting.
+   * standard linear regression only focuses on minimizing the difference between predicted and actual values, it often becomes unstable when dealing with highly correlated variables (multicollinearity) or a large number of features. **Ridge regression fixes this by penalizing the model for having excessively large coefficients, forcing them to shrink toward zero.**
+
+* [**Random Forest Regressor**](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestRegressor.html)
+   * ensemble machine learning algorithm used to predict continuous numerical values (e.g. housing prices, temperatures, or stock trends). algorithm works by building multiple independent decision trees at training time and outputting the average prediction of all the individual trees. this method, known as Bootstrap Aggregating (Bagging), reduces overfitting and improves model accuracy
+
+* [**SGD Regressor**](https://www.geeksforgeeks.org/python/stochastic-gradient-descent-regressor/):
+   * linear regression model trained using Stochastic Gradient Descent (SGD), an iterative optimization technique that updates model parameters one sample at a time rather than using the entire dataset at once
+   * how SGD Regressor Works
+      * Sample-by-Sample Updates: estimates the gradient of the loss function using a single randomly chosen data point (or a small mini-batch) per step, then adjusts the weights immediately.
+      * Loss Functions: supports ordinary least squares (squared_error), robust regression (huber), and linear support vector regression (epsilon_insensitive).
+      * Regularization: includes penalties like L2 (ridge), L1 (lasso), or a mix of both (elasticnet) to shrink weights and avoid overfitting.
+      * Key Advantages:
+         * Speed with Big Data: trains much faster than traditional batch gradient descent when dealing with massive datasets containing over 10,000 samples.
+         * Online Learning: supports partial_fit, meaning it can continuously learn from real-time data streams as new information arrives.
+         * Escaping Local Minima: inherent noise in single-sample updates helps the algorithm jump out of shallow local minimums in complex cost surfaces.
+
+app can then expose:
+
+* fitted model metrics
+
+* feature importance or coefficients
+
+* generated pipeline artifact
+
+* generated pipeline code
+
+---
+
+### **3. Model Comparison**
+
+comparison workflow trains compatible baseline estimators and returns a leaderboard using real holdout results.
+
+this provides a comparison layer that the LLM can reference during final synthesis.
+
+the comparison values are derived from actual model execution instead of LLM-generated estimates.
+
+---
+
+### **4. Machine Learning Agent**
+
+agent workspace accepts a natural-language ML engineering task.
+
+Qwen agent can then:
+
+* inspect the dataset
+
+* recommend a modeling setup
+
+* train a candidate model
+
+* compare algorithms
+
+* generate pipeline code
+
+* synthesize findings from tool observations
+
+---
+
+### **5. Tool Trace**
+
+every agent tool invocation is appended to the tool trace.
+
+Example trace:
+
+```json
+[
+  {
+    "tool": "inspect_dataset",
+    "arguments": {},
+    "result": {
+      "rows": 32561,
+      "columns": 15
+    }
+  },
+  {
+    "tool": "train_candidate_model",
+    "arguments": {
+      "target": "income",
+      "algorithm": "Logistic Regression"
+    },
+    "result": {
+      "metrics": "holdout metrics"
+    }
+  }
+]
+```
+
+trace allows the user to analyze / inspect:
+
+* which tools were called
+
+* arguments passed to each tool
+
+* tool observations
+
+* number of tool calls
+
+* modeling operations performed during the agent loop
+
+---
+
+### **6. Diagnostics**
+
+runtime diagnostics can include:
+
+* model
+
+* provider
+
+* HF token configured
+
+* tool-call count
+
+* tools used
+
+* selected algorithm
+
+* problem type
+
+* target
+
+Example:
+
+```json
+{
+  "model": "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+  "provider": "HF automatic routing",
+  "hf_token_configured": true,
+  "tool_calls": 4,
+  "tools_used": [
+    "inspect_dataset",
+    "recommend_modeling_setup",
+    "train_candidate_model",
+    "compare_algorithms"
+  ],
+  "target": "income",
+  "problem_type": "classification",
+  "algorithm": "Logistic Regression"
+}
+```
+
+the provider can appear as:
+
+```text
+HF automatic routing
+```
+
+when a specific inference provider is not explicitly configured.
+
+
+## **Local ML Execution Model**
+
+model training is performed directly inside the application with scikit-learn.
+
+```text
+Loaded dataset
+      ↓
+pandas DataFrame
+      ↓
+feature / target split
+      ↓
+scikit-learn preprocessing
+      ↓
+scikit-learn estimator
+      ↓
+local CPU training
+      ↓
+holdout predictions
+      ↓
+evaluation metrics
+      ↓
+Joblib artifact
+```
+
+Qwen3-Coder does **not** perform the numerical model fitting itself.
+
+```text
+Qwen3-Coder
+    ↓
+reasoning + tool selection + synthesis
+
+scikit-learn
+    ↓
+preprocessing + training + prediction + evaluation
+```
+
+this keeps model-performance claims grounded in real execution.
+
+## **Machine Learning Execution Separation**
+
+### Qwen3-Coder
+
+responsible for:
+
+* understanding the user's ML task
+
+* selecting appropriate tools
+
+* interpreting dataset observations
+
+* reasoning about modeling risks
+
+* deciding whether additional tools are required
+
+* synthesizing the final response
+
+### scikit-learn
+
+responsible for:
+
+* preprocessing
+
+* train / holdout splitting
+
+* fitting estimators
+
+* making predictions
+
+* calculating evaluation metrics
+
+* model comparison
+
+* fitted-pipeline generation
+
+conceptually:
+
+```text
+User task
+   ↓
+Qwen3-Coder
+   ↓
+Select ML operation
+   ↓
+scikit-learn tool
+   ↓
+Real execution result
+   ↓
+Qwen3-Coder
+   ↓
+Interpret result / select next tool
+   ↓
+Final ML assessment
+```
+
+## **File Descriptions**
+
+### **`agent.py`**
+
+main agent implementation.
+
+contains the logic for:
+
+* system prompt
+
+* tool schemas
+
+* `MachineLearningAgent`
+
+* tool dispatch
+
+* fallback
+
+* bounded agent loop
+
+* `HF InferenceClient` requests
+
+* `tool_choice="auto"`
+
+* tool observations
+
+* final response synthesis
+
+architecturally:
+
+```text
+agent.py
+   ↓
+decides WHAT ML action is needed
+   ↓
+ml_engine.py
+   ↓
+executes the ML operation
+```
+
+---
+
+### **`ml_engine.py`**
+
+machine learning execution layer.
+
+contains:
+
+* dataset loading
+
+* dataset profiling
+
+* target inference
+
+* problem-type inference
+
+* feature separation
+
+* preprocessing construction
+
+* algorithm construction
+
+* train / holdout splitting
+
+* model fitting
+
+* prediction
+
+* evaluation
+
+* model comparison
+
+* feature importance / coefficients
+
+* pipeline-code generation
+
+* Joblib artifact generation
+
+architecturally:
+
+```text
+agent.py
+   ↓
+decides WHAT ML action is needed
+   ↓
+ml_engine.py
+   ↓
+executes preprocessing / training / evaluation
+   ↓
+returns structured observation
+```
+---
+
+### **`app.py`**
+
+responsibilities include:
+
+* session state
+
+* Hugging Face sample loading
+
+* local dataset upload
+
+* dataset preview
+
+* target controls
+
+* problem-type controls
+
+* algorithm controls
+
+* training callbacks
+
+* comparison callbacks
+
+* generated-code display
+
+* downloadable model artifact
+
+* agent execution
+
+* tool-trace display
+
+* runtime diagnostics
+
+---
+
+### **`config.py`**
+
+agent and application runtime configuration.
+
+controls values such as:
+
+```text
+HF_MODEL_ID
+
+HF_PROVIDER
+
+HF_TOKEN
+
+MAX_UPLOAD_MB
+
+MAX_PROFILE_ROWS
+
+MAX_TRAIN_ROWS
+
+MAX_AGENT_STEPS
+
+DEFAULT_MAX_TOKENS
+
+RANDOM_STATE
+```
+
+## **Modeling Guardrails**
+
+application separates LLM reasoning from numerical machine learning execution.
+
+Qwen agent can decide which operation should be performed, but:
+
+```text
+training
+
+prediction
+
+evaluation
+
+metric calculation
+
+model comparison
+```
+
+are handled by scikit-learn execution tools.
+
+this architecture helps prevent fabricated model-performance claims.
+
+additional controls include:
+
+* bounded agent steps
+
+* configurable maximum model tokens
+
+* fixed random state by default
+
+* controlled algorithm list
+
+* maximum training-row limit
+
+* deterministic / structured preprocessing behavior
+
+* fallback execution path
+
+* tool trace
+
+* structured model observations
+
+## **Model Performance Grounding**
+
+the system is designed so the LLM does not invent model metrics.
+
+```text
+Dataset
+   ↓
+scikit-learn model training
+   ↓
+Prediction
+   ↓
+Metric calculation
+   ↓
+Structured tool observation
+   ↓
+Qwen3-Coder
+   ↓
+Final interpretation
+```
+
+performance values should only be presented as real model results when the associated training / evaluation tool successfully executes.
+
+if the tool does not run successfully, the final response should not claim that a model was trained or evaluated.
+
+
+## **Model Artifact**
+
+trained preprocessing + estimator pipelines can be serialized through Joblib.
+
+```text
+Numeric preprocessing
+        +
+Categorical preprocessing
+        +
+Estimator
+        ↓
+scikit-learn Pipeline
+        ↓
+fit
+        ↓
+Joblib serialization
+        ↓
+.joblib artifact
+```
+
+this allows the fitted pipeline to be reused later without manually rebuilding preprocessing and estimator logic.
+
+
+## **Agent Pattern Workflow:**
+
+```text
+Single Agent
+    +
+Function Calling
+    +
+Machine Learning Tools
+    +
+Bounded Tool Loop
+    +
+Tool Observations
+    +
+Final LLM Synthesis
+```
+
+full execution:
+
+```text
+USER
+ ↓
+Gradio / app.py
+ ↓
+MachineLearningAgent / agent.py
+ ↓
+Qwen3-Coder
+ ↓
+tool_choice="auto"
+ ↓
+ML Tool
+ ↓
+ml_engine.py
+ ↓
+Observation
+ ↓
+Qwen3-Coder
+ ↓
+repeat up to MAX_AGENT_STEPS
+ ↓
+Final ML Assessment
+ ↓
+Recommended modeling setup
+ ↓
+Evaluation findings
+ ↓
+Model comparison
+ ↓
+Pipeline code
+ ↓
+Tool Trace
+```
+
+
+# **Core Runtime Components**
+
+## [**scikit-learn**](https://scikit-learn.org/stable/)
+
+### **What it is:**
+
+scikit-learn ml framework used to build preprocessing pipelines, estimators, training workflows, predictions, and evaluation metrics.
+
+### **Why it is used in this project:**
+
+the application needs a real ML execution layer so model-performance values come from fitted models rather than LLM estimates.
+
+### **How it is used here:**
+
+```text
+Dataset
+   ↓
+Preprocessing
+   ↓
+Estimator
+   ↓
+scikit-learn Pipeline
+   ↓
+Training
+   ↓
+Holdout prediction
+   ↓
+Holdout evaluation
+   ↓
+Metrics + fitted artifact
+```
+
+scikit-learn is used to:
+
+* build numeric preprocessing
+
+* build categorical preprocessing
+
+* combine transformations through `ColumnTransformer`
+
+* build estimator pipelines
+
+* split datasets into train and holdout sets
+
+* fit models
+
+* generate predictions
+
+* calculate classification metrics
+
+* calculate regression metrics
+
+* compare candidate estimators
+
+* expose supported feature importance / coefficient values
+
+* produce reusable fitted model pipelines
+
+
+## [**pandas**](https://pandas.pydata.org/docs/)
+
+### **Why it is used in this project:**
+
+the application needs a lightweight in-memory tabular representation before datasets can be profiled and passed into scikit-learn.
+
+### **How it is used here:**
+
+* load supported dataset formats
+
+* hold the active dataset in memory
+
+* inspect columns and pandas data types
+
+* determine numerical and categorical features
+
+* analyze null values
+
+* inspect unique values
+
+* separate prediction target from model features
+
+* provide training data to scikit-learn
+
+workflow:
+
+```text
+Uploaded / HF dataset
+        ↓
+pandas DataFrame
+        ↓
+Dataset profiling
+        ↓
+Feature + target identification
+        ↓
+scikit-learn
+```
+
+## **Joblib**
+
+### **What it is:**
+
+Joblib is used to serialize fitted Python machine learning objects
+
+### **Why it is used in this project:**
+
+a trained model is more useful when the complete preprocessing + estimator pipeline can be reused outside the interactive session.
+
+### **How it is used here:**
+
+```text
+Fitted preprocessing
+        +
+Fitted estimator
+        ↓
+scikit-learn Pipeline
+        ↓
+Joblib
+        ↓
+.joblib model artifact
+```
+
+after training, the fitted preprocessing + estimator pipeline can be exported as a `.joblib` artifact for later reuse.
+
+## **PyArrow**
+
+### **What it is:**
+
+PyArrow provides support for Apache Arrow / Parquet-based data interchange.
+
+### **How it is used here:**
+
+PyArrow supports loading Parquet datasets into the application's pandas-based dataset workflow.
+
+```text
+Parquet file
+     ↓
+PyArrow support
+     ↓
+pandas DataFrame
+     ↓
+ML workflow
+```
+
+
+## **OpenPyXL**
+
+### **What it is:**
+
+OpenPyXL provides Python support for reading Excel workbook formats used by the dataset upload workflow.
+
+### **How it is used here:**
+
+```text
+XLSX dataset
+     ↓
+OpenPyXL
+     ↓
+pandas
+     ↓
+Dataset profile
+     ↓
+ML workflow
+```
+
+## **HF Automatic Routing**
+
+### **What it is:**
+
+Hugging Face automatic routing allows `InferenceClient` to route the Qwen model request through an available Hugging Face Inference Provider when a specific provider is not explicitly configured.
+
+### **Why it is used:**
+
+it avoids coupling the application to one inference backend and simplifies deployment of the agent.
+
+### **How it is used here:**
+
+```text
+MachineLearningAgent
+      ↓
+huggingface_hub.InferenceClient
+      ↓
+provider="auto"
+      ↓
+Hugging Face Inference Provider
+      ↓
+Qwen3-Coder
+      ↓
+tool request or final synthesis
+```
+
+model configuration is controlled through:
+
+```text
+HF_MODEL_ID
+
+HF_PROVIDER
+
+HF_TOKEN
+```
+
+within this project:
+
+* `HF_MODEL_ID` identifies the Qwen model
+
+* `HF_PROVIDER` can configure provider behavior
+
+* automatic routing can be used when a specific backend is not forced
+
+* the routed model performs tool selection, reasoning, and final synthesis
+
+* scikit-learn performs the actual numerical ML operations
+
+
+## **Training / Evaluation Architecture**
+
+```text
+Dataset
+    ↓
+pandas
+    ↓
+Feature / target split
+    ↓
+Train / holdout split
+    ↓
+ColumnTransformer
+    ↓
+┌────────────────────────────┐
+│ Numeric preprocessing      │
+│                            │
+│ median imputation          │
+│ optional scaling           │
+└────────────────────────────┘
+              +
+┌────────────────────────────┐
+│ Categorical preprocessing  │
+│                            │
+│ most-frequent imputation   │
+│ one-hot encoding           │
+└────────────────────────────┘
+    ↓
+Estimator
+    ↓
+scikit-learn Pipeline
+    ↓
+   fit
+    ↓
+holdout prediction
+    ↓
+evaluation metrics
+    ↓
+Agent observation
+```
+
+
+## **Classification Workflow**
+
+```text
+Classification Dataset
+        ↓
+ Target Selection
+        ↓
+ Preprocessing
+        ↓
+Candidate classifier
+        ↓
+    Training
+        ↓
+Holdout predictions
+        ↓
+    accuracy
+weighted precision
+ weighted recall
+   weighted F1
+ROC-AUC where supported
+        ↓
+Agent interpretation
+```
+
+supported baseline classifiers include:
+
+* Logistic Regression
+
+* Random Forest Classifier
+
+* SGD Classifier
+
+* Linear SVM Classifier
+
+## **Regression Workflow**
+
+```text
+Regression dataset
+        ↓
+Target selection
+        ↓
+  Preprocessing
+        ↓
+Candidate regressor
+        ↓
+    Training
+        ↓
+Holdout predictions
+        ↓
+       MAE
+      RMSE
+       R²
+        ↓
+Agent interpretation
+```
+
+supported baseline regressors include:
+
+* Ridge Regression
+
+* Random Forest Regressor
+
+* SGD Regressor
+