qualitranslate 1.5.1__tar.gz

qualitranslate-1.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Yalcinkaya
+
+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.

qualitranslate-1.5.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: qualitranslate
+Version: 1.5.1
+Summary: Forward translation, blind back-translation, reconciliation and recorded human review for qualitative interview transcripts
+Author-email: Ali Yalcinkaya <aliyalcink@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AliYalcinkayaMD/qualitranslate
+Project-URL: Source, https://github.com/AliYalcinkayaMD/qualitranslate
+Project-URL: Issues, https://github.com/AliYalcinkayaMD/qualitranslate/issues
+Keywords: qualitative research,translation,back-translation,interviews,cross-language research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# QualiTranslate (Python)
+
+QualiTranslate helps research teams translate qualitative interview transcripts with large language models while keeping the steps that make translation in cross-language research defensible:
+
+**forward translation → blind back-translation → reconciliation → recorded human review**
+
+It runs on your own computer as a small local web page. Nothing is saved to disk unless you download it, and nothing is sent anywhere until you choose a translation tool.
+
+The same tool is available for R as the `qualitranslate` R package. Both versions share the prompts, the interface and the project file format, so a project started in one can be continued in the other.
+
+## Install and start
+
+You need Python 3.9 or newer. On a Mac, use the installer from [python.org](https://www.python.org/downloads/macos/) if Python is not installed yet.
+
+```bash
+python3 -m pip install qualitranslate
+qualitranslate
+```
+
+Your browser opens the workspace at `http://127.0.0.1:8765` (or the next free address shown in the Terminal). Keep the Terminal window open while you work. Press Control+C there to stop.
+
+If the `qualitranslate` command is not found, start it with `python3 -m qualitranslate`.
+
+QualiTranslate uses only the Python standard library.
+
+## What it does
+
+1. **Add a transcript.** Paste text or open a `.docx`, `.txt` or `.md` file. The app splits it into sections by speaker turn or paragraph and points out headers, notes and tables, so you can confirm what enters translation. A quick local check warns about possible identifiers (e-mail addresses, phone-like and CPR-like numbers, web addresses, full dates). It never changes your text, and it cannot find names or places.
+2. **Choose a tool.** Each stage can use a different tool:
+   - **Claude API** or **Mistral API**: automatic, with your own API key.
+   - **Any AI chat** (for example ChatGPT, Claude, Microsoft Copilot or Mistral's Le Chat), by copying a prepared prompt packet and pasting the reply back.
+3. **Translate.** The app runs forward translation, blind back-translation and reconciliation as separate requests. The back-translation request contains only the forward translation: never the original, the study context or the glossary.
+4. **Review.** Reconciliation flags possible problems by category (for example negation, omission, temporality, idioms and metaphors) and severity. A named reviewer records a decision for each section.
+5. **Download.** One ZIP holds the translation table (CSV), a side-by-side report (HTML), the project file, every prompt and reply, the audit trail and a methods record that starts with a **draft methods paragraph** for your manuscript.
+
+Try **Try the demo** first. It runs all three stages on fictional data without calling any AI service.
+
+## Model settings
+
+Under **Advanced settings** each stage has its own provider and model, plus:
+
+- **Temperature or top-p**, sent only when you set them. Some current Claude models accept only their default temperature; if a request is rejected, set it back to *Provider default*.
+- **Reasoning effort**: for Claude models that support it (`low` to `max`) and Mistral models with adjustable reasoning (`none` or `high`). It mostly matters for reconciliation, where finding subtle discrepancies benefits from more reasoning.
+- **Random seed** (Mistral only). A seed does not guarantee identical translations.
+- A **different model for blind back-translation** can catch errors that the first model would repeat. In the guided setup choose it under *Blind back-translation model*.
+
+In copy-and-paste mode these settings are not sent anywhere; set them in the chat itself if it offers them, and record what you used.
+
+Changing a later stage's settings keeps the earlier stages: for example, a new back-translation model clears only the back-translations and reconciliations.
+
+## Data protection
+
+- Text is sent only to the service you choose, in batches. Use a tool and account that your institution has approved for the data in your study, and pseudonymise transcripts first when your approval requires it.
+- API keys are kept only in memory while the app runs. They are never written to disk or included in exports.
+- Projects stay in memory until you download them.
+
+## What it does not claim
+
+Back-translation is a diagnostic aid. Separate requests to the same model are not independent human translators, and a new or temporary chat does not prove that a service has no other context. The methods record states what was actually done, including the tools, models and settings used, and does not claim validation or equivalence.
+
+## Licence
+
+MIT. See `LICENSE`.

qualitranslate-1.5.1/README.md

@@ -0,0 +1,63 @@
+# QualiTranslate (Python)
+
+QualiTranslate helps research teams translate qualitative interview transcripts with large language models while keeping the steps that make translation in cross-language research defensible:
+
+**forward translation → blind back-translation → reconciliation → recorded human review**
+
+It runs on your own computer as a small local web page. Nothing is saved to disk unless you download it, and nothing is sent anywhere until you choose a translation tool.
+
+The same tool is available for R as the `qualitranslate` R package. Both versions share the prompts, the interface and the project file format, so a project started in one can be continued in the other.
+
+## Install and start
+
+You need Python 3.9 or newer. On a Mac, use the installer from [python.org](https://www.python.org/downloads/macos/) if Python is not installed yet.
+
+```bash
+python3 -m pip install qualitranslate
+qualitranslate
+```
+
+Your browser opens the workspace at `http://127.0.0.1:8765` (or the next free address shown in the Terminal). Keep the Terminal window open while you work. Press Control+C there to stop.
+
+If the `qualitranslate` command is not found, start it with `python3 -m qualitranslate`.
+
+QualiTranslate uses only the Python standard library.
+
+## What it does
+
+1. **Add a transcript.** Paste text or open a `.docx`, `.txt` or `.md` file. The app splits it into sections by speaker turn or paragraph and points out headers, notes and tables, so you can confirm what enters translation. A quick local check warns about possible identifiers (e-mail addresses, phone-like and CPR-like numbers, web addresses, full dates). It never changes your text, and it cannot find names or places.
+2. **Choose a tool.** Each stage can use a different tool:
+   - **Claude API** or **Mistral API**: automatic, with your own API key.
+   - **Any AI chat** (for example ChatGPT, Claude, Microsoft Copilot or Mistral's Le Chat), by copying a prepared prompt packet and pasting the reply back.
+3. **Translate.** The app runs forward translation, blind back-translation and reconciliation as separate requests. The back-translation request contains only the forward translation: never the original, the study context or the glossary.
+4. **Review.** Reconciliation flags possible problems by category (for example negation, omission, temporality, idioms and metaphors) and severity. A named reviewer records a decision for each section.
+5. **Download.** One ZIP holds the translation table (CSV), a side-by-side report (HTML), the project file, every prompt and reply, the audit trail and a methods record that starts with a **draft methods paragraph** for your manuscript.
+
+Try **Try the demo** first. It runs all three stages on fictional data without calling any AI service.
+
+## Model settings
+
+Under **Advanced settings** each stage has its own provider and model, plus:
+
+- **Temperature or top-p**, sent only when you set them. Some current Claude models accept only their default temperature; if a request is rejected, set it back to *Provider default*.
+- **Reasoning effort**: for Claude models that support it (`low` to `max`) and Mistral models with adjustable reasoning (`none` or `high`). It mostly matters for reconciliation, where finding subtle discrepancies benefits from more reasoning.
+- **Random seed** (Mistral only). A seed does not guarantee identical translations.
+- A **different model for blind back-translation** can catch errors that the first model would repeat. In the guided setup choose it under *Blind back-translation model*.
+
+In copy-and-paste mode these settings are not sent anywhere; set them in the chat itself if it offers them, and record what you used.
+
+Changing a later stage's settings keeps the earlier stages: for example, a new back-translation model clears only the back-translations and reconciliations.
+
+## Data protection
+
+- Text is sent only to the service you choose, in batches. Use a tool and account that your institution has approved for the data in your study, and pseudonymise transcripts first when your approval requires it.
+- API keys are kept only in memory while the app runs. They are never written to disk or included in exports.
+- Projects stay in memory until you download them.
+
+## What it does not claim
+
+Back-translation is a diagnostic aid. Separate requests to the same model are not independent human translators, and a new or temporary chat does not prove that a service has no other context. The methods record states what was actually done, including the tools, models and settings used, and does not claim validation or equivalence.
+
+## Licence
+
+MIT. See `LICENSE`.

qualitranslate-1.5.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qualitranslate"
+version = "1.5.1"
+description = "Forward translation, blind back-translation, reconciliation and recorded human review for qualitative interview transcripts"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ali Yalcinkaya", email = "aliyalcink@gmail.com" }]
+keywords = ["qualitative research", "translation", "back-translation", "interviews", "cross-language research"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Text Processing :: Linguistic",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/AliYalcinkayaMD/qualitranslate"
+Source = "https://github.com/AliYalcinkayaMD/qualitranslate"
+Issues = "https://github.com/AliYalcinkayaMD/qualitranslate/issues"
+
+[project.scripts]
+qualitranslate = "qualitranslate.app:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qualitranslate = ["prompts.json", "web/*"]

qualitranslate-1.5.1/setup.cfg

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

qualitranslate-1.5.1/src/qualitranslate/__init__.py

@@ -0,0 +1,11 @@
+"""QualiTranslate: forward translation, blind back-translation, reconciliation and
+human review of qualitative interview transcripts, in a local browser workspace."""
+from .core import APP_VERSION as __version__
+
+__all__ = ["__version__", "main"]
+
+
+def main(argv=None):
+    """Start the local QualiTranslate workspace (same as the `qualitranslate` command)."""
+    from .app import main as _main
+    return _main(argv)

qualitranslate-1.5.1/src/qualitranslate/__main__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+raise SystemExit(main())

qualitranslate-1.5.1/src/qualitranslate/app.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Start the local QualiTranslate workspace: python3 app.py"""
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from .core import (APP_VERSION, DEMO_SOURCE, WorkflowError, Workspace, export_bundle,
+                  export_csv, export_html, methods_paragraph, read_document, read_upload)
+
+ROOT = Path(__file__).resolve().parent
+MAX_REQUEST = 25_000_000
+
+
+def make_handler(workspace, token):
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "QualiTranslate/" + APP_VERSION
+
+        def log_message(self, *args):
+            # The standard logger would print request URLs and project activity.
+            pass
+
+        def _host_ok(self):
+            return self.headers.get("Host") in {"127.0.0.1:" + str(self.server.server_port), "localhost:" + str(self.server.server_port)}
+
+        def _authorized(self):
+            origin = self.headers.get("Origin")
+            allowed = {"http://127.0.0.1:" + str(self.server.server_port), "http://localhost:" + str(self.server.server_port)}
+            supplied = self.headers.get("X-QualiTranslate-Token", "")
+            # Compare as bytes: compare_digest refuses non-ASCII str, which would drop the connection.
+            return self._host_ok() and (origin is None or origin in allowed) and secrets.compare_digest(supplied.encode("utf-8", "surrogateescape"), token.encode("utf-8"))
+
+        def _send(self, data, content_type="application/json; charset=utf-8", status=200, filename=None):
+            if not isinstance(data, bytes):
+                data = json.dumps(data, ensure_ascii=False).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Referrer-Policy", "no-referrer")
+            self.send_header("X-Frame-Options", "DENY")
+            self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'")
+            if filename:
+                self.send_header("Content-Disposition", 'attachment; filename="' + filename + '"')
+            self.end_headers()
+            self.wfile.write(data)
+
+        def do_GET(self):
+            if not self._host_ok():
+                self._send({"error": "Host rejected."}, status=403)
+                return
+            if self.path in {"/", "/index.html"}:
+                data = (ROOT / "web" / "index.html").read_text(encoding="utf-8").replace("__CSRF_TOKEN__", token)
+                self._send(data.encode(), "text/html; charset=utf-8")
+            elif self.path in {"/assets/app.js", "/assets/style.css"}:
+                filename = self.path.rsplit("/", 1)[1]
+                mime = "text/javascript; charset=utf-8" if filename.endswith(".js") else "text/css; charset=utf-8"
+                self._send((ROOT / "web" / filename).read_bytes(), mime)
+            elif self.path == "/api/state" and self._authorized():
+                state = workspace.snapshot()
+                # Exact prompt history is exported separately, not resent on each UI poll.
+                runs = state["project"].pop("runs")
+                state["project"]["run_count"] = len(runs)
+                state["project"]["last_manual_label"] = next((r.get("provenance", {}).get("tool_model_reported_by_user", "") for r in reversed(runs) if r.get("provenance", {}).get("provider") == "manual"), "")
+                state["project"]["audit_count"] = len(state["project"].pop("audit"))
+                self._send(state)
+            elif self.path == "/health":
+                self._send({"app": "QualiTranslate", "version": APP_VERSION})
+            else:
+                self._send({"error": "Not found or access denied."}, status=404)
+
+        def do_POST(self):
+            if not self._authorized():
+                self._send({"error": "Request rejected. Open the app from its local address."}, status=403)
+                return
+            try:
+                length = int(self.headers.get("Content-Length", "0"))
+                if not 0 < length <= MAX_REQUEST:
+                    self._send({"error": "Request is empty or exceeds 25 MB."}, status=413)
+                    return
+                if self.headers.get_content_type() != "application/json":
+                    raise WorkflowError("Requests must use application/json.")
+                body = json.loads(self.rfile.read(length))
+                if not isinstance(body, dict):
+                    raise WorkflowError("Request must be a JSON object.")
+                route = self.path
+                if route == "/api/import":
+                    workspace.load_text(body.get("text", ""), body.get("title", "Untitled interview"), split_speakers=body.get("split_speakers", True) is True)
+                elif route == "/api/file":
+                    self._send(read_document(body.get("filename", ""), body.get("data", "")))
+                    return
+                elif route == "/api/inspect":
+                    self._send(workspace.inspect_document(body.get("text", ""), body.get("blocks")))
+                    return
+                elif route == "/api/import-selected":
+                    workspace.import_selected(body.get("inspection_id"), body.get("included_ids"), body.get("title", "Untitled interview"), body.get("settings"), body.get("split_speakers", True) is True)
+                elif route == "/api/demo":
+                    workspace.load_text(DEMO_SOURCE, "Synthetic sample · treatment success", demo=True)
+                elif route == "/api/settings":
+                    workspace.save_settings(body.get("settings"))
+                elif route == "/api/key":
+                    workspace.set_key(body.get("provider"), body.get("key", ""))
+                elif route == "/api/models":
+                    provider = body.get("provider")
+                    with workspace.lock:
+                        key = workspace.keys.get(provider, "")
+                    self._send({"models": workspace.client.models(provider, key, body.get("workspace_id", ""))})
+                    return
+                elif route == "/api/prompt":
+                    task = workspace.prepare_task(body.get("stage"))
+                    task["copy_text"] = task["system"] + "\n\nINPUT JSON:\n" + task["user"]
+                    self._send(task)
+                    return
+                elif route == "/api/manual":
+                    workspace.apply_manual(body.get("task_id"), body.get("response", ""), body.get("model_label", ""))
+                elif route == "/api/run":
+                    workspace.start_job(body.get("stage"), demo=body.get("demo") is True,
+                                        expected_project_id=body.get('expected_project_id'),expected_revision=body.get('expected_revision'))
+                elif route == "/api/methods":
+                    self._send({"paragraph": methods_paragraph(workspace.snapshot()["project"])})
+                    return
+                elif route == "/api/stop":
+                    workspace.cancel.set()
+                elif route == "/api/edit":
+                    workspace.edit(body.get("id"), body.get("stage"), body.get("text", ""), body.get("note", ""))
+                elif route == "/api/review":
+                    workspace.review(body.get("id"), body.get("text", ""), body.get("reviewer", ""), body.get("note", ""), body.get("uncertainty") is True, body.get("method", "individual"))
+                elif route == "/api/review-batch":
+                    workspace.review_batch_minor(body.get("ids"), body.get("reviewer", ""), body.get("revision"))
+                elif route == "/api/review-clear":
+                    workspace.clear_review(body.get("id"))
+                elif route == "/api/project":
+                    workspace.import_project(body.get("project"))
+                elif route == "/api/reset":
+                    workspace.clear()
+                elif route == "/api/export":
+                    project = workspace.snapshot()["project"]
+                    kind = body.get("kind", "zip")
+                    if kind == "json":
+                        data, mime, name = json.dumps(project, ensure_ascii=False, indent=2).encode(), "application/json", "qualitranslate-project.json"
+                    elif kind == "csv":
+                        data, mime, name = export_csv(project), "text/csv; charset=utf-8", "qualitranslate-translations.csv"
+                    elif kind == "html":
+                        data, mime, name = export_html(project), "text/html; charset=utf-8", "qualitranslate-parallel-review.html"
+                    elif kind == "zip":
+                        data, mime, name = export_bundle(project), "application/zip", "qualitranslate-research-bundle.zip"
+                    else:
+                        raise WorkflowError("Unknown export format.")
+                    self._send(data, mime, filename=name)
+                    return
+                else:
+                    self._send({"error": "Unknown endpoint."}, status=404)
+                    return
+                self._send({"ok": True})
+            except (WorkflowError, json.JSONDecodeError, TypeError, ValueError, AttributeError) as exc:
+                message = str(exc) if isinstance(exc, WorkflowError) else "Invalid request format."
+                self._send({"error": message}, status=400)
+            except Exception:
+                self._send({"error": "An internal error occurred. Completed work remains in memory; export your project before restarting."}, status=500)
+
+        def do_OPTIONS(self):
+            self._send({"error": "Cross-origin access is disabled."}, status=403)
+
+    return Handler
+
+
+def running_version(port):
+    """Return the version of a QualiTranslate already serving this port, if any."""
+    try:
+        import urllib.request
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        with opener.open("http://127.0.0.1:" + str(port) + "/health", timeout=1.5) as response:
+            data = json.loads(response.read(2000))
+        return str(data.get("version", "unknown")) if data.get("app") == "QualiTranslate" else ""
+    except Exception:
+        return ""
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Local qualitative translation workspace")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--no-browser", action="store_true")
+    args = parser.parse_args(argv)
+    if not 0 <= args.port <= 65535:
+        parser.error("Port must be between 0 and 65535.")
+    workspace, token = Workspace(), secrets.token_urlsafe(32)
+    server = None
+    for port in [args.port] + ([p for p in range(args.port + 1, args.port + 11)] if args.port else []):
+        try:
+            server = ThreadingHTTPServer(("127.0.0.1", port), make_handler(workspace, token))
+            break
+        except OSError:
+            other = running_version(port)
+            if other:
+                print("Note: QualiTranslate " + other + " is already running at http://127.0.0.1:" + str(port) +
+                      " (probably in another Terminal window). This new copy will use a different address." +
+                      ("" if other == APP_VERSION else " Close the older window when you no longer need it, so you do not use the old version by mistake."))
+    if server is None:
+        print("No free local port was found. Close other QualiTranslate Terminal windows and try again.")
+        return 1
+    url = "http://127.0.0.1:" + str(server.server_port)
+    print("QualiTranslate " + APP_VERSION + "\nOpen " + url + "\nKeep this window open. Press Control+C to stop.\nProject data stays in memory until you explicitly export it. API mode sends selected text to the chosen provider.")
+    if not args.no_browser:
+        threading.Timer(0.7, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopping. In-memory project and credentials will be cleared.")
+    finally:
+        workspace.cancel.set()
+        workspace.keys.clear()
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())