Add one justified AI-powered feature

Why this matters

Today you add one AI-powered feature to your capstone — and you add it the way a professional does, which means most of the hour goes into everything around the model call: where the key lives, what happens when the provider is slow, what you do with output that is confidently wrong, and how the feature behaves when the provider is simply down.

The rule underneath all of it: model output is untrusted external input and must be validated before you store it or show it. Same posture you take toward a form field a stranger typed.

A narrow AI task

A model is worth using when the output is probabilistic and a human can check it cheaply. It is the wrong tool when a wrong answer is silently harmful.

Good fits — the model drafts, a person approves:

• Summarising five free-text maintenance notes into two sentences.
• Extracting structured fields from a pasted note: which equipment, what part, urgency.
• Suggesting a title or a category for a record.

Bad fits — never send these to a model:

• Deciding whether a user is allowed to see a record. Authorisation is code, on the server.
• Computing a total, a due date, or anything arithmetic. Your existing code is exact and free.
• Anything that writes to the database with no human in between.

Pick one narrow task and write it in one sentence, with the exact input and the exact output shape. "Given up to 2000 characters of maintenance notes, return a summary of at most 300 characters and a severity of low, medium, or high." That sentence is the whole feature.

The key lives on the server. Always.

Your API key is a password that spends your money. It must never appear in browser code, in any form. Not in a React component, not in a config file the frontend imports, not in an environment variable your bundler embeds.

That last one is the trap. Vite only exposes variables prefixed VITE_ to client code, and it does so by inlining the literal value into the JavaScript it builds. VITE_AI_API_KEY ends up as plain text in a file anyone can open with View Source. There is no fixing this later; the key must be rotated.

The correct shape: the browser calls your server, and your server calls the provider.

browser  ──POST /api/summarize──▶  your server  ──▶  AI provider
                                   (holds AI_API_KEY, enforces limits)

Your server is also where you enforce login, cap input size, and count usage — none of which the browser can be trusted to do.

Cost, latency, and timeouts

Two facts that shape the whole design: every call costs money, and every call is slow — typically seconds, occasionally much longer. So:

• Cap the input. Reject or truncate above a fixed character count. Long inputs cost more and are usually a paste accident.
• Cap the frequency. A per-user daily limit, checked in your database. Without it, one loop in a browser tab can spend your budget overnight.
• Set a timeout. Below, 15 seconds; past that you stop waiting and fall back.
• Tell the user something is happening. A disabled button and "Summarising… this can take a few seconds" is the minimum. A silent 8-second wait reads as a broken app and gets clicked again.

app.post("/api/summarize", requireLogin, async (req, res) => {
  const notes = String(req.body.notes ?? "");
  if (notes.length === 0) return res.status(400).json({ error: "No notes provided." });
  if (notes.length > 2000) return res.status(400).json({ error: "Notes too long (max 2000)." });
  if (!process.env.AI_API_KEY) return res.status(503).json({ error: "Suggestions unavailable." });

  try {
    const response = await fetch(process.env.AI_API_URL, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        authorization: `Bearer ${process.env.AI_API_KEY}`,
      },
      body: JSON.stringify(/* the request shape from your provider's docs */),
      signal: AbortSignal.timeout(15000),
    });
    if (!response.ok) return res.status(503).json({ error: "Suggestions unavailable." });
    const suggestion = parseSuggestion(await extractText(response));
    if (!suggestion) return res.status(503).json({ error: "Suggestions unavailable." });
    return res.json({ suggestion });
  } catch (error) {
    console.error({ where: "summarize", name: error.name, message: error.message });
    return res.status(503).json({ error: "Suggestions unavailable." });
  }
});

The request body and the path to the text inside the response are provider-specific: take them from your provider's own documentation and do not guess them. Everything else — the limits, the timeout, the 503, the log — is yours and is the same whichever provider you use.

Structured output and validating it

Asking for prose gives you something you can only display. Ask for structured output — JSON in a shape you specified — and you can check it. Many providers offer a mode that constrains output to a schema; check your provider's docs for whether yours does. Either way, you still validate, because a mode that usually works is not a guarantee.

function parseSuggestion(raw) {
  let parsed;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return null;                                   // not JSON at all
  }
  if (typeof parsed !== "object" || parsed === null) return null;
  const { summary, severity } = parsed;
  if (typeof summary !== "string" || summary.length === 0 || summary.length > 300) return null;
  if (!["low", "medium", "high"].includes(severity)) return null;
  return { summary, severity };
}

Nothing leaves this function that your app did not already agree to accept. A model that invents a severity of "critical", returns an apology in prose, or wraps its JSON in explanation returns null here, and null means fall back — not crash, not store.

Human confirmation and fallback

Human confirmation means no durable write happens on model output alone. The suggestion appears in an editable field, marked as generated, and the existing Save button is what writes to the database. The user can edit it, replace it, or ignore it.

Show the uncertainty on screen. A small label — "AI-generated draft. Check before saving." — is the honest interface. Presenting generated text with no marking makes your app claim something it cannot back up.

Fallback behaviour means the feature is additive: when the provider is down, over budget, slow, or returns something invalid, the user gets the ordinary manual form and a quiet line saying suggestions are unavailable right now. Nothing they were trying to do becomes impossible. If your core workflow stops working when the provider does, you did not add a feature — you added a dependency.

Walkthrough

1. Add AI_API_KEY and AI_API_URL to .env; confirm .env is in .gitignore with git check-ignore .env (it prints .env when ignored).
2. Add the /api/summarize route above, with login required and both limits.
3. Add parseSuggestion and unit-test it with four inputs: valid JSON, invalid JSON, a valid shape with severity: "critical", and a 400-character summary. Only the first should pass.
4. In the UI, add a "Suggest summary" button beside the existing field. While waiting: disable it and show the waiting text. On success: fill the field, keep it editable, show the draft label. On any failure: leave the field alone and show "Suggestions unavailable".
5. Force each failure: wrong key, no key, and — to test the timeout — point AI_API_URL at a URL that never responds.

Your turn

1. Write your one-sentence feature definition with exact input and output shape.
2. Implement the server route with login, input cap, usage cap, timeout, and logging.
3. Implement and test the validator. Nothing unvalidated reaches the UI or the database.
4. Build the UI: waiting state, editable draft, visible "AI-generated" label, human Save.
5. Verify the fallback with the key removed and with an unreachable URL.
6. Confirm with grep -ri "api_key" src/ that no key or key-bearing variable appears in frontend code.

Common pitfalls

• Calling the provider from the browser to "keep it simple". The key is then public. There is no simple version of this that is safe.
• Trusting output because it parsed. Valid JSON with a made-up severity is still wrong. Check values, not just syntax.
• No timeout. One slow call holds a spinner open indefinitely and the user reloads mid-write.
• Writing the suggestion straight to the database. Then a hallucination is now a record, and nobody knows which rows are generated.

Verify it yourself

Open today's reference, the Codex CLI documentation, and look at what it says about how the tool handles your environment, credentials, and approvals.

1. Does it describe anything about sandboxing, approvals, or access to your environment? Note one thing that applies to a repository holding a real API key.
2. This lesson claimed you should never paste a key into a prompt. Find whatever the docs say about secrets or environment access and decide whether your current setup matches it.

Then open your provider's own documentation and confirm the exact request and response shape you used. If any field in your code is not in their docs, you guessed — fix it now.