duckdb-vectors 261014__tar.gz

duckdb_vectors-261014/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Report something that does not work as expected
+title: ""
+labels: "bug"
+assignees: ""
+---
+
+### What happened?
+
+<!-- What you expected, and what actually happened. -->
+
+### How to reproduce
+
+<!-- A minimal snippet or steps. The smaller, the faster we can help. -->
+
+```python
+```
+
+### Environment
+
+- duckdb-vectors version:
+- Python version:
+- Backend (`hashing` / `local` / `bedrock:...`) and read-only mode:

duckdb_vectors-261014/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

duckdb_vectors-261014/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,36 @@
+---
+name: Task
+about: Propose a feature, improvement, or fix as a four-section ticket
+title: ""
+labels: ""
+assignees: ""
+---
+
+<!--
+This project uses a four-section ticket (the TrunkFlow fat ticket): the issue
+embeds the design and a Definition of Done, so the work is understood before it
+starts. Fill in all four sections. Keep each one tight.
+-->
+
+### What is this?
+
+<!-- The feature, capability, or bug, stated precisely. Name the components
+impacted and the boundaries. -->
+
+### Why does it matter?
+
+<!-- The problem this solves and who benefits. What it unlocks or unblocks. -->
+
+### How to implement it?
+
+<!-- The design decisions, not step-by-step code. For each decision: the
+options considered and the preferred option with its rationale. -->
+
+### Definition of done
+
+<!-- A checkable, ordered task list. Include docs, tests, implementation, and
+verification. -->
+
+- [ ]
+- [ ]
+- [ ] Lint (`ruff check`, `ruff format --check`) and tests (`pytest`) pass.

duckdb_vectors-261014/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!--
+Thanks for the contribution. The design rationale lives in the linked issue
+(the four-section ticket); this template confirms what changed and that it is
+ready to merge. Keep each pull request focused on one change.
+-->
+
+## Summary
+
+<!-- What this changes, in a sentence or two. -->
+
+## Linked issue
+
+<!-- e.g. Closes #12. If there is no issue, briefly state the motivation here. -->
+
+Closes #
+
+## Changes
+
+<!-- The notable changes, as a short list. -->
+
+-
+
+## Checklist
+
+- [ ] One focused change.
+- [ ] Tests added or updated for the behavior.
+- [ ] `uv run ruff format .` and `uv run ruff check .` pass.
+- [ ] `uv run pytest -q` passes.
+- [ ] Docs updated (README or docstrings) if behavior changed.
+- [ ] Fits the project principles (retrieval-only, boring/composable,
+      framework-agnostic, read-fast).

duckdb_vectors-261014/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Create venv and install
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Test
+        run: uv run pytest -q

duckdb_vectors-261014/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC).
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build wheel and sdist
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

duckdb_vectors-261014/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# DuckDB artifacts
+*.duckdb
+*.duckdb.wal
+
+# Transient build output (ping-agentcore.out/, etc.) — the *.out convention
+*.out/
+# AgentCore CLI state, if ever written outside a build dir
+.bedrock_agentcore/
+.bedrock_agentcore.yaml
+
+# OS
+.DS_Store

duckdb_vectors-261014/.hadolint.yaml

@@ -0,0 +1,18 @@
+# hadolint configuration for the example Dockerfiles.
+# These are teaching examples where clarity is favored over production pinning.
+ignored:
+  # DL3013: pin pip versions. The examples install `duckdb-vectors` by name to
+  # show the simplest form; the package is not yet on PyPI, so a pinned version
+  # here would be misleading. Pin in your own production image.
+  - DL3013
+  # DL3059: consecutive RUN instructions. The examples keep the install step and
+  # the index-build step as separate, readable RUN lines on purpose.
+  - DL3059
+  # DL3008: pin apt versions. The RAG example installs a build toolchain
+  # (build-essential, cmake) to compile llama-cpp-python; pinning apt versions
+  # in a throwaway test image is unnecessary ceremony.
+  - DL3008
+  # SC2086: word-splitting on the wheel glob. The examples install the single
+  # locally built wheel via `$(echo dist/*.whl)[extra]`; the glob is intentional
+  # and the paths have no spaces, so the word-splitting warning does not apply.
+  - SC2086

duckdb_vectors-261014/.markdownlint.json

@@ -0,0 +1,19 @@
+{
+  "MD009": false,
+  "MD013": false,
+  "MD014": false,
+  "MD022": false,
+  "MD024": false,
+  "MD025": false,
+  "MD026": false,
+  "MD028": false,
+  "MD029": false,
+  "MD032": false,
+  "MD033": false,
+  "MD034": false,
+  "MD036": false,
+  "MD038": false,
+  "MD040": false,
+  "MD047": false,
+  "MD060": false
+}

duckdb_vectors-261014/CHANGES.md

@@ -0,0 +1,62 @@
+# Changes
+
+## Pending
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## v261014
+
+First public release of duckdb-vectors: an embeddable, S3-Vectors-flavored
+semantic-search building block over a local DuckDB file, with hybrid vector
+plus exact-token BM25 retrieval, pluggable embedding and chunking, a CLI, and
+end-to-end container lifecycles. Versioning is now derived from git tags.
+
+### Added
+
+- VectorStore over a single DuckDB file: S3-flavored put/query plus
+  chunk-first add/query, per-chunk ETag, dual read-write/read-only lifecycle (#1)
+- hybrid retrieval: brute-force cosine distance fused with exact-token BM25
+  via reciprocal rank fusion, hybrid by default (#1)
+- pluggable embedders (local fastembed default, bedrock Titan, deterministic
+  hashing test fixture) and a swappable markdown chunker (#1)
+- CLI to index a folder, report, and search (#1)
+- metadata-aware search via injectable ranking SQL with built-in defaults (#2)
+- comprehensive documentation set, contributor onboarding, and an indexed
+  developer workbook (#3, #4, #6)
+- lean Makefile covering setup, lint, test, build, and ping targets (#5)
+- end-to-end ping lifecycles for Docker, Lambda, and AgentCore driven from
+  make targets and shell snippets (#7)
+- mypy type checking wired into the lint stage (#8)
+
+### Changed
+
+- derive the package version from git tags via hatch-vcs instead of a
+  hardcoded string
+- build the BM25 index without stemming or stopwords for exact-token and
+  acronym matching
+- lead the docs and examples with the local backend, reframing hashing as a
+  test-only fixture (#4)
+- lint Markdown and Dockerfiles alongside Python; make hadolint setup
+  platform-neutral (#5)
+- make setup non-interactive and venv-isolated (#5)
+- assemble the AgentCore agent in a *.out build dir to keep the committed
+  example pristine (#7)
+- polish PyPI packaging metadata (#1)
+
+### Removed
+
+- drop the hardcoded `__version__` constant from the package in favour of
+  tag-derived versioning
+- drop the personal AWS profile name from the ping snippets (#7)
+
+### Metrics
+
+- tests: 39 passed, 1 skipped
+- python: 2379 lines (34 files)
+- markdown: 3940 lines (34 files)

duckdb_vectors-261014/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to duckdb-vectors
+
+Thanks for considering a contribution. `duckdb-vectors` grows through small,
+focused improvements, and new contributors are genuinely welcome — whether you
+fix a typo, add an embedding backend, or sharpen the docs.
+
+This page helps you decide whether a change fits before you dive in. The full
+developer reference — prerequisites, setup, the Makefile workflow, testing, and
+the detailed conventions — lives in the
+[developer workbook](documentation/developer-workbook.md).
+
+## Does your change fit?
+
+`duckdb-vectors` is intentionally small, and the best contributions keep it
+that way: one clear thing, done well, with a test and a line of docs. A change
+fits when it respects the project's shape:
+
+- __Do one thing well.__ This is a retrieval building block — store, index,
+  search. Generation, prompting, and LLM orchestration belong in the harness,
+  not here.
+- __Boring, composable technology.__ Prefer the standard library and DuckDB's
+  own features over new dependencies; heavy ones belong behind an optional
+  extra.
+- __Framework-agnostic.__ No hard dependency on a specific agent framework.
+- __Read-mostly and fast.__ The serving path opens read-only and answers in
+  tens of milliseconds.
+
+## Good first contributions
+
+You do not need to understand the whole codebase to help:
+
+- __Add an embedding backend__ — the registry is the main extension point.
+- __Add a chunker__ — for a document format not covered well yet.
+- __Improve the docs__ — clarify a page or add a worked example.
+- __Share a ranking recipe__ — a neat injectable `vector_sql` / `text_sql`.
+- __Report a rough edge__ — a clear issue with a minimal reproduction.
+
+The [developer workbook](documentation/developer-workbook.md) explains how to do
+each of these, how to set up your environment (`make setup`), and how to run the
+checks (`make lint`, `make test`) before you open a pull request. If you are
+unsure where to start, open an issue describing what you want to do.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE) that covers this project.

duckdb_vectors-261014/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernard Paques
+
+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.

duckdb_vectors-261014/Makefile

@@ -0,0 +1,126 @@
+help:
+	@echo "Common commands:"
+	@echo "$$ make setup     - Check prerequisites, create the venv, install tooling"
+	@echo "$$ make lint      - Run Ruff, Markdown, and Dockerfile lint checks"
+	@echo "$$ make test      - Run the pytest suite"
+	@echo "$$ make format    - Format Python code with Ruff"
+	@echo "$$ make build     - Build the wheel and sdist with uv"
+	@echo "$$ make clean     - Remove build artifacts and caches"
+	@echo "$$ make ping-docker    - End-to-end ping: offline RAG container"
+	@echo "$$ make ping-lambda    - End-to-end ping: deploy and invoke on AWS Lambda"
+	@echo "$$ make ping-agentcore - End-to-end ping: deploy and invoke on Bedrock AgentCore"
+	@echo "$$ make push      - Rebase onto main and push commits to git remote"
+	@echo " ... and you have access to git, uv, ruff and pytest directly as well."
+
+# combine lines of each target
+.ONESHELL:
+# ensure child processes get variables set in this Makefile
+.EXPORT_ALL_VARIABLES:
+
+# default embedding backend for the CLI and examples
+# "local" uses fastembed (minimum viable setup); "bedrock:titan" embeds in the
+# cloud; "hashing" is a deterministic, dependency-free fixture for tests only
+DUCKDB_VECTORS_BACKEND ?= local
+# default DuckDB database path
+DUCKDB_VECTORS_DB_PATH ?= vectors.duckdb
+# default Python path for imports
+PYTHONPATH ?= .
+# source locations for static analysis
+PYTHON_PATHS := src/ tests/ examples/
+# markdown files for static analysis
+MARKDOWN_FILES := README.md CONTRIBUTING.md $(shell find documentation -name '*.md')
+# Dockerfiles for static analysis
+DOCKERFILES := $(shell find . -name 'Dockerfile' -not -path './.venv/*')
+
+setup: check-prerequisites setup-python setup-markdownlint setup-hadolint
+
+check-prerequisites:
+	@echo "Checking prerequisites (see CONTRIBUTING.md)..."
+	@command -v python3 >/dev/null || { echo "ERROR: python3 not found — install Python 3.12+"; exit 1; }
+	@command -v uv >/dev/null || { echo "ERROR: uv not found — see https://docs.astral.sh/uv/"; exit 1; }
+	@command -v docker >/dev/null || echo "WARNING: docker not found — needed only for the example container agents"
+	@command -v npm >/dev/null || echo "WARNING: npm not found — needed for setup-markdownlint"
+	@command -v hadolint >/dev/null || echo "WARNING: hadolint not found — needed for lint-dockerfile; see https://github.com/hadolint/hadolint#install"
+
+setup-python:
+	@echo "Creating virtual environment with uv..."
+	uv venv --clear
+	@echo "Installing the package with all extras..."
+	uv pip install --python .venv/bin/python -e ".[local,bedrock,cli,dev]"
+
+setup-markdownlint:
+	@command -v markdownlint >/dev/null && markdownlint --version || { \
+		echo "Installing markdownlint-cli via npm..."; \
+		npm install markdownlint-cli -g || { \
+			echo "npm global install failed (often a permissions issue)."; \
+			echo "Install markdownlint-cli yourself, e.g. 'npm install -g"; \
+			echo "markdownlint-cli' with a user-writable npm prefix. Needed"; \
+			echo "only for 'make lint-markdown'."; \
+		}; \
+	}
+
+setup-hadolint:
+	@command -v hadolint >/dev/null && hadolint --version || { \
+		echo "hadolint not found. It has no pip/npm package; install it for"; \
+		echo "your platform from https://github.com/hadolint/hadolint#install"; \
+		echo "(binary release, Docker image 'hadolint/hadolint', or a native"; \
+		echo "package). Needed only for 'make lint-dockerfile'."; \
+	}
+
+lint: lint-python lint-markdown lint-dockerfile
+
+lint-python:
+	@echo "Running Ruff linter..."
+	.venv/bin/ruff check ${PYTHON_PATHS}
+	@echo "Running Ruff format check..."
+	.venv/bin/ruff format --check ${PYTHON_PATHS}
+	@echo "Running mypy type check..."
+	.venv/bin/mypy
+
+lint-markdown:
+	@echo "Validating Markdown files..."
+	markdownlint ${MARKDOWN_FILES}
+
+lint-dockerfile:
+	@echo "Validating Dockerfiles..."
+	hadolint ${DOCKERFILES}
+
+format:
+	@echo "Formatting Python code with Ruff..."
+	.venv/bin/ruff format ${PYTHON_PATHS}
+
+test:
+	@echo "Running tests..."
+	.venv/bin/pytest -q
+
+build:
+	@echo "Building wheel and sdist..."
+	uv build
+
+clean:
+	@echo "Removing build artifacts and caches..."
+	rm -rf dist build *.egg-info src/*.egg-info *.out
+	rm -rf .ruff_cache .pytest_cache
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+
+# End-to-end ping tests. Each runs a shell snippet from fixtures/shell/ that
+# builds a search agent from documentation/, runs the fixed query, and pipes
+# the result to the shared Python validator. The AWS pings create real,
+# billable resources and leave them running; use AWS_PROFILE to select the
+# account. The venv is put on PATH so the snippets' `python` is the project's.
+PING_ENV := PATH="$(PWD)/.venv/bin:$$PATH"
+
+ping-docker:
+	$(PING_ENV) bash fixtures/shell/ping-docker.sh
+
+ping-lambda:
+	$(PING_ENV) bash fixtures/shell/ping-lambda.sh
+
+ping-agentcore:
+	$(PING_ENV) bash fixtures/shell/ping-agentcore.sh
+
+rebase:
+	git pull --rebase origin main
+
+push: rebase
+	git push