Skip to content

v0.10.0 — Metric Taxonomy and Impact Graph

Choose a tag to compare

View all tags
@flyersworder flyersworder released this 17 Apr 14:37
· 50 commits to main since this release
v0.10.0
fb9c80e

What's New

Metric taxonomy and impact graph — agents can now reason about metric roles (north-star vs team KPI, leading vs lagging) and walk a causal graph between metrics to ground recommendations in evidence. When asked "why did revenue drop?", an agent can follow upstream edges like active_customers → total_revenue (positive, verified): A/B test exp-042, +3.2% lift rather than blindly requerying revenue.

Added

  • Metric role metadata on MetricDefinition: optional domains / tier (north_star / department_kpi / team_kpi) / indicator_kind (leading / lagging). All defaulted — existing contracts parse unchanged.
  • MetricImpact dataclass — directed, annotated edges with direction, confidence (verified / correlated / hypothesized), free-text evidence the agent can cite verbatim. Declared via a top-level metric_impacts: block in the semantic YAML.
  • trace_metric_impacts tool (13th tool) — BFS through the impact graph. direction="upstream" returns drivers (root-cause analysis); direction="downstream" returns affected metrics (action-impact reasoning). max_depth clamped to [1, 10].
  • build_metric_impact_index() and walk_metric_impacts() helpers in semantic.base, mirroring the existing build_relationship_index / find_join_path pattern. Dual-keyed index, cycle-safe BFS.
  • get_metric_impacts() on SemanticSource — YamlSource parses from YAML; DbtSource / CubeSource return [] (impacts live in the contract YAML regardless of where metrics come from — dbt and Cube have no native causal-graph concept).
  • meta.tier / meta.indicator_kind / meta.domains read from each metric's meta dict in DbtSource and CubeSource. String→list coercion for tier / domains is consistent across YAML, dbt, and Cube.
  • Factory validation warnings for unknown metric references in metric_impacts, mirroring the existing domain-reference validation.
  • Public API surface: MetricDefinition, MetricImpact, Relationship, SemanticSource now re-exported from the top-level agentic_data_contracts package.

Changed

  • Tool count: 13 tools (was 12).
  • lookup_metric response enriched with domains, tier, indicator_kind, and citation-ready impacts / impacted_by edges (e.g. "positive impact on total_revenue (verified): A/B test exp-042, +3.2% lift"). Optional fields omitted when empty.
  • list_metrics filters: optional tier and indicator_kind alongside the existing domain filter. Entries include tier and indicator_kind when set.
  • list_metrics domain semantics: filtering now unions contract-side Domain.metrics with self-declared metric.domains. Metrics that self-declare a domain are discoverable via the filter even if the contract's Domain.metrics list doesn't include them.
  • Example (examples/revenue_agent/) demonstrates the new fields, an impact edge, and a trace_metric_impacts step in the demo.

Breaking

  • SemanticSource protocol extension: gains required get_metric_impacts() -> list[MetricImpact]. Custom third-party implementations must add this method (returning [] is fine); without it, isinstance(source, SemanticSource) returns False. All built-in sources (YamlSource, DbtSource, CubeSource) implement it — no migration for users of the built-in sources.

Full Changelog: v0.9.2...v0.10.0

Assets 2
Loading