pvzebra 1.0.0__tar.gz

pvzebra-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include pvzebra/LICENSE
+include pvzebra/__init__.py
+include pvzebra/_factory.py
+include pvzebra/_zebra.py
+include pvzebra/_util.py
+recursive-include pvzebra/lib *

pvzebra-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: pvzebra
+Version: 1.0.0
+Summary: Zebra Translate
+Home-page: https://github.com/Picovoice/zebra
+Author: Picovoice
+Author-email: hello@picovoice.ai
+Keywords: Translation,Text Translation,Language Translation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Zebra Binding for Python
+
+## Zebra Translate
+
+Made in Vancouver, Canada by [Picovoice](https://picovoice.ai)
+
+Zebra is a lightweight, on-device neural machine translation engine. Zebra is:
+
+- Private; All processing runs locally.
+- Cross-Platform:
+  - Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64)
+  - Raspberry Pi (3, 4, 5)
+
+## Compatibility
+
+- Python 3.9+
+- Runs on Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64), and Raspberry Pi (3, 4, 5).
+
+## Installation
+
+```console
+pip3 install pvzebra
+```
+
+## AccessKey
+
+Zebra requires a valid Picovoice `AccessKey` at initialization. `AccessKey` acts as your credentials when using Zebra SDKs.
+You can get your `AccessKey` for free. Make sure to keep your `AccessKey` secret.
+Signup or Login to [Picovoice Console](https://console.picovoice.ai/) to get your `AccessKey`.
+
+### Usage
+
+Create an instance of the engine and translate some text:
+
+```python
+import pvzebra
+
+handle = pvzebra.create(access_key='${ACCESS_KEY}', model_path='${MODEL_PATH}')
+
+translation = handle.translate('${TEXT}')
+print(translation)
+```
+
+Replace `${ACCESS_KEY}` with yours obtained from [Picovoice Console](https://console.picovoice.ai/), `${MODEL_PATH}` with
+a supported translation model located [here](../../lib/common/) and `${TEXT}` with the text to translate.
+Finally, when done be sure to explicitly release the resources using `handle.delete()`.
+
+### Translation Models
+
+Zebra translation models are located [here](../../lib/common/). The selected model decides the source and target translation languages.
+
+The format of the model follows:
+
+```console
+zebra_params_${SOURCE}_${TARGET}.pv
+```
+
+Where `${SOURCE}` is the language code of the source language and `${TARGET}` is the language code of the target language for the translation.
+
+## Demos
+
+[pvzebrademo](https://pypi.org/project/pvzebrademo/) provides command-line utilities for translating text using Zebra.

pvzebra-1.0.0/README.md

@@ -0,0 +1,62 @@
+# Zebra Binding for Python
+
+## Zebra Translate
+
+Made in Vancouver, Canada by [Picovoice](https://picovoice.ai)
+
+Zebra is a lightweight, on-device neural machine translation engine. Zebra is:
+
+- Private; All processing runs locally.
+- Cross-Platform:
+  - Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64)
+  - Raspberry Pi (3, 4, 5)
+
+## Compatibility
+
+- Python 3.9+
+- Runs on Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64), and Raspberry Pi (3, 4, 5).
+
+## Installation
+
+```console
+pip3 install pvzebra
+```
+
+## AccessKey
+
+Zebra requires a valid Picovoice `AccessKey` at initialization. `AccessKey` acts as your credentials when using Zebra SDKs.
+You can get your `AccessKey` for free. Make sure to keep your `AccessKey` secret.
+Signup or Login to [Picovoice Console](https://console.picovoice.ai/) to get your `AccessKey`.
+
+### Usage
+
+Create an instance of the engine and translate some text:
+
+```python
+import pvzebra
+
+handle = pvzebra.create(access_key='${ACCESS_KEY}', model_path='${MODEL_PATH}')
+
+translation = handle.translate('${TEXT}')
+print(translation)
+```
+
+Replace `${ACCESS_KEY}` with yours obtained from [Picovoice Console](https://console.picovoice.ai/), `${MODEL_PATH}` with
+a supported translation model located [here](../../lib/common/) and `${TEXT}` with the text to translate.
+Finally, when done be sure to explicitly release the resources using `handle.delete()`.
+
+### Translation Models
+
+Zebra translation models are located [here](../../lib/common/). The selected model decides the source and target translation languages.
+
+The format of the model follows:
+
+```console
+zebra_params_${SOURCE}_${TARGET}.pv
+```
+
+Where `${SOURCE}` is the language code of the source language and `${TARGET}` is the language code of the target language for the translation.
+
+## Demos
+
+[pvzebrademo](https://pypi.org/project/pvzebrademo/) provides command-line utilities for translating text using Zebra.

pvzebra-1.0.0/pvzebra/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pvzebra-1.0.0/pvzebra/__init__.py

@@ -0,0 +1,14 @@
+#
+# Copyright 2026 Picovoice Inc.
+#
+# You may not use this file except in compliance with the license. A copy of the license is located in the "LICENSE"
+# file accompanying this source.
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+from ._factory import *
+from ._util import *
+from ._zebra import *

pvzebra-1.0.0/pvzebra/_factory.py

@@ -0,0 +1,76 @@
+#
+# Copyright 2026 Picovoice Inc.
+#
+# You may not use this file except in compliance with the license. A copy of the license is located in the "LICENSE"
+# file accompanying this source.
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+from typing import (
+    Optional,
+    Sequence
+)
+
+from ._util import default_library_path
+
+from ._zebra import (
+    list_hardware_devices,
+    Zebra,
+)
+
+
+def create(
+        access_key: str,
+        model_path: Optional[str] = None,
+        device: Optional[str] = None,
+        library_path: Optional[str] = None) -> Zebra:
+    """
+    Factory method for Zebra Translate engine.
+
+    :param access_key: AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
+    :param model_path: Absolute path to the file containing model parameters (`.pv`).
+    Sets the source and target translation languages.
+    :param device: String representation of the device (e.g., CPU or GPU) to use. If set to `best`, the most
+    suitable device is selected automatically. If set to `gpu`, the engine uses the first available GPU device.
+    To select a specific GPU device, set this argument to `gpu:${GPU_INDEX}`, where `${GPU_INDEX}` is the index
+    of the target GPU. If set to `cpu`, the engine will run on the CPU with the default number of threads.
+    To specify the number of threads, set this argument to `cpu:${NUM_THREADS}`, where `${NUM_THREADS}`
+    is the desired number of threads.
+    :param library_path: Absolute path to Zebra's dynamic library. If not set it will be set to the default location.
+    :return: An instance of Zebra translation engine.
+    """
+
+    if device is None:
+        device = "best"
+
+    if library_path is None:
+        library_path = default_library_path()
+
+    return Zebra(
+        access_key=access_key,
+        model_path=model_path,
+        device=device,
+        library_path=library_path)
+
+
+def available_devices(library_path: Optional[str] = None) -> Sequence[str]:
+    """
+    Lists all available devices that Zebra can use for translation. Each entry in the list can be the `device` argument
+    of `.create` factory method or `Zebra` constructor.
+    :param library_path: Absolute path to Zebra's dynamic library. If not set it will be set to the default location.
+    :return: List of all available devices that Zebra can use for translation.
+    """
+
+    if library_path is None:
+        library_path = default_library_path()
+
+    return list_hardware_devices(library_path=library_path)
+
+
+__all__ = [
+    "available_devices",
+    "create"
+]

pvzebra-1.0.0/pvzebra/_util.py

@@ -0,0 +1,82 @@
+#
+# Copyright 2026 Picovoice Inc.
+#
+# You may not use this file except in compliance with the license. A copy of the license is located in the "LICENSE"
+# file accompanying this source.
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+import os
+import platform
+import subprocess
+
+
+def _is_64bit():
+    return "64bit" in platform.architecture()[0]
+
+
+def _linux_machine() -> str:
+    machine = platform.machine()
+    if machine == "x86_64":
+        return machine
+    elif machine in ["aarch64", "armv7l"]:
+        arch_info = ("-" + machine) if _is_64bit() else ""
+    else:
+        raise NotImplementedError("Unsupported CPU architecture: `%s`" % machine)
+
+    cpu_info = ""
+    try:
+        cpu_info = subprocess.check_output(["cat", "/proc/cpuinfo"]).decode("utf-8")
+        cpu_part_list = [x for x in cpu_info.split("\n") if "CPU part" in x]
+        cpu_part = cpu_part_list[0].split(" ")[-1].lower()
+    except Exception as e:
+        raise RuntimeError("Failed to identify the CPU with `%s`\nCPU info: `%s`" % (e, cpu_info))
+
+    if "0xd03" == cpu_part:
+        return "cortex-a53" + arch_info
+    elif "0xd07" == cpu_part:
+        return "cortex-a57" + arch_info
+    elif "0xd08" == cpu_part:
+        return "cortex-a72" + arch_info
+    elif "0xd0b" == cpu_part:
+        return "cortex-a76" + arch_info
+    else:
+        raise NotImplementedError("Unsupported CPU: `%s`." % cpu_part)
+
+
+_RASPBERRY_PI_MACHINES = {
+    "cortex-a53",
+    "cortex-a72",
+    "cortex-a76",
+    "cortex-a53-aarch64",
+    "cortex-a72-aarch64",
+    "cortex-a76-aarch64"}
+
+
+def default_library_path(relative: str = "") -> str:
+    if platform.system() == "Darwin":
+        if platform.machine() == "x86_64":
+            return os.path.join(os.path.dirname(__file__), relative, "lib/mac/x86_64/libpv_zebra.dylib")
+        elif platform.machine() == "arm64":
+            return os.path.join(os.path.dirname(__file__), relative, "lib/mac/arm64/libpv_zebra.dylib")
+    elif platform.system() == "Linux":
+        linux_machine = _linux_machine()
+        if linux_machine == "x86_64":
+            return os.path.join(os.path.dirname(__file__), relative, "lib/linux/x86_64/libpv_zebra.so")
+        elif linux_machine in _RASPBERRY_PI_MACHINES:
+            return os.path.join(
+                os.path.dirname(__file__), relative, "lib/raspberry-pi/%s/libpv_zebra.so" % linux_machine
+            )
+    elif platform.system() == "Windows":
+        if platform.machine().lower() == 'amd64':
+            return os.path.join(os.path.dirname(__file__), relative, "lib", "windows", "amd64", "libpv_zebra.dll")
+        elif platform.machine().lower() == 'arm64':
+            return os.path.join(os.path.dirname(__file__), relative, "lib", "windows", "arm64", "libpv_zebra.dll")
+
+    raise NotImplementedError("Unsupported platform.")
+
+
+__all__ = ["default_library_path"]

pvzebra-1.0.0/pvzebra/_zebra.py

@@ -0,0 +1,312 @@
+import os
+import pathlib
+from collections import namedtuple
+from ctypes import *
+from enum import Enum
+from typing import *
+
+
+class ZebraError(Exception):
+    def __init__(self, message: str = "", message_stack: Sequence[str] = None):
+        super().__init__(message)
+
+        self._message = message
+        self._message_stack = list() if message_stack is None else message_stack
+
+    def __str__(self):
+        message = self._message
+        if len(self._message_stack) > 0:
+            message += ":"
+            for i in range(len(self._message_stack)):
+                message += "\n  [%d] %s" % (i, self._message_stack[i])
+        return message
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+    @property
+    def message_stack(self) -> Sequence[str]:
+        return self._message_stack
+
+
+class ZebraMemoryError(ZebraError):
+    pass
+
+
+class ZebraIOError(ZebraError):
+    pass
+
+
+class ZebraInvalidArgumentError(ZebraError):
+    pass
+
+
+class ZebraStopIterationError(ZebraError):
+    pass
+
+
+class ZebraKeyError(ZebraError):
+    pass
+
+
+class ZebraInvalidStateError(ZebraError):
+    pass
+
+
+class ZebraRuntimeError(ZebraError):
+    pass
+
+
+class ZebraActivationError(ZebraError):
+    pass
+
+
+class ZebraActivationLimitError(ZebraError):
+    pass
+
+
+class ZebraActivationThrottledError(ZebraError):
+    pass
+
+
+class ZebraActivationRefusedError(ZebraError):
+    pass
+
+
+class Zebra(object):
+    """
+    Python binding for Zebra Translate engine.
+    """
+
+    class PicovoiceStatuses(Enum):
+        SUCCESS = 0
+        OUT_OF_MEMORY = 1
+        IO_ERROR = 2
+        INVALID_ARGUMENT = 3
+        STOP_ITERATION = 4
+        KEY_ERROR = 5
+        INVALID_STATE = 6
+        RUNTIME_ERROR = 7
+        ACTIVATION_ERROR = 8
+        ACTIVATION_LIMIT_REACHED = 9
+        ACTIVATION_THROTTLED = 10
+        ACTIVATION_REFUSED = 11
+
+    _PICOVOICE_STATUS_TO_EXCEPTION = {
+        PicovoiceStatuses.OUT_OF_MEMORY: ZebraMemoryError,
+        PicovoiceStatuses.IO_ERROR: ZebraIOError,
+        PicovoiceStatuses.INVALID_ARGUMENT: ZebraInvalidArgumentError,
+        PicovoiceStatuses.STOP_ITERATION: ZebraStopIterationError,
+        PicovoiceStatuses.KEY_ERROR: ZebraKeyError,
+        PicovoiceStatuses.INVALID_STATE: ZebraInvalidStateError,
+        PicovoiceStatuses.RUNTIME_ERROR: ZebraRuntimeError,
+        PicovoiceStatuses.ACTIVATION_ERROR: ZebraActivationError,
+        PicovoiceStatuses.ACTIVATION_LIMIT_REACHED: ZebraActivationLimitError,
+        PicovoiceStatuses.ACTIVATION_THROTTLED: ZebraActivationThrottledError,
+        PicovoiceStatuses.ACTIVATION_REFUSED: ZebraActivationRefusedError,
+    }
+
+    class CZebra(Structure):
+        pass
+
+    def __init__(self, access_key: str, model_path: str, device: str, library_path: str) -> None:
+        """
+        Constructor.
+
+        :param access_key: AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
+        :param model_path: Absolute path to the file containing model parameters (`.pv`).
+        Sets the source and target translation languages.
+        :param device: String representation of the device (e.g., CPU or GPU) to use. If set to `best`, the most
+        suitable device is selected automatically. If set to `gpu`, the engine uses the first available GPU device.
+        To select a specific GPU device, set this argument to `gpu:${GPU_INDEX}`, where `${GPU_INDEX}` is the index
+        of the target GPU. If set to `cpu`, the engine will run on the CPU with the default number of threads.
+        To specify the number of threads, set this argument to `cpu:${NUM_THREADS}`, where `${NUM_THREADS}`
+        is the desired number of threads.
+        :param library_path: Absolute path to Zebra's dynamic library.
+        """
+
+        if not isinstance(access_key, str) or len(access_key) == 0:
+            raise ZebraInvalidArgumentError("`access_key` should be a non-empty string.")
+
+        if not isinstance(model_path, str) or len(model_path) == 0:
+            raise ZebraInvalidArgumentError("`model_path` should be a non-empty string.")
+
+        if not os.path.exists(model_path):
+            raise ZebraIOError("Could not find model file at `%s`." % model_path)
+
+        if not isinstance(device, str) or len(device) == 0:
+            raise ZebraInvalidArgumentError("`device` should be a non-empty string.")
+
+        if not os.path.exists(library_path):
+            raise ZebraIOError("Could not find Zebra's dynamic library at `%s`." % library_path)
+
+        library = cdll.LoadLibrary(library_path)
+
+        set_sdk_func = library.pv_set_sdk
+        set_sdk_func.argtypes = [c_char_p]
+        set_sdk_func.restype = None
+
+        set_sdk_func("python".encode("utf-8"))
+
+        self._get_error_stack_func = library.pv_get_error_stack
+        self._get_error_stack_func.argtypes = [POINTER(POINTER(c_char_p)), POINTER(c_int)]
+        self._get_error_stack_func.restype = self.PicovoiceStatuses
+
+        self._free_error_stack_func = library.pv_free_error_stack
+        self._free_error_stack_func.argtypes = [POINTER(c_char_p)]
+        self._free_error_stack_func.restype = None
+
+        init_func = library.pv_zebra_init
+        init_func.argtypes = [c_char_p, c_char_p, c_char_p, POINTER(POINTER(self.CZebra))]
+        init_func.restype = self.PicovoiceStatuses
+
+        self._handle = POINTER(self.CZebra)()
+
+        status = init_func(
+            access_key.encode(),
+            model_path.encode(),
+            device.encode(),
+            byref(self._handle))
+        if status is not self.PicovoiceStatuses.SUCCESS:
+            raise self._PICOVOICE_STATUS_TO_EXCEPTION[status](
+                message="Initialization failed", message_stack=self._get_error_stack()
+            )
+
+        max_character_limit_func = library.pv_zebra_max_character_limit
+        max_character_limit_func.argtypes = [POINTER(self.CZebra), POINTER(c_int32)]
+        max_character_limit_func.restype = self.PicovoiceStatuses
+
+        c_max_character_limit = c_int32()
+        status = max_character_limit_func(self._handle, byref(c_max_character_limit))
+        if status is not self.PicovoiceStatuses.SUCCESS:
+            raise self._PICOVOICE_STATUS_TO_EXCEPTION[status](
+                message="Failed to get max character limit", message_stack=self._get_error_stack()
+            )
+        self._max_character_limit = c_max_character_limit.value
+
+        self._delete_func = library.pv_zebra_delete
+        self._delete_func.argtypes = [POINTER(self.CZebra)]
+        self._delete_func.restype = None
+
+        self._translate_func = library.pv_zebra_translate
+        self._translate_func.argtypes = [
+            POINTER(self.CZebra),
+            c_char_p,
+            POINTER(c_char_p),
+        ]
+        self._translate_func.restype = self.PicovoiceStatuses
+
+        self._translation_delete_func = library.pv_zebra_translation_delete
+        self._translation_delete_func.argtypes = [POINTER(self.CZebra), c_char_p]
+        self._translation_delete_func.restype = None
+
+        version_func = library.pv_zebra_version
+        version_func.argtypes = []
+        version_func.restype = c_char_p
+        self._version = version_func().decode("utf-8")
+
+    def translate(self, text: str) -> str:
+        """
+        Translates text. The maximum number of characters that can be translated at once
+        is given by `.max_character_limit`.
+
+        :param text: Text to translate.
+        :return: Translated text.
+        """
+
+        if len(text) == 0:
+            raise ZebraInvalidArgumentError("Text cannot be empty.")
+
+        if len(text) > self.max_character_limit:
+            raise ZebraInvalidArgumentError("Maximum character limit exceeded.")
+
+        c_translation = c_char_p()
+        status = self._translate_func(self._handle, text.encode(), byref(c_translation))
+        if status is not self.PicovoiceStatuses.SUCCESS:
+            raise self._PICOVOICE_STATUS_TO_EXCEPTION[status](
+                message="Translate failed", message_stack=self._get_error_stack()
+            )
+
+        translation = c_translation.value.decode()
+        self._translation_delete_func(self._handle, c_translation)
+
+        return translation
+
+    def delete(self) -> None:
+        """Releases resources acquired by Zebra."""
+
+        self._delete_func(self._handle)
+
+    @property
+    def version(self) -> str:
+        """Version."""
+
+        return self._version
+
+    @property
+    def max_character_limit(self) -> int:
+        """Gets the maximum number of characters that can be translated at once by `.translate`."""
+
+        return self._max_character_limit
+
+    def _get_error_stack(self) -> Sequence[str]:
+        message_stack_ref = POINTER(c_char_p)()
+        message_stack_depth = c_int()
+        status = self._get_error_stack_func(byref(message_stack_ref), byref(message_stack_depth))
+        if status is not self.PicovoiceStatuses.SUCCESS:
+            raise self._PICOVOICE_STATUS_TO_EXCEPTION[status](message="Unable to get Zebra error state")
+
+        message_stack = list()
+        for i in range(message_stack_depth.value):
+            message_stack.append(message_stack_ref[i].decode("utf-8"))
+
+        self._free_error_stack_func(message_stack_ref)
+
+        return message_stack
+
+
+def list_hardware_devices(library_path: str) -> Sequence[str]:
+    dll_dir_obj = None
+    if hasattr(os, "add_dll_directory"):
+        dll_dir_obj = os.add_dll_directory(os.path.dirname(library_path))
+
+    library = cdll.LoadLibrary(library_path)
+
+    if dll_dir_obj is not None:
+        dll_dir_obj.close()
+
+    list_hardware_devices_func = library.pv_zebra_list_hardware_devices
+    list_hardware_devices_func.argtypes = [POINTER(POINTER(c_char_p)), POINTER(c_int32)]
+    list_hardware_devices_func.restype = Zebra.PicovoiceStatuses
+    c_hardware_devices = POINTER(c_char_p)()
+    c_num_hardware_devices = c_int32()
+    status = list_hardware_devices_func(byref(c_hardware_devices), byref(c_num_hardware_devices))
+    if status is not Zebra.PicovoiceStatuses.SUCCESS:
+        raise _PICOVOICE_STATUS_TO_EXCEPTION[status](message='`pv_zebra_list_hardware_devices` failed.')
+    res = [c_hardware_devices[i].decode() for i in range(c_num_hardware_devices.value)]
+
+    free_hardware_devices_func = library.pv_zebra_free_hardware_devices
+    free_hardware_devices_func.argtypes = [POINTER(c_char_p), c_int32]
+    free_hardware_devices_func.restype = None
+    free_hardware_devices_func(c_hardware_devices, c_num_hardware_devices.value)
+
+    return res
+
+
+__all__ = [
+    'list_hardware_devices',
+    "Zebra",
+    "ZebraActivationError",
+    "ZebraActivationLimitError",
+    "ZebraActivationRefusedError",
+    "ZebraActivationThrottledError",
+    "ZebraError",
+    "ZebraIOError",
+    "ZebraInvalidArgumentError",
+    "ZebraInvalidStateError",
+    "ZebraKeyError",
+    "ZebraMemoryError",
+    "ZebraRuntimeError",
+    "ZebraStopIterationError"
+]

pvzebra-1.0.0/pvzebra.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: pvzebra
+Version: 1.0.0
+Summary: Zebra Translate
+Home-page: https://github.com/Picovoice/zebra
+Author: Picovoice
+Author-email: hello@picovoice.ai
+Keywords: Translation,Text Translation,Language Translation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Zebra Binding for Python
+
+## Zebra Translate
+
+Made in Vancouver, Canada by [Picovoice](https://picovoice.ai)
+
+Zebra is a lightweight, on-device neural machine translation engine. Zebra is:
+
+- Private; All processing runs locally.
+- Cross-Platform:
+  - Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64)
+  - Raspberry Pi (3, 4, 5)
+
+## Compatibility
+
+- Python 3.9+
+- Runs on Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64), and Raspberry Pi (3, 4, 5).
+
+## Installation
+
+```console
+pip3 install pvzebra
+```
+
+## AccessKey
+
+Zebra requires a valid Picovoice `AccessKey` at initialization. `AccessKey` acts as your credentials when using Zebra SDKs.
+You can get your `AccessKey` for free. Make sure to keep your `AccessKey` secret.
+Signup or Login to [Picovoice Console](https://console.picovoice.ai/) to get your `AccessKey`.
+
+### Usage
+
+Create an instance of the engine and translate some text:
+
+```python
+import pvzebra
+
+handle = pvzebra.create(access_key='${ACCESS_KEY}', model_path='${MODEL_PATH}')
+
+translation = handle.translate('${TEXT}')
+print(translation)
+```
+
+Replace `${ACCESS_KEY}` with yours obtained from [Picovoice Console](https://console.picovoice.ai/), `${MODEL_PATH}` with
+a supported translation model located [here](../../lib/common/) and `${TEXT}` with the text to translate.
+Finally, when done be sure to explicitly release the resources using `handle.delete()`.
+
+### Translation Models
+
+Zebra translation models are located [here](../../lib/common/). The selected model decides the source and target translation languages.
+
+The format of the model follows:
+
+```console
+zebra_params_${SOURCE}_${TARGET}.pv
+```
+
+Where `${SOURCE}` is the language code of the source language and `${TARGET}` is the language code of the target language for the translation.
+
+## Demos
+
+[pvzebrademo](https://pypi.org/project/pvzebrademo/) provides command-line utilities for translating text using Zebra.

pvzebra-1.0.0/pvzebra.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+MANIFEST.in
+README.md
+setup.py
+pvzebra/LICENSE
+pvzebra/__init__.py
+pvzebra/_factory.py
+pvzebra/_util.py
+pvzebra/_zebra.py
+pvzebra.egg-info/PKG-INFO
+pvzebra.egg-info/SOURCES.txt
+pvzebra.egg-info/dependency_links.txt
+pvzebra.egg-info/top_level.txt
+pvzebra/lib/linux/x86_64/libpv_zebra.so
+pvzebra/lib/mac/arm64/libpv_zebra.dylib
+pvzebra/lib/mac/x86_64/libpv_zebra.dylib
+pvzebra/lib/raspberry-pi/cortex-a53/libpv_zebra.so
+pvzebra/lib/raspberry-pi/cortex-a53-aarch64/libpv_zebra.so
+pvzebra/lib/raspberry-pi/cortex-a72/libpv_zebra.so
+pvzebra/lib/raspberry-pi/cortex-a72-aarch64/libpv_zebra.so
+pvzebra/lib/raspberry-pi/cortex-a76/libpv_zebra.so
+pvzebra/lib/raspberry-pi/cortex-a76-aarch64/libpv_zebra.so
+pvzebra/lib/windows/amd64/libpv_zebra.dll
+pvzebra/lib/windows/amd64/pv_ypu_impl_cuda_zebra.dll
+pvzebra/lib/windows/arm64/libpv_zebra.dll

pvzebra-1.0.0/pvzebra.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pvzebra-1.0.0/pvzebra.egg-info/top_level.txt

@@ -0,0 +1 @@
+pvzebra

pvzebra-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pvzebra-1.0.0/setup.py

@@ -0,0 +1,64 @@
+#
+# Copyright 2026 Picovoice Inc.
+#
+# You may not use this file except in compliance with the license. A copy of the license is located in the "LICENSE"
+# file accompanying this source.
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+import os
+import shutil
+
+import setuptools
+
+INCLUDE_FILES = ('../../LICENSE', '__init__.py', '_factory.py', '_zebra.py', '_util.py')
+INCLUDE_LIBS = ('linux', 'mac', 'raspberry-pi', 'windows')
+os.system('git clean -dfx')
+
+package_folder = os.path.join(os.path.dirname(__file__), 'pvzebra')
+os.mkdir(package_folder)
+manifest_in = ""
+
+for rel_path in INCLUDE_FILES:
+    shutil.copy(os.path.join(os.path.dirname(__file__), rel_path), package_folder)
+    manifest_in += "include pvzebra/%s\n" % os.path.basename(rel_path)
+
+os.mkdir(os.path.join(package_folder, 'lib'))
+for platform in INCLUDE_LIBS:
+    shutil.copytree(
+        os.path.join(os.path.dirname(__file__), '../../lib', platform),
+        os.path.join(package_folder, 'lib', platform))
+
+manifest_in += "recursive-include pvzebra/lib *\n"
+
+with open(os.path.join(os.path.dirname(__file__), 'MANIFEST.in'), 'w') as f:
+    f.write(manifest_in)
+
+with open(os.path.join(os.path.dirname(__file__), 'README.md'), 'r') as f:
+    long_description = f.read()
+
+setuptools.setup(
+    name="pvzebra",
+    version="1.0.0",
+    author="Picovoice",
+    author_email="hello@picovoice.ai",
+    description="Zebra Translate",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/Picovoice/zebra",
+    packages=["pvzebra"],
+    include_package_data=True,
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Topic :: Text Processing :: Linguistic",
+    ],
+    python_requires=">=3.9",
+    keywords="Translation, Text Translation, Language Translation",
+)