llm-conductor 1.0.0__tar.gz

llm_conductor-1.0.0/LICENSE

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

llm_conductor-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: llm-conductor
+Version: 1.0.0
+Summary: CLI pipeline for localizing nested JSON with Ollama or OpenAI-compatible LLMs
+Author: Necrofox
+License: MIT
+Project-URL: Homepage, https://github.com/Necrofox/llm-conductor
+Project-URL: Repository, https://github.com/Necrofox/llm-conductor
+Project-URL: Issues, https://github.com/Necrofox/llm-conductor/issues
+Project-URL: Changelog, https://github.com/Necrofox/llm-conductor/blob/main/CHANGELOG.md
+Keywords: localization,i18n,l10n,llm,ollama,openai,json,translation-pipeline
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0.0,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Dynamic: license-file
+
+# LLM-Conductor
+
+**CLI pipeline** for localizing nested JSON string resources with language
+models (Ollama or any OpenAI-compatible API). Optional second stage
+proofreads with a separate endpoint.
+
+This is **not** a local machine-translation product, offline dictionary, or
+GUI translator. There is no built-in MT engine — you supply the model and the
+prompts; quality follows them. Think “batch orchestration for LLM
+localization,” not “install and translate offline.”
+
+**Language pair = prompt only.** The engine does not hard-code source or
+target languages. Name them in `llm.toml`. The default `init` profile is one
+working example (often English→another language), not a product limit.
+
+## Features
+
+- Recursive JSON of any depth; non-strings left untouched
+- Per-string isolation (no batching unrelated keys into one prompt)
+- Key-name linguistic hints (`_male` / `_female` / `_plural` / …)
+- Glossary injection, formatting-tag masking, disk cache + in-run dedup
+- Reply validation, consecutive-failure breaker, OS locks, progress heartbeat
+- Independent transports for translation vs verification
+
+## Quick start
+
+### 1. Install or grab a binary
+
+```bash
+pip install -e ".[dev]"          # from a clone
+# or download llm-conductor.exe from GitHub Releases (when published)
+```
+
+PyPI upload is prepared (packaging metadata is in place) but may not be live
+yet — prefer a Release `.exe`, `pip install` from a clone, or
+`pip install git+https://github.com/Necrofox/llm-conductor.git` once the
+repo is public.
+
+### 2. Configs next to the program
+
+```bash
+llm-conductor init               # conductor.toml + llm.toml
+# portable checkout:
+python llm-conductor.py init
+```
+
+Configs resolve **beside the entry point** (exe / wrapper / installed shim),
+not cwd. Edit `llm.toml` for your endpoint and prompts; set
+`[validation].allowed_scripts` for the target writing system (e.g.
+`["cyrillic"]`, `["latin"]`, `["cjk"]`). Prefer `key_env` over literal keys.
+
+### 3. Run
+
+```bash
+llm-conductor run --target path/to/strings.json
+llm-conductor run --target path/to/strings.json --stage translate --strict
+llm-conductor run --target project/ui.list --result2target
+```
+
+Results land under `result/<target-name>/` (`translated/`, `redacted/`,
+`final/`) unless `--result2target`. See [doc/cli.md](doc/cli.md).
+
+### Ollama vs OpenAI-compatible
+
+| | Ollama | OpenAI-compatible |
+|---|---|---|
+| `type` | `ollama` | `openai` |
+| URL | `…/api/chat` | `…/v1/chat/completions` |
+| Key | ignored | `key_env` / `key` required |
+
+Point translation and verification at different hosts if you want.
+
+## Example
+
+Input (see [examples/sample.json](examples/sample.json)):
+
+```json
+{
+  "npc": {
+    "greeting_male": "Welcome, traveler.",
+    "greeting_female": "Welcome, traveler."
+  }
+}
+```
+
+Same English text, different key suffixes → separate requests and (usually)
+different grammatical forms in the target language. Full prompt rules:
+[doc/prompts.md](doc/prompts.md).
+
+## Key-name conventions
+
+| Pattern | Hint |
+|---|---|
+| `*_male`, `*_female`, `*_neutral` | gender |
+| `*_plural`, `*_singular`, `*_few`, `*_zero`, `count_*` | number |
+| `*_formal`, `*_informal` | formality |
+
+## Documentation
+
+| Doc | Topic |
+|---|---|
+| [doc/concepts.md](doc/concepts.md) | What it is / is not; isolation; language=prompt |
+| [doc/configuration.md](doc/configuration.md) | TOML split, paths, secrets |
+| [doc/cli.md](doc/cli.md) | Commands, results, exit codes |
+| [doc/prompts.md](doc/prompts.md) | Authoring prompts |
+| [doc/pipeline.md](doc/pipeline.md) | Cache, validation, resilience |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup and conventions |
+| [AGENTS.md](AGENTS.md) | Notes for AI coding agents |
+
+## Cache note
+
+Rejected model replies are not cached. A warm-cache rerun that only hits
+residual misses can exit with code `5` even if an earlier full run was `0`.
+Fix prompts/model or remeasure with `--no-cache` ([doc/cli.md](doc/cli.md)).
+
+## Roadmap (high level)
+
+- Richer input formats (e.g. subtitle adapters)
+- Optional in-stage parallelism with single-flight on the full cache key
+- Stage-local resume orthogonal to the LLM cache (concept)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Кратко (RU)
+
+**LLM-Conductor** — CLI-конвейер: гоняет строковые листья JSON через LLM
+(Ollama / OpenAI-совместимые API), опционально второй моделью вычитывает
+перевод. Это **не** локальный переводчик и не движок MT — модель и промпты
+ваши. Пара языков задаётся только текстом промпта в `llm.toml`, не схемой
+движка. Быстрый старт: `init` → правки профиля → `run --target …`. Документация
+на английском в `doc/`.

llm_conductor-1.0.0/README.md

@@ -0,0 +1,135 @@
+# LLM-Conductor
+
+**CLI pipeline** for localizing nested JSON string resources with language
+models (Ollama or any OpenAI-compatible API). Optional second stage
+proofreads with a separate endpoint.
+
+This is **not** a local machine-translation product, offline dictionary, or
+GUI translator. There is no built-in MT engine — you supply the model and the
+prompts; quality follows them. Think “batch orchestration for LLM
+localization,” not “install and translate offline.”
+
+**Language pair = prompt only.** The engine does not hard-code source or
+target languages. Name them in `llm.toml`. The default `init` profile is one
+working example (often English→another language), not a product limit.
+
+## Features
+
+- Recursive JSON of any depth; non-strings left untouched
+- Per-string isolation (no batching unrelated keys into one prompt)
+- Key-name linguistic hints (`_male` / `_female` / `_plural` / …)
+- Glossary injection, formatting-tag masking, disk cache + in-run dedup
+- Reply validation, consecutive-failure breaker, OS locks, progress heartbeat
+- Independent transports for translation vs verification
+
+## Quick start
+
+### 1. Install or grab a binary
+
+```bash
+pip install -e ".[dev]"          # from a clone
+# or download llm-conductor.exe from GitHub Releases (when published)
+```
+
+PyPI upload is prepared (packaging metadata is in place) but may not be live
+yet — prefer a Release `.exe`, `pip install` from a clone, or
+`pip install git+https://github.com/Necrofox/llm-conductor.git` once the
+repo is public.
+
+### 2. Configs next to the program
+
+```bash
+llm-conductor init               # conductor.toml + llm.toml
+# portable checkout:
+python llm-conductor.py init
+```
+
+Configs resolve **beside the entry point** (exe / wrapper / installed shim),
+not cwd. Edit `llm.toml` for your endpoint and prompts; set
+`[validation].allowed_scripts` for the target writing system (e.g.
+`["cyrillic"]`, `["latin"]`, `["cjk"]`). Prefer `key_env` over literal keys.
+
+### 3. Run
+
+```bash
+llm-conductor run --target path/to/strings.json
+llm-conductor run --target path/to/strings.json --stage translate --strict
+llm-conductor run --target project/ui.list --result2target
+```
+
+Results land under `result/<target-name>/` (`translated/`, `redacted/`,
+`final/`) unless `--result2target`. See [doc/cli.md](doc/cli.md).
+
+### Ollama vs OpenAI-compatible
+
+| | Ollama | OpenAI-compatible |
+|---|---|---|
+| `type` | `ollama` | `openai` |
+| URL | `…/api/chat` | `…/v1/chat/completions` |
+| Key | ignored | `key_env` / `key` required |
+
+Point translation and verification at different hosts if you want.
+
+## Example
+
+Input (see [examples/sample.json](examples/sample.json)):
+
+```json
+{
+  "npc": {
+    "greeting_male": "Welcome, traveler.",
+    "greeting_female": "Welcome, traveler."
+  }
+}
+```
+
+Same English text, different key suffixes → separate requests and (usually)
+different grammatical forms in the target language. Full prompt rules:
+[doc/prompts.md](doc/prompts.md).
+
+## Key-name conventions
+
+| Pattern | Hint |
+|---|---|
+| `*_male`, `*_female`, `*_neutral` | gender |
+| `*_plural`, `*_singular`, `*_few`, `*_zero`, `count_*` | number |
+| `*_formal`, `*_informal` | formality |
+
+## Documentation
+
+| Doc | Topic |
+|---|---|
+| [doc/concepts.md](doc/concepts.md) | What it is / is not; isolation; language=prompt |
+| [doc/configuration.md](doc/configuration.md) | TOML split, paths, secrets |
+| [doc/cli.md](doc/cli.md) | Commands, results, exit codes |
+| [doc/prompts.md](doc/prompts.md) | Authoring prompts |
+| [doc/pipeline.md](doc/pipeline.md) | Cache, validation, resilience |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup and conventions |
+| [AGENTS.md](AGENTS.md) | Notes for AI coding agents |
+
+## Cache note
+
+Rejected model replies are not cached. A warm-cache rerun that only hits
+residual misses can exit with code `5` even if an earlier full run was `0`.
+Fix prompts/model or remeasure with `--no-cache` ([doc/cli.md](doc/cli.md)).
+
+## Roadmap (high level)
+
+- Richer input formats (e.g. subtitle adapters)
+- Optional in-stage parallelism with single-flight on the full cache key
+- Stage-local resume orthogonal to the LLM cache (concept)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Кратко (RU)
+
+**LLM-Conductor** — CLI-конвейер: гоняет строковые листья JSON через LLM
+(Ollama / OpenAI-совместимые API), опционально второй моделью вычитывает
+перевод. Это **не** локальный переводчик и не движок MT — модель и промпты
+ваши. Пара языков задаётся только текстом промпта в `llm.toml`, не схемой
+движка. Быстрый старт: `init` → правки профиля → `run --target …`. Документация
+на английском в `doc/`.

llm_conductor-1.0.0/llm_conductor/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""LLM-Conductor: JSON localization with language models."""
+
+__version__ = "1.0.0"

llm_conductor-1.0.0/llm_conductor/__main__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""Allow ``python -m llm_conductor``."""
+
+from llm_conductor.cli.main import main
+
+if __name__ == "__main__":
+    main()

llm_conductor-1.0.0/llm_conductor/cli/exit_status.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""
+Exit code of a run that may hit several problems at once.
+
+Every problem is recorded with its code; the most severe one by
+EXIT_CODE_PRIORITY becomes the process exit code.
+"""
+import threading
+from typing import Iterable, List, NamedTuple
+
+from llm_conductor.constants import EXIT_CODE_PRIORITY, EXIT_SUCCESS
+
+
+def _checked(codes: Iterable[int]) -> List[int]:
+    """Reject codes outside the contract - an unknown code has no defined severity."""
+    checked = list(codes)
+    unknown = [code for code in checked if code not in EXIT_CODE_PRIORITY]
+    if unknown:
+        raise ValueError(f"exit codes {unknown} are not part of EXIT_CODE_PRIORITY")
+    return checked
+
+
+def most_severe(codes: Iterable[int]) -> int:
+    """
+    The code that wins by EXIT_CODE_PRIORITY.
+
+    Args:
+        codes: Exit codes; each must be listed in EXIT_CODE_PRIORITY.
+
+    Returns:
+        The most severe code, EXIT_SUCCESS for no codes.
+
+    Raises:
+        ValueError: On a code missing from EXIT_CODE_PRIORITY.
+    """
+    ranks = [EXIT_CODE_PRIORITY.index(code) for code in _checked(codes)]
+    return EXIT_CODE_PRIORITY[min(ranks)] if ranks else EXIT_SUCCESS
+
+
+class ExitRecord(NamedTuple):
+    """One recorded problem of a run."""
+
+    code: int
+    reason: str
+
+
+class ExitStatus:
+    """
+    Thread-safe accumulator of the problems of one run.
+
+    record() may be called from any thread; code and records are consistent
+    snapshots taken under the same lock.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._records: List[ExitRecord] = []
+
+    def record(self, code: int, reason: str) -> None:
+        """
+        Record a problem.
+
+        Args:
+            code: Its exit code from EXIT_CODE_PRIORITY.
+            reason: Human-readable description for the final log line.
+
+        Raises:
+            ValueError: On a code missing from EXIT_CODE_PRIORITY.
+        """
+        _checked([code])
+        with self._lock:
+            self._records.append(ExitRecord(code, reason))
+
+    @property
+    def code(self) -> int:
+        """The exit code of the run: the most severe recorded one, EXIT_SUCCESS for none."""
+        with self._lock:
+            return most_severe(record.code for record in self._records)
+
+    @property
+    def records(self) -> List[ExitRecord]:
+        """A copy of the recorded problems, in recording order."""
+        with self._lock:
+            return list(self._records)

llm_conductor-1.0.0/llm_conductor/cli/glossary.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+"""
+Where the glossary of a run comes from.
+
+The lookup chain has two levels: --glossary PATH (a missing file is an
+error), then glossary.json next to the target (file or manifest), then no
+glossary at all. A glossary is project data, so there is no shared fallback
+next to the executable - it would leak one project's terms into another.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+from llm_conductor.cli.targets import RunTarget
+from llm_conductor.constants import (
+    GLOSSARY_FILENAME,
+    GLOSSARY_ORIGIN_OPTION,
+    GLOSSARY_ORIGIN_TARGET,
+)
+from llm_conductor.core.io import safe_read_file
+from llm_conductor.exceptions import FileOperationError, TargetError
+from llm_conductor.interfaces import FileOperationsProtocol, Logger
+
+
+@dataclass(frozen=True)
+class GlossarySource:
+    """The glossary of a run and where it was found."""
+
+    terms: Dict[str, str] = field(default_factory=dict)
+    path: Optional[str] = None
+    origin: Optional[str] = None
+
+    def describe(self) -> str:
+        """One log line naming the source, its level of the chain and the number of terms."""
+        if self.path is None:
+            return "Glossary: none given and no glossary.json next to the target - working without terms"
+        return f"Glossary: {self.path} ({self.origin}), {len(self.terms)} term(s)"
+
+
+class GlossaryResolver:
+    """Walks the lookup chain and loads the glossary it finds."""
+
+    def __init__(self, file_ops: FileOperationsProtocol, logger: Logger):
+        """
+        Args:
+            file_ops: File operations for reading the glossary.
+            logger: Logger of the run.
+        """
+        self._file_ops = file_ops
+        self._logger = logger
+
+    def resolve(self, explicit_path: Optional[str], target: RunTarget) -> GlossarySource:
+        """
+        Find and load the glossary of a run.
+
+        Args:
+            explicit_path: Value of --glossary, relative to the working directory.
+            target: The run target; its directory holds the implicit glossary.json.
+
+        Returns:
+            The loaded glossary, or an empty one when the chain finds nothing.
+
+        Raises:
+            TargetError: If the explicit glossary is missing, or a found
+                glossary is unreadable or not an object of strings.
+        """
+        if explicit_path:
+            path = os.path.abspath(explicit_path)
+            if not os.path.isfile(path):
+                raise TargetError(f"Glossary {path} not found")
+            return self._load(path, GLOSSARY_ORIGIN_OPTION)
+
+        candidate = os.path.join(target.directory, GLOSSARY_FILENAME)
+        if os.path.isfile(candidate):
+            return self._load(candidate, GLOSSARY_ORIGIN_TARGET)
+        return GlossarySource()
+
+    def _load(self, path: str, origin: str) -> GlossarySource:
+        """
+        Read and check one glossary file.
+
+        Raises:
+            TargetError: If it is unreadable or not a {term: translation} object of strings.
+        """
+        try:
+            data = safe_read_file(path, f"glossary {path}", self._file_ops, self._logger,
+                                  critical=True, as_text=False)
+        except FileOperationError as e:
+            raise TargetError(str(e)) from e
+
+        if not isinstance(data, dict) or not all(
+                isinstance(term, str) and isinstance(translation, str) for term, translation in data.items()):
+            raise TargetError(f"Glossary {path} must be a JSON object mapping terms to translation strings")
+        return GlossarySource(data, path, origin)