Content for /docs

content/docs/api-reference/apply.md

@@ -0,0 +1,18 @@
+# apply
+
+Apply provided model against provided data
+
+    Args:
+        model (ModelMeta): MLEM model.
+        data (Any): Input to the model.
+        method (str, optional): Which model method to use.
+            If None, use the only method model has.
+            If more than one is available, will fail.
+        output (str, optional): If value is provided,
+            assume it's path and save output there.
+        link (bool): Whether to create a link to saved output in MLEM root folder.
+        external (bool): Whether to save result outside mlem dir
+
+    Returns:
+        If `output=None`, returns results for given data.
+            Otherwise returns None.

content/docs/api-reference/clone.md

@@ -0,0 +1,21 @@
+# clone
+
+Clones MLEM object from `path` to `out` and returns Python representation for
+the created object
+
+    Args:
+        path (str): Path to the object. Could be local path or path inside a git repo.
+        target (str): Path to save the copy of initial object to.
+        repo (Optional[str], optional): URL to repo if object is located there.
+        rev (Optional[str], optional): revision, could be git commit SHA, branch name or tag.
+        fs (Optional[AbstractFileSystem], optional): filesystem to load object from
+        target_repo (Optional[str], optional): path to repo to save cloned object to
+        target_fs (Optional[AbstractFileSystem], optional): target filesystem
+        follow_links (bool, optional): If object we read is a MLEM link, whether to load
+            the actual object link points to. Defaults to True.
+        load_value (bool, optional): Load actual python object incorporated in MlemMeta object. Defaults to False.
+        link: whether to create link in target repo
+        external: wheter to put object inside mlem dir in target repo
+
+    Returns:
+        MlemMeta: Copy of initial object saved to `out`

content/docs/api-reference/deploy.md

@@ -0,0 +1 @@
+# deploy

content/docs/api-reference/import_object.md

@@ -0,0 +1,4 @@
+# import_object
+
+Try to load an object as MLEM model (or dataset) and return it, optionally
+saving to the specified target location

content/docs/api-reference/index.md

@@ -0,0 +1,11 @@
+# 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,3 @@
+# init
+
+Creates .mlem directory in `path`

content/docs/api-reference/link.md

@@ -0,0 +1,18 @@
+# link
+
+Creates MlemLink for an `source` object and dumps it if `target` is provided
+
+    Args:
+        source (Union[str, MlemMeta]): The object to create link from.
+        source_repo (str, optional): Path to mlem repo where to load obj from
+        rev (str, optional): Revision if object is stored in git repo.
+        target (str, optional): Where to store the link object.
+        target_repo (str, optional): If provided,
+            treat `target` as link name and dump link in MLEM DIR
+        follow_links (bool): Whether to make link to the underlying object
+            if `source` is itself a link. Defaults to True.
+        external (bool): Whether to save link outside mlem dir
+        absolute (bool): Whether to make link absolute or relative to mlem repo
+
+    Returns:
+        MlemLink: Link object to the `source`.

content/docs/api-reference/load.md

@@ -0,0 +1,13 @@
+# load
+
+Load python object saved by MLEM
+
+    Args:
+        path (str): Path to the object. Could be local path or path inside a git repo.
+        repo (Optional[str], optional): URL to repo if object is located there.
+        rev (Optional[str], optional): revision, could be git commit SHA, branch name or tag.
+        follow_links (bool, optional): If object we read is a MLEM link, whether to load the
+            actual object link points to. Defaults to True.
+
+    Returns:
+        Any: Python object saved by MLEM

content/docs/api-reference/load_meta.md

@@ -0,0 +1,15 @@
+# load_meta
+
+Load MlemMeta object
+
+    Args:
+        path (str): Path to the object. Could be local path or path inside a git repo.
+        repo (Optional[str], optional): URL to repo if object is located there.
+        rev (Optional[str], optional): revision, could be git commit SHA, branch name or tag.
+        follow_links (bool, optional): If object we read is a MLEM link, whether to load the
+            actual object link points to. Defaults to True.
+        load_value (bool, optional): Load actual python object incorporated in MlemMeta object. Defaults to False.
+        fs: filesystem to load from. If not provided, will be inferred from path
+        force_type: type of meta to be loaded. Defaults to MlemMeta (any mlem meta)
+    Returns:
+        MlemMeta: Saved MlemMeta object

content/docs/api-reference/ls.md

@@ -0,0 +1 @@
+# ls

content/docs/api-reference/mlem-object.md

@@ -0,0 +1,24 @@
+# MlemObject API
+
+[comment]: <> (list notable functions of `MlemMeta` subclasses )
+
+- MlemMeta.read
+- MLemMeta.load_value
+- MlemMeta.get_value
+- MlemMeta.dump
+- MlemMeta.make_link
+- MlemMeta.clone
+- MlemMeta.update
+
+- MlemLink.load_link
+- MlemLink.parse_link
+- MlemLink.from_location
+
+- ModelMeta.from_obj
+- DatasetMeta.from_data
+
+- TargetEnvMeta.deploy
+- TargetEnvMeta.destroy
+- TargetEnvMeta.get_status
+
+Same for DeployMeta

content/docs/api-reference/pack.md

@@ -0,0 +1,8 @@
+# pack
+
+Pack model in docker-build-ready folder or directly build a docker image.
+
+    Args:
+        packager (Union[str, Packager]): Packager to use.
+            Out-of-the-box supported string values are "docker_dir" and "docker".
+        model (Union[str, ModelMeta]): The model to pack.

content/docs/api-reference/save.md

@@ -0,0 +1,39 @@
+# save()
+
+Saves given object to a given path
+
+```python
+def save(
+    obj: Any,
+    path: str,
+    repo: Optional[str] = None,
+    dvc: bool = False,
+    tmp_sample_data=None,
+    fs: Union[str, AbstractFileSystem] = None,
+    link: bool = None,
+    external: Optional[bool] = None,
+    description: str = None,
+    params: Dict[str, str] = None,
+    tags: List[str] = None,
+    update: bool = False,
+): ...
+```
+    Args:
+        obj: Object to dump
+        path: If not located on LocalFileSystem, then should be uri
+            or `fs` argument should be provided
+        repo: path to mlem repo (optional)
+        dvc: Store the object's artifacts with dvc
+        tmp_sample_data: If the object is a model or function, you can
+            provide input data sample, so MLEM will include it's schema
+            in the model's metadata
+        fs: FileSystem for the `path` argument
+        link: Whether to create a link in .mlem folder found for `path`
+        external: if obj is saved to repo, whether to put it outside of .mlem dir
+        description: description for object
+        params: arbitrary params for object
+        tags: tags for object
+        update: whether to keep old description/tags/params if new values were not provided
+
+    Returns:
+        None

content/docs/api-reference/serve.md

@@ -0,0 +1,7 @@
+# serve
+
+Serve model via HTTP/HTTPS.
+
+    Args:
+        model (ModelMeta): The model to serve.
+        server (Union[Server, str]): Out-of-the-box supported one is "fastapi".

content/docs/cli-reference/apply.md

@@ -0,0 +1,40 @@
+# apply
+
+Usage: [options] model data
+
+Apply a model to a dataset. Resulting dataset will be saved as MLEM object to
+`output` if it is provided, otherwise will be printed
+
+Arguments:
+
+    MODEL  Path to model object  [required]
+    DATA   Path to dataset object  [required]
+
+Options:
+
+    -r, --repo TEXT           Path to MLEM repo  [default: (none)]
+    --rev TEXT                Repo revision to use  [default: (none)]
+    -o, --output TEXT         Where to store the outputs.
+    -m, --method TEXT         Which model method is to apply  [default: predict]
+    --data-repo, --dr TEXT    Repo with dataset
+    --data-rev TEXT           Revision of dataset
+    -i, --import              Try to import data on-the-fly
+    --import-type, --it TEXT  Specify how to read data file for import
+    --link / --no-link        Whether to create link for output in .mlem
+                            directory
+    -e, --external            Save result not in .mlem, but directly in repo
+    --json                    Output as json
+    --help                    Show this message and exit.
+
+Examples:
+
+    Apply local mlem model to local mlem dataset
+    $ mlem apply mymodel mydatset --method predict --output myprediction
+
+    Apply local mlem model to local data file
+    $ mlem apply mymodel data.csv --method predict --import --import-type pandas[csv] --output myprediction
+
+    Apply a version of remote model to a version of remote dataset
+    $ mlem apply models/logreg --repo https://github.com/iterative/example-mlem --rev main
+                 data/test_x --data-repo https://github.com/iterative/example-mlem --data-rev main
+                 --method predict --output myprediction

content/docs/cli-reference/clone.md

@@ -0,0 +1,36 @@
+# clone
+
+Download MLEM object from `uri` and save it to `target`
+
+## Synopsis
+
+```usage
+usage: mlem clone [options] uri target
+
+arguments:
+URI     URI to object you want to clone  [required]
+TARGET  Path to store the downloaded object.  [required]
+```
+
+## Description
+
+Clones a [MLEM Object](/doc/user-guide/basic-concepts#mlem-objects) from source to target destination. This is useful in cases where you need the model without cloning the whole repository.
+
+## Options
+
+- `-r, --repo TEXT`: Path to MLEM repo  [default: (none)]
+- `--rev TEXT`: Repo revision to use  [default: (none)]
+- `--target-repo, --tr TEXT`: Repo to save target to  [default: (none)]
+- `-e, --external`: Save result not in .mlem, but directly in repo
+- `--link / --no-link`: Whether to create link for output in .mlem directory
+- `--help`: Show this message and exit.
+
+## Examples
+
+```mlem
+Copy remote model to local directory
+$ mlem clone rf --repo https://github.com/iterative/example-mlem-get-started --rev main mymodel
+
+Copy remote model to remote MLEM repo
+$ mlem clone rf --repo https://github.com/iterative/example-mlem-get-started --rev main mymodel --tr s3://mybucket/mymodel
+```

content/docs/cli-reference/create.md

@@ -0,0 +1,44 @@
+# create
+
+Creates new mlem object metafile from conf args and config files
+
+## Synopsis
+
+```usage
+usage: mlem create [options] object_type [subtype] path
+
+arguments:
+OBJECT_TYPE  Type of metafile to create  [required]
+[SUBTYPE]    Subtype of MLEM object  [default: ]
+PATH         Where to save object  [required]
+```
+
+## Description
+
+Metadata files (ending with `.mlem`) can be created for [MLEM objects](/doc/user-guide/basic-concepts#mlem-objects) using the `mlem create` command. This is particularly useful in filling up configuration values for environments and deployments using command line. Each MLEM object, along with its subtype (particular implementation) will accept different configuration arguments, the list of which can be fetched by using `mlem types OBJECT_TYPE SUBTYPE` (See the last example [here](/doc/cli-reference/types#examples))
+
+## Options
+
+- `-c, --conf TEXT`: Values for object fields in format `field.nested.name=value`
+- `-r, --repo TEXT`: Path to MLEM repo  [default: (none)]
+- `-e, --external`: Save result not in .mlem, but directly in repo
+- `--index / --no-index`: Whether to index output in .mlem directory
+- `-h, --help`: Show this message and exit.
+
+## Examples
+
+```mlem
+Fetch which all config can be passed to create a heroku env
+$ mlem types env heroku
+[not required] api_key: str = None
+
+Create heroku env
+$ mlem create env heroku production -c api_key="mlem_heroku_staging"
+💾 Saving env to .mlem/env/staging.mlem
+
+See the contents of saved metafile
+$ cat .mlem/env/staging.mlem
+api_key: mlem_heroku_staging
+object_type: env
+type: heroku
+```

content/docs/cli-reference/import.md

@@ -0,0 +1,42 @@
+# import
+
+Create MLEM model or dataset metadata from file/dir
+
+## Synopsis
+
+```usage
+usage: mlem import [options] uri target
+
+arguments:
+URI     File to import  [required]
+TARGET  Path whare to save MLEM object  [required]
+```
+
+## Description
+
+With MLEM, one can use existing saved datasets or models and use the `mlem import` command to create the necessary `metadata` files (ending with `.mlem`) for them. This is useful to quickly make the existing datasets and models compatible with MLEM, which can then be used in further operations such as `mlem apply`. This workflow is faster than writing a python script to load models and datasets and then subsequently use them.
+
+## Options
+
+- `-r, --repo TEXT`: Path to MLEM repo  [default: (none)]
+- `--rev TEXT`: Repo revision to use  [default: (none)]
+- `--target-repo, --tr TEXT`: Repo to save target to  [default: (none)]
+- `--copy / --no-copy`: Whether to create a copy of file in target location or just link existing file  [default: copy]
+- `--type TEXT`: Specify how to read file Available types: ['pandas', 'pickle']  [default: (auto infer)]
+- `--index / --no-index`: Whether to index output in .mlem directory
+- `-e, --external`: Save result not in .mlem, but directly in repo
+- `-h, --help`: Show this message and exit.
+
+Examples
+
+```mlem
+Create MLEM dataset from local csv
+$ mlem import data/data.csv data/imported_data --type pandas[csv]
+
+Create MLEM model from local pickle file
+$ mlem import data/model.pkl data/imported_model
+
+Create MLEM model from remote pickle file
+$ mlem import .mlem/model/rf --repo https://github.com/iterative/example-mlem-get-started --rev simple data/imported_model --type pickle
+💾 Saving model to .mlem/model/data/imported_model.mlem
+```

content/docs/cli-reference/index.md

@@ -0,0 +1,14 @@
+# Using MLEM Commands
+
+MLEM is a command line tool. Here, we provide the specifications, complete descriptions, and comprehensive usage examples for `mlem` commands.
+
+For a list of commands, type `mlem -h`
+
+## Typical MLEM workflow
+
+- Initialize a MLEM project in a Git Repo with [mlem init](/doc/cli-reference/init).
+- Save Models and Datasets with MLEM.
+- Load and Apply models with [mlem apply](/doc/cli-reference/apply).
+- Package models into python packages or docker images with [mlem pack](/doc/cli-reference/pack).
+- Serve your models by exposing their methods as endpoints using [mlem serve](/doc/cli-reference/serve).
+- Deploy your models to various target platforms in the cloud with [mlem deploy](/doc/cli-reference/deploy).