Skip to main content

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, find datasets by modality, and list their surveys.
  • Upload files and manage datasets, files, 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.
  • Manage knowledge bases and retrieve citation-bearing document passages.

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:

pip install phenoworks-sdk

To include the CLI:

pip install 'phenoworks-sdk[cli]'

These commands do not require a local copy of the PhenoWorks repository. See the installation guide for development installation and uv workspace usage.

Connect to PhenoWorks

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

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

Then list the projects available to your account:

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:

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 files have been uploaded. Inspect a page of files with client.files.list(dataset_id=42, data_product="image", modality="thermal"). See dataset discovery.

Upload files

Every file belongs to a dataset and declares both a data product and modality. Use modality none for files without sensor data:

from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    client.upload_dataset_file(
        dataset_id=42,
        path="orthomosaic.tif",
        data_product="orthomosaic",
        modality="rgb",
    )

client.data_products.list() returns the accepted data products and extensions. See file uploads for processing methods and recovery.

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.

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:", run.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(123) inside a client context. This reconnects to the existing run without submitting work. See pipelines and artifacts for discovery, waiting, error handling, and downloads.

Search a knowledge base

Knowledge bases are owned by the authenticated user. Documents can be reused across collections without creating duplicate indexes:

from phenoworks_sdk import PhenoWorksClient

with PhenoWorksClient() as client:
    collection = client.knowledge_bases.create({"name": "Remote Sensing"})
    client.knowledge_bases.add_document(collection["id"], file_id=42)
    results = client.knowledge_bases.search(
        collection["id"], "How was canopy temperature measured?"
    )
    for hit in results["hits"]:
        citation = hit["citation"]
        print(hit["text"], citation["file_name"], citation["page_numbers"])

The asynchronous client exposes the same operations through await client.knowledge_bases.*. Indexing may continue after a document is added; inspect the returned operation and collection document statuses before assuming it is searchable.

Command-line usage

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

phenoworks auth me
phenoworks datasets filter-by-modality thermal --param project_id=7
phenoworks pipeline-runs run --dataset-id 42 --file pipeline.json --wait
phenoworks artifacts list --param pipeline_run_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 covers uploads, JSON payloads, and migration from the backend CLI.

Documentation

To preview the documentation from the SDK package directory:

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:

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

Version 0.4 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 before running it.

Contributions follow the PhenoWorks contribution guidelines. Report vulnerabilities using the project's security policy.

License

Licensed under Apache 2.0.

Metadata

Release files for phenoworks-sdk 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phenoworks-sdk 0.4.3
File Size Uploaded Provenance Actions
phenoworks_sdk-0.4.3.tar.gz 79.5 kB With provenance Details for phenoworks_sdk-0.4.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phenoworks-sdk 0.4.3
File Interpreter ABI Platform Actions
phenoworks_sdk-0.4.3-py3-none-any.whl Python 3 none any Details for phenoworks_sdk-0.4.3-py3-none-any.whl

Total release size: 139.7 kB

Release files / phenoworks_sdk-0.4.3.tar.gz

Download URL phenoworks_sdk-0.4.3.tar.gz
Size 79.5 kB
Tags Source
SHA-256 checksum
How to use checksums
dcf3e08cc2c042ba61ff73741b5fbbce2abc8b49aa1cc00613b7c969476ed0a7
BLAKE2b-256 checksum
How to use checksums
9821517f4d02b7e815e87b762a1466465a698bbd3675cca697dc2ca326f57721
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / phenoworks_sdk-0.4.3-py3-none-any.whl

Download URL phenoworks_sdk-0.4.3-py3-none-any.whl
Size 60.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8b33840a245e8fe46cd8e15fea6e71c1a60a1a2fd6e4324dad4bc984b77b8bb9
BLAKE2b-256 checksum
How to use checksums
66177467d15e2315a8f06c83a27783f1b4fbec50b4b21c9cb2f199ca917b7af0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for phenoworks-sdk 0.4.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phenoworks_sdk-0.4.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page