From a874e0681b496ae4c45863f39859a741a45ea976 Mon Sep 17 00:00:00 2001 From: Xi Zhang Date: Wed, 10 Jun 2026 22:42:16 +0100 Subject: [PATCH] Initial --- CONTRIBUTING.md | 115 ++++++++++++++++++++++++++++++++ README.md | 172 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 243 insertions(+), 44 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e35a9c8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,115 @@ +# Contributing to EvoScientist WebUI + +We appreciate your interest and the time you spend helping improve the EvoScientist WebUI. Please read the following guidelines before contributing. + +## How you can contribute + +- **Report bugs and request features:** open an issue describing the problem, steps to reproduce, and your environment (Node version, backend version). +- **Propose design changes:** use issues to outline the problem, alternatives, and trade-offs before implementing. +- **Contribute code or docs:** submit PRs that address an open issue, with a clear rationale. + +## The zero-touch-backend principle + +> [!IMPORTANT] +> The WebUI is a **runtime client only**. It must work against an unmodified EvoScientist backend — it talks to a running deployment over the LangGraph SDK and thin same-origin `/api/` routes, and never requires changes to the EvoScientist repo. Keep all new features within this constraint (the one sanctioned exception, the `webui` launch mode, already lives in EvoScientist). + +## Prerequisites + +- **Node.js 20+**. +- A running **EvoScientist backend** (the LangGraph deployment). From your EvoScientist install: + ```bash + EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174 + ``` + Keep it running in its own terminal. + +## Development setup + +1. **Fork and clone** the repository: + ```bash + git clone https://github.com//EvoScientist-WebUI.git + cd EvoScientist-WebUI + ``` + +2. **Install dependencies** (package manager is **npm**): + ```bash + npm install + ``` + +3. **Start the dev server:** + ```bash + npm run dev + ``` + Open . In the configuration dialog, enter your **Deployment URL** (default `http://127.0.0.1:6174`) and click **Save**. + +> You need two things running: the EvoScientist backend (`EvoSci deploy`, port `6174`) and this UI (`npm run dev`, port `4716`). + +## Scripts + +| Command | Description | +| ---------------------- | --------------------------------------- | +| `npm run dev` | Start the dev server on port 4716 | +| `npm run build` | Production build + assemble `dist/` | +| `npm start` | Serve the production build on port 4716 | +| `npm run start:dist` | Run the assembled standalone `dist/` | +| `npm run lint` | Lint with ESLint | +| `npm run lint:fix` | Lint and auto-fix | +| `npm run format` | Format with Prettier | +| `npm run format:check` | Check formatting (used in CI) | + +## Production build + +```bash +npm run build # next build + assemble standalone into dist/ +npm start # serves the production build on http://localhost:4716 +``` + +## Project structure + +```txt +EvoScientist-WebUI/ + bin/ # npx launcher (evoscientist-webui.mjs → dist/server.js) + scripts/ # assemble-standalone.mjs (packs dist/, strips *.map) + src/ + app/ + api/ # thin same-origin server routes + evosci-config/ # detect backend port + skills/ # install / list / remove skills + memory/ # read / edit global memory + workspace/ # browse / edit / download files + components/ # React components (chat, panels, dialogs) + hooks/ # useChat, useThreads, useAsyncAgents, … + page.tsx # multi-view shell (routes via nuqs) + components/ # shared UI primitives + lib/ # client + server helpers (asyncAgents, memory, …) + server/ # server-only fs helpers with path guards + providers/ # Theme / Client providers +``` + +## Architecture & connection contract + +Three independent layers: + +1. **Frontend** (Next.js standalone, port `4716`) — browser connects directly to the LangGraph backend; pure client-side chat + streaming. +2. **Next `/api/` routes** (server tool layer, same-origin) — the reason distribution is `output: "standalone"` rather than a static export. +3. **Backend** (EvoScientist's `langgraph dev`, default port `6174`) — the anchor process: runs async agents, holds state, serves the SDK. + +The backend exposes graphs `EvoScientist` (main, UI-locked), `writing-agent`, `data-analysis-agent`, and the `evomemory` workers. The UI filters thread lists by `metadata.graph_id == "EvoScientist"` so worker/sub-agent threads stay hidden. + +## Code style + +- **TypeScript** — keep `npm run lint` (ESLint) clean and run `tsc --noEmit` before pushing. +- **Formatting** — `prettier --check .` must pass (run `npm run format` to fix). +- **Tailwind gotcha:** this project's `tailwind.config.mjs` overrides named tokens like `bg-primary`/`text-primary` to undefined LangSmith vars, so those classes render transparent. Use arbitrary values such as `bg-[var(--brand-solid)]` instead, and never apply a `/NN` opacity modifier to a `var()`-based color (it silently drops the declaration). +- Follow the existing patterns and conventions in the area you're modifying; keep changes minimal and focused. + +## Submitting a pull request + +1. Create a branch from `main` with a descriptive name (e.g. `fix/stream-tail`, `feat/command-palette`). +2. Make your changes, keeping commits focused. Use semantic prefixes: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`. +3. Ensure `npm run lint`, `tsc --noEmit`, and `npm run format:check` pass locally — these also run in CI. +4. Open a PR against `main` describing what changed and why. Include screenshots or screen recordings for any UI change. +5. A maintainer will review your PR. Please be responsive to feedback. + +## Need help? + +Open an [issue](https://github.com/EvoScientist/EvoScientist-WebUI/issues) if you have a question or run into a problem. diff --git a/README.md b/README.md index e38216d..7dfdf28 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,150 @@ -# EvoScientist WebUI +# 🌐 EvoScientist WebUI -Web UI for **EvoScientist** — a self-evolving AI scientist built on DeepAgents/LangGraph. +**The desktop-level browser workspace for [EvoScientist](https://github.com/EvoScientist/EvoScientist), designed to make Vibe Research feel natural. By bringing evolving memory, research skills, multi-agent workflows, and workspace management together in one place, it helps researchers spend less time managing information and more time exploring ideas — so scientific discovery can move faster.** -The browser connects directly to a running EvoScientist deployment and gives you a -chat interface with streaming responses, tool calls, sub-agent activity, files, and tasks. +
-## Prerequisites +npm +Powered by EvoScientist +Next.js 16 +License Apache 2.0 -- **Node.js 20+** -- A running **EvoScientist backend** (the LangGraph deployment). From your EvoScientist - install, start it with: +
- ```bash - EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174 - ``` +--- - Keep this running in its own terminal. + + + + +
+ +
-## Quick start (development) +> [!TIP] +> Looking for the engine behind this UI? Check out [**EvoScientist**](https://github.com/EvoScientist/EvoScientist) — the multi-agent AI scientist — and [**EvoSkills**](https://github.com/EvoScientist/EvoSkills), its ready-to-use research skill packs. This WebUI is a thin, zero-touch client: it talks to a running EvoScientist deployment over the LangGraph SDK and adds **nothing** to your backend. + +## ✨ Features + +- **💬 Streaming Chat** — Real-time responses with Markdown, GFM tables, code highlighting, and collapsible thinking/reasoning blocks. +- **👋 Human-in-the-Loop** — Approve / reject / edit tool calls, and answer the agent's structured questions (text + multiple-choice) inline. +- **⚡ Per-Thread Auto-Approve** — Persisted per conversation; survives view and thread switches and reloads. +- **🤖 Sub-Agent Activity** — Live step tracking for sub-agents, rendered exactly like the main agent (tool calls + paired results + tables). +- **🗂️ Workspace Browser** — Tree and by-type (Papers / Figures / Data / Code) views with preview, edit, download, and zip-all. +- **🧠 Memory Browser** — View, edit, and manage EvoScientist's global cross-session memory, with "recently updated" highlights and a nav badge. +- **🔌 Skills Marketplace** — Install, update, and uninstall the official [EvoSkills](https://github.com/EvoScientist/EvoSkills) catalog with version detection and a detail dialog. +- **📡 Agents Monitor Board** — Watch async background agents (writing / data-analysis) with real run status, live duration, and a side-chat for direct worker debugging. +- **🔁 Async Agent Communication** — Optional per-thread auto-report loops finished background results back to the main agent. +- **🪄 Compaction Summary** — When the backend compacts a long conversation, the summary is shown as a clean collapsible block instead of flashing by. +- **🩺 Connection Health & Resilience** — Health light, stale-URL one-click reconnect, and refresh-resumable streams. +- **🎨 Themed & Responsive** — Light/dark warm "paper" theme with EvoScientist cyan accent; desktop split panes and mobile drawers. + +## 📖 Table of Contents + +- [📦 Prerequisites](#-prerequisites) +- [⚡ Quick Start](#-quick-start) +- [🔑 Configuration](#-configuration) +- [🎨 Designed By](#-designed-by) +- [🤝 Contributing](#-contributing) +- [📚 Acknowledgments](#-acknowledgments) +- [📜 License](#-license) + +## 📦 Prerequisites + +- [**EvoScientist**](https://github.com/EvoScientist/EvoScientist) installed and configured (`EvoSci onboard`). +- **Node.js 20+** — the WebUI mode launches the front-end for you. + +## ⚡ Quick Start + +### Option A — via EvoScientist (recommended) + +The WebUI ships with EvoScientist — just pick it during setup. Run the onboarding wizard and choose **WebUI** as your UI mode: ```bash -npm install -npm run dev +EvoSci onboard # select "WebUI" when asked for the UI mode ``` -Open . In the configuration dialog, enter your **Deployment URL** -(default `http://127.0.0.1:6174`) and click **Save**. That's it — start chatting. - -> You need two things running: the EvoScientist backend (`EvoSci deploy`, port 6174) -> and this UI (`npm run dev`, port 4716). - -## Production build +Then launch EvoScientist as usual — it starts the backend and the WebUI together and opens your browser: ```bash -npm run build # outputs the optimized app -npm start # serves it on http://localhost:4716 +EvoSci # opens http://localhost:4716 ``` -## Configuration +That's it — start chatting. -- **Deployment URL** — the EvoScientist LangGraph endpoint (default `http://127.0.0.1:6174`, - the `EvoSci deploy` default port). Saved in your browser's local storage. -- The UI always talks to the **EvoScientist** main agent; its sub-agents - (`writing-agent`, `data-analysis-agent`) are internal and not user-selectable. -- _(Optional, advanced)_ Set `NEXT_PUBLIC_LANGSMITH_API_KEY` if you connect to a - deployment that requires LangSmith authentication. +### Option B — standalone -## Scripts +Start the EvoScientist backend in one terminal: -| Command | Description | -| ---------------------- | --------------------------------------- | -| `npm run dev` | Start the dev server on port 4716 | -| `npm run build` | Production build | -| `npm start` | Serve the production build on port 4716 | -| `npm run lint` | Lint with ESLint | -| `npm run format` | Format with Prettier | -| `npm run format:check` | Check formatting (used in CI) | +```bash +EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174 +``` -## Tech stack +Then launch the WebUI in another (no install required): -Next.js 16 · React 19 · TypeScript · Tailwind CSS · `@langchain/langgraph-sdk`. +```bash +npx @evoscientist/webui@latest # opens http://localhost:4716 +npx @evoscientist/webui@latest --port 5000 # or pick a custom front-end port +``` -## License +Open the URL, confirm the prefilled **Deployment URL** (auto-detected, default `http://127.0.0.1:6174`), click **Save**, and start chatting. -Apache-2.0 — see [LICENSE](LICENSE). +

🔝Back to top

+ +## 🔑 Configuration + +- **Deployment URL** — the EvoScientist LangGraph endpoint (default `http://127.0.0.1:6174`, the `EvoSci deploy` default port). Saved in your browser's local storage. +- The UI always talks to the **EvoScientist** main agent; its sub-agents (`writing-agent`, `data-analysis-agent`) are internal and not user-selectable. +- _(Optional, advanced)_ Set `NEXT_PUBLIC_LANGSMITH_API_KEY` if you connect to a deployment that requires LangSmith authentication. + +> [!TIP] +> If the backend changes ports, the health light detects the dead connection and offers a one-click **Reconnect** to the newly detected port. + +

🔝Back to top

+ +## 🎨 Designed By + + + + + + + +
+ + Xi Zhang +
+ Xi Zhang + +
+ +

🔝Back to top

+ +## 🤝 Contributing + +We welcome contributions! See the [Contributing Guidelines](./CONTRIBUTING.md) for development setup, project structure, the zero-touch-backend principle, scripts, and the release flow. + +Every contribution brings us one step closer to a future where AI accelerates scientific breakthroughs for all of humanity. + +

🔝Back to top

+ +## 📚 Acknowledgments + +This project builds upon the following outstanding open-source work: + +- [**LangGraph**](https://github.com/langchain-ai/langgraph) — A low-level orchestration framework for building, managing, and deploying long-running, stateful agents. +- [**deep-agents-ui**](https://github.com/langchain-ai/deep-agents-ui) — The LangChain reference UI for deep agents, which this project builds upon. + +We thank the authors for their valuable contributions to the open-source community. + +

🔝Back to top

+ +## 📜 License + +This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. + +

🔝Back to top