Repository navigation
Layer-2 metric: claim→claim data lineage (input_claims) - #27
Merged
Merged
Conversation
Adds a worked example of a derived metric — one whose inputs are the values
of upstream claims, not raw rows — and wires the adapter to record the
claim->claim data lineage the gate schema already models (input_claims, T29).
growth_demo/dag.py
* arpu (DEMO-D-013): a second Layer-1 base metric.
* cac_payback_ratio (DEMO-D-020): a Layer-2 metric = arpu / blended_cac.
Its kwargs bind to the two upstream claim nodes, so it has no live input
rows of its own.
hamilton/adapter.py
* track node_name -> emitted claim RecordRef per run; when a metric node's
kwargs are upstream claim-emitting nodes (Hamilton binds a kwarg to the
node of the same name), record those claims as input_claims. Topological
execution guarantees the upstream refs exist by the time the node runs.
This populates issue #6's salvageable nugget on a live edge: a derived metric
lands as payload provenance (no row fingerprint to earn) yet is not orphaned —
it traces back to the claims it was computed from. The reconciliation/republish
machinery now has a claim->claim graph to traverse (refutation contagion is the
natural follow-up).
Tests (tests/integrations/test_layered_metrics.py): the Layer-2 claim's
input_claims == {arpu_rid, cac_rid} and cites == [] (cites is knowledge-only);
payload fingerprint on the derived metric vs registered_input on its Layer-1
sources; ground-truth identity payback == (revenue/new_customers)/cac; and a
guard that flat sibling metrics declare no input_claims. 918 passed.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
…e DAG Adds catalog([modules]) — the interface an ephemeral analyst agent reads to know what measures it can stand on before authoring a new one. Built purely from @tag metadata + the compiled dependency graph (no execution, no data). integrations/hamilton/catalog.py * MeasureSpec: per ik_emit="metric" node — measure name (what you reference in a signature to reuse it), the claim_id it emits (explicit or minted identically to the adapter), metric_field, grain, filters, statement, tier, kind (base|derived), direct_upstream, and derives_from (the upstream deps that are themselves measures — the input_claims edges a derived measure carries). * Catalog: by_name / names / base() / derived() + raw external inputs. * format_catalog: the agent-readable brief. This is the discovery half of "leverage the measures that are there": pair a measure name from the catalog into a new node's signature and the adapter's input_claims wiring gives you claim->claim provenance for free. Dimensions are surfaced per-measure as grain/filters (not yet first-class). Tests (tests/integrations/test_catalog.py): lists all 5 growth_demo measures with ids/grain; flags cac_payback_ratio derived <- (arpu, blended_cac) and the flat siblings base; proves the catalog's advertised claim_id equals the id a run actually emits (no drift); readable render. 922 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
…gonomics gap) An analyst-agent E2E (discover from catalog -> compose a new derived measure -> run over sample data -> verify provenance) confirmed the loop works: the agent composed cac_inflation_ratio = naive_cac / blended_cac from catalog discovery alone, and its emitted claim carried input_claims resolving to exactly the two base measures. But it surfaced one real friction: the catalog told the agent WHAT measures exist, not HOW to author a new tagged node — the ik_* contract lived only in adapter docstrings, so the agent had to read adapter internals. Closes that gap next to discovery: * MEASURE_TAG_REFERENCE — the @tag contract (each ik_* tag, required/optional, one-line description). * authoring_guide() — renders the contract plus the composition rule that matters most: reference an existing measure BY NAME in the new node's signature and the adapter records it as input_claims for free; only compose same-grain measures. * format_catalog(cat, authoring=True) — default render now appends the guide, so the one brief an agent reads covers both discovery and authoring. Tests: authoring guide names the key tags + the by-name/input_claims/same-grain rule; default render is self-contained and the opt-out is honored. 924 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a worked example of a derived metric — one whose inputs are the values of upstream claims, not raw rows — and wires the Hamilton adapter to record the claim→claim data lineage the gate schema already models (
input_claims, T29).This lands the one salvageable nugget from #6 on a live edge. The rest of #6 is superseded by item 7 (the DAG backward walk is the lineage capture, and better — it's override-aware), and its AST-reject-rogue-I/O half conflicts with the "surface, never block" doctrine (the
registered_input→payloaddowngrade already gives the semantic guarantee).The edge a flat DAG can't express
The existing
growth_demometrics (blended_cac,demo_mer,naive_cac) are a flat layer — siblings over shared transforms, each tracing back to data. A Layer-2 metric consumes other metrics' claim values:A derived metric has no live input rows of its own, so it can't earn a row fingerprint — it lands as
payloadprovenance. Without a claim→claim edge that leaves it orphaned.input_claimsis the provenance it carries in place of extracted rows.Changes
examples/growth_demo/dag.pyarpu(DEMO-D-013) — a second Layer-1 base metric (revenue / new customers).cac_payback_ratio(DEMO-D-020) — Layer-2:arpu / blended_cac; kwargs bind to the two upstream claim nodes.integrations/hamilton/adapter.pynode_name → emitted-claim RecordRefper run. When a metric node's kwargs are upstream claim-emitting nodes (Hamilton binds a kwarg to the node of the same name), record those claims asinput_claims. Topological execution guarantees the upstream refs exist by the time the node runs. Populates the existing schema field (check_input_claims_exist-enforced) — nothing new on the record type.input_claims, notcites—citesis knowledge-provenance only (research/skill_use), and the gate rejects a claim there.Tests —
tests/integrations/test_layered_metrics.pyinput_claims == {arpu_rid, cac_rid};cites == [].data_fingerprint_source == "payload"on the derived metric vsregistered_inputon its Layer-1 sourcearpu— the contrast is the point.cac_payback_ratio == (revenue / new_customers) / cac.input_claims(adapter doesn't over-attach).918 passed, 1 deselected; ruff clean on touched files.
Follow-up this unlocks
With claim→claim edges present, the republish guard's question extends from "was this exact claim refuted?" to "does this claim derive from anything refuted?" — refutation contagion, now a real graph traversal rather than an unexpressible one. Left as a separate change.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
Generated by Claude Code