fewertokens 0.1.0__tar.gz

fewertokens-0.1.0/LICENSE

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

fewertokens-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md pyproject.toml
+recursive-include src *.py
+recursive-exclude tests *
+prune tests

fewertokens-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: fewertokens
+Version: 0.1.0
+Summary: Python SDK for the FewerTokens API — reduce LLM token usage automatically
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# fewertokens
+
+Python SDK for **FewerTokens** — route OpenAI-compatible chat completions through the gateway to reduce token usage.
+
+## Install
+
+```bash
+pip install fewertokens
+```
+
+From this monorepo (editable):
+
+```bash
+pip install -e "./fewertokens-sdk[dev]"
+```
+
+## Quick start
+
+```python
+from fewertokens import FewerTokens
+
+client = FewerTokens(
+    api_key="tr_live_...",
+    model="gpt-4o",
+    llm_api_key="sk-...",
+    base_url="http://localhost:8000",  # your FewerTokens API host
+)
+response = client.chat.completions.create("What is Python?")
+print(response.content)
+print(response.tokens_saved)
+```
+
+## Streaming
+
+```python
+for chunk in client.chat.completions.create("Explain Docker", stream=True):
+    print(chunk.content, end="", flush=True)
+```
+
+## Async
+
+```python
+response = await client.chat.completions.acreate("Hello!")
+
+stream = await client.chat.completions.acreate("Hi", stream=True)
+async for chunk in stream:
+    print(chunk.content, end="")
+```
+
+## Specification
+
+See `ai-token-reducer/docs/SDK_SPEC.md` in the main repo for the full HTTP contract.

fewertokens-0.1.0/README.md

@@ -0,0 +1,52 @@
+# fewertokens
+
+Python SDK for **FewerTokens** — route OpenAI-compatible chat completions through the gateway to reduce token usage.
+
+## Install
+
+```bash
+pip install fewertokens
+```
+
+From this monorepo (editable):
+
+```bash
+pip install -e "./fewertokens-sdk[dev]"
+```
+
+## Quick start
+
+```python
+from fewertokens import FewerTokens
+
+client = FewerTokens(
+    api_key="tr_live_...",
+    model="gpt-4o",
+    llm_api_key="sk-...",
+    base_url="http://localhost:8000",  # your FewerTokens API host
+)
+response = client.chat.completions.create("What is Python?")
+print(response.content)
+print(response.tokens_saved)
+```
+
+## Streaming
+
+```python
+for chunk in client.chat.completions.create("Explain Docker", stream=True):
+    print(chunk.content, end="", flush=True)
+```
+
+## Async
+
+```python
+response = await client.chat.completions.acreate("Hello!")
+
+stream = await client.chat.completions.acreate("Hi", stream=True)
+async for chunk in stream:
+    print(chunk.content, end="")
+```
+
+## Specification
+
+See `ai-token-reducer/docs/SDK_SPEC.md` in the main repo for the full HTTP contract.

fewertokens-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fewertokens"
+version = "0.1.0"
+description = "Python SDK for the FewerTokens API — reduce LLM token usage automatically"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+    "ruff>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

fewertokens-0.1.0/setup.cfg

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

fewertokens-0.1.0/src/fewertokens/__init__.py

@@ -0,0 +1,29 @@
+"""Python SDK for the FewerTokens API."""
+
+from fewertokens.client import FewerTokens
+from fewertokens.types.chat import ChatResponse, StreamChunk, Usage
+from fewertokens._exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    FewerTokensError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+)
+
+__all__ = [
+    "FewerTokens",
+    "ChatResponse",
+    "StreamChunk",
+    "Usage",
+    "FewerTokensError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConnectionError",
+    "RateLimitError",
+    "ServerError",
+    "TimeoutError",
+]
+
+__version__ = "0.1.0"

fewertokens-0.1.0/src/fewertokens/_constants.py

@@ -0,0 +1,10 @@
+"""HTTP header names and defaults for the FewerTokens API."""
+
+DEFAULT_BASE_URL = "https://api.fewertokens.com"
+CHAT_COMPLETIONS_PATH = "/v1/chat/completions"
+
+HEADER_LLM_API_KEY = "x-llm-api-key"
+HEADER_LLM_PROVIDER = "x-llm-provider"
+HEADER_LLM_BASE_URL = "x-llm-base-url"
+HEADER_BYPASS_OPTIMIZATIONS = "x-bypass-optimizations"
+HEADER_TOKENS_SAVED = "x-tokens-saved"

fewertokens-0.1.0/src/fewertokens/_exceptions.py

@@ -0,0 +1,55 @@
+"""SDK exception types."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+class FewerTokensError(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class AuthenticationError(FewerTokensError):
+    """401 — invalid or missing API key."""
+
+
+class RateLimitError(FewerTokensError):
+    """429 — rate limit exceeded."""
+
+
+class BadRequestError(FewerTokensError):
+    """400 — invalid request."""
+
+
+class ServerError(FewerTokensError):
+    """500/502/503 — FewerTokens gateway or upstream LLM error."""
+
+
+class TimeoutError(FewerTokensError):
+    """Request timed out."""
+
+
+class ConnectionError(FewerTokensError):
+    """Could not connect to the FewerTokens API."""
+
+
+def _error_message_from_response_body(body: bytes) -> str | None:
+    if not body:
+        return None
+    try:
+        data: dict[str, Any] = json.loads(body.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if isinstance(data.get("detail"), str):
+        return data["detail"]
+    if isinstance(data.get("message"), str):
+        return data["message"]
+    if isinstance(data.get("error"), dict) and isinstance(data["error"].get("message"), str):
+        return data["error"]["message"]
+    return None

fewertokens-0.1.0/src/fewertokens/_http.py

@@ -0,0 +1,92 @@
+"""Headers and HTTP error mapping."""
+
+from __future__ import annotations
+
+import httpx
+
+from fewertokens._constants import (
+    HEADER_BYPASS_OPTIMIZATIONS,
+    HEADER_LLM_API_KEY,
+    HEADER_LLM_BASE_URL,
+    HEADER_LLM_PROVIDER,
+)
+from fewertokens._exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    FewerTokensError,
+    _error_message_from_response_body,
+)
+
+
+def build_headers(
+    *,
+    api_key: str,
+    llm_api_key: str | None,
+    provider: str | None,
+    llm_base_url: str | None,
+    bypass: bool,
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    if llm_api_key:
+        headers[HEADER_LLM_API_KEY] = llm_api_key
+    if provider:
+        headers[HEADER_LLM_PROVIDER] = provider
+    if llm_base_url:
+        headers[HEADER_LLM_BASE_URL] = llm_base_url
+    if bypass:
+        headers[HEADER_BYPASS_OPTIMIZATIONS] = "true"
+    return headers
+
+
+def build_headers_streaming(
+    *,
+    api_key: str,
+    llm_api_key: str | None,
+    provider: str | None,
+    llm_base_url: str | None,
+    bypass: bool,
+) -> dict[str, str]:
+    h = build_headers(
+        api_key=api_key,
+        llm_api_key=llm_api_key,
+        provider=provider,
+        llm_base_url=llm_base_url,
+        bypass=bypass,
+    )
+    h["Accept"] = "text/event-stream"
+    return h
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    status = response.status_code
+    detail = _error_message_from_response_body(response.content) or response.reason_phrase
+    message = f"HTTP {status}: {detail}"
+    if status == 401:
+        raise AuthenticationError(message, status_code=status)
+    if status == 429:
+        raise RateLimitError(message, status_code=status)
+    if status == 400:
+        raise BadRequestError(message, status_code=status)
+    if status in (500, 502, 503):
+        raise ServerError(message, status_code=status)
+    raise FewerTokensError(message, status_code=status)
+
+
+def map_httpx_exception(exc: Exception) -> FewerTokensError:
+    if isinstance(exc, httpx.TimeoutException):
+        return TimeoutError(str(exc) or "Request timed out", status_code=None)
+    if isinstance(exc, httpx.ConnectError):
+        return ConnectionError(str(exc) or "Could not connect to server", status_code=None)
+    if isinstance(exc, httpx.RequestError):
+        return ConnectionError(str(exc) or "Request failed", status_code=None)
+    return FewerTokensError(str(exc))

fewertokens-0.1.0/src/fewertokens/_providers.py

@@ -0,0 +1,24 @@
+"""Infer LLM provider from model name."""
+
+_PROVIDER_MAP: tuple[tuple[str, str], ...] = (
+    ("gpt-", "openai"),
+    ("o1", "openai"),
+    ("o3", "openai"),
+    ("gemini-", "gemini"),
+    ("claude-", "anthropic"),
+    ("llama", "ollama"),
+    ("mistral", "ollama"),
+    ("mixtral", "ollama"),
+    ("qwen", "ollama"),
+    ("deepseek", "ollama"),
+    ("phi-", "ollama"),
+    ("command-r", "ollama"),
+)
+
+
+def detect_provider(model: str) -> str:
+    m = model.lower()
+    for prefix, provider in _PROVIDER_MAP:
+        if m.startswith(prefix):
+            return provider
+    return "openai"

fewertokens-0.1.0/src/fewertokens/client.py

@@ -0,0 +1,63 @@
+"""Synchronous and async-capable FewerTokens client."""
+
+from __future__ import annotations
+
+import httpx
+
+from fewertokens._constants import DEFAULT_BASE_URL
+from fewertokens.resources.chat import Chat
+
+
+class FewerTokens:
+    """HTTP client for the FewerTokens API (OpenAI-compatible chat completions)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        model: str | None = None,
+        llm_api_key: str | None = None,
+        provider: str | None = None,
+        llm_base_url: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.model = model
+        self.llm_api_key = llm_api_key
+        self.provider = provider
+        self.llm_base_url = llm_base_url
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(base_url=self.base_url, timeout=timeout)
+        self._async_client: httpx.AsyncClient | None = None
+        self.chat = Chat(self)
+
+    @property
+    def _async(self) -> httpx.AsyncClient:
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
+        return self._async_client
+
+    def close(self) -> None:
+        self._client.close()
+
+    async def aclose(self) -> None:
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+    def __enter__(self) -> FewerTokens:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> FewerTokens:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        self.close()
+        await self.aclose()

fewertokens-0.1.0/src/fewertokens/resources/__init__.py

@@ -0,0 +1 @@
+"""API resource namespaces."""

fewertokens-0.1.0/src/fewertokens/resources/chat.py

@@ -0,0 +1,472 @@
+"""Chat completions resource (sync + async)."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, AsyncIterator, Iterator, cast
+
+import httpx
+
+from fewertokens._constants import CHAT_COMPLETIONS_PATH, HEADER_TOKENS_SAVED
+from fewertokens._http import (
+    build_headers,
+    build_headers_streaming,
+    map_httpx_exception,
+    raise_for_status,
+)
+from fewertokens._providers import detect_provider
+from fewertokens.types.chat import ChatResponse, StreamChunk, Usage
+
+if TYPE_CHECKING:
+    from fewertokens.client import FewerTokens
+
+
+class Chat:
+    def __init__(self, client: FewerTokens) -> None:
+        self._c = client
+        self.completions = ChatCompletions(client)
+
+
+class ChatCompletions:
+    def __init__(self, client: FewerTokens) -> None:
+        self._c = client
+
+    def create(
+        self,
+        prompt: str | None = None,
+        *,
+        messages: list[dict[str, str]] | None = None,
+        model: str | None = None,
+        llm_api_key: str | None = None,
+        provider: str | None = None,
+        llm_base_url: str | None = None,
+        stream: bool = False,
+        bypass: bool = False,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        **kwargs: Any,
+    ) -> ChatResponse | Iterator[StreamChunk]:
+        msgs, resolved_model = _prepare_messages_and_model(
+            prompt=prompt,
+            messages=messages,
+            model=model,
+            default_model=self._c.model,
+        )
+        if stream:
+            return self._create_stream(
+                messages=msgs,
+                model=resolved_model,
+                llm_api_key=llm_api_key,
+                provider=provider,
+                llm_base_url=llm_base_url,
+                bypass=bypass,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                top_p=top_p,
+                **kwargs,
+            )
+        return self._create_json(
+            messages=msgs,
+            model=resolved_model,
+            llm_api_key=llm_api_key,
+            provider=provider,
+            llm_base_url=llm_base_url,
+            bypass=bypass,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            **kwargs,
+        )
+
+    async def acreate(
+        self,
+        prompt: str | None = None,
+        *,
+        messages: list[dict[str, str]] | None = None,
+        model: str | None = None,
+        llm_api_key: str | None = None,
+        provider: str | None = None,
+        llm_base_url: str | None = None,
+        stream: bool = False,
+        bypass: bool = False,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        **kwargs: Any,
+    ) -> ChatResponse | AsyncIterator[StreamChunk]:
+        msgs, resolved_model = _prepare_messages_and_model(
+            prompt=prompt,
+            messages=messages,
+            model=model,
+            default_model=self._c.model,
+        )
+        if stream:
+            return self._stream_async(
+                messages=msgs,
+                model=resolved_model,
+                llm_api_key=llm_api_key,
+                provider=provider,
+                llm_base_url=llm_base_url,
+                bypass=bypass,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                top_p=top_p,
+                **kwargs,
+            )
+        return await self._acreate_json(
+            messages=msgs,
+            model=resolved_model,
+            llm_api_key=llm_api_key,
+            provider=provider,
+            llm_base_url=llm_base_url,
+            bypass=bypass,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            **kwargs,
+        )
+
+    def _create_json(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        model: str,
+        llm_api_key: str | None,
+        provider: str | None,
+        llm_base_url: str | None,
+        bypass: bool,
+        temperature: float | None,
+        max_tokens: int | None,
+        top_p: float | None,
+        **kwargs: Any,
+    ) -> ChatResponse:
+        body = _build_body(
+            model=model,
+            messages=messages,
+            stream=False,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            extra=kwargs,
+        )
+        llm_key = _coalesce(llm_api_key, self._c.llm_api_key)
+        prov = _resolve_provider(provider, self._c.provider, model)
+        base_llm = _coalesce(llm_base_url, self._c.llm_base_url)
+        headers = build_headers(
+            api_key=self._c.api_key,
+            llm_api_key=llm_key,
+            provider=prov,
+            llm_base_url=base_llm,
+            bypass=bypass,
+        )
+        try:
+            r = self._c._client.post(CHAT_COMPLETIONS_PATH, json=body, headers=headers)
+            raise_for_status(r)
+        except httpx.HTTPError as e:
+            raise map_httpx_exception(e) from e
+        data = r.json()
+        tokens_saved = _parse_tokens_saved_header(r.headers.get(HEADER_TOKENS_SAVED))
+        return _response_to_chat_response(data, tokens_saved)
+
+    async def _acreate_json(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        model: str,
+        llm_api_key: str | None,
+        provider: str | None,
+        llm_base_url: str | None,
+        bypass: bool,
+        temperature: float | None,
+        max_tokens: int | None,
+        top_p: float | None,
+        **kwargs: Any,
+    ) -> ChatResponse:
+        body = _build_body(
+            model=model,
+            messages=messages,
+            stream=False,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            extra=kwargs,
+        )
+        llm_key = _coalesce(llm_api_key, self._c.llm_api_key)
+        prov = _resolve_provider(provider, self._c.provider, model)
+        base_llm = _coalesce(llm_base_url, self._c.llm_base_url)
+        headers = build_headers(
+            api_key=self._c.api_key,
+            llm_api_key=llm_key,
+            provider=prov,
+            llm_base_url=base_llm,
+            bypass=bypass,
+        )
+        try:
+            r = await self._c._async.post(CHAT_COMPLETIONS_PATH, json=body, headers=headers)
+            raise_for_status(r)
+        except httpx.HTTPError as e:
+            raise map_httpx_exception(e) from e
+        data = r.json()
+        tokens_saved = _parse_tokens_saved_header(r.headers.get(HEADER_TOKENS_SAVED))
+        return _response_to_chat_response(data, tokens_saved)
+
+    def _create_stream(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        model: str,
+        llm_api_key: str | None,
+        provider: str | None,
+        llm_base_url: str | None,
+        bypass: bool,
+        temperature: float | None,
+        max_tokens: int | None,
+        top_p: float | None,
+        **kwargs: Any,
+    ) -> Iterator[StreamChunk]:
+        body = _build_body(
+            model=model,
+            messages=messages,
+            stream=True,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            extra=kwargs,
+        )
+        llm_key = _coalesce(llm_api_key, self._c.llm_api_key)
+        prov = _resolve_provider(provider, self._c.provider, model)
+        base_llm = _coalesce(llm_base_url, self._c.llm_base_url)
+        headers = build_headers_streaming(
+            api_key=self._c.api_key,
+            llm_api_key=llm_key,
+            provider=prov,
+            llm_base_url=base_llm,
+            bypass=bypass,
+        )
+
+        def gen() -> Iterator[StreamChunk]:
+            try:
+                with self._c._client.stream(
+                    "POST", CHAT_COMPLETIONS_PATH, json=body, headers=headers
+                ) as r:
+                    raise_for_status(r)
+                    yield from _iter_sse_sync(r)
+            except httpx.HTTPError as e:
+                raise map_httpx_exception(e) from e
+
+        return gen()
+
+    def _stream_async(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        model: str,
+        llm_api_key: str | None,
+        provider: str | None,
+        llm_base_url: str | None,
+        bypass: bool,
+        temperature: float | None,
+        max_tokens: int | None,
+        top_p: float | None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamChunk]:
+        body = _build_body(
+            model=model,
+            messages=messages,
+            stream=True,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            extra=kwargs,
+        )
+        llm_key = _coalesce(llm_api_key, self._c.llm_api_key)
+        prov = _resolve_provider(provider, self._c.provider, model)
+        base_llm = _coalesce(llm_base_url, self._c.llm_base_url)
+        headers = build_headers_streaming(
+            api_key=self._c.api_key,
+            llm_api_key=llm_key,
+            provider=prov,
+            llm_base_url=base_llm,
+            bypass=bypass,
+        )
+
+        async def agen() -> AsyncIterator[StreamChunk]:
+            try:
+                async with self._c._async.stream(
+                    "POST", CHAT_COMPLETIONS_PATH, json=body, headers=headers
+                ) as r:
+                    raise_for_status(r)
+                    async for chunk in _iter_sse_async(r):
+                        yield chunk
+            except httpx.HTTPError as e:
+                raise map_httpx_exception(e) from e
+
+        return agen()
+
+
+def _coalesce(a: str | None, b: str | None) -> str | None:
+    return a if a is not None else b
+
+
+def _resolve_provider(
+    request_provider: str | None, client_provider: str | None, model: str
+) -> str | None:
+    if request_provider is not None:
+        return request_provider
+    if client_provider is not None:
+        return client_provider
+    return detect_provider(model)
+
+
+def _prepare_messages_and_model(
+    *,
+    prompt: str | None,
+    messages: list[dict[str, str]] | None,
+    model: str | None,
+    default_model: str | None,
+) -> tuple[list[dict[str, Any]], str]:
+    if messages is not None:
+        msgs = cast(list[dict[str, Any]], list(messages))
+        resolved = model or default_model
+    elif prompt is not None:
+        msgs = [{"role": "user", "content": prompt}]
+        resolved = model or default_model
+    else:
+        raise ValueError("Either prompt (positional) or messages= must be provided")
+    if not resolved:
+        raise ValueError("model is required (pass client model= or model= on this call)")
+    return msgs, resolved
+
+
+def _build_body(
+    *,
+    model: str,
+    messages: list[dict[str, Any]],
+    stream: bool,
+    temperature: float | None,
+    max_tokens: int | None,
+    top_p: float | None,
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "model": model,
+        "messages": messages,
+        "stream": stream,
+    }
+    if temperature is not None:
+        body["temperature"] = temperature
+    if max_tokens is not None:
+        body["max_tokens"] = max_tokens
+    if top_p is not None:
+        body["top_p"] = top_p
+    body.update(extra)
+    return body
+
+
+def _parse_tokens_saved_header(raw: str | None) -> int:
+    if raw is None or raw == "":
+        return 0
+    try:
+        return int(raw)
+    except ValueError:
+        return 0
+
+
+def _content_from_message(msg: dict[str, Any]) -> str:
+    c = msg.get("content")
+    if c is None:
+        return ""
+    if isinstance(c, str):
+        return c
+    return json.dumps(c)
+
+
+def _response_to_chat_response(data: dict[str, Any], tokens_saved: int) -> ChatResponse:
+    choices = data.get("choices") or []
+    content = ""
+    finish_reason: str | None = None
+    if choices:
+        ch0 = cast(dict[str, Any], choices[0])
+        message = cast(dict[str, Any], ch0.get("message") or {})
+        content = _content_from_message(message)
+        fr = ch0.get("finish_reason")
+        finish_reason = str(fr) if fr is not None else None
+    model = str(data.get("model") or "")
+    usage = None
+    if data.get("usage"):
+        u = cast(dict[str, Any], data["usage"])
+        usage = Usage(
+            prompt_tokens=int(u.get("prompt_tokens") or 0),
+            completion_tokens=int(u.get("completion_tokens") or 0),
+            total_tokens=int(u.get("total_tokens") or 0),
+        )
+    return ChatResponse(
+        content=content,
+        model=model,
+        finish_reason=finish_reason,
+        usage=usage,
+        tokens_saved=tokens_saved,
+        raw=data,
+    )
+
+
+def _parse_stream_chunk(data: dict[str, Any]) -> StreamChunk:
+    choices = data.get("choices") or []
+    if not choices:
+        return StreamChunk(
+            content="",
+            finish_reason=None,
+            model=data.get("model") if data.get("model") is not None else None,
+            tokens_saved=0,
+        )
+    ch0 = cast(dict[str, Any], choices[0])
+    delta = cast(dict[str, Any], ch0.get("delta") or {})
+    raw_content = delta.get("content")
+    if raw_content is None:
+        content = ""
+    elif isinstance(raw_content, str):
+        content = raw_content
+    else:
+        content = str(raw_content)
+    fr = ch0.get("finish_reason")
+    finish_reason = str(fr) if fr is not None else None
+    model = data.get("model")
+    return StreamChunk(
+        content=content,
+        finish_reason=finish_reason,
+        model=str(model) if model is not None else None,
+        tokens_saved=0,
+    )
+
+
+def _iter_sse_sync(response: httpx.Response) -> Iterator[StreamChunk]:
+    for line in response.iter_lines():
+        if not line:
+            continue
+        if line.startswith("data: "):
+            payload = line[6:].strip()
+            if payload == "[DONE]":
+                return
+            try:
+                data = json.loads(payload)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(data, dict):
+                yield _parse_stream_chunk(data)
+
+
+async def _iter_sse_async(response: httpx.Response) -> AsyncIterator[StreamChunk]:
+    async for line in response.aiter_lines():
+        if not line:
+            continue
+        if line.startswith("data: "):
+            payload = line[6:].strip()
+            if payload == "[DONE]":
+                return
+            try:
+                data = json.loads(payload)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(data, dict):
+                yield _parse_stream_chunk(data)

fewertokens-0.1.0/src/fewertokens/types/__init__.py

@@ -0,0 +1,5 @@
+"""Response and usage types."""
+
+from fewertokens.types.chat import ChatResponse, StreamChunk, Usage
+
+__all__ = ["ChatResponse", "StreamChunk", "Usage"]

fewertokens-0.1.0/src/fewertokens/types/chat.py

@@ -0,0 +1,35 @@
+"""Pydantic models for chat responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Usage(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class ChatResponse(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    content: str
+    model: str
+    finish_reason: str | None = None
+    usage: Usage | None = None
+    tokens_saved: int = 0
+    raw: dict[str, Any]
+
+
+class StreamChunk(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    content: str = ""
+    finish_reason: str | None = None
+    model: str | None = None
+    tokens_saved: int = 0

fewertokens-0.1.0/src/fewertokens.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: fewertokens
+Version: 0.1.0
+Summary: Python SDK for the FewerTokens API — reduce LLM token usage automatically
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# fewertokens
+
+Python SDK for **FewerTokens** — route OpenAI-compatible chat completions through the gateway to reduce token usage.
+
+## Install
+
+```bash
+pip install fewertokens
+```
+
+From this monorepo (editable):
+
+```bash
+pip install -e "./fewertokens-sdk[dev]"
+```
+
+## Quick start
+
+```python
+from fewertokens import FewerTokens
+
+client = FewerTokens(
+    api_key="tr_live_...",
+    model="gpt-4o",
+    llm_api_key="sk-...",
+    base_url="http://localhost:8000",  # your FewerTokens API host
+)
+response = client.chat.completions.create("What is Python?")
+print(response.content)
+print(response.tokens_saved)
+```
+
+## Streaming
+
+```python
+for chunk in client.chat.completions.create("Explain Docker", stream=True):
+    print(chunk.content, end="", flush=True)
+```
+
+## Async
+
+```python
+response = await client.chat.completions.acreate("Hello!")
+
+stream = await client.chat.completions.acreate("Hi", stream=True)
+async for chunk in stream:
+    print(chunk.content, end="")
+```
+
+## Specification
+
+See `ai-token-reducer/docs/SDK_SPEC.md` in the main repo for the full HTTP contract.

fewertokens-0.1.0/src/fewertokens.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/fewertokens/__init__.py
+src/fewertokens/_constants.py
+src/fewertokens/_exceptions.py
+src/fewertokens/_http.py
+src/fewertokens/_providers.py
+src/fewertokens/client.py
+src/fewertokens.egg-info/PKG-INFO
+src/fewertokens.egg-info/SOURCES.txt
+src/fewertokens.egg-info/dependency_links.txt
+src/fewertokens.egg-info/requires.txt
+src/fewertokens.egg-info/top_level.txt
+src/fewertokens/resources/__init__.py
+src/fewertokens/resources/chat.py
+src/fewertokens/types/__init__.py
+src/fewertokens/types/chat.py

fewertokens-0.1.0/src/fewertokens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fewertokens-0.1.0/src/fewertokens.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.25.0
+pydantic>=2.0.0
+
+[dev]
+pytest>=7.4.0
+pytest-asyncio>=0.23.0
+respx>=0.21.0
+ruff>=0.1.0

fewertokens-0.1.0/src/fewertokens.egg-info/top_level.txt

@@ -0,0 +1 @@
+fewertokens