Metadata-Version: 2.4
Name: tablemage
Version: 0.1.0a1
Summary: A Python package for low-code analysis of tabular data
Project-URL: Homepage, https://tablemage.readthedocs.io/
Author-email: Andrew Yang <andrew_j_yang@brown.edu>, Joshua Woo <joshua_woo@brown.edu>, Ryan Zhang <rzryanz00@gmail.com>
License: Copyright 2025 Andrew Yang
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: data science,low-code,machine learning,no-code,statistics
Classifier: Programming Language :: Python
Requires-Python: <3.13,>=3.10
Requires-Dist: adjusttext==1.2.0
Requires-Dist: matplotlib==3.9.2
Requires-Dist: numpy==1.26.4
Requires-Dist: optuna-integration==4.0.0
Requires-Dist: optuna==4.0.0
Requires-Dist: pandas==2.2.2
Requires-Dist: scikit-learn==1.5.2
Requires-Dist: scipy==1.14.1
Requires-Dist: seaborn==0.13.2
Requires-Dist: statsmodels==0.14.3
Requires-Dist: tableone==0.9.1
Requires-Dist: umap-learn==0.5.7
Requires-Dist: xgboost==2.1.1
Provides-Extra: agents
Requires-Dist: fastembed==0.5.0; extra == 'agents'
Requires-Dist: flask-cors==5.0.0; extra == 'agents'
Requires-Dist: flask==3.0.3; extra == 'agents'
Requires-Dist: llama-index-embeddings-fastembed==0.3.0; extra == 'agents'
Requires-Dist: llama-index-llms-groq==0.3.1; extra == 'agents'
Requires-Dist: llama-index-llms-ollama==0.5.0; extra == 'agents'
Requires-Dist: llama-index-llms-openai==0.3.12; extra == 'agents'
Requires-Dist: llama-index==0.12.13; extra == 'agents'
Requires-Dist: python-dotenv==1.0.1; extra == 'agents'
Description-Content-Type: text/markdown

# TableMage &nbsp; 🧙‍♂️📊

![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
![Tests Passing](https://github.com/ajy25/TableMage/actions/workflows/test.yml/badge.svg)
[![Documentation Status](https://readthedocs.org/projects/tablemage/badge/?version=latest)](https://tablemage.readthedocs.io/en/latest/?badge=latest)


TableMage is a Python package for low-code/conversational clinical data science.
TableMage can help you quickly explore tabular datasets, 
easily perform regression analyses,
and effortlessly benchmark machine learning models.


## Installation

We recommend installing TableMage in a new virtual environment.

To install TableMage:
```
git clone https://github.com/ajy25/TableMage.git
cd TableMage
pip install .
```

TableMage supports Python versions 3.10 through 3.12.

> [!NOTE]
> **For MacOS users:** You might run into an error involving [XGBoost](https://xgboost.readthedocs.io/en/stable/#), one of TableMage's dependencies, when using TableMage for the first time.
> To resolve this error, you'll need to install libomp: `brew install libomp`. This requries [Homebrew](https://brew.sh/).

## Quick start (low-code)

You'll likely use TableMage for machine learning model benchmarking. Here's how to do it.

```python
import tablemage as tm
import pandas as pd
import joblib

# load table (assume 'y' is a numeric variable we wish to predict)
df = ...

# initialize an Analyzer object
analyzer = tm.Analyzer(df, test_size=0.2)

# preprocess data, taking care to exclude the target variable 'y' from the operations
c

# train regressors
reg_report = analyzer.regress(  # categorical variables are automatically one-hot encoded
    models=[                    # hyperparameter tuning is preset and automatic
        tm.ml.LinearR('l2', name='ridge'),
        tm.ml.TreesR('random_forest', name='rf'),
        tm.ml.TreesR('xgboost', name='xgb'),
    ],
    target='y',                 # automatically drops examples with missing values in target variable
    predictors=None,            # None signifies all variables except target variable
    feature_selectors=[
        tm.fs.BorutaFSR()       # select subset of predictors prior to training
    ]
)

# view model metrics
print(reg_report.metrics('test'))

# predict on new data
new_df = ...
ridge_model = reg_report.model('ridge').sklearn_pipeline()
y_pred = ridge_model.predict(new_df)

# save as sklearn pipeline
joblib.dump(ridge_model, 'ridge.joblib')
```


## Quick start (conversational)

First, install the required additional dependencies.
```
pip install '.[agents]'
```

Next, add your API key. You only need to do this once; your API key will be written to a local `.env` file.
```python
import tablemage as tm
tm.use_agents()                                             # import the agents module
tm.agents.set_key("openai", "add-your-api-key-here")        # set API key
```

You can open up a chat user interface by running the following code 
and navigating to the URL that appears in the terminal.
Your conversation with the ChatDA, the AI agent, appears on the left, 
while ChatDA's analyses (figures made, tables produced, TableMage commands used) 
appear on the right.

```python
import tablemage as tm
tm.use_agents()
tm.agents.options.set_llm(
    llm_type="openai", 
    model_name="gpt-4o-mini", 
    temperature=0.1
)
# optionally, multimodal ChatDA can interpret figures
tm.agents.options.set_multimodal_llm(
    llm_type="openai",
    model_name="gpt-4o-mini",
    temperature=0.1
)                           # multimodal LLM must be specified for multimodal ChatDA
tm.agents.App(
    multimodal=True         # additional parameters can be set, e.g. memory type, 
).run(debug=False)          # disabling/enabling Python environment, etc.
```

Or, you can chat with the AI agent directly in Python:

```python
import pandas as pd
import tablemage as tm
tm.use_agents()
tm.agents.options.set_llm(
    llm_type="openai", 
    model_name="gpt-4o-mini", 
    temperature=0.1
)

# load table
df = ...

# initialize a ChatDA object
agent = tm.agents.ChatDA(
    df,                     # additional parameters can be set, e.g. memory type, 
    test_size=0.2           # disabling/enabling Python environment, etc.
)

# chat with the agent
print(agent.chat("Compute the summary statistics for the numeric variables."))
```

> [!NOTE]
> You must be connected to the internet to use the `agents` module, even if you are using Ollama to run a locally-hosted LLM.
> TableMage's agent, ChatDA, relies on FastEmbed for retrieval augmented generation, but it may need to download the FastEmbed model from the internet prior to use.
> ChatDA can be run with a local LLM and FastEmbed, ensuring total data privacy.

## Updates

TableMage is under active development.
