Metadata-Version: 2.4
Name: geni-bioinfo
Version: 0.1.0
Summary: Python client for the GENI Workflows API
Project-URL: Homepage, https://geni-bioinfo.com.br
Project-URL: Repository, https://github.com/geni-bioinfo/geni-python
Project-URL: Bug Tracker, https://github.com/geni-bioinfo/geni-python/issues
License: MIT
License-File: LICENSE
Keywords: bioinformatics,cloud,geni,genomics,nextflow,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# geni-bioinfo

[![PyPI version](https://img.shields.io/pypi/v/geni-bioinfo)](https://pypi.org/project/geni-bioinfo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Python client library for the [GENI Workflows API](https://geni-bioinfo.com.br) — a bioinformatics platform for submitting and managing Nextflow workflow executions on cloud infrastructure.

## Installation

```bash
pip install geni-bioinfo
```

## Quick start

### Authentication

**Option 1 — email and password (JWT):**

```python
from geni import GeniClient

client = GeniClient()
client.auth_login("you@example.com", "your-password")
```

**Option 2 — static API token:**

```python
from geni import GeniClient

client = GeniClient()
client.auth_token("your-api-token")
```

The API URL defaults to `https://workflows-api.geni-bioinfo.com.br`. Override it with the `GENI_API_URL` environment variable or the `api_url` constructor argument.

### Core workflow

```python
from geni import GeniClient

client = GeniClient()
client.auth_token("your-api-token")

# 1. Upload a workflow
wf = client.workflow_create(
    name="hello-world",
    version="1.0.0",
    file_path="hello.nf",
)
print(wf.name, wf.version)

# 2. Discover available engines and queues
engines = client.engine_list(status="active")
queues  = client.queue_list(status="active")

# 3. Submit the workflow
submission = client.submission_create(
    workflow_name="hello-world",
    engine_id=engines[0].id,
    queue_id=queues[0].id,
    output="s3://my-bucket/runs/hello-001",
    params_path="params.yml",
)
print(submission.submission_id, submission.status)

# 4. Poll status
sub = client.submission_get(submission.submission_id)
print(sub.status)

# 5. Stream logs
print(client.submission_logs(submission.submission_id, text=True))
```

## API reference

### `GeniClient`

| Method | Description |
|---|---|
| `auth_login(email, password)` | Authenticate with email + password (JWT) |
| `auth_token(token)` | Authenticate with a static API key |
| `user_list()` | List platform users *(admin only)* |
| `environment_list(status)` | List cloud environments *(admin only)* |
| `engine_list(status)` | List Nextflow engines *(admin only)* |
| `queue_list(status)` | List job queues *(admin only)* |
| `storage_list(status)` | List cloud storage resources *(admin only)* |
| `workflow_create(name, version, file_path, ...)` | Upload and register a workflow version |
| `workflow_list()` | List all registered workflow versions |
| `submission_create(workflow_name, engine_id, queue_id, output, params_path, ...)` | Submit a workflow for execution |
| `submission_list(status)` | List submissions |
| `submission_get(id)` | Fetch a single submission by ID |
| `submission_cancel(id)` | Cancel a running submission |
| `task_list(submission_id)` | List tasks for a submission |
| `task_logs(submission_id, task_id, text)` | Fetch task log entries |
| `submission_logs(submission_id, text)` | Fetch submission-level Nextflow logs |

### Exceptions

| Exception | Raised when |
|---|---|
| `GeniConfigError` | `auth_login()` or `auth_token()` was not called before a request |
| `GeniAuthError` | Invalid credentials or insufficient permissions (HTTP 401/403) |
| `GeniNotFoundError` | A resource ID does not exist (HTTP 404) |
| `GeniAPIError` | Any other unexpected HTTP error; exposes `.status_code`, `.method`, `.url`, `.response_body` |

## Security

- **Never hardcode credentials.** Use the `GENI_API_URL` environment variable for the API URL and load tokens from a secrets manager or `.env` file.
- All API calls use HTTPS.
- See [SECURITY.md](SECURITY.md) for the vulnerability reporting policy.

## Tutorial

An interactive Jupyter notebook is available in [`docs/tutorial.ipynb`](docs/tutorial.ipynb).

## License

MIT — see [LICENSE](LICENSE).
