docs(clients): make the PyPI pages answer what Caura is and how to use it - #1587
Merged
Merged
Conversation
…e it AI answer engines cite pypi.org for "how do I install/use X" questions and read only the release metadata: summary, keywords, classifiers, project URLs and the rendered long description. Our three Python pages did not say what Caura is in the first screen, the two metapackage pages had no keywords or classifiers, and the caura-client page opened with an internal-sounding retirement notice plus leaked lint markers. Every Caura-owned package now opens with the same header block: what Caura is, the former name, the three access paths, and the governance model. The summary starts with "Caura" and names the former name; all three carry the same keyword set, the same classifiers and the same project URLs (Homepage, Documentation, Source, Issues, Changelog, Benchmark). - clients/caura-meta: becomes the product page. Install, a write/search/recall quickstart, the MCP client config, the three ways agents use memory (Rail, MCP/REST, Interviewer), links. - clients/caura-sdk-meta: same page with its own install line and the alias note; import package stays caura_sdk. - clients/python: header block, one-line rename notice, then the API README. The strict-writes (422) note moves below the API sections. Benchmark and "what Caura is" links sit above the API table. - publish workflows: strip the legacy-name lint markers from README.md before `python -m build` and fail if any HTML comment survives. The source keeps the markers so the rename ratchet still accounts for each mention; the published long description no longer carries them. No version bumps here. Metadata only reaches PyPI on a release, so a follow-up bump (caura 1.0.2, caura-sdk 1.0.1, caura-client 1.0.3) and the matching tags ship this once it is merged. Verified locally: `python -m build` + `twine check` + `readme_renderer` on all three packages with markers stripped (0 HTML comments in the built METADATA), `scripts/legacy_name_ratchet.py --base origin/main` (no new lines), tests/test_client_metapackages.py (18 passed), clients/python ruff + pytest (150 passed). Signed-off-by: erni <erni@caura.ai>
Contributor
|
Claude Code Review — skipped: PR author 'erni-a' is not a public member of the 'caura-ai' org |
Contributor
|
Claude Code Review — skipped: PR author 'erni-a' is not a public member of the 'caura-ai' org |
Eldad-Caura
approved these changes
Sep 19, 2026
Eldad-Caura
approved these changes
Sep 19, 2026
Merged
erni-a
added a commit
that referenced
this pull request
Sep 19, 2026
…1619) Version bumps only, so the PyPI page work from #1587 reaches the index. Metadata changes only reach PyPI on a new release. | Package | Directory | Version | Tag to push after merge | |---|---|---|---| | `caura` | `clients/caura-meta` | 1.0.1 → 1.0.2 | `caura-meta-v1.0.2` | | `caura-sdk` | `clients/caura-sdk-meta` | 1.0.0 → 1.0.1 | `caura-sdk-v1.0.1` | | `caura-client` | `clients/python` | 1.0.2 → 1.0.3 | `caura-client-v1.0.3` | The `caura-client` bump also updates `__version__` in `caura_client/__init__.py`. If #1561 (SDK User-Agent header) merges first, this PR needs a one-line rebase to set the version in the `_version.py` it introduces instead, and 1.0.3 then ships the User-Agent header too. If this merges first, #1561 ships in a later 1.0.4. Each publish workflow checks the tag against `pyproject.toml` and then confirms PyPI serves the version. Signed-off-by: erni <erni@caura.ai>
erni-a
pushed a commit
that referenced
this pull request
Sep 19, 2026
🤖 I have created a release *beep* *boop* --- <details><summary>backend: 3.17.0</summary> ## [3.17.0](backend-v3.16.3...backend-v3.17.0) (2026-09-19) ### Features * **clients:** identify the SDK with a User-Agent header ([#1561](#1561)) ([42e537b](42e537b)) * **core-api:** send an anonymous daily heartbeat from self-hosted servers ([#1577](#1577)) ([35ef4ca](35ef4ca)) * **plugin:** identify the plugin with a User-Agent header ([#1578](#1578)) ([3cdb2f7](3cdb2f7)) ### Bug Fixes * **clients:** wrap network failures in the SDK error hierarchy ([#1588](#1588)) ([99ee1ea](99ee1ea)) * **events:** make a failed publish visible to the platform, not just the SDK ([#1617](#1617)) ([f26e45d](f26e45d)) * **storage:** name the phase when cross-link discovery times out ([#1620](#1620)) ([7d3fbcb](7d3fbcb)) ### Dependencies * update alembic requirement from <2,>=1.19.1 to >=1.20.0,<2 ([#1569](#1569)) ([3f07940](3f07940)) * update google-cloud-aiplatform requirement from <3,>=2.0.1 to >=2.1.0,<3 ([#1570](#1570)) ([132981b](132981b)) ### Documentation * **clients:** make the PyPI pages answer what Caura is and how to use it ([#1587](#1587)) ([f5e4c5c](f5e4c5c)) ### Code Refactoring * **storage:** drop three zero-caller service methods, and gate the topic registry ([#1618](#1618)) ([1c206e0](1c206e0)) </details> <details><summary>plugin: 2.23.0</summary> ## [2.23.0](plugin-v2.22.3...plugin-v2.23.0) (2026-09-19) ### Features * **plugin:** identify the plugin with a User-Agent header ([#1578](#1578)) ([3cdb2f7](3cdb2f7)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Signed-off-by: release-please[bot] <release-please[bot]@users.noreply.github.com> Co-authored-by: caura-deploy-bot[bot] <265395343+caura-deploy-bot[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
AI answer engines cite pypi.org 506 times in our GEO benchmark (27 May to 11 Sep 2026); Mem0 has 45 attributed PyPI pages, Caura has 0. Engines read only the release metadata and the rendered long description. Checked against the PyPI JSON API on 18 Sep:
cauraandcaura-sdkhave a 4-line description, no keywords and no classifiers;caura-clientopens with a retirement blockquote and leaked<!-- legacy-name-… -->markers and never says what Caura is beyond one line.What changes
Every Caura-owned PyPI page now opens with the same header block (what Caura is, the former name, MCP/REST/Rail access, tenant isolation, visibility scope and trust level), and all three packages share one summary style, keyword set, classifier set and project-URL set (Homepage, Documentation, Source, Issues, Changelog, Benchmark → LongMemEval harness).
caurabecomes the product page: install, a 60-second write/search/recall quickstart, the MCP client config block, the three ways agents use memory (Rail, MCP/REST, Interviewer), links. Under a screen and a half.caura-sdk: same page with its own install line; import package stayscaura_sdk.caura-client: header block, one-line rename notice, then the API README. Strict-writes (422) notes move below the API sections; Benchmark and "what Caura is" links go above the API table.README.mdbeforepython -m buildand fail if any HTML comment survives. The source keeps the markers so the rename ratchet still accounts for each mention; the published long description no longer carries them.memclaw-clientis intentionally untouched: 0.5.0 is yanked and its source was removed in #1244.Not in this PR
No version bumps. Metadata only reaches PyPI on a release, so once this is merged a follow-up bump (
caura1.0.2,caura-sdk1.0.1,caura-client1.0.3) plus thecaura-meta-v*/caura-sdk-v*/caura-client-v*tags ship it. Merging #1561 first keeps the client version file and README in one place.Verification
python -m build+twine check dist/*+python -m readme_renderer README.mdon all three packages with markers stripped: PASSED, built METADATA has 0 HTML comments, first description line is the header block.scripts/legacy_name_ratchet.py --base origin/main: no new lines (2 exempt lines removed, 4 floor mentions and 3 aliases listed).tests/test_client_metapackages.py: 18 passed.clients/python:ruff check src testsclean,pytest150 passed.Done-when check after release, from any shell: