Metadata-Version: 2.5
Name: phenoworks-sdk
Version: 0.1.1
Summary: A Python package for interacting with PhenoWorks projects, datasets, pipelines, and artifacts.
Project-URL: Homepage, https://github.com/OpenSciML/phenoworks
Project-URL: Repository, https://github.com/OpenSciML/phenoworks/tree/main/packages/phenoworks-sdk
Project-URL: Documentation, https://github.com/OpenSciML/phenoworks/tree/main/packages/phenoworks-sdk/mkdocs
Project-URL: Issues, https://github.com/OpenSciML/phenoworks/issues
Author-email: haruiz <henryruiz22@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Provides-Extra: authoring
Requires-Dist: lgopy; extra == 'authoring'
Provides-Extra: cli
Requires-Dist: pydantic<3,>=2.8; extra == 'cli'
Requires-Dist: rich>=13; extra == 'cli'
Requires-Dist: typer>=0.12.3; extra == 'cli'
Provides-Extra: dev
Requires-Dist: pydantic<3,>=2.8; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: rich>=13; extra == 'dev'
Requires-Dist: typer>=0.12.3; extra == 'dev'
Description-Content-Type: text/markdown

# PhenoWorks SDK

PhenoWorks SDK is a Python package for working with PhenoWorks from scripts,
notebooks, and the command line. It connects to your PhenoWorks server using an
API key and gives you access to projects, datasets, pipelines, and analysis
outputs with the permissions of your account.

Use it to:

- Browse projects and studies, and find datasets by modality.
- Upload files and manage datasets, assets, plots, and annotations.
- Submit pipelines, monitor their progress, and retrieve previous runs.
- Download artifacts for downstream analysis and machine-learning workflows.
- Discover analysis blocks and manage account-level installations.

The package provides `PhenoWorksClient`, `AsyncPhenoWorksClient`, and the optional
`phenoworks` CLI. The Python client requires Python 3.11 or later and HTTPX.

## Installation

Install the Python package from PyPI:

```bash
pip install phenoworks-sdk
```

To include the CLI:

```bash
pip install 'phenoworks-sdk[cli]'
```

These commands do not require a local copy of the PhenoWorks repository. See the
[installation guide](mkdocs/getting-started.md) for development installation and
uv workspace usage.

## Connect to PhenoWorks

Create an API key in your account settings and configure your server connection:

```bash
export PHENOWORKS_API_URL="https://your-phenoworks-server"
export PHENOWORKS_API_KEY="YOUR_API_KEY"
```

Then list the projects available to your account:

```python
from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    projects = client.projects.list()
    for project in projects:
        print(project["id"], project["name"])
```

You can also pass `base_url` and `api_key` directly to the client. Keep real keys
out of committed code and shared notebooks.

## Find datasets by modality

Replace the example project ID with one from your account:

```python
from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    datasets = client.datasets.filter_by_modality("thermal", project_id=7)
    for dataset in datasets:
        print(dataset["id"], dataset["name"])
```

This filters datasets by their declared `supported_modalities`. It does not
verify that matching assets have been uploaded.

## Run a pipeline and download results

Save a valid pipeline definition as `pipeline.json`, using analysis blocks
available to your account. Replace `42` with the dataset you want to process.

```python
import json
from pathlib import Path

from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    definition = json.loads(Path("pipeline.json").read_text(encoding="utf-8"))
    run = client.run_pipeline(dataset_id=42, json_pipeline=definition)
    print("Pipeline:", run.pipeline_id, "Operation:", run.operation_id)
    run.wait(timeout=3600)

    for artifact in run.artifacts():
        if artifact["status"] == "ready":
            destination = Path("results") / f"artifact-{artifact['id']}"
            client.artifacts.download(artifact["id"], destination)
```

Inspect each artifact's type, format, and metadata to select the output needed
for your analysis. Downloads require a local filename and refuse to overwrite
existing files unless `overwrite=True` is supplied.

To retrieve a previous run, use `client.pipeline_run(pipeline_id=123)` inside a
client context. This reconnects to the existing run without submitting work.
See [pipelines and artifacts](mkdocs/pipelines.md) for discovery, waiting,
error handling, and downloads.

## Command-line usage

The CLI uses the same server URL and API key environment variables:

```bash
phenoworks auth me
phenoworks datasets filter-by-modality thermal --param project_id=7
phenoworks pipelines run --dataset-id 42 --file pipeline.json --wait
phenoworks artifacts list --param pipeline_id=123
phenoworks artifacts download 789 --output ./results/features.csv
```

Use IDs and filenames from your own account. Run `phenoworks --help` to explore
commands. The [CLI guide](mkdocs/cli.md) covers uploads, JSON payloads, and
migration from the backend CLI.

## Documentation

- [Installation and authentication](mkdocs/getting-started.md)
- [Dataset discovery](mkdocs/datasets.md)
- [Pipelines and artifacts](mkdocs/pipelines.md)
- [File uploads and recovery](mkdocs/uploads.md)
- [Async clients and MCP integration](mkdocs/async.md)
- [Python API reference](mkdocs/reference.md)
- [Development and compatibility](mkdocs/development.md)

To preview the documentation from the SDK package directory:

```bash
uv run --group docs mkdocs serve
```

Markdown sources live in `mkdocs/`; `mkdocs build --strict` generates the site in
`docs/`. Generated HTML is ignored by Git.

## Development

Run tests and build the package from the repository root:

```bash
uv run --package phenoworks-sdk --extra dev pytest packages/phenoworks-sdk/tests
uv build --package phenoworks-sdk
```

Version 0.1 targets the API in this PhenoWorks checkout. Most SDK tests use mock
HTTP responses; the optional live-server test requires explicit configuration.
See the [development guide](mkdocs/development.md) before running it.

Contributions follow the PhenoWorks [contribution guidelines](https://github.com/OpenSciML/phenoworks/blob/main/CONTRIBUTING.md).
Report vulnerabilities using the project's [security policy](https://github.com/OpenSciML/phenoworks/blob/main/SECURITY.md).

## License

Licensed under [Apache 2.0](LICENSE).
