Skip to content

Contributing

Set up

git clone https://github.com/kkollsga/kglite-docs
cd kglite-docs
uv venv --python 3.12
uv pip install -e ".[dev]"

The bge-m3 ONNX weights (~2 GB) download on first test run that exercises the real embedder. If you have them cached at a non-default path:

export HF_HUB_CACHE=/path/to/hub
export FASTEMBED_CACHE_PATH=/path/to/hub

Run the tests

pytest                          # full suite (will download bge-m3 on the embed-marked tests)
pytest -m "not embed"            # fast path; uses the stub embedder
pytest tests/test_quality.py     # one file
pytest -k "verification"         # one keyword
pytest --cov=kglite_docs         # with coverage

The default suite uses a deterministic stub embedder so it runs in well under a second. @pytest.mark.embed tests need bge-m3 weights and take a few seconds.

Lint + type-check

uv run ruff check src/ tests/
uv run mypy src/kglite_docs       # advisory in v0.1

Release process

  1. Bump the version implicitly via a git tag: git tag v0.1.0 && git push --tags.
  2. The release.yml workflow:
  3. Builds sdist + wheel
  4. Publishes to PyPI (trusted publisher)
  5. Creates a GitHub Release with autogenerated notes
  6. No manual API tokens — PyPI uses OIDC trusted publishing. You configure that once per project at https://pypi.org/manage/account/publishing/.

hatch-vcs derives the version from the git tag. The build inserts __version__ into src/kglite_docs/_version.py automatically.

Project layout cheat sheet

kglite-docs/
├── src/kglite_docs/        # the package
│   ├── corpus.py           # public façade
│   ├── ingest/             # parsing + chunking
│   ├── embed.py            # bge-m3 adapter
│   ├── store.py            # kglite wrapping
│   ├── schema.py           # node/edge constants
│   ├── enrich.py           # summaries + verification
│   ├── tagging.py          # tags (reified for multi-agent)
│   ├── activity.py         # agents + views
│   ├── ocr.py              # scanned-page handoff
│   ├── cluster.py          # clustering procedures
│   ├── quality.py          # grounding + claim verification
│   ├── translate.py        # per-chunk translations
│   ├── export.py           # MD / DOCX / PDF
│   ├── context.py          # budgeted prompt composer
│   ├── agents.py           # Anthropic SDK / claude CLI shim
│   ├── cli.py              # `kglite-docs` CLI
│   └── mcp_server/         # FastMCP wiring
├── tests/                  # pytest
├── demos/workflow.py        # end-to-end Sonnet demo
├── docs/                   # this folder
├── sample_data/pdfs/       # 16 arXiv papers + a few non-PDFs
└── .github/workflows/      # ci.yml + release.yml

Pull requests

  • One concern per PR; small + focused beats large + sprawling.
  • Add or extend tests for any user-visible change.
  • The embed-marked tests are advisory in CI (they're skipped to keep CI fast and avoid bge-m3 downloads); run them locally before opening a PR that touches ingest/, enrich.py, or quality.py.