add macos notes

This changes the dockerfile as well.

.gitea/workflows/bump-and-release.yml

@@ -0,0 +1,52 @@
+name: Bump Version and Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  bump-and-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITEA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Bump version
+        id: bump
+        run: |
+          python bump_version.py ${{ github.event.inputs.bump_type }}
+          NEW_VERSION=$(grep -oP 'version = "\K[^"]+' pyproject.toml)
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Commit and tag
+        run: |
+          git config user.name "gitea-actions[bot]"
+          git config user.email "gitea-actions[bot]@users.noreply.gitea.io"
+          git add pyproject.toml
+          git commit -m "bump version to v${{ steps.bump.outputs.version }}"
+          git tag v${{ steps.bump.outputs.version }}
+
+      - name: Push changes
+        run: |
+          git push origin main
+          git push origin v${{ steps.bump.outputs.version }}

.gitea/workflows/release.yml

@@ -66,8 +66,8 @@ jobs:
           echo "## Installation" >> release-notes.md
           echo "" >> release-notes.md
           echo '```bash' >> release-notes.md
-          echo 'uv sync' >> release-notes.md
+          echo 'pip install embeddingbuddy' >> release-notes.md
-          echo 'uv run python main.py' >> release-notes.md
+          echo 'embeddingbuddy serve' >> release-notes.md
           echo '```' >> release-notes.md
 
       - name: Create Release

.github/workflows/pypi-release.yml

@@ -0,0 +1,33 @@
+name: PyPI Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # For trusted publishing
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CLAUDE.md

@@ -21,29 +21,23 @@ uv sync
 
 **Run the application:**
 
-Development mode (with auto-reload):
+Using the CLI (recommended):
 
 ```bash
-uv run run_dev.py
+# Production mode (no debug, no auto-reload)
+embeddingbuddy serve
+
+# Development mode (debug + auto-reload on code changes)
+embeddingbuddy serve --dev
+
+# Debug logging only (no auto-reload)
+embeddingbuddy serve --debug
+
+# With custom host/port
+embeddingbuddy serve --host 0.0.0.0 --port 8080
 ```
 
-Production mode (with Gunicorn WSGI server):
+The app will be available at <http://127.0.0.1:8050> by default
-
-```bash
-# First install production dependencies
-uv sync --extra prod
-
-# Then run in production mode
-uv run run_prod.py
-```
-
-Legacy mode (basic Dash server):
-
-```bash
-uv run main.py
-```
-
-The app will be available at <http://127.0.0.1:8050>
 
 **Run tests:**
 
@@ -204,6 +198,52 @@ Uses modern Python stack with uv for dependency management:
 - **Testing:** pytest for test framework
 - **Dev Tools:** uv for package management
 
+## CI/CD and Release Management
+
+### Repository Setup
+
+This project uses a **dual-repository workflow**:
+
+- **Primary repository:** Gitea instance at `git.hawt.cloud` (read-write)
+- **Mirror repository:** GitHub (read-only mirror)
+
+### Workflow Organization
+
+**Gitea Workflows (`.gitea/workflows/`):**
+- **`bump-and-release.yml`** - Manual version bumping workflow
+  - Runs `bump_version.py` to update version in `pyproject.toml`
+  - Commits changes and creates git tag
+  - Pushes to Gitea (main branch + tag)
+  - Triggered manually via workflow_dispatch with choice of patch/minor/major bump
+- **`release.yml`** - Automated release creation
+  - Triggered when version tags are pushed
+  - Runs tests, builds packages
+  - Creates Gitea release with artifacts
+- **`test.yml`** - Test suite execution
+- **`security.yml`** - Security scanning
+
+**GitHub Workflows (`.github/workflows/`):**
+- **`docker-release.yml`** - Builds and publishes Docker images
+- **`pypi-release.yml`** - Publishes packages to PyPI
+- These workflows are read-only (no git commits/pushes) and create artifacts only
+
+### Release Process
+
+1. Run manual bump workflow on Gitea: **Actions → Bump Version and Release**
+2. Select version bump type (patch/minor/major)
+3. Workflow commits version change and pushes tag to Gitea
+4. Tag push triggers `release.yml` on Gitea (creates release)
+5. GitHub mirror receives tag and triggers artifact builds (Docker, PyPI)
+
+### Version Management
+
+Use `bump_version.py` for version updates:
+```bash
+python bump_version.py patch    # 0.3.0 -> 0.3.1
+python bump_version.py minor    # 0.3.0 -> 0.4.0
+python bump_version.py major    # 0.3.0 -> 1.0.0
+```
+
 ## Development Guidelines
 
 **When adding new features:**

Dockerfile

@@ -23,10 +23,6 @@ COPY pyproject.toml uv.lock ./
 
 # Copy source code (needed for editable install)
 COPY src/ src/
-COPY main.py .
-COPY wsgi.py .
-COPY run_prod.py .
-COPY assets/ assets/
 
 # Change ownership of source files before building (lighter I/O)
 RUN chown -R appuser:appuser /app
@@ -59,10 +55,6 @@ RUN chown appuser:appuser /app
 # Copy files from builder with correct ownership
 COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv
 COPY --from=builder --chown=appuser:appuser /app/src /app/src
-COPY --from=builder --chown=appuser:appuser /app/main.py /app/main.py
-COPY --from=builder --chown=appuser:appuser /app/assets /app/assets
-COPY --from=builder --chown=appuser:appuser /app/wsgi.py /app/wsgi.py
-COPY --from=builder --chown=appuser:appuser /app/run_prod.py /app/run_prod.py
 
 # Switch to non-root user
 USER appuser
@@ -86,5 +78,5 @@ EXPOSE 8050
 HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
     CMD python -c "import requests; requests.get('http://localhost:8050/', timeout=5)" || exit 1
 
-# Run application with Gunicorn in production
+# Run application in production mode (no debug, no auto-reload)
-CMD ["python", "run_prod.py"]
+CMD ["embeddingbuddy", "serve"]

README.md

@@ -28,6 +28,73 @@ documents and prompts to understand how queries relate to your content.
 - **Sidebar layout** with controls on left, large visualization area on right
 - **Real-time visualization** optimized for small to medium datasets
 
+## Network Dependency
+
+**Note:** The application loads the Transformers.js library (v3.0.0) from `cdn.jsdelivr.net` for client-side embedding generation. This requires an active internet connection and sends requests to a third-party CDN. The application will function without internet if you only use the file upload features for pre-computed embeddings.
+
+## Quick Start
+
+### Installation
+
+**Option 1: Install with uv (recommended)**
+
+```bash
+# Install as a CLI tool (no need to clone the repo)
+uv tool install embeddingbuddy
+
+# Run the application
+embeddingbuddy serve
+```
+
+**Option 2: Install with pip/pipx**
+
+```bash
+# Install with pipx (isolated environment)
+pipx install embeddingbuddy
+
+# Or install with pip
+pip install embeddingbuddy
+
+# Run the application
+embeddingbuddy
+```
+
+**Option 3: Run with Docker**
+
+```bash
+# Pull and run the Docker image
+docker run -p 8050:8050 ghcr.io/godber/embedding-buddy:latest
+```
+
+The application will be available at <http://127.0.0.1:8050>
+
+### macOS Installation Notes
+
+If installation fails with C++ compiler or library errors (common with `opentsne`), install Xcode Command Line Tools:
+
+```bash
+# Install or update Command Line Tools
+xcode-select --install
+
+# Or reset existing installation
+sudo xcode-select --reset
+```
+
+### Using the Application
+
+1. **Open your browser** to <http://127.0.0.1:8050>
+2. **Upload your data**:
+   - Drag and drop an NDJSON file containing embeddings (see Data Format below)
+   - Optionally upload a second file with prompts to compare against documents
+3. **Choose visualization settings**:
+   - Select dimensionality reduction method (PCA, t-SNE, or UMAP)
+   - Choose 2D or 3D visualization
+   - Pick color coding (by category, subcategory, or tags)
+4. **Explore**:
+   - Click points to view full content
+   - Toggle prompt visibility
+   - Rotate and zoom 3D plots
+
 ## Data Format
 
 EmbeddingBuddy accepts newline-delimited JSON (NDJSON) files for both documents
@@ -73,26 +140,18 @@ uv sync
 
 2. **Run the application:**
 
-**Development mode** (with auto-reload):
-
 ```bash
-uv run run_dev.py
+# Production mode (no debug, no auto-reload)
-```
+embeddingbuddy serve
 
-**Production mode** (with Gunicorn WSGI server):
+# Development mode (debug + auto-reload on code changes)
+embeddingbuddy serve --dev
 
-```bash
+# Debug logging only (no auto-reload)
-# Install production dependencies
+embeddingbuddy serve --debug
-uv sync --extra prod
 
-# Run in production mode
+# Custom host/port
-uv run run_prod.py
+embeddingbuddy serve --host 0.0.0.0 --port 8080
-```
-
-**Legacy mode** (basic Dash server):
-
-```bash
-uv run main.py
 ```
 
 3. **Open your browser** to <http://127.0.0.1:8050>
@@ -180,10 +239,8 @@ src/embeddingbuddy/
 │       └── interactions.py    # User interaction callbacks
 └── utils/                     # Utility functions
 
-main.py            # Application runner (at project root)
+# CLI entry point
-main.py            # Application runner (at project root)
+embeddingbuddy serve    # Main CLI command to start the server
-run_dev.py         # Development server runner
-run_prod.py        # Production server runner
 ```
 
 ### Testing

main.py

@@ -1,10 +0,0 @@
-from src.embeddingbuddy.app import create_app, run_app
-
-
-def main():
-    app = create_app()
-    run_app(app)
-
-
-if __name__ == "__main__":
-    main()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "embeddingbuddy"
-version = "0.6.2"
+version = "0.8.3"
 description = "A Python Dash application for interactive exploration and visualization of embedding vectors through dimensionality reduction techniques."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,6 +17,10 @@ dependencies = [
     "opensearch-py>=3.0.0",
 ]
 
+[project.scripts]
+embeddingbuddy = "embeddingbuddy.cli:main"
+embeddingbuddy-serve = "embeddingbuddy.app:serve"
+
 [project.optional-dependencies]
 test = [
     "pytest>=8.4.1",
@@ -50,3 +54,6 @@ where = ["src"]
 
 [tool.setuptools.package-dir]
 "" = "src"
+
+[tool.setuptools.package-data]
+embeddingbuddy = ["assets/**/*"]

run_dev.py

@@ -1,32 +0,0 @@
-#!/usr/bin/env python3
-"""
-Development runner with auto-reload enabled.
-This runs the Dash development server with hot reloading.
-"""
-import os
-from src.embeddingbuddy.app import create_app, run_app
-
-def main():
-    """Run the application in development mode with auto-reload."""
-    # Force development settings
-    os.environ["EMBEDDINGBUDDY_ENV"] = "development"
-    os.environ["EMBEDDINGBUDDY_DEBUG"] = "true"
-
-    # Check for OpenSearch disable flag (optional for testing)
-    # Set EMBEDDINGBUDDY_OPENSEARCH_ENABLED=false to test without OpenSearch
-    opensearch_status = os.getenv("EMBEDDINGBUDDY_OPENSEARCH_ENABLED", "true")
-    opensearch_enabled = opensearch_status.lower() == "true"
-    
-    print("🚀 Starting EmbeddingBuddy in development mode...")
-    print("📁 Auto-reload enabled - changes will trigger restart")
-    print("🌐 Server will be available at http://127.0.0.1:8050")
-    print(f"🔍 OpenSearch: {'Enabled' if opensearch_enabled else 'Disabled'}")
-    print("⏹️  Press Ctrl+C to stop")
-    
-    app = create_app()
-    
-    # Run with development server (includes auto-reload when debug=True)
-    run_app(app, debug=True)
-
-if __name__ == "__main__":
-    main()

run_prod.py

@@ -1,52 +0,0 @@
-#!/usr/bin/env python3
-"""
-Production runner using Gunicorn WSGI server.
-This provides better performance and stability for production deployments.
-"""
-import os
-import subprocess
-import sys
-from src.embeddingbuddy.config.settings import AppSettings
-
-def main():
-    """Run the application in production mode with Gunicorn."""
-    # Force production settings
-    os.environ["EMBEDDINGBUDDY_ENV"] = "production"
-    os.environ["EMBEDDINGBUDDY_DEBUG"] = "false"
-    # Disable OpenSearch by default in production (can be overridden by setting env var)
-    if "EMBEDDINGBUDDY_OPENSEARCH_ENABLED" not in os.environ:
-        os.environ["EMBEDDINGBUDDY_OPENSEARCH_ENABLED"] = "false"
-    
-    print("🚀 Starting EmbeddingBuddy in production mode...")
-    print(f"⚙️  Workers: {AppSettings.GUNICORN_WORKERS}")
-    print(f"🌐 Server will be available at http://{AppSettings.GUNICORN_BIND}")
-    print("⏹️  Press Ctrl+C to stop")
-    
-    # Gunicorn command
-    cmd = [
-        "gunicorn",
-        "--workers", str(AppSettings.GUNICORN_WORKERS),
-        "--bind", AppSettings.GUNICORN_BIND,
-        "--timeout", str(AppSettings.GUNICORN_TIMEOUT),
-        "--keep-alive", str(AppSettings.GUNICORN_KEEPALIVE),
-        "--access-logfile", "-",
-        "--error-logfile", "-",
-        "--log-level", "info",
-        "wsgi:application"
-    ]
-    
-    try:
-        subprocess.run(cmd, check=True)
-    except KeyboardInterrupt:
-        print("\n🛑 Shutting down...")
-        sys.exit(0)
-    except subprocess.CalledProcessError as e:
-        print(f"❌ Error running Gunicorn: {e}")
-        sys.exit(1)
-    except FileNotFoundError:
-        print("❌ Gunicorn not found. Install it with: uv add gunicorn")
-        print("💡 Or run in development mode with: python run_dev.py")
-        sys.exit(1)
-
-if __name__ == "__main__":
-    main()

src/embeddingbuddy/app.py

@@ -1,25 +1,30 @@
-import dash
+"""
-import dash_bootstrap_components as dbc
+EmbeddingBuddy application factory and server functions.
-from .config.settings import AppSettings
+
-from .ui.layout import AppLayout
+This module contains the main application creation logic with imports
-from .ui.callbacks.data_processing import DataProcessingCallbacks
+moved inside functions to avoid loading heavy dependencies at module level.
-from .ui.callbacks.visualization import VisualizationCallbacks
+"""
-from .ui.callbacks.interactions import InteractionCallbacks
 
 
 def create_app():
+    """Create and configure the Dash application instance."""
     import os
+    import dash
+    import dash_bootstrap_components as dbc
+    from .ui.layout import AppLayout
+    from .ui.callbacks.data_processing import DataProcessingCallbacks
+    from .ui.callbacks.visualization import VisualizationCallbacks
+    from .ui.callbacks.interactions import InteractionCallbacks
 
-    # Get the project root directory (two levels up from this file)
+    # Get the assets directory relative to this module
-    project_root = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+    module_dir = os.path.dirname(__file__)
-    assets_path = os.path.join(project_root, "assets")
+    assets_path = os.path.join(module_dir, "assets")
 
     app = dash.Dash(
         __name__,
         title="EmbeddingBuddy",
         external_stylesheets=[
             dbc.themes.BOOTSTRAP,
-            "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css",
         ],
         assets_folder=assets_path,
         meta_tags=[
@@ -124,6 +129,9 @@ def _register_client_side_callbacks(app):
 
 
 def run_app(app=None, debug=None, host=None, port=None):
+    """Run the Dash application with specified settings."""
+    from .config.settings import AppSettings
+
     if app is None:
         app = create_app()
 
@@ -134,6 +142,75 @@ def run_app(app=None, debug=None, host=None, port=None):
     )
 
 
-if __name__ == "__main__":
+def serve(host=None, port=None, dev=False, debug=False):
+    """Start the EmbeddingBuddy web server.
+
+    Args:
+        host: Host to bind to (default: 127.0.0.1)
+        port: Port to bind to (default: 8050)
+        dev: Development mode - enable debug logging and auto-reload (default: False)
+        debug: Enable debug logging only, no auto-reload (default: False)
+    """
+    import os
+    from .config.settings import AppSettings
+
+    # Determine actual values to use
+    actual_host = host if host is not None else AppSettings.HOST
+    actual_port = port if port is not None else AppSettings.PORT
+
+    # Determine mode
+    # --dev takes precedence and enables both debug and auto-reload
+    # --debug enables only debug logging
+    # No flags = production mode (no debug, no auto-reload)
+    use_reloader = dev
+    use_debug = dev or debug
+
+    # Only print startup messages in main process (not in Flask reloader)
+    if not os.environ.get("WERKZEUG_RUN_MAIN"):
+        from importlib.metadata import version
+
+        try:
+            pkg_version = version("embeddingbuddy")
+        except Exception:
+            pkg_version = "unknown"
+
+        mode = "development" if dev else ("debug" if debug else "production")
+        print(f"Starting EmbeddingBuddy v{pkg_version} in {mode} mode...")
+        print("Loading dependencies (this may take a few seconds)...")
+        print(f"Server will start at http://{actual_host}:{actual_port}")
+        if use_reloader:
+            print("Auto-reload enabled - server will restart on code changes")
+
     app = create_app()
-    run_app(app)
+
+    # Suppress Flask development server warning in production mode
+    if not use_debug and not use_reloader:
+        import warnings
+        import logging
+
+        # Suppress the werkzeug warning
+        warnings.filterwarnings("ignore", message=".*development server.*")
+
+        # Set werkzeug logger to ERROR level to suppress the warning
+        werkzeug_logger = logging.getLogger("werkzeug")
+        werkzeug_logger.setLevel(logging.ERROR)
+
+    # Use Flask's built-in server with appropriate settings
+    app.run(
+        debug=use_debug, host=actual_host, port=actual_port, use_reloader=use_reloader
+    )
+
+
+def main():
+    """Legacy entry point - redirects to cli module.
+
+    This is kept for backward compatibility but the main CLI
+    is now in embeddingbuddy.cli for faster startup.
+    """
+    from .cli import main as cli_main
+
+    cli_main()
+
+
+if __name__ == "__main__":
+    main()

src/embeddingbuddy/assets/fontawesome.css

@@ -0,0 +1,2 @@
+/* Load Font Awesome from local assets */
+@import url("/assets/fontawesome/css/all.min.css");

src/embeddingbuddy/assets/fontawesome/LICENSE.txt

@@ -0,0 +1,165 @@
+Fonticons, Inc. (https://fontawesome.com)
+
+--------------------------------------------------------------------------------
+
+Font Awesome Free License
+
+Font Awesome Free is free, open source, and GPL friendly. You can use it for
+commercial projects, open source projects, or really almost whatever you want.
+Full Font Awesome Free license: https://fontawesome.com/license/free.
+
+--------------------------------------------------------------------------------
+
+# Icons: CC BY 4.0 License (https://creativecommons.org/licenses/by/4.0/)
+
+The Font Awesome Free download is licensed under a Creative Commons
+Attribution 4.0 International License and applies to all icons packaged
+as SVG and JS file types.
+
+--------------------------------------------------------------------------------
+
+# Fonts: SIL OFL 1.1 License
+
+In the Font Awesome Free download, the SIL OFL license applies to all icons
+packaged as web and desktop font files.
+
+Copyright (c) 2023 Fonticons, Inc. (https://fontawesome.com)
+with Reserved Font Name: "Font Awesome".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+SIL OPEN FONT LICENSE
+Version 1.1 - 26 February 2007
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting — in part or in whole — any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+# Code: MIT License (https://opensource.org/licenses/MIT)
+
+In the Font Awesome Free download, the MIT license applies to all non-font and
+non-icon files.
+
+Copyright 2023 Fonticons, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+# Attribution
+
+Attribution is required by MIT, SIL OFL, and CC BY licenses. Downloaded Font
+Awesome Free files already contain embedded comments with sufficient
+attribution, so you shouldn't need to do anything additional when using these
+files normally.
+
+We've kept attribution comments terse, so we ask that you do not actively work
+to remove them from files, especially code. They're a great way for folks to
+learn about Font Awesome.
+
+--------------------------------------------------------------------------------
+
+# Brand Icons
+
+All brand icons are trademarks of their respective owners. The use of these
+trademarks does not indicate endorsement of the trademark holder by Font
+Awesome, nor vice versa. **Please do not use brand logos for any purpose except
+to represent the company, product, or service to which they refer.**

src/embeddingbuddy/cli.py

@@ -0,0 +1,67 @@
+"""
+Lightweight CLI entry point for EmbeddingBuddy.
+
+This module provides a fast command-line interface that only imports
+heavy dependencies when actually needed by subcommands.
+"""
+
+import argparse
+import sys
+
+
+def main():
+    """Main CLI entry point with minimal imports for fast help text."""
+    parser = argparse.ArgumentParser(
+        prog="embeddingbuddy",
+        description="EmbeddingBuddy - Interactive embedding visualization tool",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  embeddingbuddy serve                    # Production mode (no debug, no auto-reload)
+  embeddingbuddy serve --dev              # Development mode (debug + auto-reload)
+  embeddingbuddy serve --debug            # Debug logging only (no auto-reload)
+  embeddingbuddy serve --port 8080        # Custom port
+  embeddingbuddy serve --host 0.0.0.0     # Bind to all interfaces
+        """,
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command", help="Available commands", metavar="<command>"
+    )
+
+    # Serve subcommand
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start the web server",
+        description="Start the EmbeddingBuddy web server for interactive visualization",
+    )
+    serve_parser.add_argument(
+        "--host", default=None, help="Host to bind to (default: 127.0.0.1)"
+    )
+    serve_parser.add_argument(
+        "--port", type=int, default=None, help="Port to bind to (default: 8050)"
+    )
+    serve_parser.add_argument(
+        "--dev",
+        action="store_true",
+        help="Development mode: enable debug logging and auto-reload",
+    )
+    serve_parser.add_argument(
+        "--debug", action="store_true", help="Enable debug logging (no auto-reload)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "serve":
+        # Only import heavy dependencies when actually running serve
+        from embeddingbuddy.app import serve
+
+        serve(host=args.host, port=args.port, dev=args.dev, debug=args.debug)
+    else:
+        # No command specified, show help
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/embeddingbuddy/config/settings.py

@@ -69,7 +69,7 @@ class AppSettings:
     TEXT_PREVIEW_LENGTH = 100
 
     # App Configuration
-    DEBUG = os.getenv("EMBEDDINGBUDDY_DEBUG", "True").lower() == "true"
+    DEBUG = os.getenv("EMBEDDINGBUDDY_DEBUG", "False").lower() == "true"
     HOST = os.getenv("EMBEDDINGBUDDY_HOST", "127.0.0.1")
     PORT = int(os.getenv("EMBEDDINGBUDDY_PORT", "8050"))
 

src/embeddingbuddy/ui/callbacks/data_processing.py

@@ -660,14 +660,12 @@ class DataProcessingCallbacks:
         import os
 
         try:
-            # Get the project root directory (four levels up from this file)
+            # Get the embeddingbuddy package directory (three levels up from this file)
             current_file = os.path.abspath(__file__)
-            project_root = os.path.dirname(
+            package_dir = os.path.dirname(
-                os.path.dirname(
+                os.path.dirname(os.path.dirname(current_file))
-                    os.path.dirname(os.path.dirname(os.path.dirname(current_file)))
             )
-            )
+            sample_file_path = os.path.join(package_dir, "assets", "sample-txt.md")
-            sample_file_path = os.path.join(project_root, "assets", "sample-txt.md")
 
             if os.path.exists(sample_file_path):
                 with open(sample_file_path, "r", encoding="utf-8") as file:

src/embeddingbuddy/wsgi.py

@@ -0,0 +1,12 @@
+"""
+WSGI entry point for production deployment.
+Use this with a production WSGI server like Gunicorn.
+"""
+
+from embeddingbuddy.app import create_app
+
+# Create the application instance
+application = create_app()
+
+# For compatibility with different WSGI servers
+app = application

uv.lock

@@ -412,7 +412,7 @@ wheels = [
 
 [[package]]
 name = "embeddingbuddy"
-version = "0.5.1"
+version = "0.8.1"
 source = { editable = "." }
 dependencies = [
     { name = "dash" },

wsgi.py

@@ -1,20 +0,0 @@
-"""
-WSGI entry point for production deployment.
-Use this with a production WSGI server like Gunicorn.
-"""
-from src.embeddingbuddy.app import create_app
-
-# Create the application instance
-application = create_app()
-
-# For compatibility with different WSGI servers
-app = application
-
-if __name__ == "__main__":
-    # This won't be used in production, but useful for testing
-    from src.embeddingbuddy.config.settings import AppSettings
-    application.run(
-        host=AppSettings.HOST,
-        port=AppSettings.PORT,
-        debug=False
-    )