vectorspacelab/arex-skill/ui-and-deployment

ui-and-deployment

Use this sub-skill when the task is to run, configure, deploy, smoke-check, or troubleshoot Sparrow's user-facing shells and their service wiring.

Route here for

• Gradio shell operation: document-processing page, dashboard page, feedback page, upload limits, Sparrow key controls, Oracle-backed dashboard/feedback, Gradio queueing, and temporary file cleanup.
• Next shell operation: /process, /dashboard, /feedback, /api/inference, /api/summarize, package scripts, package metadata checks, upload gates, streaming route behavior, and deployment environment variables.
• Service topology checks across UI, LLM API, optional Oracle DB, optional OCR service, and optional agents service.
• UI-facing diagnosis where the symptom might be an upload validation failure, unreachable backend API, restricted-key configuration, missing database records, npm dependency state, CORS/port mismatch, or reverse-proxy buffering.

Route elsewhere

• LLM API request semantics, engine options, CLI usage, model backend selection, pipeline behavior, schema validation internals, and backend HTTP endpoint contracts: route to api-engine-and-cli.
• OCR model behavior, OCR endpoint details, PDF/image text extraction, bounding boxes, and OCR dependencies: route to ocr-service.
• Agent workflow execution, agent selection, Prefect/Celery/Redis behavior, async task polling, and workflow-specific payloads: route to agent-workflows.
• Do not change API payload meaning from this sub-skill; only verify that the UI forwards the expected fields and displays failures coherently.

Operating workflow

1. Identify the active shell: Gradio Python UI, Next UI, or both behind a proxy. Use UI deployment for run commands, shell responsibilities, and configuration keys.
2. Confirm the service graph and startup order from service topology: UI -> LLM API, optional UI/LLM API -> Oracle DB, optional side services for OCR and agents.
3. Run metadata-only checks before installing or building Node packages. Use `scripts/ui_config_check.py` against a Next package.json, or run it without a package file to print the embedded expectations.
4. For user-visible failures, triage with troubleshooting. Separate local upload validation, UI server route failures, backend API failures, restricted-key/Oracle failures, and rendering issues before changing code.
5. If the root cause is outside UI/deployment ownership, hand off with the exact observed UI symptom, the shell in use, relevant environment/config keys, service port/status, and the route target skill named above.

Fast checks

• Next package metadata should expose dev, build, start, and lint scripts and include the runtime dependencies used by the process page, dashboard, feedback, Oracle access, PDF page counting, GeoIP, and long-timeout fetch handling.
• Gradio upload validation is image/PDF-focused and removes copied inference inputs in a finally block; a background cleaner handles stale Gradio temp cache entries.
• Next upload validation is browser-side before /api/inference; server actions then forward valid files to the LLM API. A browser-side invalid type should not create backend API traffic.
• Dashboard and feedback are optional Oracle-backed features. Empty dashboard data is expected when database access is disabled; failed feedback persistence is usually a database/config issue, not an LLM issue.