Metadata-Version: 2.4
Name: TrainIQ
Version: 0.3.1
Summary: Universal TrainIQ Library – end-to-end ML/DL pipelines with a single call.
Home-page: https://github.com/jayeshpandey01/TrainIQ
Author: Jayesh Pandey
Author-email: jayeshpandey754@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/jayeshpandey01/TrainIQ/issues
Project-URL: Documentation, https://github.com/jayeshpandey01/TrainIQ#readme
Project-URL: Source Code, https://github.com/jayeshpandey01/TrainIQ
Keywords: trainiq machine-learning deep-learning neural-networks pytorch scikit-learn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.0
Requires-Dist: torch>=1.12
Requires-Dist: torchvision>=0.13
Requires-Dist: matplotlib>=3.5
Requires-Dist: Pillow>=9.0
Requires-Dist: optuna>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24
Requires-Dist: joblib>=1.2
Provides-Extra: text
Requires-Dist: transformers>=4.20; extra == "text"
Provides-Extra: xgboost
Requires-Dist: xgboost>=1.6; extra == "xgboost"
Provides-Extra: lightgbm
Requires-Dist: lightgbm>=3.3; extra == "lightgbm"
Provides-Extra: catboost
Requires-Dist: catboost>=1.1; extra == "catboost"
Provides-Extra: explain
Requires-Dist: shap>=0.42; extra == "explain"
Provides-Extra: deploy
Requires-Dist: fastapi>=0.100; extra == "deploy"
Requires-Dist: uvicorn[standard]; extra == "deploy"
Provides-Extra: onnx
Requires-Dist: onnx>=1.12; extra == "onnx"
Provides-Extra: quantum
Requires-Dist: pennylane>=0.38; extra == "quantum"
Requires-Dist: pennylane-qiskit>=0.38; extra == "quantum"
Requires-Dist: qiskit>=2.0; extra == "quantum"
Requires-Dist: qiskit-machine-learning>=0.8; extra == "quantum"
Requires-Dist: qiskit-aer>=0.14; extra == "quantum"
Provides-Extra: research
Requires-Dist: beautifulsoup4>=4.11; extra == "research"
Requires-Dist: aiohttp>=3.8; extra == "research"
Requires-Dist: sentence-transformers>=2.2; extra == "research"
Requires-Dist: faiss-cpu>=1.7; extra == "research"
Requires-Dist: ddgs>=0.1.0; extra == "research"
Requires-Dist: ollama>=0.1; extra == "research"
Requires-Dist: transformers>=4.20; extra == "research"
Requires-Dist: torch>=1.12; extra == "research"
Requires-Dist: spacy>=3.5; extra == "research"
Provides-Extra: all
Requires-Dist: transformers>=4.20; extra == "all"
Requires-Dist: xgboost>=1.6; extra == "all"
Requires-Dist: lightgbm>=3.3; extra == "all"
Requires-Dist: catboost>=1.1; extra == "all"
Requires-Dist: shap>=0.42; extra == "all"
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: uvicorn[standard]; extra == "all"
Requires-Dist: onnx>=1.12; extra == "all"
Requires-Dist: tensorboard>=2.10; extra == "all"
Requires-Dist: beautifulsoup4>=4.11; extra == "all"
Requires-Dist: aiohttp>=3.8; extra == "all"
Requires-Dist: sentence-transformers>=2.2; extra == "all"
Requires-Dist: faiss-cpu>=1.7; extra == "all"
Requires-Dist: ddgs>=0.1.0; extra == "all"
Requires-Dist: ollama>=0.1; extra == "all"
Requires-Dist: torch>=1.12; extra == "all"
Requires-Dist: spacy>=3.5; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# TrainIQ

<div align="center">

[![PyPI version](https://badge.fury.io/py/TrainIQ.svg)](https://pypi.org/project/TrainIQ/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**End-to-end machine learning pipelines with automated model selection, training, and deployment.**

[Installation](#installation) • [Quick Start](#quick-start) • [LLM Client](#llm-client-cmddllm) • [Documentation](#documentation) • [Examples](#examples)

</div>

---

## Overview

TrainIQ is a comprehensive Python library that automates the full machine learning workflow — from raw data ingestion to trained model deployment. It supports tabular, image, text, and time-series data modalities, and integrates with the `cmd-d` LLM gateway to provide language model inference, document retrieval, and real-time web search capabilities.

**Version 0.3.1** includes:

- Automated ML pipeline (AutoML) with data type and task detection
- Hyperparameter optimization via Optuna
- Integrated LLM client (`cmddllm`) with synchronous and asynchronous interfaces
- Vectorless RAG document API for retrieval-augmented generation
- Web search integration for grounded LLM completions
- AutoQML module for hybrid classical-quantum machine learning (optional)
- Model export to ONNX and TorchScript
- FastAPI deployment scaffold generation

---

## Installation

### Standard Installation

```bash
pip install TrainIQ
```

### Installation with Optional Extras

```bash
# Quantum machine learning support (PennyLane, Qiskit)
pip install TrainIQ[quantum]

# Transformer-based text models (BERT, DistilBERT)
pip install TrainIQ[text]

# XGBoost support
pip install TrainIQ[xgboost]

# ONNX model export
pip install TrainIQ[onnx]

# FastAPI deployment scaffold
pip install TrainIQ[deploy]

# AI research engine (web scraping, semantic search)
pip install TrainIQ[research]

# All optional dependencies
pip install TrainIQ[all]
```

**Requirements:** Python 3.9 or later.

---

## Quick Start

### Python API

```python
from trainiq import trainiq, trainiqConfig

# Define configuration
config = trainiqConfig(
    data_path="data.csv",
    target_column="label",
    epochs=50
)

# Train
model = trainiq(config)
results = model.train()

# Predict
predictions = model.predict(new_data)

# Export
model.export(format="onnx")
```

### Command Line Interface

```bash
# Train a model
trainiq train --data data.csv --target label --epochs 50

# With hyperparameter tuning
trainiq train --data data.csv --target label --tune --tune-trials 50

# System information
trainiq info
```

---

## LLM Client: cmddllm

TrainIQ includes a production-ready client for the `cmd-d` LLM gateway, supporting chat completions, vision inference, image generation, document retrieval (Vectorless RAG), and web-grounded search.

### Authentication

Set your API key via environment variable, configuration file, or at runtime:

```bash
export CMDD_API_KEY="your-api-key"
```

```python
from trainiq import cmddllm

client = cmddllm(api_key="your-api-key")
```

### Chat Completions

```python
from trainiq import cmddllm

client = cmddllm(api_key="your-api-key")

# Standard completion
response = client.chat.completions.create(
    model="cmd-d",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain gradient descent in two sentences."}
    ]
)
print(response.choices[0].message.content)

# Streaming
for chunk in client.chat.completions.create(
    model="cmd-d",
    messages=[{"role": "user", "content": "Tell me about transformers."}],
    stream=True
):
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### Unified Query Interface

```python
# Single-call convenience method
response = client.query("What is backpropagation?", model="cmd-d")
print(response)

# With web search grounding
response = client.query(
    "What are the latest advances in large language models?",
    model="cmd-d",
    web_search=True
)
```

### Vision (Image Understanding)

```python
# From URL
response = client.chat.completions.create(
    model="cmd-d",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
    }]
)

# From local file
import base64
with open("chart.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="cmd-d",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What does this chart show?"},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
        ]
    }]
)
```

### Image Generation

```python
response = client.images.generate(
    prompt="A neural network architecture diagram with labeled layers",
    n=1,
    size="1024x1024"
)
print(response.data[0].url)
```

### Document Retrieval (Vectorless RAG)

Upload documents and query them using BM25-based retrieval without requiring vector embeddings or a separate vector database.

```python
# Upload a document
with open("research_paper.pdf", "rb") as f:
    upload_result = client.documents.upload(
        file=f,
        filename="research_paper.pdf",
        description="ML paper on transformer scaling"
    )
print(upload_result.document_id)

# Query documents with retrieval-augmented generation
result = client.documents.query(
    query="What are the key findings on model scaling?",
    document_ids=[upload_result.document_id],
    model="cmd-d",
    top_k=5
)
print(result.answer)
for citation in result.citations:
    print(f"  - {citation.text} (chunk {citation.chunk_index})")

# List all uploaded documents
docs = client.documents.list()
for doc in docs.documents:
    print(f"{doc.document_id}: {doc.filename}")

# Delete a document
client.documents.delete(upload_result.document_id)
```

### Web Search

```python
# Perform a grounded web search
results = client.search("recent breakthroughs in quantum computing 2025")
for item in results.results:
    print(f"{item.title}: {item.url}")
    print(f"  {item.snippet}")
```

### Available Models

```python
models = client.models.list()
for model in models.data:
    print(model.id)
```

### Asynchronous Client

```python
import asyncio
from trainiq import asynccmddllm

async def main():
    async with asynccmddllm(api_key="your-api-key") as client:
        response = await client.chat.completions.create(
            model="cmd-d",
            messages=[{"role": "user", "content": "Explain attention mechanisms."}]
        )
        print(response.choices[0].message.content)

        # Async document query
        result = await client.documents.query(
            query="What is the main contribution?",
            document_ids=["doc-123"]
        )
        print(result.answer)

asyncio.run(main())
```

---

## AutoML Pipeline

### Configuration

```python
from trainiq import trainiqConfig

config = trainiqConfig(
    # Data
    data_path="data.csv",           # Path to dataset (required)
    target_column="label",          # Target column name
    task="classification",          # "classification", "regression", "forecasting"
    data_type="tabular",            # "tabular", "image", "text", "timeseries"

    # Training
    epochs=50,
    batch_size=32,
    learning_rate=1e-3,
    optimizer="adam",               # "adam", "adamw", "sgd"

    # Model selection
    model_name="resnet18",          # Specify a model or leave unset for auto-selection
    pretrained=True,

    # Hyperparameter optimization
    tune=True,
    tune_trials=30,

    # Output
    output_dir="trainiq_output",
    device="cuda",                  # "cpu", "cuda", "mps"
    seed=42
)
```

### Advanced Options

```python
config = trainiqConfig(
    # Regularization and stability
    early_stopping_patience=7,
    gradient_clip=1.0,
    mixed_precision=True,
    scheduler="cosine",

    # Architecture
    layers=[512, 256, 128],
    dropout=0.3,
    activations="relu",

    # Data handling
    val_split=0.2,
    cv_folds=5,
    class_weights="auto",

    # Ensembling
    ensemble=True,
    ensemble_top_n=3
)
```

---

## Quantum Machine Learning (AutoQML)

Requires the quantum extras: `pip install TrainIQ[quantum]`

```python
from trainiq.quantum import QuantumClassifier, BarrenPlateauWatchdog, PQKernel, QuantumNAS

# Hybrid classical-quantum classifier
qc = QuantumClassifier(
    input_dim=8,
    num_classes=3,
    n_qubits=6,
    n_layers=3,
    feature_map="angle",       # "angle", "zz", "hybrid"
    backend="pennylane",       # "pennylane", "qiskit"
    diff_method="parameter-shift",
    init_strategy="identity_block"
)

# Training (standard PyTorch loop)
import torch
import torch.nn as nn

optimizer = torch.optim.Adam(qc.parameters(), lr=0.01)
criterion = nn.CrossEntropyLoss()

for epoch in range(50):
    logits = qc(X_train)
    loss = criterion(logits, y_train)
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()

# Barren plateau monitoring
watchdog = BarrenPlateauWatchdog(variance_threshold=1e-5)
watchdog.check(qc)

# Projected Quantum Kernel (PQK) for quantum SVM
pqk = PQKernel(n_qubits=6, n_layers=2, projection="random_pauli")
K_train = pqk.fit_transform(X_train)
K_test = pqk.transform(X_test)

# Quantum architecture search
nas = QuantumNAS(
    input_dim=8,
    n_trials=30,
    search_space={"n_qubits": [4, 6, 8], "n_layers": [1, 2, 3]}
)
best_config = nas.search(X_train, y_train)
print(best_config)
```

---

## Documentation

### Data Type Detection

TrainIQ automatically identifies the data modality from the input path and file structure:

| Data Type | Accepted Formats |
|-----------|-----------------|
| Tabular | CSV, Excel, Parquet, JSON |
| Image | Folder with class subdirectories |
| Text | CSV with text columns |
| Time-Series | Sequential data with datetime index |

### Model Zoo

**Tabular**

| Model | Type | Notes |
|-------|------|-------|
| `tabular_net` | MLP Neural Network | Configurable depth and width |
| `sklearn_rf` | Random Forest | Fast, interpretable |
| `sklearn_xgb` | XGBoost | Requires `TrainIQ[xgboost]` |

**Image**

| Model | Parameters | Notes |
|-------|-----------|-------|
| `resnet18` | 11M | Fast, general purpose |
| `resnet50` | 25M | Higher accuracy |
| `efficientnet_b0` | 5M | Efficient on constrained hardware |

**Text**

| Model | Parameters | Notes |
|-------|-----------|-------|
| `text_cnn` | Less than 1M | Lightweight, fast |
| `distilbert` | 66M | High accuracy, requires `TrainIQ[text]` |

**Time-Series**

| Model | Notes |
|-------|-------|
| `lstm` | Effective for short-to-medium sequences |
| `transformer_ts` | Long-range dependency modeling |

---

## Examples

### Tabular Classification

```python
from trainiq import trainiq, trainiqConfig

config = trainiqConfig(
    data_path="iris.csv",
    target_column="species",
    epochs=50
)

model = trainiq(config)
results = model.train()
print(f"Accuracy: {results['best_val_acc']:.4f}")
```

### Tabular Regression

```python
config = trainiqConfig(
    data_path="housing.csv",
    target_column="price",
    task="regression",
    tune=True,
    tune_trials=30
)
model = trainiq(config)
results = model.train()
```

### Image Classification

```python
# Expected folder structure:
# images/
#   cat/
#   dog/
#   bird/

config = trainiqConfig(
    data_path="images/",
    data_type="image",
    model_name="resnet50",
    epochs=100,
    batch_size=64
)
model = trainiq(config)
results = model.train()
model.export(format="onnx")
```

### Text Classification

```python
config = trainiqConfig(
    data_path="reviews.csv",
    target_column="sentiment",
    data_type="text",
    model_name="distilbert",
    epochs=10
)
model = trainiq(config)
results = model.train()
```

### Time-Series Forecasting

```python
config = trainiqConfig(
    data_path="stock_prices.csv",
    data_type="timeseries",
    model_name="lstm",
    extra={"window": 30, "horizon": 7}
)
model = trainiq(config)
results = model.train()
```

---

## Evaluation and Metrics

```python
results = model.train()
metrics = results["eval_metrics"]

# Classification
print(f"Accuracy:  {metrics['accuracy']:.4f}")
print(f"F1 Score:  {metrics['f1_macro']:.4f}")
print(f"Precision: {metrics['precision_macro']:.4f}")
print(f"Recall:    {metrics['recall_macro']:.4f}")

# Regression
print(f"RMSE: {metrics['rmse']:.4f}")
print(f"MAE:  {metrics['mae']:.4f}")
print(f"R2:   {metrics['r2']:.4f}")
```

TrainIQ automatically generates training curves, confusion matrices (classification), and feature importance plots (tabular models).

---

## Deployment

### Export Model

```python
# ONNX
model.export(format="onnx")

# TorchScript
model.export(format="torchscript")

# Both formats
model.export(format="both")
```

### Generate FastAPI Application

```python
api_path = model.deploy(output_dir="my_api")
```

```bash
cd my_api
pip install -r requirements.txt
uvicorn app:app --reload
```

Generated endpoints:

```
GET  /health     -- Health check
POST /predict    -- Run inference
GET  /docs       -- Interactive API documentation (Swagger UI)
```

---

## CLI Reference

```bash
# Training
trainiq train --data data.csv --target label
trainiq train --data housing.csv --target price --task regression --epochs 100 --lr 0.001
trainiq train --data data.csv --target label --tune --tune-trials 50
trainiq train --data images/ --data-type image --model resnet50 --epochs 200

# Prediction
trainiq predict --model-path trainiq_output/checkpoints/best_model.pt --data test.csv

# Export
trainiq export --model-path model.pt --format onnx

# Deployment scaffold
trainiq deploy --model-path model.onnx --output my_api/

# System info
trainiq info
```

---

## Troubleshooting

### Out of Memory

```python
config = trainiqConfig(batch_size=16, mixed_precision=True)
```

### Slow Training

```python
config = trainiqConfig(device="cuda", num_workers=8, mixed_precision=True)
```

### Poor Model Performance

```python
config = trainiqConfig(tune=True, tune_trials=50)
```

### PyTorch DLL Error (Windows)

This is a Windows-specific PyTorch installation issue.

```bash
pip uninstall torch torchvision
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
```

For NVIDIA GPU:

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
```

### NumPy Compatibility

```bash
pip install --upgrade "numpy>=1.21,<2.0"
pip install --upgrade TrainIQ
```

---

## Contributing

Contributions are welcome. To contribute:

1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Commit your changes: `git commit -m "Add your feature"`
4. Push the branch: `git push origin feature/your-feature`
5. Open a pull request.

Please ensure all tests pass before submitting: `pytest tests/`

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Dependencies

| Library | Purpose |
|---------|---------|
| [PyTorch](https://pytorch.org/) | Deep learning framework |
| [Scikit-learn](https://scikit-learn.org/) | Classical machine learning |
| [Optuna](https://optuna.org/) | Hyperparameter optimization |
| [FastAPI](https://fastapi.tiangolo.com/) | Deployment API scaffold |
| [HTTPX](https://www.python-httpx.org/) | Async HTTP client for LLM gateway |

---

## Support

- **PyPI**: [https://pypi.org/project/TrainIQ/](https://pypi.org/project/TrainIQ/)
- **Issues**: [https://github.com/cmdplusd/TrainIQ/issues](https://github.com/cmdplusd/TrainIQ/issues)
- **Source**: [https://github.com/cmdplusd/TrainIQ](https://github.com/cmdplusd/TrainIQ)
