feat(converters): add Ataccama ONE → OSI catalog importer

[carabaestlein]

Summary

Adds a new converter under converters/ataccama/ that imports metadata from Ataccama ONE into an OSI semantic model, using Ataccama's public Catalog and Data Quality REST APIs.

Given one or more catalog items (selected by URN), it produces a single OSI semantic model: each catalog item becomes a dataset, each catalog attribute becomes a field, business terms become ai_context, and data-quality results plus other governance metadata are attached as ATACCAMA custom extensions.

What it does

• Live REST client — authenticates via OAuth2 client-credentials (short-lived tokens refreshed automatically) and follows the APIs' cursor pagination.
• CLI — ataccama-to-osi, scoped by explicit catalog-item URNs (--urn repeatable, or --urns-file), since Ataccama catalogs hold tens of thousands of items and many are BI artifacts rather than tables.
• Data-quality enrichment — overall, per-dimension, and per-column quality, plus the monitor's configured threshold and active-finding count; on by default, --no-dq skips.
• Opt-in AI warnings — --dq-ai-warnings appends a plain-language caveat to ai_context for datasets Ataccama flags as below quality.
• Library — ataccama_to_osi(bundles, ...) returns an OSI document dict.

Mapping

Ataccama ONE	OSI
CatalogItem	dataset (name de-duplicated if repeated)
CatalogItem.locations + name	dataset.source (best-effort dotted namespace)
CatalogItem.description (rich text)	dataset.description (flattened to plain text)
assigned Terms	ai_context (synonyms + instructions)
CatalogAttribute	field (name → quoted ANSI_SQL identifier)
dataType ∈ {DATE, DATETIME, TIMESTAMP, TIME}	field.dimension.is_time = true (inferred)
DQ overall/dimension quality + threshold + findings	dataset custom_extensions (vendor_name: ATACCAMA) → data.dq
DQ per-attribute quality	field custom_extensions (vendor_name: ATACCAMA) → data.dq
URNs, dataType, columnType, connection/source/stewardship/monitor	custom_extensions (vendor_name: ATACCAMA) → data

Every dataset and field carries a single ATACCAMA custom extension; dq, attribute_urn, etc. are keys inside its data JSON string.

Data quality

DQ results (from the DQ API's latest processing on each item's primary monitor) are included by default:

• Dataset: passed/failed, pass_rate_pct, threshold_pct + below_threshold (the monitor's configured bar), active_findings (0 = none open), per-dimension breakdown, and the DQ results link.
• Field: per-column passed/failed/pass_rate_pct.

Opt-in warnings (--dq-ai-warnings): appends a caveat to a dataset's ai_context so any OSI consumer (not just tools that parse the vendor extension) is told to treat low-quality data with caution.

Scope & intentional deviations from the converter guide

Ataccama's APIs are a catalog/governance/DQ surface, while OSI is an analytics semantic
model, so this converter differs from converters/index.md in three deliberate ways:

1. Import-only (Ataccama → OSI). The public Catalog API can only PATCH description/stewardship/aliases on existing items — it cannot create items, attributes, or relationships — so a faithful OSI → Ataccama export isn't possible.
2. Tests use an Ataccama fixture, not the TPC-DS baseline. TPC-DS is an input only for OSI → Vendor converters; for this Vendor → OSI direction the input is Ataccama data, so a recorded catalog fixture is the correct analog. Output is still validated against the OSI JSON schema.
3. No vendor-enum change. vendor_name is a free-form string per core-spec/spec.md, so ATACCAMA validates without touching the spec. This keeps the PR tooling-only.

Known limitations (see README)

• Metrics — Ataccama has no analytics metrics; none emitted (DQ is an extension, not an OSI metric).
• Data Trust Score / Index — not exposed by the public APIs; not emitted. The converter carries the DQ results and monitor threshold that the APIs do provide.
• Relationships / primary_key / unique_keys — not exposed by the Catalog API.
• source — only a folder hierarchy + originPath are available, not database.schema.table; source is a best-effort dotted namespace, with the authoritative connection/source URNs preserved in extensions.
• Expressions are physical — columns map to quoted identifiers (ANSI_SQL only); derived/aggregated columns are not reconstructed.

Testing

• 29 unit tests, run fully offline against a sanitized catalog fixture (synthetic tenant, host, and identifiers).
• Output validated against core-spec/osi-schema.json plus unique-name and sqlglot SQL-parse checks.

cd converters/ataccama
uv sync --group dev
uv run pytest