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.
- byterover-0.2.0/.gitignore +4 -0
- byterover-0.2.0/CHANGELOG.md +26 -0
- byterover-0.2.0/LICENSE +21 -0
- byterover-0.2.0/PKG-INFO +270 -0
- byterover-0.2.0/README.md +247 -0
- byterover-0.2.0/pyproject.toml +38 -0
- byterover-0.2.0/src/byterover/__init__.py +86 -0
- byterover-0.2.0/src/byterover/_client.py +260 -0
- byterover-0.2.0/src/byterover/_core/__init__.py +0 -0
- byterover-0.2.0/src/byterover/_core/config.py +110 -0
- byterover-0.2.0/src/byterover/_core/construct.py +82 -0
- byterover-0.2.0/src/byterover/_core/content.py +164 -0
- byterover-0.2.0/src/byterover/_core/errors.py +380 -0
- byterover-0.2.0/src/byterover/_core/idempotency.py +18 -0
- byterover-0.2.0/src/byterover/_core/pagination.py +50 -0
- byterover-0.2.0/src/byterover/_core/path.py +89 -0
- byterover-0.2.0/src/byterover/_core/presigned.py +38 -0
- byterover-0.2.0/src/byterover/_core/retry.py +125 -0
- byterover-0.2.0/src/byterover/_core/transport.py +374 -0
- byterover-0.2.0/src/byterover/_core/validate.py +40 -0
- byterover-0.2.0/src/byterover/_file_types.py +53 -0
- byterover-0.2.0/src/byterover/_version.py +2 -0
- byterover-0.2.0/src/byterover/helpers/__init__.py +1 -0
- byterover-0.2.0/src/byterover/helpers/_pool.py +83 -0
- byterover-0.2.0/src/byterover/helpers/_source.py +176 -0
- byterover-0.2.0/src/byterover/helpers/upload.py +462 -0
- byterover-0.2.0/src/byterover/helpers/upload_directory.py +285 -0
- byterover-0.2.0/src/byterover/helpers/wait.py +125 -0
- byterover-0.2.0/src/byterover/py.typed +0 -0
- byterover-0.2.0/src/byterover/resources/__init__.py +20 -0
- byterover-0.2.0/src/byterover/resources/_base.py +124 -0
- byterover-0.2.0/src/byterover/resources/_operations.py +138 -0
- byterover-0.2.0/src/byterover/resources/documents.py +521 -0
- byterover-0.2.0/src/byterover/resources/drives.py +34 -0
- byterover-0.2.0/src/byterover/resources/folders.py +101 -0
- byterover-0.2.0/src/byterover/resources/key.py +21 -0
- byterover-0.2.0/src/byterover/resources/operations.py +40 -0
- byterover-0.2.0/src/byterover/resources/uploads.py +143 -0
- byterover-0.2.0/src/byterover/types/__init__.py +90 -0
- byterover-0.2.0/src/byterover/types/_models.py +429 -0
|
@@ -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.
|
byterover-0.2.0/LICENSE
ADDED
|
@@ -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.
|
byterover-0.2.0/PKG-INFO
ADDED
|
@@ -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"]
|