|
| 1 | +# Contributing to zhub |
| 2 | + |
| 3 | +Thanks for considering a contribution. zhub is intentionally small: each file does one thing, the test bar is high, and the public surface stays neutral. Keeping it that way is the contribution. |
| 4 | + |
| 5 | +## Setup |
| 6 | + |
| 7 | +```bash |
| 8 | +git clone https://github.com/Zawwarsami16/zhub |
| 9 | +cd zhub |
| 10 | +python3 -m venv .venv && source .venv/bin/activate |
| 11 | +pip install -e '.[server,dev,brains]' |
| 12 | +python -m zhub doctor # verify install |
| 13 | +pytest # 164 tests, ~80s |
| 14 | +``` |
| 15 | + |
| 16 | +For the JS client: |
| 17 | + |
| 18 | +```bash |
| 19 | +cd js |
| 20 | +npm install |
| 21 | +npm test # 13 tests |
| 22 | +``` |
| 23 | + |
| 24 | +## How to propose a change |
| 25 | + |
| 26 | +| Change type | Path | |
| 27 | +|---|---| |
| 28 | +| Bugfix or small refactor | open a PR with the diff + a regression test | |
| 29 | +| New feature, brain adapter, primitive | open an issue first (or a `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` PR) so the design is reviewable before implementation | |
| 30 | +| Documentation | direct PR is fine | |
| 31 | + |
| 32 | +## Code rules |
| 33 | + |
| 34 | +- **Test-driven.** Every behavior change ships with a test. If you add a new file under `zhub/`, there's a matching `tests/test_<name>.py`. |
| 35 | +- **Substrate, not opinion.** zhub knows nothing about your specific AI, your devices, or your business logic. Don't add product-specific bridges — those go in their own repos and consume zhub via `publish()` / `connect()` / `expose()`. |
| 36 | +- **No new top-level deps without justification.** The optional-extras pattern (`[server]`, `[crypto]`, `[brains]`) handles most cases. Hot path stays import-light. |
| 37 | +- **Async-first.** Hub-side code is asyncio. Sync work belongs in `to_thread` or its own subprocess. |
| 38 | +- **One-line comments only when the *why* is non-obvious.** Self-documenting names beat narration. |
| 39 | + |
| 40 | +## Adding a brain adapter |
| 41 | + |
| 42 | +Most hosted LLM providers speak OpenAI-compat. Use the shared helper: |
| 43 | + |
| 44 | +```python |
| 45 | +# zhub/brains/<provider>.py |
| 46 | +from ._openai_compat import probe_openai_compat, stream_openai_compat |
| 47 | +from .base import BrainAdapter, ChatChunk |
| 48 | +import httpx, os |
| 49 | + |
| 50 | +_BASE_URL = "https://api.<provider>.com/v1" |
| 51 | +_DEFAULT_MODEL = "..." |
| 52 | + |
| 53 | +class <Provider>Adapter(BrainAdapter): |
| 54 | + name = "<provider>" |
| 55 | + label = "<Display Name>" |
| 56 | + # ... __init__, try_init using probe_openai_compat, stream delegating to stream_openai_compat |
| 57 | +``` |
| 58 | + |
| 59 | +Then register in `zhub/brains/__init__.py` REGISTRY (priority order matters for `detect()`) and add `tests/test_brains_<provider>.py` with the same monkeypatch + fake-stream pattern as the existing adapter tests. |
| 60 | + |
| 61 | +For non-OpenAI shapes (e.g. Cohere), copy `zhub/brains/cohere.py` as a template. |
| 62 | + |
| 63 | +## Running the live demo against your branch |
| 64 | + |
| 65 | +```bash |
| 66 | +GROQ_API_KEY=gsk_... python -m zhub up |
| 67 | +# → URL + KEY |
| 68 | +``` |
| 69 | + |
| 70 | +Open `http://localhost:8080/` in a browser to see the dashboard. Generate traffic with: |
| 71 | + |
| 72 | +```bash |
| 73 | +curl -s http://localhost:8080/healthz |
| 74 | +curl -s -X POST http://localhost:8080/me/v1/chat/completions \ |
| 75 | + -H "Authorization: Bearer zk_..." \ |
| 76 | + -d '{"messages":[{"role":"user","content":"hi"}]}' |
| 77 | +``` |
| 78 | + |
| 79 | +Particles fly through the live SVG flow on the dashboard for each request. |
| 80 | + |
| 81 | +## Where the design conversations live |
| 82 | + |
| 83 | +`docs/superpowers/specs/` has the design doc for every shipped phase. `docs/superpowers/plans/` has the TDD implementation plans. Walking through a few specs is the fastest way to understand how decisions were made. |
| 84 | + |
| 85 | +## License |
| 86 | + |
| 87 | +By contributing, you agree your contributions will be licensed under the MIT License. |
0 commit comments