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.