[wangyeyu1129]

Description:

Refs #18 — protocol foundation only; no issue closed.

Adds an installable, standard-library-only Python implementation of the stateless vRT v1 message and audio codecs. It uses the shared specification and vectors as its contract. This is the first part of #18, not a connection/session SDK or a claim of full conformance.

Behaviours Completed

• Decode and validate both directions of current control messages, including structural rules for every tool.stream phase, and encode validated messages without non-standard JSON numbers.
• Return classified protocol errors in framing → version → type → fields order; retain unknown members and unknown syntactically valid capability tokens.
• Distinguish missing from null and bool from numeric fields. Preserve decimal/exponent tokens with standard-library Decimal so rounding cannot turn invalid integer/range values into valid ones. Emit integral values with integer spelling.
• Encode/decode the five-byte big-endian audio header, handle uint32 boundaries and empty payloads, and optionally check sender direction. Decoding returns a read-only borrowed payload view; encoding returns owned bytes.
• Add development-only validation/lint/build tools, shared-vector and independent schema mutation tests, Python 3.10/3.14 CI, artifact installation smoke checks and an aggregate 800-line core budget check.
• Include the Apache-2.0 license in both distribution artifacts. No runtime dependencies or PyPI publication.

Files Changed

• python/src/vrealtime/protocol.py: pure codecs, structural checks, error/result types and named protocol/local-limit constants.
• python/src/vrealtime/__init__.py: explicit public exports.
• python/pyproject.toml, python/LICENSE, python/.gitignore: packaging, development tooling and generated-file exclusions.
• python/tests/conftest.py, test_spec.py, test_protocol.py, check_install.py: shared fixtures, schema oracle, edge cases and clean-install checks.
• python/README.md: API, ownership, implementation limits, known contract discrepancies, development and remaining SDK work.
• .github/workflows/python.yml: Python checks when Python/spec/workflow files change.
• README.md: link to the foundation with its scope stated explicitly.

Brief Explanation

The protocol layer has no transport, provider, device or application dependencies. Data-driven field rules and small pure functions keep validation separate from framing without introducing unused SDK abstractions. Schemas are test-time oracles, not runtime dependencies; the installed package does not read checkout files.

Tests consume the existing shared vector IDs and independently check field mutations against draft 2020-12 schemas. Numeric parsing avoids Python bool/int confusion and binary64 underflow/rounding at validation boundaries. Local depth and numeric-token/expansion limits are documented separately from wire constants. The parser allocates before depth validation, so future transports must impose frame-byte limits.

This change leaves shared schemas, vectors and TypeScript implementation unchanged. Session ordering, capability negotiation, ACK/replay, interrupts, tool execution, sockets and device audio remain for later #18 work; #17 black-box conformance is not implemented here.

Testing

• Python 3.10.22 and 3.14.8: 388 tests passed on each, including all 156 control and 9 audio vectors, schema field mutations and independent parser/audio boundary checks.
• Ruff lint and format checks passed; Python 3.10 syntax verified.
• Built wheel and sdist, then installed each into separate clean environments on Python 3.10.22 and 3.14.8 (four combinations): smoke checks passed without runtime dependencies. Apache license contents verified in both artifacts.
• Existing TypeScript checks on Node 24.15.0: npm run check:spec, npm run typecheck, npm test (459), npm run test:e2e (7), npm run build, npm run check:budgets: passed.
• Production Python code: 470 lines total, below the issue's aggregate 800-line core budget, with the rest of the SDK still pending.
• git diff --check: passed. GitHub-hosted Python matrix results are separate from local results.

Unsure About

• Duplicate JSON object names are rejected as MALFORMED. The spec prohibits senders from duplicating names but does not assign an explicit receiver classification; this local parser policy needs review.
• The prose requires unique hello.tools names, whereas the schema and TypeScript guard do not enforce uniqueness. Python enforces the explicit rule, with a regression documenting the schema discrepancy.
• Current schema/TypeScript regexes permit a final newline in capability/error-code tokens despite prose token descriptions. Python retains schema acceptance under the stated precedence; tightening the shared contract needs a separate decision.
• §3.3 still says the registry has no capabilities, while the actual registry and §7.5 define tool-stream-v1. This implementation supports message structure without advertising or negotiating that capability.
• Decimal-valued payloads and local numeric/depth limits are explicit Python API choices documented for review. This foundation has no measured real-time performance claim and is not yet a usable network SDK.