Spaces:
Runtime error
Download CONTRIBUTING.md from 12mhsssss/bimquery-api: direct link, hf CLI and curl.
- Browser
- Download file 6.31 kB
-
https://huggingface.co/spaces/12mhsssss/bimquery-api/resolve/main/CONTRIBUTING.md
- Command line
-
hf download hf://spaces/12mhsssss/bimquery-api/CONTRIBUTING.md
-
curl -L -o CONTRIBUTING.md https://huggingface.co/spaces/12mhsssss/bimquery-api/resolve/main/CONTRIBUTING.md
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 issueorhelp wanted. - Finish a handler: see Handler status.
SUMMARYis the biggest open area today β the plugin lives underapp/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
curlsnippet - What you expected β be specific
- What happened β error messages, stack traces, response bodies
- Environment β Python version, OS, Postgres/Redis versions, whether
pythonocc-coreis 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
pgvectorextension - 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-corenote: the SPATIAL and advanced CALCULATE handlers needpythonocc-core, which is most easily installed viaconda-forge/micromambarather than pip. Other handlers (COUNT, LIST, SELECT, DESCRIBE) work without it, so you can skip it for most contributions.
Pull-request workflow
- Fork the repo and create a feature branch from
main:git checkout -b feat/short-description - Write code + tests. New behaviour without tests will usually not be merged.
- Run quality checks locally:
ruff check . black --check . mypy app/ pytest - Commit using Conventional Commits:
feat: add spatial distance handlerfix: handle empty IFC files in uploaddocs: clarify groq setuptest: cover edge cases for COUNT handlerrefactor: extract LLM provider interface
- Open a PR against
mainwith:- A Conventional Commit-style title
- A description: what changed, why, how to test
- A linked issue (if any)
- 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_casefor functions, variables, modules and files;PascalCasefor classes;SCREAMING_SNAKE_CASEfor 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.