{
  "markdown": "# Digital Passport Model Assessment Workbench\n\n[![PyPI - Version](https://img.shields.io/pypi/v/dpawb)](https://pypi.org/project/dpawb/)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19731237.svg)](https://doi.org/10.5281/zenodo.19731237)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-DPAWB%20MCP-0A7B83)](https://registry.modelcontextprotocol.io/?q=dpawb)\n\n<!-- mcp-name: io.github.CE-RISE-software/dpawb -->\n\nA Python toolkit and thin CLI for SHACL-based assessment of digital passport data models, pairwise comparison of composed solutions, and SHACL-only use-case coverage analysis.\n\nThis README is primarily a repository and development entry point. The user-facing conceptual and usage reference is at [the published documentation site](https://ce-rise-software.codeberg.page/dp-assessment-workbench/). The repository-source docs remain available in [`docs/`](docs/index.md).\n\n---\n\n## What this repository contains\n\n- A publishable Python package with a CLI entry point: `dpawb`\n- A thin stdio MCP server entry point: `dpawb-mcp`\n- Contract-aligned input schemas for composition profiles, use cases, and alignments\n- Built-in vocabularies and templates exposed through discovery commands\n- Synthetic local fixtures used only for tests and validation\n- A progression-based examples tree for human and AI-agent tutorials\n\n## Tool Shape\n\nThe tool is designed primarily as an agent-usable analytical toolkit with a thin CLI. The core command surface is:\n\n- `assess`\n- `coverage`\n- `compare`\n- `prioritize`\n- `recommend-composition`\n- `schema`\n- `vocabulary`\n- `template`\n- `capabilities`\n- `summarize`\n\n## AI-agent use\n\nThe intended primary integration mode is an AI agent orchestrating the analytical pipeline through the package API or the CLI. In practice, this means:\n\n- deterministic file-based inputs\n- JSON outputs suitable for agent parsing and chaining\n- explicit analytical steps instead of a chat-oriented interface\n\nThe CLI remains useful for direct human invocation, but the main product shape is an analytical engine that can be called by agent skills, workflow runners, or tool adapters.\n\nThe package also ships a thin stdio MCP server over the same deterministic command surface:\n\n- `assess`\n- `coverage`\n- `compare`\n- `prioritize`\n- `recommend-composition`\n- `schema`\n- `vocabulary`\n- `template`\n- `capabilities`\n- `summarize`\n\nThe MCP surface stays intentionally thin:\n\n- keep `dpawb` as the core Python package\n- expose the same operations through `dpawb-mcp`\n- ship the MCP runtime as both a local Python entry point and a GitHub Container Registry image\n- publish registry metadata from the GitHub mirror\n\nThe MCP runtime and publication shape are documented in [the published MCP server page](https://ce-rise-software.codeberg.page/dp-assessment-workbench/mcp-server.html).\n\nThe public Python API is documented in [the published API reference](https://ce-rise-software.codeberg.page/dp-assessment-workbench/api-reference.html).\n\n## MCP Access\n\nThe MCP server is published with this identity:\n\n- registry name: `io.github.CE-RISE-software/dpawb`\n- OCI image pattern: `ghcr.io/ce-rise-software/dpawb-mcp:<release-version>`\n- transport: `stdio`\n- official registry base: `https://registry.modelcontextprotocol.io/`\n\nThe server is discoverable in the official MCP Registry under the name `io.github.CE-RISE-software/dpawb`.\n\nRegistry discovery page:\n\n- `https://registry.modelcontextprotocol.io/?q=dpawb`\n\nLocal client configuration example:\n\n```json\n{\n  \"mcpServers\": {\n    \"dpawb\": {\n      \"command\": \"dpawb-mcp\"\n    }\n  }\n}\n```\n\nOCI-oriented registry metadata is declared in [`server.json`](server.json). The publish workflow fills in the release version and image tag when publishing.\n\n## Install\n\n```bash\npython -m venv .venv\n. .venv/bin/activate\npip install -e .\n```\n\nPublished package name:\n\n```bash\npip install dpawb\n```\n\nThe installed MCP server command is:\n\n```bash\ndpawb-mcp\n```\n\nIf you are working in a restricted environment, the package is configured to build with `setuptools` so editable installs do not depend on fetching an extra build backend.\n\nIf build isolation or wheel support is unavailable locally, use:\n\n```bash\npython -m pip install --no-build-isolation -e .\n```\n\nIn constrained environments where editable installation is blocked by local Python packaging tooling, the repository still supports a repo-native execution path:\n\n```bash\n./scripts/run-local.sh capabilities\n./scripts/test-local.sh\nmake smoke\nmake test\nmake validate\n```\n\nMinimal local MCP runtime command:\n\n```bash\npython -m dpawb.mcp_server\n```\n\n## Example commands\n\n```bash\ndpawb assess --profile fixtures/profiles/synthetic_evolution_latest.yaml\ndpawb coverage --profile fixtures/profiles/synthetic_evolution_latest.yaml --use-case fixtures/use_cases/product_identity_lookup.yaml\ndpawb compare --left left_assessment.json --right right_assessment.json\ndpawb recommend-composition --left left_assessment.json --right right_assessment.json --comparison comparison_result.json\ndpawb summarize --result comparison_result.json --format markdown\ndpawb capabilities\n```\n\n## Local Release Check\n\nBefore wiring PyPI CI/CD, run the local packaging check in an environment with `wheel` available:\n\n```bash\nmake release-check\n```\n\nThis builds a wheel and sdist, installs the wheel into a clean temporary environment, and runs installed CLI smoke checks.\n\n## Structure\n\nThere are two distinct input areas in this repository:\n\n- `fixtures/`\n  Synthetic, repository-local test data only.\n  These files are used by tests, smoke checks, and CI validation.\n\n- `examples/01-source-ingestion/`\n  Live-source example inputs intended for manual runs.\n  These are the first step in the tutorial progression and are not part of CI validation.\n\nThe full examples tree is organized by analytical task, not by input data model:\n\n- `examples/01-source-ingestion/`\n  Load and assess declared profiles.\n- `examples/02-structural-comparison/`\n  Compare two profile assessment results.\n- `examples/03-reduced-use-case-comparison/`\n  Run the first aligned use-case comparison.\n- `examples/04-extended-use-case-comparison/`\n  Run a broader aligned use-case comparison.\n- `examples/05-composition-recommendation/`\n  Recommend a combined profile from two assessed model sets.\n\nEach example is usable by humans as a step-by-step command tutorial and by AI agents as a deterministic recipe over explicit files.\n\n## Source-ingestion examples\n\nExample profiles for live SHACL sources are included at:\n\n- `examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml`\n- `examples/01-source-ingestion/profiles/battery_product_identification_live.yaml`\n- `examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml`\n- `examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml`\n- `examples/01-source-ingestion/profiles/metadata_focused_composition_live.yaml`\n- `examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml`\n- `examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml`\n- `examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml`\n\nIf you want a single live source, the metadata-oriented example is the main starting point:\n\n```bash\n./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml\n```\n\nIf you want a composed profile, use:\n\n```bash\n./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml\n```\n\nYou can also run the traceability-only example:\n\n```bash\n./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml\n```\n\nFor manual coverage runs, example use cases are included at:\n\n- `examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml`\n- `examples/01-source-ingestion/use_cases/battery_product_identification.yaml`\n- `examples/01-source-ingestion/use_cases/battery_passport_metadata_and_classification.yaml`\n- `examples/01-source-ingestion/use_cases/record_identity_lookup.yaml`\n- `examples/01-source-ingestion/use_cases/provenance_actor_lookup.yaml`\n\nExample:\n\n```bash\n./scripts/run-local.sh coverage \\\n  --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml \\\n  --use-case examples/01-source-ingestion/use_cases/record_identity_lookup.yaml\n```\n\nThe main real comparison-driver use case is:\n\n- `examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml`\n\nIt intentionally stays narrow. It requires:\n\n- passport identity\n- battery identity\n- passport version or revision\n- one responsible actor\n- one battery type or classification signal\n\nand the joins needed to treat those as one battery-DPP representation slice.\n\nThe matching starting composition for that use case is:\n\n- `examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml`\n\nIt currently composes:\n\n- `dp_record_metadata`\n- `traceability_and_life_cycle_events`\n\nThis is the current broader baseline for the battery-DPP comparison work.\n\nFor the first reduced real pass, the narrower identity-focused comparison slice is:\n\n- canonical example folder:\n  `examples/03-reduced-use-case-comparison/`\n- use case:\n  `examples/03-reduced-use-case-comparison/use_cases/use_case.yaml`\n- left profile:\n  `examples/03-reduced-use-case-comparison/profiles/left_profile.yaml`\n- right profile:\n  `examples/03-reduced-use-case-comparison/profiles/right_profile.yaml`\n\nThis reduced slice composes:\n\n- `dp_record_metadata`\n- `product_profile`\n- `traceability_and_life_cycle_events`\n\nand is the first validated product-identification comparison slice against the\nBatteryPass General Product Information model.\n\nA second broader validated slice is also included:\n\n- canonical example folder:\n  `examples/04-extended-use-case-comparison/`\n- use case:\n  `examples/04-extended-use-case-comparison/use_cases/use_case.yaml`\n- left profile:\n  `examples/04-extended-use-case-comparison/profiles/left_profile.yaml`\n- right profile:\n  `examples/04-extended-use-case-comparison/profiles/right_profile.yaml`\n\nThis slice adds passport version/revision and battery type/classification while keeping the same CE-RISE composed model set.\n\nThe two current cross-ecosystem validation notes are:\n\n- `examples/03-reduced-use-case-comparison/notes/comparison_note.md`\n- `examples/04-extended-use-case-comparison/notes/comparison_note.md`\n\nThe step-by-step user reference for these examples is in [the published example applications guide](https://ce-rise-software.codeberg.page/dp-assessment-workbench/example-applications.html).\n\nFor manual comparison runs, a comparison-ready live pair is included with the same declared scope label:\n\n- `examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml`\n- `examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml`\n- `examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml` as a starting-point alignment example\n\nTypical flow:\n\n```bash\n./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml --output /tmp/left.json\n./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml --output /tmp/right.json\n./scripts/run-local.sh compare --left /tmp/left.json --right /tmp/right.json\n```\n\nWith an explicit analyst-authored alignment:\n\n```bash\n./scripts/run-local.sh compare \\\n  --left /tmp/left.json \\\n  --right /tmp/right.json \\\n  --alignment examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml\n```\n\nWhen an alignment file is provided, the comparison result now includes two alignment-oriented views:\n\n- `evaluated_pairs`\n  Full per-pair presence status for every declared equivalence.\n\n- `ranked_alignment_observations`\n  Review-oriented gaps for any declared pair that is only present on one side or missing on both sides.\n\nSo the main things to inspect in an alignment-aware comparison result are:\n\n- `alignment_coverage_ratio`\n- `evaluated_pairs`\n- `ranked_alignment_observations`\n\nIf that comparison result is then passed into `prioritize`, those alignment gaps can also appear directly as ranked improvement targets.\n\nThe current analytical core is still conservative by design, but it now goes beyond token matching alone:\n\n- contradiction detection covers direct cardinality conflicts and datatype-versus-object-reference conflicts\n- item coverage uses SHACL path, owner-shape, and target-class evidence\n- join coverage can be satisfied by a shared owner shape, an explicit cross-shape object-reference path, or record-level retrieval context when that is the intended analytical interpretation\n\n## Repository layout\n\n- `src/dpawb/`: package, CLI, and analytical operations\n- `src/dpawb/data/`: bundled schemas, vocabularies, and templates\n- `fixtures/`: synthetic repository-local models, profiles, use cases, and alignments for tests only\n- `examples/01-source-ingestion/`: source-ingestion profiles, use cases, and alignments for manual runs\n- `examples/03-reduced-use-case-comparison/`: self-contained aligned use-case comparison examples\n- `examples/05-composition-recommendation/`: self-contained composition recommendation example\n- `scripts/`: repo-native execution and test helpers\n- `.github/workflows/validate.yml` and `.forgejo/workflows/validate.yml`: CI validation via the repo-native path\n\n## License\n\nLicensed under the [European Union Public Licence v1.2 (EUPL-1.2)](LICENSE).\n\n## Contributing\n\nThis repository is maintained on [Codeberg](https://codeberg.org/CE-RISE-software/dp-assessment-workbench) — the canonical source of truth. The GitHub repository is a read mirror used for release archival and Zenodo integration. Issues and pull requests should be opened on Codeberg.\n\n---\n\n<a href=\"https://europa.eu\" target=\"_blank\" rel=\"noopener noreferrer\">\n  <img src=\"https://ce-rise.eu/wp-content/uploads/2023/01/EN-Funded-by-the-EU-PANTONE-e1663585234561-1-1.png\" alt=\"EU emblem\" width=\"200\"/>\n</a>\n\nFunded by the European Union under Grant Agreement No. 101092281 — CE-RISE.  \nViews and opinions expressed are those of the author(s) only and do not necessarily reflect those of the European Union or the granting authority (HADEA).\nNeither the European Union nor the granting authority can be held responsible for them.\n\n© 2026 CE-RISE consortium.  \nLicensed under the [European Union Public Licence v1.2 (EUPL-1.2)](LICENSE).  \nAttribution: CE-RISE project (Grant Agreement No. 101092281) and the individual authors/partners as indicated.\n\n<a href=\"https://www.nilu.com\" target=\"_blank\" rel=\"noopener noreferrer\">\n  <img src=\"https://nilu.no/wp-content/uploads/2023/12/nilu-logo-seagreen-rgb-300px.png\" alt=\"NILU logo\" height=\"20\"/>\n</a>\n\nDeveloped by NILU (Riccardo Boero — ribo@nilu.no) within the CE-RISE project.\n",
  "bytes": 14844,
  "sha": "dac158456dae051d7bfd5f99d40c2bad6fc8363b951817e762fac4bb1366f5f2",
  "repo_slug": "ce-rise-software/dp-assessment-workbench",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ce_rise_software_dpawb_0c5e7e73/readme"
}