zarx 0.2.0__tar.gz

zarx-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Node
+node_modules/
+*.tgz
+typescript/dist/
+.npm/
+
+# Local secrets and env files: never committed
+.env
+.env.*
+*.env
+stage.env
+
+# Editors and OS
+.DS_Store
+.idea/
+.vscode/
+
+# Audio produced by examples
+*.mp3
+*.wav
+*.pcm
+!examples/assets/*.wav

zarx-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

zarx-0.2.0/NOTICE

@@ -0,0 +1,4 @@
+Zarx SDK
+Copyright 2026 NPAW (Nice People At Work S.L.)
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

zarx-0.2.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: zarx
+Version: 0.2.0
+Summary: Python SDK for Zarx, the OpenAI-compatible inference API run by NPAW in Europe.
+Project-URL: Homepage, https://zarx.ai
+Author-email: NPAW <contact@zarx.ai>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: europe,inference,llm,openai,zarx
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: openai<4,>=1.99
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: websockets>=12; extra == 'dev'
+Provides-Extra: realtime
+Requires-Dist: websockets>=12; extra == 'realtime'
+Description-Content-Type: text/markdown
+
+# zarx (Python)
+
+Python SDK and command line for [Zarx](https://zarx.ai), the OpenAI-compatible inference API that NPAW runs on its own GPUs in Spain (EU).
+
+`zarx` is a thin layer over the official `openai` package: `zarx.Zarx` *is* an `openai.OpenAI` client, so everything you know from the OpenAI SDK works as is. What the layer adds:
+
+- the right endpoint and key: production by default, beta with `environment="beta"` or `ZARX_ENVIRONMENT=beta`, and `ZARX_API_KEY` only (an `OPENAI_API_KEY` is never sent to Zarx, an `OPENAI_BASE_URL` never redirects it);
+- Responses API calls default to `store=False`, so responses are not stored for later retrieval unless you ask for it (what else is retained depends on your key's retention policy, see `docs/data.md`);
+- generous read timeouts for the reasoning tiers (300 s read, 10 s connect) and 2 retries;
+- model name helpers (tiers and dated ids), a helper to read the reasoning text, and a `zarx` command;
+- one call per capability beyond chat: `zarx.audio.transcribe`, `transcribe_realtime`, `speak`, `translate`, and `zarx.forecast` / `forecast_csv` for time series.
+
+Requires Python 3.9 or newer (0.1.0 verified on 3.9 to 3.13 on 2026-10-31; 0.2.0 run on 3.13 on 2026-11-01).
+
+## Install
+
+```bash
+pip install zarx
+pip install "zarx[realtime]"   # adds websockets, for transcribe_realtime
+```
+
+or from a checkout of this repository: `pip install ./python` (`pip install './python[realtime]'` for realtime transcription).
+
+## Quickstart
+
+```bash
+export ZARX_API_KEY=...            # your Zarx key
+# export ZARX_ENVIRONMENT=beta     # only for beta, with a beta key
+```
+
+```python
+from zarx import Zarx, Z_FAST
+
+client = Zarx()
+completion = client.chat.completions.create(
+    model=Z_FAST,
+    messages=[{"role": "user", "content": "Say hello in one sentence."}],
+    max_tokens=64,
+)
+print(completion.choices[0].message.content)
+print(completion.model)  # the dated id that answered, e.g. z-fast-2026-10
+```
+
+Async: `from zarx import AsyncZarx`, same arguments.
+
+### Plain OpenAI SDK
+
+You do not need this package to use Zarx. The official SDK works with two settings:
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(api_key=os.environ["ZARX_API_KEY"], base_url="https://api.zarx.ai/v1")
+```
+
+If you go this way, pass `store=False` yourself on every Responses API call.
+
+## Models
+
+| Tier | Use it for | Context |
+|---|---|---|
+| `z-ultra` | hardest reasoning, long documents | 600,000 tokens |
+| `z-pro` | strong general model with reasoning, very long documents | 1,048,576 tokens (1M) |
+| `z-fast` | low latency, high volume | 16,384 tokens |
+
+`client.models.list()` is the authority on these values; production and beta both list 1,048,576 tokens for `z-pro` (checked 2026-11-01). `z-ultra` and `z-pro` also read images; `z-fast` is text only. See `docs/models.md`.
+
+A tier always points at its current release. To pin one release, use its dated id:
+
+```python
+from zarx import pin, tier_of, Z_FAST
+
+pin(Z_FAST, "2026-10")         # "z-fast-2026-10"
+tier_of("z-fast-2026-10")      # "z-fast"
+```
+
+Reasoning tokens count toward `max_tokens`: give `z-pro` at least 128 (`zarx.models.Z_PRO_MIN_MAX_TOKENS`), or the answer can come back empty with `finish_reason` `length`. The reasoning tiers accept `reasoning_effort` (`none`, `low`, `medium`, `high`) and return their reasoning next to the answer. `z-ultra` still reasons with `none` (stage, 2026-10-31), so leave it room in `max_tokens`:
+
+```python
+from zarx import reasoning_text
+
+message = completion.choices[0].message
+print(reasoning_text(message))  # None when the tier returned no reasoning
+```
+
+## Responses API and data
+
+```python
+response = client.responses.create(model="z-pro", input="Two lines on GDPR.", max_output_tokens=256)
+print(response.output_text)
+```
+
+This client sends `store=False` unless you pass `store=True`. The server default is `store=True`, and how long stored content is kept depends on your key's retention policy. See `docs/data.md` in the repository.
+
+## Errors
+
+Zarx answers in the OpenAI error format, so the OpenAI exception classes apply and are re-exported:
+
+```python
+import zarx
+
+try:
+    client.chat.completions.create(model="z-unknown", messages=[{"role": "user", "content": "hi"}])
+except zarx.NotFoundError as exc:
+    print(exc.code)  # model_not_found
+```
+
+A missing key raises `zarx.ZarxConfigError` before any request is made.
+
+### Retries and rate limits
+
+Like the OpenAI client, `Zarx` retries twice on connection errors, 408, 409, 429 and 5xx. On a 429 it waits what the `retry-after` header says (up to 59 seconds), so one call can block silently for up to about 2 minutes. Zarx keeps nothing after the response, so a retry runs the request again (there is no server-side deduplication; `Idempotency-Key` is ignored). When latency or a duplicate matters, turn retries off and handle the error yourself:
+
+```python
+client = Zarx(max_retries=0)
+try:
+    client.chat.completions.create(model="z-fast", messages=[{"role": "user", "content": "hi"}])
+except zarx.RateLimitError as exc:
+    print(exc.response.headers.get("retry-after"))  # seconds until the next minute window
+```
+
+Chat Completions responses carry `x-ratelimit-*` headers (requests and tokens: limit, remaining, reset) when your account has rate limits set, and every response carries an `x-request-id`. The per-minute window is the clock minute. See `docs/errors.md`.
+
+## Production or beta
+
+| Environment | Base URL | What it is |
+|---|---|---|
+| `production` (default) | `https://api.zarx.ai/v1` | the stable API |
+| `beta` | `https://api-stage.zarx.ai/v1` | the stage environment: new models and features land here first and may change |
+
+```python
+from zarx import Zarx
+
+client = Zarx()                         # production
+beta = Zarx(environment="beta")         # beta; "prod" and "stage" also work
+```
+
+The first that is set wins: `base_url=`, `environment=`, `ZARX_BASE_URL`, `ZARX_ENVIRONMENT`, then production. What the code says beats what the shell says. Keys are per environment: a production key gets 401 on beta and the other way round, so set the key that matches. `zarx.ENVIRONMENTS`, `zarx.PRODUCTION_BASE_URL` and `zarx.BETA_BASE_URL` are exported; `STAGE_BASE_URL` stays as an alias of `BETA_BASE_URL`. Realtime transcription follows the client's environment.
+
+## Command line
+
+```bash
+zarx models                       # models your key can use
+zarx chat "Hello"                 # streams the answer from z-fast
+zarx chat -m z-pro --show-reasoning "Why is the sky blue?"
+zarx speak "Good morning" -o hello.wav      # text to speech (WAV; -f mp3 for MP3, -v for the voice)
+zarx transcribe hello.wav                   # speech to text
+zarx translate "Good morning" --to es       # text translation (a code or a name: es, Spanish)
+zarx forecast 3 4 6 5 7 9 -p 3              # next 3 periods of a series (hourly steps ending now)
+zarx forecast --csv visits.csv -p 24 --band # from a CSV, with a low/high band; --json for the raw answer
+zarx --beta models                # same against beta (or ZARX_ENVIRONMENT=beta)
+```
+
+Exit codes: 0 success, 1 API or network error, 2 configuration or input error (for example, no key, or fewer than 3 values to forecast).
+
+If the console cannot print a character of the answer (for example a Windows console in cp1252 and an answer with Japanese text), `zarx` prints `?` in its place instead of failing. Set `PYTHONIOENCODING=utf-8` to see every character.
+
+## Audio
+
+One call each, with the client built from the environment unless you pass `client=`:
+
+```python
+from zarx import audio
+
+text = audio.transcribe("meeting.wav")                       # speech to text
+wav = audio.speak("Good morning", voice="marin")             # text to speech, WAV bytes
+spanish = audio.translate("Good morning", "Spanish")         # text translation
+text = audio.transcribe_realtime("meeting-16k.wav", on_delta=print)  # text as it is recognised
+spanish_wav = audio.speech_to_speech("meeting.wav", "es")      # voice to voice, WAV bytes
+for piece in audio.speak_stream("Good morning"):             # speech in pieces (beta), PCM 24 kHz
+    player.write(piece)
+```
+
+Voices: `zarx.voices.voices()` lists them and `zarx.voices.voice_catalog()` adds the design attributes (beta and production since 2026-11-02; a deployment without the route raises `zarx.voices.VoicesNotAvailableError`).
+
+`zarx.audio` (`transcribe`, `speak`, `translate`) and the `zarx speak`, `zarx transcribe` and `zarx translate` commands were run against stage on 2026-10-30, 2026-10-31 and 2026-11-01 with a zero-retention key: all three audio models are cleared for zero retention and answer 200. The audio model names may still change before general availability. Production lists the audio models since 2026-11-02; the measurements below are from stage (beta):
+
+- `transcribe` (`z-transcribe`, `/v1/audio/transcriptions`): WAV (8, 16, 24 or 44.1 kHz, mono or stereo), MP3 or FLAC. 13 languages detected from the audio, plus Catalan, Galician and Basque on files when you name them: `transcribe(path, language="ca")` (`gl`, `eu`; the plain ISO 639-1 code) is served by a second engine of Zarx behind the same model, same name and price (beta since 2026-11-02; production when its next release is promoted). Without `language`, Catalan comes out as Spanish with no warning, so name the language when you know it. For the other languages `language` is a hint that does not change the result; `prompt` never does. `response_format="text"` answers plain text (`text/plain`) on production and beta; the helper returns the text. `verbose_json`, `srt` and `vtt` get 400 (on beta `verbose_json` is answered when `language` is `ca`, `gl` or `eu`). `/v1/audio/translations` does not translate.
+- `transcribe_realtime` (`z-transcribe`, WebSocket at `/v1/audio/transcriptions/realtime`, Zarx's own events, not the OpenAI Realtime API): takes a WAV file or bytes in PCM16 mono 16 kHz (other WAV formats are refused before connecting), raw PCM bytes, or an iterable of PCM chunks (a microphone). `on_delta(text)` gets every piece of recognised text, `on_segment(text)` every finished sentence; the return value is the final transcript. Needs the `realtime` extra (`websockets`). A 3 s sample answered in 1.4 s on stage on 2026-11-01. Catalan, Galician and Basque are served on files only: the live route refuses `source_language` `ca`, `gl` or `eu` with `unsupported_language` (the helper never sends it), and Catalan audio sent live comes out as Spanish.
+- `speak` (`z-speech`, `/v1/audio/speech`): `response_format` `wav` (default, 24 kHz mono 16-bit), `mp3`, `opus`, `flac`, `aac` or `pcm`; `ogg` gets 422. `voice` defaults to `"alloy"`, one of 13 presets (`alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `marin`, `nova`, `onyx`, `sage`, `shimmer`, `verse`); `auto` also works, and `design:<attributes>` builds a voice from comma-separated attributes, at most one per group (gender, age, pitch, style, accent), for example `design:female,british accent` or `design:male,elderly,low pitch`; the lists are in `zarx.audio.VOICE_DESIGN_ATTRIBUTES`; free text or an unknown name gets 400 `invalid_voice` with a partner key and 422 with an account-wide key, and two attributes of one group (two accents) get 500. The same preset is not guaranteed to sound identical across calls. `speed` works; free-text `instructions` gets 422.
+- `speak_stream` (`z-speech` with `stream_format="sse"`): yields the audio in pieces as it is generated (PCM by default, about ten pieces for a sentence) and sets `.usage` (`{"input_characters": N}`) at the end. Streams on beta and production (2026-11-02); a deployment that does not stream sends the whole audio as one piece.
+- `translate` (`z-translate`, through chat completions): the target is a language name in English (`"Spanish"`) or a code (`"es"`, `"pt-BR"`); good for English, Spanish, French and German, and `GET /v1/models` lists the 36 languages it serves in `capabilities.languages.supported` on beta. Catalan, Galician and Basque are not served by `z-translate`: on beta since 2026-11-02 the request answers 400 `unsupported_language` (`openai.BadRequestError`; before that it answered Spanish in 8 of 10 sentences; production when its next release is promoted). The helper does not switch models by itself: for those three languages pass `model="z-ultra"`, `zarx.audio.translate(text, "ca", model="z-ultra")` (45 of 46 correct in our test).
+- `speech_to_speech` (`z-voice`, `/v1/audio/speech-to-speech`): an audio file in, the same speech in `target_language` (an ISO 639-1 code, default `"en"`) out, as WAV bytes whatever format is asked. About 3 s for a short sentence on beta and production (2026-11-02). `target_language` `"ca"`, `"gl"` or `"eu"` works with nothing to do on your side: the translation step runs on `z-ultra` behind the same call (beta since 2026-11-02, a Spanish clip into Catalan in 4.2 s; production when its next release is promoted).
+- Use the model name you sent, not the `model` field of audio responses, to identify the model.
+
+See `docs/models.md` for the routes and events.
+
+## Forecasting
+
+```python
+import zarx
+
+result = zarx.forecast([3, 4, 6, 5, 7, 9], 3)                 # next 3 periods, hourly steps ending now
+result = zarx.forecast(pairs, 12, include_band=True)            # [(timestamp, value), ...] with a low/high band
+result = zarx.forecast_csv("visits.csv", 24, data_points=256)   # header row, timestamp first, value last
+
+print(result.values)              # the point forecasts
+for point in result:              # .timestamp, .value, .low, .high, .percentiles
+    print(point.timestamp, point.value)
+print(result.billable_points)     # what the call is billed for (usage.datapoints, or context plus forecast points)
+```
+
+`series` is a list of numbers (one timestamp every `step`, default `"1h"`, ending now or starting at `start`), of `(timestamp, value)` pairs, of dicts `{"timestamp", "value", ...covariates}`, or a mapping of timestamp to value; at least 3 points. Pass real timestamps when you have them, the model uses the calendar. `periods` must be at least 1. Anything else you pass as a keyword goes into the request body as is (for example `forecast_extra_params={"quantile_low": 0.2, "quantile_high": 0.8}`). `result.raw` is the response exactly as the API returned it.
+
+Verified on beta on 2026-11-01 and 2026-11-02 with `z-forecast` (64 hourly points, a 512-row CSV, a 12-point daily series); production lists the model since 2026-11-02. The horizon is at most 1,000 periods per call. See `docs/models.md`.
+
+## Development
+
+```bash
+uv venv .venv && uv pip install -e '.[dev]'
+.venv/bin/pytest                    # offline tests
+ZARX_API_KEY=... ZARX_ENVIRONMENT=beta .venv/bin/pytest -m live   # with a beta key
+uv build                            # wheel and sdist in dist/
+```
+
+The `dev` extra includes `websockets`, which the `realtime` extra adds for users of `transcribe_realtime`.
+
+## License
+
+Apache License 2.0. See LICENSE and NOTICE.