Engineering journal
From Python Agent to Vulkan Frame: Designing a Bounded Control Path
How Omniweft separates authenticated local control, atomic world changes and optional presentation, with explicit limits on what each test establishes.
Source: https://louijiecompo.com/writing/from-python-agent-to-vulkan-frame/
About 4 min read
This article describes the 14 September source snapshot. Since then, Omniweft has added a scripted room showcase with scoped permissions and retained Windows GPU captures. Compare the current room output or read the 19 September update. The discussion below preserves the earlier implementation boundary.
Two implemented slices, two evidence boundaries
An agent asking to move an object should not acquire authority over every part of a world engine. The interesting engineering work is deciding how a request enters, what it can change, and how a caller learns what happened.
Omniweft now has an authenticated local Python SDK and optional SDL3/Vulkan presentation. GitHub records the renderer implementation (opens in a new tab) and SDK implementation (opens in a new tab) as merged on 13 September 2026. The checked README still contains pre-merge SDK language, so merge status must be reconciled with those records.
The title describes an architectural relationship, not a captured end-to-end demonstration. The current SDK example is headless. The renderer presents committed snapshots in a separate native fixture. Their common boundary is world state; the available evidence does not show an agent driving a live rendered window.
Start with a private local session
The SDK guide (opens in a new tab) describes a separate Python process launching a trusted native control host. Private process pipes carry fresh session credentials. The operating system selects an IPv4 loopback port, and the SDK does not follow redirects or discover proxies.
That is a deliberately narrow interface. It is not a remote service, a browser API or an operating-system sandbox. Starting an arbitrary executable would still require trusting that executable.
One host owns one World and one active session. Renewal rotates credentials while preserving the World. Existing clients retain retired credentials and are denied. Scoped grants for multiple principals remain future work.
Negotiate before requesting a change
Capability negotiation tells the client which protocol and request bounds the host admits. Typed values then describe object identity, transforms, expected revisions and transaction receipts. Negotiation is not evidence that every possible engine capability is available.
The SDK example (opens in a new tab) creates a cube, applies a transform and observes the result. It exercises strict admission sequencing and synchronous transactions through the native coordinator. A rejected pre-admission request differs from an admitted transaction that fails atomically. Both need an explicit outcome that a caller can interpret.
Make uncertainty visible
The response to a mutation can be lost after the mutation commits. Retrying automatically could apply a second change while the caller still believes it is completing the first.
Omniweft's SDK reports this as OutcomeUnknown and stops further mutations until the caller observes the current state and explicitly resynchronizes. A fresh session does not silently replay the uncertain action. Duplicate-receipt recovery and retention belong to later work.
This is a useful control-path principle: recovery semantics are part of the interface, not an exception-handling detail added afterward.
Present committed state downstream
The renderer example (opens in a new tab) converts detached committed snapshots into owned presentation packets. Its procedural cube, typed transforms and fixed camera keep the fixture bounded. The optional path uses one window, one device and one frame in flight.
Presentation answers what was drawn from a particular state. It does not decide whether a caller was authorized to create that state. Conversely, a valid authenticated receipt does not prove that pixels were presented correctly. Keeping these claims separate makes the tests more useful.
Read the evidence without widening the claim
The retained Windows GPU evidence (opens in a new tab) is bound to runtime 973162f. The renderer handoff reports 1,961 GPU-oracle assertions and 351 mutation-proof assertions. Linux physical-GPU presentation remains unverified; hosted builds and CPU structural checks do not fill that gap.
The retained SDK evidence (opens in a new tab) is bound to corrected runtime 8ce2f06. It reports 6,502 oracle assertions, with hosted Windows and Linux evidence recorded separately. Expiry and shutdown regressions test real process behavior. This article reviews those records; it does not report new engine runs or throughput measurements.
Keep the next boundary explicit
Physics, persistence, richer mesh, voxel and pixel editing, remote access and performance targets remain future slices. Restarting the current host creates a new fixture world. The SDK is source-distributed, without a published installation package from this slice.
A future integrated agent-to-frame demonstration would need to bind the accepted request, committed revision and presented frame in one retained run. Until then, the Omniweft case study keeps the implemented control and presentation paths visible, with their separate evidence and limitations.
Current project output, added 19 September 2026. These room captures postdate the article's 14 September snapshot and show the later scripted showcase.
Captured output / 18 September 2026
A room built through Python, one checked change at a time.
Five blocks stand in for a floor, two walls, a table and a stool. A scripted Python client builds the room, attempts a forbidden edit, then rearranges the furniture within its permissions.
The rejected plan leaves revision 3 intact. Only the corrected plan changes the room to revision 4.
Retained Windows GPU captures from 18 September 2026. Original 320 × 240 pixels, enlarged here. This is a scripted five-block fixture, not a language-model run or a finished game. Linux physical GPU verification remains not_run.