Provenance API Reference

This section provides detailed API documentation for the provenance tracking system in MetricEngine.

Core Classes

class metricengine.provenance.Provenance(id, op, inputs, meta)

Bases: object

Immutable provenance record for financial value calculations.

id: str

op: str

inputs: tuple[str, ...]

meta: frozendict[str, Any]

Configuration

class metricengine.provenance_config.ProvenanceConfig(enabled=True, track_literals=True, track_operations=True, track_calculations=True, fail_on_error=False, log_errors=True, log_level=30, max_history_depth=1000, enable_spans=True, enable_id_interning=True, max_hash_cache_size=10000, enable_weak_refs=False, max_graph_size=10000, enable_history_truncation=True, debug_mode=False, include_stack_traces=False)

Bases: object

Configuration for provenance tracking behavior.

enabled: bool = True

track_literals: bool = True

track_operations: bool = True

track_calculations: bool = True

fail_on_error: bool = False

log_errors: bool = True

log_level: int = 30

max_history_depth: int = 1000

enable_spans: bool = True

enable_id_interning: bool = True

max_hash_cache_size: int = 10000

enable_weak_refs: bool = False

max_graph_size: int = 10000

enable_history_truncation: bool = True

debug_mode: bool = False

include_stack_traces: bool = False

Configuration Functions

metricengine.provenance_config.get_config()

Get the current provenance configuration.

Returns the context-specific configuration if set, otherwise the global configuration.

Return type:

ProvenanceConfig

Returns:

Current ProvenanceConfig instance

metricengine.provenance_config.set_global_config(config)

Set the global provenance configuration.

Parameters:

config (ProvenanceConfig) – New global configuration

Return type:

None

metricengine.provenance_config.update_global_config(**kwargs)

Update specific fields in the global configuration.

Parameters:

**kwargs (Any) – Configuration fields to update

Return type:

None

metricengine.provenance_config.enable_provenance()

Enable provenance tracking globally.

Return type:

None

metricengine.provenance_config.disable_provenance()

Disable all provenance tracking globally.

Return type:

None

metricengine.provenance_config.set_performance_mode()

Configure for performance-critical environments.

Disables expensive features while maintaining basic provenance tracking.

Return type:

None

metricengine.provenance_config.set_debug_mode()

Configure for debugging and development.

Enables all features and detailed error reporting.

Return type:

None

Context Manager

class metricengine.provenance_config.provenance_config(**kwargs)

Bases: object

Context manager for temporary configuration changes.

Example

>>> with provenance_config(enabled=False):
...     # Provenance tracking disabled in this block
...     result = FinancialValue(100) + FinancialValue(50)
>>> # Provenance tracking restored to previous state

Utility Functions

metricengine.provenance_config.should_track_provenance()

Check if provenance tracking is currently enabled.

Return type:

bool

Returns:

True if provenance should be tracked, False otherwise

metricengine.provenance_config.should_track_literals()

Check if literal provenance tracking is enabled.

Return type:

bool

Returns:

True if literal provenance should be tracked, False otherwise

metricengine.provenance_config.should_track_operations()

Check if operation provenance tracking is enabled.

Return type:

bool

Returns:

True if operation provenance should be tracked, False otherwise

metricengine.provenance_config.should_track_calculations()

Check if calculation provenance tracking is enabled.

Return type:

bool

Returns:

True if calculation provenance should be tracked, False otherwise

metricengine.provenance_config.is_provenance_available()

Check if provenance tracking is available and functional.

Return type:

bool

Returns:

True if provenance can be used, False if it should be disabled

metricengine.provenance_config.log_provenance_error(error, context='', **metadata)

Log a provenance-related error with appropriate detail level.

Parameters:

• error (Exception) – The exception that occurred

• context (str) – Additional context about where the error occurred

• **metadata (Any) – Additional metadata to include in the log

Return type:

None

Hashing Functions

metricengine.provenance.hash_literal(value, policy)

Generate stable hash for literal values.

Parameters:

• value (Decimal | None) – The literal value (Decimal or None)

• policy (Policy) – The policy context for the value

Return type:

str

Returns:

SHA-256 hash string for the literal

Raises:

Exception – Only if fail_on_error is True in configuration

metricengine.provenance.hash_node(op, parents, policy, meta=None)

Generate stable hash for operation nodes.

Parameters:

• op (str) – Operation identifier (e.g., “+”, “-”, “calc:margin”)

• parents (tuple[FinancialValue, ...]) – Parent FinancialValue instances

• policy (Policy) – Policy context for the operation

• meta (dict | None) – Optional metadata dictionary

Return type:

str

Returns:

SHA-256 hash string for the operation node

Raises:

Exception – Only if fail_on_error is True in configuration

Export Functions

metricengine.provenance.to_trace_json(fv)

Export complete provenance graph as JSON-serializable dictionary.

This function creates a complete JSON representation of the provenance graph that can be serialized, stored, or transmitted. The format includes a root node identifier and a nodes dictionary containing all provenance records.

Parameters:

fv (FinancialValue) – FinancialValue to export provenance graph from

Return type:

dict[str, Any]

Returns:

Dictionary with ‘root’ and ‘nodes’ keys containing the complete graph

Example

>>> revenue = FinancialValue(1000)
>>> cost = FinancialValue(600)
>>> profit = revenue - cost
>>> trace = to_trace_json(profit)
>>> print(trace['root'])  # profit provenance ID
>>> print(len(trace['nodes']))  # 3 nodes

metricengine.provenance.explain(fv, max_depth=10)

Generate human-readable explanation of calculation.

This function creates a formatted text representation of how a FinancialValue was calculated, showing the operation tree in a readable format. This is useful for debugging and understanding complex calculations.

Parameters:

• fv (FinancialValue) – FinancialValue to explain

• max_depth (int) – Maximum depth to traverse (prevents infinite recursion)

Return type:

str

Returns:

Human-readable string explaining the calculation

Example

>>> revenue = FinancialValue(1000)
>>> cost = FinancialValue(600)
>>> profit = revenue - cost
>>> print(explain(profit))
# Result (400.00):
#   Operation: -
#   Left: 1000.00 (literal)
#   Right: 600.00 (literal)

metricengine.provenance.get_provenance_graph(fv)

Extract complete provenance graph as dictionary.

This function traverses the complete provenance graph starting from the given FinancialValue and returns a dictionary mapping provenance IDs to their Provenance records. This is useful for analysis and debugging of calculation lineage.

Note: This implementation can only traverse the provenance records that are directly accessible from the root FinancialValue. In the current architecture, we don’t maintain a global provenance store, so we can only include the root provenance record. A full implementation would require either: 1. A global provenance registry, or 2. Maintaining references to parent FinancialValue instances

Parameters:

fv (FinancialValue) – FinancialValue to extract provenance graph from

Return type:

dict[str, Provenance]

Returns:

Dictionary mapping provenance IDs to Provenance records

Example

>>> revenue = FinancialValue(1000)
>>> cost = FinancialValue(600)
>>> profit = revenue - cost
>>> graph = get_provenance_graph(profit)
>>> print(len(graph))  # 1 (only profit, as we can't traverse to inputs)
>>> print(list(graph.keys()))  # ['profit_id']

Span Management

metricengine.provenance.calc_span(name, **attrs)

Context manager for grouping calculations under a named span.

This context manager allows grouping related financial calculations under a named span, which will be included in the provenance metadata of all operations performed within the span context.

Parameters:

• name (str) – Name of the calculation span

• **attrs – Additional attributes to associate with the span

Yields:

None

Return type:

Generator[None, None, None]

Example

>>> with calc_span("quarterly_analysis", quarter="Q1", year=2024):
...     revenue = FinancialValue(1000)
...     cost = FinancialValue(600)
...     profit = revenue - cost  # Will include span info in provenance

>>> prov = profit.get_provenance()
>>> print(prov.meta.get("span"))  # "quarterly_analysis"
>>> print(prov.meta.get("span_attrs"))  # {"quarter": "Q1", "year": 2024}

FinancialValue Provenance Methods

The following methods are added to the metricengine.value.FinancialValue class for provenance access:

FinancialValue.has_provenance()

Check if this FinancialValue has provenance information.

Returns:

True if provenance is available, False otherwise

Return type:

bool

FinancialValue.get_provenance()

Get the provenance record for this FinancialValue.

Returns:

The provenance record, or None if not available

Return type:

Provenance or None

Raises:

ValueError if provenance is not available

FinancialValue.get_operation()

Get the operation type that created this FinancialValue.

Returns:

Operation type string (e.g., “+”, “calc:gross_margin”, “literal”)

Return type:

str or None

FinancialValue.get_inputs()

Get the provenance IDs of inputs used to create this FinancialValue.

Returns:

Tuple of input provenance IDs

Return type:

tuple[str, …] or None

Examples

Basic Usage

from metricengine import FinancialValue

# Create values with automatic provenance tracking
revenue = FinancialValue(1000)
cost = FinancialValue(600)
margin = revenue - cost

# Access provenance information
if margin.has_provenance():
    prov = margin.get_provenance()
    print(f"Operation: {prov.op}")
    print(f"Inputs: {prov.inputs}")

Configuration

from metricengine.provenance_config import update_global_config, provenance_config

# Global configuration
update_global_config(
    track_literals=False,  # Disable literal tracking
    max_history_depth=500  # Limit history depth
)

# Temporary configuration
with provenance_config(enabled=False):
    # Provenance disabled in this block
    result = expensive_calculation()

Export and Analysis

from metricengine.provenance import to_trace_json, explain

# Export provenance as JSON
trace_data = to_trace_json(result)

# Generate human-readable explanation
explanation = explain(result, max_depth=5)
print(explanation)

Calculation Spans

from metricengine.provenance import calc_span

# Group calculations under a named span
with calc_span("quarterly_analysis", quarter="Q1"):
    revenue = FinancialValue(1000)
    cost = FinancialValue(600)
    margin = revenue - cost

# Span information is included in provenance metadata
prov = margin.get_provenance()
print(prov.meta["span"])  # "quarterly_analysis"

Error Handling

from metricengine.provenance_config import log_provenance_error

try:
    # Some operation that might fail
    result = risky_calculation()
except Exception as e:
    # Log the error with provenance context
    log_provenance_error(e, "risky_calculation", input_value=input_val)
    # Handle the error appropriately
    result = fallback_calculation()

Performance Optimization

from metricengine.provenance_config import set_performance_mode, provenance_config

# Global performance optimization
set_performance_mode()

# Or selective optimization
with provenance_config(
    track_literals=False,
    enable_spans=False,
    max_history_depth=100
):
    # Optimized calculation
    result = performance_critical_calculation()