feat: first pass at guardian io contract subclasses

[AngeloDanducci]

Pull Request

Issue

Fixes #1332

Description

Adds io contract subclasses, adapter constants, and utilizes these via existing call sites in guardian.py

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

[psschwei]

if this is deprecated, do we need to update or should we just leave alone?

[AngeloDanducci]

Yes, even though we're testing deprecation since we updated the signature on in guardian.py we will fail 6/8 tests with TypeErrors unless we update the def fake_call_intrinsic function.

[ajbozarth]

Some feedback from Claude — follow-ups inline.

One non-blocking flag on the PR description (transient, so just checking intent): the "100% coverage" checkbox and the issue's "19 tests unchanged" criterion don't match the final state — guardian.py is at 98.51%, and test_guardian_documents.py is 17 tests after the XOR cases moved into the contract tests. Did you mean to leave those as-is?

[ajbozarth]

LGTM, but I'd defer final approval to others who've spent more time in the guardian code

[AngeloDanducci]

I'll give Jake a day to add his 2C, otherwise can merge and iterate later if need be.

[psschwei]

I assume this is true:

matching the output schema documented in the HF README for each adapter

but would be confirm in the PR body

[psschwei]

General comment / observation : in this PR we're implementing one contract class per intrinsic, whereas in #1321 they were more generic (for dict and list return types). My gut instinct is that it's probably better to be a little more generic if possible, but I'll also tag in @jakelorocco for his opinion.

[jakelorocco]

Yeah; I'm not quite certain how I feel about the super specific ones. I'm fine starting out this way but we may need to relax things in the future. Ultimately, we do have to specify this somewhere.