# Open Data Products SDK

> Agent-facing guide for the Open Data Products SDK landing page at https://opendataproducts.org/sdk/.

The Open Data Products SDK is the primary implementation toolkit for the Open Data Products standards family. It is an agent-ready Python SDK and MCP server for loading, detecting, validating, explaining, summarizing, generating, compacting, importing, exporting, searching, traversing, and publishing Open Data Product artifacts, OKF context bundles, and ODPR workflow recipes.

Use it across:

- ODPS: Open Data Product Specification v4.1 and compatible v4.0 product documents.
- ODPC: Open Data Product Catalog fragments, catalogs, object guidance, generated catalog artifacts, and optional TOON or GCF context sidecars.
- ODPG: Open Data Product Graph validation, summaries, traversal, strategic analysis, graph explorer output, and optional TOON or GCF context sidecars.
- ODPV: Open Data Product Vocabulary search, validation, term resolution, relationship checks, and agent context packets.
- ODPR: workflow recipes as portable workflow contracts for repeatable SDK runs, provider choices, validation gates, context formats, and review policy.
- Data Contracts: ODPS contract references, optional external `datacontract-cli` validation, schema extraction, alignment checks, and product-level reports.
- Portfolio workspaces: build, refresh, sync, render, localize, and explain connected ODPC, ODPS, and ODPG portfolio outputs from source lanes.

External context bundle support:

- OKF: Open Knowledge Format Markdown/frontmatter bundles for portable human and agent review. OKF is not a fifth Open Data Products standard; ODPS, ODPC, ODPG, and ODPV remain the canonical structured artifacts.

## Use This For

- Validating ODPS product specifications, ODPC catalogs, ODPG graphs, ODPV vocabulary, and Data Contract references.
- Creating structured context for AI agents, product owners, stewards, and engineers.
- Loading lightweight summaries with size, hash, spec, kind, and id without returning full document bodies.
- Validating OKF bundles, listing OKF concepts safely for agents, importing OKF concepts as generation-ready Markdown, and exporting ODPC catalog or portfolio artifacts as OKF context.
- Emitting compact TOON and experimental GCF sidecars for ODPC catalogs and ODPG graphs while YAML remains the canonical source.
- Discovering bundled resources such as schemas, prompt templates, vocabulary records, catalog object records, graph object records, and `okf.spec` metadata.
- Generating standards-aware artifacts with local LLMs through Ollama, LM Studio, vLLM, llama.cpp server, embedded llama.cpp via `llama-cpp-python`, LocalAI, or hosted providers such as Claude, OpenAI, OpenRouter, and Groq.
- Using ODPR recipes as workflow contracts for repeatable SDK automation across local, hosted, deterministic, and hybrid steps.
- Searching ODPV terms, ODPC catalog guidance, graph objects, Data Contract context, and product references.
- Traversing product, objective, KPI, use-case, signal, and graph relationships.
- Exposing safe SDK operations to AI agents through Model Context Protocol.
- Rendering an ARWS-compatible agent manifest.
- Building end-to-end portfolio workspaces from objectives, use cases, signals, and product source material.

## Project Links

- SDK page: https://opendataproducts.org/sdk/
- GitHub repository: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk
- Repository guides: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides
- API reference: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/API.md
- Command guide: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/commands.md
- LLM generation guide: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/generation.md
- Embedded llama.cpp guide: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/llama-cpp.md
- LLM selection guide: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/llm-selection-guide.md
- ODPR workflow recipes: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/planning/sdk-workflow-profiles-plan.md
- Agent surface guide: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/agent-surface.md
- Data Contract workflows: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/data-contracts.md
- OKF commands: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/commands.md#okf-context-bundles
- OKF adapter reference: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/open_data_products/okf_spec.md
- Open Data Product Initiative: https://opendataproducts.org/
- Standards family:
  - ODPS: https://opendataproducts.org/v4.1/
  - ODPV: https://opendataproducts.org/odpv-v1.0/
  - ODPG: https://opendataproducts.org/odpg-v1.0/
  - ODPC: https://opendataproducts.org/odpc-v1.0/

## Install

```bash
pip install open-data-products
```

Optional Data Contract adapter:

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

Optional embedded llama.cpp support:

```bash
pip install "open-data-products[llama-cpp]"
```

## CLI Entry Point

Use the unified command:

```bash
open-data-products
```

Common workflows:

```bash
# Cross-spec validation and explanation
open-data-products validate examples/product.yaml
open-data-products explain examples/product.yaml
open-data-products summary examples/product.yaml
open-data-products refs open_data_products/odpg/data/graph/graph.yaml --json

# Bundled resources for agents
open-data-products resources --json
open-data-products resources --id odpv.terms --json
open-data-products resources --id odpc.objects --json
open-data-products resources --id odpg.objects --json
open-data-products resources --id okf.spec --json

# OKF context bundles
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/

# Compact context sidecars
open-data-products odpc-build fragments/ --output catalog.yaml --toon catalog.toon --gcf catalog.gcf
open-data-products odpg-build fragments/ --output graph.yaml --toon graph.toon --gcf graph.gcf

# Agent surfaces
open-data-products serve
open-data-products manifest --json

# LLM-backed generation
open-data-products generate \
  --input source_docs/products/ \
  --kind product-reference \
  --output generated/

# Portfolio workspace orchestration
open-data-products portfolio build \
  --objectives source_docs/objectives/ \
  --use-cases source_docs/use-cases/ \
  --signals source_docs/signals/ \
  --products source_docs/products/ \
  --output generated/portfolio/
open-data-products portfolio refresh generated/portfolio/
open-data-products portfolio sync generated/portfolio/
open-data-products portfolio localize generated/portfolio/ --languages "fi,sv,ar,vi"
open-data-products portfolio explain generated/portfolio/
```

Most commands print human-readable output by default. Add `--json` when agents, CI jobs, or scripts need stable machine-readable output.

## LLM Usage

The SDK supports LLM-assisted generation workflows. Agents and developers can use local LLMs through Ollama, LM Studio, vLLM, llama.cpp server, embedded llama.cpp via `llama-cpp-python`, and LocalAI, or hosted providers such as Claude, OpenAI, OpenRouter, and Groq, to help generate standards-aware ODPS, ODPC, and ODPG artifacts.

The default generation config suggests provider profiles such as `ollama-gemma3n`, `ollama-qwen3`, `ollama-qwen3-14b`, `lmstudio-gemma4-12b`, `llamacpp-embedded`, `claude`, and `openai`. Select them with `--provider <name>`, extend the config with additional local models, hosted providers, GGUF model paths, or OpenAI-compatible endpoints, and use the LLM selection guide to match a profile to each SDK job.

Example profile-backed commands:

```bash
open-data-products generate \
  --input source_docs/products/ \
  --kind product-reference \
  --provider ollama-gemma3n \
  --output generated/

open-data-products portfolio refresh \
  generated/portfolio/ \
  --provider claude

open-data-products portfolio localize \
  generated/portfolio/ \
  --languages "fi,sv" \
  --provider lmstudio-gemma4-12b
```

Local model names are provided by the selected runtime rather than hard-coded by the SDK. Common local model families include Llama, DeepSeek, Qwen, Mistral, Mixtral, Phi, Gemma, Code Llama, StarCoder, Yi, Command R, Falcon, Granite, Nemotron, Vicuna, WizardLM, and other models exposed through an Ollama server, OpenAI-compatible local server, or local GGUF file.

Use llama.cpp in two ways:

- `llama.cpp server`, LM Studio, vLLM, and LocalAI can be configured through OpenAI-compatible local endpoints.
- `llamacpp-embedded` uses the optional `llama-cpp-python` package to call a local GGUF model directly, without running a separate server.

Keep generated output grounded in the standards family and validate artifacts after generation.

## Compact Context Sidecars

The SDK can emit compact context sidecars for ODPC catalogs and ODPG graphs:

- TOON sidecars pack repeated object structures into a smaller text shape for model context.
- GCF sidecars are experimental agent-facing context exports for repeated catalog rows and graph nodes or edges.
- ODPR workflow recipes can make compact-context choices explicit, including which sidecars, providers, validation gates, and review steps a repeatable agent run should use.
- YAML remains the canonical standards artifact. Treat `.toon` and `.gcf` files as generated sidecars for prompts, summaries, review automation, and agent workflows.

Common commands:

```bash
open-data-products odpc-build fragments/ \
  --output catalog.yaml \
  --toon catalog.toon \
  --gcf catalog.gcf

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

When compact sidecars sit beside a canonical YAML file, SDK summaries can expose them as context artifacts so agents can discover the smaller representation before reading full document bodies.

Recommended generation loop:

1. Load or create source context.
2. Generate or update the artifact with a local LLM or provider.
3. Validate the resulting YAML or JSON with `open-data-products validate`.
4. Explain or inspect the artifact with `open-data-products explain`.
5. Build catalogs, graphs, compact sidecars, or portfolio outputs only after review.

## OKF Context Bundles

The SDK supports Open Knowledge Format as an external Markdown/frontmatter context bundle format:

- Use `open-data-products okf-validate <bundle-dir>` to validate an OKF bundle.
- Use `open-data-products okf-summary <bundle-dir>` to list concept metadata without returning full Markdown bodies.
- Use `open-data-products okf-import <bundle-dir> --output <source-docs-dir>` to write OKF concepts as generation-ready Markdown source documents.
- Use `open-data-products okf-export <catalog-or-portfolio> --output <bundle-dir>` to export an ODPC catalog file or portfolio workspace as a portable OKF bundle.
- Use `open-data-products resources --id okf.spec --json` for bundled OKF adapter/spec metadata.

OKF is a context exchange format, not a canonical Open Data Products structured artifact. Do not describe OKF as ODPS, ODPC, ODPG, ODPV, or as a fifth standard.

## MCP And ARWS Usage

The SDK includes Model Context Protocol support for agent hosts.

Run the MCP server over stdio:

```bash
open-data-products serve
```

Render the ARWS agent manifest:

```bash
open-data-products manifest --json
```

Use MCP when an agent needs structured resources, safe tools, validation, explanation, summaries, compact context artifact discovery, OKF bundle validation, OKF concept listing, reference discovery, search, traversal, product context, standards-aware graph relationships, or LLM-assisted generation workflows.

Safe OKF MCP tools:

- `validate_okf_bundle`
- `list_okf_concepts`

## Selected Guide Tracks

Use the full guide index when you need the course-aligned sequence:

https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides

The Udemy Masterclass for the Data Product SDK is now available. It turns the current SDK updates into a guided, practical learning path for building scalable, agent-ready data product value management workflows:

https://www.udemy.com/course/scalable-data-product-value-management-with-agent-ready-sdk/?referralCode=DE23AF7C13D47E90B996

For voucher access to the SDK Masterclass, contact Jarkko Moilanen on LinkedIn:

https://www.linkedin.com/in/jarkkomoilanen/

Recommended website tracks:

- Start:
  - Set up Python, pip, PyPI, and the SDK: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/00-setup-python
  - Installing and running the SDK: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/07-installing-and-running-sdk
  - Validating and explaining standards files: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/08-validating-and-explaining-standards-files
- Generate:
  - Working with local LLMs: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/10-working-with-local-llms
  - Working with online LLM providers: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/11-working-with-online-llm-providers
  - Choosing an LLM for each SDK job: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/llm-selection-guide.md
  - Embedded llama.cpp: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/blob/main/docs/user/llama-cpp.md
  - Working with generation and fragments: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/13-working-with-generation-and-fragments
- Reason:
  - Use ODPV vocabulary helpers: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/09-use-odpv-vocabulary-helpers
  - Working with ODPG graphs: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/14-working-with-odpg-graphs
  - Working with ODPC catalogs: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/15-working-with-odpc-catalogs
- Portfolio:
  - From commands to portfolio builder: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/16-from-commands-to-portfolio-builder
  - Build the first portfolio in Colab: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/18-build-first-portfolio-in-colab
  - Final review, human view, and agent-ready YAML: https://github.com/Open-Data-Product-Initiative/odp-agent-sdk/tree/main/examples/guides/20-final-review-human-view-and-agent-ready-yaml

## Maintainer

- Jarkko Moilanen: https://www.linkedin.com/in/jarkkomoilanen/

## Agent Notes

- Prefer `open-data-products` examples when documenting SDK workflows.
- Treat the SDK as the standards-family toolkit, not an ODPS-only tool.
- Mention MCP and ARWS together when describing agent-host support.
- Mention both local LLM runtimes, including LM Studio and embedded llama.cpp, and service providers when describing generation.
- Mention that common provider profile names are suggestions enabled by the default SDK generation configuration and selected with `--provider <name>`.
- Mention that teams can extend generation config with their own model and provider profiles.
- Mention ODPR recipes as workflow contracts for repeatable SDK runs, not just another model setting.
- Mention OKF as an external Markdown/frontmatter context bundle format, not as a fifth Open Data Products standard.
- Mention `open_data_products.okf` when Python helper surfaces are relevant: validation, concept summaries, import, and export.
- Mention `validate_okf_bundle` and `list_okf_concepts` when describing safe MCP OKF support.
- Mention `okf.spec` when describing bundled resource metadata.
- Mention TOON and GCF as optional compact sidecars, not replacements for YAML.
- Use `open-data-products serve` for the MCP server command.
- Use `open-data-products manifest --json` for the ARWS agent manifest command.
- Validate generated artifacts before presenting them as usable standards files.