outerproduct 0.1.0__tar.gz

outerproduct-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.egg-info/
+.venv/
+.vscode/
+.pytest_cache/
+.ruff_cache/
+.claude/
+
+.DS_Store
+.agents/
+skills-lock.json
+dist/
+site/
+
+# Solve OUT-294
+uv.lock

outerproduct-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OuterProduct
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outerproduct-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: outerproduct
+Version: 0.1.0
+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~=0.1
+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.interpret()
+
+# Counterfactual scenario search
+trace = rm.scenario(X, target_class=1, max_steps=10)
+
+# Model-aware segmentation
+trace = rm.segment(X, n_clusters=3)
+```
+
+### 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.ai",
+    hardware=op.ModalHardware(),
+)
+```
+

outerproduct-0.1.0/README.md

@@ -0,0 +1,118 @@
+# 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.interpret()
+
+# Counterfactual scenario search
+trace = rm.scenario(X, target_class=1, max_steps=10)
+
+# Model-aware segmentation
+trace = rm.segment(X, n_clusters=3)
+```
+
+### 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.ai",
+    hardware=op.ModalHardware(),
+)
+```
+

outerproduct-0.1.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "outerproduct"
+version = "0.1.0"
+description = "Python SDK for the OuterProduct API"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "OuterProduct, Inc." },
+]
+keywords = ["explainability", "machine-learning", "outerproduct", "sdk", "xai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx~=0.27",
+  "numpy~=1.23",
+  "outerproduct-http-types~=0.1",
+  "pandas~=2.0",
+  "pydantic>=2.0,<3"
+]
+
+[project.urls]
+Documentation = "https://docs.outerproduct.com"
+Homepage = "https://outerproduct.com"
+
+[project.optional-dependencies]
+dev = ["pytest", "respx", "pyarrow>=14.0"]
+parquet = ["pyarrow>=14.0"]
+
+[dependency-groups]
+dev = [
+  "prek>=0.3.11",
+  "pyarrow>=14.0",
+  "pytest>=9.0.3",
+  "respx>=0.23.1",
+  "ruff>=0.15.12",
+  "tombi>=0.9.26",
+  "ty>=0.0.33",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/outerproduct"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/outerproduct/**",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.hatch.envs.hatch-test]
+extra-dependencies = ["respx", "pyarrow>=14.0"]
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.12", "3.13", "3.14"]
+
+[tool.ruff]
+include = [
+  "benchmarks/**/*.py",
+  "benchmarks/**/*.pyi",
+  "examples/**/*.py",
+  "examples/**/*.pyi",
+  "pyproject.toml",
+  "scripts/**/*.py",
+  "scripts/**/*.pyi",
+  "src/**/*.py",
+  "src/**/*.pyi",
+  "tests/**/*.py",
+  "tests/**/*.pyi",
+]
+extend-exclude = [".agents"]
+force-exclude = true
+
+[tool.ruff.lint]
+# Add specific rules you want to disable here
+ignore = [
+  "N802",  # invalid-function-name (sample_X is ML convention)
+  "N803",  # invalid-argument-name (X, y are ML convention)
+  "N806",  # non-lowercase-variable-in-function (same)
+  "EM101",  # raw-string-in-exception
+  "EM102",  # f-string-in-exception
+  "TRY003",  # raise-vanilla-args
+  "INP001",  # implicit-namespace-package
+  "PT006"  # pytest-parametrize-names-wrong-type
+]
+
+[tool.tombi.files]
+include = ["*.toml", "**/*.toml"]
+exclude = [".agents/**", ".ruff_cache/**", ".venv/**"]
+
+[tool.ty.src]
+include = ["src"]

outerproduct-0.1.0/src/outerproduct/__init__.py

@@ -0,0 +1,153 @@
+"""OuterProduct — a Python SDK for training and explaining tabular ML models.
+
+The package exposes a small, flat surface organised around the following
+core concepts:
+
+- :class:`~outerproduct.dataset.Dataset` — a tabular dataset with an optional label column and
+  per-column schema (:class:`~outerproduct.dataset.Column`).
+- :class:`~outerproduct.connector.Connector` — a source of data (:class:`~outerproduct.connector.FileUploadConnector`,
+  :class:`~outerproduct.connector.S3Connector`, …) that produces a :class:`~outerproduct.dataset.Dataset`.
+- :class:`~outerproduct.trainer.Trainer` — orchestrates general-purpose training and
+  returns a :class:`~outerproduct.model.Model` via :meth:`~outerproduct.trainer.Trainer.configure` and
+  :meth:`~outerproduct.trainer.Trainer.run`.
+- :class:`~outerproduct.model.Model` — a trained predictor with :meth:`~outerproduct.model.Model.predict`.
+- :class:`~outerproduct.model.Predictor` — a duck-typed wrapper around an external
+  prediction endpoint, used to hand black-box models into
+  :func:`~outerproduct.reasoning.fit` for distillation.
+- :class:`~outerproduct.model.ReasoningModel` — a :class:`~outerproduct.model.Model` that also supports
+  :meth:`~outerproduct.model.ReasoningModel.explain`, :meth:`~outerproduct.model.ReasoningModel.interpret`,
+  :meth:`~outerproduct.model.ReasoningModel.scenario`, and :meth:`~outerproduct.model.ReasoningModel.segment`.
+  Produced by :func:`~outerproduct.reasoning.fit`.
+- :class:`~outerproduct.reasoning.Reasoning` / :class:`~outerproduct.reasoning.ReasoningTrace` — the typed results of
+  reasoning calls.
+
+Quickstart
+----------
+.. code-block:: python
+
+    import outerproduct as op
+
+    op.init(api_key="...")
+    connector = op.FileUploadConnector()
+    dataset = connector.upload("customers.csv", label_column="churn")
+    reasoning_model = op.reasoning.fit(dataset)
+    predictions = reasoning_model.predict(X_new)
+    reasoning = reasoning_model.explain(X_new)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib.metadata import version as _pkg_version
+
+from outerproduct_http_types import ConnectorType
+
+from outerproduct import agentic
+from outerproduct.connector import (
+    Connector,
+    DatabricksConnector,
+    FileUploadConnector,
+    S3Connector,
+    SnowflakeConnector,
+)
+from outerproduct.dataset import Column, Dataset
+from outerproduct.job import Job, ReasoningJob, TrainerJob
+from outerproduct.model import Model, ReasoningModel, predict
+from outerproduct.reasoning import Reasoning, ReasoningTrace
+from outerproduct.trainer import (
+    Hardware,
+    Metric,
+    ModalHardware,
+    Trainer,
+)
+
+try:
+    __version__ = _pkg_version("outerproduct")
+except Exception:
+    __version__ = "unknown"
+
+
+@dataclass
+class _GlobalState:
+    """Module-level state populated by :func:`~outerproduct.init`. Internal."""
+
+    api_key: str | None = None
+    base_url: str | None = None
+    hardware: Hardware | None = None
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+_state = _GlobalState()
+
+
+def init(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    hardware: Hardware | None = None,
+) -> None:
+    """Configure the OuterProduct SDK for the current Python process.
+
+    Call once near the top of your program. Subsequent operations
+    (training, prediction, uploads) read credentials, the API base URL,
+    and the default execution backend from the state recorded here.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        import outerproduct as op
+        op.init(api_key="op_live_...", hardware=op.ModalHardware())
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Bearer token used to authenticate against the OuterProduct API.
+        If omitted, the ``OUTERPRODUCT_API_KEY`` environment variable is
+        consulted at use time.
+    base_url : str, optional
+        Override for the API base URL. If omitted, the SDK uses the
+        production endpoint.
+    hardware : Hardware, optional
+        Default execution backend used by :class:`~outerproduct.trainer.Trainer`
+        and :func:`~outerproduct.reasoning.fit`. If omitted, the API
+        server falls back to a managed Modal worker.
+    """
+    _state.api_key = api_key
+    _state.base_url = base_url
+    _state.hardware = hardware
+
+
+__all__ = [
+    # Bootstrap
+    "init",
+    "__version__",
+    # Dataset
+    "Dataset",
+    "Column",
+    # Jobs
+    "Job",
+    "TrainerJob",
+    "ReasoningJob",
+    # Model
+    "Model",
+    "ReasoningModel",
+    "predict",
+    # Reasoning
+    "Reasoning",
+    "ReasoningTrace",
+    # Trainer
+    "Trainer",
+    "Hardware",
+    "ModalHardware",
+    "Metric",
+    # Connector
+    "Connector",
+    "ConnectorType",
+    "FileUploadConnector",
+    "S3Connector",
+    "SnowflakeConnector",
+    "DatabricksConnector",
+    # Agentic feature sourcing (submodule, accessed as op.agentic.*)
+    "agentic",
+]

outerproduct-0.1.0/src/outerproduct/agentic/__init__.py

@@ -0,0 +1,16 @@
+"""Agent-driven feature sourcing.
+
+Everything under :mod:`outerproduct.agentic` is part of an agent-driven flow
+that turns unstructured or semi-structured sources into typed tabular
+features. The boundary is the *flow*, not whether each individual function
+makes an LLM call — deterministic helpers (PDF parsing, batching, schema
+persistence) live here too because they support the same contract.
+
+Submodules
+----------
+- :mod:`outerproduct.agentic.documents` — files (PDF, image, text).
+"""
+
+from outerproduct.agentic import documents
+
+__all__ = ["documents"]