Metadata-Version: 2.4
Name: dataerai-sdk
Version: 0.1.1b1
Summary: Python SDK for the Dataerai transfer daemon
Author: DataErai
License: DATAERAI PROPRIETARY SOFTWARE LICENSE AGREEMENT
        
        Version 1.2
        
        Copyright (c) 2026 Dataerai, Inc. All Rights Reserved.
        
        ================================================================================
        NOTICE: THE SOFTWARE IS PROPRIETARY AND CONFIDENTIAL. NO RIGHTS ARE GRANTED
        EXCEPT AS EXPRESSLY AND NARROWLY SET FORTH BELOW. ALL RIGHTS NOT EXPRESSLY
        GRANTED ARE RESERVED BY DATAERAI, INC. THIS AGREEMENT APPLIES EQUALLY TO USE
        BY HUMANS AND BY ARTIFICIAL INTELLIGENCE AGENTS (SEE SECTION 4). IF YOU DO NOT
        AGREE TO EVERY TERM OF THIS AGREEMENT, YOU HAVE NO LICENSE AND MUST NOT ACCESS,
        INSTALL, COPY, OR USE THE SOFTWARE IN ANY MANNER.
        ================================================================================
        
        This Dataerai Proprietary Software License Agreement (this "Agreement") is a
        binding legal agreement between Dataerai, Inc., a corporation organized under
        the laws of the Commonwealth of Pennsylvania ("Licensor"), and the single
        identified individual or legal entity that has been expressly authorized in
        writing by Licensor to receive the Software ("Licensee"). By accessing,
        installing, copying, or using the Software, or by clicking to accept, Licensee
        agrees to be bound by this Agreement.
        
        --------------------------------------------------------------------------------
        1. DEFINITIONS
        --------------------------------------------------------------------------------
        
        1.1 "Software" means the Dataerai software package, in any and all forms,
            including without limitation source code, object code, byte code, binaries,
            scripts, schemas, configuration, models, weights, prompts, embeddings,
            graph taxonomies, registries, metadata, libraries, application programming
            interfaces, command-line tooling, and any associated materials, together
            with all updates, upgrades, patches, modifications, enhancements, and
            Documentation, whether delivered now or in the future.
        
        1.2 "Documentation" means any technical or user materials, in any medium,
            provided or made available by Licensor relating to the Software.
        
        1.3 "Authorized Purpose" means solely the internal, non-production evaluation
            of the Software by Licensee, on systems owned and controlled by Licensee,
            strictly within the scope, seat count, term, and field of use expressly
            stated in a written authorization signed by an officer of Licensor. Absent
            such a written authorization, the Authorized Purpose is null and no use is
            permitted.
        
        1.4 "Confidential Information" means the Software and any non-public information
            disclosed by Licensor, whether or not marked confidential. The Software is
            deemed Confidential Information in its entirety.
        
        --------------------------------------------------------------------------------
        2. GRANT OF LICENSE
        --------------------------------------------------------------------------------
        
        2.1 Subject to Licensee's strict and continuous compliance with every term of
            this Agreement, Licensor grants to Licensee a personal, non-exclusive,
            non-transferable, non-sublicensable, non-assignable, revocable, royalty-
            bearing-or-evaluation-only, and fully revocable license to use the Software
            solely for the Authorized Purpose and solely during the Term.
        
        2.2 The license granted in Section 2.1 is the entirety of the rights granted.
            It conveys no right to copy (except a single archival copy as required for
            backup, retaining all notices), no right to modify, no right to create
            derivative works, no right to distribute, no right to sublicense, no right
            to display or perform publicly, and no right to use in production, in a
            service bureau, or on behalf of any third party.
        
        2.3 No license, immunity, or other right is granted by implication, estoppel,
            exhaustion, or otherwise. No patent, trademark, or other intellectual
            property right is licensed except the limited use right in Section 2.1.
        
        --------------------------------------------------------------------------------
        3. RESTRICTIONS
        --------------------------------------------------------------------------------
        
        Licensee shall not, and shall not permit, enable, or assist any third party or
        AI Agent (as defined in Section 4) to:
        
        3.1 copy, reproduce, republish, upload, post, transmit, or otherwise duplicate
            the Software except for the single archival copy permitted in Section 2.2;
        
        3.2 modify, adapt, translate, port, fork, or create derivative works of the
            Software, in whole or in part;
        
        3.3 sell, resell, rent, lease, lend, distribute, transfer, disclose, host,
            sublicense, time-share, or otherwise make the Software available to any
            third party, whether for value or not;
        
        3.4 reverse engineer, decompile, disassemble, decrypt, extract, or otherwise
            attempt to derive or reconstruct the source code, architecture, algorithms,
            model weights, training data, graph taxonomies, or trade secrets embodied
            in the Software, except, and only to the minimum extent, that this
            prohibition is unenforceable under applicable law and only after written
            notice to Licensor;
        
        3.5 use the Software to develop, train, benchmark, or improve any competing,
            similar, or alternative product, model, or service;
        
        3.6 conduct, publish, or disclose any benchmark, performance, security, or
            comparative test or analysis of the Software without Licensor's prior
            written consent;
        
        3.7 remove, alter, obscure, or fail to reproduce any copyright, proprietary,
            confidentiality, or other notice contained in or on the Software;
        
        3.8 circumvent, disable, or interfere with any license-key, telemetry, usage-
            metering, digital-rights-management, or access-control mechanism;
        
        3.9 use the Software in excess of the authorized seat count, scope, field of
            use, or Term, or for any purpose other than the Authorized Purpose; or
        
        3.10 use the Software in violation of any applicable law, regulation, or third-
             party right, including export control and sanctions laws.
        
        --------------------------------------------------------------------------------
        4. ARTIFICIAL INTELLIGENCE, AGENTS, AND AUTOMATED USE
        --------------------------------------------------------------------------------
        
        4.1 Definition. "AI Agent" means any artificial intelligence or machine-
            learning system, model, or software — including any autonomous or semi-
            autonomous agent, large language model, multi-agent system, robotic process
            automation, bot, crawler, scraper, copilot, or other automated process —
            that accesses, operates, invokes, queries, or acts upon the Software,
            whether or not under direct human supervision, and whether operating on
            Licensee's behalf, on Licensee's systems, or using Licensee's credentials,
            tokens, API keys, or sessions.
        
        4.2 Agents Bound by this Agreement. This Agreement applies in full to any access
            to or use of the Software by, through, or on behalf of an AI Agent. Every
            restriction, obligation, and prohibition that binds Licensee binds equally
            any AI Agent that Licensee deploys, authorizes, instructs, integrates, or
            permits to interact with the Software. An AI Agent is not a separate,
            independent, or exempt user, and acquires no rights of its own under this
            Agreement.
        
        4.3 Full Responsibility for Agent Conduct. Licensee is fully and solely
            responsible for all acts and omissions of any AI Agent acting on Licensee's
            behalf, on Licensee's systems, or via Licensee's credentials, as if those
            acts were Licensee's own. The autonomy of the AI Agent, the absence of human
            supervision, or the absence of specific human intent is not a defense to any
            breach. Licensee shall not use an AI Agent to do, attempt, or enable
            anything that Licensee is itself prohibited from doing under this Agreement.
        
        4.4 No Training, Ingestion, or Derivation. Licensee shall not, and shall not
            permit any AI Agent or third party to, use the Software or any portion of it
            — including its source code, object code, structure, schemas, graph
            taxonomies, registries, metadata, model weights, prompts, embeddings,
            Documentation, or Outputs — as input to, as training, fine-tuning, or
            alignment data for, as a retrieval or context corpus for, or as a basis to
            distill, replicate, or derive, any AI Agent, model, dataset, or competing
            system.
        
        4.5 No Automated Extraction. Licensee shall not use any AI Agent to scrape,
            crawl, harvest, index, reverse engineer, or otherwise extract the Software,
            its structure, its parameters, or its Outputs, including by means of
            automated or adversarial querying intended to reconstruct or approximate the
            Software's behavior, weights, taxonomies, or underlying data.
        
        4.6 Outputs. "Outputs" means any data, content, predictions, classifications,
            embeddings, analyses, graphs, or other results generated by the Software or
            by any AI Agent through use of the Software. Outputs constitute Confidential
            Information, are licensed (not assigned) to Licensee solely for the
            Authorized Purpose, and remain subject to every restriction in this
            Agreement. Licensee obtains no right to use Outputs to train, evaluate, or
            improve any AI Agent, model, or competing system.
        
        4.7 Disclosure of Agentic Use. Upon Licensor's request, Licensee shall disclose
            whether, and the manner in which, any AI Agent has accessed or used the
            Software, and shall cooperate with any audit under Section 8 directed at
            such use.
        
        --------------------------------------------------------------------------------
        5. OWNERSHIP
        --------------------------------------------------------------------------------
        
        5.1 The Software is licensed, not sold. Licensor and its licensors retain all
            right, title, and interest in and to the Software and all intellectual
            property rights therein. Licensee acquires no ownership interest of any
            kind. All feedback, suggestions, and ideas provided by Licensee — whether
            authored by a human or generated by an AI Agent — are hereby assigned to
            Licensor without restriction or compensation.
        
        --------------------------------------------------------------------------------
        6. CONFIDENTIALITY
        --------------------------------------------------------------------------------
        
        6.1 Licensee shall hold the Software and all Confidential Information in strict
            confidence, shall not disclose it to any person or AI Agent other than
            Licensee's employees with a need to know who are bound by written
            obligations at least as protective as this Agreement, and shall use it
            solely for the Authorized Purpose. Licensee shall protect it using no less
            than the degree of care it uses for its own most sensitive information, and
            in no event less than a reasonable degree of care. Licensee shall not input,
            expose, or transmit the Software or Confidential Information to any third-
            party AI Agent or service that would acquire rights in, or use for training,
            the material so disclosed.
        
        --------------------------------------------------------------------------------
        7. TERM AND TERMINATION
        --------------------------------------------------------------------------------
        
        7.1 This Agreement and the license commence on the date Licensee first accesses
            the Software and continue only for the period expressly authorized in
            writing by Licensor (the "Term"). If no period is stated, the Term is
            thirty (30) days.
        
        7.2 Licensor may terminate or suspend this Agreement and the license at any
            time, for any reason or no reason, with or without notice, in its sole
            discretion. This license is revocable at will.
        
        7.3 This Agreement terminates automatically and immediately upon any breach by
            Licensee, without notice and without opportunity to cure.
        
        7.4 Upon any expiration or termination, all rights granted cease immediately,
            and Licensee shall, within five (5) days, cease all use, permanently delete
            or destroy all copies of the Software (including the archival copy, all
            Outputs, and all derivatives and extracts), purge the Software and Outputs
            from any AI Agent context, cache, or store, and certify such destruction in
            writing to Licensor upon request. Sections 1, 3, 4, 5, 6, 7.4, and 8
            through 13 survive termination.
        
        --------------------------------------------------------------------------------
        8. AUDIT
        --------------------------------------------------------------------------------
        
        8.1 Licensor may, upon reasonable notice, audit Licensee's use of the Software,
            including by inspecting records and systems and reviewing AI Agent logs and
            access histories, to verify compliance. Licensee shall cooperate. Any
            unauthorized use revealed by an audit constitutes a material breach.
        
        --------------------------------------------------------------------------------
        9. DISCLAIMER OF WARRANTIES
        --------------------------------------------------------------------------------
        
        9.1 THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITH ALL FAULTS AND
            WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW,
            LICENSOR DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR
            OTHERWISE, INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR
            A PARTICULAR PURPOSE, TITLE, ACCURACY, AND NON-INFRINGEMENT, AND ANY
            WARRANTY ARISING FROM COURSE OF DEALING OR USAGE OF TRADE. LICENSOR DOES NOT
            WARRANT THAT THE SOFTWARE WILL BE UNINTERRUPTED, ERROR-FREE, OR SECURE, OR
            THAT ANY OUTPUT GENERATED BY THE SOFTWARE OR BY ANY AI AGENT WILL BE
            ACCURATE, COMPLETE, OR FIT FOR ANY PURPOSE.
        
        --------------------------------------------------------------------------------
        10. LIMITATION OF LIABILITY
        --------------------------------------------------------------------------------
        
        10.1 TO THE MAXIMUM EXTENT PERMITTED BY LAW, LICENSOR SHALL NOT BE LIABLE FOR
             ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE
             DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR GOODWILL, ARISING
             OUT OF OR RELATING TO THIS AGREEMENT, THE SOFTWARE, OR ANY ACTION TAKEN BY
             AN AI AGENT, REGARDLESS OF THE THEORY OF LIABILITY AND EVEN IF ADVISED OF
             THE POSSIBILITY OF SUCH DAMAGES.
        
        10.2 LICENSOR'S TOTAL CUMULATIVE LIABILITY ARISING OUT OF OR RELATING TO THIS
             AGREEMENT SHALL NOT EXCEED THE GREATER OF (A) THE FEES ACTUALLY PAID BY
             LICENSEE TO LICENSOR FOR THE SOFTWARE IN THE THREE (3) MONTHS PRECEDING THE
             CLAIM, OR (B) ONE HUNDRED U.S. DOLLARS (US$100).
        
        --------------------------------------------------------------------------------
        11. INDEMNIFICATION
        --------------------------------------------------------------------------------
        
        11.1 Licensee shall defend, indemnify, and hold harmless Licensor and its
             officers, directors, employees, and agents from and against any and all
             claims, damages, liabilities, costs, and expenses (including reasonable
             attorneys' fees) arising out of or relating to Licensee's use of the
             Software, any use of the Software by any AI Agent acting on Licensee's
             behalf or via Licensee's credentials, or any breach of this Agreement.
        
        --------------------------------------------------------------------------------
        12. EXPORT, SANCTIONS, AND COMPLIANCE
        --------------------------------------------------------------------------------
        
        12.1 Licensee shall comply with all applicable export control, sanctions, and
             anti-corruption laws and shall not export, re-export, or transfer the
             Software to any prohibited destination, entity, or person, or use it for
             any prohibited end use.
        
        --------------------------------------------------------------------------------
        13. GENERAL
        --------------------------------------------------------------------------------
        
        13.1 Governing Law; Venue. This Agreement is governed by the laws of the
             Commonwealth of Pennsylvania, excluding its conflict-of-laws rules. The
             parties submit to the exclusive jurisdiction of the state and federal
             courts located in Pennsylvania.
        
        13.2 Equitable Relief. Licensee acknowledges that any breach of Sections 2, 3,
             4, or 6 would cause irreparable harm for which monetary damages are
             inadequate, and that Licensor is entitled to injunctive relief without the
             need to post bond.
        
        13.3 Assignment. Licensee may not assign or transfer this Agreement or any
             rights or obligations, by operation of law or otherwise, without
             Licensor's prior written consent. Any attempted assignment in violation is
             void. Licensor may freely assign.
        
        13.4 No Waiver. No failure or delay by Licensor in exercising any right waives
             it. Any waiver must be in a writing signed by Licensor.
        
        13.5 Severability. If any provision is held unenforceable, it shall be modified
             to the minimum extent necessary, and the remaining provisions remain in
             full force.
        
        13.6 Entire Agreement. Subject to Section 13.8, this Agreement, together
             with any written authorization issued by Licensor, is the entire agreement
             between the parties regarding the Software and supersedes all prior or
             contemporaneous understandings. Any conflicting or additional terms
             proposed by Licensee are rejected.
        
        13.7 U.S. Government Rights. If Licensee is a U.S. Government entity, the
             Software is "commercial computer software" and "commercial computer
             software documentation," and any use, duplication, or disclosure is
             subject to the restrictions of this Agreement to the extent permitted by
             applicable Federal Acquisition Regulation and agency supplements.
        
        13.8 Amendments; Updated Versions.
        
             (a) Licensor may issue an amended or replacement version of this Agreement
             (an "Updated Agreement"). To be effective as to Licensee, an Updated
             Agreement must: (i) conspicuously identify itself as an updated version of
             this Agreement and state its version number and effective date; (ii) be
             provided to Licensee in full by a method reasonably calculated to give
             Licensee notice; and (iii) be affirmatively accepted by Licensee through
             a click-through acceptance, electronic signature, or other written
             acceptance by a person authorized to bind Licensee. Licensor may condition
             any renewal, extension, update, upgrade, or continued access to the
             Software after the end of the then-current Term upon such acceptance.
        
             (b) Upon Licensee's affirmative acceptance, the Updated Agreement
             supersedes and replaces all prior versions of this Agreement between
             Licensor and Licensee with respect to the Software, effective on the later
             of the Updated Agreement's stated effective date or Licensee's acceptance
             date. Unless the Updated Agreement expressly states otherwise, any then-
             effective written authorization issued by Licensor remains in force only to
             the extent it is consistent with the Updated Agreement.
        
             (c) Until an Updated Agreement becomes effective under this Section 13.8,
             the version of this Agreement previously accepted by Licensee remains
             controlling, subject to Licensor's termination and suspension rights under
             Section 7. Licensor shall retain a reasonably accessible record of each
             version of this Agreement and the date on which Licensee accepted it.
        
        ================================================================================
        For licensing inquiries, contact: legal@dataerai.com
        Dataerai, Inc. — Center Valley, Pennsylvania, USA
        ================================================================================
        
Project-URL: Homepage, https://dataerai.com
Project-URL: Documentation, https://docs.dataerai.com
Project-URL: Source, https://github.com/dataerai/dataerai-toolkit
Keywords: dataerai,data-transfer,sdk,research-data
Classifier: License :: Other/Proprietary License
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: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Provides-Extra: ml
Requires-Dist: torch; extra == "ml"
Requires-Dist: numpy>=2; extra == "ml"
Requires-Dist: requests>=2; extra == "ml"
Requires-Dist: zarr>=3; extra == "ml"
Requires-Dist: s3fs; extra == "ml"
Dynamic: license-file

# Dataerai Python SDK

Python client for the Dataerai transfer daemon.  
Supports authenticated uploads, downloads, and metadata operations.
The daemon is started automatically if it is not already running.

## Requirements

- Python ≥ 3.10
- The `dataerai` binary must be installed and on `PATH` (or pass `binary_path` explicitly)
- The user must be logged in via `dataerai auth login` before calling `auth_status()` / `upload()` / `download()`

## Installation

```bash
pip install dataerai-sdk
# or, from source:
pip install -e sdk/python/
```

## Quick start

```python
from dataerai import DataeraiClient

with DataeraiClient(binary_path="/usr/local/bin/dataerai") as client:
    # Check auth
    status = client.auth_status()
    print(f"Logged in as {status.user_email}, token expires {status.expires_at}")

    # Create a project to own your data (also provisions its root collection)
    project = client.create_project("My dataset project", description="Demo")
    print(f"Created project {project.project_id}")

    # Upload a file into it
    result = client.upload(
        "/path/to/data.csv",
        title="My dataset",
        owner_type="project",
        owner_id=project.project_id,
        on_progress=lambda p: print(f"  {p.percent:.0f}%  {p.rate_mbps:.1f} MB/s"),
    )
    print(f"Uploaded  asset_id={result.asset_id}  content_id={result.content_id}")

    # Download it back
    dl = client.download(result.asset_id, dest_dir="/tmp/downloads")
    for f in dl.files:
        print(f"  {f.local_path}  ({f.size:,} bytes)")

    # Read / update metadata
    meta = client.get_metadata(result.asset_id)
    updated = client.set_metadata(result.asset_id, title="My dataset v2", tags=["csv", "demo"])
```

## API reference

### `DataeraiClient(*, socket_path, binary_path, auto_start, start_timeout_s, request_timeout_s)`

| Parameter | Default | Description |
|---|---|---|
| `socket_path` | `$DATAERAI_SOCKET` or `/run/user/<uid>/dataerai-transfer.sock` | Unix socket path |
| `binary_path` | `None` | Path to the `dataerai` binary (required for `auto_start`) |
| `auto_start` | `True` | Spawn the daemon if the socket does not exist |
| `start_timeout_s` | `10.0` | Seconds to wait for the daemon socket to appear |
| `request_timeout_s` | `30.0` | Per-request timeout in seconds |

Use as a context manager (`with DataeraiClient(...) as client:`) for automatic cleanup, or call `client.connect()` / `client.close()` manually.

### Methods

| Method | Returns | Description |
|---|---|---|
| `auth_status()` | `AuthStatus` | Logged-in user and token expiry |
| `create_project(name, *, description="")` | `Project` | Create a project (+ root collection, owner membership, default allocation); requires write scope |
| `upload(local_path, *, title, owner_type, owner_id, ...)` | `UploadResult` | Upload a file; blocks until complete |
| `download(asset_id, dest_dir, ...)` | `DownloadResult` | Download latest asset content; blocks until complete |
| `get_metadata(asset_id)` | `AssetMetadata` | Retrieve asset metadata |
| `set_metadata(asset_id, **fields)` | `AssetMetadata` | Update metadata fields |

### `upload()` keyword arguments

| Argument | Type | Description |
|---|---|---|
| `title` | `str` | Asset title (required) |
| `owner_type` | `str` | `"project"` or `"collection"` (required) |
| `owner_id` | `str` | Owner entity ID (required) |
| `description` | `str \| None` | Free-text description |
| `alias` | `str \| None` | Short identifier |
| `tags` | `list[str] \| None` | Tag list |
| `metadata` | `dict \| None` | Arbitrary key-value metadata |
| `collection_id` | `str \| None` | Collection to add the asset to |
| `chunk_size_mb` | `int \| None` | Override default 64 MiB chunk size |
| `on_progress` | `Callable[[ProgressEvent], None] \| None` | Progress callback |
| `transfer_timeout_s` | `float` | Max seconds to wait for completion (default 3600) |

### Progress events

```python
@dataclass
class ProgressEvent:
    transfer_id: str
    bytes_done: int
    bytes_total: int
    chunk_index: int
    chunk_count: int
    rate_bps: float
    file_index: int
    file_name: str

    @property
    def percent(self) -> float: ...   # 0–100

    @property
    def rate_mbps(self) -> float: ...
```

### Error types

| Exception | When raised |
|---|---|
| `DaemonError(code, message)` | Daemon returned a coded error (see `code` attribute) |
| `DaemonTimeoutError` | Request or transfer exceeded the configured timeout |
| `ConnectionError` | Daemon disconnected unexpectedly |
