Spaces:
Sleeping
Sleeping
| """Always-visible error surface + one-click diagnostics hand-off. | |
| Companion to :mod:`app.ui.api_usage_panel`, and deliberately governed by a | |
| different rule: | |
| * **API Usage Status** is a developer view of *everything* that happened — | |
| token counts, per-stage API-vs-local badges, the raw call table. It stays | |
| behind ``SHOW_DEBUG_PANEL`` because it is noise for a normal user. | |
| * **This panel** shows only *failures*, and it is **never** debug-gated. A | |
| user who hits an error is exactly the user who cannot turn on a debug | |
| flag, and hiding the explanation from them is what turns "I picked a | |
| retired model" into a support ticket that reads "the app is broken". | |
| It renders nothing at all when there are no failures, so a healthy run is | |
| visually unchanged. | |
| Privacy | |
| ------- | |
| Everything shown and shared comes from the metadata-only records in | |
| :mod:`app.services.diagnostics` — no API key, dossier text, screenshot, | |
| job description, or generated proposal. The full payload is shown to the | |
| user *before* any upload, because a share button people cannot inspect is | |
| a share button people do not press. | |
| """ | |
| from __future__ import annotations | |
| import re | |
| from typing import Optional | |
| import streamlit as st | |
| from app.services import diagnostics | |
| # Plain-English meaning per status code, with the actionable next step. The | |
| # wording deliberately separates "no model is set" (a configuration gap) | |
| # from "the model you set was rejected" (a wrong/retired name) — collapsing | |
| # those two into one message is what previously sent users to re-check a | |
| # dropdown that already had a value in it. | |
| _STATUS_HELP: dict[str, tuple[str, str]] = { | |
| "access_denied": ("Model access denied", "Check your provider permissions or choose a model your account can use."), | |
| "app_error": ("Unexpected app error", "Retry the step. If it repeats, share the diagnostics with the app team."), | |
| "invalid_key": ( | |
| "API key rejected", | |
| "Re-copy the whole key and confirm it belongs to the provider " | |
| "selected in Setup (an OpenAI key will not work with Anthropic).", | |
| ), | |
| "model_missing": ( | |
| "Model not accepted by the provider", | |
| "The model name was not recognised — it may be retired, misspelled, " | |
| "or unavailable on your plan. Pick a different model in Setup.", | |
| ), | |
| "quota": ( | |
| "Out of credit or rate limited", | |
| "Add credit in your provider dashboard, or wait a moment and retry.", | |
| ), | |
| "context_overflow": ( | |
| "Too much input for this model", | |
| "Shorten the dossier or screenshot text and try again.", | |
| ), | |
| "connection": ( | |
| "Could not reach the provider", | |
| "Check your internet connection, VPN, or firewall, then retry.", | |
| ), | |
| "parse_error": ( | |
| "Unreadable reply from the model", | |
| "The model did not return valid JSON. Retrying usually fixes it; if " | |
| "it repeats, try a different model.", | |
| ), | |
| "truncated": ( | |
| "Reply cut off by the token limit", | |
| "Raise the output-token limit in Setup and retry.", | |
| ), | |
| "no_api": ( | |
| "No API key configured", | |
| "Add your key in Setup and save the configuration.", | |
| ), | |
| "unsupported_provider": ( | |
| "Provider not configured", | |
| "Choose a supported provider in Setup.", | |
| ), | |
| "exception": ( | |
| "Unexpected provider error", | |
| "Share the diagnostics below with the app team.", | |
| ), | |
| } | |
| # HTTP status refines the story where the SDK gave us one. These are exact | |
| # signals, unlike the message-text heuristics used to bucket the status. | |
| _HTTP_HELP: dict[int, str] = { | |
| 400: "The provider rejected the request itself (bad parameter) — this is " | |
| "an app-side issue, not something you configured wrong.", | |
| 401: "The key was not accepted at all.", | |
| 403: "The key is valid but is not allowed to use this model.", | |
| 404: "The model name does not exist for this provider.", | |
| 429: "Rate limit or credit limit hit.", | |
| } | |
| # Characters a provider, model, id or timestamp keeps when shown below. The | |
| # values go into Markdown and some are free text (a custom model name, a | |
| # request id from whatever answered the call): a backtick would close the | |
| # code span around it and the rest would render as live Markdown, such as a | |
| # link in the app's own sidebar. Real names, ids and timestamps fit this set. | |
| _UNSAFE_CHARS = re.compile(r"[^A-Za-z0-9_.:/@+-]") | |
| _MAX_VALUE_LEN = 80 | |
| def _safe(value: object, default: str = "—") -> str: | |
| """``value`` cut down to plain id characters, safe inside Markdown.""" | |
| text = _UNSAFE_CHARS.sub("", str(value or ""))[:_MAX_VALUE_LEN] | |
| return text or default | |
| def _describe(event: dict) -> tuple[str, str]: | |
| """Return ``(headline, next_step)`` for one failed call.""" | |
| status = str(event.get("status") or "exception") | |
| headline, action = _STATUS_HELP.get( | |
| status, ("Something went wrong", "Share the diagnostics with the app team.") | |
| ) | |
| http_status = event.get("http_status") | |
| if isinstance(http_status, int) and http_status in _HTTP_HELP: | |
| action = f"{_HTTP_HELP[http_status]} {action}" | |
| return headline, action | |
| def _stage_label(event: dict) -> str: | |
| task = _safe(event.get("task_name"), "unknown") | |
| return task.replace("_", " ").strip().capitalize() | |
| _INTERVIEW_TASKS = frozenset({"interview_turn", "interview_check"}) | |
| def render(*, key_suffix: str = "", limit: int = 50) -> None: | |
| """Render the diagnostics panel, or nothing when there is no failure. | |
| Pass a unique ``key_suffix`` when calling from more than one screen so | |
| Streamlit widget keys stay unique. | |
| """ | |
| try: | |
| session_events = list(st.session_state.get("api_usage_log") or []) | |
| except Exception: # noqa: BLE001 - outside a script run | |
| session_events = [] | |
| # Disk first on a single-user install: it survives the page reload that | |
| # usually follows a failure and spans earlier sessions. On the shared | |
| # cloud host the disk log holds every visitor's calls, so only this | |
| # session's own log is used there (see diagnostics.visitor_events). | |
| events = diagnostics.visitor_events(session_events, limit=limit) | |
| # The guided interview reports on its own API where the user is, and it | |
| # can run on a different provider (an optional Groq key) from the rest of | |
| # the app. Its failures are left out here, or a rejected interview key | |
| # would read as "Problem detected" for the main API that is working. | |
| events = [ | |
| e for e in events | |
| if str((e or {}).get("task_name") or "") not in _INTERVIEW_TASKS | |
| ] | |
| # Only failures since the last successful call: a success is proof the | |
| # problem is over, and a warning that never clears is one users learn | |
| # to ignore. | |
| failures = diagnostics.unresolved_errors(events) | |
| if not failures: | |
| return | |
| latest = failures[-1] | |
| headline, action = _describe(latest) | |
| with st.expander(f"⚠️ Problem detected — {headline}", expanded=False): | |
| st.markdown(f"**{headline}**") | |
| st.caption(action) | |
| st.markdown( | |
| f"- **Stage:** {_stage_label(latest)}\n" | |
| f"- **Provider / model:** `{_safe(latest.get('provider'))}`" | |
| f" · `{_safe(latest.get('model'))}`\n" | |
| f"- **When:** {_safe(latest.get('timestamp'))}" | |
| ) | |
| # Correlation ids: meaningless to the user, decisive for support. | |
| req_id = latest.get("request_id") | |
| http_status = latest.get("http_status") | |
| err_type = latest.get("error_type") | |
| if req_id or http_status or err_type: | |
| bits = [] | |
| if http_status: | |
| bits.append(f"HTTP `{_safe(http_status)}`") | |
| if err_type: | |
| bits.append(f"type `{_safe(err_type)}`") | |
| if req_id: | |
| bits.append(f"request `{_safe(req_id)}`") | |
| st.caption("Reference: " + " · ".join(bits)) | |
| if len(failures) > 1: | |
| st.caption(f"{len(failures)} failed calls since the last success.") | |
| st.divider() | |
| _render_share(session_events, key_suffix=key_suffix) | |
| def _render_share(session_events: list[dict], *, key_suffix: str = "") -> None: | |
| """Build-and-share controls: inspect, download, and optional upload.""" | |
| st.markdown("**Share with the app team**") | |
| st.caption( | |
| "Metadata only — no API key, dossier text, screenshots, job posts, " | |
| "or generated proposals." | |
| ) | |
| # One report id per session so the download, the upload, and whatever the | |
| # user quotes in an email all refer to the same thing. | |
| id_key = f"diag_report_id_{key_suffix}" | |
| if id_key not in st.session_state: | |
| st.session_state[id_key] = diagnostics.new_report_id() | |
| report_id: str = st.session_state[id_key] | |
| report = diagnostics.build_report( | |
| report_id=report_id, session_events=session_events | |
| ) | |
| payload = diagnostics.report_to_json(report) | |
| st.download_button( | |
| "Download diagnostics", | |
| data=payload, | |
| file_name=f"{report_id}.json", | |
| mime="application/json", | |
| use_container_width=True, | |
| key=f"diag_dl_{key_suffix}", | |
| help="Save the report and attach it to an email or chat message.", | |
| ) | |
| # st.code ships a native copy button, so there is no need for custom JS | |
| # (which the app's CSP-tight embed would complicate anyway). | |
| with st.expander("View / copy report", expanded=False): | |
| st.code(payload, language="json") | |
| if diagnostics.is_upload_configured(): | |
| sent_key = f"diag_sent_{key_suffix}" | |
| if st.button( | |
| "Send to support", | |
| use_container_width=True, | |
| key=f"diag_send_{key_suffix}", | |
| help="Uploads the report above so the team can look it up by id.", | |
| ): | |
| st.session_state[sent_key] = diagnostics.upload_report(report) | |
| sent: Optional[bool] = st.session_state.get(sent_key) | |
| if sent is True: | |
| st.success(f"Sent. Quote reference **{report_id}** to the team.") | |
| elif sent is False: | |
| st.warning( | |
| "Upload failed. Use **Download diagnostics** above and send " | |
| "the file instead." | |
| ) | |
| else: | |
| st.caption(f"Reference id: **{report_id}**") | |
| __all__ = ["render"] | |