Metadata-Version: 2.4
Name: mlflow-mongodb
Version: 0.1.0.dev0
Summary: MongoDB model registry store plugin for MLflow
Home-page: https://github.com/mongodb-developer/mlflow-mongodb
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio!=4.15.0,<5,>=3.6.2
Requires-Dist: mlflow>=3.1.0
Requires-Dist: pymongo[srv]<5,>=4.0.0
Provides-Extra: dev
Requires-Dist: check-jsonschema==0.37.4; extra == "dev"
Requires-Dist: pre-commit==4.6.1; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff==0.16.0; extra == "dev"
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MongoDB Backend for MLflow Registered Models

> [WARNING]
> This project is under active development and has not reached a stable release. APIs, storage
> formats, and configuration may change at any time without notice. **It is not intended for
> production use.** See [LICENSE](LICENSE) for the full disclaimer of warranties.

An MLflow plugin that stores registered models, versions, aliases, tags, and related metadata
in MongoDB. MLflow tracking data, such as experiments and runs, remains in a separate backend
store.

## Installation

Python 3.10 or newer, MLflow 3.1 or newer, and a MongoDB deployment are required.

```bash
python -m pip install "mlflow-mongodb>=0.1.0.dev0"
```

## Running MLflow

The tracking store and registered-model store are configured independently. For example, the
following configuration keeps experiments and runs in SQLite and stores registered models
and their versions in MongoDB:

```bash
export TRACKING_STORE_URI="sqlite:///tracking.db"
export REGISTRY_STORE_URI="mongodb://localhost:27017/mlflow_registry"
export MLFLOW_BIND_HOST="127.0.0.1"
export MLFLOW_BIND_PORT="5000"

mlflow server \
  --backend-store-uri "${TRACKING_STORE_URI}" \
  --registry-store-uri "${REGISTRY_STORE_URI}" \
  --host "${MLFLOW_BIND_HOST}" \
  --port "${MLFLOW_BIND_PORT}"
```

Open `http://127.0.0.1:5000` to use the MLflow UI. Clients can connect to the server with:

```bash
export MLFLOW_TRACKING_URI="http://127.0.0.1:5000"
```

The MongoDB URI must include the database name; `mlflow_registry` is the database name in
the example above. Authentication, replica-set, TLS, and other connection options can be
provided using standard MongoDB URI syntax. For example:

```text
mongodb://username:password@mongo.example.com:27017/mlflow_registry?authSource=admin
```

## Documentation

New to MLflow? Start with the [MLflow Tracking Quickstart](https://mlflow.org/docs/latest/ml/getting-started/quickstart/).
The following guides provide additional context for using this plugin:

- [Model Registry Tutorial](https://mlflow.org/docs/latest/ml/model-registry/tutorial) — register and manage model versions.
- [Backend Stores](https://mlflow.org/docs/latest/self-hosting/architecture/backend-store/) — understand where MLflow stores tracking data.
- [Tracking Server Configuration](https://mlflow.org/docs/latest/self-hosting/architecture/tracking-server/) — configure tracking and registry stores independently.
- [MongoDB Connection Strings](https://www.mongodb.com/docs/manual/reference/connection-string/) — configure authentication, TLS, replica sets, and other URI options.

## Versioning

This project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`), same as
[MLflow](https://mlflow.org/) itself. It's currently on major version `0`, meaning the API isn't
yet stable and may change between releases. `main` always carries a `.devN` version (e.g.
`0.1.0.dev0`) to signal it's unreleased and ahead of the latest published version.

## Contributor setup

For development, clone the repository and install it in editable mode:

```bash
git clone https://github.com/mongodb-developer/mlflow-mongodb.git
cd mlflow-mongodb

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

If you downloaded a source archive instead, extract it and run the `venv` and `pip` commands
from the extracted repository root. The final `.` in `pip install -e .` means “install the
project in the current directory,” and `-e` keeps the installation linked to that source
checkout.

Install the development dependencies and Git hooks with:

```bash
python -m pip install -e ".[dev]"
pre-commit install --install-hooks
```

Run all formatting, linting, and repository checks with:

```bash
pre-commit run --all-files
```

## Functional tests

The functional tests use a real MongoDB 8.0 or newer server. Install the project in editable
mode with its development dependencies before running them:

```bash
python -m pip install -e ".[dev]"
```

Set `MONGODB_URI` to a dedicated test database. The database name must contain `test` as a
distinct hyphen- or underscore-separated segment; for example:

```bash
export MONGODB_URI="mongodb://localhost:27017/mlflow_functional_test"
python -m pytest tests/functional
```

Authentication, replica-set, TLS, and other standard MongoDB URI options can be included in
`MONGODB_URI`. Use a replica set when running tests that exercise MongoDB transactions.

The functional suite deletes documents from its application collections after every test so
their indexes can be reused. At the end of the test session, it drops the database selected by
`MONGODB_URI`. Never point `MONGODB_URI` at a database containing data that must be preserved.
