Two builds for the SuperDocs engineer round — Priyanshu Semwal - #124
Open
Priyanshu2425 wants to merge 7 commits into
Open
Two builds for the SuperDocs engineer round — Priyanshu Semwal#124Priyanshu2425 wants to merge 7 commits into
Priyanshu2425 wants to merge 7 commits into
Conversation
use-cases/Priyanshu2425/quota-aware-agent — an agent that reads its remaining allowance before it plans, sizes the work to fit, and degrades in plain language instead of dying halfway through someone's document. MCP server, three tools, offline test suite. use-cases/Priyanshu2425/word-doc-repair — Salvage. A .docx that will not open, opened the way Word will not: what survives is recovered, a valid file is rebuilt around it, and what did not come back is named. It never claims a complete repair, and a test fails the build if it ever does. Both run offline with no key. The SuperDocs path is an optional second pass in each, and every failure on it degrades back to the local result. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The reuse of budget.py and of the SuperDocs client between the two projects is still stated plainly — reuse is only a shortcut when it is hidden — without naming a repository that is not public. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Layout only. Both projects still run offline with no key, and both suites pass from inside this repository: quota-aware-agent 50, word-doc-repair 55. PYTHONPATH is gone from every documented command — each pyproject declares its own pytest pythonpath, so `python3 -m pytest` needs no env var and no install. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ive API Per-request pricing was the headline one. estimate() pooled a plan's sections and divided by 25 -- correct for a publisher sending one request, wrong for an agent sending one per step. Four five-section edits quoted one operation and billed four, so the agent reported 'it fits', started, and ran out partway through the document: the exact failure this build exists to prevent, arriving through its own arithmetic. estimate(changes, batched=...) now makes the question explicit and QuotaAwareAgent.BATCHED answers it once, so the planner and the executor cannot drift. Also fixed: - a call that timed out was recorded FAILED, hence repeatable, so a rerun would have paid for it again. provably_never_sent() marks only a refused connection, a DNS failure or a 4xx as unbilled; everything else stays IN_FLIGHT and is reported to a person. - an exhausted allowance raised on the free export, breaking the one guarantee the reserve is sold on. Free calls now record the signal without refusing. - plan_work had no ledger, so it quoted full price for work run_work would skip. settled() is now the single answer both paths use. - resolve_operation added: a started-and-unconfirmed step was correctly never retried and could never be resolved through the MCP surface -- a state the surface could enter and not leave. - a rerun of finished work reported 'nothing fits', naming a resource failure as the cause of a success. - document_base64 added; the surface could previously only take HTML text. - when_it_does_not_fit=refuse was tested and unreachable from the surface. - the test proving the server starts pointed PYTHONPATH at the project root, not backend/, so it passed only where the package was already installed. Found by running live: SuperDocs picks its parser from the filename extension, so HTML sent as contract.docx is a 400 about zip files -- and contract.docx was this demo's own default. check_upload_name refuses the mismatch before sending, including the .txt case that would otherwise succeed and parse markup as text, and tests/fake.py now models the 400. 71 tests offline with no key; 69 in a clean venv with the MCP SDK and the package uninstalled, the protocol test driving a real stdio client. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…it returns
The card is banded S2 · API + export and asks for a clean, styled file. The
four-call contract was written, tested and working -- and reachable only through
`cli.py --via-superdocs` behind an environment variable. The page the README
calls "the product" never touched SuperDocs. That is the third appearance of one
shape in this workspace: a capability present in the code and unreachable from
the surface a person uses.
- POST /api/style/{token} runs the four calls and streams them as NDJSON, the
same wire shape as the repair, because it is the same situation: something
slow is happening to a person's document and they are entitled to watch it.
- GET /api/capabilities is asked before anything is offered, so a step this copy
of the page cannot take is one sentence rather than a button that fails when
pressed -- and the sentence says what is not affected.
- The styled copy is a second file, offered only after the plain one is already
downloadable, never automatic, and both downloads stay on screen together.
- The allowance is read before the first billable call. A balance that cannot be
read is not treated as a balance of zero: /v1/agents/whoami answers agent keys,
and refusing on a number nobody managed to read would be its own bluff.
Then the first live run came back with 199 words that were not sent: three
invented paragraphs, a totals block, a disclaimer, a signature block, a
confidentiality footer. It opened cleanly and read better than the plain
rebuild, which is why it is the worst output this product can produce -- its
owner would have no reason to doubt it. The instruction was tightened to forbid
additions by name, and content_drift() now compares the words that came back
against the words that went out and discards the file on any difference at all.
The re-run came back identical and was accepted. The instruction is the request;
the guard is the promise.
Also: the .doc refusal told people to open the file in Word, which is the thing
they cannot do; it now says what to do when Word will not open it either.
63 offline tests (was 55), 76 with the web extra, 46 frontend tests (was 36).
Verified live twice against the real API, including the approval gate.
manual-test/MANUAL_QA_PLAN.html and manual-test/UI_FLOWS.html record what was
actually run and mark eight judgement calls as not run rather than as passed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… 1 skipped Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Clone, two commands, no key and no install -- there are no runtime dependencies, which is why that works on a bare clone. Adds the environment table with placeholders, a claim-to-command table so every behaviour the README asserts names the command that demonstrates it, and the SuperDocs surfaces this build uses, which CONTRIBUTING asks for and the README only implied. Every command in it was executed before it was written down. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Priyanshu Semwal (@Priyanshu2425)
Two builds for the SuperDocs engineer round, both under
use-cases/Priyanshu2425/. One pull request covering the round, per CONTRIBUTING.quota-aware-agent— band S1 · MCPAn agent that reads its remaining SuperDocs allowance before it plans, sizes the work to fit, and when it does not fit it degrades and says so in a sentence a person can read — instead of starting a job it cannot finish and dying halfway through someone's document.
The problem it takes seriously: an API-key agent cannot poll its balance.
/v1/users/me/usageand/limitsrejectsk_keys with a401— I checked that live rather than taking it from the docs. So the balance is authoritative atwhoamiand after each response, and an estimate in between, and every number this build prints says which kind it is. Confirmed and estimated figures are never added together.Four MCP tools —
check_allowance,plan_work,run_work,resolve_operation— of which onlyrun_workcosts anything. Every result carries abudgetblock so a calling agent never has to spend a turn asking what is left. An operation ledger keeps a rerun after a crash from paying twice for work already in the document, and a call that was sent but whose outcome was never learned is neither repeated nor forgotten — it is reported, because retrying might be charged twice and skipping might leave the work undone.word-doc-repair— band S2 · API + exportA consumer-facing repair tool for a DOCX that will not open cleanly: re-ingest the damaged file, normalise what structure can be recovered, export a clean styled file, and tell the user plainly what was recovered. Best-effort by design, and it says so — it never claims a full repair.
Both
MIT licensed, README and screenshot in each folder, built for the SuperDocs task. Tests run offline with no API key and no network, so anything claimed here can be checked without spending an operation.
Two platform findings worth passing on, both hit while building:
POST /v1/documents/uploadpicks its parser from the filename extension, not the bytes. HTML sent asreport.docxreturns400 Invalid DOCX file: File is not a zip file, which names neither the cause nor the fix. The same bytes asreport.htmlare fine.report.txtis accepted and parses the markup as literal text — a silent wrong answer rather than an error.POST /v1/chat/asyncreturned nousageblock on any response, and a completed, approved edit did not move the account's operation count. An integrator trusting the documentedusageblock will build on a number that never arrives.