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

• Installation and authentication
• Dataset discovery
• Pipelines and artifacts
• File uploads and recovery
• Async clients and MCP integration
• Python API reference
• Development and compatibility

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.