bump version to v0.6.4

.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 }}

.github/workflows/docker-release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
 
 env:
   REGISTRY: ghcr.io

.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

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.6.1"
+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",

src/embeddingbuddy/app.py

@@ -134,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()