Upload 4 files

.gitignore

@@ -0,0 +1,18 @@
+# SQLite database files
+jobs.db
+*.db-shm
+*.db-wal
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Environment / secrets
+.env
+.env.*
+
+# Editor
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,29 @@
+# Code Evaluator — Hugging Face Spaces
+#
+# Requirements:
+#   - Non-root user with UID 1000 (HF Spaces security policy)
+#   - Application must listen on port 7860
+#   - /home/user/.local/bin on PATH for pip-installed binaries
+
+FROM python:3.11-slim
+
+# Create the non-root user and /app in a single layer to minimise image size.
+RUN useradd -m -u 1000 -s /bin/bash user \
+    && mkdir -p /app \
+    && chown user:user /app
+
+WORKDIR /app
+
+USER user
+
+ENV PATH="/home/user/.local/bin:${PATH}"
+
+# Copy deps first so Docker cache reuses this layer on source-only changes.
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

main.py

@@ -0,0 +1,353 @@
+# Code Evaluator — Asynchronous Python grading service
+#
+# Flow:
+#   POST /submit  → inserts "Processing" row, enqueues background LLM call,
+#                   returns {job_id, status} immediately.
+#   GET  /report  → returns current row state (Processing / Completed / Failed).
+
+import json
+import logging
+import os
+import sqlite3
+import uuid
+from contextlib import asynccontextmanager, contextmanager
+
+from fastapi import BackgroundTasks, Depends, FastAPI, File, Header, HTTPException, UploadFile
+from fastapi.responses import JSONResponse
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-8s  %(name)s — %(message)s",
+    datefmt="%Y-%m-%dT%H:%M:%S",
+)
+logger = logging.getLogger("code_evaluator")
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+# Shared key distributed to consuming services via the X-API-Key header.
+# Set the CUSTOM_API_KEY environment secret in your deployment dashboard.
+# The server refuses to start if this is missing — no silent fallback.
+YOUR_CUSTOM_API_KEY: str | None = os.getenv("CUSTOM_API_KEY")
+if not YOUR_CUSTOM_API_KEY:
+    raise RuntimeError(
+        "CUSTOM_API_KEY environment secret is not set. "
+        "Add it to your deployment secrets and restart."
+    )
+
+# LLM provider API key — set as an environment secret, never hardcoded.
+HUGGINGFACE_API_KEY: str | None = os.getenv("HUGGINGFACE_API_KEY")
+
+if not HUGGINGFACE_API_KEY:
+    logger.warning(
+        "HUGGINGFACE_API_KEY is not set. "
+        "All /submit requests will fail during LLM inference. "
+        "Add the secret in your deployment environment and restart."
+    )
+
+# AsyncOpenAI client pointed at the HuggingFace OpenAI-compatible gateway.
+# Swap base_url and api_key env var to switch providers (e.g. OpenRouter)
+# without touching any other part of the code.
+openai_client = AsyncOpenAI(
+    api_key=HUGGINGFACE_API_KEY or "missing-key",
+    base_url="https://api-inference.huggingface.co/v1/",
+)
+
+MODEL_ID: str = "Qwen/Qwen2.5-Coder-32B-Instruct"
+
+# ---------------------------------------------------------------------------
+# Database
+# ---------------------------------------------------------------------------
+
+DB_PATH: str = os.getenv("DB_PATH", "jobs.db")
+
+logger.info("Database path: %s", DB_PATH)
+
+
+@contextmanager
+def get_db_connection():
+    """
+    Yield a thread-safe SQLite connection and guarantee closure on exit.
+
+    check_same_thread=False is required because FastAPI's async event loop
+    may dispatch sync I/O across threads; operations here are short and safe.
+    """
+    conn: sqlite3.Connection | None = None
+    try:
+        conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        yield conn
+    finally:
+        if conn is not None:
+            conn.close()
+
+
+def init_db() -> None:
+    """Create the evaluations table if it does not already exist."""
+    logger.info("Initialising database schema …")
+    with get_db_connection() as conn:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS evaluations (
+                job_id  TEXT PRIMARY KEY,
+                status  TEXT NOT NULL,
+                report  TEXT
+            )
+            """
+        )
+        conn.commit()
+    logger.info("Database ready.")
+
+
+def db_create_job(job_id: str) -> None:
+    """Insert a new evaluation row with status 'Processing'."""
+    with get_db_connection() as conn:
+        conn.execute(
+            "INSERT INTO evaluations (job_id, status, report) VALUES (?, ?, ?)",
+            (job_id, "Processing", None),
+        )
+        conn.commit()
+    logger.info("[%s] Job created → status=Processing.", job_id)
+
+
+def db_update_job(job_id: str, status: str, report: str) -> None:
+    """Update the status and report columns for the given job_id."""
+    with get_db_connection() as conn:
+        conn.execute(
+            "UPDATE evaluations SET status = ?, report = ? WHERE job_id = ?",
+            (status, report, job_id),
+        )
+        conn.commit()
+    logger.info("[%s] Job updated → status=%s.", job_id, status)
+
+
+def db_get_job(job_id: str) -> sqlite3.Row | None:
+    """Return the evaluation row for job_id, or None if not found."""
+    with get_db_connection() as conn:
+        cursor = conn.execute(
+            "SELECT job_id, status, report FROM evaluations WHERE job_id = ?",
+            (job_id,),
+        )
+        return cursor.fetchone()
+
+
+# ---------------------------------------------------------------------------
+# Background Worker
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT: str = (
+    "You are an unyielding, expert Python code auditor. Your sole responsibility "
+    "is to evaluate student-submitted Python scripts and produce a precise, "
+    "objective, and actionable grading report.\n\n"
+    "CRITICAL OUTPUT CONTRACT:\n"
+    "- Respond with ONLY a raw JSON object. No Markdown fences, no prose, "
+    "no preamble, no trailing commentary.\n"
+    "- The JSON object MUST contain exactly these three keys:\n"
+    '  1. "score"      (integer, 0–100): Overall benchmark score reflecting '
+    "correctness, efficiency, readability, and best-practice adherence.\n"
+    '  2. "percentage" (float, 0.0–100.0): Execution precision — how accurately '
+    "the code fulfils its apparent intent relative to a flawless implementation.\n"
+    '  3. "mistakes"   (array of strings): Every defect found — architectural '
+    "issues, logical fallacies, syntax bugs, missing optimisations, poor naming, "
+    "security vulnerabilities, or style violations. Each item must name the "
+    "problem and its recommended fix. Return [] if no mistakes are found.\n\n"
+    "SCORING RUBRIC:\n"
+    "  90–100 : Near-perfect — production-ready.\n"
+    "  70–89  : Good — minor issues only.\n"
+    "  50–69  : Adequate — notable defects.\n"
+    "  30–49  : Poor — significant bugs or anti-patterns.\n"
+    "  0–29   : Critical failure — non-functional or trivially wrong.\n\n"
+    "Output the raw JSON object as your entire response. "
+    "Do NOT add any key other than score, percentage, and mistakes."
+)
+
+
+async def process_evaluation(job_id: str, code_text: str) -> None:
+    """
+    Call the LLM to grade code_text and persist the result for job_id.
+
+    On any exception the row is updated to 'Failed' with a serialised error
+    payload — the job can never be stuck in 'Processing' indefinitely.
+    """
+    logger.info("[%s] Background evaluation started.", job_id)
+
+    user_message: str = (
+        "Evaluate the following Python script and return your grading report "
+        "as a raw JSON object exactly as specified in your instructions.\n\n"
+        f"```python\n{code_text}\n```"
+    )
+
+    try:
+        logger.info("[%s] Calling LLM (model=%s) …", job_id, MODEL_ID)
+
+        response = await openai_client.chat.completions.create(
+            model=MODEL_ID,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": user_message},
+            ],
+            response_format={"type": "json_object"},
+            temperature=0.1,
+            max_tokens=2048,
+        )
+
+        raw_json_text: str = response.choices[0].message.content.strip()
+        logger.info("[%s] LLM responded (%d chars). Validating …", job_id, len(raw_json_text))
+
+        parsed_report: dict = json.loads(raw_json_text)
+
+        missing_keys = {"score", "percentage", "mistakes"} - parsed_report.keys()
+        if missing_keys:
+            raise ValueError(
+                f"LLM response missing required keys: {missing_keys}. "
+                f"Raw snippet: {raw_json_text[:400]}"
+            )
+
+        db_update_job(job_id=job_id, status="Completed", report=json.dumps(parsed_report))
+        logger.info("[%s] Evaluation completed successfully.", job_id)
+
+    except Exception as exc:
+        logger.exception("[%s] Evaluation failed: %s", job_id, exc)
+        db_update_job(
+            job_id=job_id,
+            status="Failed",
+            report=json.dumps({"error_type": type(exc).__name__, "error_message": str(exc)}),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Application
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialise the database on startup; nothing to clean up on shutdown."""
+    init_db()
+    logger.info("Code Evaluator started and ready.")
+    yield
+
+
+app = FastAPI(
+    title="Code Evaluator",
+    description=(
+        "Asynchronous Python code grading service. "
+        "Submit a script, receive a job_id instantly, poll for the structured report."
+    ),
+    version="2.1.0",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# Auth dependency
+# ---------------------------------------------------------------------------
+
+async def verify_api_key(x_api_key: str = Header(...)) -> None:
+    """Reject requests whose X-API-Key header does not match the shared key."""
+    if x_api_key != YOUR_CUSTOM_API_KEY:
+        logger.warning("Rejected request — invalid X-API-Key supplied.")
+        raise HTTPException(status_code=401, detail="Unauthorised: invalid or missing X-API-Key.")
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.post(
+    "/submit",
+    summary="Submit a Python script for asynchronous evaluation",
+    dependencies=[Depends(verify_api_key)],
+)
+async def submit_code(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(..., description="Python source file (.py) to evaluate"),
+) -> JSONResponse:
+    """
+    Accept a .py upload, create a tracking row, enqueue LLM evaluation, and
+    return a job_id immediately — no waiting for inference to complete.
+    """
+    # Read at most MAX_UPLOAD_BYTES + 1 so we never load a huge file into
+    # memory. Reading one byte over the limit lets us detect and reject it
+    # before any processing happens.
+    MAX_UPLOAD_BYTES = 100_000  # 100 KB — more than enough for a student script
+    raw_bytes: bytes = await file.read(MAX_UPLOAD_BYTES + 1)
+
+    if len(raw_bytes) > MAX_UPLOAD_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"File exceeds the {MAX_UPLOAD_BYTES // 1000} KB size limit. "
+                   "Ensure you are submitting a Python source file, not a binary.",
+        )
+
+    code_text: str = raw_bytes.decode("utf-8")
+
+    logger.info("Received submission — filename=%s, size=%d bytes.", file.filename, len(raw_bytes))
+
+    job_id: str = str(uuid.uuid4())
+
+    # Insert the row BEFORE enqueuing so GET /report/{job_id} never returns 404
+    # in the window between submission and the background task starting.
+    db_create_job(job_id=job_id)
+    background_tasks.add_task(process_evaluation, job_id=job_id, code_text=code_text)
+
+    logger.info("[%s] Job enqueued for background processing.", job_id)
+    return JSONResponse(content={"job_id": job_id, "status": "Processing"})
+
+
+@app.get(
+    "/report/{job_id}",
+    summary="Retrieve the grading report for a submitted job",
+    dependencies=[Depends(verify_api_key)],
+)
+async def get_report(job_id: str) -> JSONResponse:
+    """
+    Poll for the evaluation result of a previously submitted script.
+
+    Returns 404 if the job_id is unknown, otherwise returns the current
+    state: Processing, Completed (with report), or Failed (with error).
+    """
+    row: sqlite3.Row | None = db_get_job(job_id=job_id)
+
+    if row is None:
+        logger.warning("Report requested for unknown job_id=%s.", job_id)
+        raise HTTPException(
+            status_code=404,
+            detail=f"Job '{job_id}' not found. Verify the job_id or re-submit.",
+        )
+
+    status: str = row["status"]
+    report_raw: str | None = row["report"]
+
+    if status == "Processing":
+        return JSONResponse(content={
+            "job_id": job_id,
+            "status": "Processing",
+            "message": "Your submission is being evaluated. Retry in a few seconds.",
+        })
+
+    elif status == "Failed":
+        error_payload: dict = (
+            json.loads(report_raw)
+            if report_raw
+            else {"error_type": "Unknown", "error_message": "No details available."}
+        )
+        return JSONResponse(content={"job_id": job_id, "status": "Failed", "error": error_payload})
+
+    elif status == "Completed":
+        return JSONResponse(content={
+            "job_id": job_id,
+            "status": "Completed",
+            "report": json.loads(report_raw),
+        })
+
+    else:
+        logger.error("[%s] Unexpected status value '%s' in database.", job_id, status)
+        return JSONResponse(
+            status_code=500,
+            content={"job_id": job_id, "status": status, "message": "Unexpected internal state."},
+        )

requirements.txt

@@ -0,0 +1,4 @@
+fastapi
+uvicorn[standard]
+python-multipart
+openai