launchables 0.4.0__tar.gz → 0.5.0__tar.gz

{launchables-0.4.0 → launchables-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: launchables
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python client for the Launchables Decision API
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://www.launchables.ai/docs
@@ -34,6 +34,7 @@ resp = client.decide(
     "Customer bought the item 12 days ago and has no receipt. "
     "Policy: refunds within 30 days with proof of purchase.",
     {"refund": noul("Is a refund permitted under the policy?")},
+    model="myles-g-12b",
 )
 
 answer = resp.answers["refund"]
@@ -42,7 +43,9 @@ print(answer.decide(threshold_yes=0.9, threshold_no=0.1))  # "yes" | "no" | "per
 print(resp.usage.input_tokens, resp.model)
 ```
 
-`decide` returns a `DecisionResponse` with `.answers`, `.usage`, `.model` and `.raw` (the untouched JSON). `state` may be a string or a dict. To include images, see [Images](#images).
+`decide(state, questions, model=...)` returns a `DecisionResponse` with `.answers`, `.usage`, `.model` and `.raw` (the untouched JSON). `state` may be a string or a dict. To include images, see [Images](#images).
+
+Always pass `model`, a model id from `client.models()` (for example `"myles-g-12b"` or `"myles-g-31b"`), so every request names the model that answers it. The API is moving to requiring it; until then a request without one is answered by the server's default model, which can change.
 
 ### Question types
 
@@ -54,7 +57,7 @@ questions = {
     "topic": choice("What is this about?", ["billing", "returns", "other"]),       # or {label: description}
     "urgency": score("How urgent is it?", ["not urgent", "low", "medium", "high"]),  # lowest level first, numbered from 0
 }
-resp = client.decide(state, questions)
+resp = client.decide(state, questions, model="myles-g-12b")
 
 resp.answers["topic"].choice          # "returns"
 resp.answers["topic"].probabilities   # {"billing": 0.06, "returns": 0.89, ...}
@@ -87,6 +90,7 @@ resp = client.decide(
     {"receipt": "receipt_photo", "note": "Customer asks for a refund"},
     {"total_matches": noul("Does the total printed on receipt_photo equal 23.40?")},
     assets={"receipt_photo": Image.from_path("receipt.jpg")},
+    model="myles-g-12b",
     image_budget=140,  # optional: 70, 140 or 280 (the default)
 )
 ```
@@ -104,6 +108,51 @@ Limits, checked by the server (each breach is an `InvalidRequestError` whose mes
 
 Images count as input tokens and are included in `usage.input_tokens`. At budget 280 one image costs up to about 280 tokens, at 140 up to about 140, at 70 up to about 70. An image referenced in the state is billed once per request however many questions read it; one referenced in a question's instructions or criteria is billed for that question, once per use.
 
+## Batches
+
+The Batch API answers many decisions from one submission, within 24 hours, at half the live price per input token. Use it for work that does not need an answer straight away: back-catalogues, nightly reviews, re-scoring after a policy change. Batch support is in version 0.5.0 and later.
+
+```python
+from launchables import Launchables, choice, noul
+
+client = Launchables()
+
+batch = client.batch([
+    {"custom_id": "ticket-1001", "model": "myles-g-12b", "state": "Charged twice for order 4471",
+     "questions": {"refund": noul("Is a refund due?")}},
+    {"custom_id": "ticket-1002", "model": "myles-g-31b", "state": {"message": "The app crashes on login"},
+     "questions": {"team": choice("Which team?", ["billing", "returns", "technical", "other"])}},
+])  # CreatedBatch(id="batch_...", status="queued", lines=2, estimated_cost=..., expires_at=..., data_region=...)
+
+finished = client.batches.wait_for(batch.id)  # polls 5 s, 7.5 s, 11.25 s ... up to 60 s apart
+
+for r in client.batches.stream_results(batch.id):
+    if r.ok:
+        print(r.custom_id, r.response.answers)  # a DecisionResponse, exactly as decide() returns it
+    else:
+        print(r.custom_id, r.error.get("type"))  # e.g. "expired", "cancelled", "invalid_question"
+```
+
+Each line is a dict: the body of one `decide` request with your own `custom_id` (1 to 64 letters, digits or `_ . : -`, unique in the batch) and a `model`, which every line must name: a batch has no default model. Keys are as they are sent: `custom_id`, `model`, `state`, `questions`, and optionally `assets` and `image_budget`. Lines may name different models. Images must be inline (`Image.from_path`, `Image.from_bytes`, or a dict with `data_base64`); a batch line cannot carry file parts.
+
+| Call | What it does |
+| --- | --- |
+| `batch(lines, webhook_url=None)` or `batches.create(...)` | Checks every line, sends them as one JSONL file and returns the queued batch (`CreatedBatch`) with its cost estimate. |
+| `batches.list()` | The calling key's batches (`Batch`), oldest first. |
+| `batches.retrieve(batch_id)` | Status (`"queued"`, `"running"`, `"done"`, `"failed"` or `"cancelled"`), `counts` (`done`, `failed`, `pending`) and times. |
+| `batches.wait_for(batch_id, ...)` | Polls until the results can be collected. The first check is at once; the wait after it, `poll_interval` (5 seconds), grows 1.5 times a check up to `max_interval` (60 seconds), both at least 1 second; `timeout` (25 hours) raises `BatchTimeoutError`; setting `stop` (a `threading.Event`) raises `BatchWaitCancelledError`; `on_poll(batch)` sees each status. It keeps waiting through a brief outage (connection errors, 429 and 5xx other than `batch_unavailable`). Giving up never cancels the batch. |
+| `batches.stream_results(batch_id)` | Each result line as it arrives, in input order, so a large file is never held in memory. |
+| `batches.results(batch_id)` | Every result line in one list. |
+| `batches.cancel(batch_id)` | Stops the batch. Lines already answered stay in the results and are billed; the rest read as cancelled and are not. |
+
+A result is an `AnsweredBatchResult` (`ok` is `True`, `response` is a `DecisionResponse`) or a `FailedBatchResult` (`ok` is `False`, `error` is a dict saying why). Both have `custom_id`, `model` (the exact model build that answered), `status` (the HTTP status the line got, 200 when answered, or `None` for a line that never ran), `usage` (`input_tokens` is what the line is billed on) and `raw`. `BatchTimeoutError` and `BatchWaitCancelledError` carry the last status read in `.batch`.
+
+The client checks every line before sending and raises `ValidationError` naming the line (`line 3 (custom_id ticket-1003): ...`). The server checks every line again and refuses the whole batch if any is invalid: `InvalidRequestError` with `.type` `"invalid_batch"` and each bad line in `e.body["errors"]` (`{"line", "type", "error"}`), so nothing is half-queued. Other batch errors: `RateLimitError` with `.type` `"too_many_batches"` when the key already has its limit of batches queued or running (not retried; `.retry_after` says when to try); `ConflictError` with `.type` `"batch_not_finished"` for results before the batch has ended, or `"batch_finished"` for cancelling a batch that is already done or failed; `NotFoundError` (`"batch_not_found"`) for an id the key does not own; `APIError` with `.type` `"batch_unavailable"` where the Batch API is not switched on (not retried).
+
+A submission is retried only after a refusal that stored nothing (429 `rate_limited`, 503 `busy`), never after a lost connection or a 502, so a retry cannot submit the same batch twice. Status, results and cancel calls are retried like any other.
+
+Batches belong to the API key that submitted them. A rolled key is a new key: collect a batch's results with the key that submitted it, before that key stops working. See the [Batch API documentation](https://www.launchables.ai/docs/api/batches) for limits, the 24-hour window, webhooks, retention and where batch data is stored.
+
 ## Key expiry
 
 Every API key expires. The client reads the expiry date from each response, so your program can plan rotation instead of finding out when the key stops working.
@@ -157,7 +206,7 @@ All errors derive from `LaunchablesError` and carry `.status`, `.message` (the s
 | `PermissionDeniedError` | 403: the key's workspace may not use this model (`.type` `"model_not_allowed"`), or the admin key's maker is no longer an owner |
 | `RateLimitError` | 429 (`.retry_after` seconds, if sent) |
 | `InvalidRequestError` | 400, 411, 413, 422 and other 4xx; `ValidationError` is the local pre-flight subclass. `.type` says what was wrong with an image: `"invalid_assets"`, `"unsupported_image_format"`, `"invalid_image"`, `"image_too_large"`, `"image_dimensions"`, `"too_many_images"`, `"unreferenced_asset"` or `"image_reference_truncated"` (400), or `"invalid_image_budget"` (422). |
-| `NotFoundError`, `ConflictError` | 404 and 409 from the key management API (subclasses of `InvalidRequestError`) |
+| `NotFoundError`, `ConflictError` | 404 and 409 from the key management API and the Batch API (subclasses of `InvalidRequestError`) |
 | `APIError` | 5xx |
 | `APIConnectionError` | could not reach the server (including timeouts) |
 
@@ -165,7 +214,7 @@ All errors derive from `LaunchablesError` and carry `.status`, `.message` (the s
 from launchables import OutOfCreditError, RateLimitError, InvalidRequestError, LaunchablesError
 
 try:
-    resp = client.decide(state, questions)
+    resp = client.decide(state, questions, model="myles-g-12b")
 except OutOfCreditError as e:
     print("workspace budget reached" if e.type == "budget_exceeded" else "top up credit")
 except RateLimitError as e:

{launchables-0.4.0 → launchables-0.5.0}/README.md

@@ -17,6 +17,7 @@ resp = client.decide(
     "Customer bought the item 12 days ago and has no receipt. "
     "Policy: refunds within 30 days with proof of purchase.",
     {"refund": noul("Is a refund permitted under the policy?")},
+    model="myles-g-12b",
 )
 
 answer = resp.answers["refund"]
@@ -25,7 +26,9 @@ print(answer.decide(threshold_yes=0.9, threshold_no=0.1))  # "yes" | "no" | "per
 print(resp.usage.input_tokens, resp.model)
 ```
 
-`decide` returns a `DecisionResponse` with `.answers`, `.usage`, `.model` and `.raw` (the untouched JSON). `state` may be a string or a dict. To include images, see [Images](#images).
+`decide(state, questions, model=...)` returns a `DecisionResponse` with `.answers`, `.usage`, `.model` and `.raw` (the untouched JSON). `state` may be a string or a dict. To include images, see [Images](#images).
+
+Always pass `model`, a model id from `client.models()` (for example `"myles-g-12b"` or `"myles-g-31b"`), so every request names the model that answers it. The API is moving to requiring it; until then a request without one is answered by the server's default model, which can change.
 
 ### Question types
 
@@ -37,7 +40,7 @@ questions = {
     "topic": choice("What is this about?", ["billing", "returns", "other"]),       # or {label: description}
     "urgency": score("How urgent is it?", ["not urgent", "low", "medium", "high"]),  # lowest level first, numbered from 0
 }
-resp = client.decide(state, questions)
+resp = client.decide(state, questions, model="myles-g-12b")
 
 resp.answers["topic"].choice          # "returns"
 resp.answers["topic"].probabilities   # {"billing": 0.06, "returns": 0.89, ...}
@@ -70,6 +73,7 @@ resp = client.decide(
     {"receipt": "receipt_photo", "note": "Customer asks for a refund"},
     {"total_matches": noul("Does the total printed on receipt_photo equal 23.40?")},
     assets={"receipt_photo": Image.from_path("receipt.jpg")},
+    model="myles-g-12b",
     image_budget=140,  # optional: 70, 140 or 280 (the default)
 )
 ```
@@ -87,6 +91,51 @@ Limits, checked by the server (each breach is an `InvalidRequestError` whose mes
 
 Images count as input tokens and are included in `usage.input_tokens`. At budget 280 one image costs up to about 280 tokens, at 140 up to about 140, at 70 up to about 70. An image referenced in the state is billed once per request however many questions read it; one referenced in a question's instructions or criteria is billed for that question, once per use.
 
+## Batches
+
+The Batch API answers many decisions from one submission, within 24 hours, at half the live price per input token. Use it for work that does not need an answer straight away: back-catalogues, nightly reviews, re-scoring after a policy change. Batch support is in version 0.5.0 and later.
+
+```python
+from launchables import Launchables, choice, noul
+
+client = Launchables()
+
+batch = client.batch([
+    {"custom_id": "ticket-1001", "model": "myles-g-12b", "state": "Charged twice for order 4471",
+     "questions": {"refund": noul("Is a refund due?")}},
+    {"custom_id": "ticket-1002", "model": "myles-g-31b", "state": {"message": "The app crashes on login"},
+     "questions": {"team": choice("Which team?", ["billing", "returns", "technical", "other"])}},
+])  # CreatedBatch(id="batch_...", status="queued", lines=2, estimated_cost=..., expires_at=..., data_region=...)
+
+finished = client.batches.wait_for(batch.id)  # polls 5 s, 7.5 s, 11.25 s ... up to 60 s apart
+
+for r in client.batches.stream_results(batch.id):
+    if r.ok:
+        print(r.custom_id, r.response.answers)  # a DecisionResponse, exactly as decide() returns it
+    else:
+        print(r.custom_id, r.error.get("type"))  # e.g. "expired", "cancelled", "invalid_question"
+```
+
+Each line is a dict: the body of one `decide` request with your own `custom_id` (1 to 64 letters, digits or `_ . : -`, unique in the batch) and a `model`, which every line must name: a batch has no default model. Keys are as they are sent: `custom_id`, `model`, `state`, `questions`, and optionally `assets` and `image_budget`. Lines may name different models. Images must be inline (`Image.from_path`, `Image.from_bytes`, or a dict with `data_base64`); a batch line cannot carry file parts.
+
+| Call | What it does |
+| --- | --- |
+| `batch(lines, webhook_url=None)` or `batches.create(...)` | Checks every line, sends them as one JSONL file and returns the queued batch (`CreatedBatch`) with its cost estimate. |
+| `batches.list()` | The calling key's batches (`Batch`), oldest first. |
+| `batches.retrieve(batch_id)` | Status (`"queued"`, `"running"`, `"done"`, `"failed"` or `"cancelled"`), `counts` (`done`, `failed`, `pending`) and times. |
+| `batches.wait_for(batch_id, ...)` | Polls until the results can be collected. The first check is at once; the wait after it, `poll_interval` (5 seconds), grows 1.5 times a check up to `max_interval` (60 seconds), both at least 1 second; `timeout` (25 hours) raises `BatchTimeoutError`; setting `stop` (a `threading.Event`) raises `BatchWaitCancelledError`; `on_poll(batch)` sees each status. It keeps waiting through a brief outage (connection errors, 429 and 5xx other than `batch_unavailable`). Giving up never cancels the batch. |
+| `batches.stream_results(batch_id)` | Each result line as it arrives, in input order, so a large file is never held in memory. |
+| `batches.results(batch_id)` | Every result line in one list. |
+| `batches.cancel(batch_id)` | Stops the batch. Lines already answered stay in the results and are billed; the rest read as cancelled and are not. |
+
+A result is an `AnsweredBatchResult` (`ok` is `True`, `response` is a `DecisionResponse`) or a `FailedBatchResult` (`ok` is `False`, `error` is a dict saying why). Both have `custom_id`, `model` (the exact model build that answered), `status` (the HTTP status the line got, 200 when answered, or `None` for a line that never ran), `usage` (`input_tokens` is what the line is billed on) and `raw`. `BatchTimeoutError` and `BatchWaitCancelledError` carry the last status read in `.batch`.
+
+The client checks every line before sending and raises `ValidationError` naming the line (`line 3 (custom_id ticket-1003): ...`). The server checks every line again and refuses the whole batch if any is invalid: `InvalidRequestError` with `.type` `"invalid_batch"` and each bad line in `e.body["errors"]` (`{"line", "type", "error"}`), so nothing is half-queued. Other batch errors: `RateLimitError` with `.type` `"too_many_batches"` when the key already has its limit of batches queued or running (not retried; `.retry_after` says when to try); `ConflictError` with `.type` `"batch_not_finished"` for results before the batch has ended, or `"batch_finished"` for cancelling a batch that is already done or failed; `NotFoundError` (`"batch_not_found"`) for an id the key does not own; `APIError` with `.type` `"batch_unavailable"` where the Batch API is not switched on (not retried).
+
+A submission is retried only after a refusal that stored nothing (429 `rate_limited`, 503 `busy`), never after a lost connection or a 502, so a retry cannot submit the same batch twice. Status, results and cancel calls are retried like any other.
+
+Batches belong to the API key that submitted them. A rolled key is a new key: collect a batch's results with the key that submitted it, before that key stops working. See the [Batch API documentation](https://www.launchables.ai/docs/api/batches) for limits, the 24-hour window, webhooks, retention and where batch data is stored.
+
 ## Key expiry
 
 Every API key expires. The client reads the expiry date from each response, so your program can plan rotation instead of finding out when the key stops working.
@@ -140,7 +189,7 @@ All errors derive from `LaunchablesError` and carry `.status`, `.message` (the s
 | `PermissionDeniedError` | 403: the key's workspace may not use this model (`.type` `"model_not_allowed"`), or the admin key's maker is no longer an owner |
 | `RateLimitError` | 429 (`.retry_after` seconds, if sent) |
 | `InvalidRequestError` | 400, 411, 413, 422 and other 4xx; `ValidationError` is the local pre-flight subclass. `.type` says what was wrong with an image: `"invalid_assets"`, `"unsupported_image_format"`, `"invalid_image"`, `"image_too_large"`, `"image_dimensions"`, `"too_many_images"`, `"unreferenced_asset"` or `"image_reference_truncated"` (400), or `"invalid_image_budget"` (422). |
-| `NotFoundError`, `ConflictError` | 404 and 409 from the key management API (subclasses of `InvalidRequestError`) |
+| `NotFoundError`, `ConflictError` | 404 and 409 from the key management API and the Batch API (subclasses of `InvalidRequestError`) |
 | `APIError` | 5xx |
 | `APIConnectionError` | could not reach the server (including timeouts) |
 
@@ -148,7 +197,7 @@ All errors derive from `LaunchablesError` and carry `.status`, `.message` (the s
 from launchables import OutOfCreditError, RateLimitError, InvalidRequestError, LaunchablesError
 
 try:
-    resp = client.decide(state, questions)
+    resp = client.decide(state, questions, model="myles-g-12b")
 except OutOfCreditError as e:
     print("workspace budget reached" if e.type == "budget_exceeded" else "top up credit")
 except RateLimitError as e:

{launchables-0.4.0 → launchables-0.5.0}/src/launchables/__init__.py

@@ -2,6 +2,23 @@
 
 from ._version import __version__
 from .admin import AdminKeys
+from .batches import (
+    BATCH_FINISHED_STATUSES,
+    CUSTOM_ID_PATTERN,
+    AnsweredBatchResult,
+    Batch,
+    BatchCostEstimate,
+    BatchCounts,
+    Batches,
+    BatchLine,
+    BatchResult,
+    BatchTimeoutError,
+    BatchUsage,
+    BatchWaitCancelledError,
+    CreatedBatch,
+    FailedBatchResult,
+    to_jsonl,
+)
 from .client import DEFAULT_ADMIN_BASE_URL, DEFAULT_BASE_URL, KEY_EXPIRY_WARNING_DAYS, KeyExpiryWarning, Launchables
 from .errors import (
     APIConnectionError,
@@ -36,4 +53,7 @@ __all__ = [
     "LaunchablesError", "AuthenticationError", "OutOfCreditError", "PermissionDeniedError",
     "RateLimitError", "InvalidRequestError", "NotFoundError", "ConflictError",
     "ValidationError", "APIError", "APIConnectionError",
+    "Batches", "Batch", "BatchLine", "BatchCounts", "BatchCostEstimate", "BatchUsage", "CreatedBatch", "BatchResult",
+    "AnsweredBatchResult", "FailedBatchResult", "BatchTimeoutError", "BatchWaitCancelledError",
+    "BATCH_FINISHED_STATUSES", "CUSTOM_ID_PATTERN", "to_jsonl",
 ]

launchables-0.5.0/src/launchables/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"