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

Install from PyPI:

python -m pip install guwenzi-tools

Alternatively, install a release wheel or this source directory:

python -m pip install /path/to/guwenzi_tools-0.3.2-py3-none-any.whl
# or, from this directory
python -m pip install .

Option A: log in with an Open Glyph website account (0.3+)

If you have an account on the Open Glyph website (or another site running the same gateway), no endpoint or token is needed:

guwenzi-tools login

The CLI shows a connection code and opens the website in your browser. Confirm the code matches and approve; the terminal completes automatically. The issued credential belongs to your account, is stored only on this machine, and can be revoked at any time from the website workspace (账号与数据) or with:

guwenzi-tools whoami
guwenzi-tools logout   # revokes on the server and removes the local profile

--website URL points at a different site; --no-browser prints the approval URL instead of opening it.

Option B: configure your own service (self-hosted)

Configure the endpoint once. Enter the service token at the hidden prompt:

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:

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:

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:

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:

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

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:

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:

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:

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

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

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:

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.