brain-db-sdk 0.1.0__tar.gz

brain_db_sdk-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Rust
+/rust/target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+
+# TypeScript / Node
+node_modules/
+/typescript/dist/
+*.tsbuildinfo
+
+# OS
+.DS_Store

brain_db_sdk-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Niraj Georgian
+
+   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.

brain_db_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: brain-db-sdk
+Version: 0.1.0
+Summary: Python client SDK for the Brain memory database. Speaks Brain's BRN0 wire protocol directly over TCP.
+Project-URL: Homepage, https://github.com/arc-labs-ai/brain-sdk
+Project-URL: Repository, https://github.com/arc-labs-ai/brain-sdk
+Author: Niraj Georgian
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,brain,client,database,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cbor2>=5.9
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# brain-db-sdk (Python)
+
+The Python client for the Brain memory database. Speaks Brain's BRN0 wire
+protocol directly; no dependency on Brain's internal code.
+
+**Status: typed-graph verbs (Phase 6).** The wire codec (Phase 1) is **verified
+byte-for-byte against the shared conformance corpus** (all 86 `.bin`/`.json`
+cases re-encode to identical bytes). On top of it, a synchronous connection
+layer (a `transport` over a socket, a `Connection` running the handshake HELLO →
+WELCOME → AUTH → AUTH_OK and request/response, a `BrainClient` holding the
+negotiated session), the three v1 verbs with ergonomic builders (`encode()`,
+`recall()` streaming to EOS / `recall_frames()`, `forget()`), a `with_retry`
+helper + `RetryPolicy` (exponential backoff, server `retry_after_ms`), and the
+typed-graph verbs: `create_entity()`, `create_statement()`, `create_relation()`,
+`upload_schema()`, and `materialize_procedural()`; and the space/session registry
+verbs: `create_space()` / `list_spaces()` / `delete_space()` and
+`create_session()` / `list_sessions()` / `delete_session()` for managing the
+per-request isolation unit (space) and conversation groupings (session) that a
+trusted principal targets via `act_as`. `BrainClient` is built on a
+`MuxConnection`: a background reader thread demultiplexes responses by
+`stream_id`, so **every verb is concurrency-safe** and many requests run in
+flight at once over one connection from multiple threads. A `Pool` opens a fixed
+set of such connections and hands them out round-robin for socket-level
+parallelism. Transparent reconnect and an `asyncio` client are later phases.
+
+The full build plan is in the repo-root [`../PLAN.md`](../PLAN.md); the
+layered architecture is in [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
+
+```python
+from brain_db_sdk import (
+    BrainClient, EncodeBuilder, RecallBuilder, ForgetBuilder, RetryPolicy, with_retry,
+)
+
+with BrainClient.connect("127.0.0.1", 7878) as client:
+    stored = client.encode(EncodeBuilder("the user prefers dark mode").build())
+    answer = client.recall(RecallBuilder("ui preferences").limit(5).build())
+    # answer.answer_kind is Single/Set (fact answer.values) or Episodic
+    # (memory answer.results); NoSubject/NoMemory means "don't know".
+    # Ride out transient ResourceExhausted/Unavailable; the stable request_id
+    # makes the resend idempotent.
+    req = ForgetBuilder(stored.memory_id).build()
+    with_retry(lambda: client.forget(req), RetryPolicy())
+```
+
+Develop + verify against the corpus:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install cbor2 pytest
+PYTHONPATH=src .venv/bin/python -m pytest tests/ -q
+```
+
+The integration suites run against a real server when `BRAIN_SDK_IT_DATA` is
+set, and skip otherwise; `scripts/it-server.sh up` boots one and prints the
+vars. Set `BRAIN_SDK_IT_REQUIRED=1` wherever a server is meant to be reachable
+so a misconfigured one fails instead of reading as green.
+
+Layout (folder-per-concern, mirroring the reference Rust SDK):
+
+```
+src/brain_db_sdk/
+  wire/        frame + CBOR codec, opcodes, typed payloads (corpus-verified)
+  errors.py    client error taxonomy (BrainError + subclasses)
+  transport.py sync read/write of whole frames over a socket
+  connection.py handshake + one-at-a-time request/response
+  client.py    high-level BrainClient: connect, handshake, encode/recall/forget
+  verbs.py     ergonomic EncodeBuilder / RecallBuilder / ForgetBuilder
+  retry.py     RetryPolicy + with_retry (exponential backoff, server retry_after)
+```
+
+## HTTP tier
+
+For hosted Brain (the Arc cloud gateway) or a self-hosted `brain-edge` edge, the
+package also ships `BrainHttpClient` — a JSON-over-HTTP client with the same verb
+surface, field names, and error shape as the Rust and TypeScript SDKs (the
+canonical contract is [`../HTTP_CONTRACT.md`](../HTTP_CONTRACT.md)). Use it when
+you talk to Brain through an HTTP edge and authenticate with an API key; use the
+wire `BrainClient` above for a direct socket, streaming, transactions, and
+typed-graph management. It has no third-party dependency — pure `urllib`.
+
+```python
+from brain_db_sdk import BrainHttpClient
+
+brain = BrainHttpClient(api_key, base_url="https://api.arc-labs.ai")
+stored = brain.encode(text="the kettle whistled")
+answer = brain.recall(query="what whistled?", max_results=3)
+who = brain.whoami()  # namespace + space_id + permissions
+```
+
+Dependencies: `cbor2` (runtime), `pytest` (dev). CRC32C is pure Python.
+
+The live HTTP edge smoke tests cover identity, capabilities, and a memory
+encode/recall/list/forget lifecycle across all SDKs. Run them from the repo
+root with `BRAIN_SDK_IT_HTTP=https://edge.example BRAIN_SDK_IT_HTTP_KEY=brain_…
+scripts/edge-it.sh`.
+License: Apache-2.0.

brain_db_sdk-0.1.0/README.md

@@ -0,0 +1,95 @@
+# brain-db-sdk (Python)
+
+The Python client for the Brain memory database. Speaks Brain's BRN0 wire
+protocol directly; no dependency on Brain's internal code.
+
+**Status: typed-graph verbs (Phase 6).** The wire codec (Phase 1) is **verified
+byte-for-byte against the shared conformance corpus** (all 86 `.bin`/`.json`
+cases re-encode to identical bytes). On top of it, a synchronous connection
+layer (a `transport` over a socket, a `Connection` running the handshake HELLO →
+WELCOME → AUTH → AUTH_OK and request/response, a `BrainClient` holding the
+negotiated session), the three v1 verbs with ergonomic builders (`encode()`,
+`recall()` streaming to EOS / `recall_frames()`, `forget()`), a `with_retry`
+helper + `RetryPolicy` (exponential backoff, server `retry_after_ms`), and the
+typed-graph verbs: `create_entity()`, `create_statement()`, `create_relation()`,
+`upload_schema()`, and `materialize_procedural()`; and the space/session registry
+verbs: `create_space()` / `list_spaces()` / `delete_space()` and
+`create_session()` / `list_sessions()` / `delete_session()` for managing the
+per-request isolation unit (space) and conversation groupings (session) that a
+trusted principal targets via `act_as`. `BrainClient` is built on a
+`MuxConnection`: a background reader thread demultiplexes responses by
+`stream_id`, so **every verb is concurrency-safe** and many requests run in
+flight at once over one connection from multiple threads. A `Pool` opens a fixed
+set of such connections and hands them out round-robin for socket-level
+parallelism. Transparent reconnect and an `asyncio` client are later phases.
+
+The full build plan is in the repo-root [`../PLAN.md`](../PLAN.md); the
+layered architecture is in [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
+
+```python
+from brain_db_sdk import (
+    BrainClient, EncodeBuilder, RecallBuilder, ForgetBuilder, RetryPolicy, with_retry,
+)
+
+with BrainClient.connect("127.0.0.1", 7878) as client:
+    stored = client.encode(EncodeBuilder("the user prefers dark mode").build())
+    answer = client.recall(RecallBuilder("ui preferences").limit(5).build())
+    # answer.answer_kind is Single/Set (fact answer.values) or Episodic
+    # (memory answer.results); NoSubject/NoMemory means "don't know".
+    # Ride out transient ResourceExhausted/Unavailable; the stable request_id
+    # makes the resend idempotent.
+    req = ForgetBuilder(stored.memory_id).build()
+    with_retry(lambda: client.forget(req), RetryPolicy())
+```
+
+Develop + verify against the corpus:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install cbor2 pytest
+PYTHONPATH=src .venv/bin/python -m pytest tests/ -q
+```
+
+The integration suites run against a real server when `BRAIN_SDK_IT_DATA` is
+set, and skip otherwise; `scripts/it-server.sh up` boots one and prints the
+vars. Set `BRAIN_SDK_IT_REQUIRED=1` wherever a server is meant to be reachable
+so a misconfigured one fails instead of reading as green.
+
+Layout (folder-per-concern, mirroring the reference Rust SDK):
+
+```
+src/brain_db_sdk/
+  wire/        frame + CBOR codec, opcodes, typed payloads (corpus-verified)
+  errors.py    client error taxonomy (BrainError + subclasses)
+  transport.py sync read/write of whole frames over a socket
+  connection.py handshake + one-at-a-time request/response
+  client.py    high-level BrainClient: connect, handshake, encode/recall/forget
+  verbs.py     ergonomic EncodeBuilder / RecallBuilder / ForgetBuilder
+  retry.py     RetryPolicy + with_retry (exponential backoff, server retry_after)
+```
+
+## HTTP tier
+
+For hosted Brain (the Arc cloud gateway) or a self-hosted `brain-edge` edge, the
+package also ships `BrainHttpClient` — a JSON-over-HTTP client with the same verb
+surface, field names, and error shape as the Rust and TypeScript SDKs (the
+canonical contract is [`../HTTP_CONTRACT.md`](../HTTP_CONTRACT.md)). Use it when
+you talk to Brain through an HTTP edge and authenticate with an API key; use the
+wire `BrainClient` above for a direct socket, streaming, transactions, and
+typed-graph management. It has no third-party dependency — pure `urllib`.
+
+```python
+from brain_db_sdk import BrainHttpClient
+
+brain = BrainHttpClient(api_key, base_url="https://api.arc-labs.ai")
+stored = brain.encode(text="the kettle whistled")
+answer = brain.recall(query="what whistled?", max_results=3)
+who = brain.whoami()  # namespace + space_id + permissions
+```
+
+Dependencies: `cbor2` (runtime), `pytest` (dev). CRC32C is pure Python.
+
+The live HTTP edge smoke tests cover identity, capabilities, and a memory
+encode/recall/list/forget lifecycle across all SDKs. Run them from the repo
+root with `BRAIN_SDK_IT_HTTP=https://edge.example BRAIN_SDK_IT_HTTP_KEY=brain_…
+scripts/edge-it.sh`.
+License: Apache-2.0.

brain_db_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,229 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "brain-db-sdk"
+version = "0.1.0" # x-release-please-version
+description = "Python client SDK for the Brain memory database. Speaks Brain's BRN0 wire protocol directly over TCP."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Niraj Georgian" }]
+keywords = ["brain", "memory", "ai-agents", "client", "database"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  # CBOR (RFC 8949) payload maps. cbor2 distinguishes byte strings from
+  # arrays (required for id / [u8;N] fields) and exposes per-value
+  # minimal-float encoding, which the wire format needs for f32 fields.
+  # >=5.9 is a security floor, not a feature floor: cbor2 5.6-5.8 are
+  # vulnerable to CVE-2026-26209 (CVSS 7.5) -- uncontrolled recursion in
+  # loads() lets a peer crash the client with a <100KB deeply-nested payload.
+  # 5.9 added the nesting-depth cap that turns that into a clean
+  # CBORDecodeError. See tests/test_malformed.py, which pins the behaviour.
+  "cbor2>=5.9",
+  # CRC32C is implemented in pure Python (wire/crc32c.py) — no native or
+  # network dependency for a core checksum.
+]
+
+[project.urls]
+Homepage = "https://github.com/arc-labs-ai/brain-sdk"
+Repository = "https://github.com/arc-labs-ai/brain-sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.16", "pyright>=1.1.400"]
+
+[tool.ruff]
+target-version = "py310"
+# Matches the TypeScript SDK's Biome setting and the width this code was
+# already written to. Ruff's default 88 would reflow 198 existing lines for no
+# reason; 100 reflows 93 and they are genuinely long.
+line-length = 100
+
+[tool.ruff.format]
+# The formatter half, which this package did not have. Rust has rustfmt and
+# TypeScript now has Biome; leaving Python unformatted was the odd one out.
+docstring-code-format = true
+
+[tool.ruff.lint]
+# Everything on, exceptions written down.
+#
+# The previous selection was ["F", "E9", "B"]. Running `--select ALL` produced
+# ~3400 findings; the ones removed below are removed for a stated reason, with
+# the count they produced, so the next person can see they were considered
+# rather than never enabled. Starting from ALL also means a new ruff release
+# arrives with its new rules already on, which is the same "no silent drift"
+# property the protocol gates give the wire.
+select = ["ALL"]
+
+ignore = [
+  # -- the formatter owns these ------------------------------------------
+  "E501",   # 299. line-too-long: `ruff format` decides line breaks.
+  "COM812", # 174. missing-trailing-comma: same.
+  "ISC001", #      single-line-implicit-concat: conflicts with the formatter.
+  "ISC003", #      explicit-string-concat: directly contradicts ISC004, which
+  #      is kept. In a collection literal an *implicit* concat is
+  #      one missing comma away from silently merging two elements,
+  #      so the explicit `+` is the safer of the two.
+
+  # -- docstring style, not docstring absence -----------------------------
+  # This package is heavily documented; what pydocstyle objects to is the
+  # *shape*. The prose here is deliberately multi-paragraph and explanatory,
+  # and these rules would flatten it.
+  "D203", #      incompatible with D211, which is the convention used.
+  "D205", # 211. blank line required after a one-line summary.
+  "D209", # 164. multi-line closing quotes on their own line.
+  "D213", # 285. multi-line summary on the second line: this codebase puts
+  #      the summary on the first line (D212), which is the opposite.
+  "D401", #  21. imperative mood ("Returns the…" vs "Return the…").
+  "D400", #   1. first line must end with a period.
+  "D415", #   1. same, with more punctuation allowed.
+
+  # -- fights what this package is ----------------------------------------
+  "PLR2004", #  74. magic-value-comparison: opcodes, CBOR major types and
+  #      frame offsets are magic numbers by definition.
+  "FBT001", #  26. boolean-typed positional argument, and
+  "FBT002", #   6. boolean default, and
+  "FBT003", #  91. boolean positional in a call — the wire dataclasses mirror
+  #      the server's field order, which is not ours to reshape.
+  "TRY003", #  29. long message outside the exception class, and
+  "EM101",  #   7. string literal in a raise, and
+  "EM102",  #  22. f-string in a raise — a wire error should say what byte or
+  #      field was wrong, at the point that knows.
+  "CPY001", #  49. missing copyright notice: the licence is in LICENSE.
+  "UP045",  # 193. `Optional[X]` -> `X | None`, and
+  "UP007",  #   2. the same for Union. These were required at the old >=3.9
+  #      floor, where `X | Y` is not available at runtime and several
+  #      of these modules evaluate annotations eagerly. At >=3.10 the
+  #      syntax works, so the ignores are now a deliberate choice not
+  #      to churn ~195 annotation sites rather than a hard constraint.
+  "PYI019", #   3. same TypeVar-instead-of-Self constraint as PYI034 below.
+  "PYI034", #   3. `__enter__` should return `Self` — which is 3.11+, while
+  #      requires-python is >=3.10, and `typing_extensions` is not a
+  #      dependency. A `TypeVar` bound to the class carries the same
+  #      meaning and is what these use; ruff's autofix for this rule
+  #      imports typing_extensions and breaks the install.
+  "TC001", #   1. and
+  "TC003", #   3. move typing-only imports into a TYPE_CHECKING block. The
+  #      saving is a few microseconds of import time; the risk is a
+  #      dataclass or a `get_type_hints` call resolving a name that
+  #      is no longer there at runtime. Not worth it for this shape
+  #      of code.
+  "D107", #  12. undocumented `__init__`: every one is a one-line
+  #      constructor under a class docstring that already says what
+  #      the type is and what it carries. A second docstring below
+  #      it would restate the first.
+  "RUF022", #   1. `__all__` is grouped by tier (wire, http, client) with a
+  #      comment on each group; alphabetising it would scatter the
+  #      groups and orphan the comments.
+  "D105", #   8. undocumented magic method: `__enter__`/`__exit__`/`__iter__`
+  #      mean exactly what the protocol says they mean.
+  "N818", #  11. exception names must end in "Error": these mirror the Rust
+  #      SDK's variant names (VersionMismatch, ConnectionClosed) so
+  #      the three SDKs read the same.
+
+  # -- thresholds, not defects --------------------------------------------
+  "PLR0913", #   7. too-many-arguments
+  "PLR0917", #   7. too-many-positional-arguments
+  "PLR0915", #   3. too-many-statements
+  "PLR0912", #   2. too-many-branches
+  "PLR0911", #   2. too-many-return-statements
+  "C901",    #   3. complex-structure
+
+  # -- wrong for this code, on inspection ---------------------------------
+  "PERF203", #   4. try-except in a loop: every one is a retry or a
+  #      best-effort cleanup, which is what the construct is for.
+  "S110", #   4. try-except-pass: all four are best-effort connection
+  #      teardown, already carrying a comment saying so. A failure
+  #      to close a socket we are discarding is not actionable.
+]
+
+[tool.ruff.lint.per-file-ignores]
+# The wire and HTTP type modules mirror the server's structs one-for-one. Their
+# documentation is the protocol itself — `conformance/protocol.json` carries
+# every field and serde attribute, and the corpus pins the bytes. A docstring
+# on each of ~495 generated-equivalent `to_map`/`from_map` methods would
+# restate the method name and bury the ones that do carry meaning.
+"src/brain_db_sdk/wire/types.py" = [
+  "D101",
+  "D102",
+  "D105",
+  "D106",
+  "D107",
+  "RUF012",
+]
+"src/brain_db_sdk/http/types.py" = ["D101", "D102", "D105", "D106", "D107"]
+
+# Tests: `assert` is what pytest is built on, fixture data is camelCase because
+# the wire is, and the feature folders deliberately have no `__init__.py` (the
+# pytest importlib mode below is what makes that work).
+"tests/**" = [
+  "S101",    # 368. assert
+  "INP001",  #  30. implicit namespace package
+  "ANN",     # 111. missing annotations on test helpers
+  "D100",
+  "D101",
+  "D102",
+  "D103",
+  "D104",
+  "D107",
+  "N815",    #   4. camelCase in class scope — JSON fixture keys
+  "N812",    #   1. lowercase import aliased to non-lowercase
+  "PLC0415", #   3. import outside top-level — deliberate lazy imports
+  "E402",    #   1. import not at top — after a guard
+  "PT018",   #  15. composite assertion
+  "SLF001",  #      private member access: tests check internals on purpose
+  "S105",
+  "S106",
+  "S311",
+]
+
+[tool.pytest.ini_options]
+# importlib import mode lets the feature folders (tests/encode/, tests/recall/,
+# …) each carry a `test_<feature>.py` without basename collisions against the
+# flat offline suites (e.g. tests/test_handshake.py vs tests/handshake/…).
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+markers = [
+  "slow: builds a wheel; excluded from the default run with -m 'not slow'",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/brain_db_sdk"]
+# PEP 561: without this marker in the built wheel, a downstream type checker
+# MUST ignore every annotation in the installed package — so all of the typing
+# above would reach exactly nobody. `tests/test_py_typed.py` asserts it is
+# present and listed here.
+artifacts = ["src/brain_db_sdk/py.typed"]
+
+[tool.pyright]
+# The type checker the other two SDKs always had: Rust has the compiler,
+# TypeScript has `tsc`, and Python had annotations that nothing verified.
+#
+# pyright rather than mypy. The original reason was that mypy 2.x refuses to
+# target anything below 3.10 and the floor was 3.9, so mypy could not check the
+# version we ship. At a >=3.10 floor that no longer applies, and pyright stays
+# on its own merits: it is what Pylance runs, so what CI enforces is what a
+# user sees in their editor.
+include = ["src/brain_db_sdk"]
+pythonVersion = "3.10"
+# `standard`, not `strict`, and the difference is recorded rather than hidden:
+# strict additionally reports 112 `reportUnknown*` diagnostics, essentially all
+# of them in `wire/types.py`'s externally-tagged union helpers, where a
+# `variant: str` selects which of several shapes `value` holds. Typing those
+# fully means writing out every union arm; four of the eleven are done (see
+# AuthCredentials, StatementValue, StatementObject, RetrieverSelection) and the
+# rest are the same mechanical work. `standard` gates on every diagnostic that
+# indicates an actual type error, which is what this is for; the count above is
+# the honest size of what it does not yet cover.
+typeCheckingMode = "standard"
+# Reported as errors rather than warnings so CI actually gates on them.
+reportMissingTypeStubs = "error"