Metadata-Version: 2.2
Name: cf-pipeline-sdk
Version: 0.2.0
Summary: Cogniflow pipeline SDK (cf_siggen + headers)
Requires-Python: >=3.11
Requires-Dist: cf-ontology>=0.2.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Description-Content-Type: text/markdown

# cf_pipeline_sdk

`cf_pipeline_sdk` packages the native SDK assets needed by Cogniflow step packages:

- the Python module `cogniflow_pipeline_sdk`
- the `python -m cogniflow_pipeline_sdk.siggen` entry path
- packaged C/C++ headers for downstream builds
- the `cf_siggen` native binary copied into the installed package

Published distribution name:

```bash
pip install cf-pipeline-sdk
```

## Scope

The published distribution name is `cf-pipeline-sdk`.
The Python import package remains `cogniflow_pipeline_sdk`.

Downstream native step packages consume the SDK through:

- `import cogniflow_pipeline_sdk`
- `cogniflow_pipeline_sdk.cf_sdk_include_path()`
- `cogniflow_pipeline_sdk.cf_siggen_path()`
- `python -m cogniflow_pipeline_sdk.siggen`

## Validation Spec Output

`cogniflow_pipeline_sdk.validation.generate_validation_spec(...)` keeps the
existing normalized port fields unchanged:

- `id`
- `key`
- `types`
- `name`
- `multi` for input ports

When a step manifest port declares `cf:valueContract`, the generated port entry
now adds a `value_contract` object with additive metadata:

- `shape_kind`
- `element_types`
- `table_schema.columns[]` with `name`, `type`, and `nullable` when a table
  schema is declared

If a legacy `cf:portType`/`cf:parameterType` fallback conflicts with
`cf:valueContract/cf:elementType`, validation spec generation fails with a
`ValueError` that names the affected step and member identifier. This keeps
legacy migration paths explicit while exposing the shared shape-aware contract
metadata.

## Native build prerequisites

The SDK is built with `scikit-build-core` and CMake.

For Windows publish/preflight runs, use:

- CPython 3.13
- CMake on `PATH`
- a working Windows C++ toolchain compatible with that CMake installation

The CI publish workflow targets `windows-latest`.
If your local machine exposes multiple CMake/compiler combinations, keep the selected CMake and compiler toolchain consistent for the whole build.

## Publishing

`cf_pipeline_sdk` is published with the dedicated Windows workflow:

- Workflow: `.github/workflows/cf_pipeline_sdk_windows_publish.yml`
- Package directory: `sandcastle/cf_pipeline/cf_pipeline_sdk`
- PyPI tag: `cf-pipeline-sdk-v<version>`
- TestPyPI tag: `cf-pipeline-sdk-v<version>-test`

Local preflight:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/mimic_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_pipeline_sdk_windows_publish.yml `
  -PackageDir sandcastle/cf_pipeline/cf_pipeline_sdk `
  -PythonExe py `
  -PythonVersion 3.13
```

Queue a dry-run dispatch:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/queue_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_pipeline_sdk_windows_publish.yml `
  -PackageDir sandcastle/cf_pipeline/cf_pipeline_sdk `
  -PublishTarget testpypi `
  -Ref main `
  -RequireLocalPass `
  -DryRun
```
