Update JSON API and example notebook

[riedgar-ms]

Add the new JSON schema functionality to the example notebook for guaranteeing valid syntax. Also, rename the json_schema argument in the guidance.json() function to be just schema.

[slundberg]

Thanks @riedgar-ms ! Looks great. The only change I would suggest is changing from guidance.library import json as gen_json to from guidance import json as gen_json since we expose all the library functions at the top level.

One other note unrelated to this PR, why do we have json_schema instead of schema for json_schema=character_schema_obj? It seems like it is obviously a json schema since we are generating json and schema matches other libraries like jsonschema

[riedgar-ms]

No particular reason on the argument naming, beyond "That's what came to mind first." I have updated (tag @hudson-ai for info).

We probably should review the arguments across all public functions, and make sure we're consistent about which have to be named when present.

[hudson-ai]

Wonderful! Thank you @riedgar-ms for looping me in :)

May be a separate PR, but it may be worth adding some extra info around effective prompting (in art_of_prompt_design?). Note in particular that quest_items are now just "."...

E.g. showing the LM what schema it will use ahead of time and even adding examples to the schema, e.g.

{
    "type": "object",
    "properties": {
        "description" : { "type" : "string" },
        "name" : { "type" : "string" },
        "age" : { "type" : "integer" },
        "armour" : { "type" : "string", "enum" : ["leather", "chainmail", "plate"] },
        "weapon" : { "type" : "string", "enum" : ["sword", "axe", "mace", "spear", "bow", "crossbow"] },
        "class" : { "type" : "string" },
        "mantra" : { "type" : "string" },
        "strength" : { "type" : "integer" },
        "quest_items" : {
            "type" : "array",
            "items": { "type": "string" },
            "examples": ["Triforce", "Master Sword"],
        }
    }
}

(although maybe not these examples, as Nintendo is very protective of its IP)

I'd also put forward that generating JSON is a popular enough use-case that an example deserves to be in the README, and maybe you guys could consider a version-bump and PyPI release in the near future ;)

[riedgar-ms]

@hudson-ai Something like that would probably be good in expanded documentation (I have a few ideas for what to do with the notebooks, since the fact that they're not run regularly is a big problem).

@slundberg does this look better to you?

[riedgar-ms]

Ping @slundberg

[riedgar-ms]

@slundberg does this address your concerns?

[riedgar-ms]

@slundberg ?

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 65.61%. Comparing base (8f5b3bd) to head (3dfb1aa).

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #699      +/-   ##
==========================================
- Coverage   69.19%   65.61%   -3.58%     
==========================================
  Files          53       53              
  Lines        3967     3967              
==========================================
- Hits         2745     2603     -142     
- Misses       1222     1364     +142     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[riedgar-ms]

@slundberg does this address your concerns?

[riedgar-ms]

@slundberg ?

[riedgar-ms]

Is the API now more in line with your preferences @slundberg ?

[Harsha-Nori]

API seems fine to me. Seems like a nice set of updates and examples - thanks! Merging.