{"cells":[{"cell_type":"markdown","metadata":{},"source":["# Quanta API quick start\n","Open in Jupyter or upload this file using Google Colab's File menu. Install `requests` if needed.\n","Without `engine`, a request is graded by `maths_reasoning`, the two-letter maths grading. Set `engine` to grade a final answer (`exact_match`, `fuzzy_match`) or against your own rubric (`rubric_additive`, `rubric_custom`); see Grading Engines in the docs.\n","**Run All does not submit paid reviews.** Enable only named examples you intend to pay for. There is no enforced dollar cap on a review; input size and economy mode do not guarantee a maximum bill. Do not enable examples when you require a hard budget cap.\n","The health check is public; authenticated reads and grading require an API key from [API Keys](https://api.quanta.world/api-keys)."]},{"cell_type":"code","metadata":{},"source":["import csv\n","import io\n","import json\n","import os\n","import time\n","from pathlib import Path\n","import requests\n","\n","BASE_URL = \"https://api.quanta.world\"\n","API_KEY = os.environ.get(\"QUANTA_API_KEY\", \"\")\n","# To enter a key privately: import getpass; API_KEY = getpass.getpass(\"API key: \")\n","PAID_EXAMPLES = set()  # Example: {\"text\"}; each named example sends one billed request.\n","RUN_BULK_REVIEW = False\n","\n","def object_value(value):\n","    if isinstance(value, str):\n","        try:\n","            value = json.loads(value)\n","        except (ValueError, TypeError):\n","            return {}\n","    return value if isinstance(value, dict) else {}\n","\n","def api_request(method, path, *, authenticated=True, **kwargs):\n","    headers = dict(kwargs.pop(\"headers\", {}))\n","    if authenticated:\n","        if not API_KEY:\n","            raise RuntimeError(\"Set QUANTA_API_KEY or enter API_KEY privately first.\")\n","        headers[\"Authorization\"] = f\"Bearer {API_KEY}\"\n","    try:\n","        review_path = path.split(\"?\", 1)[0].rstrip(\"/\")\n","        synchronous_review = method.upper() == \"POST\" and review_path in {\"/api/review\", \"/api-portal/api/review\"}\n","        read_timeout = 840 if synchronous_review else 180\n","        response = requests.request(method, f\"{BASE_URL}{path}\", headers=headers, timeout=(10, read_timeout), **kwargs)\n","    except requests.RequestException:\n","        raise RuntimeError(\"Request failed or timed out. A submitted review may have been accepted; do not automatically resubmit a paid request.\") from None\n","    if not response.ok:\n","        try:\n","            error = object_value(response.json())\n","        except ValueError:\n","            error = {}\n","        message = error.get(\"message\") or error.get(\"error\") or \"Request failed\"\n","        raise RuntimeError(f\"HTTP {response.status_code}: {message}\")\n","    return response\n","\n","def api_json(method, path, **kwargs):\n","    try:\n","        body = api_request(method, path, **kwargs).json()\n","    except ValueError:\n","        raise RuntimeError(\"API returned invalid JSON.\") from None\n","    if not isinstance(body, dict):\n","        raise RuntimeError(\"API returned an unexpected response shape.\")\n","    return body\n","\n","def run_review(name, payload):\n","    if name not in PAID_EXAMPLES:\n","        print(f\"Skipped paid example: {name}\")\n","        return None\n","    return api_json(\"POST\", \"/api/review\", json=payload)\n","\n","def upload_bulk(csv_bytes):\n","    if not RUN_BULK_REVIEW:\n","        print(\"Skipped paid bulk review\")\n","        return None\n","    body = api_json(\"POST\", \"/api/bulk-review\", files={\"file\": (\"reviews.csv\", csv_bytes, \"text/csv\")})\n","    job_id = object_value(body.get(\"job\")).get(\"id\")\n","    if not isinstance(job_id, str) or not job_id:\n","        raise RuntimeError(\"Upload response has no job.id; inspect the response before submitting again.\")\n","    return job_id\n","\n","def poll_job(job_id, max_polls=60, interval_seconds=5):\n","    for attempt in range(max_polls):\n","        data = api_json(\"GET\", f\"/api/jobs/{job_id}\")\n","        job = object_value(data.get(\"job\"))\n","        if not job or not job.get(\"status\"):\n","            raise RuntimeError(\"Job response has no job status.\")\n","        status = job[\"status\"]\n","        if status == \"completed\":\n","            return data\n","        if status in {\"failed\", \"cancelled\"}:\n","            raise RuntimeError(f\"Job {job_id}: {status}. Inspect history; do not resubmit automatically.\")\n","        if attempt + 1 < max_polls:\n","            time.sleep(interval_seconds)\n","    raise TimeoutError(f\"Polling limit reached for {job_id}. Keep this job ID and check it later; do not resubmit.\")\n","\n","def result_rows(data):\n","    results = data.get(\"results\")\n","    if not isinstance(results, list):\n","        raise RuntimeError(\"Job response has no results list.\")\n","    rows = []\n","    for result in results:\n","        result = object_value(result)\n","        output = object_value(result.get(\"output\"))\n","        model = object_value(output.get(\"model_output\"))\n","        metadata = object_value(output.get(\"metadata\"))\n","        bills = object_value(metadata.get(\"bills\"))\n","        rows.append({\n","            \"index\": result.get(\"index\"), \"status\": result.get(\"status\"),\n","            \"grade\": result.get(\"grade\") or output.get(\"overall_grade\"),\n","            \"feedback_summary\": result.get(\"feedback_summary\") or model.get(\"feedback_summary\") or output.get(\"feedback_summary\"),\n","            \"billed_usd\": bills.get(\"total_bill_usd\"),\n","            \"validity\": json.dumps(model.get(\"validity\") or output.get(\"validity\"), ensure_ascii=False),\n","            \"quality\": json.dumps(model.get(\"quality\") or output.get(\"quality\"), ensure_ascii=False),\n","            \"sanity\": json.dumps(model.get(\"sanity\") or output.get(\"sanity\"), ensure_ascii=False),\n","            \"error_message\": result.get(\"error_message\"),\n","        })\n","    return rows\n","\n","def save_results(data, filename=\"review-results.csv\"):\n","    rows = result_rows(data)\n","    if not rows:\n","        raise RuntimeError(\"No results to export.\")\n","    with Path(filename).open(\"w\", newline=\"\", encoding=\"utf-8\") as output:\n","        writer = csv.DictWriter(output, fieldnames=list(rows[0]))\n","        writer.writeheader()\n","        writer.writerows(rows)\n","    return str(filename)\n","\n","def download_job_export(job_id, filename=\"server-review-results.csv\"):\n","    response = api_request(\"GET\", f\"/api/jobs/{job_id}/export\")\n","    Path(filename).write_bytes(response.content)\n","    return str(filename)"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Free health check"]},{"cell_type":"code","metadata":{},"source":["print(json.dumps(api_json(\"GET\", \"/api/health\", authenticated=False), indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Free example: exact match\n","`exact_match` compares a final answer with no model call and is not charged; it still counts toward the key's daily review limit."]},{"cell_type":"code","metadata":{},"source":["exact_request = {\n","    \"engine\": \"exact_match\",\n","    \"task\": {\"content\": [{\"type\": \"text\", \"text\": \"How many primes are less than 100?\"}], \"final_answer\": \"25\"},\n","    \"input_answer\": \"25\",\n","}\n","if API_KEY:\n","    print(json.dumps(api_json(\"POST\", \"/api/review\", json=exact_request)[\"engine\"], indent=2))\n","else:\n","    print(\"Set API_KEY to run the free exact-match example.\")"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Paid example: text\n","Disabled by default. Add \"text\" to PAID_EXAMPLES only when you intend to pay for this request. Public example images may be hosted on the production asset domain; grading still uses BASE_URL."]},{"cell_type":"code","metadata":{},"source":["text_payload = {\n    \"task\": {\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"How many six-digit numbers contain exactly three zeros in their decimal representation, with the additional constraint that no two zeros are adjacent? Note: numbers do not begin with a zero.\",\n            },\n        ],\n        \"is_context_required\": False,\n        \"context_details\": [],\n        \"correct_solutions\": [\n            {\n                \"slogan\": \"Direct computation\",\n                \"content\": [\n                    {\n                        \"type\": \"text\",\n                        \"text\": r\"\"\"**Answer:** $9^3 = 729$\n\n**Explanation:**\n\n1. Since there are 3 non-adjacent zeros, they have to be in places 2, 4 and 6 counted from the left. I.e. the only way a six-digit number satisfies the condition is if it is of the form $\\overline{a0b0c0}$.\n2. The remaining digits $a, b, c$ are arbitrary with the only condition that none of them is $0$. Therefore the total number of such six-digit numbers is $$9 \\cdot 9 \\cdot 9 = 729.$$\"\"\",\n                    },\n                ],\n            },\n        ],\n    },\n    \"input_solution\": [\n        {\n            \"type\": \"text\",\n            \"text\": r\"\"\"Firstly, there are 9-1=8 possibilities for the first digit since it cannot be zero.\n\nNow, as for the digits in positions 2, 3, 4, 5 and 6 (indexed from the left): since the zeros can't be adjacent, they must be in positions 2, 4 and 6, and for the remaining 5-3=2 we are considering, there are $10 \\cdot 10$ options for which digit they can be (since they can not be 0).\n\nHowever, we counted some of these $8 \\cdot 10 \\cdot 10 = 800$ options twice, specifically the ones where there are non-zeros in positions 3 and 5. Thus, all in all, that gives us $N = 800 - 9 \\cdot 9 = 729$ options.\n\n**Answer:** 729\"\"\",\n        },\n    ],\n    \"reviewing_parameters\": {\n        \"strictness\": \"auto\",\n        \"aux_rubric\": {\n            \"validity\": \"No points should be deducted for the lack of explanation of why zeros must be in positions 2, 4 and 6 (or that non-zeros should be in 1, 3, 5); this is counted as trivial.\",\n            \"quality\": \"This is an easy and short problem, so there is NO need to be too judgemental about the presentation.\",\n        },\n    },\n}\n","text_result = run_review(\"text\", text_payload)\n","if text_result is not None:\n","    print(json.dumps(text_result, indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Paid example: context\n","Disabled by default. Add \"context\" to PAID_EXAMPLES only when you intend to pay for this request. A task with context and an unrelated text submission demonstrates a sanity failure.\n"]},{"cell_type":"code","metadata":{},"source":["context_payload = {\n    \"task\": {\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"Following that other problem, what is the answer if we need '2 or 5' instead of '1 or 4'?\",\n            },\n        ],\n        \"is_context_required\": True,\n        \"context_details\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"'That other problem' refers to: \\\"There is a six-sided die with the numbers 1, 2, …, 6 on its faces. Find the probability of rolling 1 or 4.\\\" So this problem is the same, just with 2 and 5 instead of 1 and 4.\",\n            },\n        ],\n        \"correct_solutions\": [\n            {\n                \"slogan\": \"Direct computation, nothing fancy\",\n                \"content\": [\n                    {\n                        \"type\": \"text\",\n                        \"text\": \"\"\"**Answer:** $1/3$\n\n**Explanation:** There are six possibilities for what one could roll, namely {roll 1, roll 2, roll 3, roll 4, roll 5, roll 6}. Precisely two of them are of interest. Hence the answer is $2/6 = 1/3$.\"\"\",\n                    },\n                ],\n            },\n        ],\n    },\n    \"input_solution\": [\n        {\n            \"type\": \"text\",\n            \"text\": r\"\"\"The area of a circle of radius 3 is $A = \\pi r^2 = 9\\pi$, and its circumference is $2\\pi r = 6\\pi$. So the ratio of area to circumference is $3/2$.\n\n**Answer:** $3/2$\"\"\",\n        },\n    ],\n    \"reviewing_parameters\": {\n        \"strictness\": \"auto\",\n        \"aux_rubric\": {\n            \"validity\": \"-\",\n            \"quality\": \"-\",\n        },\n    },\n}\n","context_result = run_review(\"context\", context_payload)\n","if context_result is not None:\n","    print(json.dumps(context_result, indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Paid example: tiling (with pictures)\n","Disabled by default. Add \"tiling\" to PAID_EXAMPLES only when you intend to pay for this request.\n"]},{"cell_type":"code","metadata":{},"source":["tiling_payload = {\n    \"task\": {\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"Is it possible to form a square out of exactly 100 T-shaped pieces like the one below, each made of four unit squares?\",\n            },\n            {\n                \"type\": \"image_url\",\n                \"image_url\": {\n                    \"url\": \"https://ujngnciigcpczmsloboz.supabase.co/storage/v1/object/public/quanta-public/api/quick-start/t-tetromino.png\",\n                },\n            },\n        ],\n        \"is_context_required\": False,\n        \"context_details\": [],\n        \"correct_solutions\": [\n            {\n                \"slogan\": \"Construction with repetition\",\n                \"content\": [\n                    {\n                        \"type\": \"text\",\n                        \"text\": r\"\"\"**Answer:** Yes, it is possible.\n\n**Explanation:**\n\n1. Four of these pieces form a $4 \\times 4$ square, as shown below:\"\"\",\n                    },\n                    {\n                        \"type\": \"image_url\",\n                        \"image_url\": {\n                            \"url\": \"https://ujngnciigcpczmsloboz.supabase.co/storage/v1/object/public/quanta-public/api/quick-start/t-tetromino-4x4-split.png\",\n                        },\n                    },\n                    {\n                        \"type\": \"text\",\n                        \"text\": r\"2. Arranging 25 such $4 \\times 4$ squares in a $5 \\times 5$ grid gives a $20 \\times 20$ square made of $4 \\cdot 25 = 100$ pieces, as required.\",\n                    },\n                ],\n            },\n        ],\n    },\n    \"input_solution\": [\n        {\n            \"type\": \"text\",\n            \"text\": r\"\"\"100 pieces cover $400$ unit squares, so the square we are after is $20 \\times 20$. Split it into $25$ squares of size $4 \\times 4$.\n\nFour T-pieces tile one $4 \\times 4$ square, as in the picture below. Doing this in all 25 small squares uses $25 \\cdot 4 = 100$ pieces, so the answer is **yes**.\"\"\",\n        },\n        {\n            \"type\": \"image_url\",\n            \"image_url\": {\n                \"url\": \"https://ujngnciigcpczmsloboz.supabase.co/storage/v1/object/public/quanta-public/api/quick-start/t-tetromino-4x4-student-tiling.png\",\n            },\n        },\n    ],\n    \"reviewing_parameters\": {\n        \"strictness\": \"lenient\",\n        \"aux_rubric\": {\n            \"validity\": \"-\",\n            \"quality\": \"-\",\n        },\n    },\n}\n","tiling_result = run_review(\"tiling\", tiling_payload)\n","if tiling_result is not None:\n","    print(json.dumps(tiling_result, indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Paid example: handwriting\n","Disabled by default. Add \"handwriting\" to PAID_EXAMPLES only when you intend to pay for this request. Public example images may be hosted on the production asset domain; grading still uses BASE_URL."]},{"cell_type":"code","metadata":{},"source":["handwriting_payload = {\n    \"task\": {\n        \"content\": [\n            {\n                \"type\": \"text\",\n                \"text\": \"Lazy Ania has divided the (closed) interval AB into 20 identical (closed) intervals and called each of them a **big** one, whereas diligent Tony has divided the same interval into 2019 identical (closed) intervals and called each of them a **small** one. Let's call a small interval **good** if it lies fully inside one of the big intervals. How many good intervals are there?\",\n            },\n        ],\n        \"is_context_required\": False,\n        \"context_details\": [],\n        \"correct_solutions\": [\n            {\n                \"slogan\": \"Direct computation, nothing fancy\",\n                \"content\": [\n                    {\n                        \"type\": \"text\",\n                        \"text\": r\"\"\"**Answer:** 2000\n\n**Explanation:**\n\n1. A small interval is not good if at least one endpoint of a big interval lies strictly inside it. Every endpoint of a big interval, except $A$ and $B$, lies inside exactly one small interval. Therefore there are 19 small intervals which are not good, and the answer is $2019 - 19 = 2000$.\n2. Remark: the argument relies on no endpoint of a big interval (other than $A$ and $B$) coinciding with an endpoint of a small one. If the $k$-th endpoint from the left of a big interval were the $m$-th endpoint of a small one, then $k \\cdot AB/20 = m \\cdot AB/2019$, i.e. $2019k = 20m$. Since $20$ and $2019$ are coprime, $20 \\mid k$, so $k = 20$ and the point is $B$.\"\"\",\n                    },\n                ],\n            },\n        ],\n    },\n    \"input_solution\": [\n        {\n            \"type\": \"image_url\",\n            \"image_url\": {\n                \"url\": \"https://ujngnciigcpczmsloboz.supabase.co/storage/v1/object/public/quanta-public/api/quick-start/handwritten-intervals-solution-photo.jpeg\",\n            },\n        },\n    ],\n    \"reviewing_parameters\": {\n        \"strictness\": \"auto\",\n        \"cost_efficiency_mode\": \"standard\",\n        \"aux_rubric\": {\n            \"validity\": \"It is important to prove that none of the endpoints of big and small intervals coincide. If this is not proven, the grade can be at most B (if everything else is perfect).\",\n            \"quality\": \"-\",\n        },\n    },\n}\n","handwriting_result = run_review(\"handwriting\", handwriting_payload)\n","if handwriting_result is not None:\n","    print(json.dumps(handwriting_result, indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Paid bulk review: one row\n","Set RUN_BULK_REVIEW=True only if you intend to pay for the entire review. No external sheet is loaded. Polling stops after 60 reads, waits 5 seconds between attempts, and every HTTP request has a timeout. A network timeout after submitting is not permission to retry."]},{"cell_type":"code","metadata":{},"source":["csv_buffer = io.StringIO()\n","writer = csv.DictWriter(csv_buffer, fieldnames=[\"task.content\", \"task.correct_solutions\", \"task.is_context_required\", \"input_solution\"])\n","writer.writeheader()\n","writer.writerow({\"task.content\": json.dumps(text_payload[\"task\"][\"content\"]), \"task.correct_solutions\": json.dumps(text_payload[\"task\"][\"correct_solutions\"]), \"task.is_context_required\": \"FALSE\", \"input_solution\": json.dumps(text_payload[\"input_solution\"])})\n","job_id = None\n","data = None\n","job_id = upload_bulk(csv_buffer.getvalue().encode(\"utf-8\"))\n","if job_id:\n","    print(f\"Keep job ID: {job_id}\")\n","    data = poll_job(job_id)\n","    print(json.dumps(result_rows(data), indent=2))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{},"source":["## Export completed results\n","billed_usd comes from public metadata.bills.total_bill_usd. Missing billing information stays empty; private provider costs are never treated as the customer bill. These reads do not submit grading."]},{"cell_type":"code","metadata":{},"source":["if data is not None and job_id:\n","    print(save_results(data))\n","    print(download_job_export(job_id))\n","else:\n","    print(\"No completed bulk job in this run. Use an existing job ID to poll and export without creating another review.\")"],"execution_count":null,"outputs":[]}],"metadata":{"kernelspec":{"display_name":"Python 3","language":"python","name":"python3"},"language_info":{"name":"python","version":"3"}},"nbformat":4,"nbformat_minor":4}