diff --git a/.github/workflows/release.yml b/.gitea/workflows/bump-and-release.yml similarity index 68% rename from .github/workflows/release.yml rename to .gitea/workflows/bump-and-release.yml index ad7ab71..5cf409d 100644 --- a/.github/workflows/release.yml +++ b/.gitea/workflows/bump-and-release.yml @@ -1,4 +1,4 @@ -name: Create Release +name: Bump Version and Release on: workflow_dispatch: @@ -22,7 +22,8 @@ jobs: - name: Checkout code uses: actions/checkout@v4 with: - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ secrets.GITEA_TOKEN }} + fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v5 @@ -39,8 +40,8 @@ jobs: - name: Commit and tag run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" + 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 }} @@ -49,13 +50,3 @@ jobs: run: | git push origin main git push origin v${{ steps.bump.outputs.version }} - - - name: Create GitHub Release - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: v${{ steps.bump.outputs.version }} - release_name: Release v${{ steps.bump.outputs.version }} - draft: false - prerelease: false diff --git a/CLAUDE.md b/CLAUDE.md index efb61c2..36977ec 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index 65f262e..786c979 100644 --- a/README.md +++ b/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 + +### Using the Application + +1. **Open your browser** to +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 diff --git a/pyproject.toml b/pyproject.toml index 50239dd..d289590 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,6 +17,9 @@ dependencies = [ "opensearch-py>=3.0.0", ] +[project.scripts] +embeddingbuddy = "embeddingbuddy.app:main" + [project.optional-dependencies] test = [ "pytest>=8.4.1", diff --git a/src/embeddingbuddy/app.py b/src/embeddingbuddy/app.py index ac99c58..71f29c5 100644 --- a/src/embeddingbuddy/app.py +++ b/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()