local-llm-client 0.1.0__tar.gz

local_llm_client-0.1.0/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.

local_llm_client-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: local-llm-client
+Version: 0.1.0
+Summary: ローカル LLM ゲートウェイ（local-llm-server / OpenAI 互換）に繋ぐ高レベルクライアント。エージェント共通のクライアントで、openai のボイラープレートを再実装しない。
+Author: ToPo-ToPo-ToPo
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/ToPo-ToPo-ToPo/local-llm-client
+Keywords: llm,openai,client,local-llm,gateway,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0
+Dynamic: license-file
+
+# local-llm-client
+
+ローカル LLM ゲートウェイ（[local-llm-server](https://github.com/ToPo-ToPo-ToPo/local-llm-server) / OpenAI 互換）に繋ぐ**高レベルクライアント**。
+
+- サーバー（ゲートウェイ）は別パッケージ。これは**接続する側**（エージェント共通のクライアント）。
+- 各エージェントが openai のボイラープレート（メッセージ整形・画像入力・thinking 切替・ストリーム）を
+  再実装しなくて済む。
+- 依存は公式 `openai` SDK のみ。
+
+## インストール
+
+```bash
+uv add local-llm-client
+```
+
+## 使い方
+
+ゲートウェイ（`local-llm-server`）を起動しておき、公開ポートに繋ぐだけ。
+
+```python
+from local_llm_client import LLMClient
+
+llm = LLMClient(
+    model="mlx-community/Qwen3.6-27B-4bit",
+    base_url="http://127.0.0.1:8799/v1",
+)
+print(llm.respond("ローカル LLM の利点を3つ。"))
+
+# 画像入力・ストリーム
+print(llm.respond("これは何？", images=["photo.jpg"]))
+for piece in llm.respond("長い説明を", stream=True):
+    print(piece, end="", flush=True)
+```
+
+起動確認付きのワンライナー（未起動なら親切なエラー。サーバーは起動しない）:
+
+```python
+from local_llm_client import connect, ServerNotRunningError
+
+try:
+    llm = connect(model="mlx-community/Qwen3.6-27B-4bit",
+                  base_url="http://127.0.0.1:8799/v1")
+except ServerNotRunningError:
+    print("先にゲートウェイ（local-llm-server）を起動してください")
+```
+
+高度な操作（embeddings / tool calling / 構造化出力 / async など）は、土台の openai クライアントに
+`llm.openai` で直接アクセスできる。素の `openai` SDK で `base_url` を指してもよい。
+
+## ライセンス
+
+Apache-2.0

local_llm_client-0.1.0/README.md

@@ -0,0 +1,52 @@
+# local-llm-client
+
+ローカル LLM ゲートウェイ（[local-llm-server](https://github.com/ToPo-ToPo-ToPo/local-llm-server) / OpenAI 互換）に繋ぐ**高レベルクライアント**。
+
+- サーバー（ゲートウェイ）は別パッケージ。これは**接続する側**（エージェント共通のクライアント）。
+- 各エージェントが openai のボイラープレート（メッセージ整形・画像入力・thinking 切替・ストリーム）を
+  再実装しなくて済む。
+- 依存は公式 `openai` SDK のみ。
+
+## インストール
+
+```bash
+uv add local-llm-client
+```
+
+## 使い方
+
+ゲートウェイ（`local-llm-server`）を起動しておき、公開ポートに繋ぐだけ。
+
+```python
+from local_llm_client import LLMClient
+
+llm = LLMClient(
+    model="mlx-community/Qwen3.6-27B-4bit",
+    base_url="http://127.0.0.1:8799/v1",
+)
+print(llm.respond("ローカル LLM の利点を3つ。"))
+
+# 画像入力・ストリーム
+print(llm.respond("これは何？", images=["photo.jpg"]))
+for piece in llm.respond("長い説明を", stream=True):
+    print(piece, end="", flush=True)
+```
+
+起動確認付きのワンライナー（未起動なら親切なエラー。サーバーは起動しない）:
+
+```python
+from local_llm_client import connect, ServerNotRunningError
+
+try:
+    llm = connect(model="mlx-community/Qwen3.6-27B-4bit",
+                  base_url="http://127.0.0.1:8799/v1")
+except ServerNotRunningError:
+    print("先にゲートウェイ（local-llm-server）を起動してください")
+```
+
+高度な操作（embeddings / tool calling / 構造化出力 / async など）は、土台の openai クライアントに
+`llm.openai` で直接アクセスできる。素の `openai` SDK で `base_url` を指してもよい。
+
+## ライセンス
+
+Apache-2.0

local_llm_client-0.1.0/local_llm_client/__init__.py

@@ -0,0 +1,37 @@
+"""local-llm-client — ローカル LLM ゲートウェイ（OpenAI 互換）に繋ぐ高レベルクライアント。
+
+サーバー（ゲートウェイ）は別パッケージ `local-llm-server`。本パッケージは**接続する側**
+（エージェント共通のクライアント）だけを提供し、各エージェントが openai のボイラープレートを
+再実装しなくて済むようにする。依存は公式 `openai` SDK のみ。
+
+    from local_llm_client import LLMClient, connect
+
+    llm = LLMClient(model="mlx-community/Qwen3.6-27B-4bit",
+                    base_url="http://127.0.0.1:8799/v1")
+    print(llm.respond("こんにちは", images=["photo.jpg"]))
+"""
+from __future__ import annotations
+
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MODEL,
+    LLMClient,
+    ServerNotRunningError,
+    build_user_content,
+    connect,
+    is_ready,
+    thinking_extra_body,
+    to_image_url,
+)
+
+__all__ = [
+    "LLMClient",
+    "connect",
+    "ServerNotRunningError",
+    "is_ready",
+    "to_image_url",
+    "build_user_content",
+    "thinking_extra_body",
+    "DEFAULT_MODEL",
+    "DEFAULT_BASE_URL",
+]

local_llm_client-0.1.0/local_llm_client/client.py

@@ -0,0 +1,196 @@
+"""ローカル LLM ゲートウェイ（OpenAI 互換）へ繋ぐ高レベルクライアント。
+
+各エージェントが個別に書いていた「system / user / 画像をまとめて chat.completions に
+投げ、テキスト（or ストリーム）を受け取る」ラッパー。公式 `openai` SDK を土台にするため
+自動リトライ・型付きレスポンス・ツール呼び出し/構造化出力などの高度機能もそのまま使える。
+
+    from local_llm_client import LLMClient
+
+    llm = LLMClient(model="mlx-community/Qwen3.6-27B-4bit",
+                    base_url="http://127.0.0.1:8799/v1")
+    print(llm.respond("俳句を一つ詠んでください。"))
+
+起動中のゲートウェイに繋ぐワンライナー（未起動なら親切なエラー。サーバーは起動しない）
+なら connect():
+
+    from local_llm_client import connect
+
+    llm = connect(model="mlx-community/Qwen3.6-27B-4bit",
+                  base_url="http://127.0.0.1:8799/v1")
+    for piece in llm.respond("ローカル LLM の利点は？", stream=True):
+        print(piece, end="", flush=True)
+
+より高度な操作（embeddings / tool calling / 構造化出力 / async など）は、`LLMClient.openai`
+で土台の openai クライアントに直接アクセスできる。
+"""
+from __future__ import annotations
+
+import base64
+import mimetypes
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Iterator
+
+from openai import OpenAI
+
+# ゲートウェイ（local-llm-server）の既定値。クライアントは公開ポートへ繋ぐだけ。
+DEFAULT_MODEL = "mlx-community/Qwen3.6-27B-4bit"
+DEFAULT_BASE_URL = "http://127.0.0.1:8799/v1"
+
+
+class ServerNotRunningError(RuntimeError):
+    """接続先（ゲートウェイ）が応答しなかった。"""
+
+
+def is_ready(base_url: str = DEFAULT_BASE_URL, timeout: float = 1.0) -> bool:
+    """OpenAI 互換サーバー（ゲートウェイ）が応答可能かを判定する。"""
+    try:
+        with urllib.request.urlopen(f"{base_url}/models", timeout=timeout) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+def _is_url(ref: str) -> bool:
+    return ref.startswith(("http://", "https://", "data:"))
+
+
+def to_image_url(ref: str) -> str:
+    """画像参照（ローカルパス or URL）を OpenAI 互換の image_url 文字列に変換する。
+
+    URL / データURI はそのまま、ローカルファイルは base64 のデータURIにする。
+    """
+    if _is_url(ref):
+        return ref
+    path = Path(ref)
+    if not path.exists():
+        raise FileNotFoundError(f"Image not found: {ref}")
+    mime = mimetypes.guess_type(path.name)[0] or "image/png"
+    data = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime};base64,{data}"
+
+
+def build_user_content(
+    text: str, images: list[str] | None = None
+) -> str | list[dict[str, Any]]:
+    """テキスト（＋画像）を OpenAI 互換の user メッセージ content に組み立てる。
+
+    画像が無ければ素の文字列、あれば text パート＋image_url パートの配列を返す。
+    """
+    if not images:
+        return text
+    parts: list[dict[str, Any]] = [{"type": "text", "text": text}]
+    for ref in images:
+        parts.append({"type": "image_url", "image_url": {"url": to_image_url(ref)}})
+    return parts
+
+
+def thinking_extra_body(enable: bool) -> dict[str, Any]:
+    """思考(thinking)モードの ON/OFF をサーバーへ渡す extra_body を作る。
+
+    バックエンドによって解釈するキーが異なるため両形式を併記する（未知キーは無視される）:
+      - mlx-vlm      … トップレベル enable_thinking
+      - mlx_lm/llama … chat_template_kwargs.enable_thinking
+
+    chat.completions.create(..., extra_body=thinking_extra_body(False)) のように渡す。
+    """
+    return {
+        "enable_thinking": enable,
+        "chat_template_kwargs": {"enable_thinking": enable},
+    }
+
+
+class LLMClient:
+    """OpenAI 互換エンドポイント（ゲートウェイ）へ繋ぐクライアント。
+
+    respond() は非ストリームでは生成テキスト（str）を、stream=True ではテキスト断片の
+    Iterator[str] を返す。マルチモーダルは images にローカルパス/URL を渡す。土台の
+    openai クライアントは ``self.openai`` で直接使える（embeddings / tool calling など）。
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str = "not-needed",
+        temperature: float = 0.0,
+        max_tokens: int | None = None,
+        timeout: Any = None,
+    ) -> None:
+        self.model = model
+        self.base_url = base_url
+        self.temperature = float(temperature)
+        self.max_tokens = max_tokens
+        # timeout は float / httpx.Timeout / None。None のときは openai の既定に任せる
+        # （ローカルの巨大モデルは初回応答が遅いので、長め/無制限を渡せるようにする）。
+        client_kwargs: dict[str, Any] = {"base_url": base_url, "api_key": api_key}
+        if timeout is not None:
+            client_kwargs["timeout"] = timeout
+        self.openai = OpenAI(**client_kwargs)
+
+    def respond(
+        self,
+        user_text: str,
+        *,
+        system_prompt: str | None = None,
+        images: list[str] | None = None,
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> str | Iterator[str]:
+        """1 ターン生成する。stream=True なら断片の Iterator[str] を返す。"""
+        messages: list[dict[str, Any]] = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": build_user_content(user_text, images)})
+
+        params: dict[str, Any] = dict(
+            model=self.model, messages=messages, temperature=self.temperature, **kwargs
+        )
+        if self.max_tokens is not None:
+            params["max_tokens"] = self.max_tokens
+
+        if stream:
+            return self._stream(params)
+        resp = self.openai.chat.completions.create(**params)
+        return resp.choices[0].message.content or ""
+
+    def _stream(self, params: dict[str, Any]) -> Iterator[str]:
+        for chunk in self.openai.chat.completions.create(stream=True, **params):
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta.content
+            if delta:
+                yield delta
+
+
+def connect(
+    model: str = DEFAULT_MODEL,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    temperature: float = 0.0,
+    max_tokens: int | None = None,
+    timeout: Any = None,
+) -> LLMClient:
+    """**起動中のゲートウェイ**に繋いだ LLMClient を返す（サーバーは起動しない）。
+
+    挙動は 2 つだけ:
+      1. base_url が応答する … そのゲートウェイに繋いだ LLMClient を返す。
+      2. 応答しない          … ServerNotRunningError を投げる（先にゲートウェイを起動して）。
+
+    繋ぐ前に死活確認したいときの薄いワンライナー。挙動は `LLMClient(model, base_url=...)` と
+    同じだが、未起動なら早めに親切なエラーを出す。
+    """
+    if not is_ready(base_url):
+        raise ServerNotRunningError(
+            f"No gateway responding at {base_url}. Start it first (the local-llm-server "
+            "gateway / its app), then connect again."
+        )
+    return LLMClient(
+        model,
+        base_url=base_url,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        timeout=timeout,
+    )

local_llm_client-0.1.0/local_llm_client.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: local-llm-client
+Version: 0.1.0
+Summary: ローカル LLM ゲートウェイ（local-llm-server / OpenAI 互換）に繋ぐ高レベルクライアント。エージェント共通のクライアントで、openai のボイラープレートを再実装しない。
+Author: ToPo-ToPo-ToPo
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/ToPo-ToPo-ToPo/local-llm-client
+Keywords: llm,openai,client,local-llm,gateway,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0
+Dynamic: license-file
+
+# local-llm-client
+
+ローカル LLM ゲートウェイ（[local-llm-server](https://github.com/ToPo-ToPo-ToPo/local-llm-server) / OpenAI 互換）に繋ぐ**高レベルクライアント**。
+
+- サーバー（ゲートウェイ）は別パッケージ。これは**接続する側**（エージェント共通のクライアント）。
+- 各エージェントが openai のボイラープレート（メッセージ整形・画像入力・thinking 切替・ストリーム）を
+  再実装しなくて済む。
+- 依存は公式 `openai` SDK のみ。
+
+## インストール
+
+```bash
+uv add local-llm-client
+```
+
+## 使い方
+
+ゲートウェイ（`local-llm-server`）を起動しておき、公開ポートに繋ぐだけ。
+
+```python
+from local_llm_client import LLMClient
+
+llm = LLMClient(
+    model="mlx-community/Qwen3.6-27B-4bit",
+    base_url="http://127.0.0.1:8799/v1",
+)
+print(llm.respond("ローカル LLM の利点を3つ。"))
+
+# 画像入力・ストリーム
+print(llm.respond("これは何？", images=["photo.jpg"]))
+for piece in llm.respond("長い説明を", stream=True):
+    print(piece, end="", flush=True)
+```
+
+起動確認付きのワンライナー（未起動なら親切なエラー。サーバーは起動しない）:
+
+```python
+from local_llm_client import connect, ServerNotRunningError
+
+try:
+    llm = connect(model="mlx-community/Qwen3.6-27B-4bit",
+                  base_url="http://127.0.0.1:8799/v1")
+except ServerNotRunningError:
+    print("先にゲートウェイ（local-llm-server）を起動してください")
+```
+
+高度な操作（embeddings / tool calling / 構造化出力 / async など）は、土台の openai クライアントに
+`llm.openai` で直接アクセスできる。素の `openai` SDK で `base_url` を指してもよい。
+
+## ライセンス
+
+Apache-2.0

local_llm_client-0.1.0/local_llm_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+local_llm_client/__init__.py
+local_llm_client/client.py
+local_llm_client.egg-info/PKG-INFO
+local_llm_client.egg-info/SOURCES.txt
+local_llm_client.egg-info/dependency_links.txt
+local_llm_client.egg-info/requires.txt
+local_llm_client.egg-info/top_level.txt
+tests/test_client.py

local_llm_client-0.1.0/local_llm_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

local_llm_client-0.1.0/local_llm_client.egg-info/requires.txt

@@ -0,0 +1 @@
+openai>=1.0

local_llm_client-0.1.0/local_llm_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+local_llm_client

local_llm_client-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "local-llm-client"
+version = "0.1.0"
+description = "ローカル LLM ゲートウェイ（local-llm-server / OpenAI 互換）に繋ぐ高レベルクライアント。エージェント共通のクライアントで、openai のボイラープレートを再実装しない。"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "ToPo-ToPo-ToPo" }]
+keywords = ["llm", "openai", "client", "local-llm", "gateway", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Operating System :: OS Independent",
+]
+# 公式 openai SDK を土台にする（自動リトライ・型付き応答・ツール呼び出し/構造化出力）。
+# サーバー（ゲートウェイ）は別パッケージ local-llm-server。本パッケージは接続のみ。
+dependencies = [
+    "openai>=1.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/ToPo-ToPo-ToPo/local-llm-client"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["local_llm_client*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

local_llm_client-0.1.0/setup.cfg

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

local_llm_client-0.1.0/tests/test_client.py

@@ -0,0 +1,166 @@
+"""LLMClient / connect / 整形ヘルパのテスト（openai をモック、実サーバーには繋がない）。"""
+from __future__ import annotations
+
+import base64
+
+import pytest
+
+from local_llm_client import ServerNotRunningError
+from local_llm_client import client as client_mod
+from local_llm_client.client import (
+    LLMClient,
+    build_user_content,
+    connect,
+    thinking_extra_body,
+    to_image_url,
+)
+
+
+# --- マルチモーダル content 構築 -------------------------------------------
+def test_build_user_content_text_only():
+    assert build_user_content("hello") == "hello"
+
+
+def test_build_user_content_with_image_passthrough_url():
+    content = build_user_content("見て", images=["https://example.com/a.png"])
+    assert content[0] == {"type": "text", "text": "見て"}
+    assert content[1]["image_url"]["url"] == "https://example.com/a.png"
+
+
+def test_to_image_url_local_file_becomes_data_uri(tmp_path):
+    p = tmp_path / "pix.png"
+    p.write_bytes(b"\x89PNG\r\n")
+    url = to_image_url(str(p))
+    assert url.startswith("data:image/png;base64,")
+    assert base64.b64decode(url.split(",", 1)[1]) == b"\x89PNG\r\n"
+
+
+def test_to_image_url_missing_file_raises():
+    with pytest.raises(FileNotFoundError):
+        to_image_url("/no/such/file.png")
+
+
+# --- respond（openai クライアントをフェイクに差し替え） --------------------
+class _FakeMessage:
+    def __init__(self, content):
+        self.content = content
+
+
+class _FakeChoice:
+    def __init__(self, content):
+        self.message = _FakeMessage(content)
+
+
+class _FakeResp:
+    def __init__(self, content):
+        self.choices = [_FakeChoice(content)]
+
+
+class _FakeDelta:
+    def __init__(self, content):
+        self.content = content
+
+
+class _FakeStreamChoice:
+    def __init__(self, content):
+        self.delta = _FakeDelta(content)
+
+
+class _FakeStreamChunk:
+    def __init__(self, content):
+        self.choices = [_FakeStreamChoice(content)]
+
+
+class _FakeCompletions:
+    def __init__(self):
+        self.calls = []
+
+    def create(self, **kwargs):
+        self.calls.append(kwargs)
+        if kwargs.get("stream"):
+            return iter([_FakeStreamChunk("こん"), _FakeStreamChunk("にちは")])
+        return _FakeResp("done")
+
+
+class _FakeChat:
+    def __init__(self):
+        self.completions = _FakeCompletions()
+
+
+class _FakeOpenAI:
+    def __init__(self, *a, **k):
+        self.init_kwargs = k
+        self.chat = _FakeChat()
+
+
+@pytest.fixture
+def fake_openai(monkeypatch):
+    monkeypatch.setattr(client_mod, "OpenAI", _FakeOpenAI)
+
+
+def test_respond_non_stream_returns_text(fake_openai):
+    llm = LLMClient(model="m")
+    assert llm.respond("hi") == "done"
+    sent = llm.openai.chat.completions.calls[0]
+    assert sent["messages"][-1] == {"role": "user", "content": "hi"}
+
+
+def test_respond_includes_system_prompt(fake_openai):
+    llm = LLMClient(model="m")
+    llm.respond("hi", system_prompt="be brief")
+    msgs = llm.openai.chat.completions.calls[0]["messages"]
+    assert msgs[0] == {"role": "system", "content": "be brief"}
+
+
+def test_respond_stream_yields_pieces(fake_openai):
+    llm = LLMClient(model="m")
+    assert list(llm.respond("hi", stream=True)) == ["こん", "にちは"]
+
+
+def test_respond_passes_images(fake_openai):
+    llm = LLMClient(model="m")
+    llm.respond("見て", images=["https://example.com/a.png"])
+    content = llm.openai.chat.completions.calls[0]["messages"][-1]["content"]
+    assert isinstance(content, list) and content[1]["type"] == "image_url"
+
+
+def test_max_tokens_forwarded(fake_openai):
+    LLMClient(model="m", max_tokens=128).respond("hi")
+    assert LLMClient(model="m", max_tokens=128).max_tokens == 128
+
+
+def test_openai_client_accessible(fake_openai):
+    # 土台の openai クライアントに直接アクセスできる（高度操作用）。
+    llm = LLMClient(model="m", base_url="http://127.0.0.1:8080/v1")
+    assert llm.openai.init_kwargs["base_url"] == "http://127.0.0.1:8080/v1"
+
+
+def test_timeout_passed_to_openai(fake_openai):
+    # timeout を渡したときだけ openai クライアントへ伝える（None なら既定に任せる）。
+    assert "timeout" not in LLMClient(model="m").openai.init_kwargs
+    assert LLMClient(model="m", timeout=42.0).openai.init_kwargs["timeout"] == 42.0
+
+
+# --- connect（起動中ゲートウェイに繋ぐだけ。自動起動しない） ----------------
+def test_connect_returns_client_when_gateway_ready(fake_openai, monkeypatch):
+    monkeypatch.setattr(client_mod, "is_ready", lambda url, *a, **k: True)
+    llm = connect(model="m", base_url="http://127.0.0.1:8799/v1")
+    assert isinstance(llm, LLMClient)
+    assert llm.base_url == "http://127.0.0.1:8799/v1"
+
+
+def test_connect_raises_when_gateway_down(monkeypatch):
+    # 未起動なら自前で立てず、親切なエラーを投げる。
+    monkeypatch.setattr(client_mod, "is_ready", lambda url, *a, **k: False)
+    with pytest.raises(ServerNotRunningError):
+        connect(model="m", base_url="http://127.0.0.1:8799/v1")
+
+
+# --- thinking_extra_body（バックエンド protocol ヘルパ） --------------------
+def test_thinking_extra_body_emits_both_forms():
+    on = thinking_extra_body(True)
+    assert on["enable_thinking"] is True                       # mlx-vlm 形式
+    assert on["chat_template_kwargs"]["enable_thinking"] is True  # mlx_lm/llama 形式
+    off = thinking_extra_body(False)
+    assert off["enable_thinking"] is False
+    assert off["chat_template_kwargs"]["enable_thinking"] is False