guwenzi-tools 0.2.0__tar.gz

guwenzi_tools-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guwenzi contributors
+
+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.

guwenzi_tools-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE PUBLISHING.md
+recursive-include src/gwz_client/data *.json *.md
+recursive-include tests *.py
+recursive-include scripts *.py

guwenzi_tools-0.2.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: guwenzi-tools
+Version: 0.2.0
+Summary: CLI and Python client for evidence-preserving historical-document and glyph tools
+Author: Guwenzi contributors
+License-Expression: MIT
+Keywords: ocr,paleography,glyph,cli,multimodal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: filelock<4,>=3.15
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Provides-Extra: fonts
+Requires-Dist: fonttools<5,>=4.60; extra == "fonts"
+Requires-Dist: skia-pathops<1,>=0.8; extra == "fonts"
+Dynamic: license-file
+
+# guwenzi-tools
+
+A lightweight CLI and Python client for a remote **Guwenzi** historical-document and glyph service. Supports external multimodal agents that can run commands and view images. Python 3.10+; Linux, macOS and Windows. Client license: MIT.
+
+安装包只包含客户端、工具schema和agent说明。模型、字库、文献和访问凭据留在各自的部署环境里。服务端需要实现 `guwenzi.tools.v1`；安装客户端不会自动获得公共推理服务，也不会在本机下载或加载Qwen、DINO、YOLO、torch或MLX。
+
+## Install and connect
+
+Once the project is published to PyPI:
+
+```sh
+python -m pip install guwenzi-tools
+```
+
+Before publication, install the release wheel or this source directory:
+
+```sh
+python -m pip install /path/to/guwenzi_tools-0.2.0-py3-none-any.whl
+# or, from this directory
+python -m pip install .
+```
+
+Configure the endpoint once. Enter the service token at the hidden prompt:
+
+```sh
+guwenzi-tools configure --endpoint https://your-service.example/api/predict/guwenzi_tools
+guwenzi-tools doctor --quick
+guwenzi-tools doctor
+```
+
+EAS uses raw Authorization by default. For a standalone server with Bearer authentication add `--auth bearer`. HTTPS is the default requirement; explicitly use `--allow-http` for a service that only has HTTP. Loopback HTTP works for local testing. The complete service URL includes its application prefix; do not append `/health` or `/v1` when configuring it.
+
+For agents and CI, configure a reference to an environment variable instead of storing its value:
+
+```sh
+guwenzi-tools configure --endpoint https://your-service.example/api/predict/guwenzi_tools --token-env GWZ_REMOTE_TOKEN
+```
+
+Provide that environment variable through your agent's secret settings. `--token-stdin` is another option. `config show` redacts saved tokens. Multiple profiles are supported with `--profile NAME`; `config use NAME` changes the default, and the first configured profile is selected automatically. The config location can be changed with `--config FILE` or `GWZ_CLIENT_CONFIG`. POSIX credential files are written with mode0600.
+
+The existing `GWZ_REMOTE_URL`, `GWZ_REMOTE_TOKEN`, `GWZ_REMOTE_AUTH` environment variables and `--remote URL` alias remain supported. Explicit endpoint overrides do not inherit a different server's stored token.
+
+## Document workflow
+
+Start with one page, inspect the evidence, and continue according to the reading task:
+
+```sh
+guwenzi-tools document open paper.pdf
+guwenzi-tools page prepare DOCUMENT_ID 1 --output work/page-1
+```
+
+For a terminal tool with a short waiting limit, submit and collect separately:
+
+```sh
+guwenzi-tools page prepare DOCUMENT_ID 1 --output work/page-1 --detach
+guwenzi-tools status JOB_ID --wait --output work/page-1
+```
+
+The second command downloads the completed page's evidence and prints a compact summary. It can be repeated after an interruption. Crop, line splitting and glyph search/resolve also support `--detach`.
+
+Or prepare selected pages in one resumable operation:
+
+```sh
+guwenzi-tools document prepare paper.pdf --pages 1-3 --output work/paper
+guwenzi-tools document prepare paper.pdf --pages 1-3 --output work/paper --resume
+```
+
+`document prepare` defaults to all pages if `--pages` is omitted. Mode/DPI, endpoint, page range and source hash must agree when resuming. Preparation is sequential, matching the small server's one-heavy-task limit. A complete evidence preparation is not a completed OCR transcription.
+
+Output folders contain:
+
+| File | Purpose |
+|---|---|
+| `brief.json` | Compact navigation and original image paths |
+| `result.json` | Full server response, with source text and unresolved status |
+| `materials.json` | Original/viewing-derivative files and SHA256 verification |
+| `index.html` | Local visual review page; image links open original files |
+| `transcriptions.draft.json` | Per-block requests to fill after reading the images |
+| `assets/` | Exact original bytes and separately labelled enlarged views |
+
+Native PDFs retain source-layer text and original glyph evidence. Scans use remote YOLO layout and projection lines/slots, then the calling multimodal model supplies text. Word/PPT are converted by the server. The CLI itself does not infer the reading of an image.
+
+## Uncertain glyphs
+
+```sh
+guwenzi-tools line split LINE_ASSET_ID --output work/line
+guwenzi-tools crop LINE_ASSET_ID --box 10 0 60 80 --output work/crop
+guwenzi-tools glyph search CROP_ASSET_ID --output work/search
+```
+
+View the query and candidate originals returned by the search. Select a matching candidate using its request-scoped ID:
+
+```sh
+guwenzi-tools glyph select SEARCH_ID c3 --output work/binding.json
+```
+
+The choice of `c3` is an example, not a default decision. If no candidate matches, expand once or register the unresolved original:
+
+```sh
+guwenzi-tools glyph search CROP_ASSET_ID --expand-search SEARCH_ID --output work/expanded
+guwenzi-tools glyph register CROP_ASSET_ID --output work/unresolved.json
+guwenzi-tools glyph resolve PERMANENT_CODE --output work/identity
+```
+
+Projection proposes boundaries. Crop boxes always use original-image pixels. `gwz:` codes identify a specific original/source asset; similarity, selection and a valid code do not prove a Unicode reading. Source identities and original forms are preserved.
+
+## Transcribe and export
+
+Fill `transcriptions.draft.json` with text and structured glyph references, then:
+
+```sh
+guwenzi-tools transcribe work/page-1/transcriptions.draft.json
+guwenzi-tools document result DOCUMENT_ID --offset 0 --limit 20
+guwenzi-tools document export DOCUMENT_ID --output work/export
+```
+
+Use `--skip-empty` only when intentionally submitting a partially filled draft. Every `part` has exactly one string field: `text`, `binding_id`, `glyph_code`, or `asset_id`. Bindings must belong to the selected block or its recorded crops/slots; the server enforces the association. The exported JSON keeps original source text, transcriptions, figures/tables and verification status. JSON preserves codepoints exactly; it performs no Unicode normalization or traditional/simplified conversion. Markdown is a readable derivative and references the preserved image files.
+
+Export saves assets referenced by the v1 API and the archived original document. It does not claim to enumerate every intermediate file kept inside the server. For large exports, consider `--no-images` first or a page-specific evidence packet.
+
+## Agents and low-level access
+
+```sh
+guwenzi-tools agent guide --plain
+guwenzi-tools agent install-skill --directory /your-agent/skills/guwenzi-remote
+guwenzi-tools tools
+guwenzi-tools tools --server
+guwenzi-tools call glyph_search --json @request.json
+guwenzi-tools call page_prepare --json @request.json --detach
+guwenzi-tools status JOB_ID --wait
+guwenzi-tools asset ASSET_ID --output original.png
+```
+
+Convenience commands output one JSON envelope on stdout and progress on stderr. Full page/search responses are stored locally while summaries point the agent to image files; image base64 is not printed. `call` and `status` retain the v1 job envelope. Tasks already submitted continue on the server if the CLI stops waiting. Receipts retain job IDs without credentials. An uncertain POST outcome is not automatically repeated; GET failures and explicit429 rejections have bounded retries.
+
+Any multimodal agent with shell access and an image-viewing function can use the same CLI. Hosted chat interfaces that cannot run commands need an application-side tool adapter; installing a Python package alone does not give a hosted model filesystem or shell access. No MCP connection or specific model provider is required.
+
+## Python SDK
+
+```python
+from gwz_client import Client
+from gwz_client.workflow import Preparation
+
+with Client.from_config() as client:
+    print(client.health())
+    result = Preparation(client, "work/paper").run("paper.pdf", page_spec="1")
+    print(result["document_id"])
+    job = client.call("document_result", {"document_id": result["document_id"], "limit": 20})
+    print(job["result"])
+```
+
+Credentials can also be supplied to `Client(endpoint, token, auth="raw")` by your application's secret store. The SDK and CLI share the same transport and integrity checks.
+
+## Distribution and service access
+
+PyPI distributes the client, not an inference entitlement. Each deployment owner provides an endpoint and access credentials separately. The current v1 service has one EAS access domain and a shared document store; profiles are client connection settings, not server-side tenant isolation. A public multi-user SaaS would need separate identity, quotas and data isolation on the service side.
+
+This repository can build a wheel and source distribution with `python -m build`, and validate them with `python -m twine check dist/*`. Publication is a separate owner action. See `PUBLISHING.md` in the source distribution for TestPyPI/PyPI release steps. This MIT license covers the client only; server dependencies, model weights and external glyph datasets have their own licenses.
+
+## Inline glyphs and real fonts
+
+Page preparation and document export write `reading.html`: permanent gwz markers display as inline glyph images, with links to the enlarged originals. Long IDs remain in the evidence JSON. This view can be printed even when no usable font outline exists.
+
+For a native PDF packet with preserved `.path` programs, install the optional font dependencies and export an ordinary OpenType CFF font:
+
+```sh
+python -m pip install 'guwenzi-tools[fonts]'
+guwenzi-tools font build --packet work/page-1 --output work/font
+guwenzi-tools font encode text.txt --map work/font/glyph-map.json --output work/typeset.txt
+```
+
+Install the generated `.otf` in your word processor, or explicitly embed it in your typesetting tool. `font-preview.html` embeds it for local browser viewing. `glyph-map.json` records its SHA256, font-local PUA characters, gwz identities, original path hashes and geometric transforms. Keep the font and mapping with the document. A gwz identifier alone is not an installed font character; PUA has meaning only with the matching font.
+
+Supported original fill paths retain Bezier curves; independent fills are unioned before font encoding. Unsupported paint/clipping operations and conflicting outlines are reported, not silently traced. CFF has finite coordinate precision, and the export normalizes the glyph into a common em box; it does not recover the original font's complete metrics. Original evidence remains unchanged.
+
+For a **printed bitmap** without usable original outlines, a multimodal agent can reuse the existing companion `guwenzi-glyph compose` CLI to write KAGE programs, render, inspect, revise and export fonts. This is explicitly a model reconstruction, not the original shape. Handwriting, rubbings and uncertain forms remain images. The companion CLI, Node, KAGE engine and GlyphWiki dump are separate from this lightweight client; `pip install guwenzi-tools` does not install them. The client itself does not infer a KAGE program from a bitmap.
+
+`glyph search` deliberately shows images and request-scoped candidate IDs before revealing labels. `glyph select` returns the complete selected identity; `glyph resolve` saves it in `result.json` and includes an `identity` summary on stdout: source codepoints, font/source hashes, version, glyph ID/name and available source aliases/relations. `reading_status=no_confirmed_reading_in_v1` means the API does not provide a verified scholarly reading. A source font can borrow an unassigned, private-use or unrelated codepoint; neither a `U+...` label nor a glyph name confirms Unicode identity. `source_material_in_bundle=false` also means the metadata is available but the original font program is not in that deployed bundle.

guwenzi_tools-0.2.0/PUBLISHING.md

@@ -0,0 +1,66 @@
+# Publishing the lightweight client
+
+`guwenzi-tools` is a normal Python distribution, even when the inference service is hosted on your own server. PyPI hosts the CLI/SDK code; the server endpoint and credentials are configured by the installer. PyPI does not run the server or distribute its model weights. This client's license is MIT; it does not license the server image, models or glyph datasets.
+
+The client source is this directory (`tools/guwenzi-client`), not the historical server-side package in `tools/guwenzi-service`. The distribution contains only `gwz_client`, the public tool schemas, the agent skill and documentation. Do not add endpoint credentials, `.ossutilconfig`, local profiles, workspaces or research data to it.
+
+## 1. Build and inspect locally
+
+Use Python3.10 or newer, in an isolated environment:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m unittest discover -s tests -v
+python -m build --outdir dist
+python -m twine check dist/*.whl dist/*.tar.gz
+python scripts/audit_dist.py dist
+```
+
+Test installation into a new virtual environment and run `guwenzi-tools --version`, `tools`, `agent guide` and a real service call. The release is compatible with the existing CPU service protocol v1; it does not require re-uploading its Docker image.
+
+## 2. Create the publishing account
+
+Create a PyPI account, verify its email address and enable two-factor authentication. TestPyPI is a separate service/account. The name `guwenzi-tools` must still be available when you first upload; a successful lookup returning404 is not a reservation. Recheck it before publishing. If someone else owns it, choose a different distribution name in pyproject.toml (the console command can remain guwenzi-tools).
+
+For manual upload, create a PyPI API token in account settings. On the first upload there is no existing project to scope a token to, so use the available account-level token option for that initial creation, then use a project-scoped token for later releases. The PyPI token is separate from the EAS service token and Alibaba AccessKey. Supply publishing credentials to Twine locally; do not put them in the package.
+
+## 3. Upload to TestPyPI, then verify installation
+
+```sh
+python -m twine upload --repository testpypi --username __token__ dist/*.whl dist/*.tar.gz
+```
+
+Enter the TestPyPI API token at the password prompt. Install ordinary dependencies from the normal PyPI index first, then fetch only this package from TestPyPI:
+
+```sh
+python -m pip install 'httpx>=0.28,<1' 'filelock>=3.15,<4'
+python -m pip install --index-url https://test.pypi.org/simple/ --no-deps guwenzi-tools==0.2.0
+guwenzi-tools --version
+```
+
+Configure a server profile and exercise a small document. Publishing a client to TestPyPI does not copy your EAS endpoint or give test users server access.
+
+## 4. Publish the reviewed artefacts to PyPI
+
+```sh
+python -m twine upload --username __token__ dist/*.whl dist/*.tar.gz
+```
+
+Use the PyPI token, not the TestPyPI token. A package/version filename cannot simply be overwritten later: bump the version for subsequent changes. Once uploaded successfully, users can run:
+
+```sh
+python -m pip install guwenzi-tools
+guwenzi-tools configure --endpoint https://their-service.example/api/predict/guwenzi_tools
+guwenzi-tools doctor --quick
+guwenzi-tools agent install-skill --directory /their-agent/skills/guwenzi-remote
+```
+
+Actual PyPI/TestPyPI upload is an explicit release action. The build/audit scripts do not upload anything automatically.
+
+## Automated releases later
+
+When a source repository and CI are available, PyPI Trusted Publishing can exchange a CI identity for a short-lived publishing token. Configure the exact repository/workflow/environment under the project (or a pending publisher), build once, run tests, inspect the artefacts, then publish through the protected release workflow. A source repository is not required for the first manual Twine release.
+
+For a public hosted service, separate client distribution from user provisioning. The current v1 EAS token gives access to one shared service/data domain; a public multi-user offering still needs independent identities, data isolation, quotas and service-side limits. The CLI's profiles are not that isolation layer.
+
+References: [Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/), [TestPyPI guide](https://packaging.python.org/en/latest/guides/using-testpypi/), [PyPI account/token help](https://pypi.org/help/), [Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/), [Twine](https://twine.readthedocs.io/en/stable/).

guwenzi_tools-0.2.0/README.md

@@ -0,0 +1,178 @@
+# guwenzi-tools
+
+A lightweight CLI and Python client for a remote **Guwenzi** historical-document and glyph service. Supports external multimodal agents that can run commands and view images. Python 3.10+; Linux, macOS and Windows. Client license: MIT.
+
+安装包只包含客户端、工具schema和agent说明。模型、字库、文献和访问凭据留在各自的部署环境里。服务端需要实现 `guwenzi.tools.v1`；安装客户端不会自动获得公共推理服务，也不会在本机下载或加载Qwen、DINO、YOLO、torch或MLX。
+
+## Install and connect
+
+Once the project is published to PyPI:
+
+```sh
+python -m pip install guwenzi-tools
+```
+
+Before publication, install the release wheel or this source directory:
+
+```sh
+python -m pip install /path/to/guwenzi_tools-0.2.0-py3-none-any.whl
+# or, from this directory
+python -m pip install .
+```
+
+Configure the endpoint once. Enter the service token at the hidden prompt:
+
+```sh
+guwenzi-tools configure --endpoint https://your-service.example/api/predict/guwenzi_tools
+guwenzi-tools doctor --quick
+guwenzi-tools doctor
+```
+
+EAS uses raw Authorization by default. For a standalone server with Bearer authentication add `--auth bearer`. HTTPS is the default requirement; explicitly use `--allow-http` for a service that only has HTTP. Loopback HTTP works for local testing. The complete service URL includes its application prefix; do not append `/health` or `/v1` when configuring it.
+
+For agents and CI, configure a reference to an environment variable instead of storing its value:
+
+```sh
+guwenzi-tools configure --endpoint https://your-service.example/api/predict/guwenzi_tools --token-env GWZ_REMOTE_TOKEN
+```
+
+Provide that environment variable through your agent's secret settings. `--token-stdin` is another option. `config show` redacts saved tokens. Multiple profiles are supported with `--profile NAME`; `config use NAME` changes the default, and the first configured profile is selected automatically. The config location can be changed with `--config FILE` or `GWZ_CLIENT_CONFIG`. POSIX credential files are written with mode0600.
+
+The existing `GWZ_REMOTE_URL`, `GWZ_REMOTE_TOKEN`, `GWZ_REMOTE_AUTH` environment variables and `--remote URL` alias remain supported. Explicit endpoint overrides do not inherit a different server's stored token.
+
+## Document workflow
+
+Start with one page, inspect the evidence, and continue according to the reading task:
+
+```sh
+guwenzi-tools document open paper.pdf
+guwenzi-tools page prepare DOCUMENT_ID 1 --output work/page-1
+```
+
+For a terminal tool with a short waiting limit, submit and collect separately:
+
+```sh
+guwenzi-tools page prepare DOCUMENT_ID 1 --output work/page-1 --detach
+guwenzi-tools status JOB_ID --wait --output work/page-1
+```
+
+The second command downloads the completed page's evidence and prints a compact summary. It can be repeated after an interruption. Crop, line splitting and glyph search/resolve also support `--detach`.
+
+Or prepare selected pages in one resumable operation:
+
+```sh
+guwenzi-tools document prepare paper.pdf --pages 1-3 --output work/paper
+guwenzi-tools document prepare paper.pdf --pages 1-3 --output work/paper --resume
+```
+
+`document prepare` defaults to all pages if `--pages` is omitted. Mode/DPI, endpoint, page range and source hash must agree when resuming. Preparation is sequential, matching the small server's one-heavy-task limit. A complete evidence preparation is not a completed OCR transcription.
+
+Output folders contain:
+
+| File | Purpose |
+|---|---|
+| `brief.json` | Compact navigation and original image paths |
+| `result.json` | Full server response, with source text and unresolved status |
+| `materials.json` | Original/viewing-derivative files and SHA256 verification |
+| `index.html` | Local visual review page; image links open original files |
+| `transcriptions.draft.json` | Per-block requests to fill after reading the images |
+| `assets/` | Exact original bytes and separately labelled enlarged views |
+
+Native PDFs retain source-layer text and original glyph evidence. Scans use remote YOLO layout and projection lines/slots, then the calling multimodal model supplies text. Word/PPT are converted by the server. The CLI itself does not infer the reading of an image.
+
+## Uncertain glyphs
+
+```sh
+guwenzi-tools line split LINE_ASSET_ID --output work/line
+guwenzi-tools crop LINE_ASSET_ID --box 10 0 60 80 --output work/crop
+guwenzi-tools glyph search CROP_ASSET_ID --output work/search
+```
+
+View the query and candidate originals returned by the search. Select a matching candidate using its request-scoped ID:
+
+```sh
+guwenzi-tools glyph select SEARCH_ID c3 --output work/binding.json
+```
+
+The choice of `c3` is an example, not a default decision. If no candidate matches, expand once or register the unresolved original:
+
+```sh
+guwenzi-tools glyph search CROP_ASSET_ID --expand-search SEARCH_ID --output work/expanded
+guwenzi-tools glyph register CROP_ASSET_ID --output work/unresolved.json
+guwenzi-tools glyph resolve PERMANENT_CODE --output work/identity
+```
+
+Projection proposes boundaries. Crop boxes always use original-image pixels. `gwz:` codes identify a specific original/source asset; similarity, selection and a valid code do not prove a Unicode reading. Source identities and original forms are preserved.
+
+## Transcribe and export
+
+Fill `transcriptions.draft.json` with text and structured glyph references, then:
+
+```sh
+guwenzi-tools transcribe work/page-1/transcriptions.draft.json
+guwenzi-tools document result DOCUMENT_ID --offset 0 --limit 20
+guwenzi-tools document export DOCUMENT_ID --output work/export
+```
+
+Use `--skip-empty` only when intentionally submitting a partially filled draft. Every `part` has exactly one string field: `text`, `binding_id`, `glyph_code`, or `asset_id`. Bindings must belong to the selected block or its recorded crops/slots; the server enforces the association. The exported JSON keeps original source text, transcriptions, figures/tables and verification status. JSON preserves codepoints exactly; it performs no Unicode normalization or traditional/simplified conversion. Markdown is a readable derivative and references the preserved image files.
+
+Export saves assets referenced by the v1 API and the archived original document. It does not claim to enumerate every intermediate file kept inside the server. For large exports, consider `--no-images` first or a page-specific evidence packet.
+
+## Agents and low-level access
+
+```sh
+guwenzi-tools agent guide --plain
+guwenzi-tools agent install-skill --directory /your-agent/skills/guwenzi-remote
+guwenzi-tools tools
+guwenzi-tools tools --server
+guwenzi-tools call glyph_search --json @request.json
+guwenzi-tools call page_prepare --json @request.json --detach
+guwenzi-tools status JOB_ID --wait
+guwenzi-tools asset ASSET_ID --output original.png
+```
+
+Convenience commands output one JSON envelope on stdout and progress on stderr. Full page/search responses are stored locally while summaries point the agent to image files; image base64 is not printed. `call` and `status` retain the v1 job envelope. Tasks already submitted continue on the server if the CLI stops waiting. Receipts retain job IDs without credentials. An uncertain POST outcome is not automatically repeated; GET failures and explicit429 rejections have bounded retries.
+
+Any multimodal agent with shell access and an image-viewing function can use the same CLI. Hosted chat interfaces that cannot run commands need an application-side tool adapter; installing a Python package alone does not give a hosted model filesystem or shell access. No MCP connection or specific model provider is required.
+
+## Python SDK
+
+```python
+from gwz_client import Client
+from gwz_client.workflow import Preparation
+
+with Client.from_config() as client:
+    print(client.health())
+    result = Preparation(client, "work/paper").run("paper.pdf", page_spec="1")
+    print(result["document_id"])
+    job = client.call("document_result", {"document_id": result["document_id"], "limit": 20})
+    print(job["result"])
+```
+
+Credentials can also be supplied to `Client(endpoint, token, auth="raw")` by your application's secret store. The SDK and CLI share the same transport and integrity checks.
+
+## Distribution and service access
+
+PyPI distributes the client, not an inference entitlement. Each deployment owner provides an endpoint and access credentials separately. The current v1 service has one EAS access domain and a shared document store; profiles are client connection settings, not server-side tenant isolation. A public multi-user SaaS would need separate identity, quotas and data isolation on the service side.
+
+This repository can build a wheel and source distribution with `python -m build`, and validate them with `python -m twine check dist/*`. Publication is a separate owner action. See `PUBLISHING.md` in the source distribution for TestPyPI/PyPI release steps. This MIT license covers the client only; server dependencies, model weights and external glyph datasets have their own licenses.
+
+## Inline glyphs and real fonts
+
+Page preparation and document export write `reading.html`: permanent gwz markers display as inline glyph images, with links to the enlarged originals. Long IDs remain in the evidence JSON. This view can be printed even when no usable font outline exists.
+
+For a native PDF packet with preserved `.path` programs, install the optional font dependencies and export an ordinary OpenType CFF font:
+
+```sh
+python -m pip install 'guwenzi-tools[fonts]'
+guwenzi-tools font build --packet work/page-1 --output work/font
+guwenzi-tools font encode text.txt --map work/font/glyph-map.json --output work/typeset.txt
+```
+
+Install the generated `.otf` in your word processor, or explicitly embed it in your typesetting tool. `font-preview.html` embeds it for local browser viewing. `glyph-map.json` records its SHA256, font-local PUA characters, gwz identities, original path hashes and geometric transforms. Keep the font and mapping with the document. A gwz identifier alone is not an installed font character; PUA has meaning only with the matching font.
+
+Supported original fill paths retain Bezier curves; independent fills are unioned before font encoding. Unsupported paint/clipping operations and conflicting outlines are reported, not silently traced. CFF has finite coordinate precision, and the export normalizes the glyph into a common em box; it does not recover the original font's complete metrics. Original evidence remains unchanged.
+
+For a **printed bitmap** without usable original outlines, a multimodal agent can reuse the existing companion `guwenzi-glyph compose` CLI to write KAGE programs, render, inspect, revise and export fonts. This is explicitly a model reconstruction, not the original shape. Handwriting, rubbings and uncertain forms remain images. The companion CLI, Node, KAGE engine and GlyphWiki dump are separate from this lightweight client; `pip install guwenzi-tools` does not install them. The client itself does not infer a KAGE program from a bitmap.
+
+`glyph search` deliberately shows images and request-scoped candidate IDs before revealing labels. `glyph select` returns the complete selected identity; `glyph resolve` saves it in `result.json` and includes an `identity` summary on stdout: source codepoints, font/source hashes, version, glyph ID/name and available source aliases/relations. `reading_status=no_confirmed_reading_in_v1` means the API does not provide a verified scholarly reading. A source font can borrow an unassigned, private-use or unrelated codepoint; neither a `U+...` label nor a glyph name confirms Unicode identity. `source_material_in_bundle=false` also means the metadata is available but the original font program is not in that deployed bundle.

guwenzi_tools-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "guwenzi-tools"
+version = "0.2.0"
+description = "CLI and Python client for evidence-preserving historical-document and glyph tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Guwenzi contributors"}]
+keywords = ["ocr", "paleography", "glyph", "cli", "multimodal"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Image Recognition"
+]
+dependencies = ["httpx>=0.28,<1", "filelock>=3.15,<4"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2,<2", "twine>=6,<7"]
+fonts = ["fonttools>=4.60,<5", "skia-pathops>=0.8,<1"]
+
+[project.scripts]
+guwenzi-tools = "gwz_client.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gwz_client = ["data/*.json", "data/*.md", "data/skill/*.md"]

guwenzi_tools-0.2.0/scripts/audit_dist.py

@@ -0,0 +1,39 @@
+"""Reject server/model/private artefacts before publication. Does not upload."""
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+import tarfile
+import zipfile
+
+FORBIDDEN_PATHS = ('.venv/','gwz_service/','datasets/','research/','training/','outputs/','.ossutilconfig','.pypirc')
+FORBIDDEN_SUFFIXES = ('.pt','.pth','.npy','.sqlite3','.safetensors','.pdf','.png','.jpg','.jpeg')
+PRIVATE_PATTERNS = (rb'/Users/[A-Za-z0-9._-]+/', rb'\d{12,20}\.cn-[a-z]+\.pai-eas',
+                    rb'oss-pai-[a-z0-9]+-cn-[a-z]+', rb'crpi-[a-z0-9]+(?:-vpc)?\.cn-')
+
+def audit(directory):
+    directory=Path(directory)
+    reports=[]
+    for file in sorted([*directory.glob('*.whl'),*directory.glob('*.tar.gz')]):
+        if file.name.endswith('.whl'):
+            with zipfile.ZipFile(file) as z:members=[(name,z.read(name)) for name in z.namelist() if not name.endswith('/')]
+        else:
+            with tarfile.open(file) as z:members=[(m.name,z.extractfile(m).read()) for m in z.getmembers() if m.isfile()]
+        for name,data in members:
+            if any(part in name for part in FORBIDDEN_PATHS) or name.endswith(FORBIDDEN_SUFFIXES):
+                raise ValueError('Forbidden package member: '+name)
+            if any(re.search(pattern,data) for pattern in PRIVATE_PATTERNS):
+                raise ValueError('Private deployment reference in package: '+name)
+        assert any(name.endswith('skill/SKILL.md') for name,_ in members),'Missing skill'
+        assert any(name.endswith('tools-v1.json') for name,_ in members),'Missing tool schema'
+        assert any(name.endswith('LICENSE') for name,_ in members),'Missing license'
+        reports.append({'file':file.name,'bytes':file.stat().st_size,'sha256':hashlib.sha256(file.read_bytes()).hexdigest(),
+                        'members':len(members),'status':'passed'})
+    if len(reports)!=2:
+        raise ValueError('Expected one wheel and one sdist')
+    return {'status':'passed','artefacts':reports,'uploaded':False}
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser();p.add_argument('directory');a=p.parse_args()
+    print(json.dumps(audit(a.directory),indent=2))

guwenzi_tools-0.2.0/scripts/integration_check.py

@@ -0,0 +1,78 @@
+"""Exercise the installed client against a real v1 host; never logs tokens.
+
+Provide a directory with native.pdf, raster.png and query.png. The fixtures
+are not part of the distribution. This uploads them to the chosen service.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+def run(args):
+    root=Path(args.output).resolve();root.mkdir(parents=True,exist_ok=True)
+    env=dict(os.environ)
+    env['GWZ_CLIENT_CONFIG']=str(root/'profile.json')
+    # In real use configure a profile or supply GWZ_REMOTE_TOKEN externally.
+    commands=[]
+    def cli(*parts, label=None):
+        started=time.monotonic()
+        p=subprocess.run([sys.executable,'-m','gwz_client.cli',*map(str,parts)],env=env,capture_output=True,text=True)
+        try:response=json.loads(p.stdout)
+        except ValueError as exc:raise RuntimeError('Client did not return JSON: '+p.stderr[:2000]) from exc
+        if p.returncode or not response.get('ok'):
+            raise RuntimeError(json.dumps(response,ensure_ascii=True))
+        name=label or ('-'.join(str(x) for x in parts[:2]))
+        (root/(name+'.json')).write_text(json.dumps(response,ensure_ascii=True,indent=2))
+        commands.append({'command':name,'seconds':time.monotonic()-started,'ok':True})
+        print(json.dumps(commands[-1]),flush=True)
+        return response['result']
+    cli('configure','--endpoint',args.endpoint,'--token-env','GWZ_REMOTE_TOKEN',label='configure')
+    cli('doctor','--quick',label='doctor-quick')
+    cli('tools','--server',label='server-tools')
+    native=cli('document','prepare',Path(args.fixtures)/'native.pdf','--pages','3','--output',root/'native',label='prepare-native')
+    resume=cli('document','prepare',Path(args.fixtures)/'native.pdf','--pages','3','--output',root/'native','--resume',label='resume-native')
+    assert native['document_id']==resume['document_id']
+    raster=cli('document','prepare',Path(args.fixtures)/'raster.png','--pages','1','--output',root/'raster',label='prepare-raster')
+    page=json.loads((root/'raster/pages/p0001/result.json').read_text())
+    assert any(b['type']=='table' for b in page['blocks'])
+    line=next(b for b in page['blocks'] if b['type']=='text' and b.get('slot_count',0)>1)
+    split=cli('line','split',line['asset']['asset_id'],'--output',root/'split',label='split-line')
+    slot=split['slots'][0]
+    crop=cli('crop',line['asset']['asset_id'],'--box',*slot['bbox_px'],'--output',root/'crop',label='crop-slot')
+    assert crop['asset_id']==slot['asset_id']
+    unknown=cli('glyph','register',crop['asset_id'],label='register-original')
+    transcription={'document_id':raster['document_id'],'page':1,'block_id':line['block_id'],
+                   'parts':[{'text':'整合測試𠀀後：'},{'glyph_code':unknown['code']}]}
+    request=root/'transcribe.json';request.write_text(json.dumps(transcription,ensure_ascii=True))
+    cli('transcribe',request,label='transcribe-original')
+    uploaded=cli('upload',Path(args.fixtures)/'query.png',label='upload-query')
+    imported=subprocess.run([sys.executable,'-m','gwz_client.cli','call','asset_import','--json',
+                              json.dumps({'input_key':uploaded['input_key']})],env=env,capture_output=True,text=True)
+    envelope=json.loads(imported.stdout)
+    assert imported.returncode==0 and envelope['ok']
+    aid=envelope['result']['asset_id']
+    search=cli('glyph','search',aid,'--output',root/'search',label='search-eight')
+    assert len(search['candidates'])==8
+    for c in search['candidates']:
+        assert Path(c['image']).is_file() and Path(c['view']).is_file()
+    # This is a scoped-binding regression check, not an autonomous visual
+    # model or an accuracy benchmark. Choice is explicit in the test.
+    selected=cli('glyph','select',search['search_id'],'c1',label='select-known-regression-candidate')
+    assert selected['recognition_status']=='model_selected_unverified'
+    cli('glyph','resolve',selected['code'],'--output',root/'resolved',label='resolve-code')
+    exported=cli('document','export',raster['document_id'],'--output',root/'export',label='export-document')
+    assert '整合測試𠀀後' in Path(exported['markdown']).read_text()
+    assert not exported['content_verified']
+    report={'status':'passed','commands':commands,'client_version':'0.2.0','protocol':'guwenzi.tools.v1',
+            'native_document_id':native['document_id'],'raster_document_id':raster['document_id'],
+            'selected_code':selected['code'],'raster_blocks':len(page['blocks']),
+            'note':'Real transport/model tests; explicit regression selection and synthetic transcription, not OCR accuracy.'}
+    (root/'report.json').write_text(json.dumps(report,indent=2))
+    print(json.dumps({'status':'passed','report':str(root/'report.json')}))
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser();p.add_argument('--endpoint',required=True);p.add_argument('--fixtures',required=True);p.add_argument('--output',required=True)
+    run(p.parse_args())

guwenzi_tools-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+