Merge branch 'main' into jennyyangyi-magic-patch-1

Author: markurtz

.github/workflows/development.yml

@@ -1,7 +1,7 @@
 name: Development
 
 on:
-  pull_request:
+  pull_request_target:
     types: [opened, synchronize, reopened]
 
 jobs:
@@ -21,6 +21,20 @@ jobs:
       - name: Run quality checks
         run: tox -e quality
 
+  ui-quality-checks:
+    permissions:
+      contents: "read"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run quality and typing checks
+        run: npm run lint
+
   type-checks:
     runs-on: ubuntu-latest
     strategy:
@@ -37,6 +51,20 @@ jobs:
       - name: Run quality checks
         run: tox -e types
 
+  ui-type-checks:
+    permissions:
+      contents: "read"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run quality and typing checks
+        run: npm run type-check
+
   precommit-checks:
     runs-on: ubuntu-latest
     strategy:
@@ -51,7 +79,21 @@ jobs:
       - name: Install dependencies
         run: pip install pre-commit
       - name: Run pre-commit checks
-        run: pre-commit run --all-files
+        run: SKIP=ruff-format pre-commit run --all-files
+
+  ui-precommit-check:
+    permissions:
+      contents: "read"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run pre-commit checks
+        run: npx husky run pre-commit
 
   unit-tests:
     runs-on: ubuntu-latest
@@ -69,6 +111,20 @@ jobs:
       - name: Run unit tests
         run: tox -e test-unit -- -m "smoke or sanity"
 
+  ui-unit-tests:
+    permissions:
+      contents: "read"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit
+
   integration-tests:
     runs-on: ubuntu-latest
     strategy:
@@ -85,6 +141,20 @@ jobs:
       - name: Run integration tests
         run: tox -e test-integration -- -m smoke
 
+  ui-integration-tests:
+    permissions:
+      contents: "read"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run integration tests
+        run: npm run test:integration
+
   build:
     runs-on: ubuntu-latest
     strategy:

.github/workflows/main.yml

@@ -52,7 +52,7 @@ jobs:
       - name: Install dependencies
         run: pip install pre-commit
       - name: Run pre-commit checks
-        run: pre-commit run --all-files
+        run: SKIP=ruff-format pre-commit run --all-files
 
   unit-tests:
     runs-on: ubuntu-latest

.gitignore

@@ -178,3 +178,53 @@ cython_debug/
 # Project specific files
 *.json
 *.yaml
+
+# But not scenarios
+!src/guidellm/benchmark/scenarios/*.json
+!src/guidellm/benchmark/scenarios/*.yaml
+
+# UI Section - Next.js/React application under src/ui/
+# dependencies
+/node_modules/
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+coverage/
+
+# next.js
+/src/ui/.next/
+/src/ui/out/
+
+# production
+build/
+
+# misc
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# vercel
+src/ui/.vercel
+
+# typescript
+*.tsbuildinfo
+src/ui/next-env.d.ts
+
+# Root-level UI config files that should be tracked
+!package.json
+!package-lock.json
+!tsconfig.json
+!tsconfig.*.json
+!src/ui/lib
+!src/ui/public/manifest.json
+.eslintcache

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.pre-commit-config.yaml

@@ -8,6 +8,10 @@ repos:
   rev: v0.11.7
   hooks:
     - id: ruff
+      name: run linter
+      args: [ --fix, --show-fixes ]
+    - id: ruff-format
+      name: run formatter
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: v1.15.0
   hooks:

.prettierignore

@@ -0,0 +1,18 @@
+# === Don't touch ===
+*.md
+*.mdx
+*.yaml
+*.yml
+
+# === Skip all JSON …
+*.json
+
+# === include relevant json ===
+!src/ui/**/*.json
+!tests/ui/**/*.json
+
+# Root-level configs to format
+!/.eslint.config.js
+!/tsconfig*.json
+!/*.config.{js,ts}
+!/jest.setup.ts

.prettierrc

@@ -0,0 +1,12 @@
+{
+  "arrowParens": "always",
+  "bracketSameLine": false,
+  "bracketSpacing": true,
+  "jsxSingleQuote": false,
+  "printWidth": 88,
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "useTabs": false
+}

DEVELOPING.md

@@ -179,6 +179,94 @@ Review the coverage report to confirm that your new code is adequately tested.
 
 3. **Address Feedback**: Respond to any feedback from reviewers and make necessary changes.
 
+## Developing the Web UI
+
+The GuideLLM project includes a frontend UI located in `src/ui`, built using [Next.js](https://nextjs.org/). This section provides instructions for working on the UI.
+
+### Getting Started
+
+First, install dependencies:
+
+```bash
+npm install
+```
+
+Then, start the local development server:
+
+```bash
+npm run dev
+```
+
+Then open [http://localhost:3000](http://localhost:3000) in your browser.
+
+### Building for Production
+
+To build the app for production (output in the `out` directory):
+
+```bash
+npm run build
+```
+
+### Running UI Tests
+
+- **Unit tests**:
+
+  ```bash
+  npm run test:unit
+  ```
+
+- **Integration tests**:
+
+  ```bash
+  npm run test:integration
+  ```
+
+- **Integration+Unit tests with coverage**:
+
+  ```bash
+  npm run coverage
+  ```
+
+- **End-to-end tests** (using Cypress, ensure live dev server):
+
+  ```bash
+  npm run test:e2e
+  ```
+
+### Code Quality and Styling
+
+- **Fix styling issues**:
+
+  ```bash
+  npm run format
+  ```
+
+- **Run ESLint checks**:
+
+  ```bash
+  npm run lint
+  ```
+
+- **Run TS type checks**:
+
+  ```bash
+  npm run type-checks
+  ```
+
+##### Tagging Tests
+
+Reference [https://www.npmjs.com/package/jest-runner-groups](jest-runner-groups) Add @group with the tag in a docblock at the top of the test file to indicate which types of tests are contained within. Can't distinguish between different types of tests in the same file.
+
+```
+/**
+ * Admin dashboard tests
+ *
+ * @group smoke
+ * @group sanity
+ * @group regression
+ */
+```
+
 ## Additional Resources
 
 - [CONTRIBUTING.md](https://github.com/neuralmagic/guidellm/blob/main/CONTRIBUTING.md): Guidelines for contributing to the project.

README.md

@@ -153,6 +153,48 @@ The `guidellm benchmark` command is used to run benchmarks against a generative
 
 - `--output-path`: Defines the path to save the benchmark results. Supports JSON, YAML, or CSV formats. If a directory is provided, the results will be saved as `benchmarks.json` in that directory. If not set, the results will be saved in the current working directory.
 
+### GuideLLM UI
+
+GuideLLM UI is a companion frontend for visualizing the results of a GuideLLM benchmark run.
+
+### 🛠 Running the UI
+
+1. Use the Hosted Build (Recommended for Most Users)
+
+After running a benchmark with GuideLLM, a report.html file will be generated (by default at guidellm_report/report.html). This file references the latest stable version of the UI hosted at:
+
+```
+https://neuralmagic.github.io/guidellm/ui/dev/
+```
+
+Open the file in your browser and you're done—no setup required.
+
+2. Build and Serve the UI Locally (For Development) This option is useful if:
+
+- You are actively developing the UI
+
+- You want to test changes to the UI before publishing
+
+- You want full control over how the report is displayed
+
+```bash
+npm install
+npm run build
+npx serve out
+```
+
+This will start a local server (e.g., at http://localhost:3000). Then, in your GuideLLM config or CLI flags, point to this local server as the asset base for report generation.
+
+### 🧪 Development Notes
+
+During UI development, it can be helpful to view sample data. We include a sample benchmark run wired into the Redux store under:
+
+```
+src/lib/store/[runInfo/workloadDetails/benchmarks]WindowData.ts
+```
+
+In the future this will be replaced by a configurable untracked file for dev use.
+
 ## Resources
 
 ### Documentation

cypress.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  e2e: {
+    specPattern: 'tests/ui/cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
+    supportFile: 'tests/ui/cypress/support/e2e.ts',
+    baseUrl: 'http://localhost:3000', // optional
+  },
+});