Metadata-Version: 2.4
Name: outerproduct
Version: 0.2.3
Summary: Python SDK for the OuterProduct API
Project-URL: Documentation, https://docs.outerproduct.com
Project-URL: Homepage, https://outerproduct.com
Author: OuterProduct, Inc.
License-Expression: MIT
License-File: LICENSE
Keywords: explainability,machine-learning,outerproduct,sdk,xai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx~=0.27
Requires-Dist: numpy~=1.23
Requires-Dist: outerproduct-http-types
Requires-Dist: pandas~=2.0
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pyarrow>=14.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Provides-Extra: parquet
Requires-Dist: pyarrow>=14.0; extra == 'parquet'
Description-Content-Type: text/markdown

# outerproduct-sdk
Python SDK for training and explaining tabular ML models with the OuterProduct API.

## Installation

```bash
pip install outerproduct
```

## Quick Start

```python
import outerproduct as op

# 1. Initialize the SDK
op.init(api_key="op_live_...")

# 2. Upload data
connector = op.FileUploadConnector()
dataset = connector.upload("credit.csv", label_column="default")

# 3. Train a reasoning model
rm = op.reasoning.fit(dataset)

# 4. Predict
predictions = rm.predict(X_new)

# 5. Explain
reasoning = rm.explain(X_new)
print(reasoning.feature_names[:3])
print(reasoning.attributions)
```

You can also set `OUTERPRODUCT_API_KEY` as an environment variable and call `op.init()` with no arguments.

## Usage

### Build a Dataset from Code

```python
import pandas as pd
import outerproduct as op

df = pd.read_csv("credit.csv")
dataset = op.Dataset.from_pandas(df, label_column="default")
```

### Train a Plain Model (No Explanations)

```python
trainer = op.Trainer.configure(dataset, model_types=["tabm", "xgboost"])
model = trainer.run(strategy="random")
predictions = model.predict(X_new)
```

### Distill a Black-Box Model

```python
# Wrap an external prediction endpoint
teacher = op.model.Predictor(
    "https://your-model-server.com/predict",
    headers={"Authorization": "Bearer ..."},
)

# Distill into a reasoning model
rm = op.reasoning.fit(dataset, teacher=teacher)
```

You can also distill an existing OuterProduct-trained model:

```python
trained = op.Trainer.configure(dataset).run()
rm = op.reasoning.fit(dataset, teacher=trained)
```

### Reasoning Model Operations

```python
# Per-sample explanations
reasoning = rm.explain(X)

# Predict + explain in one call
predictions, reasoning = rm.predict_and_explain(X)

# Global feature importance
reasoning = rm.get_global_drivers()

# Counterfactual scenario search
trace = rm.scenario(X, target_class=1, max_steps=10)

# Pattern aggregation across rejected predictions
import outerproduct as op
pt = op.reasoning.pattern_tracker.fit(rm, dataset, target_range=(0.5, None))
pt.distribution(X_new)
```

### Non-Blocking Jobs

`reasoning.fit()` blocks until training completes by default. To return immediately:

```python
rm = op.reasoning.fit(dataset, non_blocking=True)
```

### Configuration

```python
import outerproduct as op

# Reads OUTERPRODUCT_API_KEY from environment
op.init()

# All options
op.init(
    api_key="op_live_...",
    base_url="https://api.outerproduct.com",
    hardware=op.ModalHardware(),
)
```

