answerline 0.3.0__tar.gz → 0.6.0__tar.gz

{answerline-0.3.0/src/answerline.egg-info → answerline-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: answerline
-Version: 0.3.0
+Version: 0.6.0
 Summary: Python client for the AnswerLine answer and search monitoring API.
 Author-email: AnswerLine <support@answerline.dev>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 Python client for the [AnswerLine](https://answerline.dev) API — structured JSON answers from AI assistants
 (ChatGPT, Perplexity, Gemini, Copilot, Grok) and Google surfaces (Search, News, AI Overview, AI Mode), on httpx.
 
-ChatGPT, Gemini, Copilot, Google Search (with AI Overview), AI Mode and Google News are served today; Perplexity and Grok are paused for now and coming back soon. [Coverage](https://answerline.dev/docs/coverage) lists what is served and from which countries. A monitor call to a paused engine fails with a 404 and an async task with a 422, each saying so, and nothing is billed.
+All eight engines are served. [Coverage](https://answerline.dev/docs/coverage) lists the countries each one is served from.
 
 ```bash
 pip install answerline
@@ -37,6 +37,10 @@ with Client("sk_...") as client:
     # copilot, grok, aimode, google, google_news), or client.monitor(engine, **body).
     answer = client.monitor.chatgpt(prompt="iPhone 17 or Galaxy S26?", country="US")
 
+    # A US state: ChatGPT answers from inside Texas; every other engine answers it for the whole US.
+    # A state implies country "US"; with another country it is refused with a 400.
+    texas = client.monitor.chatgpt(prompt="Best pickup truck for towing?", state="TX")
+
     # Async tasks: create, poll, or run to a terminal status.
     task = client.async_tasks.run(
         "CHATGPT",
@@ -44,7 +48,8 @@ with Client("sk_...") as client:
         idempotency_key="phone-compare-1",
     )
 
-    client.credits()  # {"remaining", "perCycle", "cycleResetsAt"}
+    client.credits()  # {"remaining": USD balance, "perCycle": None, "cycleResetsAt": None}
+    client.engines()  # {"windowRequests": n, "engines": [{"taskType", "name", "status", "successRate", "yourSuccessRate", "yourRequests"}]}
 ```
 
 `AsyncClient` has the same methods, awaitable. `async_tasks.create_batch` submits up to 500 tasks in one call;
@@ -52,7 +57,7 @@ with Client("sk_...") as client:
 the queue. Prefer a webhook (`webhook_url=` on the task) over polling for many tasks — verify deliveries with
 `verify_webhook(body, header, secret)` against the `Webhook-Signature` header.
 
-Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, credit
+Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, USD balance
 and request-id headers); transport failures raise `TimeoutError` or `ConnectionError`. 429s and safely replayable
 failures are retried with jittered backoff; `timeout`, `sync_timeout`, `max_retries` and `http_client` are
 constructor options.
@@ -62,7 +67,8 @@ constructor options.
 One answer is one draw from an engine that varies its answers. `visibility.measure` asks each engine the same prompt
 `samples` times as separate async tasks and returns the results per engine; with a `brand` it also runs
 `brand_check` over them: how many answers mention the brand (with a Wilson 95% interval), its average rank among the
-brands you list, how many cite its own domains, and which domains get cited when it is absent.
+brands you list, how many cite its own domains, and which domains get cited when it is absent. `samples` is any whole
+number from 1 (default 10); a round of more than 500 tasks goes out in several batch calls.
 
 ```python
 from answerline import brand_check

{answerline-0.3.0 → answerline-0.6.0}/README.md

@@ -3,7 +3,7 @@
 Python client for the [AnswerLine](https://answerline.dev) API — structured JSON answers from AI assistants
 (ChatGPT, Perplexity, Gemini, Copilot, Grok) and Google surfaces (Search, News, AI Overview, AI Mode), on httpx.
 
-ChatGPT, Gemini, Copilot, Google Search (with AI Overview), AI Mode and Google News are served today; Perplexity and Grok are paused for now and coming back soon. [Coverage](https://answerline.dev/docs/coverage) lists what is served and from which countries. A monitor call to a paused engine fails with a 404 and an async task with a 422, each saying so, and nothing is billed.
+All eight engines are served. [Coverage](https://answerline.dev/docs/coverage) lists the countries each one is served from.
 
 ```bash
 pip install answerline
@@ -17,6 +17,10 @@ with Client("sk_...") as client:
     # copilot, grok, aimode, google, google_news), or client.monitor(engine, **body).
     answer = client.monitor.chatgpt(prompt="iPhone 17 or Galaxy S26?", country="US")
 
+    # A US state: ChatGPT answers from inside Texas; every other engine answers it for the whole US.
+    # A state implies country "US"; with another country it is refused with a 400.
+    texas = client.monitor.chatgpt(prompt="Best pickup truck for towing?", state="TX")
+
     # Async tasks: create, poll, or run to a terminal status.
     task = client.async_tasks.run(
         "CHATGPT",
@@ -24,7 +28,8 @@ with Client("sk_...") as client:
         idempotency_key="phone-compare-1",
     )
 
-    client.credits()  # {"remaining", "perCycle", "cycleResetsAt"}
+    client.credits()  # {"remaining": USD balance, "perCycle": None, "cycleResetsAt": None}
+    client.engines()  # {"windowRequests": n, "engines": [{"taskType", "name", "status", "successRate", "yourSuccessRate", "yourRequests"}]}
 ```
 
 `AsyncClient` has the same methods, awaitable. `async_tasks.create_batch` submits up to 500 tasks in one call;
@@ -32,7 +37,7 @@ with Client("sk_...") as client:
 the queue. Prefer a webhook (`webhook_url=` on the task) over polling for many tasks — verify deliveries with
 `verify_webhook(body, header, secret)` against the `Webhook-Signature` header.
 
-Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, credit
+Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, USD balance
 and request-id headers); transport failures raise `TimeoutError` or `ConnectionError`. 429s and safely replayable
 failures are retried with jittered backoff; `timeout`, `sync_timeout`, `max_retries` and `http_client` are
 constructor options.
@@ -42,7 +47,8 @@ constructor options.
 One answer is one draw from an engine that varies its answers. `visibility.measure` asks each engine the same prompt
 `samples` times as separate async tasks and returns the results per engine; with a `brand` it also runs
 `brand_check` over them: how many answers mention the brand (with a Wilson 95% interval), its average rank among the
-brands you list, how many cite its own domains, and which domains get cited when it is absent.
+brands you list, how many cite its own domains, and which domains get cited when it is absent. `samples` is any whole
+number from 1 (default 10); a round of more than 500 tasks goes out in several batch calls.
 
 ```python
 from answerline import brand_check

{answerline-0.3.0 → answerline-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "answerline"
-version = "0.3.0"
+version = "0.6.0"
 description = "Python client for the AnswerLine answer and search monitoring API."
 readme = "README.md"
 requires-python = ">=3.10"

{answerline-0.3.0 → answerline-0.6.0}/src/answerline/__init__.py

@@ -43,26 +43,26 @@ import httpx
 from .visibility import brand_check, wilson
 from .webhooks import SIGNATURE_HEADER, verify_webhook
 
-__all__ = ["ANSWER_ENGINES", "MAX_BATCH", "MAX_SAMPLES", "ApiError", "AsyncClient", "Client", "Meta",
+__all__ = ["ANSWER_ENGINES", "MAX_BATCH", "ApiError", "AsyncClient", "Client", "Meta",
            "SIGNATURE_HEADER", "brand_check", "verify_webhook", "wilson"]
 
 # Sent as `answerline-py/<version>`; keep in step with pyproject.toml.
-__version__ = "0.3.0"
+__version__ = "0.6.0"
 MAX_BATCH = 500
 # The answer engines `visibility.measure` samples, each asked with `prompt` and `country`, and their task types.
 ANSWER_ENGINES = {"chatgpt": "CHATGPT", "perplexity": "PERPLEXITY", "gemini": "GEMINI", "copilot": "COPILOT",
                   "grok": "GROK", "aimode": "AIMODE"}
-MAX_SAMPLES = 100
 DEFAULT_BASE_URL = "https://api.answerline.dev"
 TIMEOUT_S = 30.0
-# Sync monitor calls and task creation: the server answers a sync call within its 330 s deadline plus one result read
-# (6.5 s), and keeps resending a creation through a failover until 330 s, so the client never gives up just as the
+# Sync monitor calls and task creation: the server answers a sync call within its 630 s deadline plus one result read
+# (6.5 s), and keeps resending a creation through a failover until 630 s, so the client never gives up just as the
 # server answers.
-SYNC_TIMEOUT_S = 360.0
-# The server resends a clear that did not reach its dispatcher for up to 120 s, then allows the clear 120 s.
-CLEAR_QUEUE_TIMEOUT_S = 270.0
-# A task's longest run once started (5 minutes) and a wait for a slot, plus margin.
-WAIT_TIMEOUT_S = 660.0
+SYNC_TIMEOUT_S = 660.0
+# The server resends a clear that did not reach its dispatcher for up to 120 s, then answers within one 10 s call
+# (202 `clearing` for a queue longer than that call clears), plus margin.
+CLEAR_QUEUE_TIMEOUT_S = 150.0
+# A task's longest run once started (10 minutes) and a wait for a slot, plus margin.
+WAIT_TIMEOUT_S = 960.0
 MAX_RETRIES = 2
 _BACKOFF_S = 0.5
 _MAX_DELAY_S = 8.0
@@ -84,7 +84,7 @@ class _Secret:
 
 _IDEMPOTENT = frozenset({"GET", "HEAD", "PUT", "OPTIONS"})
 #: POSTs that create nothing and cost nothing, so repeating one is as safe as a GET: resolving a Google
-#: redirect link, whose contract documents transient upstream failures.
+#: redirect link, whose contract documents transient failures from Google.
 _REPLAYABLE_PATHS = frozenset({"/v1/monitor/google/goto"})
 # No connection was made, so the request never left.
 _NOT_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
@@ -97,9 +97,13 @@ _LIMIT_HEADERS = {
     "concurrent_limit": "X-Concurrent-Limit",
     "concurrent_current": "X-Concurrent-Current",
     "concurrent_remaining": "X-Concurrent-Remaining",
+    "latency_ms": "X-Latency-Ms",
+}
+
+# USD amount headers (up to six decimals); the integer map above refuses them.
+_CREDIT_HEADERS = {
     "credits_remaining": "X-Credits-Remaining",
     "credits_charged": "X-Credits-Charged",
-    "latency_ms": "X-Latency-Ms",
 }
 
 T = TypeVar("T")
@@ -121,8 +125,9 @@ class Meta:
     concurrent_limit: Optional[int] = None
     concurrent_current: Optional[int] = None
     concurrent_remaining: Optional[int] = None
-    credits_remaining: Optional[int] = None
-    credits_charged: Optional[int] = None
+    # Amounts are USD and fractional (up to 6 decimals).
+    credits_remaining: Optional[float] = None
+    credits_charged: Optional[float] = None
     latency_ms: Optional[int] = None
 
 
@@ -234,29 +239,31 @@ class _Api:
         """Visibility helpers: `client.visibility.measure(prompt=..., engines=[...], country=..., brand={...})`."""
         return _Visibility(self)
 
-    def chatgpt(self, prompt: str, country: str, **options: Any) -> Any:
-        return self.monitor("chatgpt", prompt=prompt, country=country, **options)
+    def chatgpt(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("chatgpt", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def perplexity(self, prompt: str, country: str, **options: Any) -> Any:
-        return self.monitor("perplexity", prompt=prompt, country=country, **options)
+    def perplexity(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("perplexity", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def gemini(self, prompt: str, country: str, **options: Any) -> Any:
-        return self.monitor("gemini", prompt=prompt, country=country, **options)
+    def gemini(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("gemini", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def copilot(self, prompt: str, country: str, **options: Any) -> Any:
-        return self.monitor("copilot", prompt=prompt, country=country, **options)
+    def copilot(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("copilot", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def grok(self, prompt: str, country: str, **options: Any) -> Any:
-        return self.monitor("grok", prompt=prompt, country=country, **options)
+    def grok(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self.monitor("grok", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def ai_mode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
-        return self.monitor("aimode", **_geo({"prompt": prompt}, country, gl, options))
+    def ai_mode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, state: Optional[str] = None,
+                **options: Any) -> Any:
+        return self.monitor("aimode", **_geo({"prompt": prompt}, {"country": country, "gl": gl, "state": state}, options))
 
     def google(self, **options: Any) -> Any:
         return self.monitor("google", **options)
 
-    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
-        return self.monitor("google/news", **_geo({"query": query}, country, gl, options))
+    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, state: Optional[str] = None,
+                    **options: Any) -> Any:
+        return self.monitor("google/news", **_geo({"query": query}, {"country": country, "gl": gl, "state": state}, options))
 
     # -- async tasks ----------------------------------------------------------
     def create_task(self, task_type: str, payload: Dict[str, Any], priority: Optional[int] = None,
@@ -295,6 +302,10 @@ class _Api:
             try:
                 task, meta = yield from poller._request("GET", _task_path(task_id), None)
             except (ApiError, httpx.TransportError) as err:
+                # A poll given the time left that ran out of it is the deadline passing, whatever the clock now says: a
+                # timer can fire a few milliseconds early, and the poll that followed could never answer in time.
+                if isinstance(err, httpx.TimeoutException) and remaining <= self.timeout:
+                    raise TimeoutError(f"task {task_id} did not finish in time") from err
                 # A rate limit's Retry-After is waited out while it ends before the deadline; one past it raises now.
                 delay = _retry_delay(err, True, poll, interval, deadline - time.monotonic())
                 if delay is None:
@@ -314,14 +325,21 @@ class _Api:
         return self._run(self._data("GET", "/v1/async/status"))
 
     def clear_queue(self) -> Any:
-        """Deletes QUEUED tasks (never charged). Clearing a full queue takes a while, so it gets a longer timeout
-        (the larger of `CLEAR_QUEUE_TIMEOUT_S` and the client's `timeout`)."""
+        """Deletes QUEUED tasks (never charged): `{"success": true, "cleared": n}`, or `{"success": true, "clearing": true}`
+        when the queue is longer than one call clears and the rest is still being deleted (`status()` shows it shrink).
+        The server may first wait out a dispatcher failover, so it gets a longer timeout (the larger of
+        `CLEAR_QUEUE_TIMEOUT_S` and the client's `timeout`)."""
         return self._run(self._data("DELETE", "/v1/async/queue", timeout=max(CLEAR_QUEUE_TIMEOUT_S, self.timeout)))
 
     # -- utility ----------------------------------------------------------------
     def credits(self) -> Any:
         return self._run(self._data("GET", "/v1/credits"))
 
+    def engines(self) -> Any:
+        """Each engine you can call: `status` now, and its success rate over everyone's and your own newest requests
+        (100 with none)."""
+        return self._run(self._data("GET", "/v1/engines"))
+
     def countries(self, model: Optional[str] = None) -> Any:
         query = f"?model={urllib.parse.quote(model, safe='')}" if model else ""
         return self._run(self._data("GET", f"/v1/countries{query}"))
@@ -348,34 +366,33 @@ class _Monitor:
     def __call__(self, engine: str, **body: Any) -> Any:
         return self._api._run(self._api._data("POST", f"/v1/monitor/{engine}", body))
 
-    def chatgpt(self, prompt: str, country: str, **options: Any) -> Any:
-        return self("chatgpt", prompt=prompt, country=country, **options)
+    def chatgpt(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self("chatgpt", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def perplexity(self, prompt: str, country: str, **options: Any) -> Any:
-        return self("perplexity", prompt=prompt, country=country, **options)
+    def perplexity(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self("perplexity", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def gemini(self, prompt: str, country: str, **options: Any) -> Any:
-        return self("gemini", prompt=prompt, country=country, **options)
+    def gemini(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self("gemini", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def copilot(self, prompt: str, country: str, **options: Any) -> Any:
-        return self("copilot", prompt=prompt, country=country, **options)
+    def copilot(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self("copilot", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def grok(self, prompt: str, country: str, **options: Any) -> Any:
-        return self("grok", prompt=prompt, country=country, **options)
+    def grok(self, prompt: str, country: Optional[str] = None, state: Optional[str] = None, **options: Any) -> Any:
+        return self("grok", **_geo({"prompt": prompt}, {"country": country, "state": state}, options))
 
-    def aimode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
-        return self("aimode", **_geo({"prompt": prompt}, country, gl, options))
+    def aimode(self, prompt: str, country: Optional[str] = None, gl: Optional[str] = None, state: Optional[str] = None,
+               **options: Any) -> Any:
+        return self("aimode", **_geo({"prompt": prompt}, {"country": country, "gl": gl, "state": state}, options))
 
-    def google(self, query: Optional[str] = None, country: Optional[str] = None, **options: Any) -> Any:
-        body = {**options}
-        if query is not None:
-            body["query"] = query
-        if country is not None:
-            body["country"] = country
-        return self("google", **body)
+    def google(self, query: Optional[str] = None, country: Optional[str] = None, state: Optional[str] = None,
+               **options: Any) -> Any:
+        given = {"query": query, "country": country, "state": state}
+        return self("google", **{**options, **{k: v for k, v in given.items() if v is not None}})
 
-    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, **options: Any) -> Any:
-        return self("google/news", **_geo({"query": query}, country, gl, options))
+    def google_news(self, query: str, country: Optional[str] = None, gl: Optional[str] = None, state: Optional[str] = None,
+                    **options: Any) -> Any:
+        return self("google/news", **_geo({"query": query}, {"country": country, "gl": gl, "state": state}, options))
 
 
 class _AsyncTasks:
@@ -429,8 +446,8 @@ class _Visibility:
     def measure(self, prompt: str, engines: List[str], country: str, samples: int = 10,
                 include: Optional[Dict[str, Any]] = None, rounds: int = 1, spacing_seconds: float = 0.0,
                 brand: Optional[Dict[str, Any]] = None, competitors: Optional[List[Dict[str, Any]]] = None,
-                timeout: float = WAIT_TIMEOUT_S, interval: float = 10.0) -> Any:
-        """Asks each engine (keys of `ANSWER_ENGINES`) the same prompt `samples` times (1 to `MAX_SAMPLES`) as
+                timeout: float = WAIT_TIMEOUT_S, interval: float = 10.0, state: Optional[str] = None) -> Any:
+        """Asks each engine (keys of `ANSWER_ENGINES`) the same prompt `samples` times (an integer, 1 or more) as
         independent async tasks, each under its own idempotency key, waits for them and returns per engine
         `{"requested", "completed", "failed", "results", "errors", "unfinished"}`, plus `"brand_check"` (see
         `brand_check`) when a `brand` is given. `unfinished` lists the ids of submitted tasks whose wait failed: they may
@@ -440,7 +457,8 @@ class _Visibility:
         failed and the rest go on; only cancellation propagates.
 
         `rounds` splits each engine's samples into that many batches, `spacing_seconds` apart start to start (default:
-        one round, all at once). `include` is sent with every sample. `timeout` is one deadline for all the waits,
+        one round, all at once). `include` and `state` (a US state code: ChatGPT answers from inside it, the other
+        engines for the whole US) are sent with every sample. `timeout` is one deadline for all the waits,
         starting once the last round is submitted: each task's wait gets the time left, and a task still unfinished
         when it passes is a failed sample. `interval` applies to each wait, as in `wait_for_task`.
 
@@ -448,8 +466,8 @@ class _Visibility:
         or hours apart measure how much the engine varies its own answer to this prompt from this country, not what
         different users see. Small samples give wide intervals (3 of 5 is anywhere from 23% to 88%): take 10 or more
         per engine, spread over hours with `rounds` and `spacing_seconds`."""
-        if isinstance(samples, bool) or not isinstance(samples, int) or not 1 <= samples <= MAX_SAMPLES:
-            raise ValueError(f"samples is an integer from 1 to {MAX_SAMPLES}, got {samples!r}")
+        if isinstance(samples, bool) or not isinstance(samples, int) or samples < 1:
+            raise ValueError(f"samples is an integer of 1 or more, got {samples!r}")
         if isinstance(rounds, bool) or not isinstance(rounds, int) or not 1 <= rounds <= samples:
             raise ValueError(f"rounds is an integer from 1 to samples, got {rounds!r}")
         if not spacing_seconds >= 0:
@@ -457,6 +475,8 @@ class _Visibility:
         if not engines or len(set(engines)) < len(engines) or not all(e in ANSWER_ENGINES for e in engines):
             raise ValueError(f"engines are distinct answer engines ({', '.join(ANSWER_ENGINES)}), got {engines!r}")
         payload: Dict[str, Any] = {"prompt": prompt, "country": country}
+        if state is not None:
+            payload["state"] = state
         if include is not None:
             payload["include"] = include
         api = self._api
@@ -494,10 +514,16 @@ class _Visibility:
             # The tasks run concurrently on the server, so one deadline covers every wait: a stalled engine costs
             # `timeout` once.
             deadline = time.monotonic() + timeout
+            # A wait that timed out was given all the time left, so the deadline has passed for every task after it,
+            # whatever the clock says: a timer can fire a few milliseconds early, and a poll in that sliver never answers.
+            expired = False
             for engine, task_id in tasks:
                 try:
+                    if expired:
+                        raise TimeoutError(f"task {task_id} did not finish in time")
                     done = yield from api._wait(task_id, deadline - time.monotonic(), interval)
                 except Exception as err:
+                    expired = expired or isinstance(err, TimeoutError)
                     fail(engine, err)
                     out[engine]["unfinished"].append(task_id)
                     continue
@@ -570,15 +596,14 @@ class AsyncClient(_Api):
         await self.aclose()
 
 
-def _geo(body: Dict[str, Any], country: Optional[str], gl: Optional[str], options: Dict[str, Any]) -> Dict[str, Any]:
-    """The spec's country/gl either-of: one must be given, both may be (`gl` then serves the engine's locale)."""
-    body = {**body, **options}
-    if country is not None:
-        body["country"] = country
-    if gl is not None:
-        body["gl"] = gl
-    if "country" not in body and "gl" not in body:
-        raise ValueError("country or gl is required")
+def _geo(body: Dict[str, Any], geo: Dict[str, Optional[str]], options: Dict[str, Any]) -> Dict[str, Any]:
+    """The body with the geo fields given, over `options`; at least one of them is required. `state` is a US state code
+    (e.g. "TX") and implies country "US"; with any other country it is refused with a 400. ChatGPT answers from inside
+    the state; every other engine answers it for the whole US (https://answerline.dev/docs/coverage#states). Given both
+    `country` and `gl`, `gl` serves the engine's locale."""
+    body = {**body, **options, **{k: v for k, v in geo.items() if v is not None}}
+    if not body.keys() & geo.keys():
+        raise ValueError(f"{' or '.join(geo)} is required")
     return body
 
 
@@ -598,7 +623,8 @@ def _parse(outcome: Union[httpx.Response, Exception]) -> Tuple[Any, Meta]:
         raise outcome
     headers = outcome.headers
     meta = Meta(outcome.status_code, headers, headers.get("X-Request-Id"),
-                **{name: _int(headers.get(header)) for name, header in _LIMIT_HEADERS.items()})
+                **{name: _int(headers.get(header)) for name, header in _LIMIT_HEADERS.items()},
+                **{name: _float(headers.get(header)) for name, header in _CREDIT_HEADERS.items()})
     is_json, parsed = _decode(outcome.content)
     if not outcome.is_success or not is_json:
         error = parsed.get("error") if isinstance(parsed, dict) else None
@@ -618,6 +644,13 @@ def _int(value: Optional[str]) -> Optional[int]:
         return None
 
 
+def _float(value: Optional[str]) -> Optional[float]:
+    try:
+        return float(value) if value is not None else None
+    except ValueError:
+        return None
+
+
 def _decode(raw: bytes) -> Tuple[bool, Any]:
     """(True, value) for an empty or JSON body, (False, text) otherwise."""
     try:

{answerline-0.3.0 → answerline-0.6.0/src/answerline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: answerline
-Version: 0.3.0
+Version: 0.6.0
 Summary: Python client for the AnswerLine answer and search monitoring API.
 Author-email: AnswerLine <support@answerline.dev>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 Python client for the [AnswerLine](https://answerline.dev) API — structured JSON answers from AI assistants
 (ChatGPT, Perplexity, Gemini, Copilot, Grok) and Google surfaces (Search, News, AI Overview, AI Mode), on httpx.
 
-ChatGPT, Gemini, Copilot, Google Search (with AI Overview), AI Mode and Google News are served today; Perplexity and Grok are paused for now and coming back soon. [Coverage](https://answerline.dev/docs/coverage) lists what is served and from which countries. A monitor call to a paused engine fails with a 404 and an async task with a 422, each saying so, and nothing is billed.
+All eight engines are served. [Coverage](https://answerline.dev/docs/coverage) lists the countries each one is served from.
 
 ```bash
 pip install answerline
@@ -37,6 +37,10 @@ with Client("sk_...") as client:
     # copilot, grok, aimode, google, google_news), or client.monitor(engine, **body).
     answer = client.monitor.chatgpt(prompt="iPhone 17 or Galaxy S26?", country="US")
 
+    # A US state: ChatGPT answers from inside Texas; every other engine answers it for the whole US.
+    # A state implies country "US"; with another country it is refused with a 400.
+    texas = client.monitor.chatgpt(prompt="Best pickup truck for towing?", state="TX")
+
     # Async tasks: create, poll, or run to a terminal status.
     task = client.async_tasks.run(
         "CHATGPT",
@@ -44,7 +48,8 @@ with Client("sk_...") as client:
         idempotency_key="phone-compare-1",
     )
 
-    client.credits()  # {"remaining", "perCycle", "cycleResetsAt"}
+    client.credits()  # {"remaining": USD balance, "perCycle": None, "cycleResetsAt": None}
+    client.engines()  # {"windowRequests": n, "engines": [{"taskType", "name", "status", "successRate", "yourSuccessRate", "yourRequests"}]}
 ```
 
 `AsyncClient` has the same methods, awaitable. `async_tasks.create_batch` submits up to 500 tasks in one call;
@@ -52,7 +57,7 @@ with Client("sk_...") as client:
 the queue. Prefer a webhook (`webhook_url=` on the task) over polling for many tasks — verify deliveries with
 `verify_webhook(body, header, secret)` against the `Webhook-Signature` header.
 
-Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, credit
+Calls raise `ApiError` (`status`, stable `code`, parsed `body`, and `meta` with the rate-limit, concurrency, USD balance
 and request-id headers); transport failures raise `TimeoutError` or `ConnectionError`. 429s and safely replayable
 failures are retried with jittered backoff; `timeout`, `sync_timeout`, `max_retries` and `http_client` are
 constructor options.
@@ -62,7 +67,8 @@ constructor options.
 One answer is one draw from an engine that varies its answers. `visibility.measure` asks each engine the same prompt
 `samples` times as separate async tasks and returns the results per engine; with a `brand` it also runs
 `brand_check` over them: how many answers mention the brand (with a Wilson 95% interval), its average rank among the
-brands you list, how many cite its own domains, and which domains get cited when it is absent.
+brands you list, how many cite its own domains, and which domains get cited when it is absent. `samples` is any whole
+number from 1 (default 10); a round of more than 500 tasks goes out in several batch calls.
 
 ```python
 from answerline import brand_check

{answerline-0.3.0 → answerline-0.6.0}/src/answerline.egg-info/SOURCES.txt

@@ -10,8 +10,6 @@ src/answerline.egg-info/SOURCES.txt
 src/answerline.egg-info/dependency_links.txt
 src/answerline.egg-info/requires.txt
 src/answerline.egg-info/top_level.txt
-tests/localhost-cert.pem
-tests/localhost-key.pem
 tests/test_client.py
 tests/test_visibility.py
 tests/test_webhooks.py

{answerline-0.3.0 → answerline-0.6.0}/tests/test_client.py

@@ -360,7 +360,7 @@ class ClientTest(ServerTest):
             self.new_client(timeout=0.01).clear_queue()
         self.assertEqual(self.sleep.call_count, 0, "a timed-out clear may still be running: not repeated")
         await_seen(self, 1)
-        self.assertEqual(answerline.CLEAR_QUEUE_TIMEOUT_S, 270.0)
+        self.assertEqual(answerline.CLEAR_QUEUE_TIMEOUT_S, 150.0)
 
     def test_dropped_connections_retry_get_but_not_sync_calls(self):
         REPLIES.extend(["reset", task_reply("QUEUED")])
@@ -546,13 +546,21 @@ class ClientTest(ServerTest):
         self.assertEqual([e.code for e in out["chatgpt"]["errors"]], ["INSUFFICIENT_CREDITS", "INSUFFICIENT_CREDITS", "NOT_FOUND"])
 
     def test_visibility_measure_refuses_bad_options_before_sending(self):
-        for options in ({"samples": 0}, {"samples": 101}, {"samples": 2.5}, {"samples": 3, "rounds": 4}, {"rounds": 0},
+        for options in ({"samples": 0}, {"samples": -1}, {"samples": 2.5}, {"samples": 3, "rounds": 4}, {"rounds": 0},
                         {"spacing_seconds": -1}, {"engines": []}, {"engines": ["chatgpt", "chatgpt"]},
                         {"engines": ["google"]}):
             with self.subTest(options=options), self.assertRaises(ValueError):
                 self.client.visibility.measure(**{"prompt": "x", "engines": ["chatgpt"], "country": "US", **options})
         self.assertEqual(SEEN, [])
 
+    def test_visibility_measure_takes_any_number_of_samples(self):
+        # No upper bound: 501 samples, past the 100 it once allowed, go out in batches of at most MAX_BATCH.
+        self.assertFalse(hasattr(answerline, "MAX_SAMPLES"))
+        REPLIES.extend([error(403, "INSUFFICIENT_CREDITS"), error(403, "INSUFFICIENT_CREDITS")])
+        out = self.client.visibility.measure("x", ["chatgpt"], "US", samples=501)
+        self.assertEqual([len(json.loads(s[3])) for s in SEEN], [MAX_BATCH, 1])
+        self.assertEqual((out["chatgpt"]["requested"], out["chatgpt"]["failed"]), (501, 501))
+
 
 class AsyncClientTest(ServerTest, unittest.IsolatedAsyncioTestCase):
     """The asyncio client runs the same calls; these check that its runner sends, waits and maps errors alike."""

answerline-0.3.0/tests/localhost-cert.pem

@@ -1,11 +0,0 @@
------BEGIN CERTIFICATE-----
-MIIBoDCCAUagAwIBAgIUGl4E2FTh5mbDrsvR/CGSuY14tIEwCgYIKoZIzj0EAwIw
-FDESMBAGA1UEAwwJMTI3LjAuMC4xMCAXDTI2MDkxNDIxMTAxMloYDzIxMjYwODIx
-MjExMDEyWjAUMRIwEAYDVQQDDAkxMjcuMC4wLjEwWTATBgcqhkjOPQIBBggqhkjO
-PQMBBwNCAAQWPixZ2ME9prdR+m7sipWKOVmIwrXlZ32aO+ySiIECSTS3+1po3bFB
-mjKW1we39G5F1LHZfKSdP8vMc6wE4guao3QwcjAdBgNVHQ4EFgQU5FOuodtWI4IR
-gdfnJIcIirPf+AkwHwYDVR0jBBgwFoAU5FOuodtWI4IRgdfnJIcIirPf+AkwDwYD
-VR0TAQH/BAUwAwEB/zAPBgNVHREECDAGhwR/AAABMA4GA1UdDwEB/wQEAwIChDAK
-BggqhkjOPQQDAgNIADBFAiEAxy0k552unmVHuD2oBV5/ZoehGRqC5M/GSJGd+smc
-s7UCIGi3F3Y1o+ATHldxx71BjZojy+AGgYx2orlI7zhQsICg
------END CERTIFICATE-----

answerline-0.3.0/tests/localhost-key.pem

@@ -1,5 +0,0 @@
------BEGIN PRIVATE KEY-----
-MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgXVxxNTv2/fq/HUeS
-jZwEdhwMaON64AhCmr+BBedFfwuhRANCAAQWPixZ2ME9prdR+m7sipWKOVmIwrXl
-Z32aO+ySiIECSTS3+1po3bFBmjKW1we39G5F1LHZfKSdP8vMc6wE4gua
------END PRIVATE KEY-----