bigif 1.0.0__tar.gz

bigif-1.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: bigif
+Version: 1.0.0
+Summary: The official Python SDK for the Big If True API (Big, Disco and Ticker, OpenAI-compatible).
+Author: Big If True
+License: MIT
+Project-URL: Homepage, https://bigif.org/developers/
+Project-URL: Documentation, https://bigif.org/developers/sdks/#python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+
+# bigif
+
+The official Python SDK for the [Big If True API](https://bigif.org/developers/): use Big, Disco and Ticker
+from Python with streaming, function calling, images and typed errors. Requests use your Big If True credits.
+
+```python
+from bigif import BigIfTrue
+
+client = BigIfTrue()  # reads BIGIF_API_KEY
+print(client.ask("Hello!", model="big"))
+```
+
+See https://bigif.org/developers/sdks/#python for the full guide.

bigif-1.0.0/README.md

@@ -0,0 +1,13 @@
+# bigif
+
+The official Python SDK for the [Big If True API](https://bigif.org/developers/): use Big, Disco and Ticker
+from Python with streaming, function calling, images and typed errors. Requests use your Big If True credits.
+
+```python
+from bigif import BigIfTrue
+
+client = BigIfTrue()  # reads BIGIF_API_KEY
+print(client.ask("Hello!", model="big"))
+```
+
+See https://bigif.org/developers/sdks/#python for the full guide.

bigif-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bigif"
+version = "1.0.0"
+description = "The official Python SDK for the Big If True API (Big, Disco and Ticker, OpenAI-compatible)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Big If True" }]
+dependencies = ["httpx>=0.25,<1"]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Typing :: Typed"]
+
+[project.urls]
+Homepage = "https://bigif.org/developers/"
+Documentation = "https://bigif.org/developers/sdks/#python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+bigif = ["py.typed"]

bigif-1.0.0/setup.cfg

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

bigif-1.0.0/src/bigif/__init__.py

@@ -0,0 +1,16 @@
+"""The official Python SDK for the Big If True API.
+
+    from bigif import BigIfTrue
+    client = BigIfTrue()            # reads BIGIF_API_KEY
+    client.ask("Hello", model="big")
+
+Sync (``BigIfTrue``) and async (``AsyncBigIfTrue``) clients share one shape:
+``models``, ``chat.completions``, ``completions``, ``images`` and ``ask``.
+Responses are ``APIObject`` values: dicts that also allow attribute access.
+"""
+from ._client import AsyncBigIfTrue, BigIfTrue
+from ._errors import BigIfTrueError
+from ._types import APIObject, AsyncStream, Image, Stream
+
+__version__ = "1.0.0"
+__all__ = ["BigIfTrue", "AsyncBigIfTrue", "BigIfTrueError", "APIObject", "Stream", "AsyncStream", "Image", "__version__"]

bigif-1.0.0/src/bigif/_client.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from ._errors import BigIfTrueError
+from ._types import APIObject, AsyncStream, Image, Stream
+
+DEFAULT_BASE_URL = "https://bigif.org/api/openai/v1"
+RETRY_STATUSES = {408, 409, 429, 500, 502, 503, 504}
+Messages = List[Dict[str, Any]]
+
+
+def _headers(api_key: str, app_name: Optional[str]) -> Dict[str, str]:
+    from . import __version__
+
+    headers = {"Authorization": f"Bearer {api_key}", "User-Agent": f"bigif-python/{__version__}", "Accept": "application/json"}
+    if app_name:
+        headers["X-Title"] = app_name
+    return headers
+
+
+def _delay(attempt: int, response: Optional[httpx.Response]) -> float:
+    after = response.headers.get("retry-after") if response is not None else None
+    if after and after.replace(".", "", 1).isdigit():
+        return min(float(after), 30.0)
+    return min(0.5 * 2 ** attempt, 8.0) + random.random() * 0.25
+
+
+def _error(response: httpx.Response) -> BigIfTrueError:
+    try:
+        data = response.json()
+    except ValueError:
+        data = {"error": {"message": response.text[:500] or f"HTTP {response.status_code}"}}
+    return BigIfTrueError.from_response(response.status_code, data, response.headers.get("x-request-id", ""))
+
+
+def _out_of_quota(response: httpx.Response) -> bool:
+    """A usage limit or empty credit balance won't clear by retrying."""
+    try:
+        return (response.json().get("error") or {}).get("type") == "insufficient_quota"
+    except (ValueError, AttributeError):
+        return False
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+class _Base:
+    def __init__(self, api_key: Optional[str], base_url: Optional[str], timeout: float, max_retries: int, app_name: Optional[str]) -> None:
+        self.api_key = api_key or os.environ.get("BIGIF_API_KEY") or ""
+        if not self.api_key:
+            raise BigIfTrueError("No API key. Pass api_key= or set BIGIF_API_KEY. Create one at https://bigif.org/workspace/?view=api.")
+        self.base_url = (base_url or os.environ.get("BIGIF_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.app_name = app_name
+
+
+class BigIfTrue(_Base):
+    """The Big If True API, synchronously.
+
+    ``BigIfTrue(api_key=None, base_url=None, timeout=600, max_retries=2,
+    app_name=None)``; the key defaults to ``BIGIF_API_KEY``. ``app_name`` is
+    shown as the app in your API activity log.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 600.0,
+                 max_retries: int = 2, app_name: Optional[str] = None, http_client: Optional[httpx.Client] = None) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries, app_name)
+        self._http = http_client or httpx.Client(timeout=httpx.Timeout(timeout, connect=10.0))
+        self.models = _Models(self)
+        self.chat = _Chat(self)
+        self.completions = _Completions(self)
+        self.images = _Images(self)
+
+    def request(self, method: str, path: str, body: Optional[dict] = None, *, stream: bool = False) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = _headers(self.api_key, self.app_name)
+        for attempt in range(self.max_retries + 1):
+            try:
+                request = self._http.build_request(method, url, json=body, headers=headers)
+                response = self._http.send(request, stream=stream)
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    time.sleep(_delay(attempt, None))
+                    continue
+                raise BigIfTrueError(f"Could not reach the Big If True API: {exc}") from exc
+            if response.status_code < 400:
+                return Stream(response) if stream else APIObject.wrap(response.json())
+            if stream:
+                response.read()
+            if response.status_code in RETRY_STATUSES and attempt < self.max_retries and not _out_of_quota(response):
+                response.close()
+                time.sleep(_delay(attempt, response))
+                continue
+            raise _error(response)
+        raise BigIfTrueError("The request could not be completed.")
+
+    def ask(self, prompt: str, *, model: str = "big", system: Optional[str] = None, **params: Any) -> str:
+        """One question, one answer: the reply's text."""
+        messages: Messages = ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
+        return self.chat.completions.create(model=model, messages=messages, **params).choices[0].message.content or ""
+
+    def openapi(self) -> APIObject:
+        """The API's OpenAPI description."""
+        return self.request("GET", "/openapi.json")
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "BigIfTrue":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncBigIfTrue(_Base):
+    """The Big If True API, asynchronously (same methods, awaited)."""
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 600.0,
+                 max_retries: int = 2, app_name: Optional[str] = None, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries, app_name)
+        self._http = http_client or httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=10.0))
+        self.models = _AsyncModels(self)
+        self.chat = _AsyncChat(self)
+        self.completions = _AsyncCompletions(self)
+        self.images = _AsyncImages(self)
+
+    async def request(self, method: str, path: str, body: Optional[dict] = None, *, stream: bool = False) -> Any:
+        import asyncio
+
+        url = f"{self.base_url}{path}"
+        headers = _headers(self.api_key, self.app_name)
+        for attempt in range(self.max_retries + 1):
+            try:
+                request = self._http.build_request(method, url, json=body, headers=headers)
+                response = await self._http.send(request, stream=stream)
+            except httpx.TransportError as exc:
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_delay(attempt, None))
+                    continue
+                raise BigIfTrueError(f"Could not reach the Big If True API: {exc}") from exc
+            if response.status_code < 400:
+                return AsyncStream(response) if stream else APIObject.wrap(response.json())
+            if stream:
+                await response.aread()
+            if response.status_code in RETRY_STATUSES and attempt < self.max_retries and not _out_of_quota(response):
+                await response.aclose()
+                await asyncio.sleep(_delay(attempt, response))
+                continue
+            raise _error(response)
+        raise BigIfTrueError("The request could not be completed.")
+
+    async def ask(self, prompt: str, *, model: str = "big", system: Optional[str] = None, **params: Any) -> str:
+        messages: Messages = ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
+        reply = await self.chat.completions.create(model=model, messages=messages, **params)
+        return reply.choices[0].message.content or ""
+
+    async def openapi(self) -> APIObject:
+        return await self.request("GET", "/openapi.json")
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncBigIfTrue":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+
+def _stream_body(params: Dict[str, Any], stream: bool) -> Dict[str, Any]:
+    body = _clean(params)
+    if stream:
+        body["stream"] = True
+        body.setdefault("stream_options", {"include_usage": True})
+    return body
+
+
+class _Models:
+    def __init__(self, client: BigIfTrue) -> None:
+        self._client = client
+
+    def list(self) -> List[APIObject]:
+        return self._client.request("GET", "/models").data
+
+    def retrieve(self, model: str) -> APIObject:
+        return self._client.request("GET", f"/models/{model}")
+
+
+class _ChatCompletions:
+    def __init__(self, client: BigIfTrue) -> None:
+        self._client = client
+
+    def create(self, *, model: str, messages: Messages, stream: bool = False, **params: Any) -> Union[APIObject, Stream]:
+        """POST /chat/completions. Any OpenAI field may be passed (tools,
+        response_format, top_p, seed...). With ``stream=True`` returns a Stream."""
+        body = _stream_body({"model": model, "messages": messages, **params}, stream)
+        return self._client.request("POST", "/chat/completions", body, stream=stream)
+
+
+class _Chat:
+    def __init__(self, client: BigIfTrue) -> None:
+        self.completions = _ChatCompletions(client)
+
+
+class _Completions:
+    def __init__(self, client: BigIfTrue) -> None:
+        self._client = client
+
+    def create(self, *, model: str, prompt: str, stream: bool = False, **params: Any) -> Union[APIObject, Stream]:
+        body = _stream_body({"model": model, "prompt": prompt, **params}, stream)
+        return self._client.request("POST", "/completions", body, stream=stream)
+
+
+class _Images:
+    def __init__(self, client: BigIfTrue) -> None:
+        self._client = client
+
+    def generate(self, prompt: str, **params: Any) -> Image:
+        return Image(self._client.request("POST", "/images/generations", _clean({"prompt": prompt, **params})))
+
+
+class _AsyncModels:
+    def __init__(self, client: AsyncBigIfTrue) -> None:
+        self._client = client
+
+    async def list(self) -> List[APIObject]:
+        return (await self._client.request("GET", "/models")).data
+
+    async def retrieve(self, model: str) -> APIObject:
+        return await self._client.request("GET", f"/models/{model}")
+
+
+class _AsyncChatCompletions:
+    def __init__(self, client: AsyncBigIfTrue) -> None:
+        self._client = client
+
+    async def create(self, *, model: str, messages: Messages, stream: bool = False, **params: Any) -> Union[APIObject, AsyncStream]:
+        body = _stream_body({"model": model, "messages": messages, **params}, stream)
+        return await self._client.request("POST", "/chat/completions", body, stream=stream)
+
+
+class _AsyncChat:
+    def __init__(self, client: AsyncBigIfTrue) -> None:
+        self.completions = _AsyncChatCompletions(client)
+
+
+class _AsyncCompletions:
+    def __init__(self, client: AsyncBigIfTrue) -> None:
+        self._client = client
+
+    async def create(self, *, model: str, prompt: str, stream: bool = False, **params: Any) -> Union[APIObject, AsyncStream]:
+        body = _stream_body({"model": model, "prompt": prompt, **params}, stream)
+        return await self._client.request("POST", "/completions", body, stream=stream)
+
+
+class _AsyncImages:
+    def __init__(self, client: AsyncBigIfTrue) -> None:
+        self._client = client
+
+    async def generate(self, prompt: str, **params: Any) -> Image:
+        return Image(await self._client.request("POST", "/images/generations", _clean({"prompt": prompt, **params})))

bigif-1.0.0/src/bigif/_errors.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BigIfTrueError(Exception):
+    """An error from the API (or the connection to it).
+
+    ``status`` is the HTTP status (0 for a connection failure); ``type``,
+    ``code`` and ``param`` come from the API's OpenAI-shaped error body.
+    """
+
+    def __init__(self, message: str, *, status: int = 0, type: str = "", code: Optional[str] = None,
+                 param: Optional[str] = None, request_id: str = "", body: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+        self.code = code
+        self.param = param
+        self.request_id = request_id
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"BigIfTrueError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+    @classmethod
+    def from_response(cls, status: int, data: Any, request_id: str = "") -> "BigIfTrueError":
+        error = data.get("error") if isinstance(data, dict) else None
+        if isinstance(error, dict):
+            return cls(str(error.get("message") or f"HTTP {status}"), status=status, type=str(error.get("type") or ""),
+                       code=error.get("code"), param=error.get("param"), request_id=request_id, body=data)
+        return cls(f"HTTP {status}", status=status, request_id=request_id, body=data)

bigif-1.0.0/src/bigif/_types.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, AsyncIterator, Iterator, Optional
+
+from ._errors import BigIfTrueError
+
+
+class APIObject(dict):
+    """A response object: a dict whose keys are also attributes."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            if name.startswith("__"):
+                raise AttributeError(name) from None
+            return None
+
+    @classmethod
+    def wrap(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            return cls({k: cls.wrap(v) for k, v in value.items()})
+        if isinstance(value, list):
+            return [cls.wrap(v) for v in value]
+        return value
+
+    @property
+    def text(self) -> str:
+        """A chunk's or completion's text (content delta, message or legacy text)."""
+        choices = self.get("choices") or []
+        if not choices:
+            return ""
+        choice = choices[0]
+        delta = choice.get("delta") or {}
+        message = choice.get("message") or {}
+        return delta.get("content") or message.get("content") or choice.get("text") or ""
+
+
+def _events(lines: Iterator[str]) -> Iterator[APIObject]:
+    for line in lines:
+        if not line.startswith("data:"):
+            continue
+        data = line[5:].strip()
+        if data == "[DONE]":
+            return
+        if not data:
+            continue
+        chunk = json.loads(data)
+        if isinstance(chunk, dict) and chunk.get("error"):
+            raise BigIfTrueError.from_response(200, chunk)
+        yield APIObject.wrap(chunk)
+
+
+class Stream:
+    """Iterate a streamed completion chunk by chunk. ``usage`` holds the final
+    usage (when the server sends it) and ``text`` the text so far."""
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+        self.usage: Optional[APIObject] = None
+        self.text = ""
+        self.request_id = response.headers.get("x-request-id", "")
+
+    def __iter__(self) -> Iterator[APIObject]:
+        try:
+            for chunk in _events(self._response.iter_lines()):
+                if chunk.get("usage"):
+                    self.usage = chunk["usage"]
+                self.text += chunk.text
+                yield chunk
+        finally:
+            self._response.close()
+
+    def until_done(self) -> str:
+        for _ in self:
+            pass
+        return self.text
+
+    def close(self) -> None:
+        self._response.close()
+
+    def __enter__(self) -> "Stream":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncStream:
+    """The async version of :class:`Stream` (``async for chunk in stream``)."""
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+        self.usage: Optional[APIObject] = None
+        self.text = ""
+        self.request_id = response.headers.get("x-request-id", "")
+
+    async def __aiter__(self) -> AsyncIterator[APIObject]:
+        try:
+            async for line in self._response.aiter_lines():
+                for chunk in _events(iter([line])):
+                    if chunk.get("usage"):
+                        self.usage = chunk["usage"]
+                    self.text += chunk.text
+                    yield chunk
+                if line.strip() == "data: [DONE]":
+                    return
+        finally:
+            await self._response.aclose()
+
+    async def until_done(self) -> str:
+        async for _ in self:
+            pass
+        return self.text
+
+    async def close(self) -> None:
+        await self._response.aclose()
+
+    async def __aenter__(self) -> "AsyncStream":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+
+class Image(APIObject):
+    """A generated image: ``bytes`` (when returned inline), ``url``, ``save()``."""
+
+    @property
+    def bytes(self) -> Optional[bytes]:
+        item = (self.get("data") or [{}])[0]
+        return base64.b64decode(item["b64_json"]) if item.get("b64_json") else None
+
+    @property
+    def url(self) -> Optional[str]:
+        return (self.get("data") or [{}])[0].get("url")
+
+    def save(self, path: str) -> str:
+        content = self.bytes
+        if content is None:
+            raise BigIfTrueError("This image was returned as a URL; download it from image.url.")
+        with open(path, "wb") as handle:
+            handle.write(content)
+        return path

bigif-1.0.0/src/bigif.egg-info/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: bigif
+Version: 1.0.0
+Summary: The official Python SDK for the Big If True API (Big, Disco and Ticker, OpenAI-compatible).
+Author: Big If True
+License: MIT
+Project-URL: Homepage, https://bigif.org/developers/
+Project-URL: Documentation, https://bigif.org/developers/sdks/#python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+
+# bigif
+
+The official Python SDK for the [Big If True API](https://bigif.org/developers/): use Big, Disco and Ticker
+from Python with streaming, function calling, images and typed errors. Requests use your Big If True credits.
+
+```python
+from bigif import BigIfTrue
+
+client = BigIfTrue()  # reads BIGIF_API_KEY
+print(client.ask("Hello!", model="big"))
+```
+
+See https://bigif.org/developers/sdks/#python for the full guide.

bigif-1.0.0/src/bigif.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/bigif/__init__.py
+src/bigif/_client.py
+src/bigif/_errors.py
+src/bigif/_types.py
+src/bigif/py.typed
+src/bigif.egg-info/PKG-INFO
+src/bigif.egg-info/SOURCES.txt
+src/bigif.egg-info/dependency_links.txt
+src/bigif.egg-info/requires.txt
+src/bigif.egg-info/top_level.txt
+tests/test_client.py

bigif-1.0.0/src/bigif.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bigif-1.0.0/src/bigif.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.25

bigif-1.0.0/src/bigif.egg-info/top_level.txt

@@ -0,0 +1 @@
+bigif

bigif-1.0.0/tests/test_client.py

@@ -0,0 +1,87 @@
+"""The bigif SDK against a mocked API: requests carry the key, app name and
+OpenAI fields; responses read as attributes; streams yield chunks, text and
+usage; tool-call chunks arrive; errors raise BigIfTrueError with the API's
+code; retryable failures retry but a quota error does not; async mirrors sync;
+images decode and save."""
+import base64
+import json
+
+import httpx
+import pytest
+
+from bigif import AsyncBigIfTrue, BigIfTrue, BigIfTrueError
+
+SSE = "".join(f"data: {json.dumps(c)}\n\n" for c in (
+    {"choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}}]},
+    {"choices": [{"index": 0, "delta": {"content": "Hel"}}]},
+    {"choices": [{"index": 0, "delta": {"content": "lo"}}]},
+    {"choices": [{"index": 0, "delta": {"tool_calls": [{"index": 0, "id": "c1", "function": {"name": "f", "arguments": "{}"}}]}}]},
+    {"choices": [], "usage": {"prompt_tokens": 3, "completion_tokens": 2, "bigif": {"credits": 1.5}}},
+)) + "data: [DONE]\n\n"
+
+
+def handler(seen):
+    def respond(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content or b"{}")
+        seen.append((request, body))
+        if request.url.path.endswith("/models"):
+            return httpx.Response(200, json={"object": "list", "data": [{"id": "big"}, {"id": "disco"}]})
+        if request.url.path.endswith("/images/generations"):
+            return httpx.Response(200, json={"created": 1, "data": [{"b64_json": base64.b64encode(b"png").decode()}]})
+        if body.get("model") == "broke":
+            return httpx.Response(429, json={"error": {"message": "Out of credits", "type": "insufficient_quota", "code": "insufficient_quota"}})
+        if body.get("model") == "flaky" and len(seen) < 2:
+            return httpx.Response(503, json={"error": {"message": "busy", "type": "server_error"}}, headers={"retry-after": "0"})
+        if body.get("stream"):
+            return httpx.Response(200, text=SSE, headers={"content-type": "text/event-stream", "x-request-id": "r1"})
+        return httpx.Response(200, json={"id": "x", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hi there"}, "finish_reason": "stop"}],
+                                        "usage": {"total_tokens": 5}, "bigif": {"credits": 0.5}})
+    return respond
+
+
+def client(seen, **kwargs):
+    return BigIfTrue(api_key="bit-test", app_name="Tests", http_client=httpx.Client(transport=httpx.MockTransport(handler(seen))), **kwargs)
+
+
+def test_requests_responses_and_streams():
+    seen = []
+    api = client(seen)
+    assert api.ask("Hello", model="disco", system="Be brief.", top_p=0.5) == "Hi there"
+    request, body = seen[-1]
+    assert request.headers["authorization"] == "Bearer bit-test" and request.headers["x-title"] == "Tests"
+    assert str(request.url) == "https://bigif.org/api/openai/v1/chat/completions"
+    assert body == {"model": "disco", "messages": [{"role": "system", "content": "Be brief."}, {"role": "user", "content": "Hello"}], "top_p": 0.5}
+    reply = api.chat.completions.create(model="big", messages=[{"role": "user", "content": "x"}])
+    assert reply.choices[0].message.content == "Hi there" and reply.bigif.credits == 0.5 and reply.missing is None
+    stream = api.chat.completions.create(model="big", messages=[{"role": "user", "content": "x"}], stream=True)
+    chunks = list(stream)
+    assert seen[-1][1]["stream_options"] == {"include_usage": True} and stream.text == "Hello" and stream.usage.bigif.credits == 1.5
+    assert chunks[3].choices[0].delta.tool_calls[0].function.name == "f" and stream.request_id == "r1"
+    assert [m.id for m in api.models.list()] == ["big", "disco"]
+    assert api.images.generate("a cat").bytes == b"png"
+
+
+def test_errors_and_retries(tmp_path, monkeypatch):
+    monkeypatch.setattr("bigif._client._delay", lambda *a: 0)
+    seen = []
+    api = client(seen)
+    with pytest.raises(BigIfTrueError) as error:
+        api.ask("x", model="broke")
+    assert error.value.status == 429 and error.value.code == "insufficient_quota" and len(seen) == 1
+    seen.clear()
+    assert api.ask("x", model="flaky") == "Hi there" and len(seen) == 2
+    image = api.images.generate("a dog")
+    assert open(image.save(str(tmp_path / "dog.png")), "rb").read() == b"png"
+    monkeypatch.delenv("BIGIF_API_KEY", raising=False)
+    with pytest.raises(BigIfTrueError):
+        BigIfTrue()
+
+
+@pytest.mark.asyncio
+async def test_async_client():
+    seen = []
+    async with AsyncBigIfTrue(api_key="bit-test", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler(seen)))) as api:
+        assert await api.ask("Hello") == "Hi there"
+        stream = await api.chat.completions.create(model="big", messages=[{"role": "user", "content": "x"}], stream=True)
+        assert [c.text async for c in stream][1:3] == ["Hel", "lo"] and stream.usage.prompt_tokens == 3
+        assert [m.id for m in await api.models.list()] == ["big", "disco"]