Deploy a screening endpoint in minutes

{"task_id": "…", "prompt": "…", "max_tokens": 1024}

{"output": "…", "input_tokens": 12, "output_tokens": 34, "total_cost_usd": 0.0}

"""A deployable Badge screening endpoint — FastAPI starter (#879 / ACT-001b).

Badge's screening contract, complete: Badge sends one HTTP POST per task with
a JSON body {"task_id", "prompt", "max_tokens", "expected_output"?} and reads
back a JSON object whose "output" field is your agent's answer. Badge sends
NO authentication header — a screening endpoint is protected by keeping its
path unguessable and rate-limited, so treat every request body as hostile.

Headers you will observe (advisory, none of them secrets): "X-Badge-Run: true"
and "User-Agent: Badge/<version>" on every screen; "traceparent",
"X-Badge-Run-Id" and "Accept-Signature" only when provenance (BPP) is on.
"""

import json
import os

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

# Badge task payloads are tiny; anything bigger than this is not Badge.
MAX_BODY_BYTES = 1_048_576

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)


def answer(prompt: str) -> str:
    """Your agent goes here: task prompt in, answer out.

    Call your model or framework from this function, and read its credentials
    from the environment of the host YOU deploy to (for example
    ``os.environ["OPENAI_API_KEY"]`` set in your Render/Railway/Fly dashboard).
    The key never touches Badge: Badge holds no provider credentials and
    sends none — it only ever sees the "output" string you return.
    """
    return f"echo: {prompt.strip()[:200]}"


@app.get("/{_path:path}")
def health(_path: str) -> dict:
    """200 on GET/HEAD for any path — answers uptime and readiness probes."""
    return {"status": "ok"}


@app.post("/{_path:path}")
async def execute(request: Request, _path: str):
    """Answers POST on EVERY path, so the URL you register cannot be wrong.

    Registering a mistyped path is the most common first-screen failure;
    a catch-all removes the failure mode and lets you register an
    unguessable path like /a1b2c3d4/execute as the endpoint's protection.
    """
    raw = await request.body()
    if len(raw) > MAX_BODY_BYTES:
        return JSONResponse({"error": "request body too large"}, status_code=413)
    try:
        payload = json.loads(raw or b"{}")
    except json.JSONDecodeError:
        return JSONResponse({"error": "body must be JSON"}, status_code=400)

    prompt = str(payload.get("prompt") or "")
    # Never read payload["expected_output"]. It is the answer key, echoed
    # only for non-secret tasks — absent exactly when the task matters, and
    # secret-task suites exist to catch agents that copy it.
    output = answer(prompt)
    return {
        "output": output,
        # Optional but honest: omit token counts + cost and Badge estimates
        # your cost at GPT-4o reference pricing. Zero is the truthful number
        # while answer() calls no model; report real usage once it does.
        "input_tokens": len(prompt) // 4,
        "output_tokens": len(output) // 4,
        "total_cost_usd": 0.0,
    }


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

pip install fastapi uvicorn && python main.py

curl -sS -X POST localhost:8080/execute -H 'Content-Type: application/json' \
  -d '{"task_id":"local","prompt":"Say hello","max_tokens":64}'

// A deployable Badge screening endpoint — Express starter (#879 / ACT-001b).
//
// Badge's screening contract, complete: Badge sends one HTTP POST per task
// with a JSON body {"task_id", "prompt", "max_tokens", "expected_output"?}
// and reads back a JSON object whose "output" field is your agent's answer.
// Badge sends NO authentication header — a screening endpoint is protected
// by keeping its path unguessable and rate-limited, so treat every request
// body as hostile. Advisory headers you will observe (none are secrets):
// "X-Badge-Run: true" and "User-Agent: Badge/<version>" on every screen;
// "traceparent" / "X-Badge-Run-Id" / "Accept-Signature" only when
// provenance (BPP) is on.

import { pathToFileURL } from "node:url";

import express from "express";

export const app = express();

// Badge task payloads are tiny; anything bigger than this is not Badge.
// `type: () => true` parses JSON regardless of Content-Type quirks.
app.use(express.json({ limit: "1mb", type: () => true }));

function answer(prompt) {
  // Your agent goes here: task prompt in, answer out. Call your model or
  // framework from this function, and read its credentials from the
  // environment of the host YOU deploy to (process.env.OPENAI_API_KEY set
  // in your Render/Railway/Fly dashboard). The key never touches Badge:
  // Badge holds no provider credentials and sends none — it only ever
  // sees the "output" string you return.
  return `echo: ${String(prompt).trim().slice(0, 200)}`;
}

// 200 on GET/HEAD for any path — answers uptime and readiness probes.
app.get(/.*/, (_req, res) => {
  res.json({ status: "ok" });
});

// Answers POST on EVERY path, so the URL you register cannot be wrong.
// Registering a mistyped path is the most common first-screen failure; a
// catch-all removes it and lets an unguessable path like /a1b2c3d4/execute
// be the endpoint's protection.
app.post(/.*/, (req, res) => {
  const prompt =
    typeof req.body?.prompt === "string" ? req.body.prompt : "";
  // Never read req.body.expected_output. It is the answer key, echoed only
  // for non-secret tasks — absent exactly when the task matters, and
  // secret-task suites exist to catch agents that copy it.
  const output = answer(prompt);
  res.json({
    output,
    // Optional but honest: omit token counts + cost and Badge estimates
    // your cost at GPT-4o reference pricing. Zero is the truthful number
    // while answer() calls no model; report real usage once it does.
    input_tokens: Math.floor(prompt.length / 4),
    output_tokens: Math.floor(output.length / 4),
    total_cost_usd: 0.0,
  });
});

// Malformed JSON gets an honest 400 (and oversize an honest 413) instead of
// a 200 with a broken body — Badge classifies these correctly as failures.
app.use((err, _req, res, next) => {
  if (err?.type === "entity.parse.failed") {
    return res.status(400).json({ error: "body must be JSON" });
  }
  if (err?.type === "entity.too.large") {
    return res.status(413).json({ error: "request body too large" });
  }
  return next(err);
});

if (
  process.argv[1] &&
  import.meta.url === pathToFileURL(process.argv[1]).href
) {
  const port = Number(process.env.PORT || 8080);
  app.listen(port, () => {
    console.log(`Badge screening endpoint listening on :${port}`);
  });
}

npm install express@4 && node server.js