tarjamli 0.1.0__py3-none-any.whl

tarjamli/__init__.py

@@ -0,0 +1,5 @@
+"""Tarjamli translation client for Sawalni API."""
+from .client import (Tarjamli, Translation, TranslationError, AuthenticationError,
+                     RateLimitError, IncompleteTranslationError)
+__all__ = ["Tarjamli", "Translation", "TranslationError", "AuthenticationError",
+           "RateLimitError", "IncompleteTranslationError"]

tarjamli/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

tarjamli/cli.py

@@ -0,0 +1,26 @@
+import argparse
+import json
+import sys
+from . import Tarjamli, TranslationError
+
+def main():
+    parser = argparse.ArgumentParser(prog="tarjamli")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("languages", help="List language and script codes")
+    command = commands.add_parser("translate", help="Translate text; use --text - to read stdin")
+    command.add_argument("--text", required=True)
+    command.add_argument("--source", required=True)
+    command.add_argument("--target", required=True)
+    command.add_argument("--instructions", default="")
+    command.add_argument("--json", action="store_true", help="Print the full API response")
+    args = parser.parse_args()
+    if args.command == "languages":
+        print(json.dumps(Tarjamli.languages(), ensure_ascii=False, indent=2))
+        return
+    try:
+        text = sys.stdin.read() if args.text == "-" else args.text
+        result = Tarjamli().translate(text, source=args.source, target=args.target, instructions=args.instructions)
+        print(json.dumps(result.raw, ensure_ascii=False, indent=2) if args.json else result.text)
+    except (TranslationError, ValueError) as error:
+        print(str(error), file=sys.stderr)
+        raise SystemExit(1)

tarjamli/client.py

@@ -0,0 +1,95 @@
+"""Small standard-library client for Tarjamli Mini v4. Python 3.10+."""
+import json
+import os
+import urllib.error
+import urllib.request
+from importlib.resources import files
+
+ENDPOINT = "https://api.sawalni.com/v1/language/translate"
+LANGUAGES = json.loads(files("tarjamli").joinpath("languages.json").read_text())
+
+class TranslationError(RuntimeError):
+    """A request failed or returned an unusable translation."""
+
+class AuthenticationError(TranslationError):
+    pass
+
+class RateLimitError(TranslationError):
+    pass
+
+class IncompleteTranslationError(TranslationError):
+    pass
+
+def make_request(text, source, target, instructions="", *, model="tarjamli-mini-v4"):
+    if model not in ("tarjamli-mini-v4",):
+        raise ValueError("Unsupported model")
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError("text must be nonempty")
+    if len(text.encode("utf-8")) > 262144:
+        raise ValueError("text exceeds 262144 UTF-8 bytes")
+    if source not in LANGUAGES or target not in LANGUAGES:
+        raise ValueError("Use explicit supported source and target codes from languages.json")
+    if not isinstance(instructions, str) or len(instructions.encode("utf-8")) > 32768:
+        raise ValueError("instructions must be a string of at most 32768 UTF-8 bytes")
+    payload = dict(model=model, text=text, source=source, target=target)
+    if instructions.strip():
+        payload["instructions"] = instructions
+    return payload
+
+def translate(text, source, target, instructions="", *, api_key=None, timeout=180, model="tarjamli-mini-v4"):
+    payload = make_request(text, source, target, instructions, model=model)
+    key = api_key or os.environ.get("SAWALNI_API_KEY")
+    if not key:
+        raise AuthenticationError("Set SAWALNI_API_KEY in your shell or pass api_key")
+    request = urllib.request.Request(ENDPOINT, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers={"Authorization": "Bearer " + key, "Content-Type": "application/json", "User-Agent": "Sawalni-Tarjamli-Starter/1.0"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = json.load(response)
+    except urllib.error.HTTPError as error:
+        error_type = AuthenticationError if error.code in (401, 403) else RateLimitError if error.code == 429 else TranslationError
+        raise error_type(f"Translation HTTP {error.code}; check access, input and API status. No automatic retry.") from None
+    except (urllib.error.URLError, TimeoutError):
+        raise TranslationError("Translation connection failed or timed out. Check before retrying; the request may have run.") from None
+    except (ValueError, UnicodeError):
+        raise TranslationError("API returned invalid JSON") from None
+    data = body.get("data") if isinstance(body, dict) else None
+    if not isinstance(data, dict) or not isinstance(data.get("translated"), str) or not data["translated"].strip():
+        raise TranslationError("API returned no translation")
+    if data.get("complete") is not True:
+        raise IncompleteTranslationError("Translation is incomplete; shorten the input before trying again")
+    if data.get("source") != source or data.get("target") != target or data.get("model") != payload["model"]:
+        raise TranslationError("Unexpected response model or language identity")
+    return body
+
+
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass(frozen=True)
+class Translation:
+    """Translation text and the full API response, including usage when provided."""
+    text: str
+    source: str
+    target: str
+    model: str
+    raw: dict[str, Any]
+
+class Tarjamli:
+    """Synchronous client. Requests are never retried automatically."""
+    def __init__(self, api_key: str | None = None, *, timeout: float = 180) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self._api_key = api_key
+        self.timeout = timeout
+
+    @staticmethod
+    def languages() -> dict[str, str]:
+        """Return a copy of the supported language-code mapping."""
+        return dict(LANGUAGES)
+
+    def translate(self, text: str, *, source: str, target: str, instructions: str = "", model: str = "tarjamli-mini-v4") -> Translation:
+        body = translate(text, source, target, instructions, api_key=self._api_key,
+                         timeout=self.timeout, model=model)
+        data = body["data"]
+        return Translation(data["translated"], data["source"], data["target"], data["model"], body)

tarjamli/languages.json

@@ -0,0 +1,56 @@
+{
+  "ary_Arab": "Moroccan Arabic",
+  "ary_Latn": "Moroccan Arabic written in Latin script",
+  "shi_Latn": "Tachelhit written in Latin script",
+  "zgh_Tfng": "Standard Moroccan Tamazight written in Tifinagh script",
+  "amh_Ethi": "Amharic",
+  "arb_Arab": "Modern Standard Arabic",
+  "ben_Beng": "Bengali",
+  "ces_Latn": "Czech",
+  "cmn_Hans": "Simplified Chinese",
+  "dan_Latn": "Danish",
+  "deu_Latn": "German",
+  "ell_Grek": "Greek",
+  "eng_Latn": "English",
+  "fin_Latn": "Finnish",
+  "fra_Latn": "French",
+  "guj_Gujr": "Gujarati",
+  "hau_Latn": "Hausa",
+  "heb_Hebr": "Hebrew",
+  "hin_Deva": "Hindi",
+  "hun_Latn": "Hungarian",
+  "ind_Latn": "Indonesian",
+  "ita_Latn": "Italian",
+  "jpn_Jpan": "Japanese",
+  "kan_Knda": "Kannada",
+  "khm_Khmr": "Khmer",
+  "kor_Hang": "Korean",
+  "lao_Laoo": "Lao",
+  "mal_Mlym": "Malayalam",
+  "mar_Deva": "Marathi",
+  "mya_Mymr": "Burmese",
+  "nld_Latn": "Dutch",
+  "nob_Latn": "Norwegian Bokmål",
+  "npi_Deva": "Nepali",
+  "pan_Guru": "Punjabi written in Gurmukhi",
+  "pes_Arab": "Persian",
+  "pol_Latn": "Polish",
+  "por_Latn": "Portuguese",
+  "ron_Latn": "Romanian",
+  "rus_Cyrl": "Russian",
+  "sin_Sinh": "Sinhala",
+  "som_Latn": "Somali",
+  "spa_Latn": "Spanish",
+  "swe_Latn": "Swedish",
+  "swh_Latn": "Swahili",
+  "tam_Taml": "Tamil",
+  "tel_Telu": "Telugu",
+  "tha_Thai": "Thai",
+  "tur_Latn": "Turkish",
+  "ukr_Cyrl": "Ukrainian",
+  "urd_Arab": "Urdu",
+  "vie_Latn": "Vietnamese",
+  "yor_Latn": "Yoruba",
+  "zsm_Latn": "Malay",
+  "zul_Latn": "Zulu"
+}

tarjamli-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: tarjamli
+Version: 0.1.0
+Summary: Python client for Tarjamli translation through Sawalni API
+Author-email: Omar Kamali <omar@omneitylabs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://api.sawalni.com
+Project-URL: Issues, https://github.com/omneity-labs/starter-translation/issues
+Project-URL: Examples, https://github.com/omneity-labs/starter-translation
+Keywords: translation,darija,amazigh,tarjamli,sawalni
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tarjamli
+
+A small Python client for Tarjamli translation through the [Sawalni API](https://api.sawalni.com). Translate text, convert Darija between Arabic and Latin scripts, and give the translation context about tone, gender or address forms.
+
+Python 3.10+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install tarjamli
+```
+
+Set your Sawalni API key:
+
+```sh
+export SAWALNI_API_KEY="your-key"
+```
+
+## Translate
+
+```python
+from tarjamli import Tarjamli
+
+client = Tarjamli()
+result = client.translate(
+    "واش تقدر تصيفط ليا الدوسي؟",
+    source="ary_Arab",
+    target="fra_Latn",
+    instructions="Address one person formally using vous.",
+)
+print(result.text)
+```
+
+Pass your own text. Remove `instructions` for ordinary translation, or change it to supply context. The API field is `instructions`; tone and gender are not separate parameters.
+
+## Convert Darija scripts
+
+```python
+result = client.translate(
+    "سلام، كيف داير؟",
+    source="ary_Arab",
+    target="ary_Latn",
+)
+print(result.text)
+```
+
+Reverse the source and target for Latin → Arabic. Use `client.languages()` to list supported language and script codes, including `shi_Latn` for Tachelhit and `zgh_Tfng` for Tamazight in Tifinagh.
+
+## CLI
+
+```sh
+tarjamli translate --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
+tarjamli languages
+```
+
+Use `--text -` to read standard input. Add `--json` for the full API response.
+
+## Configuration and results
+
+`Tarjamli(api_key=None, timeout=180)` reads `SAWALNI_API_KEY` when no key is passed. Keep keys in server-side code or your terminal environment. The package does not load `.env` files.
+
+`translate(text, *, source, target, instructions="", model="tarjamli-mini-v4")` returns a `Translation` with `text`, `source`, `target`, `model`, and `raw` (the full response, including usage when supplied). This release supports the checked Mini model only.
+
+Each call sends one request to `POST https://api.sawalni.com/v1/language/translate`. Live requests use your API balance. There are no automatic retries.
+
+## Errors
+
+```python
+from tarjamli import AuthenticationError, RateLimitError, TranslationError
+
+try:
+    result = client.translate("Hello", source="eng_Latn", target="ary_Arab")
+except AuthenticationError:
+    # Check your key and model access.
+    raise
+except RateLimitError:
+    # Decide when to retry in your application.
+    raise
+except TranslationError:
+    # Includes incomplete responses, connection errors and unexpected identities.
+    raise
+```
+
+Invalid local input raises `ValueError`. Incomplete output raises `IncompleteTranslationError`, a subclass of `TranslationError`. The client checks the returned model and language codes before returning a result.
+
+[More examples](https://github.com/omneity-labs/starter-translation) · [API documentation](https://api.sawalni.com/docs) · [MIT license](LICENSE).

tarjamli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tarjamli/__init__.py,sha256=a0UHJwDGgscod5B4EHzf2gxFxBSBB8hZF1-Y60mmYJU,339
+tarjamli/__main__.py,sha256=z3OQolCKD8rUd3pKYp_FISq2VctFhFl1mV-DVnaoNOM,29
+tarjamli/cli.py,sha256=IlSaA59_Uws8UXbs0gDVqwfBWhV0x3ZFSFVJAWDUf70,1263
+tarjamli/client.py,sha256=EdJFQtI6xH5Vji03Mee_Z73xBd9eT2dL6HQZSLtfaEs,4531
+tarjamli/languages.json,sha256=3CKr5vJN7wf195yrba5Ijh9trCh4wZbVqJI7Qa75Yp4,1501
+tarjamli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tarjamli-0.1.0.dist-info/licenses/LICENSE,sha256=nRQxaiQTOi3f1G6BfpYfKOMwtIj7mM6gREvd8qyjIqY,1069
+tarjamli-0.1.0.dist-info/METADATA,sha256=0D6E-jeUJtYqZfDcEfJSVjR_ph4jIVJDeXxelsuYdHI,3729
+tarjamli-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tarjamli-0.1.0.dist-info/entry_points.txt,sha256=ghwleMXtELYNk5Mw3hbB3OTYN8_dqofTR73FIQoIuMU,47
+tarjamli-0.1.0.dist-info/top_level.txt,sha256=ZvcCOuJWN_nn8ygf5F_p-QDd0-9r6bwf_au9_2WGFZU,9
+tarjamli-0.1.0.dist-info/RECORD,,

tarjamli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tarjamli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tarjamli = tarjamli.cli:main

tarjamli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Omneity Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tarjamli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tarjamli