async-sonic 0.1.0__tar.gz

async_sonic-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,cfg}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

async_sonic-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Something does not work as documented
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What you did, what you expected and what you got instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A short script we can run against a Sonic server.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or output
+      render: text
+  - type: input
+    id: sonic
+    attributes:
+      label: Sonic server version
+      placeholder: v1.9.1
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and OS
+      placeholder: "3.14.0, macOS 15"
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: async-sonic version or commit

async_sonic-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/cr0hn/async-sonic/security/advisories/new
+    about: Please report vulnerabilities privately, not as a public issue.

async_sonic-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest an improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Include the API you would like to call, if it applies.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - label: It does not require runtime dependencies
+          required: true

async_sonic-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What and why
+
+<!-- What does this change, and why? Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] Unit test added or updated (`tests/test_unit.py`)
+- [ ] Integration test added or updated, if it affects real-server behaviour (`tests/test_integration.py`)
+- [ ] `uv run ruff check .`, `uv run ruff format --check .`, `uv run pyright` and `uv run pytest` pass (0 skipped)
+- [ ] `README.md` and `llms.txt` updated if the public API changed
+- [ ] No new runtime dependencies

async_sonic-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly

async_sonic-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - name: Pre-pull the Sonic image
+        run: docker pull valeriansaliou/sonic:v1.9.1
+      - name: Tests (unit + integration against a real Sonic; nothing may be skipped)
+        run: |
+          uv run pytest -ra | tee pytest.log
+          if grep -Eq '[0-9]+ skipped' pytest.log; then
+            echo "::error::Tests were skipped; CI requires every test to run"
+            exit 1
+          fi

async_sonic-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - name: Pre-pull the Sonic image
+        run: docker pull valeriansaliou/sonic:v1.9.1
+      - name: Tests (nothing may be skipped)
+        run: |
+          uv run pytest -ra | tee pytest.log
+          if grep -Eq '[0-9]+ skipped' pytest.log; then
+            echo "Tests were skipped; refusing to publish."
+            exit 1
+          fi
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Trusted Publishing (OIDC); no API token stored in secrets
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.12.4

async_sonic-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/

async_sonic-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at cr0hn@cr0hn.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

async_sonic-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to async-sonic
+
+Thanks for your interest. Bug reports, fixes and improvements are welcome.
+
+## Ground rules
+
+- **Zero runtime dependencies.** The client is the Sonic protocol on top of `asyncio`; keep it that way.
+- **Keep it small.** The library is a single module on purpose. Prefer the simplest change that works.
+- **Tests at both levels.** Every change comes with a unit test (fake server, `tests/test_unit.py`) and,
+  when it touches behaviour visible to a real server, an integration test (`tests/test_integration.py`).
+- **English** for code, comments, docs, error messages and commit messages.
+- Protocol questions are settled by Sonic's [`PROTOCOL.md`](https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md)
+  and by what a real server does; when they disagree, document the deviation in the README.
+
+## Setup
+
+Python 3.14+ and [uv](https://docs.astral.sh/uv/). Integration tests also need Docker.
+
+```bash
+git clone https://github.com/cr0hn/async-sonic
+cd async-sonic
+uv sync
+```
+
+## Before opening a pull request
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+```
+
+CI runs the same commands against a real Sonic in Docker and **fails if any test is skipped**, so
+run the whole suite with Docker available and check that the `skipped` count is 0.
+
+If you change the public API, update `README.md` and `llms.txt` in the same pull request.
+
+## Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`,
+`chore:`...). There is no `CHANGELOG.md`: the git history is the changelog.
+
+## Releasing (maintainers)
+
+Publishing uses PyPI Trusted Publishing (OIDC); there are no tokens in the repository secrets.
+One-time setup: on PyPI, add a trusted publisher for this repository, workflow `publish.yml`,
+environment `pypi`.
+
+1. Bump `version` in `pyproject.toml` and merge it to `main` with CI green.
+2. Tag it: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+3. Publish a GitHub Release for that tag. The `Publish` workflow re-runs ruff, pyright and the full
+   test suite against a real Sonic, builds, runs `twine check` and uploads to PyPI.
+
+The workflow can also be started manually (`workflow_dispatch`) from the Actions tab.
+
+## Reporting bugs and security issues
+
+Use the issue templates. For vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of opening a
+public issue.
+
+By contributing you agree that your contributions are licensed under the [MIT License](LICENSE).

async_sonic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Alfocea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

async_sonic-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: async-sonic
+Version: 0.1.0
+Summary: A zero-dependency, fully typed asyncio client for the Sonic search index, with connection pooling and pipelining.
+Project-URL: Homepage, https://github.com/cr0hn/async-sonic
+Project-URL: Repository, https://github.com/cr0hn/async-sonic
+Project-URL: Issues, https://github.com/cr0hn/async-sonic/issues
+Author-email: Daniel Alfocea <cr0hn@cr0hn.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,asyncio,client,connection-pool,pipelining,search,sonic,sonic-search,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# async-sonic
+
+A zero-dependency, fully typed asyncio client for the [Sonic](https://github.com/valeriansaliou/sonic) search index, with connection pooling and pipelining.
+
+[![CI](https://github.com/cr0hn/async-sonic/actions/workflows/ci.yml/badge.svg)](https://github.com/cr0hn/async-sonic/actions/workflows/ci.yml)
+![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+LLM-friendly reference: [`llms.txt`](llms.txt).
+
+## Table of contents
+
+- [Why async-sonic](#why-async-sonic)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [API reference](#api-reference)
+- [Concurrency and performance](#concurrency-and-performance)
+- [Error handling](#error-handling)
+- [Escaping and limits](#escaping-and-limits)
+- [Compatibility and limitations](#compatibility-and-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why async-sonic
+
+Sonic is a fast, lightweight search index that speaks a plain-text protocol
+([`PROTOCOL.md`](https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md)).
+The asyncio client that existed on PyPI (`asonic`, last released in 2020) does not work, and
+the other clients are synchronous. `async-sonic` implements the protocol from its specification
+on top of `asyncio.open_connection` and nothing else.
+
+- **One class**: `Sonic(host, port, password)` used as `async with`, with flat, obviously named
+  methods (`push`, `query`, `suggest`, ...). Channels, handshake and pool are hidden.
+- **Fast**: a lazy per-channel connection pool plus pipelining (one background reader per
+  connection). See [the numbers](#concurrency-and-performance).
+- **Zero runtime dependencies**, Python 3.14+, strict typing, `py.typed`.
+- **Honest errors**: no hidden retries; every exception message says what happened and what to do.
+- **LLM-friendly**: short docstrings with a one-line example on every public method, plus
+  [`llms.txt`](llms.txt).
+
+## Installation
+
+```bash
+uv add async-sonic        # or: pip install async-sonic
+```
+
+The package is not on PyPI yet; until then install from Git:
+
+```bash
+uv add git+https://github.com/cr0hn/async-sonic
+# or: pip install git+https://github.com/cr0hn/async-sonic
+```
+
+## Quickstart
+
+<!-- quickstart -->
+```python
+import asyncio
+from async_sonic import Sonic
+
+
+async def main() -> None:
+    async with Sonic("localhost", 1491, "SecretPassword") as sonic:
+        await sonic.push("videos", "catalog", "video:1", "cats and dogs are funny", lang="eng")
+        await sonic.push("videos", "catalog", "video:2", "stray dogs", lang="eng")
+        print(await sonic.query("videos", "catalog", "cats", lang="eng"))
+        await sonic.trigger(
+            "consolidate"
+        )  # SUGGEST reads a graph that is only updated on consolidate
+        print(await sonic.suggest("videos", "catalog", "fun"))
+        await sonic.flush_collection("videos")
+
+
+asyncio.run(main())
+```
+Output:
+```text
+['video:1']
+['funny']
+```
+<!-- /quickstart -->
+
+This block is executed as a test against a real Sonic
+(`tests/test_integration.py::test_readme_quickstart_runs`), so it cannot drift from the code.
+To try it, start Sonic (see [Development](#development)) and use its host, port and password.
+
+## API reference
+
+`Sonic` opens nothing on construction or on `async with` entry: connections are opened lazily on
+the first command, one pool per channel.
+
+```python
+Sonic(host="localhost", port=1491, password="", *,
+      pool_size=4, max_in_flight=None, timeout=10.0, connect_timeout=5.0)
+```
+
+| Method | Sonic command | Channel | Returns |
+|---|---|---|---|
+| `query(collection, bucket, terms, *, limit, offset, lang)` | `QUERY` | search | `list[str]` object ids, best first |
+| `suggest(collection, bucket, word, *, limit)` | `SUGGEST` | search | `list[str]` words |
+| `list_words(collection, bucket, *, limit, offset)` | `LIST` | search | `list[str]` words |
+| `push(collection, bucket, object, text, *, lang)` | `PUSH` | ingest | `None` |
+| `pop(collection, bucket, object, text)` | `POP` | ingest | `int` |
+| `count(collection, bucket=None, object=None)` | `COUNT` | ingest | `int` |
+| `flush_collection(collection)` | `FLUSHC` | ingest | `int` |
+| `flush_bucket(collection, bucket)` | `FLUSHB` | ingest | `int` |
+| `flush_object(collection, bucket, object)` | `FLUSHO` | ingest | `int` |
+| `trigger(action=None, data=None)` | `TRIGGER` | control | `str` |
+| `info()` | `INFO` | control | `dict[str, int]` |
+| `ping()` | `PING` | control | `None` |
+| `help(manual=None)` | `HELP` | control | `str` |
+
+`close()` (or leaving the `async with`) sends `QUIT` on every connection. `quote(text)` is public.
+
+`lang` is an ISO 639-3 code (`"eng"`, `"spa"`) or `"none"`. If omitted, Sonic guesses the
+language of the text, and may guess differently at index and query time: pass it on both sides.
+
+Deliberate differences from the protocol:
+
+- `list_words`: Sonic's `LIST` enumerates **words** of the index, not objects.
+- `count` uses `COUNT` rather than `COUNTC/COUNTB/COUNTO` (see [Compatibility](#compatibility-and-limitations)).
+
+## Concurrency and performance
+
+A Sonic channel is a TCP connection in one mode (search, ingest or control).
+
+- **Pool**: up to `pool_size` connections per channel, opened when needed (an idle connection is
+  reused before a new one is opened). A command goes to the least loaded connection.
+- **Pipelining**: each connection writes commands without waiting for replies, and a background
+  reader task hands the replies to futures. `PROTOCOL.md` allows this: immediate replies (`OK`,
+  `RESULT`, `PONG`, `PENDING <id>`, `ERR`) arrive **in order** (a FIFO of futures), while the
+  `EVENT` lines of `QUERY`/`SUGGEST`/`LIST` may arrive **out of order** and are matched by the
+  id of their `PENDING`. `max_in_flight` caps simultaneous commands per connection
+  (`None` = unlimited, `1` = no pipelining).
+- **No retries, no magic reconnection.** If a connection drops, its in-flight commands fail with
+  `SonicConnectionError`; the *next* command opens a fresh connection. What to retry, and when,
+  is your decision (a `PUSH` is idempotent if you `flush_object` first; a `POP` is not).
+- **Per-command timeout** (`timeout`) raises `SonicTimeout`, but the connection stays usable: the
+  late reply is discarded when it arrives and nothing gets out of sync.
+
+### Measured numbers
+
+`benchmarks/bench.py`: 2000 operations per row, Sonic v1.9.1 in Docker Desktop (4 CPUs) on an
+Apple M2 Max, over localhost. **It is a single run and numbers vary from run to run**: trust the
+orders of magnitude, not the decimals.
+
+| Scenario | QUERY ops/s | PUSH ops/s |
+|---|---:|---:|
+| 1 connection, sequential | 2205 | 3061 |
+| pool of 8, concurrent, no pipelining | 10549 | 7559 |
+| 1 connection, pipelining | 13464 | 12795 |
+| pool of 8 + pipelining | 14843 | 11104 |
+
+Pipelining is the big lever: 4x to 6x over sequential. On top of it the pool did not help in
+this run (an earlier run showed +40% for queries and nothing for writes), so with pipelining one
+connection is often enough; the pool mostly matters when `max_in_flight` is capped. Over a real
+network with latency the gap to the sequential case is larger, because a round trip is paid once
+per burst instead of once per command; that was not measured.
+
+## Error handling
+
+Every exception inherits from `SonicError`; messages say what happened and what to do.
+
+| Exception | When |
+|---|---|
+| `SonicConnectionError` | could not connect, or the connection dropped, was closed or received `ENDED` |
+| `SonicTimeout` (subclass of the previous one) | `connect_timeout` or `timeout` expired |
+| `SonicServerError` | Sonic answered `ERR ...` (`.code`, `.line`); also a wrong password (`authentication_failed`) |
+| `SonicProtocolError` | Sonic said something outside `PROTOCOL.md`; the connection is closed |
+| `ValueError` (builtin) | invalid argument, or a command that does not fit in the buffer; nothing is sent |
+
+```python
+from async_sonic import Sonic, SonicServerError, SonicTimeout
+
+async with Sonic(password="SecretPassword") as sonic:
+    try:
+        await sonic.query("videos", "catalog", "cats", limit=0)
+    except SonicServerError as exc:
+        print(exc.code)  # policy_reject
+    except SonicTimeout:
+        ...  # Sonic did not answer in time; the connection is still usable
+```
+
+## Escaping and limits
+
+`quote(text)` wraps text in quotes: `"` becomes `\"`, `\` becomes `\\` (so a trailing backslash
+cannot swallow the closing quote) and newlines (`\n`, `\r`) become a space, because a raw newline
+would cut the command in two; Sonic tokenizes on whitespace, so no word is lost. Unicode goes
+through as UTF-8. `collection`, `bucket`, `object`, `action`... cannot be empty or contain
+whitespace, quotes or control characters (`ValueError`).
+
+**Buffer.** `STARTED ... buffer(N)` (20000 by default) is the limit of a whole command line,
+newline included. `PROTOCOL.md` asks clients to split: `push` does it for you, emitting several
+`PUSH` commands for the same object, always cutting **between words**. `query`, `suggest` and
+`pop` are not split (splitting would change their meaning) and raise `ValueError`, as does a
+single word longer than the buffer.
+
+## Compatibility and limitations
+
+- **Verified**: Sonic **v1.9.1** (official image `valeriansaliou/sonic:v1.9.1`) on Docker
+  Desktop, macOS arm64, Python 3.14. Every command in the table above; text with quotes,
+  backslashes, newlines, accents, CJK and emoji; a 48 KB text (split by the buffer); real `ERR`
+  replies; a wrong password; and 200 concurrent queries over the pool with pipelining.
+- **Deviations from `PROTOCOL.md` found on v1.9.1**:
+  - `COUNTC`, `COUNTB` and `COUNTO` answer `ERR unknown_command`; `COUNT` is used instead, and
+    `count(collection, bucket)` returns the number of **distinct words**, not of objects
+    (measured: 2 objects, 4 words, `count` returned 4).
+  - `SUGGEST` and `LIST` only see new words after `trigger("consolidate")`.
+  - A wrong password is answered with `ENDED authentication_failed` (surfaced as `SonicServerError`).
+  - Replies end in `\r\n`.
+- **Not verified**: other Sonic versions (the `COUNTC/B/O` commands may exist in later ones);
+  `TRIGGER backup` and `restore` (they are sent, never tested against real data); Linux and
+  Windows (CI covers Linux); sustained load or a server with many clients; network latency.
+- No TLS: Sonic Channel is plain TCP. Do not expose it to an untrusted network.
+- Searching without accents (`cancion` for `canción`) depends on the server configuration
+  (`diacritic_folding_enabled`), not on this client; the test `sonic.cfg` does not enable it.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run pytest                      # everything
+uv run pytest tests/test_unit.py   # unit tests only, no docker needed
+uv run python benchmarks/bench.py  # benchmark against a real Sonic
+```
+
+- `tests/test_unit.py` runs against a fake asyncio server (`tests/fake_sonic.py`) that speaks the
+  real protocol: handshake, out-of-order `PENDING`/`EVENT`, `ERR`, abrupt close, `ENDED`, slow
+  replies (timeouts and late replies), buffer splitting, pool and pipelining with latency.
+- `tests/test_integration.py` runs against a **real Sonic**. If `docker` is available, the
+  fixture starts `valeriansaliou/sonic:v1.9.1` with `tests/sonic.cfg` (password `SecretPassword`)
+  on a free port. **Without docker these tests are skipped with an explicit reason**
+  (`SKIPPED: docker is not available...`): always check the `skipped` count, because a green run
+  with every integration test skipped does not prove the real wiring. CI fails if any test is skipped.
+
+## Contributing
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Please follow the
+[Code of Conduct](CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) (c) 2026 Daniel Alfocea.