Framework-agnostic SuperDocs agent adapter + 3 quickstarts — Vrutansh Patel

[vrutansh]

What this adds

A framework-agnostic Python adapter for SuperDocs with thin native bindings and comparable quickstarts for:

• LangGraph
• CrewAI
• OpenAI Agents SDK

All three execute the same document-editing task through one maintained core and return the same canonical output.

Design

The framework-independent core owns:

• Document upload
• Asynchronous chat and compact polling
• Proposed-change parsing
• Explicit approval
• Export
• Large-file streaming uploads
• Crash-safe checkpoints and resumable execution

Framework bindings only translate the portable tool specification into each framework’s native shape. The core imports no agent framework.

Reliability

• Atomic checkpoints persist session, job, phase, and approved change IDs.
• Re-entry resumes the existing job instead of repeating a costly edit.
• Completed runs repeat only export.
• The session job history closes the crash window between starting an edit and saving its job ID.
• Proposed-change content receives the documented second JSON parse; completed results remain objects.
• Slow operations remain resumable and produce progress updates instead of being treated as crashes.
• Files above 20 MiB use the pre-signed streaming upload flow.
• Credentials and document content never enter checkpoints.

Verification

• 31 offline tests passing
• 90.91% branch coverage
• Ruff lint and formatting checks passing
• Wheel and source distribution build successfully
• Clean-copy install, test, and build verified
• Live output parity verified across all three frameworks on Windows/Python 3.12.10
• Final hardened live parity run: 70.93 seconds

The live parity test is explicitly opt-in and limited to three edits per run.

Assignment checklist

• Framework-independent core
• Three native framework quickstarts
• Identical output for the same task
• Clean-clone execution
• Documented fourth-binding process
• Hosted MCP versus wrapper guidance
• Versioned v0.1.0 release
• Upload, chat, approval, and export contract
• Screenshot and reproducible verification commands

Review-policy note

The comparison quickstarts retrieve proposed changes and auto-approve them so unattended framework outputs remain comparable. Applications requiring human decisions can use the lower-level job and approval methods to present every proposal before applying it.

Release

v0.1.0 release and distribution artifacts

Scope

Every changed file is contained within:

extensions/vrutansh/superdocs-agent-adapter/