Two builds for the SuperDocs engineer round — Priyanshu Semwal

use-cases/Priyanshu2425/.gitignore

@@ -0,0 +1,9 @@
+# Build artefacts from running the two projects in this folder. Kept here
+# rather than at the repository root, because CONTRIBUTING.md asks each builder
+# to change nothing outside their own folder.
+__pycache__/
+*.pyc
+.pytest_cache/
+node_modules/
+*.tsbuildinfo
+.DS_Store

use-cases/Priyanshu2425/quota-aware-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Priyanshu Semwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

use-cases/Priyanshu2425/quota-aware-agent/backend/demo.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Run the agent. With no key it runs against a documented fake, so a reviewer
+can see the behaviour without spending an operation.
+
+    python3 backend/demo.py                     # offline, against the fake
+    python3 backend/demo.py --scenario tight    # not enough allowance, it degrades
+    python3 backend/demo.py --scenario broke    # no allowance, it refuses to start
+    python3 backend/demo.py --live              # real API, needs SUPERDOCS_API_KEY
+
+    --sample N    small-sample mode: run at most N steps
+    --receipt     print the line items and whether they add up
+    --refuse      refuse a partial run rather than deliver a subset
+    --ledger F    keep the operation ledger in F, so running twice shows what
+                  a rerun after a crash does NOT pay for a second time
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+# The offline demo answers with `tests/fake.py`, the same fake the suite uses,
+# so what a reviewer watches here is what the tests assert. That lives beside
+# this package rather than inside it, so the project root goes on the path --
+# the alternative is a second fake, and a fake nobody wrote cannot flatter the
+# code that calls it.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from quota_aware_agent.policy import Policy, WhenItDoesNotFit
+from quota_aware_agent import QuotaAwareAgent, Step, SuperDocsClient
+from quota_aware_agent.client import HttpTransport
+from quota_aware_agent.idempotency import OperationLedger
+
+WORK = [
+    Step("figures", "Correct the revenue figures in the summary table.", 25, "critical"),
+    Step("dates",   "Fix the effective dates in section 3.",             25, "high"),
+    Step("terms",   "Align the defined terms with the glossary.",        25, "medium"),
+    Step("footer",  "Tidy the footer and page numbering.",               25, "low"),
+]
+
+SCENARIOS = {"roomy": 500, "tight": 3, "broke": 1}
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--scenario", choices=sorted(SCENARIOS), default="roomy")
+    p.add_argument("--live", action="store_true", help="use the real API")
+    p.add_argument("--sample", type=int, default=None, help="run at most N steps")
+    # HTML content, so an HTML name. SuperDocs picks its parser from the
+    # extension, so "contract.docx" holding HTML is a 400 on a live run.
+    p.add_argument("--file", default="contract.html")
+    p.add_argument("--receipt", action="store_true",
+                   help="print the line items and whether they add up")
+    p.add_argument("--refuse", action="store_true",
+                   help="refuse a partial run rather than deliver a subset")
+    p.add_argument("--ledger", default=None,
+                   help="keep the operation ledger in this file, so a second "
+                        "run sees what the first one paid for")
+    a = p.parse_args(argv)
+
+    if a.live:
+        key = os.environ.get("SUPERDOCS_API_KEY")
+        if not key:
+            print("SUPERDOCS_API_KEY is not set. Run without --live to use the fake.",
+                  file=sys.stderr)
+            return 2
+        transport = HttpTransport(key)
+        sleep = None
+        print("Running against the real API. Operations will be billed.\n")
+    else:
+        from tests.fake import FakeSuperDocs
+        transport = FakeSuperDocs(remaining=SCENARIOS[a.scenario])
+        sleep = lambda s: None
+        print(f"Offline demo, scenario '{a.scenario}': "
+              f"{SCENARIOS[a.scenario]} operation(s) of allowance. Nothing is billed.\n")
+
+    client = SuperDocsClient(transport, **({"sleep": sleep} if sleep else {}))
+    policy = Policy(
+        reserve=1, max_steps=a.sample,
+        when_it_does_not_fit=(WhenItDoesNotFit.REFUSE if a.refuse
+                              else WhenItDoesNotFit.DEGRADE),
+    )
+    agent = QuotaAwareAgent(client, policy=policy,
+                            ledger=OperationLedger(a.ledger) if a.ledger else None)
+
+    content = b"<h1>Quarterly report</h1><p>...</p>"
+    report = agent.run("demo-session", a.file, content, WORK)
+
+    print(report.plain_language())
+    print()
+    print(f"  planned:   {report.planned or '-'}")
+    print(f"  completed: {report.completed or '-'}")
+    print(f"  deferred:  {report.deferred or '-'}")
+    print(f"  stopped:   {report.stop_reason.value}")
+    if a.receipt:
+        print()
+        print(report.receipt.render_text(report.balance_at_start,
+                                         report.balance_at_end))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

use-cases/Priyanshu2425/quota-aware-agent/backend/quota_aware_agent/__init__.py

@@ -0,0 +1,9 @@
+from .agent import QuotaAwareAgent, Report, Step
+from .budget import Balance, BudgetGuard, Change, Plan, estimate
+from .client import HttpTransport, QuotaExhausted, SuperDocsClient, parse_proposed_changes
+
+__all__ = [
+    "QuotaAwareAgent", "Report", "Step",
+    "Balance", "BudgetGuard", "Change", "Plan", "estimate",
+    "HttpTransport", "QuotaExhausted", "SuperDocsClient", "parse_proposed_changes",
+]