bump version to v0.6.4

Reviewed-on: godber/embedding-buddy#7

.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

@@ -71,22 +71,15 @@ jobs:
           echo '```' >> release-notes.md
 
       - name: Create Release
-        uses: actions/create-release@v1
+        uses: akkuman/gitea-release-action@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          NODE_OPTIONS: '--experimental-fetch'
         with:
+          token: ${{ secrets.GITEA_TOKEN }}
           tag_name: ${{ github.ref_name || github.event.inputs.version }}
           release_name: Release ${{ github.ref_name || github.event.inputs.version }}
           body_path: release-notes.md
           draft: false
           prerelease: false
-
-      - name: Upload Release Assets
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
-        with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: dist/
-          asset_name: embeddingbuddy-dist
-          asset_content_type: application/zip
+          files: |-
+            dist/*

.github/workflows/docker-release.yml

@@ -0,0 +1,54 @@
+name: Docker Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.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

@@ -204,6 +204,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:**
@@ -217,7 +263,7 @@ Uses modern Python stack with uv for dependency management:
 **Code Organization Principles:**
 
 - Single responsibility principle
-- Clear module boundaries  
+- Clear module boundaries
 - Testable, isolated components
 - Configuration over hardcoding
 - Error handling at appropriate layers

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Austin Godber - EmbeddingBuddy
+
+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.

README.md

@@ -28,6 +28,57 @@ 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
 
+## 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
+```
+
+**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>
+
+### 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

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "embeddingbuddy"
-version = "0.5.0"
+version = "0.6.4"
 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,9 @@ dependencies = [
     "opensearch-py>=3.0.0",
 ]
 
+[project.scripts]
+embeddingbuddy = "embeddingbuddy.app:main"
+
 [project.optional-dependencies]
 test = [
     "pytest>=8.4.1",

run_dev.py

@@ -11,10 +11,16 @@ def main():
     # 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_prod.py

@@ -13,6 +13,9 @@ def main():
     # 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}")

src/embeddingbuddy/app.py

@@ -16,11 +16,33 @@ def create_app():
 
     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=[
+            {
+                "name": "description",
+                "content": "Interactive embedding visualization tool for exploring high-dimensional vectors through dimensionality reduction techniques like PCA, t-SNE, and UMAP.",
+            },
+            {"name": "author", "content": "EmbeddingBuddy"},
+            {
+                "name": "keywords",
+                "content": "embeddings, visualization, dimensionality reduction, PCA, t-SNE, UMAP, machine learning, data science",
+            },
+            {"name": "viewport", "content": "width=device-width, initial-scale=1.0"},
+            {
+                "property": "og:title",
+                "content": "EmbeddingBuddy - Interactive Embedding Visualization",
+            },
+            {
+                "property": "og:description",
+                "content": "Explore and visualize embedding vectors through interactive 2D/3D plots with multiple dimensionality reduction techniques.",
+            },
+            {"property": "og:type", "content": "website"},
+        ],
     )
 
     # Allow callbacks to components that are dynamically created in tabs
@@ -112,6 +134,11 @@ def run_app(app=None, debug=None, host=None, port=None):
     )
 
 
-if __name__ == "__main__":
+def main():
+    """Main entry point for the embeddingbuddy CLI command."""
     app = create_app()
     run_app(app)
+
+
+if __name__ == "__main__":
+    main()

src/embeddingbuddy/config/settings.py

@@ -85,6 +85,9 @@ class AppSettings:
     GUNICORN_KEEPALIVE = int(os.getenv("GUNICORN_KEEPALIVE", "5"))
 
     # OpenSearch Configuration
+    OPENSEARCH_ENABLED = (
+        os.getenv("EMBEDDINGBUDDY_OPENSEARCH_ENABLED", "True").lower() == "true"
+    )
     OPENSEARCH_DEFAULT_SIZE = 100
     OPENSEARCH_SAMPLE_SIZE = 5
     OPENSEARCH_CONNECTION_TIMEOUT = 30

src/embeddingbuddy/ui/callbacks/data_processing.py

@@ -82,19 +82,23 @@ class DataProcessingCallbacks:
         )
         def render_tab_content(active_tab):
             from ...ui.components.datasource import DataSourceComponent
+            from ...config.settings import AppSettings
 
             datasource = DataSourceComponent()
 
-            if active_tab == "opensearch-tab":
+            if active_tab == "opensearch-tab" and AppSettings.OPENSEARCH_ENABLED:
                 return [datasource.create_opensearch_tab()]
             elif active_tab == "text-input-tab":
                 return [datasource.create_text_input_tab()]
             else:
                 return [datasource.create_file_upload_tab()]
 
-        # Register callbacks for both data and prompts sections
-        self._register_opensearch_callbacks("data", self.opensearch_client_data)
-        self._register_opensearch_callbacks("prompts", self.opensearch_client_prompts)
+        # Register callbacks for both data and prompts sections (only if OpenSearch is enabled)
+        if AppSettings.OPENSEARCH_ENABLED:
+            self._register_opensearch_callbacks("data", self.opensearch_client_data)
+            self._register_opensearch_callbacks(
+                "prompts", self.opensearch_client_prompts
+            )
 
         # Register collapsible section callbacks
         self._register_collapse_callbacks()

src/embeddingbuddy/ui/callbacks/interactions.py

@@ -7,6 +7,16 @@ class InteractionCallbacks:
         self._register_callbacks()
 
     def _register_callbacks(self):
+        @callback(
+            Output("about-modal", "is_open"),
+            [Input("about-button", "n_clicks"), Input("about-modal-close", "n_clicks")],
+            prevent_initial_call=True,
+        )
+        def toggle_about_modal(about_clicks, close_clicks):
+            if about_clicks or close_clicks:
+                return True if about_clicks else False
+            return False
+
         @callback(
             [
                 Output("processed-data", "data", allow_duplicate=True),

src/embeddingbuddy/ui/components/about.py

@@ -0,0 +1,90 @@
+from dash import html, dcc
+import dash_bootstrap_components as dbc
+
+
+class AboutComponent:
+    def _get_about_content(self):
+        return """
+# 🔍 Interactive Embedding Vector Visualization
+
+EmbeddingBuddy is a web application for interactive exploration and
+visualization of embedding vectors through dimensionality reduction techniques
+(PCA, t-SNE, UMAP).
+
+You have two ways to get started:
+
+1. Generate embeddings directly in the browser if it supports WebGPU.
+2. Upload your NDJSON file containing embedding vectors and metadata.
+
+## Generating Embeddings in Browser
+
+1. Expand the "Generate Embeddings" section.
+2. Input your text data (one entry per line).
+    1. Optionally you can use the built in sample data by clicking "Load Sample Data" button.
+3. Click "Generate Embeddings" to create vectors using a pre-trained model.
+
+## NDJSON File Format
+
+```json
+{"id": "doc_001", "embedding": [0.1, -0.3, 0.7, ...], "text": "Sample text content", "category": "news", "subcategory": "politics", "tags": ["election", "politics"]}
+{"id": "doc_002", "embedding": [0.2, -0.1, 0.9, ...], "text": "Another example", "category": "review", "subcategory": "product", "tags": ["tech", "gadget"]}
+```
+
+
+## ✨ Features
+
+- Drag-and-drop NDJSON file upload
+- Multiple dimensionality reduction algorithms
+- 2D/3D interactive plots with Plotly
+- Color coding by categories, subcategories, or tags
+- In-browser embedding generation
+- OpenSearch integration for data loading
+
+## 🔧 Supported Algorithms
+
+- **PCA** (Principal Component Analysis)
+- **t-SNE** (t-Distributed Stochastic Neighbor Embedding)
+- **UMAP** (Uniform Manifold Approximation and Projection)
+
+---
+
+📂 [View on GitHub](https://github.com/godber/EmbeddingBuddy)
+
+*Built with: Python, Dash, Plotly, scikit-learn, OpenTSNE, UMAP*
+        """.strip()
+
+    def create_about_modal(self):
+        return dbc.Modal(
+            [
+                dbc.ModalHeader(
+                    dbc.ModalTitle("Welcome to EmbeddingBuddy"),
+                    close_button=True,
+                ),
+                dbc.ModalBody(
+                    [dcc.Markdown(self._get_about_content(), className="mb-0")]
+                ),
+                dbc.ModalFooter(
+                    [
+                        dbc.Button(
+                            "Close",
+                            id="about-modal-close",
+                            color="secondary",
+                            n_clicks=0,
+                        )
+                    ]
+                ),
+            ],
+            id="about-modal",
+            is_open=True,
+            size="lg",
+        )
+
+    def create_about_button(self):
+        return dbc.Button(
+            [html.I(className="fas fa-info-circle me-2"), "About"],
+            id="about-button",
+            color="outline-info",
+            size="sm",
+            n_clicks=0,
+            className="ms-2",
+        )

src/embeddingbuddy/ui/components/datasource.py

@@ -1,6 +1,7 @@
 from dash import dcc, html
 import dash_bootstrap_components as dbc
 from .upload import UploadComponent
+from embeddingbuddy.config.settings import AppSettings
 
 
 class DataSourceComponent:
@@ -9,15 +10,18 @@ class DataSourceComponent:
 
     def create_tabbed_interface(self):
         """Create tabbed interface for different data sources."""
+        tabs = [dbc.Tab(label="File Upload", tab_id="file-tab")]
+
+        # Only add OpenSearch tab if enabled
+        if AppSettings.OPENSEARCH_ENABLED:
+            tabs.append(dbc.Tab(label="OpenSearch", tab_id="opensearch-tab"))
+
         return dbc.Card(
             [
                 dbc.CardHeader(
                     [
                         dbc.Tabs(
-                            [
-                                dbc.Tab(label="File Upload", tab_id="file-tab"),
-                                dbc.Tab(label="OpenSearch", tab_id="opensearch-tab"),
-                            ],
+                            tabs,
                             id="data-source-tabs",
                             active_tab="file-tab",
                         )

src/embeddingbuddy/ui/components/sidebar.py

@@ -3,6 +3,7 @@ import dash_bootstrap_components as dbc
 from .upload import UploadComponent
 from .datasource import DataSourceComponent
 from .textinput import TextInputComponent
+from embeddingbuddy.config.settings import AppSettings
 
 
 class SidebarComponent:
@@ -102,6 +103,10 @@ class SidebarComponent:
         )
 
     def _create_data_sources_item(self):
+        tooltip_text = "Load existing embeddings: upload files"
+        if AppSettings.OPENSEARCH_ENABLED:
+            tooltip_text += " or read from OpenSearch"
+
         return dbc.AccordionItem(
             [
                 self.datasource_component.create_error_alert(),
@@ -115,7 +120,7 @@ class SidebarComponent:
                         className="fas fa-info-circle text-muted",
                         style={"cursor": "pointer"},
                         id="load-embeddings-info-icon",
-                        title="Load existing embeddings: upload files or read from OpenSearch",
+                        title=tooltip_text,
                     ),
                 ]
             ),

src/embeddingbuddy/ui/components/textinput.py

@@ -16,14 +16,14 @@ class TextInputComponent:
         """Create the complete text input interface with model selection and processing options."""
         return html.Div(
             [
-                # Model selection section
-                self._create_model_selection(),
-                html.Hr(),
                 # Text input section
                 self._create_text_input_area(),
                 # Text action buttons
                 self._create_text_action_buttons(),
                 html.Hr(),
+                # Model selection section
+                self._create_model_selection(),
+                html.Hr(),
                 # Processing options
                 self._create_processing_options(),
                 html.Hr(),

src/embeddingbuddy/ui/layout.py

@@ -1,16 +1,19 @@
 from dash import dcc, html
 import dash_bootstrap_components as dbc
 from .components.sidebar import SidebarComponent
+from .components.about import AboutComponent
 
 
 class AppLayout:
     def __init__(self):
         self.sidebar = SidebarComponent()
+        self.about = AboutComponent()
 
     def create_layout(self):
         return dbc.Container(
             [self._create_header(), self._create_main_content()]
-            + self._create_stores(),
+            + self._create_stores()
+            + [self.about.create_about_modal()],
             fluid=True,
         )
 
@@ -19,7 +22,19 @@ class AppLayout:
             [
                 dbc.Col(
                     [
-                        html.H1("EmbeddingBuddy", className="text-center mb-4"),
+                        html.Div(
+                            [
+                                html.H1(
+                                    "EmbeddingBuddy",
+                                    className="text-center mb-4 d-inline",
+                                ),
+                                html.Div(
+                                    [self.about.create_about_button()],
+                                    className="float-end",
+                                ),
+                            ],
+                            className="d-flex justify-content-between align-items-center",
+                        ),
                         # Load Transformers.js from CDN
                         html.Script(
                             """

uv.lock

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