lightphe 0.0.12__tar.gz → 0.0.13__tar.gz

{lightphe-0.0.12 → lightphe-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightphe
-Version: 0.0.12
+Version: 0.0.13
 Summary: A Lightweight Partially Homomorphic Encryption Library for Python
 Home-page: https://github.com/serengil/LightPHE
 Author: Sefik Ilkin Serengil
@@ -251,27 +251,6 @@ However, if you tried to multiply ciphertexts with RSA, or xor ciphertexts with
 
 ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. The library supports 3 elliptic curve forms (weierstrass, edwards and koblitz) and 100+ standard elliptic curve configurations.
 
-Building an elliptic curve with LightPHE is very straightforward. Once the curve is initialized, you can perform operations such as point addition and scalar multiplication.
-
-```python
-from lightphe import ECC
-
-forms = ["weierstrass", "edwards", "koblitz"]
-
-# construct an elliptic curve
-ed = ECC(form_name="edwards")
-
-# Base Point
-G = ed.G
-
-_2G = G + G
-_3G = _2G + G
-_5G = _3G + _2G
-
-_20G = 4 * _5G
-_19G = _20G - G
-```
-
 In LightPHE, the [Elliptic Curve ElGamal](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) scheme is implemented, offering a secure and efficient homomorphic encryption option.
 
 ```python
@@ -289,11 +268,108 @@ Each curve in LightPHE has a specific order, which is carefully chosen to balanc
 
 See [`curves`](https://github.com/serengil/LightPHE/tree/master/lightphe/elliptic_curve_forms) page for a list of all supported forms, curves and their details.
 
+### Vector Embeddings and Tensors
+
+LightPHE supports homomorphic encryption on vector embeddings and tensors. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
+
+```python
+# build a cryptosystem
+cs = LightPHE(algorithm_name="Paillier")
+
+# define plain embedding
+tensor = [1.005, 2.05, 3.005, 4.005, -5.05, 6, 7.003, 7.002]
+
+# encrypt vector embedding
+encrypted_tensors = cs.encrypt(tensor)
+
+# restore embedding
+decrypted_tensors = cs.decrypt(encrypted_tensors)
+
+# proof of work
+assert all(abs(original - decrypted) < 1e-2 for original, decrypted in zip(tensor, decrypted_tensors))
+```
+
+Encrypted embeddings retain their homomorphic properties, enabling secure computations on encrypted data without decryption. For example, two embeddings encrypted using a multiplicatively homomorphic algorithm can be multiplied element-wise.
+
+```python
+# build a multiplicatively homomorphic cryptosystem (e.g. RSA)
+cs = LightPHE("RSA")
+
+# define plain embeddings
+t1 = [1.005, 2.05, -3.5, 3.1, -4]
+t2 = [5, 6.2, -7.002, -7.1, 8.02]
+
+# encrypt embeddings
+c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
+
+# perform element-wise homomorphic multiplication
+c3 = c1 * c2
+
+# proof of work
+assert np.allclose(cs.decrypt(c3), [a * b for a, b in zip(t1, t2)], rtol=1e-2)
+```
+
+Similarly, two embeddings encrypted with an additively homomorphic algorithm can be added. Additionally, an encrypted embedding can be multiplied by a constant or a plain embedding.
+
+```python
+# build an additively homomorphic cryptosystem (e.g. Paillier)
+cs = LightPHE("Paillier")
+
+# define plain embeddings
+t1 = [1.005, 2.05, 3.6, 4, 4.02, 3.5]
+t2 = [5, 6.2, 7.5, 8.02, 8.02, 4.5]
+t3 = [1.03, 2.04, 3.05, 7.02, 2.01, 1.06]
+
+# encrypt embeddings
+c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
+
+# perform addition of two encrypted embeddings
+c4 = c1 + c2
+
+# perform scalar multiplication on an embedding
+c5 = 3 * c1
+
+# perform element-wise multiplication between an encrypted embedding and plain embedding
+c6 = c1 * t3  # Encrypted-plaintext multiplication
+
+# proof of work
+assert np.allclose(cs.decrypt(c4), [a + b for a, b in zip(t1, t2)], rtol=1e-2)
+assert np.allclose(cs.decrypt(c5), [a * 3 for a in t1], rtol=1e-2)
+assert np.allclose(cs.decrypt(c6), [a * b for a, b in zip(t1, t3)], rtol=1e-2)
+```
+
+### Vector Similarity Search with PHE
+
+Many machine learning models rely on a two-tower architecture, including facial recognition, reverse image search, recommendation engines, large language models, and more. In this setup, user and item inputs are separately mapped to vector embeddings.
+
+For example, suppose all facial embeddings in your database are encrypted on-prem in advance. When verifying an identity, the attempted facial embedding is generated on an edge device or in the cloud. You can compute the encrypted similarity by performing a dot product between the encrypted vector and the plain vector, ensuring secure comparison without decrypting sensitive data. Only additively homomorphic cryptosystems offer encrypted similarity calculation.
+
+```python
+# build an additively homomorphic cryptosystem (e.g. Paillier)
+cs = LightPHE("Paillier")
+
+# define plain vectors - suppose those are l2 normalized already
+alpha = [7.1, 5.2, 5.3, 2.4, 3.5, 4.6]  # On-prem vector (user tower)
+beta = [5.6, 3.7, 2.8, 4, 0, 5.9]  # Cloud vector (item tower)
+
+# encrypt embedding
+encrypted_alpha = cs.encrypt(alpha)
+
+# dot product of encrypted embedding and plain embedding
+encrypted_cosine_similarity = encrypted_alpha @ beta
+
+# decrypt similarity
+cosine_similarity = cs.decrypt(encrypted_cosine_similarity)[0]
+
+# proof of work
+assert abs(cosine_similarity - sum(x * y for x, y in zip(alpha, beta))) < 1e-2
+```
+
 # Contributing
 
 All PRs are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.
 
-You should be able run `make test` and `make lint` commands successfully before committing. Once a PR is created, GitHub test workflow will be run automatically and unit test results will be available in [GitHub actions](https://github.com/serengil/LightPHE/actions/workflows/tests.yml) before approval. Besides, workflow will evaluate the code with pylint as well.
+You should be able run `make test` and `make lint` commands successfully before committing. Once a PR is created, GitHub test workflow will be run automatically and unit test results will be available in [GitHub actions](https://github.com/serengil/LightPHE/actions/workflows/tests.yml) before approval.
 
 # Support
 

{lightphe-0.0.12 → lightphe-0.0.13}/README.md

@@ -235,27 +235,6 @@ However, if you tried to multiply ciphertexts with RSA, or xor ciphertexts with
 
 ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. The library supports 3 elliptic curve forms (weierstrass, edwards and koblitz) and 100+ standard elliptic curve configurations.
 
-Building an elliptic curve with LightPHE is very straightforward. Once the curve is initialized, you can perform operations such as point addition and scalar multiplication.
-
-```python
-from lightphe import ECC
-
-forms = ["weierstrass", "edwards", "koblitz"]
-
-# construct an elliptic curve
-ed = ECC(form_name="edwards")
-
-# Base Point
-G = ed.G
-
-_2G = G + G
-_3G = _2G + G
-_5G = _3G + _2G
-
-_20G = 4 * _5G
-_19G = _20G - G
-```
-
 In LightPHE, the [Elliptic Curve ElGamal](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) scheme is implemented, offering a secure and efficient homomorphic encryption option.
 
 ```python
@@ -273,11 +252,108 @@ Each curve in LightPHE has a specific order, which is carefully chosen to balanc
 
 See [`curves`](https://github.com/serengil/LightPHE/tree/master/lightphe/elliptic_curve_forms) page for a list of all supported forms, curves and their details.
 
+### Vector Embeddings and Tensors
+
+LightPHE supports homomorphic encryption on vector embeddings and tensors. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
+
+```python
+# build a cryptosystem
+cs = LightPHE(algorithm_name="Paillier")
+
+# define plain embedding
+tensor = [1.005, 2.05, 3.005, 4.005, -5.05, 6, 7.003, 7.002]
+
+# encrypt vector embedding
+encrypted_tensors = cs.encrypt(tensor)
+
+# restore embedding
+decrypted_tensors = cs.decrypt(encrypted_tensors)
+
+# proof of work
+assert all(abs(original - decrypted) < 1e-2 for original, decrypted in zip(tensor, decrypted_tensors))
+```
+
+Encrypted embeddings retain their homomorphic properties, enabling secure computations on encrypted data without decryption. For example, two embeddings encrypted using a multiplicatively homomorphic algorithm can be multiplied element-wise.
+
+```python
+# build a multiplicatively homomorphic cryptosystem (e.g. RSA)
+cs = LightPHE("RSA")
+
+# define plain embeddings
+t1 = [1.005, 2.05, -3.5, 3.1, -4]
+t2 = [5, 6.2, -7.002, -7.1, 8.02]
+
+# encrypt embeddings
+c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
+
+# perform element-wise homomorphic multiplication
+c3 = c1 * c2
+
+# proof of work
+assert np.allclose(cs.decrypt(c3), [a * b for a, b in zip(t1, t2)], rtol=1e-2)
+```
+
+Similarly, two embeddings encrypted with an additively homomorphic algorithm can be added. Additionally, an encrypted embedding can be multiplied by a constant or a plain embedding.
+
+```python
+# build an additively homomorphic cryptosystem (e.g. Paillier)
+cs = LightPHE("Paillier")
+
+# define plain embeddings
+t1 = [1.005, 2.05, 3.6, 4, 4.02, 3.5]
+t2 = [5, 6.2, 7.5, 8.02, 8.02, 4.5]
+t3 = [1.03, 2.04, 3.05, 7.02, 2.01, 1.06]
+
+# encrypt embeddings
+c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
+
+# perform addition of two encrypted embeddings
+c4 = c1 + c2
+
+# perform scalar multiplication on an embedding
+c5 = 3 * c1
+
+# perform element-wise multiplication between an encrypted embedding and plain embedding
+c6 = c1 * t3  # Encrypted-plaintext multiplication
+
+# proof of work
+assert np.allclose(cs.decrypt(c4), [a + b for a, b in zip(t1, t2)], rtol=1e-2)
+assert np.allclose(cs.decrypt(c5), [a * 3 for a in t1], rtol=1e-2)
+assert np.allclose(cs.decrypt(c6), [a * b for a, b in zip(t1, t3)], rtol=1e-2)
+```
+
+### Vector Similarity Search with PHE
+
+Many machine learning models rely on a two-tower architecture, including facial recognition, reverse image search, recommendation engines, large language models, and more. In this setup, user and item inputs are separately mapped to vector embeddings.
+
+For example, suppose all facial embeddings in your database are encrypted on-prem in advance. When verifying an identity, the attempted facial embedding is generated on an edge device or in the cloud. You can compute the encrypted similarity by performing a dot product between the encrypted vector and the plain vector, ensuring secure comparison without decrypting sensitive data. Only additively homomorphic cryptosystems offer encrypted similarity calculation.
+
+```python
+# build an additively homomorphic cryptosystem (e.g. Paillier)
+cs = LightPHE("Paillier")
+
+# define plain vectors - suppose those are l2 normalized already
+alpha = [7.1, 5.2, 5.3, 2.4, 3.5, 4.6]  # On-prem vector (user tower)
+beta = [5.6, 3.7, 2.8, 4, 0, 5.9]  # Cloud vector (item tower)
+
+# encrypt embedding
+encrypted_alpha = cs.encrypt(alpha)
+
+# dot product of encrypted embedding and plain embedding
+encrypted_cosine_similarity = encrypted_alpha @ beta
+
+# decrypt similarity
+cosine_similarity = cs.decrypt(encrypted_cosine_similarity)[0]
+
+# proof of work
+assert abs(cosine_similarity - sum(x * y for x, y in zip(alpha, beta))) < 1e-2
+```
+
 # Contributing
 
 All PRs are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.
 
-You should be able run `make test` and `make lint` commands successfully before committing. Once a PR is created, GitHub test workflow will be run automatically and unit test results will be available in [GitHub actions](https://github.com/serengil/LightPHE/actions/workflows/tests.yml) before approval. Besides, workflow will evaluate the code with pylint as well.
+You should be able run `make test` and `make lint` commands successfully before committing. Once a PR is created, GitHub test workflow will be run automatically and unit test results will be available in [GitHub actions](https://github.com/serengil/LightPHE/actions/workflows/tests.yml) before approval.
 
 # Support
 

{lightphe-0.0.12 → lightphe-0.0.13}/lightphe/__init__.py

@@ -4,6 +4,8 @@ import json
 from typing import Optional, Union, List
 import multiprocessing
 from contextlib import closing
+import traceback
+import copy
 
 # 3rd party dependencies
 from tqdm import tqdm
@@ -36,7 +38,7 @@ from lightphe.elliptic_curve_forms.koblitz import Koblitz
 
 logger = Logger(module="lightphe/__init__.py")
 
-VERSION = "0.0.12"
+VERSION = "0.0.13"
 
 
 class LightPHE:
@@ -155,12 +157,13 @@ class LightPHE:
         return cs
 
     def encrypt(
-        self, plaintext: Union[int, float, list]
+        self, plaintext: Union[int, float, list], silent: bool = False
     ) -> Union[Ciphertext, EncryptedTensor]:
         """
         Encrypt a plaintext with a built cryptosystem
         Args:
             plaintext (int, float or tensor): message
+            silent (bool): set this to True if you do not want to see progress bar
         Returns
             ciphertext (from lightphe.models.Ciphertext import Ciphertext): encrypted message
         """
@@ -169,16 +172,21 @@ class LightPHE:
 
         if isinstance(plaintext, list):
             # then encrypt tensors
-            return self.__encrypt_tensors(tensor=plaintext)
+            return self.__encrypt_tensors(tensor=plaintext, silent=silent)
 
         ciphertext = self.cs.encrypt(
             plaintext=phe_utils.normalize_input(
                 value=plaintext, modulo=self.cs.plaintext_modulo
             )
         )
+
+        public_keys = self.cs.keys.copy()
+        if public_keys.get("private_key") is not None:
+            del public_keys["private_key"]
+
         return Ciphertext(
             algorithm_name=self.algorithm_name,
-            keys=self.cs.keys,
+            keys=public_keys,
             value=ciphertext,
             form=self.form,
             curve=self.curve,
@@ -206,11 +214,12 @@ class LightPHE:
 
         return self.cs.decrypt(ciphertext=ciphertext.value)
 
-    def __encrypt_tensors(self, tensor: list) -> EncryptedTensor:
+    def __encrypt_tensors(self, tensor: list, silent: bool = False) -> EncryptedTensor:
         """
         Encrypt a given tensor
         Args:
             tensor (list of int or float)
+            silent (bool): set this to True if you do not want to see progress bar
         Returns
             encrypted tensor (list of encrypted tensor object)
         """
@@ -218,7 +227,6 @@ class LightPHE:
 
         encrypted_zero = self.cs.encrypt(plaintext=0)
         divisor_encrypted = self.cs.encrypt(plaintext=10**self.precision)
-        is_positive_tensor = all(m >= 0 for m in tensor)
 
         num_workers = min(len(tensor), 2 * multiprocessing.cpu_count())
         logger.debug(f"encrypting tensors in {num_workers} parallel")
@@ -228,14 +236,13 @@ class LightPHE:
 
             for m in tensor:
                 f = pool.apply_async(
-                    encrypt_something,
+                    encrypt_float,
                     (
                         m,
                         divisor_encrypted,
                         self.cs,
                         self.precision,
                         encrypted_zero,
-                        is_positive_tensor,
                     ),
                 )
                 funclist.append(f)
@@ -245,7 +252,7 @@ class LightPHE:
             for f in tqdm(
                 funclist,
                 desc="Encrypting tensors",
-                disable=True if len(tensor) < 100 else False,
+                disable=silent,
             ):
                 result = f.get(timeout=10)
                 encrypted_tensor.append(result)
@@ -253,9 +260,13 @@ class LightPHE:
             toc = time.time()
             logger.debug(f"encryption took {toc - tic} seconds")
 
+            public_cs = copy.deepcopy(self.cs)
+            if public_cs.keys.get("private_key") is not None:
+                del public_cs.keys["private_key"]
+
             return EncryptedTensor(
                 fractions=encrypted_tensor,
-                cs=self.cs,
+                cs=public_cs,
                 precision=self.precision,
             )
 
@@ -277,7 +288,10 @@ class LightPHE:
             sign = c.sign
             abs_dividend = self.cs.decrypt(ciphertext=c.abs_dividend)
             # dividend = self.cs.decrypt(ciphertext=c.dividend)
+
+            # TODO: do I really need encrypted divisor? cannot I store current_precision
             divisor = self.cs.decrypt(ciphertext=c.divisor)
+
             m = sign * abs_dividend / divisor
 
             plain_tensor.append(m)
@@ -365,72 +379,91 @@ class LightPHE:
         )
 
 
-def encrypt_something(
+def encrypt_float(
     m: Union[int, float],
-    divisor_encrypted,
+    divisor_encrypted: int,
     cs: Homomorphic,
     precision: int,
     encrypted_zero: int,
-    is_positive_tensor: bool,
 ) -> Fraction:
-    if m == 0:
-        # this is very common in VGG-Face embeddings
-        c = Fraction(
-            dividend=encrypted_zero,
-            divisor=divisor_encrypted,
-            abs_dividend=encrypted_zero,
-            sign=0,
-        )
-    elif isinstance(m, int):
-        dividend_encrypted = cs.encrypt(
-            plaintext=(m % cs.plaintext_modulo) * pow(10, precision)
-        )
-        abs_dividend_encrypted = (
-            dividend_encrypted
-            if is_positive_tensor
-            else cs.encrypt(
-                plaintext=(abs(m) % cs.plaintext_modulo) * pow(10, precision)
+    """
+    Encrypt a float value
+    Args:
+        m (int or float): message to encrypt
+        divisor_encrypted (int): pre-calculated encrypted divisor
+        cs (Homomorphic): cryptosystem itself
+        precision (int): define how many digits after dot
+        encrypted_zero (int): pre-calculated encrypted value of 0
+    Returns:
+        result (Fraction): encrypted float value
+    """
+    try:
+        if m == 0:
+            # this is very common in VGG-Face embeddings
+            c = Fraction(
+                dividend=encrypted_zero,
+                divisor=divisor_encrypted,
+                abs_dividend=encrypted_zero,
+                sign=1,
             )
-        )
-        # divisor_encrypted = self.cs.encrypt(plaintext=pow(10, self.precision))
-        c = Fraction(
-            dividend=dividend_encrypted,
-            divisor=divisor_encrypted,
-            abs_dividend=abs_dividend_encrypted,
-            sign=1 if m >= 0 else -1,
-        )
-    elif isinstance(m, float):
-        dividend, _ = phe_utils.fractionize(
-            value=(m % cs.plaintext_modulo),
-            modulo=cs.plaintext_modulo,
-            precision=precision,
-        )
-        abs_dividend = (
-            dividend
-            if is_positive_tensor
-            else phe_utils.fractionize(
-                value=(abs(m) % cs.plaintext_modulo),
+        elif isinstance(m, int):
+            dividend_encrypted = cs.encrypt(
+                plaintext=(m % cs.plaintext_modulo) * pow(10, precision)
+            )
+            abs_dividend_encrypted = (
+                dividend_encrypted
+                if m > 0
+                else cs.encrypt(
+                    plaintext=(abs(m) % cs.plaintext_modulo) * pow(10, precision)
+                )
+            )
+            # divisor_encrypted = self.cs.encrypt(plaintext=pow(10, self.precision))
+            c = Fraction(
+                dividend=dividend_encrypted,
+                divisor=divisor_encrypted,
+                abs_dividend=abs_dividend_encrypted,
+                sign=1 if m >= 0 else -1,
+            )
+        elif isinstance(m, float):
+            # got `int too large to convert float` while m mod plaintext modulo
+            # when security level is set to 128
+            dividend, _ = phe_utils.fractionize(
+                value=(m % cs.plaintext_modulo if m > cs.plaintext_modulo else m),
                 modulo=cs.plaintext_modulo,
                 precision=precision,
-            )[0]
-        )
-        dividend_encrypted = cs.encrypt(plaintext=dividend)
-        abs_dividend_encrypted = (
-            dividend_encrypted
-            if is_positive_tensor
-            else cs.encrypt(plaintext=abs_dividend)
-        )
-        # divisor_encrypted = self.cs.encrypt(plaintext=_divisor)
-        c = Fraction(
-            dividend=dividend_encrypted,
-            divisor=divisor_encrypted,
-            abs_dividend=abs_dividend_encrypted,
-            sign=1 if m >= 0 else -1,
-        )
-    else:
-        raise ValueError(f"unimplemented type - {type(m)}")
+            )
+            abs_dividend = (
+                dividend
+                if m > 0
+                else phe_utils.fractionize(
+                    value=(
+                        abs(m) % cs.plaintext_modulo
+                        if abs(m) > cs.plaintext_modulo
+                        else abs(m)
+                    ),
+                    modulo=cs.plaintext_modulo,
+                    precision=precision,
+                )[0]
+            )
+            dividend_encrypted = cs.encrypt(plaintext=dividend)
+            abs_dividend_encrypted = (
+                dividend_encrypted if m > 0 else cs.encrypt(plaintext=abs_dividend)
+            )
+            # divisor_encrypted = self.cs.encrypt(plaintext=_divisor)
+            c = Fraction(
+                dividend=dividend_encrypted,
+                divisor=divisor_encrypted,
+                abs_dividend=abs_dividend_encrypted,
+                sign=1 if m >= 0 else -1,
+            )
+        else:
+            raise ValueError(f"unimplemented type - {type(m)}")
 
-    return c
+        return c
+    except Exception as err:
+        logger.error(f"Exception while running encrypt_float: {str(err)}")
+        logger.error(traceback.format_exc())
+        raise err
 
 
 class ECC:

{lightphe-0.0.12 → lightphe-0.0.13}/lightphe/cryptosystems/EllipticCurveElGamal.py

@@ -46,8 +46,13 @@ class EllipticCurveElGamal(Homomorphic):
         self.ecc = ECC(form_name=form, curve_name=curve)
 
         self.keys = keys or self.generate_keys(key_size or self.ecc.n.bit_length())
-        self.keys["curve"] = curve
-        self.keys["form"] = form
+
+        if curve is not None:
+            self.keys["curve"] = curve
+
+        if form is not None:
+            self.keys["form"] = form
+
         self.plaintext_modulo = self.ecc.modulo
         self.ciphertext_modulo = self.ecc.modulo
 
@@ -74,7 +79,7 @@ class EllipticCurveElGamal(Homomorphic):
         # public key
         Qa = self.ecc.G * ka
 
-        keys["public_key"]["Qa"] = Qa
+        keys["public_key"]["Qa"] = Qa.get_point()
         keys["private_key"]["ka"] = ka
 
         return keys
@@ -98,7 +103,8 @@ class EllipticCurveElGamal(Homomorphic):
             ciphertext (tuple): c1 and c2
         """
         # public key
-        Qa = self.keys["public_key"]["Qa"]
+        x, y = self.keys["public_key"]["Qa"]
+        Qa = EllipticCurvePoint(x=x, y=y, curve=self.ecc.curve)
 
         # random key
         r = random_key or self.generate_random_key()
@@ -134,20 +140,7 @@ class EllipticCurveElGamal(Homomorphic):
         # we need to find k from known s_prime and G
         # this requires to solve ECDLP
 
-        # base point
-        G = self.ecc.G
-        k = 2
-        while True:
-            G = G + self.ecc.G
-
-            if G == s_prime:
-                return k
-
-            k = k + 1
-            if k > self.ecc.n:
-                raise ValueError(
-                    f"Cannot restore scalar from {s_prime} = k x {self.ecc.G}"
-                )
+        return s_prime / self.ecc.G
 
     def multiply(self, ciphertext1: tuple, ciphertext2: tuple) -> tuple:
         raise ValueError(