Metadata-Version: 2.1
Name: neptune-experimental
Version: 0.3.3
Summary: Neptune Client Experimental
Home-page: https://neptune.ai/
License: Apache-2.0
Keywords: MLOps,ML Experiment Tracking,ML Model Registry,ML Model Store,ML Metadata Store
Author: neptune.ai
Author-email: contact@neptune.ai
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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 :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: neptune (==1.9.0)
Requires-Dist: tqdm (>=4.66.0)
Requires-Dist: typing_extensions (>=4.0.0,<5.0.0)
Project-URL: Documentation, https://docs.neptune.ai/
Project-URL: Repository, https://github.com/neptune-ai/neptune-client-experimental
Project-URL: Tracker, https://github.com/neptune-ai/neptune-client-experimental/issues
Description-Content-Type: text/markdown

# Neptune Experimental Package

This package consists of experimental features that are not yet ready for production use. The API is subject to change without notice.

# Neptune Fetcher

Neptune Fetcher is a Python package designed for efficient fetching and manipulation of data from Neptune projects and runs. It provides classes and methods for interacting with Neptune data in a read-only manner.

## Installation
```bash
pip install --upgrade neptune neptune-experimental
```

## Usage

### Importing

```python
from neptune_fetcher import ReadOnlyProject
```

### Overview of Classes
- `ReadOnlyProject`: A lightweight, read-only class for handling basic project information.
    - _Constructor Parameters_:
        - `project`: Optional string specifying the project name.
        - `workspace`: Optional string specifying the workspace.
        - `api_token`: Optional string for the API token.
        - `proxies`: Optional dictionary for proxy configuration.
    - _Methods_:
        - `list_runs()`: Yields dictionaries with basic information about each run, including `sys/id` and `sys/name`.
        - `fetch_read_only_runs(with_ids: List[str])`: Returns a generator for `ReadOnlyRun` instances for specified run IDs.
        - `fetch_runs()`: Fetches runs as a DataFrame with default columns.
        - `fetch_runs_df(columns, with_ids, states, owners, tags, trashed)`: Fetches runs as a DataFrame based on specified filters.

- _`ReadOnlyProject.ReadOnlyRun`_: Represents a single Neptune run with read-only access.
    - _Methods_:
        - `__getitem__(item)`: Accesses a field by its path.
        - `__delitem__(key)`: Removes a field from the local cache.
        - `field_names`: Yields the names of all available fields in the run.
        - `prefetch(paths: List[str])`: Loads values of specified fields into local cache.


## Examples
### Fetching Project Metadata

```python
from neptune_fetcher import ReadOnlyProject

project = ReadOnlyProject(workspace="some", project="project")
```

### Listing Runs in a Project

```python
from neptune_fetcher import ReadOnlyProject

project = ReadOnlyProject(workspace="some", project="project")
ids = list(map(lambda row: row["sys/id"], project.list_runs()))
```

### Filtering and Processing Runs

```python
from neptune_fetcher import ReadOnlyProject

project = ReadOnlyProject(workspace="some", project="project")
df = project.fetch_runs_df()

matches = df["sys/name"].str.match("metrics.*")
ids = df[matches]["sys/id"]
```

### Iterating Over Runs

```python
from neptune_fetcher import ReadOnlyProject

project = ReadOnlyProject(workspace="some", project="project")
for run in project.fetch_read_only_runs(with_ids=["PROJ-2"]):
    for field in run.field_names:
        if field.startswith("param"):
            print(run[field].fetch())
        if field.startswith("metric"):
            print(run[field].fetch_values())
```

### Prefetching Values

```python
run.prefetch(["metric1", "metric2"])
print(run["metric1"].fetch(), run["metric2"].fetch())  # This will use the local cache
```

### Purging Local Cache

```python
del run["metric1"]
```


### Example
A full example can be found in `examples/fetch_api.py`.

## License

This project is licensed under the Apache License Version 2.0. For more details, see [Apache License Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

