xsync-cli 0.1.0__py3-none-any.whl

xsync_cli/sources/openai_compat.py

@@ -0,0 +1,117 @@
+"""The reader of an OpenAI-compatible model endpoint.
+
+This module knows nothing about a harness. It makes Model objects.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+from xsync_cli.core.model import Model
+
+
+class SourceError(Exception):
+    """The endpoint answered, but the answer is wrong."""
+
+
+class EndpointUnreachable(SourceError):
+    """The endpoint did not answer."""
+
+
+def _as_bool(value: Any) -> bool:
+    return value is True
+
+
+def _as_int(value: Any) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def parse_models(payload: dict[str, Any]) -> list[Model]:
+    """Make Model objects from a `/models` payload.
+
+    The function accepts an endpoint that reports no capabilities. The
+    absent fields then hold None or False.
+    """
+    data = payload.get("data")
+    if not isinstance(data, list):
+        raise SourceError("the answer has no `data` list. Check the base URL.")
+
+    models: list[Model] = []
+    for entry in data:
+        if not isinstance(entry, dict):
+            continue
+        slug = entry.get("id")
+        if not isinstance(slug, str) or not slug:
+            continue
+        capabilities = entry.get("capabilities")
+        if not isinstance(capabilities, dict):
+            capabilities = {}
+        context_window = _as_int(capabilities.get("contextWindow")) or _as_int(
+            entry.get("context_length")
+        )
+        max_output = _as_int(capabilities.get("maxOutput")) or _as_int(
+            entry.get("max_completion_tokens")
+        )
+        models.append(
+            Model(
+                slug=slug,
+                context_window=context_window,
+                max_output=max_output,
+                vision=_as_bool(capabilities.get("vision")),
+                reasoning=_as_bool(capabilities.get("reasoning")),
+                tools=_as_bool(capabilities.get("tools")),
+                search=_as_bool(capabilities.get("search")),
+                owned_by=entry.get("owned_by"),
+            )
+        )
+    models.sort(key=lambda model: model.slug)
+    return models
+
+
+def fetch_models(
+    base_url: str,
+    api_key: str | None,
+    timeout: float = 10.0,
+    retries: int = 2,
+    opener: Callable[..., Any] | None = None,
+) -> list[Model]:
+    """Read `{base_url}/models` and make Model objects.
+
+    The function tries the request `retries + 1` times. The `opener`
+    argument exists for the tests.
+    """
+    url = f"{base_url.rstrip('/')}/models"
+    headers = {"Accept": "application/json", "User-Agent": "xsync-cli"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    request = urllib.request.Request(url, headers=headers)
+    open_url = opener or urllib.request.urlopen
+
+    last: Exception | None = None
+    for _ in range(retries + 1):
+        try:
+            with open_url(request, timeout=timeout) as response:
+                raw = response.read()
+            break
+        except urllib.error.HTTPError as error:
+            if error.code in (401, 403):
+                raise SourceError(
+                    f"the endpoint refused the request with status {error.code}. "
+                    "Check the API key."
+                ) from None
+            last = error
+        except OSError as error:
+            last = error
+    else:
+        raise EndpointUnreachable(f"no answer from {url}: {last}") from None
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SourceError(f"the answer is not JSON: {error}") from None
+    if not isinstance(payload, dict):
+        raise SourceError("the answer is not a JSON object.")
+    return parse_models(payload)

xsync_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: xsync-cli
+Version: 0.1.0
+Summary: Sync the model list of an OpenAI-compatible endpoint into the Codex model catalog.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: tomlkit>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xsync-cli
+
+Sync the model list of an OpenAI-compatible endpoint into the Codex model
+catalog.
+
+Codex reads its model list from a large JSON catalog file. A person must
+write that file by hand. The file becomes wrong when the endpoint adds a
+model or drops a model. `xsync` writes the file for you.
+
+    xsync codex
+    wrote 35 models to /Users/you/.codex/9router-models.json
+
+## Install
+
+    uv tool install xsync-cli
+
+Or:
+
+    pipx install xsync-cli
+
+The package needs Python 3.11 or later. The command is `xsync`.
+
+## Start
+
+### 1. Make a profile
+
+    xsync setup
+
+The command asks for the profile name, the base URL, and the API key. Leave
+the key empty when the endpoint needs none. The command then reads the
+endpoint and shows every model that it serves.
+
+The last question asks for the wire API:
+
+- `chat` — most OpenAI-compatible servers.
+- `responses` — the OpenAI Responses API.
+
+A wrong value breaks every request. Ask the operator of the endpoint when
+you do not know.
+
+### 2. Connect Codex to the endpoint
+
+    xsync codex --init
+
+The command adds `[model_providers.<profile>]` to `~/.codex/config.toml` and
+points `model_catalog_json` at the catalog of the profile. Run this one time
+for each endpoint.
+
+### 3. Sync
+
+    xsync codex
+
+Run this command again when the endpoint changes.
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `xsync setup` | Make a profile. |
+| `xsync list` | Show the profiles. The active profile has a star. |
+| `xsync use <name>` | Set the active profile. |
+| `xsync remove <name>` | Delete a profile. |
+| `xsync codex` | Sync the active profile into the Codex catalog. |
+| `xsync codex --dry-run` | Show the difference. Write nothing. |
+| `xsync codex --profile <name>` | Use another profile for one run. |
+| `xsync codex --init` | Connect Codex to the endpoint of the profile. |
+| `xsync codex --reset` | Remove everything that xSync wrote. |
+| `xsync codex --reset --force` | Reset when no state file exists. |
+
+Exit codes: `0` for success, `1` for an error, `2` when the endpoint does not
+answer.
+
+## Switch between endpoints
+
+Codex holds one model provider. Therefore one profile is active at a time.
+
+    xsync codex --profile openrouter --init
+
+This command points Codex at the other endpoint and fills the catalog in one
+step.
+
+`xsync codex --profile X` without `--init` fills the catalog from X while
+Codex still routes somewhere else. Every model then fails at request time.
+xSync finds this mismatch before it writes, and it stops:
+
+    catalog would come from "openrouter" (https://openrouter.ai/api/v1)
+    but Codex routes to "9router" (http://127.0.0.1:20128/v1)
+    run: xsync codex --profile openrouter --init
+
+## The profile file
+
+Path: `~/.config/xsync/profiles.toml`. Mode: `0600`.
+
+    active = "9router"
+
+    [profiles.9router]
+    base_url = "http://127.0.0.1:20128/v1"
+    api_key = "sk-..."
+    wire_api = "responses"
+
+    [profiles.openrouter]
+    base_url = "https://openrouter.ai/api/v1"
+    api_key_env = "OPENROUTER_API_KEY"
+    wire_api = "chat"
+    exclude = ["*-embedding-*"]
+
+A profile uses `api_key` or `api_key_env`, but not both. Use `api_key_env`
+when you share the file. A profile with neither key sends no `Authorization`
+header.
+
+The `include` and `exclude` lists hold glob patterns. An empty `include`
+list keeps every model. The `exclude` list always wins.
+
+## Safety
+
+- The catalog write is atomic. xSync writes a temporary file, confirms the
+  JSON, and then replaces the target. It keeps one backup with the suffix
+  `.bak`.
+- The everyday `xsync codex` command never opens `config.toml` for writing.
+  Only `--init` and `--reset` do.
+- Codex writes `config.toml` while it runs. Therefore `--init` and `--reset`
+  hash the file before the edit and again before the replace. On a
+  difference they stop and write nothing.
+- `--reset` removes only what the state file `~/.codex/.xsync-state.json`
+  records. It never restores an old copy of `config.toml`, because Codex
+  adds project entries to that file over time.
+- With no state file, `--reset` prints the keys that it would remove and
+  then stops. Add `--force` to continue.
+- xSync never prints an API key.
+
+## What xSync reads and what it writes
+
+| File | Read | Write |
+|---|---|---|
+| `{base_url}/models` | yes | no |
+| `~/.config/xsync/profiles.toml` | yes | yes |
+| `~/.codex/<profile>-models.json` | yes | yes |
+| `~/.codex/config.toml` | yes | only with `--init` or `--reset` |
+| `~/.codex/.xsync-state.json` | yes | only with `--init` or `--reset` |
+
+## The catalog fields
+
+The Codex catalog needs 33 fields for each model. The endpoint supplies
+approximately 8 of them:
+
+| Codex field | Source |
+|---|---|
+| `slug` | the model id |
+| `context_window`, `max_context_window` | the context window |
+| `input_modalities` | the vision flag |
+| `supported_reasoning_levels` | the reasoning flag |
+| `supports_parallel_tool_calls` | the tool flag |
+| `supports_search_tool` | the search flag |
+
+The other fields come from `adapters/rules/codex.toml`. The rules apply in
+three layers. A later layer wins:
+
+1. `[defaults]`
+2. `[prefix.<first slug segment>]`
+3. `[slug."<exact slug>"]`
+
+Every default value comes from a catalog that works with codex-cli 0.153.4.
+
+## Develop
+
+    uv run --extra dev pytest
+
+No test opens a network connection.
+
+## License
+
+MIT.

xsync_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+xsync_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/cli.py,sha256=dmqD5WwnQC1xlV_zdRJFOSvF6LxVKI2psm7HJz4V9dE,10021
+xsync_cli/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/adapters/codex.py,sha256=9bD2MN6QMzTY6XPOBfkcTnqbk5xS4DeTB-JsrY7QdEY,5443
+xsync_cli/adapters/codex_config.py,sha256=wxCkKwdNV9Z0sYtc7RH_rSKFAxTmpd3OcNxPO5OdGSE,3908
+xsync_cli/adapters/codex_wiring.py,sha256=QFVQ90gJdPHQ31SfOGbpg78GX5LfueChKB4eSadG1kQ,4129
+xsync_cli/adapters/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/adapters/prompts/generic-codex.md,sha256=Wg2UOclZkU_zJ7OgmOGIXtkuxT1xl_osMrT_JoMzDXs,12982
+xsync_cli/adapters/prompts/generic-codex.messages.json,sha256=dWa5MSS1b9aNil9HyrHeofKVOXOECBWX186ryeMbsgQ,15769
+xsync_cli/adapters/prompts/gpt-5.4.md,sha256=mox33od1RakVvptw8c5GRRPXcSFTqHFpT8TVMjd2jwk,14763
+xsync_cli/adapters/prompts/gpt-5.4.messages.json,sha256=cOCgSqsYuTSpZXWktlkZURHcoY6jC_ElRTynHsCv5vY,17554
+xsync_cli/adapters/prompts/gpt-5.5.md,sha256=I1FjHfxWRNxaReqspBOUdb0CgQ7my3ktBYtVFVmzJC4,21473
+xsync_cli/adapters/prompts/gpt-5.5.messages.json,sha256=kWoCWtWGasew-VbLEMvMixukP4OZ_V1umTSvMpVISBE,23437
+xsync_cli/adapters/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/adapters/rules/codex.toml,sha256=NU5aUBLt7omIlsGMWWaJ4-nr5h9Mu6Az2MveekBvNSE,1867
+xsync_cli/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/core/atomic.py,sha256=au8JLySKqDwx0anBf5qoTk_tFxEPM49fuwe9MZcSTVU,871
+xsync_cli/core/diff.py,sha256=3Q0T8VH0pEu04Rf_xdTJQh0dRwGPatyIzVjwE7damVE,2730
+xsync_cli/core/filters.py,sha256=0wj5WEoacTDqBrCqRUmT-lxtz1MnxLQj1t9wD9zDrBU,936
+xsync_cli/core/model.py,sha256=nAabM8I5Sl2n3BYuSOtSH9saXKJ8EumKhEoLTew-UeM,901
+xsync_cli/core/profiles.py,sha256=RJ4ywpyfPQdRbOb_ptH5oJzRn2p_IHZ65HLktGbM34E,5783
+xsync_cli/sources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsync_cli/sources/openai_compat.py,sha256=XrBOjIJvjbpLRCxzJTjFSsWVDVYceGDjpzilWZunWPQ,3747
+xsync_cli-0.1.0.dist-info/METADATA,sha256=2OIUhmeSO5q_uuILs0EIYsIVFRl4RlkV96vZgfMduQ0,5655
+xsync_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+xsync_cli-0.1.0.dist-info/entry_points.txt,sha256=u2_0wRA3g5tfvI0hQGyzXcA7fAiOta0CcugQNHWEKj0,45
+xsync_cli-0.1.0.dist-info/licenses/LICENSE,sha256=sTTr3_kpXclg0Q0D564eHLyDlerOLIZemRPA99ogQBs,1066
+xsync_cli-0.1.0.dist-info/RECORD,,

xsync_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

xsync_cli-0.1.0.dist-info/entry_points.txt

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

xsync_cli-0.1.0.dist-info/licenses/LICENSE

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