Metadata-Version: 2.3
Name: dreamlake
Version: 0.4.2
Summary: ML experiment tracking and data storage
Keywords: machine-learning,experiment-tracking,mlops,data-storage
Author: Ge Yang, Tom Tao
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: params-proto>=1.9.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
Requires-Dist: sphinx>=7.2.0 ; extra == 'dev'
Requires-Dist: furo>=2024.0.0 ; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints>=2.0.0 ; extra == 'dev'
Requires-Dist: sphinx-autobuild>=2024.0.0 ; extra == 'dev'
Requires-Dist: sphinx-copybutton>=0.5.0 ; extra == 'dev'
Requires-Dist: sphinx-design>=0.5.0 ; extra == 'dev'
Requires-Dist: sphinx-tabs>=3.4.0 ; extra == 'dev'
Requires-Dist: sphinxcontrib-mermaid>=0.9.0 ; extra == 'dev'
Requires-Dist: sphinxext-opengraph>=0.9.0 ; extra == 'dev'
Requires-Dist: myst-parser>=2.0.0 ; extra == 'dev'
Requires-Dist: linkify-it-py>=2.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.3.0 ; extra == 'dev'
Requires-Dist: mypy>=1.9.0 ; extra == 'dev'
Requires-Python: >=3.9
Provides-Extra: dev
Description-Content-Type: text/markdown

# Dreamlake

A simple and flexible SDK for ML experiment tracking and data storage.

## Features

- **Three Usage Styles**: Decorator, context manager, or direct instantiation
- **Dual Operation Modes**: Remote (API server) or local (filesystem)
- **Auto-creation**: Automatically creates namespace, workspace, and folder hierarchy
- **Upsert Behavior**: Updates existing sessions or creates new ones
- **Simple API**: Minimal configuration, maximum flexibility
- **Time-Based Queries**: MCAP-like API for querying track data by timestamp ranges
- **Multi-Modal Sync**: Timestamp inheritance for synchronizing pose, images, and sensor data

## Installation

<table>
<tr>
<td>Using uv (recommended)</td>
<td>Using pip</td>
</tr>
<tr>
<td>

```shell
uv add dreamlake@0.4.2
```

</td>
<td>

```shell
pip install dreamlake==0.4.2
```

</td>
</tr>
</table>

## Quick Start

### Remote Mode (with API Server)

```python
from dreamlake import Session

with Session(
    name="my-experiment",
    workspace="my-workspace",
    remote="https://cu3thurmv3.us-east-1.awsapprunner.com",
    api_key="your-jwt-token"
) as session:
    print(f"Session ID: {session.id}")
```

### Local Mode (Filesystem)

```python
from dreamlake import Session

with Session(
    name="my-experiment",
    workspace="my-workspace",
    local_path=".dreamlake"
) as session:
    pass  # Your code here
```

See [examples/](examples/) for more complete examples.

## Development Setup

### Installing Dev Dependencies

To contribute to Dreamlake or run tests, install the development dependencies:

<table>
<tr>
<td>Using uv (recommended)</td>
<td>Using pip</td>
</tr>
<tr>
<td>

```shell
uv sync --extra dev
```

</td>
<td>

```shell
pip install -e ".[dev]"
```

</td>
</tr>
</table>

This installs:
- `pytest>=8.0.0` - Testing framework
- `pytest-asyncio>=0.23.0` - Async test support
- `sphinx>=7.2.0` - Documentation builder
- `sphinx-rtd-theme>=2.0.0` - Read the Docs theme
- `sphinx-autobuild>=2024.0.0` - Live preview for documentation
- `myst-parser>=2.0.0` - Markdown support for Sphinx
- `ruff>=0.3.0` - Linter and formatter
- `mypy>=1.9.0` - Type checker

### Running Tests

<table>
<tr>
<td>Using uv</td>
<td>Using pytest directly</td>
</tr>
<tr>
<td>

```shell
uv run pytest
```

</td>
<td>

```shell
pytest
```

</td>
</tr>
</table>

### Building Documentation

Documentation is built using Sphinx with Read the Docs theme.

<table>
<tr>
<td>Build docs</td>
<td>Live preview</td>
<td>Clean build</td>
</tr>
<tr>
<td>

```shell
uv run python -m sphinx -b html docs docs/_build/html
```

</td>
<td>

```shell
uv run sphinx-autobuild docs docs/_build/html
```

</td>
<td>

```shell
rm -rf docs/_build
```

</td>
</tr>
</table>

The live preview command starts a local server and automatically rebuilds when files change.

Alternatively, you can use the Makefile from within the docs directory:

```shell
cd docs
make html          # Build HTML documentation
make clean         # Clean build files
```

For maintainers, to build and publish a new release: `uv build && uv publish`
