Currency Convert (Explicit)

View as Markdown

A RocketRide filter node that converts monetary facts from one currency to another at an explicitly stated rate and date — the opt-in conversion step of the audit-grade financial extraction node suite.

What it does

Reads structured facts on the answers lane and, for every fact tagged with the configured source currency, computes the value in the target currency using a rate you supply in the configuration. Conversion is never implicit: nothing is fetched from a live foreign-exchange service, and no network access or credentials are involved. This is the counterpart to normalize_facts, which only tags currency and never converts.

The conversion is non-destructive and audit-friendly:

• the original amount and currency are left untouched;
• a converted block (amount + currency) is added;
• a provenance entry records the rate, rate date, and source/target currencies.

All arithmetic uses decimal.Decimal with half-up rounding, so results are exact and reproducible. The node depends only on the Python standard library.

Records that are not fact objects (plain text, bare numbers), facts missing the amount/currency fields, or facts whose currency does not match the configured source are passed through unchanged — the node never drops a record.

Fact-record convention

A "fact" is a JSON object with a numeric amount under amount_field (default amount) and a currency code under currency_field (default currency). An answer payload may be a single fact object or a list of fact objects; other shapes pass through untouched.

Input:

{ "amount": 100, "currency": "EUR" }

Output (source EUR → target USD at rate 1.1, date 2026-06-30):

{
  "amount": 100,
  "currency": "EUR",
  "converted": { "amount": 110.0, "currency": "USD" },
  "provenance": [
    {
      "op": "currency_convert_explicit",
      "rate": 1.1,
      "rate_date": "2026-06-30",
      "source_currency": "EUR",
      "target_currency": "USD"
    }
  ]
}

If the fact already carries a provenance list, the conversion entry is appended so upstream provenance is preserved.

Configuration

Lanes

Lane	In → Out	Behaviour
answers	answers → answers	Converts facts whose currency matches source_currency; all other records pass through unchanged.

Fields

Field	Type	Default	Description
source_currency	string	EUR	Currency code to convert FROM. Only facts tagged with this currency are converted (case-insensitive).
target_currency	string	USD	Currency code to convert TO.
rate	number	1.0	The stated multiplier applied to the source amount (target = source × rate).
rate_date	string	""	The date the rate applies to (ISO 8601). Recorded in the provenance entry.
amount_field	string	amount	The fact field holding the numeric amount to convert.
currency_field	string	currency	The fact field holding the currency code.
decimals	integer	2	Fractional digits for the converted amount (rounded half-up).

If source_currency, target_currency, or rate is missing or invalid, the node logs a warning and passes all answers through unchanged rather than failing the run.

Pipeline position

datalab_parse → extract_facts → normalize_facts → currency_convert_explicit → schema_validate → …

This node is marked experimental.

Schema

Field	Type	Description	Default
currency_convert_explicit.amount_field	string	Amount field The fact field holding the numeric amount to convert.	"amount"
currency_convert_explicit.currency_field	string	Currency field The fact field holding the currency code.	"currency"
currency_convert_explicit.decimals	integer	Rounding decimals Number of fractional digits for the converted amount (rounded half-up).	2
currency_convert_explicit.profile	string	Conversion Explicit currency conversion configuration	"default"
currency_convert_explicit.rate	number	Conversion rate The stated multiplier applied to the source amount (target = source × rate). Supply the rate deliberately; nothing is fetched.	1
currency_convert_explicit.rate_date	string	Rate date The date the rate applies to (ISO 8601, e.g. 2026-06-30). Recorded in the conversion provenance.	""
currency_convert_explicit.source_currency	string	Source currency Currency code to convert FROM (e.g. EUR). Only facts tagged with this currency are converted; case-insensitive.	"EUR"
currency_convert_explicit.target_currency	string	Target currency Currency code to convert TO (e.g. USD).	"USD"