iscc-search 0.1.0__tar.gz

iscc_search-0.1.0/.dockerignore

@@ -0,0 +1,11 @@
+# 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.
+
+# Ignore everything
+**
+
+# Allow the Dockerfile and the pre-built wheel produced by `uv build`
+!Dockerfile
+!dist/*.whl

iscc_search-0.1.0/.editorconfig

@@ -0,0 +1,20 @@
+# see http://editorconfig.org
+
+# Top-level config
+root = true
+
+
+# All files
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 119
+
+
+# YAML files
+[*.{yml,yaml}]
+indent_size = 2

iscc_search-0.1.0/.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

iscc_search-0.1.0/.gitattributes

@@ -0,0 +1,25 @@
+# Set default behavior to automatically normalize line endings
+* text=auto
+
+# Force LF line endings for markdown files
+*.md text eol=lf
+
+# Force LF for other text files that should have consistent endings
+*.py text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.cfg text eol=lf
+*.ini text eol=lf
+*.json text eol=lf
+*.txt text eol=lf
+*.sh text eol=lf
+Makefile text eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

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

@@ -0,0 +1,30 @@
+name: "Setup Python Environment"
+description: "Set up Python environment for the given Python version"
+
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: true
+    default: "3.12"
+  uv-version:
+    description: "uv version to use"
+    required: true
+    default: "0.6.14"
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.0.0
+      with:
+        version: ${{ inputs.uv-version }}
+        enable-cache: 'true'
+        cache-suffix: ${{ matrix.python-version }}
+
+    - name: Install Python dependencies
+      run: uv sync --frozen
+      shell: bash

iscc_search-0.1.0/.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

iscc_search-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,235 @@
+name: Release
+
+# Triggered when a GitHub Release is published. The release tag (vX.Y.Z) becomes the package version
+# via hatch-vcs. Pre-release tags (v1.0.0-rc1) publish to PyPI + ghcr but do NOT update `latest`.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    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
+
+      - uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - 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: OpenAPI build + validation
+        run: uv run poe build
+
+      - name: Run tests
+        run: uv run poe test
+
+  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 + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-env
+
+      - name: Build
+        run: uv build
+
+      - name: Verify version matches release tag
+        run: |
+          # hatch-vcs strips the leading `v` from tags, so `v0.1.0` → `0.1.0`
+          expected="${GITHUB_REF_NAME#v}"
+          actual=$(ls dist/iscc_search-*.whl | sed -E 's|dist/iscc_search-([^-]+)-.*|\1|' | head -1)
+          if [ "$expected" != "$actual" ]; then
+            echo "::error::Wheel version ($actual) does not match release tag ($expected)"
+            exit 1
+          fi
+          echo "Version verified: $actual"
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  wheel-smoke:
+    name: Smoke-test wheel (${{ matrix.os }})
+    needs: wheel-build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Install and verify
+        run: |
+          python -m venv .smoke-venv
+          # Cross-platform venv bin dir:
+          if [ -d ".smoke-venv/Scripts" ]; then
+            BIN=.smoke-venv/Scripts
+          else
+            BIN=.smoke-venv/bin
+          fi
+          "$BIN/python" -m pip install --upgrade pip
+          "$BIN/python" -m pip install dist/*.whl
+          "$BIN/python" -c "import iscc_search; print('version:', iscc_search.__version__)"
+          "$BIN/iscc-search" --help
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [test, test-smoke, wheel-smoke]
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - uses: astral-sh/setup-uv@v8.0.0
+        with:
+          version: "0.6.14"
+
+      - name: Publish
+        run: uv publish dist/*
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+  publish-docker:
+    name: Publish Docker image
+    needs: [test, test-smoke, wheel-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 }}
+          # `latest=auto` attaches `latest` only to the highest non-prerelease tag.
+          flavor: |
+            latest=auto
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - 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
+          cache-to: type=gha,mode=max
+
+  deploy-docs:
+    name: Deploy documentation
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # zensical gh-deploy pushes to gh-pages
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-python-env
+
+      - name: Build docs
+        run: |
+          uv run zensical build
+          uv run python scripts/gen_llms_full.py
+
+      - name: Deploy to gh-pages
+        run: uv run zensical gh-deploy --force