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](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_<feature>.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.