Skip to content

Reporter SDK

This is the canonical SDK contract page for custom reporter authoring in Truthound 3.0.

Truthound 3.0 reporters are authored against ValidationRunResult, not persistence DTOs or pre-3.0 Report objects.

  1. Subclass ValidationReporter or use the SDK builder helpers.
  2. Start from presentation = self.present(run_result).
  3. Use RunPresentation as the primary structure for summaries, issues, and metadata.
  4. Call presentation.to_legacy_view() only when a mixin, helper, or export path genuinely needs compatibility-era flattened rows.

Scaffolding generated by truthound scaffold reporter targets the v3 contract directly and does not import persistence DTOs from truthound.stores.results.

Core SDK Contract

For custom plugins and in-repo reporters:

  • canonical input: truthound.core.ValidationRunResult
  • shared presentation model: truthound.reporters.presentation.RunPresentation
  • compatibility helper: RunPresentation.to_legacy_view()
  • migration helpers: truthound.reporters.sdk.compat
  • canonical plugin contract: Reporter.render(run_result, *, context)

Reporter authors should optimize for the shared presentation model instead of re-deriving summary logic from raw issues. That keeps built-in reporters, validation docs, and plugin reporters aligned.

What Belongs In The SDK

The SDK surface is for:

  • reporter builders and decorators
  • reusable mixins
  • template reporters
  • schema validation helpers
  • testing utilities and mock builders

It is not the same thing as the built-in get_reporter(...) registry. Template reporters such as YAML or JUnit XML live in the SDK family even when they are ready to use out of the box.

Compatibility Rules

  • Treat ValidationRunResult as the source of truth.
  • Do not use persisted ValidationResult DTOs as the primary reporter contract.
  • Use to_legacy_view() only when compatibility-shaped rows simplify a helper or formatter.
  • Keep custom reporter docs and examples in RunPresentation terms first.

Use truthound doctor --migrate-2to3 to detect old Report assumptions before upgrading an existing reporter package.