great-docs.yml

# Great Docs Configuration for Pointblank
# See https://posit-dev.github.io/great-docs/user-guide/configuration.html

display_name: Pointblank

# Docstring Parser
parser: numpy

# Dynamic Introspection
dynamic: true

# Logo
logo:
  light: assets/pointblank_logo_small.svg
  dark: assets/pointblank_logo_small.svg

# Homepage
# Use a simple index.qmd as the landing page
homepage: index
hero:
  logo: assets/pointblank_logo.svg
  logo_height: 250px

# Scale-to-fit for Pointblank validation report tables
scale_to_fit:
  - "#pb_tbl"

# GitHub Integration
github_style: widget

# Source Links
source:
  enabled: true
  branch: main

# CLI Documentation (Click-based)
cli:
  enabled: true
  module: pointblank.cli
  name: cli

# MCP Server Documentation
mcp:
  enabled: true
  module: pointblank.mcp
  server_var: mcp
  name: Pointblank MCP Server
  categories:
    "Data Management":
      - load_dataframe
      - list_loaded_dataframes
      - list_available_backends
      - delete_dataframe
    "Data Analysis":
      - profile_dataframe
    "Validation":
      - create_validator
      - add_validation_step
      - apply_validation_template
      - interrogate_validator
      - get_validation_step_output
      - list_active_validators
      - delete_validator
    "Table Visualization":
      - preview_table
      - missing_values_table
      - column_summary_table
    "AI & Assistant":
      - validation_assistant
      - draft_validation_plan
    "Reference & Management":
      - get_pointblank_api_reference
      - server_health_check

# Changelog
changelog:
  enabled: true

# Custom Sections
sections:
  - title: Demos
    dir: examples
    index: true
    index_columns: 2
  - title: Blog
    dir: blog
    type: blog

# Author Information
authors:
  - name: Richard Iannone
    role: Maintainer
    affiliation: Posit, PBC
    email: riannone@me.com
    github: rich-iannone
    orcid: 0000-0003-3925-190X

# Funding / Copyright Holder
funding:
  name: "Posit Software, PBC"
  roles:
    - Copyright holder
    - funder
  homepage: https://posit.co
  ror: https://ror.org/03wc8by49

# API Discovery
exclude:
  - config
  - assistant.MODEL_PROVIDERS

# API Reference Structure
# Organized to match the current quartodoc sections
reference:
  title: "API Reference"
  sections:
    - title: Validate
      desc: >
        When performing data validation, use the `Validate` class to get the process started. It
        takes the target table and options for metadata and failure thresholds (using the
        `Thresholds` class or shorthands). The `Validate` class has numerous methods for defining
        validation steps and for obtaining post-interrogation metrics and data.
      contents:
        - name: Validate
          members: false
        - Thresholds
        - name: Actions
          members: false
        - FinalActions
        - name: Schema
          members: false
        - name: DraftValidation
          members: false
        - name: EditValidation
          members: true
        - name: MissingSpec
          members: true

    - title: Contracts and Pipelines
      desc: >
        Use `Contract` and `Step` to define declarative data quality contracts that specify what
        valid data looks like. Use `Pipeline` to enforce contracts at both boundaries of a data
        transformation (source and target), producing a `PipelineResult` with full introspection
        into what passed and what failed.
      contents:
        - name: Contract
          members: true
        - name: Step
          members: true
        - name: Pipeline
          members: true
        - name: PipelineResult
          members: true

    - title: Contract Import/Export
      desc: >
        Import external schema definitions (JSON Schema, Frictionless Table Schema, and more) into
        Pointblank validation workflows, or export Pointblank contracts to those formats. Use
        `import_contract()` as the entry point, `export_contract()` for the reverse, and
        `register_adapter()` to add support for custom formats.
      contents:
        - import_contract
        - export_contract
        - list_adapters
        - register_adapter
        - name: ContractImport
          members: true
        - name: ContractAdapter
          members: true

    - title: Validation Steps
      desc: >
        Validation steps are sequential validations on the target data. Call `Validate`'s validation
        methods to build up a validation plan: a collection of steps that provides good validation
        coverage.
      contents:
        - Validate.col_vals_gt
        - Validate.col_vals_lt
        - Validate.col_vals_ge
        - Validate.col_vals_le
        - Validate.col_vals_eq
        - Validate.col_vals_ne
        - Validate.col_vals_between
        - Validate.col_vals_outside
        - Validate.col_vals_in_set
        - Validate.col_vals_not_in_set
        - Validate.col_vals_increasing
        - Validate.col_vals_decreasing
        - Validate.col_vals_null
        - Validate.col_vals_not_null
        - Validate.col_vals_regex
        - Validate.col_vals_within_spec
        - Validate.col_vals_expr
        - Validate.col_exists
        - Validate.col_pct_null
        - Validate.col_pct_missing
        - Validate.col_missing_coded
        - Validate.col_missing_only_coded
        - Validate.col_missing_consistent
        - Validate.rows_distinct
        - Validate.rows_complete
        - Validate.col_schema_match
        - Validate.row_count_match
        - Validate.col_count_match
        - Validate.data_freshness
        - Validate.tbl_match
        - Validate.conjointly
        - Validate.specially
        - Validate.prompt

    - title: Aggregation Steps
      desc: >
        These validation methods check aggregated column values (sums, averages, standard
        deviations) against fixed values or column references.
      contents:
        - Validate.col_sum_gt
        - Validate.col_sum_lt
        - Validate.col_sum_ge
        - Validate.col_sum_le
        - Validate.col_sum_eq
        - Validate.col_avg_gt
        - Validate.col_avg_lt
        - Validate.col_avg_ge
        - Validate.col_avg_le
        - Validate.col_avg_eq
        - Validate.col_sd_gt
        - Validate.col_sd_lt
        - Validate.col_sd_ge
        - Validate.col_sd_le
        - Validate.col_sd_eq

    - title: Column Selection
      desc: >
        Use the `col()` function along with column selection helpers to flexibly select columns for
        validation. Combine `col()` with `starts_with()`, `matches()`, etc. for selecting multiple
        target columns.
      contents:
        - col
        - starts_with
        - ends_with
        - contains
        - matches
        - everything
        - first_n
        - last_n
        - expr_col

    - title: Segment Groups
      desc: >
        Combine multiple values into a single segment using `seg_*()` helper functions.
      contents:
        - seg_group

    - title: Interrogation and Reporting
      desc: >
        The validation plan is executed when `interrogate()` is called. After interrogation, view
        validation reports, extract metrics, or split data based on results.
      contents:
        - Validate.interrogate
        - Validate.set_tbl
        - Validate.get_tabular_report
        - Validate.get_step_report
        - Validate.get_json_report
        - Validate.get_dataframe_report
        - Validate.to_code
        - Validate.to_yaml
        - Validate.suggest_improvements
        - Validate.from_prompt
        - Validate.get_sundered_data
        - Validate.get_data_extracts
        - Validate.all_passed
        - Validate.assert_passing
        - Validate.assert_below_threshold
        - Validate.assert_dimension_scores
        - Validate.above_threshold
        - Validate.get_dimension_scores
        - Validate.get_health_score
        - Validate.get_scorecard
        - Validate.n
        - Validate.n_passed
        - Validate.n_failed
        - Validate.f_passed
        - Validate.f_failed
        - Validate.warning
        - Validate.error
        - Validate.critical

    - title: Inspection and Assistance
      desc: >
        Functions for getting to grips with a new data table. Use `DataScan` for a quick overview,
        `preview()` for first/last rows, `col_summary_tbl()` for column summaries, and
        `missing_vals_tbl()` for missing value analysis.
      contents:
        - DataScan
        - preview
        - col_summary_tbl
        - missing_vals_tbl
        - load_dataset
        - get_data_path
        - connect_to_table
        - print_database_tables

    - title: Table Pre-checks
      desc: >
        Helper functions for use with the `active=` parameter of validation methods. These inspect
        the target table before a step runs and conditionally skip the step when preconditions are
        not met.
      contents:
        - has_columns
        - has_rows

    - title: YAML
      desc: >
        Functions for using YAML to orchestrate validation workflows.
      contents:
        - yaml_interrogate
        - validate_yaml
        - yaml_to_python

    - title: Utility Functions
      desc: >
        Functions for accessing metadata about the target data and managing configuration.
      contents:
        - get_column_count
        - get_row_count
        - get_action_metadata
        - get_validation_summary
        - write_file
        - read_file
        - ref

    - title: Test Data Generation
      desc: >
        Generate synthetic test data based on schema definitions. Use `generate_dataset()` to create
        data from a Schema object, or `schema_from_tbl()` to infer a generation-ready schema from an
        existing table (Polars, Pandas, or Ibis/DuckDB).
      contents:
        - generate_dataset
        - schema_from_tbl
        - int_field
        - float_field
        - string_field
        - bool_field
        - date_field
        - datetime_field
        - time_field
        - duration_field
        - profile_fields

    - title: Prebuilt Actions
      desc: >
        Prebuilt action functions for common notification patterns.
      contents:
        - send_slack_notification
        - emit_otel

    - title: Metadata Import/Export
      desc: >
        Import variable-level metadata from external data standards files (CDISC Define-XML,
        Controlled Terminology, SPSS `.sav`, SAS XPORT, Stata `.dta`, and more) and export metadata
        to various formats. Use `import_metadata()` as the entry point and `export_metadata()` for
        the reverse.
      contents:
        - import_metadata
        - export_metadata
        - name: MetadataImport
          members: true
        - name: MetadataPackage
          members: true
        - name: VariableMetadata
          members: true
        - name: Codelist
          members: true
        - name: CodelistEntry
          members: true
        - name: MissingValueCode
          members: true

    - title: SDTM Validation
      desc: >
        Validate clinical datasets against CDISC SDTM domain templates. Use `validate_sdtm()` to
        generate a full `Validate` workflow, or `validate_sdtm_structure()` for a quick structural
        conformance check. Retrieve domain templates with `get_sdtm_domain()` and
        `list_sdtm_domains()`.
      contents:
        - validate_sdtm
        - validate_sdtm_structure
        - sdtm_to_metadata
        - get_sdtm_domain
        - list_sdtm_domains
        - name: SDTMDomainTemplate
          members: true
        - name: SDTMVariableSpec
          members: true

    - title: ADaM Validation
      desc: >
        Validate analysis datasets against CDISC ADaM templates. Use `validate_adam()` to generate a
        full `Validate` workflow, or `validate_adam_structure()` for a quick structural conformance
        check. Retrieve dataset templates with `get_adam_dataset()` and `list_adam_datasets()`.
      contents:
        - validate_adam
        - validate_adam_structure
        - adam_to_metadata
        - get_adam_dataset
        - list_adam_datasets
        - name: ADaMDatasetTemplate
          members: true
        - name: ADaMVariableSpec
          members: true

    - title: Integrations
      desc: >
        Classes for integrating Pointblank with external observability and monitoring systems. Use
        `OTelExporter` to export validation results as OpenTelemetry metrics, traces, and logs.
      contents:
        - name: integrations.otel.OTelExporter
          members: true