Skip to content

Add a Python API page - #20

Merged
ahmad-codex merged 1 commit into
ahmad-codex:mainfrom
am-official:docs/python-api
Oct 26, 2026
Merged

ahmad-codex merged 1 commit into
ahmad-codex:mainfrom
am-official:docs/python-api

Conversation

@am-official

Copy link
Copy Markdown
Contributor

What and why

Adds docs/python.md, which documents run_lab, make_codec and run_pg for notebook use. It has a runnable example on ~2,000 small random vectors, tables of the arguments and result fields, the pipeline syntax (search[>rerank[:candidates]]), and from_lab / from_pg for getting a recommendation. The README links to it, and CHANGELOG has an Unreleased entry.

Closes #13

How it was tested

tests/test_docs.py extracts the page's python blocks and runs them in order, so the page fails the build if it drifts from the code. The run_pg example needs a database, so it is marked <!-- not tested: needs Postgres --> and is only compiled. The runnable blocks take about 4 s. I also broke one attribute name in the page to confirm the test fails on drift, then restored it.

  • uv run pytest -m "not crosscheck": 36 passed (34 before)
  • uv run ruff check src tests benchmarks and uv run ruff format --check src tests benchmarks: pass

Only run on the pinned Python locally, not the full 3.10-3.13 matrix.

Checklist

  • uv run ruff check src tests and uv run ruff format --check src tests pass
  • uv run pytest -m "not crosscheck" passes
  • A new or changed codec has a test against its paper's numbers, and pytest -m crosscheck passes when a reference implementation exists (n/a, no codec change)
  • Byte counts include every per-row float the codec stores (n/a)
  • No connection string, password or private data in code, tests or reports
  • docs/method.md and CHANGELOG.md updated where behavior or numbers change (CHANGELOG entry added; no behavior change)

docs/python.md documents run_lab, make_codec and run_pg with an example on
small random vectors. tests/test_docs.py runs its python blocks in order, so
the page breaks the build if it drifts from the code; the run_pg block needs
a database and is only compiled.
@github-actions

Copy link
Copy Markdown

Thanks for your first pull request. CI runs ruff, the tests on Python 3.10 to 3.13, the
cross-checks against rabitqlib and turbovec, a real Postgres run with pgvector and VectorChord,
and the demo image. CONTRIBUTING.md lists what reviews check.

@ahmad-codex ahmad-codex left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked every name, default and field on the page against lab.py, pg.py, recommend.py and codecs/. All correct, including the LabResult/PgPoint fields and the codec bit ranges. Ran the examples as written and got exactly the output shown. The doc test is a nice touch: no network, no Postgres, fast, and CI already picks it up through -m "not crosscheck". Tests and ruff pass locally.

Two optional nits: a couple of example lines are close to 120 chars (fine, but splitting the long prints would read better), and it might be worth noting in python_blocks that the "not tested" comment has to be on the line right above the fence. Approving.

@ahmad-codex
ahmad-codex merged commit 80b20a6 into ahmad-codex:main Oct 26, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Python API page in the docs

2 participants