Add JSON Patch to SDK

[kpwtxt]

No description provided.

[aschwa]

Slick examples! A few clarifying nits

[rlouf]

Almost there! Not sure what the LICENSE file is doing there + should we add an example of constructing the JSON object from the stream (there must be a python library that does that?).

[kpwtxt]

@rlouf Added a jsonpatch example: 5fc45ab#diff-3fe5c41a0700fcc1431745fe8ca47fb82c935ffcfb16c12dd085a4343469c378

[kpwtxt]

Added a CLI wrapper around the stream client:

$ dottxt stream  --timing --model openai/gpt-oss-20b   --schema contact.schema.json   "Extract: John Smith <john@acme.com>, VP Engineering"
{"op":"add","path":"","value":{}}
[timing] #1   t=+2209.8ms  Δ=+2209.8ms  add /
{"op":"add","path":"/email","value":".<john@acme.com>"}
[timing] #2   t=+2210.1ms  Δ=+0.3ms     add /email
{"op":"add","path":"/name","value":"John Smith"}
[timing] #3   t=+2211.6ms  Δ=+1.5ms     add /name
{"op":"add","path":"/role","value":"VP Engineering"}
[timing] #4   t=+2242.8ms  Δ=+31.3ms    add /role
[timing] done events=4 elapsed=2251.6ms

[rlouf]

What's the case for the is_leaf method?

[kpwtxt]

It lets you filter structural add ops like {} [] and the root object creation. If is_leaf == True then a field / value were set by the add op.

[kpwtxt]

@rlouf Here's a real example showing what ops look like with nested objects:

{"op":"add","path":"","value":{}}
{"op":"add","path":"/address","value":{}}
{"op":"add","path":"/address/city","value":"Raleigh"}
{"op":"add","path":"/address/country","value":"/USA"}
{"op":"add","path":"/address/postal_code","value":"27604"}
{"op":"add","path":"/address/street","value":"123 Main St"}
{"op":"add","path":"/email","value":"john@acme.com"}
{"op":"add","path":"/name","value":"John Smith"}
{"op":"add","path":"/role","value":"VP Engineering"}

Two options come to mind:

1. Drop is_leaf() and force the client to figure how to handle something like "path":"","value":{} or "path":"/address","value":{}

2. Keep is_leaf() as a convience function, but leave it out of the example as the field name string match is sufficient to skip non-leaf values.

[kpwtxt]

This example would work without the is_leaf() check:

        async for event in stream:
            if not event.is_leaf:
                continue
            match event.field:
                case "action":
                    proposed_action = event.value
                    print(f"proposed action: {event.value}")
                    if event.value in HIGH_RISK_ACTIONS:
                        approved = await ask_human(f"Approve action '{event.value}'?")
                        if not approved:
                            print("operator declined — reply will not be sent")
                case "reply" if approved:
                    await send_reply(event.value)
                case "reply":
                    print(f"discarded reply (action '{proposed_action}' declined)")

But this example would change without adding its own check for non-leaf values:

        async for event in stream:
            if not event.is_leaf:
                continue
            print(f"{event.field:>24} = {event.value!r}")

[kpwtxt]

Went with 2) for now. Dropped is_leaf prior to the match since the field name/value check filters. Kept it for the field iteration as a filter against op events for empty objects.