Spaces:
Runtime error
Runtime error
File size: 6,311 Bytes
e6be672 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | # 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.
|