cortexa-sdk 0.1.6

User-side Python SDK for downloading datasets and assets from Cortexa. Now supports including or excluding annotations with the 'assets_included' parameter.

Cortexa SDK

The Cortexa SDK is a Python client for downloading datasets from a Cortexa server, supporting both programmatic and CLI usage.

Installation

pip install cortexa-sdk

Configuration

You can configure the SDK in three ways (precedence: function parameters > config file > environment variables):

1. Function parameters (passed directly to download_dataset)
2. Config file (~/.cortexa/config.json)
3. Environment variables

Example config file (auto-generate with cortexa-sdk --init-config):

{
  "api_key": "your-api-key",
  "base_url": "http://your-cortexa-server/api/v1",
  "dataset_dir": "~/datasets"
}

Environment variables:

• CORTEXA_API_KEY – API key
• CORTEXA_BASE_URL – Base URL of the Cortexa server
• CORTEXA_DATASET_DIR – Default dataset download directory
• CORTEXA_CONFIG – Path to a JSON config file (defaults to ~/.cortexa/config.json)

Usage

Python API:

You can use the SDK in two ways:

1. Pass all parameters explicitly (highest precedence):

from cortexa_sdk import download_dataset, ExportType

path = download_dataset(
    dataset_id="DATASET_ID",
    export_type=ExportType.JSON,
    api_key="YOUR_API_KEY",
    base_url="http://your-cortexa-server/api/v1",
    download_dir="~/datasets",
    assets_included=True
)
print("Dataset saved to", path)

2. Use config file or environment variables (lower precedence):

from cortexa_sdk import download_dataset, ExportType

path = download_dataset("DATASET_ID", export_type=ExportType.JSON)
print("Dataset saved to", path)

In this case, the SDK will read values from ~/.cortexa/config.json or environment variables if parameters are not provided.

CLI:

cortexa-sdk --init-config  # Generate default config file if needed
cortexa-sdk -d "DATASET_ID" --export-type JSON
cortexa-sdk -d "DATASET_ID" \
  --export-type JSON \
  --api-key TOKEN \
  --base-url http://localhost:8000/api/v1 \
  --download-dir ./tmp/datasets \
  --assets-included True

Example output:

Created download task for dataset 688a26a52b1a60e8375b98d7
Created dataset download task 688a79d2b3c851acb0606df6 for 688a26a52b1a60e8375b98d7
dataset task 688a79d2b3c851acb0606df6 status: PROCESSING progress: 40%
... (progress updates) ...
dataset task 688a79d2b3c851acb0606df6 status: COMPLETED progress: 100%
Downloading dataset from ...
Saved dataset to tmp/datasets/688a26a52b1a60e8375b98d7.zip

Examples

Using environment variables:

export CORTEXA_API_KEY="TOKEN"
export CORTEXA_BASE_URL="https://api.example.com/api/v1"
python - <<'PY'
from cortexa_sdk import download_dataset
download_dataset("dataset123")
PY

Using a config file:

from cortexa_sdk import download_dataset, ExportType
path = download_dataset("dataset123", export_type=ExportType.COCO)
print(path)

Overriding with parameters:

from cortexa_sdk import download_dataset, ExportType

download_dataset(
    "dataset123",
    export_type=ExportType.COCO,
    api_key="TOKEN",
    base_url="https://api.example.com/api/v1",
    download_dir="/tmp/datasets",
    assets_included=True,
)

Configuration Resolution Order

1. Parameters passed to download_dataset
2. Values from the config file (~/.cortexa/config.json or as set by CORTEXA_CONFIG)
3. Environment variables

Project Structure

The main files and folders for the Cortexa SDK project are organized as follows:

cortexa-sdk-project/
│
├── pyproject.toml                # Project metadata and build configuration
├── README.md                     # This documentation file
├── test-download.py              # Example/test script for dataset download
├── cortexa_sdk/                  # SDK source code package
│   ├── __init__.py               # SDK main logic and API
│   └── cli.py                    # Command-line interface entry point
│
└── ... (other files and folders)

• pyproject.toml: Defines the package, dependencies, and CLI entry point.
• README.md: Documentation for installation, configuration, usage, and development.
• test-download.py: Example script to demonstrate SDK usage for downloading datasets.
• cortexa_sdk/: The main SDK Python package.
  • __init__.py: Implements the SDK API (e.g., download_dataset).
  • cli.py: Implements the CLI (cortexa-sdk command).

You can run the CLI directly after installation:

cortexa-sdk --help

Or use the SDK in your own Python scripts as shown in the usage examples above.

Releasing to PyPI

1. Install build tools:

   pip install --upgrade setuptools build twine
   

2. Build the package:

   python -m build
   

3. Upload to PyPI:

   twine upload dist/*
   

4. Tag and push the release in git:

   git tag v<version>
   git push --tags
   

5. (Optional) Test uploads using TestPyPI with twine.

Rebuild and reinstall locally:

python -m build
pip install dist/cortexa_sdk-*.whl --force-reinstall