Skip to content

python-consumption.md

Latest commit

 

History

History
126 lines (102 loc) · 9.53 KB

python-consumption.md

File metadata and controls

126 lines (102 loc) · 9.53 KB

Python Consumption

This page describes the public JSON-first consumption path for Python users.

It is intentionally narrow:

  • read the published client-recipe navigator before choosing a Python or cross-language entrypoint
  • read compact reference JSON artifacts
  • read the compact validator envelope-family map
  • build validator-envelope requests for validate, batch, and fix flows from the published example payloads
  • call the published gates and stats support routes from the same raw-JSON path
  • parse validator pass/fail/batch/fix, bounded shared plus route-specific error-envelope, and support response envelopes from the published example payloads
  • inspect curated raw capsule assets
  • recompute integrity_sha3_512 from the published G16 rule
  • consume the same assets from a repository checkout or an extracted packed artifact

It does not turn this repository into a PyPI package, a Python SDK, or a replacement for the stronger schema, OpenAPI, or live-validator surfaces.

If you want the strongest published HTTP contract directly rather than the compact route pack first, inspect ../examples/client/python-openapi-reference.py. That recipe reads the packaged openapi/validate.openapi.json artifact from a repo checkout or extracted tarball and recovers the published route family, bearer-auth scheme, bounded stats query parameter, and response-status coverage without Node imports.

Repo checkout recipes

The shortest repo-relative Python examples live under ../examples/client/:

Run them from a checkout with:

python3 examples/client/python-client-recipe-index.py
python3 examples/client/python-parse-archive-bundle.py
python3 examples/client/python-contract-reference.py
python3 examples/client/python-live-validator-client.py
python3 examples/client/python-recompute-integrity-seal.py
python3 examples/client/python-validate-single.py
python3 examples/client/python-validate-batch.py
python3 examples/client/python-validate-fix.py
python3 examples/client/python-get-gates.py
python3 examples/client/python-get-stats.py
python3 examples/client/python-parse-validate-responses.py
python3 examples/client/python-parse-error-responses.py
python3 examples/client/python-parse-support-responses.py

The first recipe reads the published client-recipe navigator and recovers the Python and package runtime starts plus the dedicated Python and installed-package navigation tasks. The second recipe reads the published archive-bundle sample directly as raw JSON so Python consumers can inspect replay posture and manifest contents without Node imports or a Python SDK layer. The third recipe reads the compact contract-reference JSON exports. That includes the compact validator envelope-family map in addition to the root constants, gate map, route map, and curated confidence-vector capsule. The fourth recipe turns the published route map plus request examples into one reusable Python live-validator bridge for validate, batch, fix, gates, and stats, defaulting to a dry-run summary and switching to live HTTP calls when N1HUB_BASE_URL and N1HUB_TOKEN are set. The fifth recipe recomputes integrity_sha3_512 over the published four-root payload, verifies the positive note example, and computes the repaired hash for the intentional G16 teaching example. The validator-envelope request recipes load the published validate, batch, and fix request examples, print dry-run summaries by default, and can send those envelopes to a live validator when N1HUB_BASE_URL and N1HUB_TOKEN are set. The support-route recipes read the published gates and stats samples by default and switch to live HTTP requests against the same routes when N1HUB_BASE_URL and N1HUB_TOKEN are set. python-get-stats.py also accepts N1HUB_STATS_LIMIT for the bounded published GET /api/validate/stats?limit=... path. The response-parsing recipes load the published pass/fail/batch/fix, bounded shared plus route-specific error-envelope, and support-response examples so Python consumers can inspect bounded response families without guessing field layout from prose alone.

Packed-artifact workflow

Python users do not need npm install to consume the JSON artifacts. They can work from an extracted tarball or another unpacked release artifact.

Example flow:

npm pack
mkdir -p packed-artifact
tar -xzf num1hub-capsule-specs-0.2.0.tgz -C packed-artifact
python3 packed-artifact/package/examples/client/python-client-recipe-index.py
python3 packed-artifact/package/examples/client/python-parse-archive-bundle.py
python3 packed-artifact/package/examples/client/python-contract-reference.py
python3 packed-artifact/package/examples/client/python-live-validator-client.py
python3 packed-artifact/package/examples/client/python-recompute-integrity-seal.py
python3 packed-artifact/package/examples/client/python-validate-single.py
python3 packed-artifact/package/examples/client/python-validate-batch.py
python3 packed-artifact/package/examples/client/python-validate-fix.py
python3 packed-artifact/package/examples/client/python-get-gates.py
python3 packed-artifact/package/examples/client/python-get-stats.py
python3 packed-artifact/package/examples/client/python-parse-validate-responses.py
python3 packed-artifact/package/examples/client/python-parse-error-responses.py
python3 packed-artifact/package/examples/client/python-parse-support-responses.py

Those scripts resolve the package root from their own location, so they still work after extraction as long as the package/ layout is preserved.

What this proves

  • Python consumers can read references/contract-constants.json, references/validation-gates.json, and references/validator-envelope-families.json directly.
  • Python consumers can read examples/client/recipe-index.json directly from a repo checkout or extracted packed artifact and recover runtime-lane starts plus task entrypoints without Node imports.
  • Python consumers can read the published archive-bundle sample directly from a repo checkout or extracted packed artifact without a Python SDK wrapper.
  • Python consumers can discover the published validator request families, response families, and shared definitions without scraping schema defs by hand.
  • Python consumers can use references/validator-routes.json plus the published request examples to build one reusable live client for all published validator routes instead of stitching five separate scripts together.
  • Python consumers can load the published validator-envelope request examples for POST /api/validate, POST /api/validate/batch, and POST /api/validate/fix without inferring request shape from prose alone.
  • Python consumers can call the published GET /api/validate/gates and GET /api/validate/stats routes, including the bounded optional limit query path on stats, or inspect their sample payloads from the same raw-JSON path.
  • Python consumers can inspect the published pass/fail/batch/fix validator responses, the bounded shared generic/unauthorized/forbidden/conflict/rate-limit error envelopes plus the route-specific stats-computation failure sample, and the published gates / stats support responses directly from raw JSON assets.
  • Python consumers can recompute published integrity seals without calling private runtime helpers.
  • The packed artifact includes enough public JSON and example material for cross-language consumption.

Boundaries

  • This is a raw-asset consumption path, not a Python package distribution promise.
  • The recipes read published JSON artifacts and documented sealing rules; they do not expose the TypeScript or Zod projection layer as Python modules.
  • The validator-envelope recipes are thin client examples, including one reusable full-route bridge, not a Python SDK, retry stack, or hosted-service guarantee.
  • The recipes prove the published G16 rule, validator-envelope request/response payload shapes, and packaged asset layout, not every edge-case behavior of the live validator.

Related surfaces

Verification

  • npm run check:python-recipes
  • npm run check:package-surface
  • npm run verify:repo