dcp-tools 1.0.0a1__tar.gz

dcp_tools-1.0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ONE Campaign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcp_tools-1.0.0a1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: dcp-tools
+Version: 1.0.0a1
+Summary: Tools to work with the Data Commons Platform.
+Keywords: data-commons,datacommons,dcp,etl,statistics
+Author: ONE Campaign, Luca Picci, Jorge Rivera
+Author-email: Luca Picci <lpicci96@gmail.com>, Jorge Rivera <jorge.rivera@one.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.11.3,<3.0.0
+Requires-Dist: pandas>=2.2.3,<4.0.0
+Requires-Dist: pydantic-settings>=2.9.1,<3.0.0
+Requires-Dist: google-cloud-storage>=3.1.0,<4.0.0
+Requires-Dist: datacommons-admin>=1.1.0
+Requires-Python: >=3.13
+Project-URL: homepage, https://docs.one.org/tools/dcp-tools/
+Project-URL: documentation, https://docs.one.org/tools/dcp-tools/
+Project-URL: repository, https://github.com/ONEcampaign/dcp-tools
+Project-URL: issues, https://github.com/ONEcampaign/dcp-tools/issues
+Description-Content-Type: text/markdown
+
+# dcp-tools
+
+__Manage and load data to Data Commons Platform instances__
+
+[![PyPI](https://img.shields.io/pypi/v/dcp-tools.svg)](https://pypi.org/project/dcp-tools/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dcp-tools.svg)](https://pypi.org/project/dcp-tools/)
+[![Docs](https://img.shields.io/badge/docs-dcp--tools-blue)](https://docs.one.org/tools/dcp-tools/)
+[![Lint/format: Ruff](https://img.shields.io/badge/lint%2Fformat-ruff-46a758.svg)](https://github.com/astral-sh/ruff)
+
+A [Data Commons Platform](https://docs.datacommons.org/custom_dc/custom_data.html) instance takes
+your data as CSVs in a fixed variable-per-row shape, plus a `config.json` that maps each CSV's
+columns onto the Data Commons schema. If you're defining your own statistical variables,
+entities, or properties rather than reusing existing ones, you also need MCF (Meta Content
+Framework) files describing them. `dcp-tools` builds and validates that bundle in Python (or from
+the CLI) and uploads it to Cloud Storage to trigger the platform's ingestion job.
+
+This package was published as `bblocks-datacommons-tools` until version 0.1.1, and imported as
+`bblocks.datacommons_tools`. Installing the old distribution now pulls in `dcp-tools` and
+redirects those imports with a `DeprecationWarning`, so existing code keeps working. Update
+imports to `dcp_tools` when convenient.
+
+## Install
+
+```bash
+pip install dcp-tools
+```
+
+While `1.0.0` is still in alpha, this is a pre-release, so pip won't find it
+unless you ask for pre-releases explicitly: `pip install --pre dcp-tools`.
+
+Or from GitHub:
+
+```bash
+pip install git+https://github.com/ONEcampaign/dcp-tools
+```
+
+## Quickstart
+
+This builds a config and MCF for a source, a provenance, one input file, and one statistical
+variable, then exports the bundle to disk.
+
+```python
+from pathlib import Path
+
+import pandas as pd
+from dcp_tools import CustomDataManager
+
+manager = CustomDataManager()
+manager.add_source(dcid="ONEData", url="https://data.one.org")
+manager.add_provenance(
+    dcid="ONEClimateFinance",
+    url="https://datacommons.one.org/data/climate-finance-files",
+    source="ONEData",
+)
+
+data = pd.DataFrame({
+    "country": ["Kenya", "Kenya", "Vietnam"],
+    "year": [2022, 2023, 2023],
+    "variable": ["climateFinanceProvidedCommitments"] * 3,
+    "value": [12.4, 15.1, 8.7],
+})
+manager.add_input_file(
+    file_name="climate_finance/one_cf_provider_commitments.csv",
+    provenance="ONEClimateFinance",
+    data=data,
+    column_mappings={
+        "observationAbout": "country",
+        "date": "year",
+        "variable": "variable",
+        "value": "value",
+    },
+    observation_properties={"unit": "USDollar"},
+)
+
+manager.add_variable_to_mcf(
+    dcid="climateFinanceProvidedCommitments",
+    name="Climate finance commitments (bilateral)",
+    description="Funding committed for climate adaptation and mitigation projects",
+    stat_type="dcid:measuredValue",
+)
+
+out_dir = Path("export/climate_finance")
+out_dir.mkdir(parents=True, exist_ok=True)
+manager.export_all(out_dir)
+```
+
+`export_all` writes `config.json`, the CSV, and both MCF files under `out_dir`. Since we
+never called `set_import_name`, `config.json` defaults `importName` to the export directory's
+name, and column mappings and the provenance name are resolved to full dcids:
+
+```json
+{
+    "importName": "climate_finance",
+    "inputFiles": [
+        {
+            "filename": "climate_finance/one_cf_provider_commitments.csv",
+            "provenance": "dcid:provenance/ONEClimateFinance",
+            "columnMappings": {
+                "dcid:variableMeasured": "variable",
+                "dcid:observationDate": "year",
+                "dcid:value": "value",
+                "dcid:observationAbout": "country"
+            },
+            "observationProperties": {"unit": "USDollar"},
+            "format": "variablePerRow"
+        }
+    ]
+}
+```
+
+## Loading it
+
+Once you have a bundle on disk, `dcp_tools.gcp_utilities` uploads it and triggers the load:
+
+```python
+from dcp_tools.gcp_utilities import get_kg_settings, upload_to_cloud_storage, run_data_load
+
+settings = get_kg_settings(source="env", env_file="customDC.env")
+upload_to_cloud_storage(settings=settings, directory="export/climate_finance")
+run_data_load(settings=settings)
+```
+
+`run_data_load` triggers the DCP (Data Commons Platform) ingestion job, which ingests the new
+data and serves it. There's no separate redeploy step to run. See the
+[loading-data docs](https://docs.one.org/tools/dcp-tools/loading-data/) for the
+full settings reference, and the `dcp-tools` CLI (`upload`, `dataload`, `pipeline`), which wraps
+this same flow.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING](https://github.com/ONEcampaign/dcp-tools/blob/main/CONTRIBUTING.MD)
+for how to get started, report bugs, and submit changes.

dcp_tools-1.0.0a1/README.md

@@ -0,0 +1,132 @@
+# dcp-tools
+
+__Manage and load data to Data Commons Platform instances__
+
+[![PyPI](https://img.shields.io/pypi/v/dcp-tools.svg)](https://pypi.org/project/dcp-tools/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dcp-tools.svg)](https://pypi.org/project/dcp-tools/)
+[![Docs](https://img.shields.io/badge/docs-dcp--tools-blue)](https://docs.one.org/tools/dcp-tools/)
+[![Lint/format: Ruff](https://img.shields.io/badge/lint%2Fformat-ruff-46a758.svg)](https://github.com/astral-sh/ruff)
+
+A [Data Commons Platform](https://docs.datacommons.org/custom_dc/custom_data.html) instance takes
+your data as CSVs in a fixed variable-per-row shape, plus a `config.json` that maps each CSV's
+columns onto the Data Commons schema. If you're defining your own statistical variables,
+entities, or properties rather than reusing existing ones, you also need MCF (Meta Content
+Framework) files describing them. `dcp-tools` builds and validates that bundle in Python (or from
+the CLI) and uploads it to Cloud Storage to trigger the platform's ingestion job.
+
+This package was published as `bblocks-datacommons-tools` until version 0.1.1, and imported as
+`bblocks.datacommons_tools`. Installing the old distribution now pulls in `dcp-tools` and
+redirects those imports with a `DeprecationWarning`, so existing code keeps working. Update
+imports to `dcp_tools` when convenient.
+
+## Install
+
+```bash
+pip install dcp-tools
+```
+
+While `1.0.0` is still in alpha, this is a pre-release, so pip won't find it
+unless you ask for pre-releases explicitly: `pip install --pre dcp-tools`.
+
+Or from GitHub:
+
+```bash
+pip install git+https://github.com/ONEcampaign/dcp-tools
+```
+
+## Quickstart
+
+This builds a config and MCF for a source, a provenance, one input file, and one statistical
+variable, then exports the bundle to disk.
+
+```python
+from pathlib import Path
+
+import pandas as pd
+from dcp_tools import CustomDataManager
+
+manager = CustomDataManager()
+manager.add_source(dcid="ONEData", url="https://data.one.org")
+manager.add_provenance(
+    dcid="ONEClimateFinance",
+    url="https://datacommons.one.org/data/climate-finance-files",
+    source="ONEData",
+)
+
+data = pd.DataFrame({
+    "country": ["Kenya", "Kenya", "Vietnam"],
+    "year": [2022, 2023, 2023],
+    "variable": ["climateFinanceProvidedCommitments"] * 3,
+    "value": [12.4, 15.1, 8.7],
+})
+manager.add_input_file(
+    file_name="climate_finance/one_cf_provider_commitments.csv",
+    provenance="ONEClimateFinance",
+    data=data,
+    column_mappings={
+        "observationAbout": "country",
+        "date": "year",
+        "variable": "variable",
+        "value": "value",
+    },
+    observation_properties={"unit": "USDollar"},
+)
+
+manager.add_variable_to_mcf(
+    dcid="climateFinanceProvidedCommitments",
+    name="Climate finance commitments (bilateral)",
+    description="Funding committed for climate adaptation and mitigation projects",
+    stat_type="dcid:measuredValue",
+)
+
+out_dir = Path("export/climate_finance")
+out_dir.mkdir(parents=True, exist_ok=True)
+manager.export_all(out_dir)
+```
+
+`export_all` writes `config.json`, the CSV, and both MCF files under `out_dir`. Since we
+never called `set_import_name`, `config.json` defaults `importName` to the export directory's
+name, and column mappings and the provenance name are resolved to full dcids:
+
+```json
+{
+    "importName": "climate_finance",
+    "inputFiles": [
+        {
+            "filename": "climate_finance/one_cf_provider_commitments.csv",
+            "provenance": "dcid:provenance/ONEClimateFinance",
+            "columnMappings": {
+                "dcid:variableMeasured": "variable",
+                "dcid:observationDate": "year",
+                "dcid:value": "value",
+                "dcid:observationAbout": "country"
+            },
+            "observationProperties": {"unit": "USDollar"},
+            "format": "variablePerRow"
+        }
+    ]
+}
+```
+
+## Loading it
+
+Once you have a bundle on disk, `dcp_tools.gcp_utilities` uploads it and triggers the load:
+
+```python
+from dcp_tools.gcp_utilities import get_kg_settings, upload_to_cloud_storage, run_data_load
+
+settings = get_kg_settings(source="env", env_file="customDC.env")
+upload_to_cloud_storage(settings=settings, directory="export/climate_finance")
+run_data_load(settings=settings)
+```
+
+`run_data_load` triggers the DCP (Data Commons Platform) ingestion job, which ingests the new
+data and serves it. There's no separate redeploy step to run. See the
+[loading-data docs](https://docs.one.org/tools/dcp-tools/loading-data/) for the
+full settings reference, and the `dcp-tools` CLI (`upload`, `dataload`, `pipeline`), which wraps
+this same flow.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING](https://github.com/ONEcampaign/dcp-tools/blob/main/CONTRIBUTING.MD)
+for how to get started, report bugs, and submit changes.

dcp_tools-1.0.0a1/pyproject.toml

@@ -0,0 +1,151 @@
+[project]
+name = "dcp-tools"
+version = "1.0.0a1"
+description = "Tools to work with the Data Commons Platform."
+authors = [
+    { name = "ONE Campaign" },
+    { name = "Luca Picci", email = "lpicci96@gmail.com" },
+    { name = "Jorge Rivera", email = "jorge.rivera@one.org" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.11.3,<3.0.0",
+    "pandas>=2.2.3,<4.0.0",
+    "pydantic-settings>=2.9.1,<3.0.0",
+    "google-cloud-storage>=3.1.0,<4.0.0",
+    "datacommons-admin>=1.1.0",
+]
+keywords = ["data-commons", "datacommons", "dcp", "etl", "statistics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+dcp-tools = "dcp_tools.cli:main"
+
+[project.urls]
+homepage = "https://docs.one.org/tools/dcp-tools/"
+documentation = "https://docs.one.org/tools/dcp-tools/"
+repository = "https://github.com/ONEcampaign/dcp-tools"
+issues = "https://github.com/ONEcampaign/dcp-tools/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ty>=0.0.33",
+    "ruff>=0.8.0",
+    "pre-commit>=3.0.0",
+    "mkdocs-material>=9.6.14,<10.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+extend-include = ["*.ipynb"]
+
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "*.egg-info",
+    ".pytest_cache",
+    "htmlcov",
+]
+
+[tool.ruff.lint]
+# "N" (pep8-naming) is intentionally omitted: the public API mirrors the Data
+# Commons config.json schema, which is camelCase (e.g. ``importName``,
+# ``set_includeInputSubdirs``). Those names are a serialization contract, not a
+# style choice, so the naming rules would fight the domain.
+select = [
+    "E", "W", "F",      # pycodestyle, pyflakes
+    "I",                 # isort
+    "UP",                # pyupgrade
+    "B",                 # bugbear
+    "C4",                # comprehensions
+    "SIM",               # simplify
+    "PL",                # pylint
+    "RUF",               # ruff-specific
+    "ERA",               # eradicate (commented-out code)
+    "PERF",              # perflint
+    "ANN",               # flake8-annotations (require type hints on public APIs)
+]
+
+ignore = [
+    "E501",     # Line length (formatter handles)
+    "PLR0913",  # Too many arguments
+    "PLR0912",  # Too many branches
+    "PLR0914",  # Too many locals
+    "PLR0915",  # Too many statements
+    "PLR2004",  # Magic values
+    "ANN401",   # Allow `Any` in typed signatures
+]
+
+# Allow autofix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+# Tests don't need annotations or pylint-complexity gates.
+"tests/**/*.py" = ["ANN", "PLR2004"]
+# Notebooks: don't require annotations; allow REPL-style patterns.
+"**/*.ipynb" = ["ANN", "F401", "F811", "E402"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = ["src/dcp_tools"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=src/dcp_tools --cov-report=term"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "def __str__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+precision = 2

dcp_tools-1.0.0a1/src/dcp_tools/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import version
+
+from .custom_data.config_utils import merge_configs_from_directory
+from .custom_data.data_management import CustomDataManager
+from .custom_data.schema_tools import csv_metadata_to_mcf_file, csv_metadata_to_nodes
+
+__version__ = version("dcp-tools")
+
+
+__all__ = [
+    "CustomDataManager",
+    "csv_metadata_to_mcf_file",
+    "csv_metadata_to_nodes",
+    "merge_configs_from_directory",
+]

dcp_tools-1.0.0a1/src/dcp_tools/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m dcp_tools``."""
+
+from dcp_tools.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dcp_tools-1.0.0a1/src/dcp_tools/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command line interface for ``dcp_tools`` package."""
+
+from dcp_tools.cli.main import main
+
+__all__ = ["main"]

dcp_tools-1.0.0a1/src/dcp_tools/cli/common.py

@@ -0,0 +1,9 @@
+import argparse
+
+from dcp_tools.gcp_utilities import KGSettings, get_kg_settings
+
+
+def load_settings_from_args(args: argparse.Namespace) -> KGSettings:
+    if args.settings_file:
+        return get_kg_settings(source="json", file=args.settings_file)
+    return get_kg_settings(env_file=args.env_file)

dcp_tools-1.0.0a1/src/dcp_tools/cli/csv2mcf.py

@@ -0,0 +1,91 @@
+"""CSV to MCF command implementation."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from dcp_tools.custom_data.schema_tools import (
+    NodeTypes,
+    csv_metadata_to_mcf_file,
+)
+
+__all__ = ["add_parser", "run"]
+
+
+def _kv_pair(value: str) -> tuple[str, str]:
+    """Parse a KEY=VALUE string into a tuple."""
+    if "=" not in value:
+        raise ValueError(f"Invalid key-value pair: {value}")
+    key, val = value.split("=", 1)
+    return key.strip(), val.strip()
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``csv2mcf`` subcommand with the CLI parser."""
+    parser = subparsers.add_parser(
+        "csv2mcf", help="Convert a CSV of Node metadata to an MCF file"
+    )
+
+    parser.add_argument("csv", type=Path, help="Path to the input CSV file")
+    parser.add_argument("mcf", type=Path, help="Path to write the generated MCF")
+
+    parser.add_argument(
+        "--node-type",
+        choices=[node_type.value for node_type in NodeTypes],
+        default="Node",
+        help="Type of node to create (default: %(default)s)",
+    )
+
+    parser.add_argument(
+        "--column-mapping",
+        metavar="CSV_COL=MCF_PROP",
+        type=_kv_pair,
+        action="append",
+        help=(
+            "Map CSV column names to MCF properties. "
+            "May be used multiple times, eg: "
+            "--column-mapping description=searchDescription --column-mapping indicator=Node"
+        ),
+    )
+
+    parser.add_argument(
+        "--csv-option",
+        metavar="KEY=VALUE",
+        type=_kv_pair,
+        action="append",
+        help=(
+            "Extra keyword arguments forwarded to pandas.read_csv, "
+            'e.g. --csv-option delimiter=";" --csv-option encoding=UTF-8'
+        ),
+    )
+
+    parser.add_argument(
+        "--ignore-column",
+        metavar="COLUMN",
+        action="append",
+        help="Name of a CSV column to ignore. May be specified multiple times.",
+    )
+
+    parser.add_argument(
+        "--append", action="store_true", help="Append to the output file if it exists."
+    )
+
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the ``csv2mcf`` command."""
+    column_mapping = dict(args.column_mapping) if args.column_mapping else None
+    csv_options = dict(args.csv_option) if args.csv_option else None
+
+    csv_metadata_to_mcf_file(
+        csv_path=args.csv,
+        mcf_path=args.mcf,
+        node_type=args.node_type,
+        column_to_property_mapping=column_mapping,
+        csv_options=csv_options,
+        ignore_columns=args.ignore_column,
+        overwrite=not args.append,
+    )
+    return 0

dcp_tools-1.0.0a1/src/dcp_tools/cli/data_load.py

@@ -0,0 +1,35 @@
+"""Run the data load job via CLI."""
+
+import argparse
+from pathlib import Path
+
+from dcp_tools.cli.common import load_settings_from_args
+from dcp_tools.gcp_utilities.pipeline import run_data_load
+
+__all__ = ["add_parser", "run"]
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``dataload`` subcommand."""
+    parser = subparsers.add_parser(
+        "dataload", help="Run the Knowledge Graph data load job"
+    )
+    parser.add_argument(
+        "--settings-file", type=Path, help="Path to the KG settings JSON file"
+    )
+    parser.add_argument(
+        "--env-file", type=Path, help="Optional .env file containing KG settings"
+    )
+    parser.add_argument(
+        "--imports",
+        type=str,
+        help="Comma-separated list of imports to load, defaults to all imports",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the ``dataload`` command."""
+    settings = load_settings_from_args(args)
+    run_data_load(settings=settings, imports=args.imports)
+    return 0

dcp_tools-1.0.0a1/src/dcp_tools/cli/data_load_pipeline.py

@@ -0,0 +1,47 @@
+"""Run the full Knowledge Graph pipeline via CLI."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from dcp_tools.cli.common import load_settings_from_args
+from dcp_tools.gcp_utilities.pipeline import (
+    run_data_load,
+    upload_to_cloud_storage,
+)
+
+__all__ = ["add_parser", "run"]
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``pipeline`` subcommand."""
+    parser = subparsers.add_parser(
+        "pipeline", help="Run the full Knowledge Graph loading pipeline"
+    )
+    parser.add_argument(
+        "--settings-file", type=Path, help="Path to the KG settings JSON file"
+    )
+    parser.add_argument(
+        "--env-file", type=Path, help="Optional .env file containing KG settings"
+    )
+    parser.add_argument(
+        "--directory",
+        type=Path,
+        help="Local directory to upload. Defaults to settings.LOCAL_PATH",
+    )
+    parser.add_argument(
+        "--sync",
+        action="store_true",
+        default=False,
+        help="Delete remote blobs that no longer have a local counterpart after uploading",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the ``pipeline`` command."""
+    settings = load_settings_from_args(args)
+    upload_to_cloud_storage(settings=settings, directory=args.directory, sync=args.sync)
+    run_data_load(settings=settings)
+    return 0