graphos-client 0.14.12__tar.gz

graphos_client-0.14.12/.gitignore

@@ -0,0 +1,46 @@
+# Python build / caches
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+build/
+dist/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+coverage-*.xml
+
+# Local env / secrets — everything in deploy/secrets except *.example and .gitkeep
+services/graphos/deploy/secrets/*
+!services/graphos/deploy/secrets/*.example
+!services/graphos/deploy/secrets/.gitkeep
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Local override files
+.env
+.env.local
+docker-compose.override.yml
+
+# Local design notes, never committed
+docs/design/
+
+# Crash dumps from Windows / Cygwin tools
+*.stackdump
+

graphos_client-0.14.12/DEVELOPMENT.md

@@ -0,0 +1,92 @@
+# Developing the Python client
+
+How to work on `graphos-client`, the async Python client in
+`clients/python/`. The rules for the whole repository (docs, test stacks,
+git, privacy) are in [`development.md`](../../docs/guide/development.md); they apply here too.
+Its users' guide is the [client README](README.md).
+
+## 1. Where to look
+
+Paths are under `clients/python/`.
+
+| Question | Look in |
+|---|---|
+| A method, its URL, retries and errors | `src/graphos_client/_client.py` (`GraphosClient`) |
+| Request and response models | `src/graphos_client/_models.py` |
+| `ensure_tenant`'s drift lines | `src/graphos_client/_drift.py` |
+| Sign-in and token renewal | `src/graphos_client/_auth.py` (`PasswordAuth`, `BearerAuth`) |
+| One client per tenant, re-registration | `src/graphos_client/_pool.py` (`GraphosPool`, `TenantSchema`) |
+| Errors raised | `src/graphos_client/_errors.py` |
+| What the package exports | `src/graphos_client/__init__.py` |
+| Runnable examples | `examples/0*_*.py` |
+| The service side of a model | `services/graphos/src/graphos/contracts/` |
+
+## 2. Setup, test, lint
+
+In a venv at `.venv` in the checkout
+([development.md, Python environment](../../docs/guide/development.md#python-environment)):
+
+```bash
+pip install -e "clients/python[dev]"
+ruff check clients/python/src clients/python/tests clients/python/examples
+pytest clients/python/tests
+```
+
+The tests need no server: they use httpx's `MockTransport` and assert the
+request the client builds and the model it parses. To run an example
+against a running stack, set `GRAPHOS_URL` (default
+`http://127.0.0.1:8080`), `GRAPHOS_USER` and `GRAPHOS_PASSWORD`.
+
+## 3. Rules
+
+- **Published on its own.** The client depends on `httpx` and `pydantic`
+  only, never on the `graphos` service package. Keep it that way.
+- **Models mirror the service 1:1.** `_models.py` is a copy of
+  `graphos.contracts`; when a contract changes, the model changes in the
+  same commit. A field the service added recently gets a default (`None`
+  or empty), so the client still reads older servers.
+- **Async only** (`asyncio` + `httpx`), one pooled `httpx.AsyncClient` per
+  client, one tenant per client.
+- **Retries only what is safe to repeat.** Network errors and 5xx are
+  retried with backoff. A call that is long or must not run twice (a
+  recompute, an import, a Cypher query, a job submission, a delete with
+  data) passes `idempotent=False`. A `504`, a `507` (the database out of disk
+  space) and 4xx errors are never retried.
+- **Errors:** a non-2xx response raises `GraphosError`; a 503 raises
+  `GraphosNotReady`.
+- **Every public name is exported** from `__init__.py`. The package ships
+  `py.typed`; every function is annotated.
+
+## 4. Code conventions
+
+- **Ruff** with the config in `clients/python/pyproject.toml`: line length
+  100, target `py311`, rules `E F I B UP SIM RET PL` (`PLR0913` ignored:
+  methods mirror the API's parameters). Same ruff range as the service
+  (`>=0.16,<0.17`); lint with the newest 0.16.x, as CI does.
+- Module docstrings, typing and comments follow the service's conventions
+  ([services/graphos/DEVELOPMENT.md §4](../../services/graphos/DEVELOPMENT.md#4-code-conventions)).
+- Tests live in `clients/python/tests/test_<area>.py`; names say what is
+  checked. A new method gets a test of its request and of its parsed
+  response.
+- Examples read their settings from the environment and use the neutral
+  example tenants (`acme`, `library`, `team_*`, `demo`). Lint covers them.
+
+## 5. When the client changes
+
+Besides the shared list in [development.md §3](../../docs/guide/development.md#3-docs-discipline):
+
+- the README's "What the client covers" table lists every method; "Not
+  wrapped" lists what is left to plain HTTP;
+- the README's examples table lists every script in `examples/`;
+- a change in retries or errors updates the README's "Behaviour" section;
+- a change to what the client promises (async only, its dependencies, what
+  it retries) gets an [ADR](../../docs/guide/adrs/README.md) first.
+
+## 6. Release
+
+The client shares its version with the service and the UI
+(`node tools/release/version.mjs <version>`). It is published to PyPI by
+hand: the `graphos-client-release` workflow, run from a version tag
+(`.github/workflows/client-release.yml`). A version tag does not publish it.
+Never tag or publish without the owner's approval
+([development.md §6](../../docs/guide/development.md#6-git)).

graphos_client-0.14.12/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 [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

graphos_client-0.14.12/NOTICE

@@ -0,0 +1,12 @@
+graphos
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+graphos runs on Apache AGE (https://age.apache.org/), a project of the
+Apache Software Foundation, licensed under the Apache License, Version 2.0.
+Apache AGE is used as an unmodified upstream container image and is not
+redistributed in this repository. "Apache", "Apache AGE" and the Apache
+feather logo are trademarks of The Apache Software Foundation.
+
+See THIRD_PARTY_NOTICES.md for the licences of Apache AGE, PostgreSQL and the
+Python dependencies.

graphos_client-0.14.12/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: graphos-client
+Version: 0.14.12
+Summary: Async HTTP client for the graphos graph service.
+Project-URL: Homepage, https://github.com/pomentum/graphos
+Project-URL: Documentation, https://github.com/pomentum/graphos/tree/main/clients/python
+Project-URL: Source, https://github.com/pomentum/graphos
+Project-URL: Issues, https://github.com/pomentum/graphos/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: apache-age,asyncio,client,cypher,graph,graph-database,postgresql
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1.0,>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov<7.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.3; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# graphos-client
+
+Async Python client for [graphos](https://github.com/pomentum/graphos), a multi-tenant graph service built on PostgreSQL and Apache AGE. Typed request and response models, pooled connections, and a tenant pool for services that write to many tenants.
+
+```bash
+pip install graphos-client             # from PyPI
+pip install -e clients/python          # from a checkout of the repository
+```
+
+Requires Python 3.11+. The client is async-only (`asyncio` + `httpx`).
+
+## Quickstart
+
+```python
+import asyncio
+import os
+
+from graphos_client import EdgeUpsert, GraphosClient, NodeUpsert, PasswordAuth
+
+
+async def main() -> None:
+    async with GraphosClient(
+        base_url="http://127.0.0.1:8080",
+        # A service account allowed to create the tenant (create_tenants), or an admin.
+        # Without auth=, the client signs in as GRAPHOS_USER / GRAPHOS_PASSWORD.
+        auth=PasswordAuth("loader", os.environ["GRAPHOS_PASSWORD"]),
+        tenant="acme",
+    ) as g:
+        await g.register_tenant(vertex_labels=["User", "Document"], edge_labels=["AUTHORED"])
+
+        await g.upsert_nodes([
+            NodeUpsert(id="u1", label="User", properties={"name": "ada"}),
+            NodeUpsert(id="d1", label="Document", properties={"name": "graphs-101"}),
+        ])
+        await g.upsert_edges([
+            EdgeUpsert(src_id="u1", src_label="User", dst_id="d1",
+                       dst_label="Document", type="AUTHORED"),
+        ])
+
+        hits = await g.search(q="ada")                # hit.properties["id"] is your id
+        around = await g.neighbors(node_id="u1")
+        reach = await g.expand(node_id="u1", max_hops=2)
+        print(len(hits.nodes), len(around.neighbors), len(reach.paths))
+
+
+asyncio.run(main())
+```
+
+## Many tenants: `GraphosPool`
+
+A service that writes to one tenant per customer, project or team can let the pool manage the clients. Each tenant gets its own client, is registered with the shared schema on first use, and is re-registered (then retried once) if the server no longer knows a label. A registration is one plain request by default; `GraphosPool(..., on_drift="warn")` (or `"fail"`) registers through `ensure_tenant` with that mode instead (below): a dry run first, its drift logged.
+
+```python
+from graphos_client import GraphosPool, PasswordAuth, TenantSchema
+
+schema = TenantSchema(
+    vertex_labels=["User", "Document"],
+    edge_labels=["AUTHORED"],
+    property_indexes=[{"label": "Document", "properties": ["kind"]}],   # serves `where kind = ...`
+)
+
+async with GraphosPool(base_url=URL, auth=PasswordAuth("loader", SECRET), schema=schema) as pool:
+    await pool.call("team_red", lambda g: g.upsert_nodes(nodes))    # registers, writes
+    cli = await pool.client("team_red")                              # the same client
+```
+
+## A program's schema: `ensure_tenant`
+
+A program that declares its schema in code and registers it on every start can learn what people
+changed in the tenant meanwhile (in the web UI, say) instead of undoing it unseen:
+
+```python
+await cli.ensure_tenant(vertex_labels=["User", "Document"], edge_labels=["AUTHORED"],
+                        on_drift="warn")      # or "fail", or "ignore" (no dry run)
+```
+
+It runs the registration as a dry run first and logs the dry run's `drift` on the logger
+`graphos_client.drift`, one line per item. At INFO: what the tenant has that the call does not
+declare (a merge keeps it; most programs declare less than the tenant has). At WARNING: what a
+`force_shrink` would remove, entries the call would replace with a different value, settings it
+would change (`strict_endpoints`, the property mode, the community algorithm), and labels, edge
+types or label pairs dropped earlier that the call creates again. Then it registers, with
+`If-Match` set to the dry run's `ETag`, so it applies exactly what was previewed. If the schema
+changed in between (another replica of the program starting at the same time), it runs the dry
+run once more on the new version, logs it, and registers with that; a second change raises
+`GraphosError` 412 and nothing is registered, as when someone unregistered the tenant in between
+(registering would restore it, undoing that). A tenant the dry run found not registered is
+registered with `If-None-Match: *` (unless it said the call restores an unregistered tenant), so
+one someone else created meanwhile is not registered unchecked. An `if_match=` you pass pins the version: the second dry run is then refused with 412.
+Each drift line is logged once, also across the second dry run. With `on_drift="fail"` it raises `SchemaDriftError` (its `drift` is the report) and
+registers nothing when the call would remove, replace or change something, or bring a removed
+item back; what is only not declared never fails it.
+
+A tenant can name one **schema manager**: `schema_manager="user:loader"` (an existing graphos user
+or service account), `"oidc-sub:<sub>"` (a caller signed in through the identity provider) or
+`"self"` (the caller, whatever it signs in with) on `register_tenant`, `ensure_tenant` or
+`import_schema`; `manage_schema=True` is `"self"`; `None` releases it; set by an owner, refused
+(422) by a server with authentication disabled. On a managed tenant only the manager changes more
+than the styles (`display`): anyone else's such write raises `GraphosError` 409 with
+`code == "schema_managed"` and `schema_manager` naming the manager. `get_tenant()` and `schema()`
+show it (`schema_manager` and `schema_manager_since`, `None` when there is none).
+
+After a registration that names a manager, the client checks the answer's `schema_manager`: a
+server older than the schema manager ignores the field, and the client then raises
+`SchemaManagerNotApplied` (a `GraphosError` with status 0: the rest of the registration was
+applied, the manager was not). An import of more than 5,000 label pairs sends the manager with
+its last call, so the calls before it are not refused.
+
+How the styles sent merge is `display_merge=`: `"entries"` (an entry sent replaces the stored
+one, `None` removes it) or `"missing_only"` (only the styles the tenant lacks are added; a
+`force_shrink` keeps the stored styles of the labels and edge types it keeps and drops the
+others). Left out, the manager's registrations get `"missing_only"`, so people's
+styles stay, and anyone else's `"entries"`; a manager that wants to correct a style it shipped
+sends `"entries"`.
+
+## Copying a tenant
+
+```python
+await cli.export_dataset("acme.ndjson.gz")                   # every node and edge, and the schema
+await cli.import_dataset("acme.ndjson.gz", name="acme_copy",  # a new tenant, restored exactly:
+                         schema="apply", mode="empty")        # schema from the file, then the data
+```
+
+Both stream: the file is never held in memory. The result says whether the file was complete.
+
+## Copying a schema
+
+```python
+doc = await cli.export_schema()                              # the whole schema, a dict
+preview = await cli.import_schema(doc, name="acme_copy", dry_run=True)
+print(preview["changes"], preview["warnings"])               # what it would change, and cost
+await cli.import_schema(doc, name="acme_copy")               # merge into (or create) acme_copy
+await cli.import_schema(doc, replace=True)                   # replace this tenant's schema
+```
+
+The document is what `GET /v1/tenants/{name}/spec` answers: a registration body, so it can be kept
+in git and reviewed as a diff. More than 5,000 declared label pairs are sent over several calls.
+
+## Examples
+
+**Signing in.** `auth=PasswordAuth(user, secret)` (or `GRAPHOS_USER` / `GRAPHOS_PASSWORD`) signs in
+and renews the 15-minute token by itself. A program that holds credentials at graphos's identity
+provider can use `auth=BearerAuth(source)` instead: `source` is an async callable answering
+`(access token, seconds valid)`, called again before expiry and once on a `401`.
+
+Runnable scripts in [`examples/`](https://github.com/pomentum/graphos/tree/main/clients/python/examples). Each reads `GRAPHOS_URL` (default `http://127.0.0.1:8080`) and signs in as `GRAPHOS_USER` / `GRAPHOS_PASSWORD`: an admin, or a service account with `create_tenants` on the example tenants (`acme`, `library`, `team_red`, `team_green`, `team_blue`, and `demo` or `GRAPHOS_DEMO_TENANT`), which makes it their owner. `07_background_jobs.py` also vacuums, which needs an admin.
+
+| Script | Shows |
+|---|---|
+| [`01_quickstart.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/01_quickstart.py) | register a tenant, write nodes and edges, search / neighbours / expand |
+| [`02_bulk_load.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/02_bulk_load.py) | batched NDJSON bulk writes and a one-request snapshot import |
+| [`03_explore.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/03_explore.py) | paginated scans, scoped and induced subgraphs, aggregates, top-K, node properties, cache |
+| [`04_communities.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/04_communities.py) | communities (Louvain, or Leiden with `algorithm="leiden"`): compute, summarise, look up |
+| [`05_tenant_pool.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/05_tenant_pool.py) | `GraphosPool` serving several tenants with one schema |
+| [`06_rule_based_edges.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/06_rule_based_edges.py) | declaring a property-match rule and letting the server write the edges |
+| [`07_background_jobs.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/07_background_jobs.py) | long operations as background jobs: submit, wait, the one-recompute rule, cancel |
+| [`08_demo_ecosystem.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/08_demo_ecosystem.py) | the demo tenant (an invented software ecosystem, about 450 nodes) and every graph algorithm on it: metrics, the top nodes by PageRank and betweenness, communities |
+| [`09_better_answers.py`](https://github.com/pomentum/graphos/blob/main/clients/python/examples/09_better_answers.py) | better answers from the algorithms on the demo tenant: search ranked by PageRank, a walk scoped to a community, the best hit per community, the bridges |
+
+## What the client covers
+
+| Area | Methods |
+|---|---|
+| Tenants | `register_tenant` (with `edge_endpoints`, `strict_endpoints`, `display`, `property_schema`, `deprecated`, `schema_manager` / `manage_schema`, `display_merge`, `force_shrink`, `dry_run`; the answer's `etag`), `ensure_tenant` (a dry run's drift logged, or `SchemaDriftError`, then the registration with its `ETag` as `If-Match`), `export_schema`, `import_schema`, `remove_edge_endpoint`, `rename_label`, `rename_edge_type`, `rename_property` (a job: `wait_for_job(result.job_id)`), `drop_label` (a deprecated, empty one), `list_tenants`, `get_tenant`, `unregister_tenant` (`drop_data=True` deletes it with its data), `restore_tenant`, `list_unregistered_tenants`, `me`, `schema`, `schema_summary` (the schema as a model needs it, with the values) |
+| Cypher console (on unless the server turns it off) | `cypher` (read-only, `$name` parameters; write clauses and functions that are not Cypher's are refused with 400), `saved_queries`, `save_query`, `run_saved_query`, `saved_query` (one by name), `delete_saved_query` |
+| Dataset | `export_dataset` (streamed to a file, gzip by suffix), `import_dataset` (streamed from one; `mode="empty"` to restore, `schema="apply"` to register the file's schema first), `read_dataset_header` |
+| Writes | `upsert_nodes`, `upsert_edges`, `bulk_upsert_nodes`, `bulk_upsert_edges`, `import_csv_nodes`, `import_csv_edges`, `snapshot_import`, `upsert_node_properties`, `patch_node`, `patch_edge`, `delete_node`, `delete_nodes` (a batch, by `NodeRef`), `delete_edge`, `delete_by_property`, `reconcile_node_edges` / `reconcile_type_edges` (a scope made exactly a given set), `resolve_edges` (`mode="reconcile"`) |
+| Reads | `search`, `get_node`, `get_edge`, `check_edges` (many edges at once, by `EdgeCheckItem`), `find_paths`, `neighbors`, `expand`, `induced_edges`, `scoped_subgraph`, `sample_subgraph`, `scan_nodes` / `scan_nodes_iter`, `scan_edges` / `scan_edges_iter`, `export_graph` |
+| Aggregates | `graph_map`, `map_hubs`, `label_top_by_edge`, `aggregate_nodes` (`missing=True` counts nodes without the property under `""`; `total` and `distinct` count nodes and values before `limit`, `None` from older servers), `aggregate_edges`, `tenant_stats` (`analyses`: when metrics and communities were computed, `stale`) |
+| Communities | `recompute_communities` (`algorithm="louvain"` or `"leiden"`, the tenant's when omitted; `from_scratch=True` makes Leiden ignore the stored groups), `community_map`, `list_communities`, `community_summary`, `community_ids` |
+| Graph metrics | `compute_metrics` (degree, PageRank, components, betweenness, stored as `graphos_*` node properties) |
+| Property definitions | `property_definitions` (every label's and type's definitions and mode), `check_properties` (the stored rows against them, `maintain`; writes nothing) |
+| Rule-based edges | `resolve_edges`, `catalogue` |
+| Cache | `cache_put`, `cache_get`, `cache_delete` |
+| Change feed | `changes`, `changes_head`, `iter_changes`, `stream_changes` (reconnects with `Last-Event-ID`), `changes_history` (newest first, for showing the past) |
+| Operations | `healthz`, `readyz`, `info` (no token; versions and features), and for admins `db_stats`, `slow_queries`, `vacuum` |
+| Background jobs | `submit_recompute_communities`, `submit_compute_metrics`, `submit_resolve_edges`, `submit_check_properties`, `submit_vacuum` (each returns a `Job`), `get_job`, `list_jobs`, `cancel_job`, `wait_for_job` |
+
+Not wrapped (use HTTP, see the [usage guide](https://github.com/pomentum/graphos/blob/main/docs/guide/usage.md)): users, grants and sign-in (`/v1/users`, `/v1/grants`, `/v1/auth/*`, `/v1/me/password`), `PATCH /v1/me/preferences`, and the MCP endpoint `/mcp`, which is for agents (see the [agents guide](https://github.com/pomentum/graphos/blob/main/docs/guide/agents.md)).
+
+## Behaviour
+
+- **Errors.** Non-2xx responses raise `GraphosError` (`status_code`, `detail`, and `body`, `code` and `schema_manager` from a JSON body: `code == "schema_managed"` is a write refused on a tenant whose schema someone else manages); `ensure_tenant(on_drift="fail")` raises `SchemaDriftError` (`drift`, status 0) before registering; a registration naming a schema manager the server did not apply raises `SchemaManagerNotApplied` (status 0, after the registration); a 503 raises `GraphosNotReady` (graphos starting or without its database, or the database out of memory or connections). A statement timeout on the server is a `504`, the database out of disk space a `507`, both with an `application/problem+json` body and not retried.
+- **Retries.** Network errors and 5xx responses are retried with exponential backoff (`retries`, `retry_backoff_s`), except `504` timeouts, `507` (the database out of disk space), read and write timeouts, and calls that are long or should not run twice (community recompute, graph metrics, rule-based edge resolution, snapshot and dataset import, vacuum, Cypher queries, restoring or deleting a tenant with its data), job submissions and cancels, which are never re-run automatically. 4xx errors are raised at once.
+- **One tenant per client.** The tenant is part of every data-plane URL; what a token may touch is enforced by the server.
+- **Connections.** One pooled `httpx.AsyncClient` per client; use `async with` or call `close()`. Pass `transport=` to supply your own `httpx` transport (tests, proxies).
+
+## Development
+
+Working on the client: see [DEVELOPMENT.md](https://github.com/pomentum/graphos/blob/main/clients/python/DEVELOPMENT.md) in the repository.
+
+## Licence
+
+Apache-2.0. See [LICENSE](https://github.com/pomentum/graphos/blob/main/clients/python/LICENSE) and [NOTICE](https://github.com/pomentum/graphos/blob/main/clients/python/NOTICE).