Build: Mitra Answers Reliably

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

MitraError

Mitra's own error type. It has a kind such as timeout or rate_limited, and never carries a provider's words.

askMitra

The one function that sends a conversation to /api/chat and returns a whole answer or throws a MitraError.

askWithRetry

A wrapper around askMitra that retries the failures worth retrying, with backoff and a limit.

Reducer

A function (state, action) => newState that is the only place state changes. It makes allowed moves explicit.

noteFor

A small function that turns a response into what to show: the answer, plus a note when it was cut off, blocked or empty.

Ref guard

A useRef flag that is checked and set at once inside the submit handler, so two submits in the same moment cannot both pass.

1. 1

   Teach the route a new situation

   In the stand-in provider add if (/closed/i.test(text)) return { fail: { status: 500, message: "Internal error" } };, then ask "closed" in the page.

   Mitra retries twice (a 500 is retryable), fails, and shows "Mitra had a problem on its side" with a Try again button. The screen code did not change: new failures reuse the messages for their kind.

2. 2

   Change the time limit

   Set TIMEOUT_MS to 3000 and ask for the slow question.

   The slow stand-in answers after 2 seconds, so it now arrives in time (the page shows its scripted text, "This answer comes too late.", as a normal answer). The example takes longer. Moving one number changed which outcome the visitor sees, which is why the limit should come from measured response times.

3. 3

   Retry a rate limit automatically

   Add "rate_limited" to RETRYABLE and ask the busy question.

   Mitra now makes three requests against a provider that said to wait two seconds, and each one counts against the limit. The visitor ends up with the same error, later. Topic 3.6 shows the right way: wait the Retry-After, with a countdown.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: Mitra v0 (Topic 0.5) works on a good day. Real days have a rate limit, a slow reply, a phone that drops off Wi-Fi, an answer that stops mid-sentence. This topic turns Topics 1.1 to 1.5 into one small program, so each idea has a place to live and each failure has a message and a way forward.

2. 2

   What changes from v0. v0 streamed text with the stand-in stream helper and sent { question }. v1 sends the conversation shape every real provider uses ({ messages }, Topic 1.1), through a route that validates and adds the system message (Topic 1.5), gets a whole JSON answer back, and no longer streams: Phase 2 streams again, on this solid footing. Every file keeps the registry names: the route is /api/chat, the helper is askMitra(messages, { signal }), and the elements are #messages, #prompt, #send, #status and #error.

3. 3

   The server part. The route checks the body, builds the provider request itself, and calls the provider. If the provider fails, it logs the real reason and returns only a small code: 429 stays 429 with its Retry-After; anything else becomes 502 provider_error. A success carries the answer, the finish reason and the token count. In this live example the "provider" is the stand-in, and the route calls it as it would call a real URL.

4. 4

   **askMitra(messages, { signal }) is the one place that talks to the route.** It adds the time limit, joins it with an optional stop signal (used from Phase 3), checks res.ok, and throws a MitraError with a kind: bad_request, rate_limited (with retryAfter), server, timeout or offline. A caller never sees a status code or a provider message. If the *visitor* aborted, the original AbortError passes through untouched, so it is not mistaken for a failure.

5. 5

   **askWithRetry adds patience.** It retries only server, timeout and offline, up to twice, with a short growing wait with jitter, and tells the screen each time ("Trying again (attempt 2)…"). It does not retry rate_limited: telling the visitor to wait is better than spending the quota that ran out (Topic 3.6 builds a countdown). After the last failure the error shows with a Try again button, which starts a fresh set of attempts.

6. 6

   The screen. One reducer holds status, the question asked, the answer, a note and an error. noteFor(data) makes the four decisions from Topic 1.1: complete (answer only), cut off (answer with an ellipsis and a note), blocked (a note, no answer) and empty (a note). A ref guard stops a double submit (Topic 1.2). The error has role="alert", and the messages area is a polite live region.

7. 7

   What Mitra can do now that it could not before: survive a failing provider, say something true and useful for each failure, retry the right ones, ignore double sends, distinguish a cut-off or blocked answer from a complete one, and keep the secret key and the instructions on the server. What is still missing, and where it is added: text that appears as it is written (Phase 2); a Stop button, partial answers and a rate-limit countdown (Phase 3); a conversation with history (Phase 4); an SDK in place of the hand-written plumbing (Phase 5); formatted answers (Phase 6); cards and actions (Phases 7 and 8).

• ↔

  Four layers cost more lines than one component, and pay back in tests, in swapping the transport (Phase 5) and in knowing where a bug lives.

• ↔

  Waiting for the whole answer makes every state simple to reason about and validate, at the cost of a slow-feeling product. Phase 2 trades some of that simplicity for speed of feel.

• I can describe each layer of Mitra v1: route, askMitra, askWithRetry, the screen.

• I can list the kinds of MitraError and the message each one shows.

• I can explain which failures Mitra retries and which it does not.

• I can test askMitra without a screen, and I know why that is useful.

• I can say what Mitra v1 cannot do yet and which phase adds each missing piece.