Release v0.1.0

.dockerignore

@@ -1,57 +1,11 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-*.egg-info/
-dist/
-build/
-*.egg
+# Allowlist-style .dockerignore: ignore everything, then explicitly allow the build inputs.
+# The Docker image installs from a pre-built wheel, so no source files are required in the context.
+# This prevents dev artifacts (cauldron/, .claude/, scratch/, tests/, docs/, .git/, secrets) from
+# ever entering the image layers or being cached by BuildKit.
 
-# Virtual environments
-.venv/
-venv/
-ENV/
-env/
+# Ignore everything
+**
 
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
-.tox/
-*.cover
-
-# Git
-.git/
-.gitignore
-.gitattributes
-
-# Documentation
-docs/
-*.md
-!README.md
-
-# Development tools
-.ruff_cache/
-.mypy_cache/
-.pre-commit-config.yaml
-
-# Local development
-scratch/
-.env
-.env.*
-
-# CI/CD
-.github/
-
-# Misc
-*.log
-.DS_Store
+# Allow the Dockerfile and the pre-built wheel produced by `uv build`
+!Dockerfile
+!dist/*.whl

.env.example

@@ -0,0 +1,85 @@
+# ISCC-Search Configuration
+# Copy to .env and customize as needed. All values shown are defaults.
+
+# --- Server ---
+
+# Index backend URI (memory://, lmdb:///path, usearch:///path)
+# Default: usearch:/// + platform-specific user data dir (e.g. ~/.local/share/iscc-search)
+# ISCC_SEARCH_INDEX_URI=usearch:///path/to/data
+
+# API secret for authentication (unset = public API)
+# ISCC_SEARCH_API_SECRET=
+
+# CORS allowed origins (comma-separated, or * for all)
+# ISCC_SEARCH_CORS_ORIGINS=*
+
+# Server host and port
+# ISCC_SEARCH_HOST=0.0.0.0
+# ISCC_SEARCH_PORT=8000
+
+# Number of worker processes (production only, unset = single worker)
+# NOTE: workers > 1 is REJECTED with the usearch:// backend — concurrent writers
+# corrupt .usearch files. Leave unset (single worker) for usearch-backed deployments.
+# ISCC_SEARCH_WORKERS=
+
+# Auto-flush sub-indexes after N dirty key mutations (0 = disabled).
+# Only safe with a single writer process. Production recommendation: 100000.
+# Reduces blast radius of hard crashes (OOM / SIGKILL / power loss).
+# ISCC_SEARCH_FLUSH_INTERVAL=0
+
+# Log level (debug, info, warning, error, critical)
+# ISCC_SEARCH_LOG_LEVEL=info
+
+# --- Shard Sizes (MB) ---
+
+# Maximum shard file size for ISCC-UNIT indexes
+# ISCC_SEARCH_SHARD_SIZE_UNITS=1024
+
+# Maximum shard file size for simprint indexes
+# ISCC_SEARCH_SHARD_SIZE_SIMPRINTS=1024
+
+# --- HNSW Parameters (Units) ---
+
+# Build-time search depth (efConstruction) for unit indexes
+# ISCC_SEARCH_HNSW_EXPANSION_ADD_UNITS=128
+
+# Query-time search depth (ef) for unit indexes
+# ISCC_SEARCH_HNSW_EXPANSION_SEARCH_UNITS=64
+
+# Graph connectivity (M) for unit indexes
+# ISCC_SEARCH_HNSW_CONNECTIVITY_UNITS=16
+
+# --- HNSW Parameters (Simprints) ---
+
+# Build-time search depth (efConstruction) for simprint indexes
+# ISCC_SEARCH_HNSW_EXPANSION_ADD_SIMPRINTS=16
+
+# Query-time search depth (ef) for simprint indexes
+# ISCC_SEARCH_HNSW_EXPANSION_SEARCH_SIMPRINTS=512
+
+# Graph connectivity (M) for simprint indexes
+# ISCC_SEARCH_HNSW_CONNECTIVITY_SIMPRINTS=8
+
+# --- Match Thresholds ---
+
+# Minimum score for unit similarity matches (0.0-1.0)
+# ISCC_SEARCH_MATCH_THRESHOLD_UNITS=0.75
+
+# Minimum score for simprint matches (0.0-1.0)
+# ISCC_SEARCH_MATCH_THRESHOLD_SIMPRINTS=0.75
+
+# --- Scoring ---
+
+# Exponent for confidence-weighted score aggregation
+# ISCC_SEARCH_CONFIDENCE_EXPONENT=4
+
+# Oversampling multiplier for simprint search diversity
+# ISCC_SEARCH_OVERSAMPLING_FACTOR=20
+
+# --- Error Tracking (Sentry) ---
+
+# Sentry DSN for error tracking (unset = disabled)
+# ISCC_SEARCH_SENTRY_DSN=
+
+# Sentry performance sampling rate (0.0-1.0)
+# ISCC_SEARCH_SENTRY_TRACES_SAMPLE_RATE=0.05

.github/actions/setup-python-env/action.yml

@@ -14,12 +14,12 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: ${{ inputs.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v2
+      uses: astral-sh/setup-uv@v8.0.0
       with:
         version: ${{ inputs.uv-version }}
         enable-cache: 'true'

.github/workflows/ci.yml

@@ -0,0 +1,223 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [develop, main]
+
+# Cancel stale in-flight PR runs; let push runs complete so publish isn't cancelled.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  test-full:
+    name: Test (ubuntu-latest, py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # hatch-vcs needs git history to derive version
+
+      - uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # Cache the iscc-sct ONNX model across runs. Parallel pytest-xdist workers
+      # otherwise race on the download and can produce a corrupt ONNX file.
+      - name: Cache iscc-sct model
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.local/share/iscc-sct
+            ~/Library/Application Support/iscc-sct
+            ~\AppData\Local\iscc\iscc-sct
+          key: iscc-sct-model-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            iscc-sct-model-${{ runner.os }}-
+
+      - name: Pre-download iscc-sct model (serial, before parallel tests)
+        run: uv run python -c "import iscc_sct.code_semantic_text as sct; sct.model()"
+
+      - name: OpenAPI build + validation
+        run: uv run poe build
+
+      - name: Run tests
+        run: uv run poe test
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v6
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  test-smoke:
+    name: Test (${{ matrix.os }}, py3.12)
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-env
+        with:
+          python-version: "3.12"
+
+      - name: Cache iscc-sct model
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.local/share/iscc-sct
+            ~/Library/Application Support/iscc-sct
+            ~\AppData\Local\iscc\iscc-sct
+          key: iscc-sct-model-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            iscc-sct-model-${{ runner.os }}-
+
+      - name: Pre-download iscc-sct model
+        run: uv run python -c "import iscc_sct.code_semantic_text as sct; sct.model()"
+
+      - name: Run tests
+        run: uv run poe test
+
+  wheel-build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-env
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  wheel-smoke:
+    name: Install wheel and smoke-test
+    needs: wheel-build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Install wheel into clean venv
+        run: |
+          python -m venv .smoke-venv
+          .smoke-venv/bin/pip install --upgrade pip
+          .smoke-venv/bin/pip install dist/*.whl
+
+      - name: Verify import and CLI
+        run: |
+          .smoke-venv/bin/python -c "import iscc_search; print('version:', iscc_search.__version__)"
+          .smoke-venv/bin/iscc-search --help
+
+  docker-smoke:
+    name: Build + smoke-test Docker image
+    needs: wheel-build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - uses: docker/setup-buildx-action@v4
+
+      - name: Build image (load into local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          load: true
+          tags: iscc-search:smoke
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run container and probe health endpoints
+        run: |
+          docker run -d --name iscc-search-smoke -p 8000:8000 iscc-search:smoke
+          # Wait up to 60s for /readyz to return 200
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8000/readyz > /dev/null; then
+              echo "Ready after ${i} attempts"
+              break
+            fi
+            sleep 2
+          done
+          curl -sf http://localhost:8000/healthz
+          curl -sf http://localhost:8000/readyz
+          echo "--- container logs ---"
+          docker logs iscc-search-smoke
+          docker stop iscc-search-smoke
+
+  publish-develop:
+    name: Publish Docker image (develop)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+    needs: [test-full, test-smoke, wheel-smoke, docker-smoke]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - uses: docker/setup-buildx-action@v4
+
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=develop
+            type=sha,prefix=develop-
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha