Skip to main content

Senzing Cookbook

For Contributors

A recipe is a markdown build-prompt that a coding agent can execute to produce working Senzing code. The bar is: grounded, test-built, reusable.

Workflow

  1. Propose. Open a New recipe issue (.github/ISSUE_TEMPLATE/new-recipe.md): what it builds, its type, difficulty, and prerequisites.
  2. Draft. Copy RECIPE_TEMPLATE.md into recipes/ and fill every section. (Adding a kitchen or place setting instead? Those are building blocks, not recipes — copy an existing file in kitchens/ or plates/, don’t use the recipe template.)
  3. Ground. Verify every Senzing fact — method names, flags, attribute names, response schemas, platform support, pricing — against the Senzing MCP coworker tools or official docs. Enforce this in your build prompt (the prompt you use to generate the recipe — not the end-user prompts): tell the assistant to use the MCP for every Senzing fact and to report what it verified against — tool/doc + topic + date. That output fills grounded_against and the Grounding sources section, so the record is generated during the build, not reconstructed later.
  4. Test-build. Run the recipe through a coding agent end to end. Confirm each acceptance criterion passes. Only then set status: verified.
  5. PR. Use the PR checklist. CODEOWNERS review required.
  6. Index. Add/update the row in cookbook.md.

The grounding rule (non-negotiable)

Never state a Senzing fact from training-data memory.

Senzing API knowledge in model training data is frequently wrong. Known confabulations to watch for:

  • G2Engine / g2engine (V3) instead of V4 SzEngine via SzAbstractFactory.
  • add_data_source / addDataSource (a CLI command) instead of the SDK register_data_source.
  • close_export instead of close_export_report.
  • Wrong attribute names (e.g. confusing NAME_ORG vs NAME_FULL).
  • Fabricated config options and platform claims (e.g. that the Python binding runs on macOS — it is Linux-only).

Verify against, in order of preference:

  1. Senzing MCP coworker: get_sdk_reference (methods, flags, response_schemas, migration), reporting_guide (export, reports, data_mart, quality), sdk_guide (install/configure/load/search per platform+language), search_docs (everything else).
  2. Official docs at https://senzing.com/docs/4/.

Reviewer checklist

must all be true to merge

  • ☐ Front matter complete, including difficulty, senzing_version, and grounded_against.
  • ☐ Every Senzing API reference matches a cited authoritative source — no V3 or confabulated methods.
  • ☐ Required confirmations include implementation language (no assumed Python).
  • ☐ Hard constraints cover PII handling and read-only / gated-write defaults where relevant.
  • ☐ Recipe was test-built end to end; acceptance criteria pass.
  • ☐ Prerequisites are accurate and point to real recipe ids.
  • ☐ cookbook.md updated.

Style

  • → One recipe per file. Keep it a prompt, not a tutorial — write to the agent.
  • → Prefer language-neutral phrasing; mark code snippets illustrative and note that method names/response JSON are identical across bindings.
  • → Concise and imperative. The acceptance criteria are the contract.