Skip to main content

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-vec extension, for vec_distance_cosine();
  • a documents table whose on-file hook embeds each **/*.md file into a TEXT embedding column;
  • a pre-query hook 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/embeddings server
  • e2e (tests/e2e/) — the full loop through the real launcher + dirsql binary + 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)

Source distribution for dirsql-plugin-embeddings 0.1.4
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)

Table of built distributions (wheels) for dirsql-plugin-embeddings 0.1.4
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page