Back to Liquid Agent DOCUMENTATION

Web UI

The project has a public static homepage and bilingual Docs, plus an installed local single-user agent workspace. The workspace uses the same agent logic as the terminal shell. Scientific computation runs locally; configured model requests and explicitly requested external retrieval can use the network.

The React application does not implement a separate scientific decision tree. It sends the conversation thread ID and user request to the Python service, which invokes the same LangGraph interaction and analysis runtime used by the CLI. The browser is responsible for presentation, streaming progress, and user controls; the backend remains responsible for intent, planning, tool selection, execution, verification, and replanning.

liquid-agent, liquid-agent web and liquid-agent client all open the local agent workspace directly at /#/agent.

• Public website: publish the homepage and Docs to GitHub Pages for visitors to browse before installation. Try it always opens Getting Started > Installation in the saved Docs language. No local-service probing is performed.
• Local application: launch the installed workspace with liquid-agent web. Use liquid-agent wiki (also liquid-agt wiki or liq wiki) to open the separately deployed public homepage and Docs. In the interactive CLI, type wiki or /wiki; portal remains a compatible alias.

Portal

The public portal uses a dark, full-screen water homepage with concise navigation:

Portal pages are English-only and have no language switch. Visiting the portal preserves your saved Docs and local workspace language preferences.

• Explore (/#/explore) introduces the liquid-biopsy workspace with a research workflow and a demo that can be stopped or played.
• Our story (/#/story) presents the scientific background and research ambition, with links to the University of Leicester's source material.
• Docs provides installation, feature guides, usage instructions and illustrated workflow examples in English and Simplified Chinese.
• Try it opens the Installation page in your saved Docs language, where the existing Join the Waitlist button provides the early-access application path.
• The footer links to user guides, examples, the public portal repository and the Terms of Use.

The water background can be paused. Reduced-motion preferences show a still image until playback is explicitly requested; a still image is also available if the video cannot play. The portal does not run an analysis or automatically open a local workspace. After receiving access and installing the software, launch the local workspace with liquid-agent web.

Older gallery, guide and about bookmarks lead to the relevant Docs page or the new Explore and Our story pages.

Interface Language

The public portal always displays English and has no language selector. Its Docs links follow your saved documentation language without changing it.

Select English or Chinese in Docs or the local workspace header. Expand the left workspace panel first if it is collapsed. English is the default for the workbench and language-neutral Docs entry, even with a Chinese browser or operating system. Chinese is an explicit option. The browser remembers your choice across pages and reloads and synchronises it between tabs on the same origin. Returning from the English portal preserves that choice. A publicly hosted Docs site and the localhost app have separate browser preferences.

Switching language does not reload the page, create a new conversation, clear a draft, change the GPT model, or interrupt a running task. If browser storage is blocked, switching still works for the current page. CLI output stays English.

This setting translates interface copy, navigation, dialogs, built-in skill names, status labels and controls, not scientific content. It does not set the Agent's response language or add a language instruction to model requests. The model chooses its language from the conversation and your instructions. User messages, GPT responses, report text, tables, figure labels, runtime skill documents, file paths and commands remain unchanged. You may ask GPT to answer in Chinese independently of this setting; no automatic translation call or extra data upload is performed.

Colour Themes

Use Colour theme alongside LIQUID-Agent in the local workspace header. The available palettes are Soft sage (default), Soft rose, Light blue, and Warm stone. The public portal uses its own fixed dark appearance. Expand the left workspace panel to reach the selector when the panel is collapsed.

Only interface colours change: backgrounds, borders, text accents, and controls. Panel layout, conversation state, analysis settings, and the colours encoded in scientific figures do not change. Selecting a theme makes no LLM request and does not restart the service or run an analysis.

The preference is stored in this browser for the current site address, survives reloads, and synchronises between open tabs on that same address. Different browsers, ports, and devices have separate preferences. Clearing site storage restores Soft sage; if storage is disabled, a selection still works for the current page but cannot be remembered after a reload. Local font assets are bundled with the interface rather than downloaded from an external font service.

Sidebar and Trash

The workspace heading is LIQUID-Agent. Compact language and colour selectors sit alongside it at the default desktop width and wrap when the sidebar is too narrow. Trash is a compact disclosure card: open it to restore a conversation or request permanent deletion. There is no separate idle/status footer.

Skills use compact, single-line rows. The small group arrow expands the hierarchy; the name opens the full guidance. Long names pan on hover or keyboard focus only when they overflow; widening the sidebar removes the need to pan. The full name also remains in the tooltip. Reduced-motion preferences disable this animation.

Selecting a skill opens a separate reading column between the workspace and the conversation, with a sliding transition. On desktop, the conversation and results narrow proportionally without changing their saved widths. Close with the upper right cross or Escape. Small buttons below the document open its references or ask GPT to discuss the selected skill. The guidance page shows no reload/overview button; Back to skill guidance appears only when a reference document is open. The current reference never links to itself; only other references remain available. Reading a skill or its references is local and does not run an analysis or call GPT. Discussion is a normal model-backed conversation turn, not permission to execute the skill. On phones, the reader is a sliding sheet instead of four unreadably narrow columns.

Save a reusable note stores a user-authored method rule or personal preference for later tasks, separately from the maintained project skills. Learn from a file, folder, or URL extracts reusable guidance from reference documents; it does not install an analysis engine or analyse a dataset. Use non-sensitive reference material rather than patient measurements. These optional controls are not needed to use the built-in skills.

Desktop Sources, Skills and Plan expand upwards, so a closed panel shows an up arrow and an open panel shows a down arrow. Results expand downwards and use the opposite arrows. On mobile, Sources and Skills follow downward document flow and their arrows adapt accordingly.

Conversation indices are stored at <data-root>/.liquid-agent/conversation-index/:

active/<chat-hash>.json
trash/<chat-hash>.json
deleted/<chat-hash>.json

Moving to Trash transfers the full index, including its saved UI snapshot, from active to trash. After active writers stop, the entire conversation-owned output tree (including intermediate files, reports, figures and uploads) moves to <data-root>/.liquid-agent/trash/conversations/<chat-hash>/. With a custom output root, Trash sits alongside that root under trash/conversations/ on the same disk. Original dataset files and other conversations stay in place. Restore moves the owned tree back to its original paths and restores the index. Permanent deletion removes the full index, owned results/uploads and runtime history; deleted retains only a hash-named guard with no messages, titles, paths or results to reject delayed requests.

Private Codex history and LangGraph checkpoints also live under <data-root>/.liquid-agent/. Restart the local service after upgrading; do not run old and new service versions concurrently during migration. Existing configuration- directory indices and runtime state migrate without relocating raw inputs or existing output directories. Skills and API-key configuration do not move to the data disk. LIQUID_BIOPSY_TASK_STATE_ROOT can explicitly override the state root. Without an explicit data-root override, a small configuration pointer remembers the chosen disk; if that disk disappears, reconnect it instead of silently creating a second local task store. Offline storage returns a readable, retryable error. On reopening or refocusing the page, cached task IDs are reconciled with disk Trash/deletion records so removed tasks cannot return from an old browser cache. If a dataset cannot be restored, cached results and plans are not shown as active.

Agent Console

Run liquid-agent web to open the agent console directly. The console is designed around three lightweight regions:

• a left workspace panel for chats, attached Sources, the compact Metadata card, and local Skills/preferences
• a central conversation panel for natural-language interaction, live workflow status, and final run summaries
• a right workspace panel for Results and Plan history, including readable reports, embedded figures, key markdown tables, generated artifacts, and archived plan versions

The side panels are resizable. Conversations and lightweight UI state are saved in browser local storage, so reopening the app restores the local chat/workspace view when possible.

After Run next step completes, the client refreshes result artifacts and regenerates the next plan automatically. The preview area is markdown-first: the selected run report is the main user-facing artifact, with key result tables and static PNG figures rendered inside the report when available. Backend JSON/TXT artifacts and generated HTML pages are hidden from the default user view unless they are needed for audit, follow-up, or developer inspection. Ledger artifacts such as plan records, result evaluations, and analysis_concept_book.json remain available to the backend and CLI follow-up path, but they do not create extra UI modes.

Plan and result follow-up answers summarize plan state, task execution, verification, QC, findings, follow-ups, and backend recommendation audits in plain language instead of exposing raw JSON. When the LLM is disabled or temporarily unavailable, local fallback guidance chooses the next suggested action from artifact type and scan state.

Install

Recommended local install:

./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data"

Equivalent terminal form:

./scripts/install_liquid_agent_cli.sh --user-data-dir "$HOME/Liquid Agent Data"

Then run:

liquid-agent web
liquid-agent client

After early-access approval, choose the local installation or launch command:

Path	Use it when	Command
One-click Mac	a local user opens the file from Finder and enters the user data directory when prompted	./install_liquid_agent.command
Terminal install	a workstation or remote shell needs explicit setup logs	./scripts/install_liquid_agent_cli.sh --user-data-dir "$HOME/Liquid Agent Data"
Web workspace	an installed user wants to chat, attach data, and analyse	liquid-agent web
Direct work	a returning user wants the agent workspace immediately	liquid-agent client

The launcher calls the same Python analysis kernel behind the scenes. The installer captures the active user environment, so users do not need to activate that environment before running liquid-agent web or liquid-agent client. Use LIQUID_AGENT_ENV=<env> only if you intentionally want another conda environment.

One-Click Launcher

On macOS, the repository also includes:

start_liquid_web.command

Double-clicking that file starts the local server through the same npm launcher and opens the browser. The server is configured for local use and shuts down after the browser page is closed.

Stopping a task is different from closing the page: a stop request terminates the active scientific child process group and leaves the local service available for the next message or an explicit resume. Closing the final local client page shuts down the service and its active jobs so no analysis process is left behind.

Browser Commands

liquid-web
liquid-client

liquid-web aliases liquid-agent web; liquid-portal aliases liquid-agent portal. liquid-client is an npm alias for liquid-agent client. By default the local app listens on http://127.0.0.1:8765 with API routes under /api/.... Both browser commands open the browser automatically unless --no-open is passed or LIQUID_AGENT_NO_OPEN=1 is set.

Use a different port when needed:

liquid-agent web --port 8771
liquid-agent client --port 8771

How To Work In The Agent Console

After installation, run liquid-agent web or liquid-agent client. The browser opens the workspace directly. Start from New chat; the app asks whether to bind a dataset immediately:

• choose a folder with the native folder picker when the data path is known
• paste a path manually when the folder picker is not available
• choose Set up later for pure chat or orientation questions

If a later chat message clearly identifies a dataset path, the UI creates or updates the corresponding dataset workspace and associates the conversation with that workspace.

The left Sources card shows the data folders explicitly attached by the user. Selecting a parent folder is displayed as one user source; the kernel may still inspect internal subfolders or sub-cohorts for analysis planning without turning the sidebar into a confusing list of internal partitions. Explicit multi-source analysis is still supported by adding multiple folders. Removing a source detaches it from the session and never deletes source data.

Adding a source performs a lightweight scan and writes a short chat summary: what was attached, how many files were scanned, whether metadata labels were selected, and whether a plan has already been started. The user can then ask for a plan, type /plan, or continue naturally. A run cannot be started until a real plan exists.

After a source is attached and scanned, the conversation header exposes Method advice. This writes a method-advice report for the current source set, refreshes the result artifacts, and adds a short chat summary with the top matched methods and the report path.

The compact Metadata card appears below Sources when metadata or label state is known. It shows the selected label, coverage, planning mode, backend, confidence, and Change/Ignore controls. The card intentionally does not show a full spreadsheet; detailed label selection belongs in the Change dialog or the CLI /metadata command.

Existing conversations can be selected, deleted, or rebound to a dataset. The bind action is intentionally small and appears with the other hover actions on a conversation row.

LLM Selection

The composer model button uses the available model catalog: OpenAI GPT by default, with optional Gemini 3.8 Flash. GPT-6 Luna (auto) is the default; GPT-6 Sol and GPT-6 Astra are explicit higher-cost choices. The current model cannot be changed while an operation is busy. Manage keys opens a provider-selectable dialog for adding, replacing, or deleting the key. A failed save keeps the dialog open and shows the error.

Credentials are kept in an owner-only local file, never in browser storage. Deletion disables subsequent requests, including from existing clients, without falling back to an environment key. An already submitted OpenAI request cannot be retroactively unsent. Gemini has a separate key and a free-tier/privacy notice before activation; use public or non-sensitive synthetic data only. See OpenAI configuration.

Conversation Behavior

• Enter submits a prompt.
• During Chinese/Japanese/Korean IME composition, Enter first confirms the composed text instead of submitting the prompt.
• Shift+Enter or Ctrl+Enter inserts a newline.
• While the assistant is responding, the send button becomes a stop button and new submissions are blocked.
• User messages can be edited. Save and resend truncates later messages and asks the assistant again from that edited point; it is not a local-only save. The editor receives keyboard focus and uses readable theme colours. Cancel or Escape discards the draft without changing the original message; blank edits cannot be submitted.
• The UI shows transformed progress summaries and loading indicators. It does not expose private model chain-of-thought.
• When a plan or long run is active, the status card stays near the bottom of the conversation area. Recent working notes are shown as a bounded, transient live feed instead of accumulating as permanent chat bubbles.
• The stop control requests cancellation through the backend job endpoint. The current safe checkpoint can finish before the run exits, and the completed report records whether the run stopped, completed, or blocked.

Results Panel

The right panel stays compact until needed. After scanning or running a task it can show:

• result history grouped by run or report
• the selected markdown report with embedded key tables and static figures
• plan history from assistant/ledger/plan_*.json
• the current runnable plan and archived previous plans
• generated artifacts when the report links to them or the user needs audit
• image previews for generated figures
• result history, hide/restore, and safe deletion for generated output files
• method-advice reports when the user asks which tools, research methods, or assay-specific routes fit the dataset

Deleting a generated report from Results also removes the associated generated files recorded in the report metadata when those files are inside recognized Liquid Agent output folders. It does not delete original source data.

The panel can be dragged wider when inspecting tables or plots.

Figures in reports and individual image results have an embedded image viewer. Use Zoom in / Zoom out, or click the percentage to reset the zoom. The top-right Fit to width / Fit to height button switches between a detailed width-filling view and a height-filling overview with a smooth transition. Scroll or drag enlarged figures to inspect them. With the image area focused, + / - zoom, 0 resets, and F switches the fit. Reduced-motion preferences are respected. Choose folder opens a folder browser at the configured data root. Double-click a folder (or use its arrow) to browse inside; select a folder and click Open to attach it. System folder picker… remains available for locations outside the data root. Cancelling leaves the conversation unchanged.

Data root

Paths are resolved the same way as the CLI: set LIQUID_BIOPSY_DATA_ROOT (or use the optional data_root field when creating a session via the API) for stable defaults. Absolute user-selected folders can also be attached directly; relative dataset names are resolved under the configured data root.

For example, a user may point the data root at any mounted folder:

/path/to/your/liquid-agent-data

On ordinary user machines without that disk, Liquid Agent falls back to a local application-data folder unless LIQUID_BIOPSY_DATA_ROOT is set.

The UI also supports working without the data disk for pure chat, orientation, LLM setup, and documentation-style questions.

Notes

• Full scan / autopilot paths load the same Python stack as the assistant, including optional model and file-IO dependencies when those extras are installed in the kernel environment.
• The web layer calls the same autopilot engine as the interactive shell, with optional event_callback / cancel_event hooks for streaming progress.
• Source-management API routes are available under /api/session/{session_id}/sources for local UI integrations.
• Web result routes are available under /api/session/{session_id}/results, /api/session/{session_id}/file, and /api/session/{session_id}/artifact. The delete route only removes files already recognized as generated Liquid Agent outputs for the current session.
• Long runs use /api/session/{session_id}/autopilot, /api/jobs/{job_id}/events, and /api/jobs/{job_id}/cancel for streaming status and safe stopping.
• The browser state is local to the browser profile. Clearing browser storage removes saved chats and UI layout state but does not delete analysis outputs on disk.

Task activity and reviewed skills

A spinning circle beside a task means it is running. If it finishes while you are in another conversation, a blue dot remains until you open that conversation. The dot means that the task needs your attention, not necessarily that it succeeded: read the final response for failure or cancellation. Sources attached to a running task have an accent border; this does not imply that every attached dataset is being computed at that instant.

Skill changes stays at the turn that produced the draft, including after acceptance or rejection. Later messages scroll it into history. Pending changes also have small green check/red cross actions at the right end of the corresponding Skills row. Click the skill name to review the diff. These indicators apply to the selected conversation; open the relevant task to review its drafts.

See the illustrated workspace walkthrough for current full-interface screenshots, key management, multi-image questions, and the workflow from Plan to Results.

Follow a real operation, not just a feature list

The GSE174302 walkthrough follows one study through folder selection, metadata checking, skill reading, plan approval, six scientific jobs, Results actions, mapped PCA questions, a two-figure follow-up, skill accept/reject and corrected reporting. A separate image-only chat demonstrates uploading two real PNGs; it also supplies the Trash/restore example. Every new screenshot comes from that actual API-backed browser session.

For individual steps, use image and selection screenshots and skill-review screenshots. Additional assay prompts in the scenario collection are labelled as templates where they were not executed here.

Compact sidebar states

The expanded left sidebar shows the LIQUID-Agent logo button. Collapsing it replaces the logo with an expand-panel icon; beneath it a single + starts a new task. Task selection controls are hidden in this narrow state. Clicking Trash expands the sidebar to show the full recycle-bin list. Expand the sidebar to select and link tasks. The sidebar widths remain your saved widths across refreshes.