Getting started
Start with a clean environment, confirm the CLI entry point, then run the read-oriented commands that are safe for local checks, CI, scripts, and agents.
Install
The SDK is distributed as the open-data-products Python package. Use a virtual environment for each project because optional extras and model-runtime dependencies can differ between a simple validation workflow, a Data Contract workflow, and a local llama.cpp workflow.
mkdir data-product-sdk-howto cd data-product-sdk-howto python3 -m venv .venv source .venv/bin/activate python3 -m pip install --upgrade pip pip install open-data-products open-data-products --version open-data-products --help
After installation, open-data-products --version should print the installed package version and open-data-products --help should show the unified command tree. If the command is not found, the virtual environment is usually not active or the agent host is using a different Python environment. The file paths below are examples; replace them with files in your project, or run them from a cloned SDK repository that contains the sample files.
pip install open-data-products installs the SDK, unified CLI, generation templates, portfolio commands, and MCP server entry point.
Use pip install "open-data-products[contracts]" for optional Data Contract CLI integration, pip install "open-data-products[email]" for Outlook MSG intake, and pip install "open-data-products[llama-cpp]" for embedded GGUF inference.
Validate and explain
Validation should be the first command in every workflow. It catches schema and SDK rule issues before you ask an LLM to use the file, render it, build a graph from it, or include it in a portfolio workspace.
open-data-products validate product.yaml open-data-products validate product.yaml --json open-data-products explain product.yaml open-data-products explain product.yaml --json open-data-products summary product.yaml --json open-data-products refs graph.yaml --json
Use validate as the quality gate, explain for a readable summary, summary for small metadata such as spec, kind, id, size, line count, and hash, and refs when a workflow needs to discover linked artifacts.
Use JSON for automation
Readable output is better at the terminal. JSON output is better for CI, scripts, notebooks, and agent tools because it gives a stable object shape and avoids parsing terminal prose.
mkdir -p reports open-data-products validate products/customer-risk.yaml --json open-data-products explain products/customer-risk.yaml --json open-data-products summary products/customer-risk.yaml --json
Discover bundled resources
Resources are useful when you need to inspect the SDK's built-in knowledge before choosing a command. For example, an agent can fetch vocabulary records before resolving a term, or inspect prompt resource metadata before deciding whether generation should use bundled prompts or project-owned prompts.
open-data-products resources --json open-data-products resources --id generation.prompt.system --json open-data-products resources --id odpc.objects --json open-data-products resources --id odpv.terms --json open-data-products resources --id odpg.objects --json open-data-products resources --id okf.spec --json
First project folder
A small project structure keeps generated files separate from source material and reports. This makes it clear which files humans wrote, which files the SDK generated, and which files are derived evidence.
source_docs/ products/ use-cases/ objectives/ signals/ generated/ fragments/ catalogs/ graphs/ reports/
Basic decision table
| Command | Use when | Output shape |
|---|---|---|
validate | You need pass/fail quality evidence. | Readable by default, JSON with --json. |
explain | A human or agent needs a compact explanation. | Text or structured JSON. |
summary | You need identity and file metadata without loading the full body. | Text or structured JSON. |
resources | You need bundled schemas, prompts, vocabulary, catalog records, or graph guidance. | Resource list or one resource by id. |