# Ritual Irys

This is a library as well as a CLI tool that allows uploading and downloading data to
and from the Irys network. Users can:

1. Upload/Download individual files from & to the Irys network.
2. Upload/Download repositories to & from the Irys network. Each repository is a
   directory containing multiple files (artifacts). These are commonly used in
   `infernet-ml` to store and retrieve models.
<!-- 
For more information, refer to the [Ritual Irys documentation]
(https://ritual-irys.docs.ritual.net/). -->

## Installation

**Via pip:**

```
pip install ritual-irys
```

**Via UV:**

```
uv pip install ritual-irys
```

## Usage

**CLI:**

```
ritual-irys --help
```

***Library:***
### Uploading a Repository

=== "Python"

    ```python
    from ritual_irys.repo_manager import RepoManager

    repo_manager = RepoManager(wallet='<wallet string>')
    upload_result = repo_manager.upload_repo(
        name='my-repo',
        path='/path/to/repo',
        version_mapping_file='/path/to/version_mapping.json'
    )
    print(f"Uploaded repo with manifest URL: {upload_result.manifest_url}")
    ```

=== "CLI"

    ```bash
    ritual-irys upload-repo --repo-name my-repo --repo-dir /path/to/repo
    ```

    <!-- Optional parameters:
    * `--version-file`: Path to a JSON file mapping filenames to versions.
    * `--wallet`: Wallet string, or path to the wallet file (default is `wallet.txt`).
    * `--api-url`: Irys gateway URL (default is `https://irys.net`). -->

### Downloading a Repository

=== "Python"

    ```python
    from ritual_irys.repo_manager import RepoManager

    repo_manager = RepoManager(wallet_path='./wallet.json')
    files = repo_manager.download_repo('owner/my-repo', base_path='/path/to/save')
    print(f"Downloaded files: {files}")
    ```

=== "CLI"

    ```bash
    ritual-irys download-repo --repo-id owner/my-repo --base-path /path/to/save
    ```
<!-- 
    Optional parameters:
    * `--force-download`: Force download even if files already exist. -->

### Uploading a File

=== "Python"

    ```python
    from pathlib import Path
    from ritual_irys.file_manager import FileManager

    file_manager = FileManager(wallet_path='./wallet.json')
    transaction = file_manager.upload(Path('/path/to/file'), tags_dict={'key': 'value'})
    print(f"Uploaded file with transaction ID: {transaction.id}")
    ```

=== "CLI"

    ```bash
    ritual-irys upload-file --file-path /path/to/file --tags '{"key": "value"}'
    ```

### Downloading a File

=== "Python"

    ```python
    from ritual_irys.file_manager import FileManager

    file_manager = FileManager(wallet_path='./wallet.json')
    file_path = file_manager.download('/path/to/save/file', 'transaction-id')
    print(f"Downloaded file to: {file_path}")
    ```

=== "CLI"

    ```bash
    ritual-irys download-file --file-path /path/to/save/file --tx-id transaction-id
    ```

### Generic Blob Upload/Download

You can upload/download generic data blobs to/from Irys using the
`FileManager` class.


```python
from ritual_irys.file_manager import FileManager

file_manager = FileManager(wallet='<wallet string>')
data = "yooooo".encode()
tx = file_manager.upload_data(data)
print("tx: %s", tx.id)

```

### Dictionary Upload/Download

Much like blobs, you can upload/download dictionaries to/from Irys using the
`FileManager` class.

```python
from ritual_irys.file_manager import FileManager

file_manager = FileManager(wallet='<wallet string>')
data = {"key": "value"}
tx = file_manager.upload_dict(data)
print("tx: %s", tx.id)
```




<!-- ## Developing

You might find yourself iterating on both `ritual_irys` & `ritual_pyirys` when
doing development. To make sure that the correct modules are imported, set the
`PYTHONPATH` environment variable like so:

```
export PYTHONPATH="libraries/ritual_irys/src:libraries/ritual_pyirys/src"
``` -->
