Metadata-Version: 2.4
Name: pythios
Version: 0.1.4
Summary: The oracle for your data — low-code ML for everyone.
Author-email: Advaith <advaith@pythios.xyz>
License-Expression: MIT
Project-URL: Homepage, https://pythios.xyz
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Requires-Dist: requests>=2.28
Requires-Dist: xgboost>=2.0
Requires-Dist: lightgbm>=4.0
Requires-Dist: optuna>=3.0
Provides-Extra: full
Requires-Dist: torch>=2.0; extra == "full"
Requires-Dist: tensorflow>=2.13; extra == "full"
Requires-Dist: shap>=0.43; extra == "full"
Requires-Dist: umap-learn>=0.5; extra == "full"
Requires-Dist: plotly>=5.0; extra == "full"
Requires-Dist: sentence-transformers>=2.2; extra == "full"
Requires-Dist: faiss-cpu>=1.7; extra == "full"
Requires-Dist: Pillow>=9.0; extra == "full"
Requires-Dist: imbalanced-learn>=0.11; extra == "full"
Dynamic: license-file

# Pythios

Low-code machine learning for tabular data.

Pythios loads data, prepares features, compares models, tunes the best candidate, and evaluates results through one simple workflow.

## Installation

```bash
python -m pip install pythios
```

Pythios supports Python 3.9 and newer. On macOS, XGBoost and LightGBM may require `brew install libomp`.

Optional features:

```bash
python -m pip install "pythios[full]"
```

## Quick start

```python
from pythios import Data, Models, Evaluate

data = Data.from_csv("churn.csv", target="Churn")
model = Models(data)
model.auto(metric="f1")

evaluation = Evaluate(model)
evaluation.metrics()
evaluation.confusion_matrix()
```

`Models.auto()` automatically splits data, encodes categorical features, compares applicable models, selects the best model, tunes it with Optuna, and retrains it. Skip tuning for a faster run:

```python
model.auto(metric="f1", tune=False)
```

## Metrics

Classification metrics are `accuracy`, `f1`, `recall`, `precision`, and `auc_roc`. Regression metrics are `r2`, `rmse`, and `mae`.

```python
model.auto(metric="recall")
model.auto(metric="auc_roc")
```

Defaults are `accuracy` for classification and `r2` for regression. You can also use `model.set_metric("f1").compare()`.

For example, a complete regression workflow using the built-in Diabetes dataset is:

```python
from pythios import Data, Evaluate, Models

data = Data.from_sklearn("diabetes")
model = Models(data).auto(metric="r2", tune=False)
evaluation = Evaluate(model)
evaluation.metrics()
evaluation.residuals()
```

An R² score of `0.455` means the model explains approximately 45.5% of the variation in the test target. This is a moderate baseline: R² of `1.0` is perfect, `0.0` is equivalent to predicting the mean, and a negative value is worse than that baseline. Always consider R² together with MAE, RMSE, and cross-validation:

```python
evaluation.cross_validate()
```

## Loading data

```python
from pythios import Data

data = Data.from_csv("data.csv", target="target")
excel = Data.from_excel("data.xlsx", target="target")
remote = Data.from_url("https://example.com/data.csv", target="target")
iris = Data.from_sklearn("iris")
```

Built-in datasets are `iris`, `wine`, `breast_cancer`, `digits`, `diabetes`, `california_housing`, and `linnerud`.

```python
data.describe()
print(data.missing_report())
data.split(test=0.2, seed=42)
```

String targets such as `Yes`/`No` are automatically detected as binary classification.

## Preprocessing

`Models.auto()` handles ordinary tabular preprocessing automatically. For manual control:

```python
from pythios import Preprocess, Models

data.split()
processed = Preprocess(data).auto().apply()
model = Models(processed).auto(metric="f1")
```

Configuration methods are chainable:

```python
processed = (
    Preprocess(data)
    .impute(method="median")
    .scale(method="standard")
    .encode(method="onehot")
    .apply()
)
```

The target is never transformed, and preprocessing is fitted on training data only.

## Models

Available names include `random_forest`, `logistic_regression`, `linear_regression`, `svm`, `knn`, `decision_tree`, `gradient_boosting`, `naive_bayes`, `ridge`, `lasso`, `xgboost`, and `lightgbm`.

```python
data.split()
model = Models(data)
model.train("random_forest", n_estimators=200)
results = model.compare()
model.tune("xgboost", trials=30)
```

## Evaluation

```python
predictions = model.predict()
probabilities = model.predict_proba()

evaluation = Evaluate(model)
evaluation.metrics()
evaluation.overfit_check()
evaluation.confusion_matrix()
evaluation.roc_curve()
evaluation.feature_importance()
evaluation.cross_validate()
evaluation.report(save="report.txt")
```

## Visualization

```python
from pythios import Visualize

visuals = Visualize(data)
visuals.distribution()
visuals.correlation()
visuals.missing()
visuals.pairplot()
visuals.summary()
```

Most visualization methods accept `save="plot.png"`.

## Unsupervised learning

```python
from pythios import Unsupervised

u = Unsupervised(data)
u.cluster(method="kmeans", k=4)
u.reduce(method="pca", n=2)
u.plot_clusters()
print(u.silhouette_score())
```

Supported clustering methods include KMeans, DBSCAN, agglomerative clustering, and Gaussian mixtures. Reduction methods include PCA, t-SNE, and UMAP.

## Embeddings

```python
from pythios import Embeddings

embeddings = Embeddings().text()
vectors = embeddings.encode(["first document", "second document"])
print(embeddings.similarity(vectors[0], vectors[1]))
```

Faiss index search is available with the `full` extra.

## Tools

```python
from pythios import Tools

Tools.profile(data)
Tools.suggest(data)
Tools.validate(data)
Tools.detect_outliers(data)
Tools.export(data, "cleaned.csv")
```

Other utilities include balancing, memory reporting, reproducible seeds, dataset comparison, and timing. LLM helpers use a locally running Ollama server.

## Saving models

```python
model.save("model.pkl")
restored = Models(data).load("model.pkl")
predictions = restored.predict()
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install pytest
pytest -q
```

## License

Pythios is released under the MIT License.
