bimquery-api / CONTRIBUTING.md
BIM Query Deploy
Claude Opus 4.7 (1M context)
deploy: initial BIM Query API on Hugging Face Spaces
e6be672
|
Raw History Blame Contribute Delete
6.31 kB

Contributing to BIM Query

Thanks for thinking about contributing β€” every PR, issue, or doc fix helps. πŸ™

This project is at an early public stage, so contributions of all sizes are welcome: bug reports, doc fixes, new handlers, performance work, examples, tests. There's a huge surface area to improve, and most of the in-progress work is honestly documented in the Handler status table β€” pick something that looks fun.

πŸ’‘ Haven't seen BIM Query in action yet? Play with the live demo at bimquery.net first β€” it'll give you a feel for the user-facing behaviour before you dive into the code.

By contributing, you agree that your contributions will be licensed under the GNU AGPL-3.0.


Where to start

Good first contributions

  • Documentation: clarify a confusing section, add an example, fix a typo. README, docstrings, this file β€” all fair game.
  • Tests: the test suite is uneven. Adding tests for an existing handler is always welcome.
  • Bug fixes: look at the issue tracker, especially anything tagged good first issue or help wanted.
  • Finish a handler: see Handler status. SUMMARY is the biggest open area today β€” the plugin lives under app/intents/summary/ and follows a clean, self-contained pattern.
  • Add sub-intents: any of the production handlers (COUNT, LIST, SELECT, CALCULATE, DESCRIBE) can grow new sub-intents β€” open an issue first to align on the shape, then PR.

Bigger work

If you're thinking about a substantial change (new endpoint, major refactor, swap of a dependency), please open an issue first to discuss the design. It saves everyone time.


Reporting bugs

Open a GitHub issue and include:

  • What you did β€” minimal reproduction, ideally a curl snippet
  • What you expected β€” be specific
  • What happened β€” error messages, stack traces, response bodies
  • Environment β€” Python version, OS, Postgres/Redis versions, whether pythonocc-core is installed
  • The IFC file β€” if the bug is data-dependent, attach the smallest IFC that triggers it (please anonymise project metadata first)

Reporting security issues

Do not open a public issue for security vulnerabilities. See SECURITY.md for the private disclosure process.


Development setup

git clone https://github.com/mzat-dev/bimquery.git
cd bimquery

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env                 # then edit: DB / Redis / S3 / API_KEY / LLM keys
alembic upgrade head
uvicorn app.main:app --reload --port 8080

You'll also need:

  • PostgreSQL 15+ with the pgvector extension
  • Redis 7+
  • An S3-compatible object store (MinIO is the easiest for local dev)

How you stand those up is up to you β€” Docker, native installs, hosted dev tiers, whatever fits. The project intentionally doesn't ship an opinionated deployment.

pythonocc-core note: the SPATIAL and advanced CALCULATE handlers need pythonocc-core, which is most easily installed via conda-forge / micromamba rather than pip. Other handlers (COUNT, LIST, SELECT, DESCRIBE) work without it, so you can skip it for most contributions.


Pull-request workflow

  1. Fork the repo and create a feature branch from main:
    git checkout -b feat/short-description
    
  2. Write code + tests. New behaviour without tests will usually not be merged.
  3. Run quality checks locally:
    ruff check .
    black --check .
    mypy app/
    pytest
    
  4. Commit using Conventional Commits:
    • feat: add spatial distance handler
    • fix: handle empty IFC files in upload
    • docs: clarify groq setup
    • test: cover edge cases for COUNT handler
    • refactor: extract LLM provider interface
  5. Open a PR against main with:
    • A Conventional Commit-style title
    • A description: what changed, why, how to test
    • A linked issue (if any)
  6. Address review feedback. Once approved, a maintainer will squash-merge β€” so don't worry about a messy commit history on your branch.

Code style

  • Python: black (line length 88), ruff for linting and import sorting, mypy for type-checking.
  • Docstrings: Google style. Short and useful beats long and decorative.
  • Naming: snake_case for functions, variables, modules and files; PascalCase for classes; SCREAMING_SNAKE_CASE for constants.
  • Comments and docstrings: English only. The codebase has multilingual features (NL queries in Italian, French, etc.) but the code itself is English so every contributor can read it.
  • Tests: pytest, no class boilerplate unless you actually need fixtures. Tests live next to the existing test file that covers the closest area, or in a new tests/test_<feature>.py.

Testing

pytest                               # full suite
pytest tests/test_intent_system.py -v   # a specific module
pytest --cov=app --cov-report=html   # with coverage report

Integration tests that touch Postgres / Redis / S3 expect those services to be reachable at the URLs in your .env. There's no in-process mocking β€” use whichever local setup you have.


Code of conduct

Participation in this project is governed by the Contributor Covenant. Be kind, assume good faith, and remember there's a person on the other side of every PR comment.


Licence compatibility

BIM Query is AGPL-3.0. Any code you contribute must be compatible β€” either your own original work or sourced from an AGPL-compatible licence (GPL-3.0+, LGPL, MIT, BSD, Apache 2.0 in most cases). If you bring third-party code, please flag it in your PR description.


Thank you for being here. πŸ™Œ

If you get stuck or aren't sure how to proceed with a contribution, open a draft PR or a discussion issue β€” we'd rather help early than receive a polished PR that needs a structural rework.