SurveyJS Python Backend Integration with FastAPI /

Extract Responses from Documents

MIT AI Provider Required

Extract Responses from Documents

Extract answers from completed work orders using a predefined form schema. Review the extracted answers alongside the source document, correct any mistakes, and save the response.

Documentation

Try this

  1. Press Use the sample scan to extract answers from a completed work order.
  2. To try your own work order, press Download blank work order and complete the PDF, or print it and fill it in by hand. Choose Upload completed work order to upload the PDF or a scan or photo. PDF, PNG, JPEG, WebP, and GIF files up to 5 MB are supported.
  3. Compare the answers with the document preview and correct any mistakes. Low-confidence answers are marked Review this answer; blank fields remain unanswered.
  4. Select I have reviewed these answers, then press Save reviewed response. Extraction creates a draft; saving sends the reviewed answers to your backend and confirms the response ID.
  5. If extraction is unavailable, enter the answers directly in the form. Press Start over to clear the draft or cancel extraction.

OpenAI and Anthropic configurations send the document to that provider for extraction. Ollama processes it on the configured Ollama server.

Running main@5b404b3

    No requests

      What the server stored

      Source file
      Document ID
      Answers to review

      Review the draft before submitting.

      Source document · Open document

      Uploaded work order
      JSON definition · shared/definitions/extract-from-paper.json View on GitHub
      {
        "title": "Work order",
        "description": "Completed on paper by the technician and scanned at the office",
        "elements": [
          {
            "type": "text",
            "name": "customer_name",
            "title": "Customer name"
          },
          {
            "type": "text",
            "name": "site_address",
            "title": "Site address"
          },
          {
            "type": "text",
            "name": "visit_date",
            "title": "Visit date",
            "inputType": "date"
          },
          {
            "type": "radiogroup",
            "name": "work_type",
            "title": "Type of work",
            "choices": [
              {
                "value": "installation",
                "text": "Installation"
              },
              {
                "value": "repair",
                "text": "Repair"
              },
              {
                "value": "inspection",
                "text": "Inspection"
              }
            ]
          },
          {
            "type": "checkbox",
            "name": "parts",
            "title": "Parts replaced",
            "choices": [
              {
                "value": "filter",
                "text": "Filter"
              },
              {
                "value": "valve",
                "text": "Valve"
              },
              {
                "value": "pump",
                "text": "Pump"
              },
              {
                "value": "sensor",
                "text": "Sensor"
              }
            ]
          },
          {
            "type": "text",
            "name": "hours",
            "title": "Hours on site",
            "inputType": "number"
          },
          {
            "type": "boolean",
            "name": "resolved",
            "title": "Issue resolved"
          },
          {
            "type": "text",
            "name": "technician",
            "title": "Technician"
          },
          {
            "type": "comment",
            "name": "notes",
            "title": "Notes"
          }
        ]
      }
      Client · shared/client/extract-from-paper.js · sjs:extract-from-paper.client View on GitHub
      // Extract a draft without saving it and validate the response before replacing any answers
      async function extract(file, signal) {
        const body = new FormData();
        body.append("scan", file);
        const response = await fetch("/api/work-orders/extract", { method: "POST", body, signal });
        if (!response.ok) throw await responseError(response, "Couldn't extract the answers. Try again or enter the answers directly in the form.");
        const result = await response.json();
        if (!result.answers || typeof result.answers !== "object" || Array.isArray(result.answers) || !Array.isArray(result.confidence)) {
          throw new Error("The extraction result couldn't be read. Try again or enter the answers directly in the form.");
        }
        return result;
      }
      Client · shared/client/extract-from-paper.js · sjs:extract-from-paper.save View on GitHub
      // Save only after human review and confirm the response ID returned by the backend
      survey.onComplete.add(async (sender, options) => {
        lock(true, true);
        sender.completedHtml = "<h3>Saving the reviewed response...</h3>";
        options.showSaveInProgress();
        try {
          const data = Object.fromEntries(sender.getAllQuestions()
            .filter(q => q !== reviewed).map(q => [q.valueName || q.name, q.isEmpty() ? null : q.value]));
          const response = await fetch("/api/responses", {
            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ formId: "work-order", data })
          });
          if (!response.ok) throw await responseError(response, "Couldn't save the reviewed response. Please try again.");
          const { id } = await response.json();
          if (!Number.isInteger(id) || id < 1) throw new Error("The server didn't confirm a saved response. Please try again.");
          setStoredQuery({ id });
          sender.completedHtml = `<h3>The reviewed response has been saved.</h3><p>Response ID: ${id}</p>`;
          showStatus(`Reviewed response #${id} saved.`);
          options.showSaveSuccess();
        } catch (error) {
          sender.completedHtml = "<h3>The reviewed response hasn't been saved.</h3>";
          options.showSaveError(error instanceof TypeError ? "Couldn't save the reviewed response. Please try again." : error.message);
        } finally { lock(false); }
      });
      Server · app/routes/extract_from_paper.py · sjs:extract-from-paper.template View on GitHub
      # Generate a blank, fillable PDF using the same schema as extraction
      @router.get("/api/work-orders/blank.pdf")
      async def blank_work_order(db: Db, surveyjs: SurveyJs) -> Response:
          form = db.execute("SELECT json FROM forms WHERE key = 'work-order'").fetchone()
          if form is None:
              raise HTTPException(404, "Unknown work order form")
          pdf = await surveyjs.post("/pdf", {"schema": json.loads(form["json"])}, timeout=60)
          if (pdf.status_code != 200 or not pdf.headers.get("content-type", "").startswith("application/pdf")
                  or not pdf.content.startswith(b"%PDF-")):
              surveyjs.unexpected("/pdf", pdf)
      
          return Response(pdf.content, media_type="application/pdf", headers={
              "Content-Disposition": 'attachment; filename="work-order.pdf"', "Cache-Control": "private, no-store"})
      Server · app/routes/extract_from_paper.py · sjs:extract-from-paper.server View on GitHub
      # POST /api/work-orders/extract — send the uploaded scan to the SurveyJS service; return a draft response
      @router.post("/api/work-orders/extract")
      async def extract_work_order(db: Db, surveyjs: SurveyJs, scan: Annotated[UploadFile | str | None, File()] = None) -> Any:
          if scan is None:
              raise HTTPException(400, 'Upload the scan in a field named "scan"')
          if isinstance(scan, str) or len(raw := await scan.read(MAX_BYTES + 1)) > MAX_BYTES:   # a text field isn't a file
              raise HTTPException(413, "The scan must be a file of 5 MB or less")
          if detect_type(raw) is None:   # by the first bytes, never the client's Content-Type
              raise HTTPException(400, "The file is not a PDF, PNG, JPEG, WebP or GIF document")
          schema = json.loads(db.execute("SELECT json FROM forms WHERE key = 'work-order'").fetchone()["json"])
          out = await surveyjs.post("/extract", {"schema": schema, "document": base64.b64encode(raw).decode()}, timeout=120)
          result: Any = None
          with suppress(ValueError):   # JSON with base64 went out, not multipart; an answer that isn't JSON fails closed
              result = json.loads(out.content)
          match out.status_code, result:   # nothing is saved: a person reviews the draft
              case 200, {"data": dict() as answers}:
                  return {"answers": answers, "confidence": result.get("confidence", []), "uniqueId": result.get("uniqueId")}
              case 400, {"error": "INVALID_DOCUMENT"}:
                  raise HTTPException(400, "The file is not a PDF, PNG, JPEG, WebP or GIF document")
              case 503, {"error": "AI_NOT_CONFIGURED"}:
                  raise HTTPException(503, "The SurveyJS service has no AI provider configured")
              case 502, {"error": "EXTRACTION_FAILED"}:
                  raise HTTPException(502, "Could not extract the response from the document")
          surveyjs.unexpected("/extract", out, log_body=False)   # fail closed, logged by status only