llmf 0.1.0__tar.gz

llmf-0.1.0/LICENSE

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

llmf-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: llmf
+Version: 0.1.0
+Summary: llmf (llmfree): one dead-simple call for free, keyless LLM endpoints, with automatic fallback.
+Author: Html
+License: MIT
+Project-URL: Homepage, https://github.com/MoonLite-Br/llmfree
+Project-URL: Issues, https://github.com/MoonLite-Br/llmfree/issues
+Keywords: llm,ai,chat,free,keyless,openai-compatible,fallback,termux
+Classifier: Development Status :: 3 - Alpha
+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 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# llmf (llmfree)
+
+**Một cú gọi duy nhất cho các LLM miễn phí, không cần API key.**
+Không đăng ký, không khai báo nhà cung cấp, không phụ thuộc thư viện ngoài (chỉ Python stdlib, chạy tốt trên Termux).
+
+```python
+import llmf
+
+print(llmf.chat("Xin chào, bạn là ai?"))
+```
+
+Chỉ vậy thôi. `llmf` tự chọn endpoint đang sống, tự chuyển sang nhà cung cấp khác khi lỗi, và luôn trả về cùng một kiểu dữ liệu.
+
+## Cài đặt
+
+```bash
+pip install llmf
+```
+
+Yêu cầu Python ≥ 3.8. Không có dependency.
+
+## Cú pháp thống nhất
+
+Mọi nhà cung cấp, mọi model đều dùng **cùng một hàm, cùng tham số**:
+
+```python
+llmf.chat("câu hỏi")                                   # tự động chọn + fallback
+llmf.chat("câu hỏi", model="best")                     # theo mục đích: fast | best | code | vision | reasoning
+llmf.chat("câu hỏi", model="llama")                    # gõ tên gần đúng, không phân biệt hoa/thường
+llmf.chat("câu hỏi", model="ovh/Qwen3.5-397B-A17B")    # chỉ định đích danh: nhà_cung_cấp/model
+llmf.chat("câu hỏi", model=["best", "fast"])           # thử lần lượt
+
+llmf.chat("...", system="Trả lời ngắn gọn", max_tokens=300, temperature=0.3)
+llmf.chat("Mô tả ảnh này", images=["anh.jpg"])         # ảnh: đường dẫn / URL / bytes
+llmf.chat("Trả JSON", json=True)
+llmf.chat([{"role": "user", "content": "hi"}])         # hoặc danh sách messages kiểu OpenAI
+```
+
+Kết quả là `Reply` – **một `str`** kèm metadata:
+
+```python
+r = llmf.chat("2+2=?")
+print(r)             # "4"  (đã strip, đã bỏ phần reasoning)
+r.provider, r.model  # ai đã trả lời
+r.reasoning          # chain-of-thought nếu có (không lẫn vào câu trả lời)
+r.usage, r.latency, r.attempts
+```
+
+### Streaming, hội thoại, async
+
+```python
+for piece in llmf.stream("Đếm từ 1 đến 10"):
+    print(piece, end="", flush=True)
+
+s = llmf.session(system="Bạn là trợ lý ngắn gọn")   # nhớ lịch sử
+s("Tên tôi là An")
+print(s("Tên tôi là gì?"))
+
+reply = await llmf.achat("hi")                       # async
+async for piece in llmf.astream("hi"): ...
+```
+
+Streaming chỉ fallback **trước khi** có chunk đầu tiên; sau đó lỗi sẽ được raise.
+
+## Dòng lệnh
+
+```bash
+llmf "Giải thích GIL trong Python"
+cat code.py | llmf "Review đoạn code này" -m code
+llmf -i                      # chat tương tác (/reset, /exit)
+llmf --stream "kể chuyện cười"
+llmf models                  # danh sách model (--live: hỏi trực tiếp từng nhà cung cấp)
+llmf providers
+llmf health                  # kiểm tra endpoint nào đang sống
+python -m llmf "hi"
+```
+
+## Nó hoạt động thế nào
+
+- **Chuỗi fallback** theo thứ tự nhanh/sạch nhất: `ovh → kilo-openrouter → chatjimmy → kilo-gateway → pollinations → llm7 → blockrun → freeai`.
+- Endpoint vừa lỗi bị **hạ ưu tiên (cooldown)** một lúc; lỗi 429 thì 60 giây.
+- Pollinations bị giới hạn 1 request/15s nên tự được **giãn nhịp** và xếp cuối.
+- **Làm sạch đầu ra**: bỏ `reasoning`, tách `<think>…</think>`, strip `\n\n`, bóc khối `<|stats|>` của ChatJimmy, coi câu trả lời rỗng / lỗi giấu trong HTTP 200 là thất bại để chuyển nhà khác.
+- `max_tokens` mặc định 1024 (model reasoning cần ≥ 200, nếu không `content` sẽ rỗng).
+- Không retry vô ích: lỗi tạm thời (mạng, 5xx, timeout) thử lại 1 vòng; 4xx / 429 thì bỏ qua đích đó.
+
+Khi tất cả đều thất bại sẽ có `llmf.AllProvidersFailed` với danh sách `.errors` chi tiết từng nơi.
+
+## Tuỳ biến (không bắt buộc)
+
+```python
+llmf.configure(timeout=30, exclude=["blockrun"])      # hoặc only=["ovh", "llm7"]
+
+# Thêm endpoint OpenAI-compatible của riêng bạn
+llmf.register("lab", "http://localhost:11434/v1", ["llama3"], front=True)
+
+# Endpoint hardcode bị chết? Lấy danh sách còn sống từ stillworks (opt-in)
+llmf.discover()
+
+c = llmf.Client(timeout=20)       # client độc lập, không dùng chung trạng thái
+```
+
+Biến môi trường: `LLMF_MODEL`, `LLMF_TIMEOUT`. Debug: `logging.getLogger("llmf").setLevel("DEBUG")`.
+
+## Lưu ý quan trọng
+
+- Đây là các endpoint **công khai, miễn phí, không chính thức**. Chúng có thể đổi, chậm, giới hạn hoặc biến mất bất cứ lúc nào – danh sách trong gói được xác minh ngày 2026-10-22. Hãy dùng `llmf health` và `llmf.discover()`.
+- **Đừng gửi dữ liệu nhạy cảm** (mật khẩu, khoá, dữ liệu cá nhân): prompt đi tới máy chủ bên thứ ba ẩn danh, và `discover()` còn dùng endpoint của người lạ.
+- Tôn trọng ToS và rate limit của từng dịch vụ; không spam. Dùng thương mại cần đọc điều khoản.
+- `llmf` không liên kết với bất kỳ nhà cung cấp nào.
+- Streaming trên phần lớn nhà cung cấp chưa được kiểm chứng trên endpoint thật (nếu họ không hỗ trợ, llmf nhận cả câu trả lời rồi trả một lần).
+
+## Phát triển
+
+```bash
+git clone https://github.com/MoonLite-Br/llmfree && cd llmf
+python -m unittest discover -s tests -v      # test chạy offline với server giả lập
+```
+
+Cấu trúc:
+
+```
+src/llmf/
+  client.py        Client, Session, Stream: fallback, cooldown, rate-limit
+  registry.py      danh mục provider + phân giải tên model (alias/fuzzy)
+  providers/       builtin.py (catalogue), openai_compat.py, chatjimmy.py
+  _messages.py     str/messages/ảnh -> messages chuẩn
+  _think.py        tách <think> (hỗ trợ streaming)
+  cli.py           lệnh `llmf`
+```
+
+Thêm nhà cung cấp mới tương thích OpenAI chỉ cần thêm một `ProviderSpec` vào `providers/builtin.py`.
+
+## License
+
+MIT

llmf-0.1.0/README.md

@@ -0,0 +1,136 @@
+# llmf (llmfree)
+
+**Một cú gọi duy nhất cho các LLM miễn phí, không cần API key.**
+Không đăng ký, không khai báo nhà cung cấp, không phụ thuộc thư viện ngoài (chỉ Python stdlib, chạy tốt trên Termux).
+
+```python
+import llmf
+
+print(llmf.chat("Xin chào, bạn là ai?"))
+```
+
+Chỉ vậy thôi. `llmf` tự chọn endpoint đang sống, tự chuyển sang nhà cung cấp khác khi lỗi, và luôn trả về cùng một kiểu dữ liệu.
+
+## Cài đặt
+
+```bash
+pip install llmf
+```
+
+Yêu cầu Python ≥ 3.8. Không có dependency.
+
+## Cú pháp thống nhất
+
+Mọi nhà cung cấp, mọi model đều dùng **cùng một hàm, cùng tham số**:
+
+```python
+llmf.chat("câu hỏi")                                   # tự động chọn + fallback
+llmf.chat("câu hỏi", model="best")                     # theo mục đích: fast | best | code | vision | reasoning
+llmf.chat("câu hỏi", model="llama")                    # gõ tên gần đúng, không phân biệt hoa/thường
+llmf.chat("câu hỏi", model="ovh/Qwen3.5-397B-A17B")    # chỉ định đích danh: nhà_cung_cấp/model
+llmf.chat("câu hỏi", model=["best", "fast"])           # thử lần lượt
+
+llmf.chat("...", system="Trả lời ngắn gọn", max_tokens=300, temperature=0.3)
+llmf.chat("Mô tả ảnh này", images=["anh.jpg"])         # ảnh: đường dẫn / URL / bytes
+llmf.chat("Trả JSON", json=True)
+llmf.chat([{"role": "user", "content": "hi"}])         # hoặc danh sách messages kiểu OpenAI
+```
+
+Kết quả là `Reply` – **một `str`** kèm metadata:
+
+```python
+r = llmf.chat("2+2=?")
+print(r)             # "4"  (đã strip, đã bỏ phần reasoning)
+r.provider, r.model  # ai đã trả lời
+r.reasoning          # chain-of-thought nếu có (không lẫn vào câu trả lời)
+r.usage, r.latency, r.attempts
+```
+
+### Streaming, hội thoại, async
+
+```python
+for piece in llmf.stream("Đếm từ 1 đến 10"):
+    print(piece, end="", flush=True)
+
+s = llmf.session(system="Bạn là trợ lý ngắn gọn")   # nhớ lịch sử
+s("Tên tôi là An")
+print(s("Tên tôi là gì?"))
+
+reply = await llmf.achat("hi")                       # async
+async for piece in llmf.astream("hi"): ...
+```
+
+Streaming chỉ fallback **trước khi** có chunk đầu tiên; sau đó lỗi sẽ được raise.
+
+## Dòng lệnh
+
+```bash
+llmf "Giải thích GIL trong Python"
+cat code.py | llmf "Review đoạn code này" -m code
+llmf -i                      # chat tương tác (/reset, /exit)
+llmf --stream "kể chuyện cười"
+llmf models                  # danh sách model (--live: hỏi trực tiếp từng nhà cung cấp)
+llmf providers
+llmf health                  # kiểm tra endpoint nào đang sống
+python -m llmf "hi"
+```
+
+## Nó hoạt động thế nào
+
+- **Chuỗi fallback** theo thứ tự nhanh/sạch nhất: `ovh → kilo-openrouter → chatjimmy → kilo-gateway → pollinations → llm7 → blockrun → freeai`.
+- Endpoint vừa lỗi bị **hạ ưu tiên (cooldown)** một lúc; lỗi 429 thì 60 giây.
+- Pollinations bị giới hạn 1 request/15s nên tự được **giãn nhịp** và xếp cuối.
+- **Làm sạch đầu ra**: bỏ `reasoning`, tách `<think>…</think>`, strip `\n\n`, bóc khối `<|stats|>` của ChatJimmy, coi câu trả lời rỗng / lỗi giấu trong HTTP 200 là thất bại để chuyển nhà khác.
+- `max_tokens` mặc định 1024 (model reasoning cần ≥ 200, nếu không `content` sẽ rỗng).
+- Không retry vô ích: lỗi tạm thời (mạng, 5xx, timeout) thử lại 1 vòng; 4xx / 429 thì bỏ qua đích đó.
+
+Khi tất cả đều thất bại sẽ có `llmf.AllProvidersFailed` với danh sách `.errors` chi tiết từng nơi.
+
+## Tuỳ biến (không bắt buộc)
+
+```python
+llmf.configure(timeout=30, exclude=["blockrun"])      # hoặc only=["ovh", "llm7"]
+
+# Thêm endpoint OpenAI-compatible của riêng bạn
+llmf.register("lab", "http://localhost:11434/v1", ["llama3"], front=True)
+
+# Endpoint hardcode bị chết? Lấy danh sách còn sống từ stillworks (opt-in)
+llmf.discover()
+
+c = llmf.Client(timeout=20)       # client độc lập, không dùng chung trạng thái
+```
+
+Biến môi trường: `LLMF_MODEL`, `LLMF_TIMEOUT`. Debug: `logging.getLogger("llmf").setLevel("DEBUG")`.
+
+## Lưu ý quan trọng
+
+- Đây là các endpoint **công khai, miễn phí, không chính thức**. Chúng có thể đổi, chậm, giới hạn hoặc biến mất bất cứ lúc nào – danh sách trong gói được xác minh ngày 2026-10-22. Hãy dùng `llmf health` và `llmf.discover()`.
+- **Đừng gửi dữ liệu nhạy cảm** (mật khẩu, khoá, dữ liệu cá nhân): prompt đi tới máy chủ bên thứ ba ẩn danh, và `discover()` còn dùng endpoint của người lạ.
+- Tôn trọng ToS và rate limit của từng dịch vụ; không spam. Dùng thương mại cần đọc điều khoản.
+- `llmf` không liên kết với bất kỳ nhà cung cấp nào.
+- Streaming trên phần lớn nhà cung cấp chưa được kiểm chứng trên endpoint thật (nếu họ không hỗ trợ, llmf nhận cả câu trả lời rồi trả một lần).
+
+## Phát triển
+
+```bash
+git clone https://github.com/MoonLite-Br/llmfree && cd llmf
+python -m unittest discover -s tests -v      # test chạy offline với server giả lập
+```
+
+Cấu trúc:
+
+```
+src/llmf/
+  client.py        Client, Session, Stream: fallback, cooldown, rate-limit
+  registry.py      danh mục provider + phân giải tên model (alias/fuzzy)
+  providers/       builtin.py (catalogue), openai_compat.py, chatjimmy.py
+  _messages.py     str/messages/ảnh -> messages chuẩn
+  _think.py        tách <think> (hỗ trợ streaming)
+  cli.py           lệnh `llmf`
+```
+
+Thêm nhà cung cấp mới tương thích OpenAI chỉ cần thêm một `ProviderSpec` vào `providers/builtin.py`.
+
+## License
+
+MIT

llmf-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llmf"
+dynamic = ["version"]
+description = "llmf (llmfree): one dead-simple call for free, keyless LLM endpoints, with automatic fallback."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Html" }]
+keywords = ["llm", "ai", "chat", "free", "keyless", "openai-compatible", "fallback", "termux"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/MoonLite-Br/llmfree"
+Issues = "https://github.com/MoonLite-Br/llmfree/issues"
+
+[project.scripts]
+llmf = "llmf.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "llmf._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+llmf = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

llmf-0.1.0/setup.cfg

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

llmf-0.1.0/src/llmf/__init__.py

@@ -0,0 +1,87 @@
+"""llmf (llmfree) - one simple call for free, keyless LLM endpoints.
+
+    >>> import llmf
+    >>> llmf.chat("Xin chào!")            # no key, no setup, automatic fallback
+    >>> llmf.chat("Explain GIL", model="best")
+    >>> for piece in llmf.stream("Count to 5"): print(piece, end="")
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any, List, Optional
+
+from ._version import __version__
+from .client import Client, Session, Stream
+from .errors import AllProvidersFailed, LLMFError, ModelNotFound, ProviderError
+from ._types import Attempt, HealthResult, ModelInfo, ProviderInfo, Reply
+
+_lock = threading.Lock()
+_default: Optional[Client] = None
+
+
+def default_client() -> Client:
+    """The shared client behind the module-level functions."""
+    global _default
+    with _lock:
+        if _default is None:
+            kw: dict = {}
+            if os.environ.get("LLMF_TIMEOUT"):
+                kw["timeout"] = float(os.environ["LLMF_TIMEOUT"])
+            if os.environ.get("LLMF_MODEL"):
+                kw["model"] = os.environ["LLMF_MODEL"]
+            _default = Client(**kw)
+        return _default
+
+
+def chat(prompt, **kw: Any) -> Reply:
+    return default_client().chat(prompt, **kw)
+
+
+def stream(prompt, **kw: Any) -> Stream:
+    return default_client().stream(prompt, **kw)
+
+
+async def achat(prompt, **kw: Any) -> Reply:
+    return await default_client().achat(prompt, **kw)
+
+
+def astream(prompt, **kw: Any):
+    return default_client().astream(prompt, **kw)
+
+
+def session(system: Optional[str] = None, **defaults: Any) -> Session:
+    return default_client().session(system, **defaults)
+
+
+def models(live: bool = False) -> List[ModelInfo]:
+    return default_client().models(live=live)
+
+
+def providers() -> List[ProviderInfo]:
+    return default_client().providers()
+
+
+def health() -> List[HealthResult]:
+    return default_client().health()
+
+
+def register(*a: Any, **kw: Any):
+    return default_client().register(*a, **kw)
+
+
+def discover(**kw: Any) -> List[str]:
+    return default_client().discover(**kw)
+
+
+def configure(**kw: Any) -> Client:
+    return default_client().configure(**kw)
+
+
+__all__ = [
+    "__version__", "Client", "Session", "Stream", "Reply", "chat", "stream", "achat", "astream",
+    "session", "models", "providers", "health", "register", "discover", "configure",
+    "default_client", "LLMFError", "ProviderError", "AllProvidersFailed", "ModelNotFound",
+    "Attempt", "HealthResult", "ModelInfo", "ProviderInfo",
+]

llmf-0.1.0/src/llmf/__main__.py

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

llmf-0.1.0/src/llmf/_http.py

@@ -0,0 +1,67 @@
+"""Tiny stdlib HTTP layer (no third-party dependencies)."""
+
+from __future__ import annotations
+
+import gzip
+import http.client
+import socket
+import ssl
+import urllib.error
+import urllib.request
+from typing import Dict, Optional
+
+from ._version import __version__
+
+DEFAULT_UA = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/130.0.0.0 Safari/537.36 llmf/%s" % __version__
+)
+
+NETWORK_ERRORS = (OSError, http.client.HTTPException, ssl.SSLError, socket.timeout)
+
+
+class HTTPFailure(Exception):
+    """Transport-level failure. ``status is None`` means no HTTP response."""
+
+    def __init__(self, status: Optional[int], body: str = "", kind: str = "http") -> None:
+        self.status = status
+        self.body = body
+        self.kind = kind  # "http" | "timeout" | "network"
+        super().__init__("%s %s" % (status if status is not None else kind, body[:120]))
+
+
+def decode_body(resp) -> str:
+    data = resp.read()
+    if resp.headers.get("Content-Encoding", "").lower() == "gzip":
+        try:
+            data = gzip.decompress(data)
+        except OSError:
+            pass
+    return data.decode("utf-8", "replace")
+
+
+def open_url(
+    url: str,
+    *,
+    headers: Dict[str, str],
+    data: Optional[bytes] = None,
+    timeout: float = 60.0,
+):
+    """Open ``url`` and return the response object (caller must close it)."""
+    req = urllib.request.Request(url, data=data, headers=headers)
+    try:
+        return urllib.request.urlopen(req, timeout=timeout)
+    except urllib.error.HTTPError as e:
+        try:
+            body = decode_body(e)
+        except Exception:  # pragma: no cover - body unreadable
+            body = ""
+        raise HTTPFailure(e.code, body) from None
+    except urllib.error.URLError as e:
+        reason = e.reason
+        kind = "timeout" if isinstance(reason, (socket.timeout, TimeoutError)) else "network"
+        raise HTTPFailure(None, str(reason), kind) from None
+    except (socket.timeout, TimeoutError) as e:
+        raise HTTPFailure(None, str(e) or "timed out", "timeout") from None
+    except NETWORK_ERRORS as e:
+        raise HTTPFailure(None, str(e), "network") from None

llmf-0.1.0/src/llmf/_messages.py

@@ -0,0 +1,60 @@
+"""Turn friendly inputs (str / messages / images) into OpenAI-style messages."""
+
+from __future__ import annotations
+
+import base64
+import copy
+import mimetypes
+import os
+from typing import Any, List, Optional, Sequence, Union
+
+Prompt = Union[str, Sequence[dict]]
+
+
+def _sniff(data: bytes) -> str:
+    if data.startswith(b"\x89PNG"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8"):
+        return "image/jpeg"
+    if data.startswith(b"GIF8"):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return "application/octet-stream"
+
+
+def image_url(img: Any) -> str:
+    """URL / data-URI / local path / raw bytes -> something an API accepts."""
+    if isinstance(img, (bytes, bytearray)):
+        data = bytes(img)
+        return "data:%s;base64,%s" % (_sniff(data), base64.b64encode(data).decode())
+    s = str(img)
+    if s.startswith(("http://", "https://", "data:")):
+        return s
+    if os.path.isfile(s):
+        with open(s, "rb") as f:
+            data = f.read()
+        mime = mimetypes.guess_type(s)[0] or _sniff(data)
+        return "data:%s;base64,%s" % (mime, base64.b64encode(data).decode())
+    raise FileNotFoundError("image not found: %r" % s)
+
+
+def build_messages(prompt: Prompt, system: Optional[str] = None,
+                   images: Optional[Sequence[Any]] = None) -> List[dict]:
+    if isinstance(prompt, str):
+        msgs: List[dict] = [{"role": "user", "content": prompt}]
+    else:
+        msgs = copy.deepcopy([dict(m) for m in prompt])
+        if not msgs:
+            raise ValueError("messages must not be empty")
+    if images:
+        idx = next((i for i in range(len(msgs) - 1, -1, -1) if msgs[i].get("role") == "user"), None)
+        if idx is None:
+            raise ValueError("images need a user message to attach to")
+        content = msgs[idx].get("content", "")
+        parts = [{"type": "text", "text": content}] if isinstance(content, str) else list(content)
+        parts += [{"type": "image_url", "image_url": {"url": image_url(i)}} for i in images]
+        msgs[idx]["content"] = parts
+    if system and not (msgs and msgs[0].get("role") == "system"):
+        msgs.insert(0, {"role": "system", "content": system})
+    return msgs

llmf-0.1.0/src/llmf/_think.py

@@ -0,0 +1,84 @@
+"""Split ``<think>...</think>`` reasoning out of a (possibly streamed) text."""
+
+from __future__ import annotations
+
+from typing import List
+
+OPEN = "<think>"
+CLOSE = "</think>"
+
+
+def _partial_suffix(s: str, token: str) -> int:
+    """Length of the longest proper prefix of ``token`` that ``s`` ends with."""
+    for k in range(min(len(token) - 1, len(s)), 0, -1):
+        if s.endswith(token[:k]):
+            return k
+    return 0
+
+
+class ThinkSplitter:
+    """Incremental splitter. ``feed()`` returns the visible text for a chunk."""
+
+    def __init__(self) -> None:
+        self._buf = ""
+        self._inside = False
+        self._started = False  # visible text has begun (for leading-space trim)
+        self.thought: List[str] = []
+
+    def _emit(self, text: str) -> str:
+        if not self._started:
+            text = text.lstrip()
+            if text:
+                self._started = True
+        return text
+
+    def feed(self, chunk: str) -> str:
+        self._buf += chunk
+        out: List[str] = []
+        while True:
+            if not self._inside:
+                i = self._buf.find(OPEN)
+                if i >= 0:
+                    out.append(self._buf[:i])
+                    self._buf = self._buf[i + len(OPEN):]
+                    self._inside = True
+                    continue
+                keep = _partial_suffix(self._buf, OPEN)
+                cut = len(self._buf) - keep
+                out.append(self._buf[:cut])
+                self._buf = self._buf[cut:]
+                break
+            j = self._buf.find(CLOSE)
+            if j >= 0:
+                self.thought.append(self._buf[:j])
+                self._buf = self._buf[j + len(CLOSE):]
+                self._inside = False
+                continue
+            keep = _partial_suffix(self._buf, CLOSE)
+            cut = len(self._buf) - keep
+            self.thought.append(self._buf[:cut])
+            self._buf = self._buf[cut:]
+            break
+        return self._emit("".join(out))
+
+    def flush(self) -> str:
+        rest, self._buf = self._buf, ""
+        if self._inside:
+            self.thought.append(rest)
+            return ""
+        return self._emit(rest)
+
+    @property
+    def reasoning(self) -> str:
+        return "".join(self.thought).strip()
+
+
+def split_think(text: str):
+    """Non-streaming helper -> ``(visible_text, reasoning_or_None)``."""
+    # Some templates only emit the closing tag (the opening one is in the prompt).
+    if CLOSE in text and OPEN not in text:
+        thought, _, text = text.partition(CLOSE)
+        return text.strip(), (thought.strip() or None)
+    sp = ThinkSplitter()
+    visible = sp.feed(text) + sp.flush()
+    return visible.strip(), (sp.reasoning or None)