Spaces:
Runtime error
Runtime error
BIM Query Deploy
Claude Opus 4.7 (1M context)
deploy: initial BIM Query API on Hugging Face Spaces
e6be672 |
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
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. | |