Skip to main content

liwenjson (Python)

LIWENJSON is the execution gate for LLM output: it decides whether a model's JSON may be executed, and when it may not, returns the sentence to send back to the model. This distribution is the Python client for the MoonBit engine — streaming repair, partial parsing, and the gate — plus two console scripts, one of which starts the local MCP server.

No third-party dependencies and nothing else to install: the wheel carries the engine for every platform the project releases — Linux x86_64 and arm64, macOS arm64, Windows x86_64 — and picks the right one at import time. The engine is the same native binary the CLI ships, reached over a versioned stdio protocol.

pip install liwenjson

The distribution name is liwenjson on PyPI — the bare name, no suffix — and it is also the import name. 1.5.2 is the first release published under it; 1.5.1 reached PyPI on 2026-10-30 as interjson-moonbit. The npm package uses the same name: npm install liwenjson.

An engine that is already installed keeps priority: LIWENJSON_BIN, then liwenjson on PATH, then the bundled binary. Set either to point the client at a newer CLI than the one this wheel was built with.

import json
from liwenjson import Client

with Client() as jm:
    plan = jm.analyze(
        model_output,
        profile="agent",
        schema_json=tool["inputSchema"],  # the declaration you already have
    )
    if plan["executable"]:
        args = json.loads(plan["text"])
    else:
        print(plan["retry"]["prompt"])    # feed this back to the model

Client keeps one liwenjson serve process alive, so a loop pays the spawn cost once. repair, analyze and validate are one-shot convenience functions that spawn a process per call.

Console scripts

Script Use
liwenjson-mcp Start the local MCP server (stdio, JSON-RPC 2.0) for Claude Code, Cursor, Cline, Windsurf, VS Code, Codex CLI or Zed
liwenjson-http Start the stateless HTTP facade (--port 8080)

liwenjson-mcp is a launcher, not a server: it resolves the engine and replaces itself with <binary> mcp, so stdin/stdout stay a clean JSON-RPC channel with no Python in the middle. Resolution order is LIWENJSON_BIN, then liwenjson on PATH, then the binary this wheel carries for the current platform. Only a platform the release does not build for — Intel macOS, for example — needs LIWENJSON_BIN.

liwenjson --version                  # liwenjson 1.5.1: the engine the launchers need
liwenjson-mcp                        # MCP stdio server
liwenjson-mcp --print-config=claude  # the client configuration snippet
liwenjson-http --port 8080           # POST /repair /analyze /validate /readiness, GET /healthz

pip install installs the client, the two console scripts and the engine. Nothing has to be on PATH for the configuration below to work:

With the engine resolvable, the client configuration is one line:

{
  "mcpServers": {
    "liwenjson": { "command": "liwenjson-mcp" }
  }
}

The server exposes four read-only tools: liwenjson_gate (the gate: executable, decision, exactness, value, retry.prompt), liwenjson_repair, liwenjson_validate, and liwenjson_readiness. The gate defaults to the agent profile, which equals Options::for_agent() — prose before the arguments is skipped rather than refused. A refused result always carries a non-empty retry.prompt and value: null. MCP is advisory: the model can decline to call the gate, so the host must gate the call itself (a Claude Code PreToolUse hook or a host-SDK gate() — see docs/INTEGRATIONS.md).

Deployment, per-client configuration, the privacy model and troubleshooting are in docs/MCP.md; host-side recipes (LangChain, LlamaIndex, streaming) are in docs/INTEGRATIONS.md.

liwenjson-http is stateless: one engine process per request, closed after it. It is the path for n8n, Dify, Coze or a gateway; for throughput, use Client.

Methods

Method Returns Use
repair(text, profile=..., schema=...) {text, exactness, ambiguous, repairs, ...} repair a document
analyze(text, profile=..., schema=..., schema_json=...) the full plan the gate; executable decides
validate(text, schema=...) {valid, error?, repaired?, schema?} check without repairing
readiness(text, schema=...) syntax/schema/settled fractions when fields become final
watch_start / watch_feed / watch_finish deltas + readiness events token-by-token
llm_open / llm_feed / llm_close per-tool-call state Anthropic/OpenAI event streams

profile is one of permissive, interactive, execution, agent, strict. execution and agent refuse a lossy or ambiguous repair instead of inventing content; LIWENJSONError carries code, message, exit_code, retry_hint and offset.

schema is the library's declaration language ({!query:string,!limit:integer}). schema_json is a JSON Schema subset — type, properties, required, items, enum, const, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, pattern — so a tool's existing inputSchema can be passed directly. Unsupported keywords raise E070 rather than being silently dropped.

Version

The Python package is 1.5.1, the engine version, published to PyPI on 2026-10-30. The MoonBit package on mooncakes is 0.13.0 because the registry currently accepts only 0.x.y; the bytes are the same. Client.hello() reports both. 0.13.0 was published on 2026-10-29, and 0.12.0 (the 1.5.0 correspondence) on 2026-10-28.

License: Apache-2.0.

Metadata

Release files for liwenjson 1.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for liwenjson 1.5.2
File Size Uploaded Provenance Actions
liwenjson-1.5.2.tar.gz 1.6 MB Without provenance Details for liwenjson-1.5.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for liwenjson 1.5.2
File Interpreter ABI Platform Actions
liwenjson-1.5.2-py3-none-any.whl Python 3 none any Details for liwenjson-1.5.2-py3-none-any.whl

Total release size: 3.2 MB

Release files / liwenjson-1.5.2.tar.gz

Download URL liwenjson-1.5.2.tar.gz
Size 1.6 MB
Tags Source
SHA-256 checksum
How to use checksums
bc604725a00c52532d84a1f12f39ff0e1d017eb633fc086ee3fedff70c727e38
BLAKE2b-256 checksum
How to use checksums
cbcd685e77526a3ba0c88694f12494f11248de07c8a16352631aa38cb2d949f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / liwenjson-1.5.2-py3-none-any.whl

Download URL liwenjson-1.5.2-py3-none-any.whl
Size 1.6 MB
Tags Python 3
SHA-256 checksum
How to use checksums
9ee0649de4a3cbfb3f9164eccead1be3811862d5a3a403897d9b21be8939c771
BLAKE2b-256 checksum
How to use checksums
3e1ac306c68a62a4c4c3725ef2cd5af151e918f7c4d04a76351ee95bd8bb0714
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for liwenjson 1.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.5.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page