# 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](README.md#-handler-status) table — pick something that looks fun. > 💡 Haven't seen BIM Query in action yet? Play with the live demo at **[bimquery.net](http://www.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](LICENSE). --- ## 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](README.md#-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](SECURITY.md) for the private disclosure process. --- ## Development setup ```bash 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`](https://github.com/pgvector/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`: ```bash git checkout -b feat/short-description ``` 2. **Write code + tests.** New behaviour without tests will usually not be merged. 3. **Run quality checks locally:** ```bash ruff check . black --check . mypy app/ pytest ``` 4. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/): - `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](https://github.com/psf/black) (line length 88), [ruff](https://github.com/astral-sh/ruff) for linting and import sorting, [mypy](https://mypy-lang.org/) 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_.py`. --- ## Testing ```bash 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](CODE_OF_CONDUCT.md). 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.