Reference

Reference patterns

Use this page for common command patterns after the basics are working: catalogs, graphs, compact context sidecars, OKF bundles, Data Contracts, Python API, and troubleshooting.

ODPC catalog outputs

Catalog builds assemble ODPC fragments or compatible product references into one catalog YAML. Add HTML when humans need a review surface. Add TOON or GCF when agents need compact sidecar context, but keep YAML as the canonical artifact. Replace fragments/ with a real folder containing ODPC fragments, ODPC catalogs, or ODPS product files.

CatalogYAML, HTML, TOON, GCF

open-data-products odpc-build fragments/ \
  --output generated/catalog.yaml \
  --html generated/catalog.html \
  --toon generated/catalog.toon \
  --gcf generated/catalog.gcf

open-data-products odpc-summary generated/catalog.yaml
open-data-products odpc-search "retention governance risk" --limit 3

ODPG graph outputs

Graph commands help inspect relationships after fragments or portfolio outputs exist. Use summaries for counts, traversal for path discovery, agent context for a focused prompt packet, and the standalone explorer when reviewers need a browser view. odpg-build can use the configured generation provider for edge inference, so local provider readiness still matters.

Graphbuild, traverse, inspect

open-data-products odpg-build fragments/ \
  --output generated/graph.yaml \
  --toon generated/graph.toon \
  --gcf generated/graph.gcf

open-data-products odpg-summary generated/graph.yaml
open-data-products odpg-traverse generated/graph.yaml --start DATA-PRODUCT-001 --depth 2
open-data-products odpg-agent-context generated/graph.yaml --node DATA-PRODUCT-001
open-data-products odpg-generate generated/graph.yaml --output generated/graph-explorer.html
open-data-products odpg-convert --input graph.graphml --output graph.yaml

OKF bundles

OKFexternal context format

open-data-products okf-validate knowledge-bundle/ --json
open-data-products okf-summary knowledge-bundle/ --json
open-data-products okf-import knowledge-bundle/ --output source_docs/okf/
open-data-products okf-export generated/portfolio/ --output okf-bundle/
open-data-products resources --id okf.spec --json

OKF is a Markdown/frontmatter context bundle format. It is not ODPS, ODPC, ODPG, ODPV, or a fifth Open Data Products standard.

Compact sidecar policy

Artifact	Role	Do not use it as
`.yaml`	Canonical standards source.	A temporary prompt-only scratch file.
`.html`	Human review surface.	The machine-readable source of truth.
`.toon`	Compact repeated-object context for agents and prompts.	A replacement for validated YAML.
`.gcf`	Experimental graph/catalog context sidecar.	A conformance artifact or separate standard.

Data Contract workflows

Use product contract commands when an ODPS product references, ships with, or needs comparison against an external Data Contract. Install the contracts extra before relying on optional contract CLI behavior.

Contractsoptional integration

pip install "open-data-products[contracts]"

open-data-products product resolve-contracts product.yaml --json
open-data-products product check-contract product.yaml contract.yaml --json
open-data-products product align-contract product.yaml contract.yaml --json
open-data-products product contract-schema contract.yaml --json
open-data-products product contract-report product.yaml contract.yaml --json
open-data-products product audit product.yaml --contract contract.yaml --json

Python API

Pythoncore helpers

from open_data_products import (
    copy_config_template,
    copy_generation_prompts,
    explain_document,
    generate_local_artifact,
    get_resource,
    list_resources,
    load_document,
    load_summary,
    resolve_references,
    validate_config,
    validate_document,
)

document = load_document("examples/product.yaml")
validation = validate_document(document)
explanation = explain_document(document)
references = resolve_references(document)
metadata = load_summary("examples/product.yaml")
resources = list_resources()
terms = get_resource("odpv.terms")

copy_config_template("generation", "generation.config.yaml")
copy_generation_prompts("prompts")
config_report = validate_config("generation", "generation.config.yaml")

signal_path = generate_local_artifact(
    "signal",
    "source_docs/signals/turnaround-delay-signal.txt",
    "generated/fragments",
    model="qwen2.5",
)

Troubleshooting

Symptom	Check	Fix
Config check fails with unknown keys.	Look for snake_case keys such as `base_url`.	Use exact keys such as `baseUrl`, `apiKeyEnv`, `sourceBudget`, and `obfuscatePersonalData`.
Generation cannot reach a provider.	Check `provider`, `type`, `baseUrl`, model name, and required environment variable.	Run the local server, pull the model, or export the env var named by `apiKeyEnv`.
Portfolio output is missing source evidence.	Run `portfolio intake --json` and inspect skipped sources, source budget, and source privacy.	Fix lane paths, install optional extras, move text into supported files, or adjust budget knowingly.
Generated YAML fails validation.	Run `validate` and inspect errors before building catalogs or graphs.	Repair the artifact, use a stronger provider/profile, narrow source input, or generate a minimal ODPS shell first.
Agent host cannot launch MCP.	Check that `open-data-products --help` works in the host environment.	Install the package into the active environment and use `open-data-products serve`.