relationalai 0.13.0__py3-none-any.whl → 0.13.0.dev0__py3-none-any.whl

relationalai/semantics/std/decimals.py

@@ -1,62 +1,55 @@
 from __future__ import annotations
-from typing import cast
-from decimal import Decimal as PyDecimal
-from relationalai.semantics.metamodel import ir, types
-from relationalai.semantics.internal import internal as b
-from .std import _make_expr
+
+from ..frontend.base import Concept, NumberConcept, Expression, Variable
+
+from . import NumberValue, numbers, _deprecated_library
+
 
 #--------------------------------------------------
 # Constructors
 #--------------------------------------------------
 
-def decimal(value: b.Producer|int|float|PyDecimal, precision=38, scale=14) -> b.Expression:
-    """
-    Create an expression that represents a decimal with this value, precision and scale.
-    """
-    if isinstance(value, int):
-        value = PyDecimal(str(value))
-    if isinstance(value, float):
-        value = PyDecimal(str(value))
-    return b.ConceptMember(b.decimal_concept(precision, scale), value, {})
-
-def parse_decimal(value: b.Producer|str, precision=38, scale=14) -> b.Expression:
-    """
-    Create an expression that represents parsing this string value as a decimal with this
-    precision and scale.
-    """
-    return _make_expr("parse_decimal", value, b.decimal_concept(precision, scale).ref("res"))
-
-def parse(value: b.Producer|str, decimal: b.Concept) -> b.Expression:
-    """
-    Create an expression that represents parsing this string value as a decimal with the
-    precision and scale of the decimal argument.
-    """
-    return parse_decimal(value, precision(decimal), scale(decimal))
+def decimal(value: NumberValue, precision=38, scale=14) -> Variable:
+    _warning(f"numbers.number({value}, {precision}, {scale})")
+    return numbers.number(value, precision, scale)
+
+def parse_decimal(value: str, precision=38, scale=14) -> Expression:
+    _warning(f"numbers.parse_number({value}, {precision}, {scale})")
+    return numbers.parse_number(value, precision, scale)
+
+def parse(value: str, decimal: Concept) -> Expression:
+    assert isinstance(decimal, NumberConcept)
+    _warning(f"numbers.parse({value}, {decimal})")
+    return numbers.parse(value, decimal)
+
+#--------------------------------------------------
+# Decimal information
+#--------------------------------------------------
+
+def is_decimal(decimal: Concept) -> bool:
+    assert isinstance(decimal, NumberConcept)
+    _warning(f"numbers.is_number({decimal})")
+    return numbers.is_number(decimal)
+
+def precision(decimal: Concept) -> int:
+    assert isinstance(decimal, NumberConcept)
+    _warning(f"numbers.precision({decimal})")
+    return numbers.precision(decimal)
+
+def scale(decimal: Concept) -> int:
+    assert isinstance(decimal, NumberConcept)
+    _warning(f"numbers.scale({decimal})")
+    return numbers.scale(decimal)
+
+def size(decimal: Concept) -> int:
+    assert isinstance(decimal, NumberConcept)
+    _warning(f"numbers.size({decimal})")
+    return numbers.size(decimal)
+
 
 #--------------------------------------------------
-# Decimal information.
+# Implementation
 #--------------------------------------------------
 
-def is_decimal(decimal: b.Concept) -> bool:
-    return b.is_decimal(decimal)
-
-def precision(decimal: b.Concept) -> int:
-    """ Assuming the concept represents a decimal, return its precision. """
-    assert b.is_decimal(decimal)
-    typ = cast(ir.DecimalType, types.decimal_by_type_str(decimal._name))
-    return typ.precision
-
-def scale(decimal: b.Concept) -> int:
-    """ Assuming the concept represents a decimal, return its scale. """
-    assert b.is_decimal(decimal)
-    typ = cast(ir.DecimalType, types.decimal_by_type_str(decimal._name))
-    return typ.scale
-
-def size(decimal: b.Concept) -> int:
-    """
-    Assuming the concept represents a decimal, return its size, i.e. the number of bits
-    needed to represent the decimal.
-    """
-    assert b.is_decimal(decimal)
-    typ = cast(ir.DecimalType, types.decimal_by_type_str(decimal._name))
-    return types.digits_to_bits(typ.precision)
+def _warning(example: str):
+    _deprecated_library("std.decimals", "std.numbers", example)

relationalai/semantics/std/floats.py

@@ -1,7 +1,15 @@
-from __future__ import annotations
+from . import StringValue
+from ..frontend.base import Library, Expression, Field, Value
+from ..frontend.core import Float, String, Number
+from decimal import Decimal as PyDecimal
 
-from relationalai.semantics.internal import internal as b
-from .std import _make_expr
+# the front-end library object
+library = Library("floats")
 
-def parse_float(value: b.Producer|str) -> b.Expression:
-    return _make_expr("parse_float", value, b.Float.ref("res"))
+_parse_float = library.Relation("parse_float", [Field.input("value", String), Field("result", Float)])
+
+def float(value: Value) -> Expression:
+    return Float(value)
+
+def parse_float(value: StringValue) -> Expression:
+    return _parse_float(value)

relationalai/semantics/std/integers.py

@@ -1,22 +1,37 @@
 from __future__ import annotations
 
-from relationalai.semantics.internal import internal as b
-from .std import _make_expr
+from ..frontend.base import Expression, Variable
+from ..frontend.core import Integer
+
+from . import StringValue, IntegerValue, numbers, _deprecated_library
+
 
 # Coerce a number to Int64.
-def int64(value: b.Producer|int) -> b.ConceptMember:
-    return b.ConceptMember(b.Int64, value, {})
+def int64(value: IntegerValue) -> Variable:
+    _warning()
+    return Integer(value)
 
 # Coerce a number to Int128.
-def int128(value: b.Producer|int) -> b.ConceptMember:
-    return b.ConceptMember(b.Int128, value, {})
+def int128(value: IntegerValue) -> Variable:
+    _warning()
+    return Integer(value)
 
-def parse_int64(value: b.Producer|str) -> b.Expression:
-    return _make_expr("parse_int64", value, b.Int64.ref("res"))
+def parse_int64(value: StringValue) -> Expression:
+    _warning(f"numbers.parse_number({value}, , 0)")
+    return numbers.parse_number(value, 19, 0)
 
-def parse_int128(value: b.Producer|str) -> b.Expression:
-    return _make_expr("parse_int128", value, b.Int128.ref("res"))
+def parse_int128(value: StringValue) -> Expression:
+    _warning(f"numbers.parse_number({value}, 38, 0)")
+    return numbers.parse_number(value, 38, 0)
 
 # Alias parse_int128 to parse
-def parse(value: b.Producer|str) -> b.Expression:
+def parse(value: StringValue) -> Expression:
     return parse_int128(value)
+
+
+#--------------------------------------------------
+# Implementation
+#--------------------------------------------------
+
+def _warning(msg: str|None = None):
+    _deprecated_library("std.integers", "std.numbers", msg)

relationalai/semantics/std/math.py

@@ -1,141 +1,212 @@
 from __future__ import annotations
 
-from relationalai.semantics.internal import internal as b
-from .std import _Number, _make_expr
-from math import pi
-
-def abs(value: _Number) -> b.Expression:
-    return _make_expr("abs", value, b.Number.ref("res"))
-
-def natural_log(value: _Number) -> b.Expression:
-    return _make_expr("natural_log", value, b.Number.ref("res"))
-
-def log(value: _Number, base: _Number | None = None) -> b.Expression:
+from . import NumberValue, FloatValue, _get_number_value
+from ..frontend.base import Library, Expression, Field
+from ..frontend.core import Numeric, Number, Integer, Float, make_overloads, minus, mul, div, power
+
+# the front-end library object
+library = Library("math")
+
+# ------------------------------
+# Basics
+# ------------------------------
+_abs = library.Relation("abs", [Field.input("value", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 2))
+_ceil = library.Relation("ceil", [Field.input("value", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 2))
+_clip = library.Relation("clip", [Field.input("value", Numeric), Field.input("lower", Numeric), Field.input("upper", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 4))
+_factorial = library.Relation("factorial", [Field.input("value", Integer), Field("result", Integer)])
+_floor = library.Relation("floor", [Field.input("value", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 2))
+_isclose = library.Relation("isclose", [Field.input("tolerance", Numeric), Field.input("x", Numeric), Field.input("y", Numeric)], overloads=make_overloads([Number, Float], 3))
+_sign = library.Relation("sign", [Field.input("x", Numeric), Field("result", Integer)], overloads=[[Number, Integer], [Float, Integer]])
+_trunc_divide = library.Relation("trunc_divide", [Field.input("numerator", Number), Field.input("denominator", Number), Field("result", Number)])
+_maximum = library.Relation("maximum", [Field.input("left", Numeric), Field.input("right", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 3))
+_minimum = library.Relation("minimum", [Field.input("left", Numeric), Field.input("right", Numeric), Field("result", Numeric)], overloads=make_overloads([Number, Float], 3))
+_isinf = library.Relation("isinf", [Field.input("value", Float)])
+_isnan = library.Relation("isnan", [Field.input("value", Float)])
+
+def abs(value: NumberValue) -> Expression:
+    return _abs(value)
+
+def ceil(value: NumberValue) -> Expression:
+    return _ceil(value)
+
+def clip(value: NumberValue, lower: NumberValue, upper: NumberValue) -> Expression:
+    # CLIP = CLAMP(v,min,max) = LEAST(max,GREATEST(min,v))
+    return _clip(lower, upper, value)
+
+def factorial(value: NumberValue) -> Expression:
+    v = _get_number_value(value)
+    if v is not None and v < 0:
+        raise ValueError("Cannot take the factorial of a negative number")
+    return _factorial(value)
+
+def floor(value: NumberValue) -> Expression:
+    return _floor(value)
+
+def isclose(x: NumberValue, y: NumberValue, tolerance: NumberValue = 1e-9) -> Expression:
+    # APPROX_EQUAL = ABS(x - y) < tolerance
+    return _isclose(tolerance, x, y)
+
+def sign(x: NumberValue) -> Expression:
+    return _sign(x)
+
+def trunc_divide(numerator: NumberValue, denominator: NumberValue) -> Expression:
+    return _trunc_divide(numerator, denominator)
+
+def maximum(left: NumberValue, right: NumberValue) -> Expression:
+    # GREATEST
+    return _maximum(left, right)
+
+def minimum(left: NumberValue, right: NumberValue) -> Expression:
+    # LEAST
+    return _minimum(left, right)
+
+def isinf(value: FloatValue) -> Expression:
+    return _isinf(value)
+
+def isnan(value: FloatValue) -> Expression:
+    return _isnan(value)
+
+# -------------------------------
+# Power and Logarithmic Functions
+# -------------------------------
+
+_cbrt = library.Relation("cbrt", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_sqrt = library.Relation("sqrt", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_exp = library.Relation("exp", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_power = library.Relation("power", [Field.input("base", Numeric), Field.input("exponent", Numeric), Field("result", Float)],
+                          overloads=[
+                              #[Number, Number, Float], # v0 and engines are not handling this correctly
+                              [Float, Float, Float]])
+_log = library.Relation("log", [Field.input("base", Numeric), Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Number, Float], [Float, Float, Float]])
+_natural_log = library.Relation("natural_log", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+
+def cbrt(value: NumberValue) -> Expression:
+    return _cbrt(value)
+
+def sqrt(value: NumberValue) -> Expression:
+    v = _get_number_value(value)
+    if v is not None and v < 0:
+        raise ValueError("Cannot take the square root of a negative number")
+    return _sqrt(value)
+
+def exp(value: NumberValue) -> Expression:
+    return _exp(value)
+
+def pow(base: NumberValue, exponent: NumberValue) -> Expression:
+    return _power(base, exponent)
+
+def natural_log(value: NumberValue) -> Expression:
+    return _natural_log(value)
+
+def log(x: NumberValue, base: NumberValue | None = None) -> Expression:
+    v = _get_number_value(x)
+    if v is not None and v <= 0:
+        raise ValueError("Cannot take the logarithm of a non-positive number")
     if base is None:
-        return _make_expr("natural_log", value, b.Number.ref("res"))
-    return _make_expr("log", base, value, b.Number.ref("res"))
-
-def log2(value: _Number) -> b.Expression:
-    return _make_expr("log", 2, value, b.Number.ref("res"))
-
-def log10(value: _Number) -> b.Expression:
-    return _make_expr("log10", value, b.Number.ref("res"))
-
-def sqrt(value: _Number) -> b.Expression:
-    return _make_expr("sqrt", value, b.Float.ref("res"))
-
-def maximum(left: _Number, right: _Number) -> b.Expression:
-    return _make_expr("maximum", left, right, b.Number.ref("res"))
-
-def minimum(left: _Number, right: _Number) -> b.Expression:
-    return _make_expr("minimum", left, right, b.Number.ref("res"))
-
-def isinf(value: _Number) -> b.Expression:
-    return _make_expr("isinf", value)
-
-def isnan(value: _Number) -> b.Expression:
-    return _make_expr("isnan", value)
-
-def ceil(value: _Number) -> b.Expression:
-    return _make_expr("ceil", value, b.Number.ref("res"))
-
-def floor(value: _Number) -> b.Expression:
-    return _make_expr("floor", value, b.Number.ref("res"))
-
-def pow(base: _Number, exponent: _Number) -> b.Expression:
-    return _make_expr("pow", base, exponent, b.Float.ref("res"))
+        return natural_log(x)
+    return _log(base, x)
 
-def cbrt(value: _Number) -> b.Expression:
-    return _make_expr("cbrt", value, b.Float.ref("res"))
+def log2(value: NumberValue) -> Expression:
+    return log(value, 2)
 
-def factorial(value: _Number) -> b.Expression:
-    return _make_expr("factorial", value, b.Number.ref("res"))
+def log10(value: NumberValue) -> Expression:
+    return log(value, 10)
 
-def cos(value: _Number) -> b.Expression:
-    return _make_expr("cos", value, b.Float.ref("res"))
 
-def cosh(value: _Number) -> b.Expression:
-    return _make_expr("cosh", value, b.Float.ref("res"))
 
-def acos(value: _Number) -> b.Expression:
-    return _make_expr("acos", value, b.Float.ref("res"))
+# ------------------------------
+# Trigonometry
+# ------------------------------
 
-def acosh(value: _Number) -> b.Expression:
-    return _make_expr("acosh", value, b.Float.ref("res"))
+_degrees = library.Relation("degrees", [Field.input("radians", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_radians = library.Relation("radians", [Field.input("degrees", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_cos = library.Relation("cos", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_sin = library.Relation("sin", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_tan = library.Relation("tan", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_cot = library.Relation("cot", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_acos = library.Relation("acos", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_asin = library.Relation("asin", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_atan = library.Relation("atan", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_acot = library.Relation("acot", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_cosh = library.Relation("cosh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_sinh = library.Relation("sinh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_tanh = library.Relation("tanh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_acosh = library.Relation("acosh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_asinh = library.Relation("asinh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_atanh = library.Relation("atanh", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
 
-def sin(value: _Number) -> b.Expression:
-    return _make_expr("sin", value, b.Float.ref("res"))
+def degrees(radians: NumberValue) -> Expression:
+    return _degrees(radians)
 
-def sinh(value: _Number) -> b.Expression:
-    return _make_expr("sinh", value, b.Float.ref("res"))
+def radians(degrees: NumberValue) -> Expression:
+    return _radians(degrees)
 
-def asin(value: _Number) -> b.Expression:
-    return _make_expr("asin", value, b.Float.ref("res"))
+def cos(value: NumberValue) -> Expression:
+    return _cos(value)
 
-def asinh(value: _Number) -> b.Expression:
-    return _make_expr("asinh", value, b.Float.ref("res"))
+def sin(value: NumberValue) -> Expression:
+    return _sin(value)
 
-def tan(value: _Number) -> b.Expression:
-    return _make_expr("tan", value, b.Float.ref("res"))
+def tan(value: NumberValue) -> Expression:
+    return _tan(value)
 
-def tanh(value: _Number) -> b.Expression:
-    return _make_expr("tanh", value, b.Float.ref("res"))
+def cot(value: NumberValue) -> Expression:
+    return _cot(value)
 
-def atan(value: _Number) -> b.Expression:
-    return _make_expr("atan", value, b.Float.ref("res"))
+def acos(value: NumberValue) -> Expression:
+    return _acos(value)
 
-def atanh(value: _Number) -> b.Expression:
-    return _make_expr("atanh", value, b.Float.ref("res"))
+def asin(value: NumberValue) -> Expression:
+    return _asin(value)
 
-def cot(value: _Number) -> b.Expression:
-    return _make_expr("cot", value, b.Float.ref("res"))
+def atan(value: NumberValue) -> Expression:
+    return _atan(value)
 
-def acot(value: _Number) -> b.Expression:
-    return _make_expr("acot", value, b.Float.ref("res"))
+def acot(value: NumberValue) -> Expression:
+    return _acot(value)
 
-def degrees(value: _Number) -> b.Expression:
-    divisor = pi / 180.0
-    return _make_expr("/", value, divisor, b.Float.ref("res"))
+def cosh(value: NumberValue) -> Expression:
+    return _cosh(value)
 
-def radians(value: _Number) -> b.Expression:
-    divisor = 180.0 / pi
-    return _make_expr("/", value, divisor, b.Float.ref("res"))
+def sinh(value: NumberValue) -> Expression:
+    return _sinh(value)
 
-def exp(value: _Number) -> b.Expression:
-    return _make_expr("exp", value, b.Float.ref("res"))
+def tanh(value: NumberValue) -> Expression:
+    return _tanh(value)
 
-def erf(value: _Number) -> b.Expression:
-    return _make_expr("erf", value, b.Float.ref("res"))
+def acosh(value: NumberValue) -> Expression:
+    v = _get_number_value(value)
+    if v is not None and v < 1:
+        raise ValueError("acosh expects a value greater than or equal to 1.")
+    return _acosh(value)
 
-def erfinv(value: _Number) -> b.Expression:
-    return _make_expr("erfinv", value, b.Float.ref("res"))
+def asinh(value: NumberValue) -> Expression:
+    return _asinh(value)
 
-def haversine(x1: _Number, y1: _Number, x2: _Number, y2: _Number, r: _Number) -> b.Expression:
-    # 2 * r * asin[sqrt[sin[(x2 - x1)/2] ^ 2 + cos[x1] * cos[x2] * sin[(y2 - y1) / 2] ^ 2]]
-    # sin[(x2 - x1)/2] ^ 2
-    x_diff = _make_expr("-", x2, x1, b.Float.ref("x_diff"))
-    x_diff2 = _make_expr("/", x_diff, 2.0, b.Float.ref("x_diff2"))
-    sin_x_diff = _make_expr("sin", x_diff2, b.Float.ref("sin_x_diff"))
-    sin_x_pow = _make_expr("pow", sin_x_diff, 2.0, b.Float.ref("sin_x_pow"))
+def atanh(value: NumberValue) -> Expression:
+    v = _get_number_value(value)
+    if v is not None and (v <= -1 or v >= 1):
+        raise ValueError("atanh expects a value between -1 and 1, exclusive.")
+    return _atanh(value)
 
-    # cos[x1] * cos[x2]
-    cos_x1 = _make_expr("cos", x1, b.Float.ref("cos_x1"))
-    cos_x2 = _make_expr("cos", x2, b.Float.ref("cos_x2"))
-    cos_x1_x2 = _make_expr("*", cos_x1, cos_x2, b.Float.ref("cos_x1_x2"))
+# ------------------------------
+# Special Functions
+# ------------------------------
+_erf = library.Relation("erf", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
+_erfinv = library.Relation("erfinv", [Field.input("value", Numeric), Field("result", Float)], overloads=[[Number, Float], [Float, Float]])
 
-    # sin[(y2 - y1) / 2] ^ 2
-    y_diff = _make_expr("-", y2, y1, b.Float.ref("y_diff"))
-    y_diff2 = _make_expr("/", y_diff, 2.0, b.Float.ref("y_diff2"))
-    sin_y_diff = _make_expr("sin", y_diff2, b.Float.ref("sin_y_diff"))
-    sin_y_pow = _make_expr("pow", sin_y_diff, 2.0, b.Float.ref("sin_y_pow"))
+def erf(value: NumberValue) -> Expression:
+    return _erf(value)
 
-    # cos[x1] * cos[x2] * sin[(y2 - y1) / 2] ^ 2
-    prod = _make_expr("*", cos_x1_x2, sin_y_pow, b.Float.ref("prod"))
-    # sin[(x2 - x1)/2] ^ 2 + cos[x1] * cos[x2] * sin[(y2 - y1) / 2] ^ 2
-    prod_sum = _make_expr("+", sin_x_pow, prod, b.Float.ref("prod_sum"))
+def erfinv(value: NumberValue) -> Expression:
+    v = _get_number_value(value)
+    if v is not None and (v < -1 or v > 1):
+        raise ValueError("erfinv expects a value between -1 and 1, inclusive.")
+    return _erfinv(value)
 
-    sqrt_val = _make_expr("sqrt", prod_sum, b.Float.ref("sqrt_val"))
-    asin_val = _make_expr("asin", sqrt_val, b.Float.ref("asin_val"))
-    haversine_r = _make_expr("*", r, asin_val, b.Float.ref("haversine_r"))
-    haversine_final = _make_expr("*", haversine_r, 2.0, b.Float.ref("haversine_final"))
-    return haversine_final
+def haversine(lat1: NumberValue, lon1: NumberValue, lat2: NumberValue, lon2: NumberValue, radius: NumberValue = 1.0) -> Expression:
+    # 2 * r * asin[sqrt[sin[(lat2 - lat1)/2] ^ 2 + cos[lat1] * cos[lat2] * sin[(lon2 - lon1) / 2] ^ 2]]
+    return mul(2, radius, _asin(_sqrt(
+        power(_sin(div(minus(lat2, lat1), 2)), 2) +
+        mul(_cos(lat1), _cos(lat2), power(_sin(div(minus(lon2, lon1), 2)), 2))
+    )))

relationalai/semantics/std/numbers.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from . import NumberValue, StringValue
+from .. import literal
+from ..frontend.base import Library, Concept, MetaRef, NumberConcept, Expression, Field, Variable
+from ..frontend.core import Number, String, cast as core_cast
+from decimal import Decimal as PyDecimal
+
+
+# the front-end library object
+library = Library("numbers")
+
+#--------------------------------------------------
+# Constructors
+#--------------------------------------------------
+_parse_number = library.Relation("parse_number", [Field.input("value", String), Field("result", Number)])
+
+def number(value: NumberValue, precision=38, scale=14) -> Variable:
+    """
+    Create an expression that represents a number with this value, precision and scale.
+    """
+    if isinstance(value, Variable):
+        cast_type = Number.size(precision, scale)
+        return core_cast(MetaRef(cast_type), value, cast_type.ref())
+
+    # literals
+    if isinstance(value, int):
+        value = PyDecimal(str(value))
+    if isinstance(value, float):
+        value = PyDecimal(str(value))
+    return literal(value, Number.size(precision, scale))
+
+def parse_number(value: StringValue, precision=38, scale=14) -> Expression:
+    """
+    Create an expression that represents parsing this string value as a number with this
+    precision and scale.
+    """
+    return _parse_number(value, Number.size(precision, scale).ref())
+
+def parse(value: str, number: NumberConcept) -> Expression:
+    """
+    Create an expression that represents parsing this string value as a number with the
+    precision and scale of the number argument.
+    """
+    return parse_number(value, precision(number), scale(number))
+
+#--------------------------------------------------
+# Number information.
+#--------------------------------------------------
+
+def is_number(number: Concept) -> bool:
+    return isinstance(number, NumberConcept)
+
+def precision(number: NumberConcept) -> int:
+    """ Assuming the concept represents a number, return its precision. """
+    return number._precision
+
+def scale(number: NumberConcept) -> int:
+    """ Assuming the concept represents a number, return its scale. """
+    return number._scale
+
+def size(number: NumberConcept) -> int:
+    """
+    Assuming the concept represents a number, return its size, i.e. the number of bits
+    needed to represent the number.
+    """
+    return digits_to_bits(number.precision)
+
+def digits_to_bits(precision)-> int:
+    """
+    Transform from a number of base 10 digits to the number of bits necessary to represent
+    that. If the precision is larger than 38, return None as that is not supported.
+
+    For example, a number with 38 digits requires 128 bits.
+    """
+    if precision <= 2:
+        return 8
+    elif precision <= 4:
+        return 16
+    elif precision <= 9:
+        return 32
+    elif precision <= 18:
+        return 64
+    elif precision <= 38:
+        return 128
+    raise ValueError(f"Invalid numeric precision '{precision}'")