logosdb 0.2.0__tar.gz

logosdb-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    name: ${{ matrix.os }} / ${{ matrix.build_type }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        build_type: [Debug, Release]
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install build tools (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends cmake ninja-build build-essential
+
+      - name: Install build tools (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew update
+          brew install cmake ninja
+
+      - name: Report toolchain versions
+        run: |
+          cmake --version
+          ninja --version || true
+          c++ --version || true
+
+      - name: Cache CMake build directory
+        uses: actions/cache@v4
+        with:
+          path: build
+          key: ${{ matrix.os }}-${{ matrix.build_type }}-cmake-${{ hashFiles('CMakeLists.txt', 'src/**', 'include/**', 'tools/**', 'tests/**', 'third_party/**') }}
+          restore-keys: |
+            ${{ matrix.os }}-${{ matrix.build_type }}-cmake-
+
+      - name: Configure
+        run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+
+      - name: Build
+        run: cmake --build build --config ${{ matrix.build_type }} --parallel
+
+      - name: List built targets
+        run: ls -la build
+
+      - name: Run tests
+        working-directory: build
+        run: ctest --output-on-failure --build-config ${{ matrix.build_type }}
+
+      - name: Smoke-test CLI
+        working-directory: build
+        run: |
+          rm -rf /tmp/ci-smoke-db
+          ./logosdb-cli info /tmp/ci-smoke-db --dim 16

logosdb-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,112 @@
+name: Publish
+
+on:
+  # Release flow: push an annotated tag matching v*.*.*
+  #   git tag v0.2.0 && git push origin v0.2.0
+  push:
+    tags: ["v*"]
+  # Manual trigger lets you exercise the full wheel matrix without cutting a
+  # tag. The default target is `dry_run` (build only, no upload) so accidental
+  # runs can never hit production; choose `pypi` to actually publish.
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to upload"
+        required: true
+        default: "dry_run"
+        type: choice
+        options:
+          - dry_run
+          - pypi
+
+jobs:
+  # ── Build ────────────────────────────────────────────────────────
+  build_wheels:
+    name: Wheels ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu-latest     → manylinux x86_64 (native; do not set dual arch in
+        #                       pyproject — that runs x86_64 Docker on ARM and
+        #                       fails with "exec format error")
+        # ubuntu-24.04-arm  → manylinux aarch64 (native)
+        # macos-13          → macOS x86_64 (Intel runner)
+        # macos-14          → macOS arm64 (Apple Silicon runner)
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-14]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+
+      - name: Upload wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+          if-no-files-found: error
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: Verify sdist contents
+        run: |
+          echo "── sdist contents ──"
+          ls -la dist/
+          tar tzf dist/*.tar.gz | head -60
+          echo "── checking third_party/hnswlib is included ──"
+          tar tzf dist/*.tar.gz | grep hnswlib | head -5
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  # ── Publish: PyPI ────────────────────────────────────────────────
+  # Runs only when a version tag was pushed, OR when dispatched manually
+  # with target=pypi. The `environment: pypi` can be configured in the
+  # repo settings to require a reviewer before this job runs.
+  publish_pypi:
+    name: Upload to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: >-
+      startsWith(github.ref, 'refs/tags/v') ||
+      (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/logosdb/
+    permissions:
+      id-token: write   # Trusted Publishing (OIDC)
+    steps:
+      - name: Download all artifacts into dist/
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: List artifacts
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

logosdb-0.2.0/.github/workflows/python.yml

@@ -0,0 +1,77 @@
+name: Python
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+      - "CMakeLists.txt"
+      - "python/**"
+      - "src/**"
+      - "include/**"
+      - "third_party/**"
+      - "tests/python/**"
+      - ".github/workflows/python.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+      - "CMakeLists.txt"
+      - "python/**"
+      - "src/**"
+      - "include/**"
+      - "third_party/**"
+      - "tests/python/**"
+      - ".github/workflows/python.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  wheel-and-test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build tools (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends cmake ninja-build build-essential
+
+      - name: Install build tools (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew update
+          brew install cmake ninja
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Build and install wheel
+        run: python -m pip install -v .
+
+      - name: Install pytest
+        run: python -m pip install pytest
+
+      - name: Run Python tests
+        run: python -m pytest tests/python/ -v
+
+      - name: Run example script
+        run: python examples/python/basic_usage.py

logosdb-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+build/
+*.o
+*.a
+*.so
+*.dylib
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+wheelhouse/

logosdb-0.2.0/CHANGELOG

@@ -0,0 +1,70 @@
+logosdb change log
+==================
+
+0.2.0  (2026-04-17)
+-------------------
+
+  Highlights: first PyPI release with Python bindings, public delete/update
+  API, and CI across Linux and macOS.
+
+  Delete / update API (closes #3)
+
+  * Added logosdb_delete(id) and logosdb_update(id, ...) to the public C API,
+    with matching DB::del() and DB::update() on the C++ wrapper. Deletions
+    are persisted as tombstone records in the JSONL metadata log and replayed
+    onto the HNSW index on reopen (including when the index file is missing
+    and has to be rebuilt from vectors.bin).
+  * Added logosdb_count_live() / DB::count_live() returning total rows minus
+    deleted rows. logosdb_count() continues to report the total (including
+    tombstoned rows) for storage-level introspection.
+  * Metadata JSONL format now also carries tombstone records of the form
+    {"op":"del","id":N}. Older data files remain readable.
+  * New C++ tests cover delete/update/re-put, persistence across reopen, and
+    tombstone replay after an index rebuild.
+
+  Python bindings and PyPI release (closes #4)
+
+  * Added Python bindings (pybind11 + scikit-build-core). pip install logosdb
+    installs a native extension that exposes logosdb.DB with put, search,
+    delete, update, count, count_live, dim, raw_vectors (zero-copy numpy
+    view) and logosdb.SearchHit. Smoke tests under tests/python/ and a
+    numpy/sentence-transformers example under examples/python/.
+  * CMakeLists.txt gained LOGOSDB_BUILD_TOOLS, LOGOSDB_BUILD_TESTS, and
+    LOGOSDB_BUILD_PYTHON options so the Python wheel build skips CLI /
+    benchmark / C++ test targets. The static core library now builds with
+    position-independent code so it can be linked into the Python extension.
+  * Added PyPI release plumbing: cibuildwheel configuration in
+    pyproject.toml and a .github/workflows/publish.yml workflow that, on
+    every v* tag, builds wheels for {Linux, macOS} x {x86_64, arm64} x
+    CPython {3.9..3.13}, builds the sdist, and uploads everything to PyPI
+    via Trusted Publishing (OIDC, no API tokens). A RELEASING.md runbook
+    documents the one-time Trusted Publisher setup and the release flow.
+
+  CI and infrastructure (closes #1)
+
+  * New .github/workflows/ci.yml builds and tests on ubuntu-latest and
+    macos-latest in both Debug and Release via CMake + Ninja, runs ctest,
+    and smoke-tests the CLI. Build directory is cached across runs.
+  * New .github/workflows/python.yml builds the Python wheel and runs the
+    pytest smoke suite on Linux and macOS for CPython 3.10 and 3.12.
+  * Fixed a latent transitive-include bug in tools/logosdb-bench.cpp that
+    broke the build on Ubuntu's libstdc++ (std::partial_sort requires an
+    explicit <algorithm> include).
+
+0.1.0  (2025-06-25)
+-------------------
+
+  Initial release.
+
+  * HNSW-based approximate nearest-neighbor search (hnswlib).
+  * Binary mmap-backed vector storage with fixed-stride rows.
+  * Append-only JSONL metadata store (text + ISO 8601 timestamp per row).
+  * RocksDB/LevelDB-style C API with opaque handles and errptr convention.
+  * C++ convenience wrapper (logosdb::DB) with RAII and exceptions.
+  * logosdb-cli command-line tool (put, search, info).
+  * logosdb-bench benchmark tool (HNSW vs brute-force).
+  * Crash recovery: HNSW index backfill from vector store on open.
+  * Thread-safe writes; lock-free concurrent reads.
+  * Integer overflow and bounds-checked storage arithmetic.
+  * 76 unit tests covering core operations, persistence, edge cases,
+    dimension mismatch rejection, and accessor bounds.

logosdb-0.2.0/CMakeLists.txt

@@ -0,0 +1,69 @@
+cmake_minimum_required(VERSION 3.15)
+project(logosdb VERSION 0.2.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+option(LOGOSDB_BUILD_TOOLS  "Build CLI and benchmark tools" ON)
+option(LOGOSDB_BUILD_TESTS  "Build unit tests"              ON)
+option(LOGOSDB_BUILD_PYTHON "Build Python bindings (pybind11)" OFF)
+
+# hnswlib is header-only
+add_library(hnswlib INTERFACE)
+target_include_directories(hnswlib INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/third_party)
+
+# Core library
+add_library(logosdb
+    src/logosdb.cpp
+    src/storage.cpp
+    src/metadata.cpp
+    src/hnsw_index.cpp
+)
+target_include_directories(logosdb PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+target_link_libraries(logosdb PRIVATE hnswlib)
+
+# Position-independent code is required when the static library is linked
+# into a shared object (the Python extension is a .so).
+set_target_properties(logosdb PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+if(APPLE)
+    # No extra link flags needed for mmap on macOS
+elseif(UNIX)
+    target_link_libraries(logosdb PRIVATE pthread)
+endif()
+
+if(LOGOSDB_BUILD_TOOLS)
+    add_executable(logosdb-cli tools/logosdb-cli.cpp)
+    target_link_libraries(logosdb-cli PRIVATE logosdb)
+
+    add_executable(logosdb-bench tools/logosdb-bench.cpp)
+    target_link_libraries(logosdb-bench PRIVATE logosdb)
+endif()
+
+if(LOGOSDB_BUILD_TESTS)
+    add_executable(logosdb-test tests/test_basic.cpp)
+    target_link_libraries(logosdb-test PRIVATE logosdb)
+
+    enable_testing()
+    add_test(NAME logosdb_basic COMMAND logosdb-test)
+endif()
+
+if(LOGOSDB_BUILD_PYTHON)
+    # Discover Python and pybind11. When built by scikit-build-core,
+    # pybind11 is provided via the build isolation environment.
+    set(PYBIND11_FINDPYTHON ON)
+    find_package(pybind11 CONFIG REQUIRED)
+
+    pybind11_add_module(_core MODULE python/src/bindings.cpp)
+    target_link_libraries(_core PRIVATE logosdb)
+    target_compile_definitions(_core PRIVATE
+        LOGOSDB_PY_VERSION="${PROJECT_VERSION}"
+    )
+
+    # Install the extension module inside the `logosdb` package directory
+    # so it is importable as `logosdb._core`.
+    install(TARGETS _core LIBRARY DESTINATION logosdb)
+endif()

logosdb-0.2.0/LICENSE

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