dirsql-plugin-embeddings
A first-party dirsql plugin that
adds semantic search over a directory of Markdown files. It is the worked
implementation behind the Search documents by
meaning how-to,
swapping that guide's local model2vec model for any OpenAI-compatible
/v1/embeddings endpoint.
uvx --with dirsql-plugin-embeddings dirsql
Deliberately minimal (v0.1): one embedding provider shape, one table, no chunking, no config surface beyond three environment variables.
How it works
The plugin ships a dirsql.toml fragment that dirsql discovers when the package
is installed alongside it. The fragment declares:
- the
sqlite-vecextension, forvec_distance_cosine(); - a
documentstable whoseon-filehook embeds each**/*.mdfile into a TEXTembeddingcolumn; - a
pre-queryhook that embeds the incoming question and emits the nearest-neighbor SQL.
Both hooks are console scripts that call the same embedder.
Configuration
The embedder reads three environment variables (point them at any hosted or self-managed OpenAI-compatible inference server):
| Variable | Meaning |
|---|---|
DIRSQL_EMBEDDINGS_BASE_URL |
Base URL; /v1/embeddings is appended. |
DIRSQL_EMBEDDINGS_MODEL |
Model name sent in the request. |
DIRSQL_EMBEDDINGS_API_KEY |
Bearer token for Authorization. |
Console scripts
| Script | Hook | Input | Output |
|---|---|---|---|
dirsql-embeddings-on-file |
on-file |
a file's absolute path (argv[1]) |
one-line JSON row array with path, text, embedding |
dirsql-embeddings-pre-query |
pre-query |
a raw request body (argv[1]) |
nearest-neighbor SQL over documents |
pre-query accepts both a verbatim server body ({"q": ...}) and the CLI
query subcommand's {"sql": <arg>} wrapper, so dirsql query '{"q": ...}' and
a real POST /query both work.
Tests
Three tiers, per the dirsql testing conventions:
- unit (colocated, mocked seams) —
src/dirsql_plugin_embeddings/*_test.py - integration (
tests/integration/) — each console script as a real subprocess against a local stub/v1/embeddingsserver - e2e (
tests/e2e/) — the full loop through the real launcher +dirsqlbinary +sqlite-vec, nothing mocked but the embedding endpoint
Metadata
Release files for dirsql-plugin-embeddings 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dirsql_plugin_embeddings-0.1.4.tar.gz | 7.2 kB | With provenance | Details for dirsql_plugin_embeddings-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dirsql_plugin_embeddings-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for dirsql_plugin_embeddings-0.1.4-py3-none-any.whl |
Total release size: 15.8 kB
Release files / dirsql_plugin_embeddings-0.1.4.tar.gz
| Download URL | dirsql_plugin_embeddings-0.1.4.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d28dd5bece984a536b9b7307f7b4f3151e801f1f3c35b3976ccb8e6a5a778916
|
|
BLAKE2b-256 checksum How to use checksums |
98deea0af7bf435e9aa3950313f0bf8d97333e3c7cb2e05571636167222021a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency logRelease files / dirsql_plugin_embeddings-0.1.4-py3-none-any.whl
| Download URL | dirsql_plugin_embeddings-0.1.4-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0da4fbe403b6ced136189c878d024ab76354bd7241a8c44152854d66a8c719f0
|
|
BLAKE2b-256 checksum How to use checksums |
aababff96cb4aada19219e47f8676d9c5e1b5f9b7ff0ee7f5de379f269810d29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency logSecurity for dirsql-plugin-embeddings 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dirsql_plugin_embeddings-0.1.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.