byterover 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. byterover-0.2.0/.gitignore +4 -0
  2. byterover-0.2.0/CHANGELOG.md +26 -0
  3. byterover-0.2.0/LICENSE +21 -0
  4. byterover-0.2.0/PKG-INFO +270 -0
  5. byterover-0.2.0/README.md +247 -0
  6. byterover-0.2.0/pyproject.toml +38 -0
  7. byterover-0.2.0/src/byterover/__init__.py +86 -0
  8. byterover-0.2.0/src/byterover/_client.py +260 -0
  9. byterover-0.2.0/src/byterover/_core/__init__.py +0 -0
  10. byterover-0.2.0/src/byterover/_core/config.py +110 -0
  11. byterover-0.2.0/src/byterover/_core/construct.py +82 -0
  12. byterover-0.2.0/src/byterover/_core/content.py +164 -0
  13. byterover-0.2.0/src/byterover/_core/errors.py +380 -0
  14. byterover-0.2.0/src/byterover/_core/idempotency.py +18 -0
  15. byterover-0.2.0/src/byterover/_core/pagination.py +50 -0
  16. byterover-0.2.0/src/byterover/_core/path.py +89 -0
  17. byterover-0.2.0/src/byterover/_core/presigned.py +38 -0
  18. byterover-0.2.0/src/byterover/_core/retry.py +125 -0
  19. byterover-0.2.0/src/byterover/_core/transport.py +374 -0
  20. byterover-0.2.0/src/byterover/_core/validate.py +40 -0
  21. byterover-0.2.0/src/byterover/_file_types.py +53 -0
  22. byterover-0.2.0/src/byterover/_version.py +2 -0
  23. byterover-0.2.0/src/byterover/helpers/__init__.py +1 -0
  24. byterover-0.2.0/src/byterover/helpers/_pool.py +83 -0
  25. byterover-0.2.0/src/byterover/helpers/_source.py +176 -0
  26. byterover-0.2.0/src/byterover/helpers/upload.py +462 -0
  27. byterover-0.2.0/src/byterover/helpers/upload_directory.py +285 -0
  28. byterover-0.2.0/src/byterover/helpers/wait.py +125 -0
  29. byterover-0.2.0/src/byterover/py.typed +0 -0
  30. byterover-0.2.0/src/byterover/resources/__init__.py +20 -0
  31. byterover-0.2.0/src/byterover/resources/_base.py +124 -0
  32. byterover-0.2.0/src/byterover/resources/_operations.py +138 -0
  33. byterover-0.2.0/src/byterover/resources/documents.py +521 -0
  34. byterover-0.2.0/src/byterover/resources/drives.py +34 -0
  35. byterover-0.2.0/src/byterover/resources/folders.py +101 -0
  36. byterover-0.2.0/src/byterover/resources/key.py +21 -0
  37. byterover-0.2.0/src/byterover/resources/operations.py +40 -0
  38. byterover-0.2.0/src/byterover/resources/uploads.py +143 -0
  39. byterover-0.2.0/src/byterover/types/__init__.py +90 -0
  40. byterover-0.2.0/src/byterover/types/_models.py +429 -0
@@ -0,0 +1,4 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
@@ -0,0 +1,26 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 (2026-11-16)
4
+
5
+ The first version of the ByteRover Python SDK, published as `byterover` on PyPI.
6
+
7
+ **It replaces the old `byterover` client.** The PyPI project `byterover` held an older "Python client library for
8
+ Byterover" at 0.1.0 to 0.1.8. Version 0.2.0 is a new SDK with a new API, and it isn't compatible with 0.1.x: code
9
+ written for 0.1.x doesn't run on 0.2.0 without changes. The 0.1.x releases stay on PyPI; to keep the old client, pin
10
+ it with `pip install "byterover<0.2"`.
11
+
12
+ - The distribution is `byterover` (`pip install byterover`), and the import name is `byterover`.
13
+ - A client for every operation an API key can call: the key, drives, folders, documents (list, read, content,
14
+ put text, update, copy, delete), uploads in parts, operations and search, plus `request()` for any other `/v1/` path.
15
+ - Retries only when they are safe: a write or a search whose outcome is unknown is never sent again.
16
+ - Helpers: `documents.upload()` from a path, bytes, a seekable file or a range source, with parallel parts, refreshed
17
+ part URLs and a safe completion; `uploads.resume()` after a crash; `documents.upload_directory()`;
18
+ `operations.wait()`; `documents.content()` resumes a cut download with Range and If-Range, and `write_to_file()`.
19
+ - A search sends an `Idempotency-Key` only when you pass one; a 2xx that isn't JSON is an error (`INVALID_RESPONSE`).
20
+ - Responses are pydantic models built without validation: fields and enum values a newer server adds come through.
21
+ - `documents.upload_directory()` opens each file without following a link, and only if it is still the file the
22
+ folder walk saw; a file swapped since is listed in `failed` and never read. Windows junctions are skipped.
23
+ - Errors pickle with their public fields only, never with the API key or an `Authorization` header.
24
+ - `QueryValue` is exported.
25
+ - Sync, thread-safe, with one `httpx.Client`; Python 3.11 or later. Its runtime dependencies are `httpx` and
26
+ `pydantic`. Licensed under MIT.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ByteRover, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: byterover
3
+ Version: 0.2.0
4
+ Summary: The ByteRover Python SDK: search your team's drives and manage their documents through the ByteRover API.
5
+ Project-URL: Homepage, https://docs.byterover.ai
6
+ Project-URL: Documentation, https://docs.byterover.ai/api/python-sdk
7
+ Author: ByteRover, Inc.
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: api,byterover,documents,rag,retrieval,sdk,search
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.11
20
+ Requires-Dist: httpx<1,>=0.27
21
+ Requires-Dist: pydantic<3,>=2.7
22
+ Description-Content-Type: text/markdown
23
+
24
+ # ByteRover Python SDK
25
+
26
+ The ByteRover Python SDK: search your drives and manage their documents from Python.
27
+
28
+ > **0.2.0 replaces the old `byterover` client.** The PyPI project `byterover` used to hold an older client (0.1.0 to
29
+ > 0.1.8) with another API. This SDK isn't compatible with it: code written for 0.1.x needs changes. To keep the old
30
+ > client, pin it with `pip install "byterover<0.2"`. See the [changelog](https://docs.byterover.ai/changelog).
31
+
32
+ ```sh
33
+ pip install byterover
34
+ # or
35
+ uv add byterover
36
+ ```
37
+
38
+ - The import name is `byterover`.
39
+ - Python 3.11 to 3.13 (see Compatibility, below). Its runtime dependencies are `httpx` and `pydantic`, whose licenses
40
+ are under Dependencies, below.
41
+ - Sync and thread-safe: one client, one `httpx.Client`. After `os.fork()`, create a new client in the child.
42
+ - Docs: [docs.byterover.ai/api/python-sdk](https://docs.byterover.ai/api/python-sdk).
43
+
44
+ ## Get an API key
45
+
46
+ A team owner or admin creates one in ByteRover: select **API keys** under **Team** in the sidebar, then **Create
47
+ key**, and choose its scope (**Search**, or **Read and write**), its drives and its expiry. The secret is shown only
48
+ once, so put it in your secret store, then in the `BYTEROVER_API_KEY` environment variable. A key starts with `brv_`.
49
+ See [Authentication and API keys](https://docs.byterover.ai/api/authentication).
50
+
51
+ ## Start
52
+
53
+ ```python
54
+ from byterover import ByteRover
55
+
56
+ client = ByteRover() # reads BYTEROVER_API_KEY, and BYTEROVER_BASE_URL if set
57
+
58
+ found = client.search(
59
+ query="How long do refunds take in the EU?",
60
+ drive_ids=["drv_…"],
61
+ effort="medium", # sets the price; there is no default
62
+ )
63
+ for result in found.results:
64
+ print(" > ".join(result.location.heading_path), result.text)
65
+ ```
66
+
67
+ | Option | Default |
68
+ |---|---|
69
+ | `api_key` | `BYTEROVER_API_KEY`; the constructor raises without one |
70
+ | `base_url` | `BYTEROVER_BASE_URL`, then `https://byterover.ai/api`. It must be https, except on loopback |
71
+ | `timeout` | 60 s for each step of an attempt (waiting for a connection, connecting, each write, each read); not a total limit. A search gets 105 s at `medium` and 135 s at `high`; any call takes its own `timeout` |
72
+ | `max_retries` | 2 |
73
+ | `http_client` | one of the client's own; part uploads go through it too |
74
+ | `logger` | none: nothing is logged |
75
+
76
+ The key is never shown in full: `repr(client)`, errors and logs show `brv_` and four characters. Use the client in a
77
+ `with` block, or call `client.close()`, to close its connections.
78
+
79
+ ## What it covers
80
+
81
+ | | |
82
+ |---|---|
83
+ | `client.key.retrieve()` | the key and the drives it reaches |
84
+ | `client.drives.list()`, `retrieve(drive_id)` | |
85
+ | `client.folders.list`, `create`, `move` (`from_=`, `to=`), `delete` | |
86
+ | `client.documents.list(drive_id, folder=, name=, status=, sort=, order=, limit=)` | pages, see below |
87
+ | `client.documents.retrieve`, `list_revisions`, `read`, `content` | `content` streams the original file |
88
+ | `client.documents.put_text`, `update`, `copy`, `delete` | |
89
+ | `client.uploads.create`, `list_parts`, `put_part`, `complete` | uploads in parts, straight to storage |
90
+ | `client.operations.retrieve(id)` | the work a write started |
91
+ | `client.search(query=, drive_ids=, effort=, …)` | |
92
+ | `client.request(method, path, query=, body=)` | any other `/v1/` path, with the same key and retries |
93
+
94
+ Fields keep the API's names (`drive_ids`, `next_cursor`, `apiKey`). Responses are pydantic models built without
95
+ validation: fields a newer server adds are kept (`model_extra`, `to_dict()`), and an enum value this SDK doesn't know
96
+ arrives as a string, so give a `match` over one a default case. Requests are typed with closed enums, so a type
97
+ checker catches a misspelled value.
98
+
99
+ ### Pages
100
+
101
+ ```python
102
+ for document in client.documents.list(drive_id, folder="/policies"):
103
+ print(document.path)
104
+ first = client.documents.list(drive_id).first_page() # or one page, with next_cursor
105
+ for page in client.documents.list(drive_id).pages():
106
+ print(len(page.documents))
107
+ ```
108
+
109
+ ### Status, headers and the trace id
110
+
111
+ ```python
112
+ answered = client.with_raw_response.documents.retrieve(document_id)
113
+ print(answered.data.path, answered.status, answered.trace_id)
114
+ ```
115
+
116
+ Quote the `trace_id` (on a response or an error) when you contact support.
117
+
118
+ ## Errors
119
+
120
+ Every error is a `ByteRoverError`. An error response is an `APIStatusError` with `status`, `code` (always a string),
121
+ `message` and `trace_id`, as one of: `BadRequestError` 400, `AuthenticationError` 401, `InsufficientBalanceError`
122
+ 402, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409 (see `code`: `VERSION_MISMATCH`,
123
+ `UPLOAD_CLOSED`, …), `RateLimitError` 429, `InternalServerError` 500 and any other 5xx, and `ServiceUnavailableError`
124
+ 503/504. On any 5xx, `from_gateway` is true when a proxy answered, not ByteRover, and the outcome is unknown. Each
125
+ error also keeps its `response` and parsed `body`. A 2xx whose body isn't JSON (a captive portal, a web page) is an
126
+ `APIStatusError` with `code` `INVALID_RESPONSE`. No response at all is an `APIConnectionError`, or an
127
+ `APITimeoutError` when the timeout ran out. A redirect is refused, not followed, so the key never leaves `base_url`.
128
+
129
+ ## Retries and writes sent twice
130
+
131
+ A call is retried only when that is safe:
132
+
133
+ - anything, when the connection failed before the request went out (`error.sent == "no"`), and on a 429 from
134
+ ByteRover;
135
+ - reads, also after a timeout, a lost connection, a 5xx or a 429 from a proxy;
136
+ - **never** a write or a search whose outcome is unknown (a timeout, a lost connection, a 5xx). The write may have
137
+ run, and the search may have been charged.
138
+
139
+ Every write sends an `Idempotency-Key` (a new one per call, kept across its retries); a search sends one only when you
140
+ pass `idempotency_key`. After an unknown outcome, check the state first
141
+ (`documents.retrieve`, `documents.list`, `operations.retrieve`), and only then send the write again with the same
142
+ `idempotency_key`:
143
+
144
+ ```python
145
+ client.documents.put_text(drive_id, path="/notes/today.txt", text=text, idempotency_key="notes-2026-11-15")
146
+ ```
147
+
148
+ If your process dies, a key the SDK made dies with it: pass your own when a write must survive a crash. Keys are kept
149
+ for 24 hours.
150
+
151
+ Stopping your program (Ctrl-C) stops the client; it doesn't stop the server, which may still finish (and, for a
152
+ search, charge) what it started. There is no server-side cancel.
153
+
154
+ ## Uploads
155
+
156
+ `documents.upload()` does the whole upload: it hashes the file (the API wants its size and SHA-256 first), opens the
157
+ upload, sends the parts to storage four at a time, refreshes part URLs that expired (they last 15 minutes), retries a
158
+ part that failed on the way, and completes it. The API chooses the part size (`part_size` in its upload plan, 8 MiB
159
+ today); `on_upload_created` hands you `part_count` and `part_size`.
160
+
161
+ ```python
162
+ result = client.documents.upload(
163
+ drive_id,
164
+ "/reports/q3.pdf",
165
+ "q3.pdf",
166
+ tags=["finance"],
167
+ wait="searchable", # or "done"; by default it returns once the upload is complete
168
+ )
169
+ print(result.document.id, result.operation.status)
170
+ ```
171
+
172
+ The source must be readable twice: a file path, bytes, a seekable binary file (`open(path, "rb")`), or an object with
173
+ `size` and `read(start, end)`. A one-shot stream is refused, with an error that says why. Every option is checked
174
+ before the file is read.
175
+
176
+ Ctrl-C raises at once and starts no more parts. A part already being sent can't be cut, so it finishes (or
177
+ times out under `part_timeout`) in the background, and Python waits for it before the process exits.
178
+
179
+ If your process may die mid-upload, keep what `on_upload_created` hands you (it holds no URL or key, so it can go in
180
+ a file or a database), and finish later with the same file:
181
+
182
+ ```python
183
+ from byterover import UploadIncompleteError
184
+
185
+ try:
186
+ client.documents.upload(drive_id, path, file, on_upload_created=lambda saved: store.put(path, saved))
187
+ except UploadIncompleteError:
188
+ # Now, or after a restart: the upload is still pending.
189
+ client.uploads.resume(store.get(path), file)
190
+ ```
191
+
192
+ A resume works while the upload is pending, and sends every part again. A part that can't be sent ends the upload
193
+ with an `UploadIncompleteError`, which names the `upload_id` and `path` (the part's own error is its `__cause__`).
194
+
195
+ If completing an upload loses its response, the SDK sends the same completion again. That's safe: the server claims
196
+ the upload first, so a completed upload just answers its document again. While another completion is still running,
197
+ the SDK keeps asking, backing off, for `complete_wait` (2 minutes by default), then raises an `UploadIncompleteError`.
198
+ Each completion attempt gets `complete_timeout` (the client's timeout by default). Raise it for very large files.
199
+
200
+ Run with your own `idempotency_key`, running `documents.upload()` again with the same key and file either finishes the
201
+ earlier upload, or answers the document the earlier run already made, for as long as the API keeps the key (24
202
+ hours). It doesn't upload the file a second time.
203
+
204
+ `documents.upload_directory(drive_id, "docs", prefix="/imports")` uploads every file whose extension the API accepts.
205
+ Hidden files and folders (`.git`, `.env`), empty files, symbolic links and files that can't be read are skipped and
206
+ listed; `include_hidden` and `ignore` change that. A file swapped for a link, a folder or another file after the
207
+ folder was read is never read: it is listed in `failed`. It isn't atomic: the result lists what `succeeded`, what uploaded
208
+ but isn't ready (`uploaded_not_ready`: the document exists, its wait failed), what `failed` and what was
209
+ `skipped`. `upload={"wait": "searchable"}` passes `wait`, `wait_timeout` and `part_concurrency` to each file's
210
+ upload. Stopping it (Ctrl-C) still raises once the files in flight have settled; a file whose completion was cut off
211
+ may still be stored, so look for it with `documents.list` before uploading it again.
212
+
213
+ `operations.wait(operation.id)` polls until the operation is `done`, at the pace the API asks for. A poll that fails
214
+ on the way (a gateway's 504 while a big file is ingested, a lost connection) is asked again at the next poll, until the
215
+ deadline. It raises `OperationFailedError` when the operation fails, and `WaitTimeoutError` after `timeout` (10
216
+ minutes by default), with the last failure as its `__cause__` when the API kept failing. The operation goes on on the
217
+ server either way.
218
+
219
+ With `wait`, anything that fails after the upload completed is an `UploadWaitError`: the document exists, and the
220
+ error carries `document_id` and `operation_id` (and the original error as `__cause__`). Don't upload the file again:
221
+ wait for the operation again. `on_upload_completed` hands you the document before any wait.
222
+
223
+ The building blocks are there too: `uploads.create`, `list_parts`, `put_part` and `complete`. `put_part` sends no API
224
+ header and never logs the URL, which is itself a credential.
225
+
226
+ ## Downloads
227
+
228
+ `documents.content(id)` streams the original file: `iter_bytes()`, `read()`, `text()` or `write_to_file(path)`. If
229
+ the connection is cut, or nothing arrives for the call's timeout, the SDK asks for the rest with `Range` and
230
+ `If-Range` on the file's ETag. If the file changed in between, the read fails instead of joining two versions.
231
+
232
+ ## Compatibility
233
+
234
+ | | Supported | Tested in CI |
235
+ |---|---|---|
236
+ | Python | 3.11 to 3.13 (`requires-python = ">=3.11"`) | 3.11, 3.12 and 3.13 |
237
+ | Operating system | any | Linux |
238
+
239
+ The package installs on a later Python too, but only the versions above are tested.
240
+
241
+ ## Versioning
242
+
243
+ The SDK is at 0.x: a new minor version (0.2 to 0.3) may break your code, and a patch version (0.2.0 to 0.2.1) fixes
244
+ bugs without breaking it. Pin a minor version, such as `byterover>=0.2,<0.3`, and read the changelog before you move
245
+ to the next one. The TypeScript SDK, `@byterover/sdk`, has the same version number. See
246
+ [Versioning and support](https://docs.byterover.ai/api/sdk-versioning).
247
+
248
+ ## Dependencies
249
+
250
+ | Package | Why | License |
251
+ |---|---|---|
252
+ | `httpx` (`>=0.27,<1`) | HTTP | BSD-3-Clause |
253
+ | `pydantic` (`>=2.7,<3`) | response models | MIT |
254
+ | `certifi`, through `httpx` | the CA certificates httpx trusts | MPL-2.0 |
255
+
256
+ `httpx` and `pydantic` also bring `httpcore`, `idna` (BSD-3-Clause), `anyio`, `h11`, `pydantic-core`,
257
+ `annotated-types`, `typing-inspection` (MIT) and `typing-extensions` (PSF-2.0).
258
+
259
+ ## Docs, changelog and support
260
+
261
+ - Docs: [Python SDK](https://docs.byterover.ai/api/python-sdk), and the
262
+ [API reference](https://docs.byterover.ai/api-reference/introduction).
263
+ - Changelog: [docs.byterover.ai/changelog](https://docs.byterover.ai/changelog), and `CHANGELOG.md` in the sdist.
264
+ - Support: contact ByteRover support and quote the `trace_id` (on a response or an error). For a search, add its
265
+ `search_id`; for a write, the `id` of its operation. See
266
+ [Errors and retries](https://docs.byterover.ai/api/errors#get-help).
267
+
268
+ ## License
269
+
270
+ MIT.
@@ -0,0 +1,247 @@
1
+ # ByteRover Python SDK
2
+
3
+ The ByteRover Python SDK: search your drives and manage their documents from Python.
4
+
5
+ > **0.2.0 replaces the old `byterover` client.** The PyPI project `byterover` used to hold an older client (0.1.0 to
6
+ > 0.1.8) with another API. This SDK isn't compatible with it: code written for 0.1.x needs changes. To keep the old
7
+ > client, pin it with `pip install "byterover<0.2"`. See the [changelog](https://docs.byterover.ai/changelog).
8
+
9
+ ```sh
10
+ pip install byterover
11
+ # or
12
+ uv add byterover
13
+ ```
14
+
15
+ - The import name is `byterover`.
16
+ - Python 3.11 to 3.13 (see Compatibility, below). Its runtime dependencies are `httpx` and `pydantic`, whose licenses
17
+ are under Dependencies, below.
18
+ - Sync and thread-safe: one client, one `httpx.Client`. After `os.fork()`, create a new client in the child.
19
+ - Docs: [docs.byterover.ai/api/python-sdk](https://docs.byterover.ai/api/python-sdk).
20
+
21
+ ## Get an API key
22
+
23
+ A team owner or admin creates one in ByteRover: select **API keys** under **Team** in the sidebar, then **Create
24
+ key**, and choose its scope (**Search**, or **Read and write**), its drives and its expiry. The secret is shown only
25
+ once, so put it in your secret store, then in the `BYTEROVER_API_KEY` environment variable. A key starts with `brv_`.
26
+ See [Authentication and API keys](https://docs.byterover.ai/api/authentication).
27
+
28
+ ## Start
29
+
30
+ ```python
31
+ from byterover import ByteRover
32
+
33
+ client = ByteRover() # reads BYTEROVER_API_KEY, and BYTEROVER_BASE_URL if set
34
+
35
+ found = client.search(
36
+ query="How long do refunds take in the EU?",
37
+ drive_ids=["drv_…"],
38
+ effort="medium", # sets the price; there is no default
39
+ )
40
+ for result in found.results:
41
+ print(" > ".join(result.location.heading_path), result.text)
42
+ ```
43
+
44
+ | Option | Default |
45
+ |---|---|
46
+ | `api_key` | `BYTEROVER_API_KEY`; the constructor raises without one |
47
+ | `base_url` | `BYTEROVER_BASE_URL`, then `https://byterover.ai/api`. It must be https, except on loopback |
48
+ | `timeout` | 60 s for each step of an attempt (waiting for a connection, connecting, each write, each read); not a total limit. A search gets 105 s at `medium` and 135 s at `high`; any call takes its own `timeout` |
49
+ | `max_retries` | 2 |
50
+ | `http_client` | one of the client's own; part uploads go through it too |
51
+ | `logger` | none: nothing is logged |
52
+
53
+ The key is never shown in full: `repr(client)`, errors and logs show `brv_` and four characters. Use the client in a
54
+ `with` block, or call `client.close()`, to close its connections.
55
+
56
+ ## What it covers
57
+
58
+ | | |
59
+ |---|---|
60
+ | `client.key.retrieve()` | the key and the drives it reaches |
61
+ | `client.drives.list()`, `retrieve(drive_id)` | |
62
+ | `client.folders.list`, `create`, `move` (`from_=`, `to=`), `delete` | |
63
+ | `client.documents.list(drive_id, folder=, name=, status=, sort=, order=, limit=)` | pages, see below |
64
+ | `client.documents.retrieve`, `list_revisions`, `read`, `content` | `content` streams the original file |
65
+ | `client.documents.put_text`, `update`, `copy`, `delete` | |
66
+ | `client.uploads.create`, `list_parts`, `put_part`, `complete` | uploads in parts, straight to storage |
67
+ | `client.operations.retrieve(id)` | the work a write started |
68
+ | `client.search(query=, drive_ids=, effort=, …)` | |
69
+ | `client.request(method, path, query=, body=)` | any other `/v1/` path, with the same key and retries |
70
+
71
+ Fields keep the API's names (`drive_ids`, `next_cursor`, `apiKey`). Responses are pydantic models built without
72
+ validation: fields a newer server adds are kept (`model_extra`, `to_dict()`), and an enum value this SDK doesn't know
73
+ arrives as a string, so give a `match` over one a default case. Requests are typed with closed enums, so a type
74
+ checker catches a misspelled value.
75
+
76
+ ### Pages
77
+
78
+ ```python
79
+ for document in client.documents.list(drive_id, folder="/policies"):
80
+ print(document.path)
81
+ first = client.documents.list(drive_id).first_page() # or one page, with next_cursor
82
+ for page in client.documents.list(drive_id).pages():
83
+ print(len(page.documents))
84
+ ```
85
+
86
+ ### Status, headers and the trace id
87
+
88
+ ```python
89
+ answered = client.with_raw_response.documents.retrieve(document_id)
90
+ print(answered.data.path, answered.status, answered.trace_id)
91
+ ```
92
+
93
+ Quote the `trace_id` (on a response or an error) when you contact support.
94
+
95
+ ## Errors
96
+
97
+ Every error is a `ByteRoverError`. An error response is an `APIStatusError` with `status`, `code` (always a string),
98
+ `message` and `trace_id`, as one of: `BadRequestError` 400, `AuthenticationError` 401, `InsufficientBalanceError`
99
+ 402, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409 (see `code`: `VERSION_MISMATCH`,
100
+ `UPLOAD_CLOSED`, …), `RateLimitError` 429, `InternalServerError` 500 and any other 5xx, and `ServiceUnavailableError`
101
+ 503/504. On any 5xx, `from_gateway` is true when a proxy answered, not ByteRover, and the outcome is unknown. Each
102
+ error also keeps its `response` and parsed `body`. A 2xx whose body isn't JSON (a captive portal, a web page) is an
103
+ `APIStatusError` with `code` `INVALID_RESPONSE`. No response at all is an `APIConnectionError`, or an
104
+ `APITimeoutError` when the timeout ran out. A redirect is refused, not followed, so the key never leaves `base_url`.
105
+
106
+ ## Retries and writes sent twice
107
+
108
+ A call is retried only when that is safe:
109
+
110
+ - anything, when the connection failed before the request went out (`error.sent == "no"`), and on a 429 from
111
+ ByteRover;
112
+ - reads, also after a timeout, a lost connection, a 5xx or a 429 from a proxy;
113
+ - **never** a write or a search whose outcome is unknown (a timeout, a lost connection, a 5xx). The write may have
114
+ run, and the search may have been charged.
115
+
116
+ Every write sends an `Idempotency-Key` (a new one per call, kept across its retries); a search sends one only when you
117
+ pass `idempotency_key`. After an unknown outcome, check the state first
118
+ (`documents.retrieve`, `documents.list`, `operations.retrieve`), and only then send the write again with the same
119
+ `idempotency_key`:
120
+
121
+ ```python
122
+ client.documents.put_text(drive_id, path="/notes/today.txt", text=text, idempotency_key="notes-2026-11-15")
123
+ ```
124
+
125
+ If your process dies, a key the SDK made dies with it: pass your own when a write must survive a crash. Keys are kept
126
+ for 24 hours.
127
+
128
+ Stopping your program (Ctrl-C) stops the client; it doesn't stop the server, which may still finish (and, for a
129
+ search, charge) what it started. There is no server-side cancel.
130
+
131
+ ## Uploads
132
+
133
+ `documents.upload()` does the whole upload: it hashes the file (the API wants its size and SHA-256 first), opens the
134
+ upload, sends the parts to storage four at a time, refreshes part URLs that expired (they last 15 minutes), retries a
135
+ part that failed on the way, and completes it. The API chooses the part size (`part_size` in its upload plan, 8 MiB
136
+ today); `on_upload_created` hands you `part_count` and `part_size`.
137
+
138
+ ```python
139
+ result = client.documents.upload(
140
+ drive_id,
141
+ "/reports/q3.pdf",
142
+ "q3.pdf",
143
+ tags=["finance"],
144
+ wait="searchable", # or "done"; by default it returns once the upload is complete
145
+ )
146
+ print(result.document.id, result.operation.status)
147
+ ```
148
+
149
+ The source must be readable twice: a file path, bytes, a seekable binary file (`open(path, "rb")`), or an object with
150
+ `size` and `read(start, end)`. A one-shot stream is refused, with an error that says why. Every option is checked
151
+ before the file is read.
152
+
153
+ Ctrl-C raises at once and starts no more parts. A part already being sent can't be cut, so it finishes (or
154
+ times out under `part_timeout`) in the background, and Python waits for it before the process exits.
155
+
156
+ If your process may die mid-upload, keep what `on_upload_created` hands you (it holds no URL or key, so it can go in
157
+ a file or a database), and finish later with the same file:
158
+
159
+ ```python
160
+ from byterover import UploadIncompleteError
161
+
162
+ try:
163
+ client.documents.upload(drive_id, path, file, on_upload_created=lambda saved: store.put(path, saved))
164
+ except UploadIncompleteError:
165
+ # Now, or after a restart: the upload is still pending.
166
+ client.uploads.resume(store.get(path), file)
167
+ ```
168
+
169
+ A resume works while the upload is pending, and sends every part again. A part that can't be sent ends the upload
170
+ with an `UploadIncompleteError`, which names the `upload_id` and `path` (the part's own error is its `__cause__`).
171
+
172
+ If completing an upload loses its response, the SDK sends the same completion again. That's safe: the server claims
173
+ the upload first, so a completed upload just answers its document again. While another completion is still running,
174
+ the SDK keeps asking, backing off, for `complete_wait` (2 minutes by default), then raises an `UploadIncompleteError`.
175
+ Each completion attempt gets `complete_timeout` (the client's timeout by default). Raise it for very large files.
176
+
177
+ Run with your own `idempotency_key`, running `documents.upload()` again with the same key and file either finishes the
178
+ earlier upload, or answers the document the earlier run already made, for as long as the API keeps the key (24
179
+ hours). It doesn't upload the file a second time.
180
+
181
+ `documents.upload_directory(drive_id, "docs", prefix="/imports")` uploads every file whose extension the API accepts.
182
+ Hidden files and folders (`.git`, `.env`), empty files, symbolic links and files that can't be read are skipped and
183
+ listed; `include_hidden` and `ignore` change that. A file swapped for a link, a folder or another file after the
184
+ folder was read is never read: it is listed in `failed`. It isn't atomic: the result lists what `succeeded`, what uploaded
185
+ but isn't ready (`uploaded_not_ready`: the document exists, its wait failed), what `failed` and what was
186
+ `skipped`. `upload={"wait": "searchable"}` passes `wait`, `wait_timeout` and `part_concurrency` to each file's
187
+ upload. Stopping it (Ctrl-C) still raises once the files in flight have settled; a file whose completion was cut off
188
+ may still be stored, so look for it with `documents.list` before uploading it again.
189
+
190
+ `operations.wait(operation.id)` polls until the operation is `done`, at the pace the API asks for. A poll that fails
191
+ on the way (a gateway's 504 while a big file is ingested, a lost connection) is asked again at the next poll, until the
192
+ deadline. It raises `OperationFailedError` when the operation fails, and `WaitTimeoutError` after `timeout` (10
193
+ minutes by default), with the last failure as its `__cause__` when the API kept failing. The operation goes on on the
194
+ server either way.
195
+
196
+ With `wait`, anything that fails after the upload completed is an `UploadWaitError`: the document exists, and the
197
+ error carries `document_id` and `operation_id` (and the original error as `__cause__`). Don't upload the file again:
198
+ wait for the operation again. `on_upload_completed` hands you the document before any wait.
199
+
200
+ The building blocks are there too: `uploads.create`, `list_parts`, `put_part` and `complete`. `put_part` sends no API
201
+ header and never logs the URL, which is itself a credential.
202
+
203
+ ## Downloads
204
+
205
+ `documents.content(id)` streams the original file: `iter_bytes()`, `read()`, `text()` or `write_to_file(path)`. If
206
+ the connection is cut, or nothing arrives for the call's timeout, the SDK asks for the rest with `Range` and
207
+ `If-Range` on the file's ETag. If the file changed in between, the read fails instead of joining two versions.
208
+
209
+ ## Compatibility
210
+
211
+ | | Supported | Tested in CI |
212
+ |---|---|---|
213
+ | Python | 3.11 to 3.13 (`requires-python = ">=3.11"`) | 3.11, 3.12 and 3.13 |
214
+ | Operating system | any | Linux |
215
+
216
+ The package installs on a later Python too, but only the versions above are tested.
217
+
218
+ ## Versioning
219
+
220
+ The SDK is at 0.x: a new minor version (0.2 to 0.3) may break your code, and a patch version (0.2.0 to 0.2.1) fixes
221
+ bugs without breaking it. Pin a minor version, such as `byterover>=0.2,<0.3`, and read the changelog before you move
222
+ to the next one. The TypeScript SDK, `@byterover/sdk`, has the same version number. See
223
+ [Versioning and support](https://docs.byterover.ai/api/sdk-versioning).
224
+
225
+ ## Dependencies
226
+
227
+ | Package | Why | License |
228
+ |---|---|---|
229
+ | `httpx` (`>=0.27,<1`) | HTTP | BSD-3-Clause |
230
+ | `pydantic` (`>=2.7,<3`) | response models | MIT |
231
+ | `certifi`, through `httpx` | the CA certificates httpx trusts | MPL-2.0 |
232
+
233
+ `httpx` and `pydantic` also bring `httpcore`, `idna` (BSD-3-Clause), `anyio`, `h11`, `pydantic-core`,
234
+ `annotated-types`, `typing-inspection` (MIT) and `typing-extensions` (PSF-2.0).
235
+
236
+ ## Docs, changelog and support
237
+
238
+ - Docs: [Python SDK](https://docs.byterover.ai/api/python-sdk), and the
239
+ [API reference](https://docs.byterover.ai/api-reference/introduction).
240
+ - Changelog: [docs.byterover.ai/changelog](https://docs.byterover.ai/changelog), and `CHANGELOG.md` in the sdist.
241
+ - Support: contact ByteRover support and quote the `trace_id` (on a response or an error). For a search, add its
242
+ `search_id`; for a write, the `id` of its operation. See
243
+ [Errors and retries](https://docs.byterover.ai/api/errors#get-help).
244
+
245
+ ## License
246
+
247
+ MIT.
@@ -0,0 +1,38 @@
1
+ [project]
2
+ name = "byterover"
3
+ version = "0.2.0"
4
+ description = "The ByteRover Python SDK: search your team's drives and manage their documents through the ByteRover API."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "ByteRover, Inc." }]
9
+ keywords = ["byterover", "search", "retrieval", "rag", "documents", "api", "sdk"]
10
+ classifiers = [
11
+ "Development Status :: 4 - Beta",
12
+ "Intended Audience :: Developers",
13
+ "Operating System :: OS Independent",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3.11",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Typing :: Typed",
19
+ ]
20
+ requires-python = ">=3.11"
21
+ dependencies = ["httpx>=0.27,<1", "pydantic>=2.7,<3"]
22
+
23
+ [project.urls]
24
+ Homepage = "https://docs.byterover.ai"
25
+ Documentation = "https://docs.byterover.ai/api/python-sdk"
26
+
27
+ [dependency-groups]
28
+ dev = ["pyright[nodejs]==1.1.414", "pytest==8.4.2", "respx==0.23.1", "ruff==0.14.1"]
29
+
30
+ [build-system]
31
+ requires = ["hatchling==1.27.0"]
32
+ build-backend = "hatchling.build"
33
+
34
+ [tool.hatch.build.targets.wheel]
35
+ packages = ["src/byterover"]
36
+
37
+ [tool.hatch.build.targets.sdist]
38
+ only-include = ["src/byterover", "README.md", "CHANGELOG.md", "LICENSE"]