コンテンツにスキップ

Frontend File Management UI Components

[!NOTE] 最新の実装状況は 機能実装ステータス (Remaining Functionality) を参照してください。

This document catalogues the lightweight Dash-based UI panels used by the EvoSpikeNet system for document upload, version history, diffing, and batch processing. All of the widgets are currently considered MVP: they provide minimal structure and rely on surrounding application code to wire callbacks and layout them in a larger page.

1. File Upload Panel

  • Status: ✅ MVP
  • Purpose: provide a drag‑and‑drop / browse component for users to submit one or more documents to the backend ingestion pipeline.
  • Implementation file: frontend/file_upload_ui.py

Details

The panel now wraps the upload widget defined in frontend/upload.py but also provides slots for a file list, preview area, and status messages. Its layout looks like:

html.Div(
    [
        create_upload_layout(multi=True),
        html.Div(id="upload-file-list", className="mt-2"),
        html.Div(id="upload-preview", className="mt-2"),
        html.Div(id="upload-status", className="mt-2"),
    ],
    id="file-upload-panel",
)

Callbacks should populate the additional divs with progress bars, error alerts, and previews of text or PDF content. max_size_mb is still configurable but defaults to 1024 MB. The module itself does not implement the callbacks – host pages (e.g. the RAG page) are responsible for wiring upload handlers, validation, streaming, and interaction with the backend APIs.

2. Version History Display

  • Status: ✅ MVP (enhanced)
  • Purpose: show a paginated table of existing saved versions for a given document or dataset, with action buttons for download, compare and rollback.
  • Implementation file: frontend/version_history_ui.py

Details

The module exports two helpers:

  • version_history_table(rows) – constructs a dash_table.DataTable with columns version, timestamp, path plus three action columns. Rows may embed markdown-formatted links or buttons for each action, which should be handled by callbacks in the host page.
  • version_history_panel(rows) – wraps the table in a html.Div with a heading and unique id for easier callback targeting.

This component still does not fetch data itself; the host page is responsible for querying the VersionManager API and refreshing rows. Example callbacks in the RAG page implement download/comparison logic.

3. Version Comparison UI

  • Status: ✅ MVP (enhanced)
  • Purpose: display a unified diff of two document versions with navigation tools.
  • Implementation file: frontend/version_compare_ui.py

Details

The panel includes navigation buttons (Prev, Next, Copy) above the diff area and still uses a dcc.Textarea for the diff output. It exposes an id for the textarea and buttons so that callbacks can implement line-by-line navigation or copy-to-clipboard behavior.

The host page must compute the diff (using frontend/version_compare.diff_text or similar) and provide the resulting lines. Navigation callbacks can highlight sections or scroll the textarea using clientside JavaScript.

4. Batch Processing UI

  • Status: ✅ MVP (enhanced)
  • Purpose: present a status table for bulk document ingestion/chunking jobs, with progress bars and action buttons.
  • Implementation file: frontend/batch_processing_ui.py

Details

The panel now contains a dash_table.DataTable with columns for filename, status, Markdown progress bar, and action buttons (e.g. cancel/retry). It also retains a generic batch-processing-status div for text-based messages.

As with other components, this module provides only layout; the hosting page (or a shared callbacks file) must populate the table’s data property and update rows as jobs are enqueued, started, completed or failed. Progress bars can be rendered via Markdown or HTML syntax within the progress column.

Notes and Next Steps

These components are designed for rapid prototyping and are intentionally minimal:

  1. Styling & layout can be extended using Dash html/dbc components.
  2. Callback wiring (upload handling, history operations, diff generation, batch status polling) should reside in the page modules under frontend/pages or similar.
  3. Accessibility & validation are currently addressed moderately: unit/ E2E tests include keyboard navigation, focus outline, responsive viewport resizing, and an axe-core audit. Additional UI enhancements (contrast ratio checks, ARIA roles, file‑type icons) may be added.
  4. Dark mode is supported by toggling the .dark-theme class; CSS snippets are included in frontend/app.py.
  5. File previews now include text, PDF text, and small image thumbnails returned in upload-preview.

Additional Notes

  • Responsive testing is exercised programmatically in the E2E suite by resizing the browser window across mobile/desktop breakpoints.
  • Error handling for backend APIs covers timeouts and 401/403 authentication failures using the safe_request helper.
  • The batch processing panel interfaces with /batch/create and /batch/cancel endpoints; these are simple demo endpoints in rag_system but can be backed by real job queues.

The back end already exposes the necessary APIs (VersionManager, rollback_version, upload endpoints) so the UI modules merely need to be integrated into a Dash application.

For comprehensive coverage, consider adding unit tests to verify that each panel renders without error given sample data.

Backend API Endpoints

The UI components are designed to work with a small set of server endpoints:

  • POST /upload_file – standard RAG file upload (already in place).
  • POST /batch/create – create a new batch job; returns job_id.
  • POST /batch/cancel – cancel a previously created job by job_id.

The batch_job_handler callback in rag.py demonstrates calling these endpoints and updating the table accordingly. These endpoints are stored in memory for demo purposes but can be wired to persistent job queues in e.g. Celery, Redis, or a database.

Backend API Endpoints

The UI components are designed to work with a small set of server endpoints:

  • POST /upload_file – standard RAG file upload (already in place).
  • POST /batch/create – create a new batch job; returns job_id.
  • POST /batch/cancel – cancel a previously created job by job_id.

These endpoints are consumed by the callbacks in rag.py and may be backed by persistent queues (Celery/Redis) in production. The simple in-memory implementation is suitable for demo or unit testing.

Callback Helpers

A supporting module frontend/ui_callbacks.py provides skeleton callbacks that can be imported by any page to wire the panels to backend logic. The file contains examples for refreshing version history, computing diffs, and handling uploads; developers should extend or replace these stubs with application‑specific API calls.

Example Integration

The RAG page (frontend/pages/rag.py) demonstrates how to import and embed these components within a real application. In its "Data Management" and related tabs the page uses:

  • file_upload_panel() for simple uploads with preview and status updates
  • the advanced create_upload_card() (streaming/parser options, background jobs, session handling)
  • version_history_panel() and version_compare_panel() to display version data tied to VersionManager along with a history-alert region for action feedback
  • batch_processing_panel() for job queue monitoring plus an "Add Job" control and in‑table cancel capability

Internally the page wraps all external HTTP calls (via fe_api_client) with a safe_request helper that enforces a 30‑second timeout and surfaces connection/authentication errors as user alerts. Action columns in the history table are wired to history_actions callback, supporting download, adjacent comparison and rollback. Uploads now return a snippet of the file as preview text, which is rendered in upload-preview.

Callbacks from frontend/ui_callbacks are imported on page load, providing ready‑made logic for refreshing history and computing diffs; the page adds a few more callbacks (batch job add/cancel, history actions, upload preview). This serves as both a reference implementation and a starting point for other pages.

Error handling, progress bars, accessibility (aria- attributes, live regions) and mobile‑friendly layout are illustrated in the RAG page, making it suitable for production use.