outerproduct 0.2.4__tar.gz → 0.3.0__tar.gz

{outerproduct-0.2.4 → outerproduct-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: outerproduct
-Version: 0.2.4
+Version: 0.3.0
 Summary: Python SDK for the OuterProduct API
 Project-URL: Documentation, https://docs.outerproduct.com
 Project-URL: Homepage, https://outerproduct.com
@@ -21,11 +21,14 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: httpx~=0.27
+Requires-Dist: narwhals>=1.13
 Requires-Dist: numpy~=1.23
 Requires-Dist: outerproduct-http-types
 Requires-Dist: pandas~=2.0
+Requires-Dist: polars<=1.41.0
 Requires-Dist: pydantic<3,>=2.0
 Provides-Extra: dev
+Requires-Dist: anyio; extra == 'dev'
 Requires-Dist: pyarrow>=14.0; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: respx; extra == 'dev'
@@ -34,10 +37,17 @@ 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
+uv add outerproduct
+```
+
+Or with pip:
+
 ```bash
 pip install outerproduct
 ```
@@ -51,11 +61,10 @@ import outerproduct as op
 op.init(api_key="op_live_...")
 
 # 2. Upload data
-connector = op.FileUploadConnector()
-dataset = connector.upload("credit.csv", label_column="default")
+dataset = op.LocalDataset.from_csv("credit.csv").upload()
 
-# 3. Train a reasoning model
-rm = op.reasoning.fit(dataset)
+# 3. Train a reasoning model (returns a job handle; .wait() blocks for the model)
+rm = op.reasoning.fit(dataset).wait()
 
 # 4. Predict
 predictions = rm.predict(X_new)
@@ -110,7 +119,7 @@ schema = DocumentSchema(
 
 ```python
 trainer = op.Trainer.configure(dataset, model_types=["tabm", "xgboost"])
-model = trainer.run(strategy="random")
+model = trainer.run(strategy="random").wait()
 predictions = model.predict(X_new)
 ```
 
@@ -124,14 +133,14 @@ teacher = op.model.Predictor(
 )
 
 # Distill into a reasoning model
-rm = op.reasoning.fit(dataset, teacher=teacher)
+rm = op.reasoning.fit(dataset, teacher=teacher).wait()
 ```
 
 You can also distill an existing OuterProduct-trained model:
 
 ```python
-trained = op.Trainer.configure(dataset).run()
-rm = op.reasoning.fit(dataset, teacher=trained)
+trained = op.Trainer.configure(dataset).run().wait()
+rm = op.reasoning.fit(dataset, teacher=trained).wait()
 ```
 
 ### Reasoning Model Operations
@@ -151,16 +160,23 @@ 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 = op.reasoning.pattern_tracker.fit(rm, dataset, target_range=(0.5, None)).wait()
 pt.distribution(X_new)
 ```
 
-### Non-Blocking Jobs
+### Jobs
 
-`reasoning.fit()` blocks until training completes by default. To return immediately:
+Every async server operation — `Trainer.run()`, `reasoning.fit()`,
+`pattern_tracker.fit()` — submits the work and returns a typed job handle
+(`TrainerJob`, `ReasoningFitJob`, `PatternTrackerJob`). Drive it however you
+need:
 
 ```python
-rm = op.reasoning.fit(dataset, non_blocking=True)
+job = op.reasoning.fit(dataset)
+
+job.status()      # "pending" | "running" | "completed" | "failed"
+job.results()     # typed JobResult once finished (raises JobFailed on failure)
+rm = job.wait()   # block until completion, return the trained ReasoningModel
 ```
 
 ### Configuration
@@ -175,7 +191,5 @@ op.init()
 op.init(
     api_key="op_live_...",
     base_url="https://api.outerproduct.com",
-    hardware=op.ModalHardware(),
 )
 ```
-

{outerproduct-0.2.4 → outerproduct-0.3.0}/README.md

@@ -1,8 +1,15 @@
 # outerproduct-sdk
+
 Python SDK for training and explaining tabular ML models with the OuterProduct API.
 
 ## Installation
 
+```bash
+uv add outerproduct
+```
+
+Or with pip:
+
 ```bash
 pip install outerproduct
 ```
@@ -16,11 +23,10 @@ import outerproduct as op
 op.init(api_key="op_live_...")
 
 # 2. Upload data
-connector = op.FileUploadConnector()
-dataset = connector.upload("credit.csv", label_column="default")
+dataset = op.LocalDataset.from_csv("credit.csv").upload()
 
-# 3. Train a reasoning model
-rm = op.reasoning.fit(dataset)
+# 3. Train a reasoning model (returns a job handle; .wait() blocks for the model)
+rm = op.reasoning.fit(dataset).wait()
 
 # 4. Predict
 predictions = rm.predict(X_new)
@@ -75,7 +81,7 @@ schema = DocumentSchema(
 
 ```python
 trainer = op.Trainer.configure(dataset, model_types=["tabm", "xgboost"])
-model = trainer.run(strategy="random")
+model = trainer.run(strategy="random").wait()
 predictions = model.predict(X_new)
 ```
 
@@ -89,14 +95,14 @@ teacher = op.model.Predictor(
 )
 
 # Distill into a reasoning model
-rm = op.reasoning.fit(dataset, teacher=teacher)
+rm = op.reasoning.fit(dataset, teacher=teacher).wait()
 ```
 
 You can also distill an existing OuterProduct-trained model:
 
 ```python
-trained = op.Trainer.configure(dataset).run()
-rm = op.reasoning.fit(dataset, teacher=trained)
+trained = op.Trainer.configure(dataset).run().wait()
+rm = op.reasoning.fit(dataset, teacher=trained).wait()
 ```
 
 ### Reasoning Model Operations
@@ -116,16 +122,23 @@ 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 = op.reasoning.pattern_tracker.fit(rm, dataset, target_range=(0.5, None)).wait()
 pt.distribution(X_new)
 ```
 
-### Non-Blocking Jobs
+### Jobs
 
-`reasoning.fit()` blocks until training completes by default. To return immediately:
+Every async server operation — `Trainer.run()`, `reasoning.fit()`,
+`pattern_tracker.fit()` — submits the work and returns a typed job handle
+(`TrainerJob`, `ReasoningFitJob`, `PatternTrackerJob`). Drive it however you
+need:
 
 ```python
-rm = op.reasoning.fit(dataset, non_blocking=True)
+job = op.reasoning.fit(dataset)
+
+job.status()      # "pending" | "running" | "completed" | "failed"
+job.results()     # typed JobResult once finished (raises JobFailed on failure)
+rm = job.wait()   # block until completion, return the trained ReasoningModel
 ```
 
 ### Configuration
@@ -140,7 +153,5 @@ op.init()
 op.init(
     api_key="op_live_...",
     base_url="https://api.outerproduct.com",
-    hardware=op.ModalHardware(),
 )
 ```
-

{outerproduct-0.2.4 → outerproduct-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "outerproduct"
-version = "0.2.4"
+version = "0.3.0"
 description = "Python SDK for the OuterProduct API"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,10 +25,12 @@ classifiers = [
 ]
 dependencies = [
   "httpx~=0.27",
+  "narwhals>=1.13",
   "numpy~=1.23",
   "outerproduct-http-types",
   "pandas~=2.0",
-  "pydantic>=2.0,<3"
+  "polars<=1.41.0",
+  "pydantic>=2.0,<3",
 ]
 
 [project.urls]
@@ -36,11 +38,12 @@ Documentation = "https://docs.outerproduct.com"
 Homepage = "https://outerproduct.com"
 
 [project.optional-dependencies]
-dev = ["pytest", "respx", "pyarrow>=14.0"]
+dev = ["anyio", "pytest", "respx", "pyarrow>=14.0"]
 parquet = ["pyarrow>=14.0"]
 
 [dependency-groups]
 dev = [
+  "anyio>=4.0",
   "prek>=0.3.11",
   "pyarrow>=14.0",
   "pytest>=9.0.3",
@@ -66,7 +69,7 @@ include = [
 ]
 
 [tool.hatch.envs.hatch-test]
-extra-dependencies = ["respx", "pyarrow>=14.0"]
+extra-dependencies = ["anyio", "respx", "pyarrow>=14.0"]
 
 [[tool.hatch.envs.hatch-test.matrix]]
 python = ["3.12", "3.13", "3.14"]
@@ -108,8 +111,18 @@ exclude = [".agents/**", ".ruff_cache/**", ".venv/**"]
 [tool.ty.src]
 include = ["src"]
 
-[tool.uv.sources]
-# Track outerproduct-http-types from main so the SDK doesn't lag behind
-# wire-format changes that haven't been published to PyPI yet. Pin by tag
-# = "v0.3.0" once http-types resumes a stable release cadence.
-outerproduct-http-types = { git = "https://github.com/OuterProduct-ai/outerproduct-http-types.git", branch = "main" }
+# By default the SDK resolves outerproduct-http-types from PyPI, via the plain
+# `outerproduct-http-types` entry in [project].dependencies above — pure-PyPI,
+# nothing to configure and no token needed for `uv sync`.
+#
+# Co-developing http-types alongside the SDK? Uncomment [tool.uv.sources] and
+# ONE override below to resolve it from source instead. This is a uv-only
+# setting that is stripped at build time, so it never affects the published
+# wheel. NOTE: with the git form, check-main-pins.py requires `branch = "main"`
+# on merges to main — don't commit a non-main pin (or the local path) to main.
+#
+# [tool.uv.sources]
+# # tip of http-types' default branch (CI git-auth is set up for this private repo):
+# outerproduct-http-types = { git = "https://github.com/OuterProduct-ai/outerproduct-http-types.git", branch = "main" }
+# # ...or a local editable checkout for live co-editing:
+# outerproduct-http-types = { path = "../outerproduct-http-types", editable = true }

{outerproduct-0.2.4 → outerproduct-0.3.0}/src/outerproduct/__init__.py

@@ -4,9 +4,10 @@ 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`.
+  per-column schema (:class:`~outerproduct_http_types.DatasetColumn`).
+- :class:`~outerproduct.connector.Connector` — an *external* source of data
+  (:class:`~outerproduct.connector.S3Connector`, …) that produces a :class:`~outerproduct.dataset.Dataset`;
+  local files and in-memory frames are staged via :meth:`~outerproduct.dataset.LocalDataset.upload` instead.
 - :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`.
@@ -22,7 +23,7 @@ core concepts:
   aggregates the per-row local-rule explanations a
   :class:`~outerproduct.model.ReasoningModel` produces over a target
   prediction band into a small set of executable filter patterns.
-- :class:`~outerproduct.reasoning.Reasoning` / :class:`~outerproduct.reasoning.ReasoningTrace` — the typed results of
+- :class:`~outerproduct.reasoning.Reasoning` / :class:`~outerproduct.reasoning.ScenarioResult` — the typed results of
   reasoning calls.
 
 Quickstart
@@ -32,9 +33,8 @@ Quickstart
     import outerproduct as op
 
     op.init(api_key="...")
-    connector = op.FileUploadConnector()
-    dataset = connector.upload("customers.csv")
-    reasoning_model = op.reasoning.fit(dataset, label_column="churn")
+    dataset = op.LocalDataset.from_csv("customers.csv").upload()
+    reasoning_model = op.reasoning.fit(dataset, task=op.BinclassConfig(label_column="churn"))
     test_dataset = op.Dataset(X_new)
     predictions = reasoning_model.predict(test_dataset)
     reasoning = reasoning_model.explain(test_dataset)
@@ -48,31 +48,55 @@ from dataclasses import dataclass, field
 from importlib.metadata import version as _pkg_version
 from typing import TYPE_CHECKING, Generator
 
-from outerproduct_http_types import ConnectorType
+from outerproduct_http_types import (
+    BinclassConfig,
+    ConnectorType,
+    ForecastingConfig,
+    MulticlassConfig,
+    RegressionConfig,
+    SequenceConfig,
+    TaskConfig,
+    TaskKind,
+)
 
 from outerproduct import agentic
 from outerproduct.connector import (
     Connector,
     DatabricksConnector,
-    FileUploadConnector,
     S3Connector,
     SnowflakeConnector,
 )
-from outerproduct.dataset import Column, Dataset
-from outerproduct.job import Job, TrainerJob
-from outerproduct.model import DiffModel, Model, ReasoningModel, predict
+from outerproduct.dataset import (
+    Dataset,
+    DatasetColumn,
+    Datatype,
+    LocalDataset,
+)
+from outerproduct.expr import Expr, col
+from outerproduct.job import Job, JobFailed, JobNotReady, ReasoningFitJob, TrainerJob
+from outerproduct.job_result import JobResult
+from outerproduct.model import (
+    DiffModel,
+    Model,
+    ReasoningModel,
+    SequenceReasoningModel,
+)
 from outerproduct import reasoning
-from outerproduct.reasoning import Reasoning, ReasoningTrace
+from outerproduct.reasoning import (
+    Change,
+    Counterfactual,
+    QueryResult,
+    Reasoning,
+    ScenarioResult,
+)
 from outerproduct.reasoning import pattern_tracker  # noqa: F401 — makes op.reasoning.pattern_tracker accessible
 from outerproduct.trainer import (
-    Hardware,
     Metric,
-    ModalHardware,
     Trainer,
 )
 
 if TYPE_CHECKING:
-    from outerproduct.client import OuterProductClient
+    from outerproduct.client import AsyncOuterProductClient, OuterProductClient
 
 try:
     __version__ = _pkg_version("outerproduct")
@@ -86,7 +110,6 @@ class _GlobalState:
 
     api_key: str | None = None
     base_url: str | None = None
-    hardware: Hardware | None = None
     extra: dict[str, object] = field(default_factory=dict)
 
 
@@ -111,6 +134,14 @@ _request_client: ContextVar["OuterProductClient | None"] = ContextVar(
     "outerproduct_request_client", default=None
 )
 
+# The async mirror. Sync (`use_client`) and async (`use_aclient`) injection
+# use *separate* contextvars so the two client colors can never be confused:
+# the async transport needs an `AsyncOuterProductClient`, the sync transport an
+# `OuterProductClient`, and a sync helper must never pick up an async client.
+_arequest_client: ContextVar["AsyncOuterProductClient | None"] = ContextVar(
+    "outerproduct_arequest_client", default=None
+)
+
 
 @contextmanager
 def use_client(
@@ -148,24 +179,49 @@ def use_client(
         _request_client.reset(token)
 
 
+@contextmanager
+def use_aclient(
+    client: "AsyncOuterProductClient",
+) -> Generator[None, None, None]:
+    """Async mirror of :func:`use_client` — inject an :class:`AsyncOuterProductClient`.
+
+    Inside this block, the SDK's async HTTP helpers (``_aclient`` /
+    ``_aresolve_client``, and therefore every ``a``-prefixed/async SDK call)
+    use ``client`` instead of building one from ``op._state``. The caller owns
+    ``client``'s lifecycle — the SDK will not ``aclose`` it.
+
+    This is itself an ordinary (synchronous) context manager — it only sets a
+    contextvar and does no I/O — so it can be entered with a plain ``with``
+    even though the client it injects is async::
+
+        async with AsyncOuterProductClient.from_credentials(base, token) as client:
+            with op.use_aclient(client):
+                await op.reasoning.afit(ds, task=...)
+    """
+    token = _arequest_client.set(client)
+    try:
+        yield
+    finally:
+        _arequest_client.reset(token)
+
+
 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.
+    (training, prediction, uploads) read credentials and the API base URL
+    from the state recorded here.
 
     Examples
     --------
     .. code-block:: python
 
         import outerproduct as op
-        op.init(api_key="op_live_...", hardware=op.ModalHardware())
+        op.init(api_key="op_live_...")
 
     Parameters
     ----------
@@ -176,23 +232,28 @@ def init(
     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
 
 
 def get_datasets() -> list[Dataset]:
-    """List datasets owned by the configured API key."""
-    from outerproduct.client import OuterProductClient
+    """List datasets owned by the configured caller.
 
-    with OuterProductClient.from_credentials(_state.base_url, _state.api_key) as client:
-        response = client.datasets_api.list()
-    return [Dataset._from_response(record) for record in response.datasets]
+    Honors :func:`use_client` — multi-tenant consumers (e.g. an MCP
+    server) get per-user authentication via the request-scoped client
+    contextvar. Falls back to the process-global API key otherwise.
+    """
+    from outerproduct.utils import _resolve_client
+
+    client = _resolve_client()
+    response = client.datasets_api.list()
+    out: list[Dataset] = []
+    for entry in response.datasets:
+        dataset = Dataset(entry.connection_config, client, entry.columns)
+        dataset._stamp_id(entry.id)
+        out.append(dataset)
+    return out
 
 
 def get_dataset(dataset_id: str) -> Dataset:
@@ -201,45 +262,98 @@ def get_dataset(dataset_id: str) -> Dataset:
     The returned Dataset has its ``_id`` and ``connection_config`` already
     stamped, so subsequent fit/predict calls short-circuit the server-side
     create.
+
+    Honors :func:`use_client` — multi-tenant consumers (e.g. an MCP
+    server) get per-user authentication via the request-scoped client
+    contextvar. Falls back to the process-global API key otherwise.
+    """
+    from outerproduct.utils import _resolve_client
+
+    client = _resolve_client()
+    entry = client.datasets_api.get(dataset_id)
+    dataset = Dataset(entry.connection_config, client, entry.columns)
+    dataset._stamp_id(entry.id)
+    return dataset
+
+
+def get_models() -> list["Model"]:
+    """List models owned by the configured caller.
+
+    Rows tagged ``model_type='reasoning'`` come back as
+    :class:`~outerproduct.model.ReasoningModel`; trainer rows come back
+    as :class:`~outerproduct.model.Model`. Both expose ``id`` /
+    ``dataset_id`` already stamped from the wire response; richer
+    attributes (``schema``, ``feature_names``) lazy-fetch on first use.
     """
-    from outerproduct.client import OuterProductClient
+    from outerproduct.model import Model
+    from outerproduct.utils import _client
+
+    with _client() as client:
+        response = client.models_api.list()
+    return [Model._from_response(record) for record in response.models]
+
+
+def get_model(model_id: str) -> "Model":
+    """Fetch a single model by id; dispatches to Model / ReasoningModel
+    based on the row's ``model_type``."""
+    from outerproduct.model import Model
+    from outerproduct.utils import _client
 
-    with OuterProductClient.from_credentials(_state.base_url, _state.api_key) as client:
-        record = client.datasets_api.get(dataset_id)
-    return Dataset._from_response(record)
+    with _client() as client:
+        record = client.models_api.get(model_id)
+    return Model._from_response(record)
 
 
 __all__ = [
     # Bootstrap
     "init",
     "use_client",
+    "use_aclient",
     "get_dataset",
     "get_datasets",
+    "get_model",
+    "get_models",
     "__version__",
     # Dataset
     "Dataset",
-    "Column",
+    "LocalDataset",
+    "DatasetColumn",
+    "Datatype",
+    "col",
+    "Expr",
     # Jobs
     "Job",
+    "JobFailed",
+    "JobNotReady",
+    "JobResult",
+    "ReasoningFitJob",
     "TrainerJob",
     # Model
     "Model",
     "DiffModel",
     "ReasoningModel",
-    "predict",
+    "SequenceReasoningModel",
     # Reasoning (submodule, accessed as op.reasoning.*)
     "reasoning",
     "Reasoning",
-    "ReasoningTrace",
+    "ScenarioResult",
+    "QueryResult",
+    "Counterfactual",
+    "Change",
     # Trainer
     "Trainer",
-    "Hardware",
-    "ModalHardware",
     "Metric",
+    # Task config
+    "TaskConfig",
+    "TaskKind",
+    "RegressionConfig",
+    "BinclassConfig",
+    "MulticlassConfig",
+    "ForecastingConfig",
+    "SequenceConfig",
     # Connector
     "Connector",
     "ConnectorType",
-    "FileUploadConnector",
     "S3Connector",
     "SnowflakeConnector",
     "DatabricksConnector",