chore(deps-dev): bump ajv from 6.12.6 to 6.14.0 in /frontend

.github/workflows/devin-review.yml

@@ -0,0 +1,29 @@
+name: Devin Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  devin-review:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Devin Review
+        # Use script to emulate a TTY as devin-review requires terminal features
+        # The -q flag suppresses script output, -e exits with command exit code,
+        # and -c runs the command. /dev/null discards script's own output.
+        env:
+          CI: true  # Ensures the tool runs in non-interactive CI mode
+        run: |
+          script -q -e -c "npx devin-review ${{ github.event.pull_request.html_url }}" /dev/null

.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"  # Publish on any tag starting with v, e.g., v0.1.0
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Required for hatch-vcs
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      # Build frontend
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm ci
+          npm run build
+          rm -rf ../src/hyperview/server/static
+          mkdir -p ../src/hyperview/server/static
+          cp -r out/* ../src/hyperview/server/static/
+
+      # Build Python package (includes frontend assets)
+      - name: Build
+        run: uv build --no-sources
+
+      # Smoke test: verify the built package can be imported
+      - name: Smoke test (wheel)
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import hyperview; print(f'hyperview {hyperview.__version__}')"
+
+      - name: Smoke test (sdist)
+        run: |
+          uv run --isolated --no-project --with dist/*.tar.gz \
+            python -c "import hyperview; print(f'hyperview {hyperview.__version__}')"
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hyperview
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Publish to PyPI
+        run: uv publish

.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 env/
 venv/
 .venv/
+/uv.lock
 *.egg-info/
 .pytest_cache/
 .coverage
@@ -21,11 +22,6 @@ htmlcov/
 # VS Code
 .vscode/
 
-# Local Context (Agent files)
-.claude/
-CLAUDE.md
-context/
-
 # Generated assets
 assets/demo_animation_frames/
 *.gif
@@ -35,6 +31,9 @@ frontend/node_modules/
 frontend/.next/
 frontend/out/
 
+# Bundled frontend in Python package (built in CI during release)
+src/hyperview/server/static/
+
 # Python package build
 dist/
 build/
@@ -43,3 +42,45 @@ build/
 # Data cache
 *.hf/
 .cache/
+
+# external repo (https://github.com/Hyper3Labs/hyper-scatter)
+hyper-scatter/
+
+# nohup
+nohup.out
+frontend/nohup.out
+
+# Local logs / tool artifacts
+.hyperview-*.log
+.hyperview-*.pid
+.playwright-mcp/
+frontend/tsconfig.tsbuildinfo
+
+# Hyperbolic model zoo (kept as a separate repo)
+hyper_model_zoo/
+hyper_models/
+scripts_ignored/
+
+# AI Context (Agent files)
+.claude/
+context/
+CLAUDE.md
+TASKS.md
+TESTS.md
+AGENTS.md
+**/AGENTS.md
+.github/agents/
+.github/instructions/
+.github/hooks/
+.github/skills/
+.agents/
+.specstory/
+
+# Generated version file (hatch-vcs)
+src/hyperview/_version.py
+
+# Local workspace overlays (not part of upstream HyperView fork)
+cosmos-curate/
+PLAN.md
+TASK.md
+submission/

CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to HyperView
+
+We welcome contributions! This guide will help you set up your development environment and submit high-quality pull requests.
+
+## Development Setup
+
+### Requirements
+- **Python 3.10+**
+- **uv** (Package manager)
+- **Node.js** (For frontend development)
+
+### One-time Setup
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/Hyper3Labs/HyperView.git
+cd HyperView
+
+# Create virtual environment and install dev dependencies
+uv venv .venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Install frontend dependencies
+cd frontend
+npm install
+cd ..
+```
+
+### Optional: Co-develop `hyper-models` locally (uv workspace)
+
+By default, HyperView installs `hyper-models` from PyPI.
+
+If you want to develop HyperView and `hyper-models` side-by-side (without publishing `hyper-models`), you can tell **uv** to use a local checkout instead:
+
+1) Clone `hyper-models` next to the HyperView repo (as a sibling directory):
+
+```bash
+cd ..
+git clone https://github.com/Hyper3Labs/hyper-models
+cd HyperView
+```
+
+2) Add the following to HyperView's `pyproject.toml` (keep this change local unless the maintainers decide otherwise):
+
+```toml
+[tool.uv.workspace]
+members = ["../hyper-models"]
+
+[tool.uv.sources]
+hyper-models = { workspace = true }
+```
+
+3) Use uv's project commands (`uv run ...`, `uv sync`, etc.) so `tool.uv.sources` is respected.
+
+## Running Locally
+
+For the best development experience, run the backend and frontend in separate terminals.
+
+### 1. Start the Backend
+Runs the Python API server at `http://127.0.0.1:6262`.
+
+```bash
+uv run hyperview demo --samples 200 --no-browser
+```
+
+_Tip: Use `HF_DATASETS_OFFLINE=1` if you have cached datasets and want to work offline._
+
+### 2. Start the Frontend
+Runs the Next.js dev server at `http://127.0.0.1:3000` with hot reloading.
+
+```bash
+cd frontend
+npm run dev
+```
+
+The frontend automatically proxies API requests (`/api/*`) to the backend.
+
+## Common Tasks
+
+### Testing & Linting
+Please ensure all checks pass before submitting a PR.
+
+```bash
+# Python
+uv run pytest             # Run unit tests
+uv run ruff format .      # formatting
+uv run ruff check . --fix # Linting
+
+# Frontend
+cd frontend
+npm run lint
+```
+
+### Exporting the Frontend
+The Python package bundles the compiled frontend. If you modify the frontend, you must regenerate the static assets so they can be served by the Python backend in production/demos.
+
+```bash
+bash scripts/export_frontend.sh
+```
+_This compiles the frontend and places artifacts into `src/hyperview/server/static/`. Do not edit files in that directory manually._
+
+## Pull Request Guidelines
+
+1.  **Scope**: Keep changes focused. Open an issue first for major refactors or new features.
+2.  **Tests**: Add tests for new logic where practical.
+3.  **Visuals**: If changing the UI, please attach a screenshot or GIF to your PR.
+4.  **Format**: Ensure code is formatted with `ruff` (Python) and `prettier` (JS/TS implicit in `npm run lint`).