Content for /docs

content/docs/api-reference/apply.md

@@ -0,0 +1,68 @@
+# mlem.api.apply()
+
+Apply provided model against provided data
+
+```py
+def apply(
+    model: Union[str, MlemModel],
+    *data: Union[str, MlemDataset, Any],
+    method: str = None,
+    output: str = None,
+    target_repo: str = None,
+    index: bool = None,
+    external: bool = None,
+    batch_size: Optional[int] = None,
+) -> Optional[Any]
+```
+
+### Usage:
+
+```py
+from mlem.api import apply
+
+y_pred = apply("rf", "data", method="predict_proba")
+```
+
+## Description
+
+This API is the underlying mechanism for the
+[mlem apply](/doc/command-reference/apply) command and facilitates running
+inferences on entire datasets. The API applies i.e. calls a model's method (eg:
+`predict`) and returns the output (as a MLEM object) while also saving it if
+required.
+
+## Parameters
+
+- **`model`** (required) - MLEM model (a MlemModel object).
+- **`data`** (required) - Input to the model.
+- `method` (optional) - Which model method to use. If None, use the only method
+  model has. If more than one is available, will fail.
+- `output` (optional) - If value is provided, assume its path and save output
+  there.
+- `target_repo` (optional) - The path to repo to save the results to.
+- `index` (optional) - Whether to index saved output in MLEM root folder.
+- `external` (optional) - Whether to save result outside mlem dir.
+- `batch_size` (optional) - If data is to be loaded and applied in batches.
+
+## Exceptions
+
+- `WrongMethodError` - Thrown if wrong method name for model is provided
+- `NotImplementedError` - Saving several input data objects is not implemented
+  yet
+
+## Examples
+
+```py
+from numpy import ndarray
+from sklearn.datasets import load_iris
+from sklearn.tree import DecisionTreeClassifier
+from mlem.core.objects import MlemDataset, MlemModel
+from mlem.api import apply
+
+train, target = load_iris(return_X_y=True)
+model = DecisionTreeClassifier().fit(train, target)
+d = MlemDataset.from_data(train)
+m = MlemModel.from_obj(model)
+res = apply(m, d, method="predict")
+assert isinstance(res, ndarray)
+```

content/docs/api-reference/apply_remote.md

@@ -0,0 +1,67 @@
+# mlem.api.apply_remote()
+
+Apply deployed model (possibly remote) against provided data.
+
+```py
+def apply_remote(
+    client: Union[str, BaseClient],
+    *data: Union[str, MlemDataset, Any],
+    method: str = None,
+    output: str = None,
+    target_repo: str = None,
+    index: bool = False,
+    **client_kwargs,
+) -> Optional[Any]
+```
+
+### Usage:
+
+```py
+from mlem.api import apply_remote
+
+res = apply_remote(client_obj, data, method="predict")
+```
+
+## Description
+
+This API is the underlying mechanism for the
+[mlem apply-remote](/doc/command-reference/apply-remote) command and facilitates
+running inferences on entire datasets for models which are deployed remotely or
+are being served locally. The API requires an explicit client object, which
+knows how to make requests to the deployed model.
+
+## Parameters
+
+- **`client`** (required) - The client to access methods of deployed model.
+- **`data`** (required) - Input to the model.
+- `method` (optional) - Which model method to use. If None, use the only method
+  model has. If more than one is available, will fail.
+- `output` (optional) - If value is provided, assume it's path and save output
+  there.
+- `target_repo` (optional) - The path to repo to save the results to.
+- `index` (optional) - Whether to index saved output in MLEM root folder.
+- `client_kwargs` (optional) - Keyword arguments for the underlying client
+  implementation being used.
+
+## Exceptions
+
+- `WrongMethodError` - Thrown if wrong method name for model is provided
+- `InvalidArgumentError` - Thrown if arguments are invalid, when method cannot
+  be None
+- `NotImplementedError` - Saving several input data objects is not implemented
+  yet
+
+## Examples
+
+```py
+from numpy import ndarray
+from sklearn.datasets import load_iris
+from mlem.api import apply_remote
+from mlem.runtime.client.base import HTTPClient
+
+train, _ = load_iris(return_X_y=True)
+client = HTTPClient(host="0.0.0.0", port=8080)
+
+res = apply_remote(client, train, method="predict")
+assert isinstance(res, ndarray)
+```

content/docs/api-reference/clone.md

@@ -0,0 +1,64 @@
+# mlem.api.clone()
+
+Clones MLEM object from `path` to `target` and returns Python representation for
+the created object.
+
+```py
+def clone(
+    path: str,
+    target: str,
+    repo: Optional[str] = None,
+    rev: Optional[str] = None,
+    fs: Optional[AbstractFileSystem] = None,
+    target_repo: Optional[str] = None,
+    target_fs: Optional[str] = None,
+    follow_links: bool = True,
+    load_value: bool = False,
+    index: bool = None,
+    external: bool = None,
+) -> MlemObject
+```
+
+### Usage:
+
+```py
+from mlem.api import clone
+
+cloned_obj = clone(path="rf", target="mymodel". repo="https://github.com/iterative/example-mlem-get-started", rev="main")
+```
+
+## Description
+
+This API is the underlying mechanism for the
+[mlem clone](/doc/command-reference/clone) command and facilitates copying of a
+[MLEM Object](/doc/user-guide/basic-concepts#mlem-objects) from source to
+target.
+
+## Parameters
+
+- **`path`** (required) - Path to the object. Could be local path or path inside
+  a Git repo.
+- **`target`** (required) - Path to save the copy of initial object to.
+- `repo` (optional) - URL to repo if object is located there.
+- `rev` (optional) - revision, could be Git commit SHA, branch name or tag.
+- `fs` (optional) - filesystem to load object from
+- `target_repo` (optional) - path to repo to save cloned object to
+- `target_fs` (optional) - target filesystem
+- `follow_links` (optional) - If object we read is a MLEM link, whether to load
+  the actual object link points to. Defaults to True.
+- `load_value` (optional) - Load actual python object incorporated in MlemMeta
+  object. Defaults to False.
+- `index` (optional) - Whether to index output in .mlem directory
+- `external` (optional) - whether to put object inside mlem dir in target repo
+
+## Exceptions
+
+None
+
+## Example: Clone a remote model to a remote repo
+
+```py
+from mlem.api import clone
+
+cloned_obj = clone(path="rf", target="mymodel". repo="https://github.com/iterative/example-mlem-get-started", rev="main", target_repo="s3://mybucket/mymodel", load_value=True)
+```

content/docs/api-reference/deploy.md

@@ -0,0 +1,58 @@
+# mlem.api.deploy()
+
+Deploy a model to target environment. Can use existing deployment declaration or
+create a new one on-the-fly.
+
+```py
+def deploy(
+    deploy_meta_or_path: Union[MlemDeploy, str],
+    model: Union[MlemModel, str] = None,
+    env: Union[MlemEnv, str] = None,
+    repo: Optional[str] = None,
+    fs: Optional[AbstractFileSystem] = None,
+    external: bool = None,
+    index: bool = None,
+    **deploy_kwargs,
+) -> MlemDeploy
+```
+
+### Usage:
+
+```py
+from mlem.api import deploy
+
+#TODO
+```
+
+## Description
+
+This API is the underlying mechanism for the
+[mlem deploy create](/doc/command-reference/deploy/create) command and provides
+a programmatic way to create deployments for a target environment.
+
+## Parameters
+
+- **`deploy_meta_or_path`** (required) - Path to deployment meta (will be
+  created if it does not exist)
+- `model` (optional) - Path to model
+- `env` (optional) - Path to target environment
+- `repo` (optional) - Path to MLEM repo
+- `fs` (optional) - filesystem to load deploy meta from. If not provided, will
+  be inferred from `deploy_meta_or_path`
+- `external` (optional) - Save result not in mlem dir, but directly in repo
+- `index` (optional) - Whether to index output in .mlem directory
+- `deploy_kwargs` (optional) - Configuration for new deployment meta if it does
+  not exist
+
+## Exceptions
+
+- `MlemObjectNotFound` - Thrown if we can't find MLEM object
+- `ValueError` - Please provide model and env args for new deployment
+
+## Examples
+
+```py
+from mlem.api import deploy
+
+#TODO
+```

content/docs/api-reference/import_object.md

@@ -0,0 +1,79 @@
+# mlem.api.import_object()
+
+Try to load an object as MLEM model (or dataset) and return it, optionally
+saving to the specified target location.
+
+```py
+def import_object(
+    path: str,
+    repo: Optional[str] = None,
+    rev: Optional[str] = None,
+    fs: Optional[AbstractFileSystem] = None,
+    target: Optional[str] = None,
+    target_repo: Optional[str] = None,
+    target_fs: Optional[AbstractFileSystem] = None,
+    type_: Optional[str] = None,
+    copy_data: bool = True,
+    external: bool = None,
+    index: bool = None,
+)
+```
+
+### Usage:
+
+```py
+import os
+from mlem.api import import_object
+from mlem.core.objects import MlemDataset
+from mlem.contrib.pandas import DataFrameType
+
+path = os.path.join(os.getcwd(), "data.csv")
+target_path = os.path.join(os.getcwd(), "imported_data")
+meta = import_object(path, target=target_path, type_="pandas[csv]", copy_data=True)
+
+assert isinstance(meta, MlemDataset)
+dt = meta.dataset
+assert isinstance(dt, DataFrameType)
+```
+
+## Description
+
+Existing datasets and model files are imported as
+[MLEM Objects](/doc/user-guide/basic-concepts#mlem-objects). Specifically, they
+are tried to be loaded as `MlemModel` or `MlemDataset`. The function also
+supports saving these objects for future use within the MLEM context. This API
+is the underlying mechanism for the [mlem import](/doc/command-reference/import)
+command.
+
+## Parameters
+
+- **`path`** (required) - Path of file to import.
+- `repo` (optional) - Path to MLEM repo.
+- `rev` (optional) - revision, could be Git commit SHA, branch name or tag.
+- `fs` (optional) - FileSystem for the `path` argument
+- `target` (optional) - Path to save MLEM object into.
+- `target_repo` (optional) - Path to MLEM repo for `target`.
+- `target_fs` (optional) - FileSystem for the `target` argument
+- `type_` (optional) - Specify how to read file. Available types: ['pickle',
+  'pandas']. Defaults to auto-infer.
+- `copy_data` (optional) - Whether to create a copy of file in target location
+  or just link existing file. Defaults to True.
+- `external` (optional) - Save result not in `.mlem`, but directly in repo
+- `index` (optional) - Whether to index output in `.mlem` directory
+
+## Exceptions
+
+None
+
+## Example: Import a saved model as MlemModel
+
+```py
+import os
+from mlem.core.objects import MlemModel
+from mlem.api import import_object
+
+path = os.path.join(os.getcwd(), "mymodel")
+target_path = os.path.join(os.getcwd(), "mlem_model")
+meta = import_object(path, target=target_path, type_="pickle", copy_data=True)
+assert isinstance(meta, MlemModel)
+```

content/docs/api-reference/index.md

@@ -0,0 +1,15 @@
+# Python API
+
+MLEM can be used as a python library, simply [install](/doc/install) with `pip`
+or `conda`. This reference provides the details about the functions in the API
+module `mlem.api`, which can be imported in any regular way, for example:
+
+```py
+import mlem.api
+```
+
+The purpose of this API is to provide programmatic access to operate on models
+and datasets from Python code.
+
+Please choose a function from the navigation sidebar to the left, or click the
+`Next` button below to jump into the first one ↘

content/docs/api-reference/init.md

@@ -0,0 +1,29 @@
+# mlem.api.init()
+
+Creates `.mlem/` directory in `path`
+
+```py
+def init(path: str = ".") -> None
+```
+
+### Usage:
+
+```py
+from mlem.api import init
+
+init(path)
+```
+
+## Description
+
+Initializes a MLEM repository by creating a `.mlem/` directory inside the given
+path. A new and empty `config.yaml` is also created inside it.
+
+## Parameters
+
+- **`path`** (required) - location of the target where a MLEM repository has to
+  be initialized i.e. a `.mlem/` folder has to be created. `.` by default
+
+## Exceptions
+
+None