Skip to content

feat: Add bundled React webview CLI for local file visualization #2107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions webview-poc/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: dist/ appears multiple times in the file (line 56). Consider consolidating these entries to avoid confusion.

downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# Virtual environments
venv/
env/
ENV/
env.bak/
venv.bak/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Node.js
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

# React/Vite
dist/
dist-ssr/
*.local

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# Logs
logs/
*.log

# Coverage
coverage/
*.lcov

# ESLint
.eslintcache

# Prettier
.prettierignore

# TypeScript
*.tsbuildinfo

# Temporary files
*.tmp
*.temp

# Built frontend bundle (generated by build script)
js-bundle/
133 changes: 133 additions & 0 deletions webview-poc/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Ragas Webview CLI

A web-based file viewer with React frontend and Python backend. Easily spin up a web interface to browse and view local project files.

## Features

- 🚀 **Standalone CLI** - Single command to start web server
- ⚛️ **React Frontend** - Modern web interface for file browsing
- 🐍 **Python Backend** - FastAPI server with file serving capabilities
- 🔄 **Development Mode** - Hot reload for both frontend and backend
- 📦 **Production Ready** - Bundled React app served by Python server

## Installation

### Using uv (recommended)

```bash
# Install with uv
uv add ragas-webview-cli

# Or install from local directory
cd webview-poc
uv sync
```

### Using pip

```bash
pip install ragas-webview-cli

# Or install from local directory
cd webview-poc
pip install -e .
```

## Usage

### Production Mode (Bundled)

```bash
# Start the webview server
uv run ragas-webview-cli --port 8000 --host 127.0.0.1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: The CLI example shows different formats (--port vs module). Consider using consistent examples to avoid confusion.


# Or use Python directly
uv run python -m ragas_webview_cli.cli --port 8000
```

### Development Mode

```bash
# Run both React dev server and Python API server
uv run python scripts/dev.py

# This starts:
# - React dev server on http://localhost:3000 (with hot reload)
# - Python API server on http://localhost:8000
```

### Building React Bundle

```bash
# Build React app for production
uv run python scripts/build.py

# Or build directly with npm
cd ragas-webview
npm run build:bundle
```

## Development Setup

### Prerequisites

- Python 3.9+
- Node.js 18+
- uv (recommended) or pip

### Setup

```bash
# Clone and setup with uv
git clone <repo>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: Replace placeholder <repo> with actual repository URL.

Suggested change
git clone <repo>
git clone https://github.com/explodinggradients/ragas

cd webview-poc
uv sync

# Install React dependencies
cd ragas-webview
npm install
cd ..

# Run development environment
uv run python scripts/dev.py
```

## Project Structure

```
webview-poc/
├── README.md
├── pyproject.toml # ← Package configuration
├── uv.lock # ← UV lock file
├── js-bundle/ # ← Built React app (not packaged)
├── ragas-webview/ # ← React source (not packaged)
├── scripts/ # ← Development scripts (not packaged)
│ ├── dev.py # ← Development server script
│ └── build.py # ← Build script
└── ragas_webview_cli/ # ← Main package (packaged in pip)
├── __init__.py
├── cli.py # ← CLI entry point
├── config.py # ← Configuration
└── server.py # ← FastAPI server
```

## Configuration

All server ports and hosts are configured in `ragas_webview_cli/config.py`:

```python
BACKEND_PORT = 8000
FRONTEND_PORT = 3000
BACKEND_HOST = "127.0.0.1"
FRONTEND_HOST = "127.0.0.1"
```

## API Endpoints

- `GET /` - Serves React app (production) or API info (development)
- `GET /api/health` - Health check endpoint
- `GET /assets/*` - Static assets (CSS, JS, images)
Comment on lines +127 to +129
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: API endpoints section is incomplete. Missing dataset and file endpoints mentioned in the PR description.


## License

MIT License
63 changes: 63 additions & 0 deletions webview-poc/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
[project]
name = "ragas-webview-cli"
version = "0.1.0"
description = "Web-based file viewer with React frontend and Python backend"
readme = "README.md"
requires-python = ">=3.9"
authors = [
{name = "Ragas Team", email = "[email protected]"}
]
keywords = ["webview", "file-viewer", "react", "fastapi"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
]

dependencies = [
"fastapi>=0.100.0",
"uvicorn[standard]>=0.23.0",
"typer>=0.9.0",
]

[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-asyncio>=0.21.0",
"httpx>=0.24.0", # For testing FastAPI
"black>=23.0.0",
"ruff>=0.1.0",
]
Comment on lines +27 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: redundant dev dependencies definition (same deps in [tool.uv])


[project.scripts]
ragas-webview-cli = "ragas_webview_cli.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["ragas_webview_cli"]
Comment on lines +43 to +44
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: no include_package_data or manifest configuration for React bundle


[tool.uv]
dev-dependencies = [
"pytest>=7.0.0",
"pytest-asyncio>=0.21.0",
"httpx>=0.24.0",
"black>=23.0.0",
"ruff>=0.1.0",
]

[tool.ruff]
select = ["E", "F", "I"]
ignore = ["E501"]
line-length = 88
target-version = "py39"

[tool.black]
line-length = 88
target-version = ["py39"]
24 changes: 24 additions & 0 deletions webview-poc/ragas-webview/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
dist
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
69 changes: 69 additions & 0 deletions webview-poc/ragas-webview/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# React + TypeScript + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
Comment on lines +1 to +8
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: Replace generic Vite template README with Ragas Webview specific documentation including setup instructions and usage examples

Suggested change
# React + TypeScript + Vite
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
Currently, two official plugins are available:
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
# Ragas Webview
A bundled React webview CLI for local file visualization in the Ragas project.
## Overview
This React + TypeScript application provides a web interface for viewing and analyzing local files generated by Ragas. It includes both development mode (separate servers) and production mode (bundled React served by Python).
## Usage
```bash
# Install the package
pip install ragas
# Generate files with main project
ragas --input data.json --output results/
# View results in browser
load-webview --data-dir results/


## Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

```js
export default tseslint.config([
globalIgnores(['dist']),
{
files: ['**/*.{ts,tsx}'],
extends: [
// Other configs...

// Remove tseslint.configs.recommended and replace with this
...tseslint.configs.recommendedTypeChecked,
// Alternatively, use this for stricter rules
...tseslint.configs.strictTypeChecked,
// Optionally, add this for stylistic rules
...tseslint.configs.stylisticTypeChecked,

// Other configs...
],
languageOptions: {
parserOptions: {
project: ['./tsconfig.node.json', './tsconfig.app.json'],
tsconfigRootDir: import.meta.dirname,
},
// other options...
},
},
])
```

You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config([
globalIgnores(['dist']),
{
files: ['**/*.{ts,tsx}'],
extends: [
// Other configs...
// Enable lint rules for React
reactX.configs['recommended-typescript'],
// Enable lint rules for React DOM
reactDom.configs.recommended,
],
languageOptions: {
parserOptions: {
project: ['./tsconfig.node.json', './tsconfig.app.json'],
tsconfigRootDir: import.meta.dirname,
},
// other options...
},
},
])
```
Loading
Loading