gremlinlabs-connector 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gremlinlabs_connector-0.3.0/.gitignore +16 -0
- gremlinlabs_connector-0.3.0/PKG-INFO +208 -0
- gremlinlabs_connector-0.3.0/README.md +181 -0
- gremlinlabs_connector-0.3.0/pyproject.toml +59 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/__init__.py +3 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/__main__.py +3 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/client.py +307 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/config.py +281 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/detect.py +62 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/main.py +174 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/messages.py +104 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/products.py +64 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/protocol.py +63 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/setup.py +399 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/startup.py +158 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/targets.py +360 -0
- gremlinlabs_connector-0.3.0/src/gremlinlabs_connector/token_store.py +98 -0
- gremlinlabs_connector-0.3.0/tests/test_connector.py +613 -0
- gremlinlabs_connector-0.3.0/tests/test_setup.py +286 -0
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gremlinlabs-connector
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Connect Gremlin Labs products (Gavel) to models and chatbots on your own computer or network: one outbound WebSocket, an allow-list of targets
|
|
5
|
+
Project-URL: Homepage, https://34-233-150-41.sslip.io
|
|
6
|
+
Project-URL: Documentation, https://34-233-150-41.sslip.io/connect-local-model
|
|
7
|
+
Author: GremlinLabs
|
|
8
|
+
License-Expression: LicenseRef-Proprietary
|
|
9
|
+
Keywords: chatbot,connector,evaluation,gavel,gremlinlabs,llm,ollama
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Testing
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27
|
|
23
|
+
Requires-Dist: keyring>=24
|
|
24
|
+
Requires-Dist: pyyaml>=6
|
|
25
|
+
Requires-Dist: websockets>=15
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# gremlinlabs-connector
|
|
29
|
+
|
|
30
|
+
One connector for every Gremlin Labs product. Today it lets Gavel use a model or a chatbot that lives on your own
|
|
31
|
+
network (a local Ollama, an internal support bot) without a tunnel and without opening an inbound port. The connector
|
|
32
|
+
runs next to them and makes **one outbound WebSocket connection** to the product; the product sends requests down that
|
|
33
|
+
connection, and the connector calls only the targets listed in its config file.
|
|
34
|
+
|
|
35
|
+
**Coming from `gavel-connector`?** It was renamed: versions 0.1.0-0.2.3 were published as `gavel-connector`, which is
|
|
36
|
+
retired. Replace it with `pipx uninstall gavel-connector && pipx install gremlinlabs-connector`, then run the setup
|
|
37
|
+
line from Gavel again (setup now keeps its files in `~/.config/gremlinlabs-connector`). A hand-written YAML config and
|
|
38
|
+
its token keep working: `gremlinlabs-connector run --config <your file>`.
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
Needs Python 3.10 or newer. Install with [pipx](https://pipx.pypa.io) (or uv); no Gavel checkout needed:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pipx install gremlinlabs-connector # or: uv tool install gremlinlabs-connector
|
|
46
|
+
gremlinlabs-connector --version
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or install the exact version your Gavel serves, from the site itself (the URL must end in the full wheel name):
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
pipx install https://<your-gavel>/downloads/gremlinlabs_connector-<version>-py3-none-any.whl
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
No pipx yet? Mac: `brew install pipx && pipx ensurepath`; Windows: `py -m pip install --user pipx` then
|
|
56
|
+
`py -m pipx ensurepath`; Debian/Ubuntu: `sudo apt install pipx && pipx ensurepath`. Then open a new terminal.
|
|
57
|
+
Step-by-step per system, starting at login, and troubleshooting: Gavel's **Connect A Local Model** guide
|
|
58
|
+
(`/connect-local-model` on your Gavel) or docs/CONNECTOR.md in the Gavel repository.
|
|
59
|
+
|
|
60
|
+
From a Gavel checkout (development): `pipx install ./connector`.
|
|
61
|
+
|
|
62
|
+
## Quick setup: one line, no files (gremlinlabs-connector 0.3.0+)
|
|
63
|
+
|
|
64
|
+
In Gavel: **Models → Add A Model → On My Computer Or Office Network** (or **Models → Connectors → Add A
|
|
65
|
+
Connector**). Owners and admins get one line with a one-time pairing code (10 minutes, single use):
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
pipx install gremlinlabs-connector && gremlinlabs-connector setup K7QF-29XM
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Run it on the computer next to your model. `setup` finds Ollama (11434), LM Studio (1234) and vLLM (8000), lists their
|
|
72
|
+
models and asks "Share these? [Y/n]" (`--yes` for scripts), pairs with Gavel, keeps the token in the system credential
|
|
73
|
+
store (Keychain, Credential Manager, Secret Service; a file only you can read when there is none, and it says so),
|
|
74
|
+
writes its own config (`~/.config/gremlinlabs-connector/config.yaml`, `%APPDATA%\gremlinlabs-connector` on Windows), starts at
|
|
75
|
+
login (launchd agent, systemd user unit, or a Task Scheduler task running the connector's own `python.exe -m
|
|
76
|
+
gremlinlabs_connector`) and starts. The page follows along: Waiting For The Computer → Paired → Found N Models → pick one.
|
|
77
|
+
|
|
78
|
+
- More later, only from that computer: `gremlinlabs-connector add-model http://localhost:1234`,
|
|
79
|
+
`gremlinlabs-connector add-chatbot http://localhost:8080/api/chat` (it sends one test message to find where the answer
|
|
80
|
+
is; `--response-path data.answer` to say it). Gavel can't add what a connector reaches.
|
|
81
|
+
- Running `setup` again on the same computer replaces its pairing (no second connector). **Reconnect** on the
|
|
82
|
+
Connectors tab gives a code for the same connector (models and chatbots using it keep working); **Revoke** cuts it
|
|
83
|
+
off at once.
|
|
84
|
+
- A run whose connector goes offline waits (up to 30 minutes) and continues by itself when it's back.
|
|
85
|
+
- Another Gavel than the hosted one: `--server https://your-gavel` (the page adds it to the line).
|
|
86
|
+
|
|
87
|
+
The rest of this page is the advanced path for IT: a YAML file and `gremlinlabs-connector run --config`.
|
|
88
|
+
|
|
89
|
+
## Set up
|
|
90
|
+
|
|
91
|
+
1. In Gavel, open **Models → Connectors**, create a connector and copy its token (`gvc_…`). It is shown once.
|
|
92
|
+
2. Put the token in an environment variable (recommended) and write `gremlinlabs-connector.yaml`. `token_env` is the
|
|
93
|
+
variable's **name**, never the token itself:
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
server: https://gavel.example.com # Gavel's address (https; http only for localhost)
|
|
97
|
+
token_env: GREMLINLABS_CONNECTOR_TOKEN # or: token: gvc_... (then keep this file private)
|
|
98
|
+
# product: gavel # the Gremlin Labs product (default gavel)
|
|
99
|
+
concurrency: 4 # requests handled at once (1-32)
|
|
100
|
+
proxy: system # how to reach Gavel: system (HTTPS_PROXY), none, or a proxy URL
|
|
101
|
+
|
|
102
|
+
targets:
|
|
103
|
+
# A model: any OpenAI-compatible server (Ollama, LM Studio, vLLM, llama.cpp ...)
|
|
104
|
+
- name: ollama
|
|
105
|
+
kind: model
|
|
106
|
+
base_url: http://localhost:11434/v1
|
|
107
|
+
# api_key_env: OLLAMA_KEY # if the server wants a key (read from this environment variable)
|
|
108
|
+
# models: [qwen2.5:7b] # optional allow-list: only these models may be called
|
|
109
|
+
|
|
110
|
+
# A chatbot behind its own HTTP API
|
|
111
|
+
- name: support-bot
|
|
112
|
+
kind: chatbot
|
|
113
|
+
url: http://support.internal:8080/api/chat
|
|
114
|
+
method: POST # POST (default), PUT, PATCH or GET
|
|
115
|
+
headers:
|
|
116
|
+
X-Api-Key: "${SUPPORT_BOT_KEY}" # ${VAR} is read from the environment when calling
|
|
117
|
+
body_template: '{"message": {{message}}, "history": {{history_json}}, "session": {{session_id}}}'
|
|
118
|
+
response_path: data.answer # where the reply is in the JSON response
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Placeholders in `body_template` are replaced with JSON values, so don't put quotes around them:
|
|
122
|
+
`{{message}}` (the new user message), `{{history_json}}` (earlier messages as `[{role, content}]`),
|
|
123
|
+
`{{messages}}` (all messages including the new one) and `{{session_id}}` (the same through one conversation).
|
|
124
|
+
|
|
125
|
+
3. Check it, then run it:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
export GREMLINLABS_CONNECTOR_TOKEN=gvc_...
|
|
129
|
+
gremlinlabs-connector check --config gremlinlabs-connector.yaml # validates the file, reaches Gavel and every target
|
|
130
|
+
gremlinlabs-connector run --config gremlinlabs-connector.yaml
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`check` prints a table (target, kind, address, ok/FAIL, detail). It lists the models of model targets and sends a
|
|
134
|
+
`HEAD` request to chatbot targets: no message is sent to your chatbot.
|
|
135
|
+
|
|
136
|
+
4. In Gavel the connector shows as **online** with its targets. Add a model under **On Your Computer Or Office
|
|
137
|
+
Network** (connector + target + model; model IDs are case-sensitive, like `qwen2.5:7b`), or a chatbot of kind
|
|
138
|
+
"connector" (connector + target).
|
|
139
|
+
|
|
140
|
+
From version 0.2.0 a model target also serves embeddings (its `/v1/embeddings`, e.g. an Ollama embedding model
|
|
141
|
+
such as `nomic-embed-text`), so a judge profile can use it as its embedding model. An older connector gets a
|
|
142
|
+
clear "install gremlinlabs-connector 0.3.0 or later" message instead; everything else keeps working with it.
|
|
143
|
+
|
|
144
|
+
Run it as a service (systemd, launchd, a container) so it restarts with the machine. It handles `SIGTERM` and
|
|
145
|
+
`Ctrl-C` cleanly.
|
|
146
|
+
|
|
147
|
+
### Running against a local Gavel (development)
|
|
148
|
+
|
|
149
|
+
```yaml
|
|
150
|
+
server: http://localhost:8000 # gavel-web; http is allowed for localhost
|
|
151
|
+
token: gvc_...
|
|
152
|
+
targets:
|
|
153
|
+
- {name: ollama, kind: model, base_url: "http://localhost:11434/v1"}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
To reach a Gavel on another machine over plain http (a LAN test), add `allow_insecure_http: true`.
|
|
157
|
+
|
|
158
|
+
## Products and extending
|
|
159
|
+
|
|
160
|
+
The connector's core is the same for every Gremlin Labs product: pairing (`setup`), the token store, model detection,
|
|
161
|
+
start-at-login, reconnect and revoke, and the WebSocket. What differs per product lives in
|
|
162
|
+
`gremlinlabs_connector/products.py`: a `Product` with its `name` (sent as `product` in the hello and the pairing
|
|
163
|
+
exchange), its default server (and the environment variable that overrides it), and its request kinds, each mapped to
|
|
164
|
+
a handler `async (http, config, payload, timeout) -> dict`.
|
|
165
|
+
|
|
166
|
+
| Product | `product` | Request kinds |
|
|
167
|
+
| --- | --- | --- |
|
|
168
|
+
| Gavel | `gavel` (the default) | `model.chat`, `chatbot.turn`, `discover`, `embed` |
|
|
169
|
+
|
|
170
|
+
To add a product, register a `Product` with its own kinds (`products.register(...)`); the hello then announces only
|
|
171
|
+
those kinds, and a request of any other kind is answered `bad_request`. Pair with it with `setup CODE --product
|
|
172
|
+
<name>`; its config says `product: <name>`. A server treats a hello or pairing without `product` as `gavel`, and Gavel
|
|
173
|
+
refuses a connector set up for another product (Gavel RULES.md RB-CONN-07). Today one install serves one product per
|
|
174
|
+
config file.
|
|
175
|
+
|
|
176
|
+
## How it stays safe
|
|
177
|
+
|
|
178
|
+
- **Outbound only.** The connector dials out to Gavel over `wss://`; nothing listens on your side, and no firewall
|
|
179
|
+
rule or tunnel is needed.
|
|
180
|
+
- **Allow-list.** It only calls the targets in its config file, at the addresses in that file. Gavel names a target;
|
|
181
|
+
it never supplies a URL. A request for anything else is refused (`unknown_target`). A model target with `models:`
|
|
182
|
+
refuses other model ids.
|
|
183
|
+
- **Your secrets stay with you.** Target API keys and header values come from your environment and are never sent to
|
|
184
|
+
Gavel.
|
|
185
|
+
- **No payload logging.** Logs carry request ids, kinds, target names, durations and status codes only; never
|
|
186
|
+
messages, replies, headers or the token.
|
|
187
|
+
- **One token, one connector.** Tokens are stored hashed in Gavel. Revoking the connector in Gavel closes its
|
|
188
|
+
connection at once and the token stops working. If a second connector starts with the same token, the newest
|
|
189
|
+
connection wins and the older one stops.
|
|
190
|
+
- Answers are kept in memory for up to 10 minutes so a request re-sent after a reconnect isn't run twice.
|
|
191
|
+
|
|
192
|
+
## Troubleshooting
|
|
193
|
+
|
|
194
|
+
| Symptom | What to do |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `config error: ...` (exit 2) | The message names the setting. Run `gremlinlabs-connector check`. |
|
|
197
|
+
| `Gavel rejected the connector token (HTTP 401)` (exit 3) | The token is mistyped or the connector was revoked. Create a new connector in Gavel. |
|
|
198
|
+
| `this connector was revoked in Gavel` (exit 3) | Someone revoked it. Create a new one and update the token. |
|
|
199
|
+
| `another gremlinlabs-connector connected with the same token` (exit 4) | Only one connector may run per token. Stop the other one, or create a second connector. |
|
|
200
|
+
| `connection to Gavel failed or dropped`, `reconnecting in N s` | Network or Gavel restart. It retries with backoff (1 s up to 60 s). Check `server:` and any proxy (`proxy: system` uses `HTTPS_PROXY`). |
|
|
201
|
+
| Gavel says `connector_offline` | The connector isn't running or can't reach Gavel; Gavel counts it offline after 60 s of silence. |
|
|
202
|
+
| Gavel says `unknown_target` | The target name isn't in this connector's config (or has a different kind). Fix the YAML and restart the connector. |
|
|
203
|
+
| `unreachable` / `timeout` from a target | The connector can't reach that URL or it's slow. `gremlinlabs-connector check` shows which. |
|
|
204
|
+
| `model_not_found` | The model id isn't served by the target (or not in its `models:` list). |
|
|
205
|
+
| `target_http_error` / `bad_response` | The chatbot answered with an HTTP error, or the reply isn't at `response_path`. |
|
|
206
|
+
|
|
207
|
+
Exit codes: 0 stopped normally, 1 a check failed, 2 config error, 3 token rejected or revoked, 4 replaced by a newer
|
|
208
|
+
connector with the same token.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# gremlinlabs-connector
|
|
2
|
+
|
|
3
|
+
One connector for every Gremlin Labs product. Today it lets Gavel use a model or a chatbot that lives on your own
|
|
4
|
+
network (a local Ollama, an internal support bot) without a tunnel and without opening an inbound port. The connector
|
|
5
|
+
runs next to them and makes **one outbound WebSocket connection** to the product; the product sends requests down that
|
|
6
|
+
connection, and the connector calls only the targets listed in its config file.
|
|
7
|
+
|
|
8
|
+
**Coming from `gavel-connector`?** It was renamed: versions 0.1.0-0.2.3 were published as `gavel-connector`, which is
|
|
9
|
+
retired. Replace it with `pipx uninstall gavel-connector && pipx install gremlinlabs-connector`, then run the setup
|
|
10
|
+
line from Gavel again (setup now keeps its files in `~/.config/gremlinlabs-connector`). A hand-written YAML config and
|
|
11
|
+
its token keep working: `gremlinlabs-connector run --config <your file>`.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
Needs Python 3.10 or newer. Install with [pipx](https://pipx.pypa.io) (or uv); no Gavel checkout needed:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
pipx install gremlinlabs-connector # or: uv tool install gremlinlabs-connector
|
|
19
|
+
gremlinlabs-connector --version
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Or install the exact version your Gavel serves, from the site itself (the URL must end in the full wheel name):
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
pipx install https://<your-gavel>/downloads/gremlinlabs_connector-<version>-py3-none-any.whl
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
No pipx yet? Mac: `brew install pipx && pipx ensurepath`; Windows: `py -m pip install --user pipx` then
|
|
29
|
+
`py -m pipx ensurepath`; Debian/Ubuntu: `sudo apt install pipx && pipx ensurepath`. Then open a new terminal.
|
|
30
|
+
Step-by-step per system, starting at login, and troubleshooting: Gavel's **Connect A Local Model** guide
|
|
31
|
+
(`/connect-local-model` on your Gavel) or docs/CONNECTOR.md in the Gavel repository.
|
|
32
|
+
|
|
33
|
+
From a Gavel checkout (development): `pipx install ./connector`.
|
|
34
|
+
|
|
35
|
+
## Quick setup: one line, no files (gremlinlabs-connector 0.3.0+)
|
|
36
|
+
|
|
37
|
+
In Gavel: **Models → Add A Model → On My Computer Or Office Network** (or **Models → Connectors → Add A
|
|
38
|
+
Connector**). Owners and admins get one line with a one-time pairing code (10 minutes, single use):
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
pipx install gremlinlabs-connector && gremlinlabs-connector setup K7QF-29XM
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Run it on the computer next to your model. `setup` finds Ollama (11434), LM Studio (1234) and vLLM (8000), lists their
|
|
45
|
+
models and asks "Share these? [Y/n]" (`--yes` for scripts), pairs with Gavel, keeps the token in the system credential
|
|
46
|
+
store (Keychain, Credential Manager, Secret Service; a file only you can read when there is none, and it says so),
|
|
47
|
+
writes its own config (`~/.config/gremlinlabs-connector/config.yaml`, `%APPDATA%\gremlinlabs-connector` on Windows), starts at
|
|
48
|
+
login (launchd agent, systemd user unit, or a Task Scheduler task running the connector's own `python.exe -m
|
|
49
|
+
gremlinlabs_connector`) and starts. The page follows along: Waiting For The Computer → Paired → Found N Models → pick one.
|
|
50
|
+
|
|
51
|
+
- More later, only from that computer: `gremlinlabs-connector add-model http://localhost:1234`,
|
|
52
|
+
`gremlinlabs-connector add-chatbot http://localhost:8080/api/chat` (it sends one test message to find where the answer
|
|
53
|
+
is; `--response-path data.answer` to say it). Gavel can't add what a connector reaches.
|
|
54
|
+
- Running `setup` again on the same computer replaces its pairing (no second connector). **Reconnect** on the
|
|
55
|
+
Connectors tab gives a code for the same connector (models and chatbots using it keep working); **Revoke** cuts it
|
|
56
|
+
off at once.
|
|
57
|
+
- A run whose connector goes offline waits (up to 30 minutes) and continues by itself when it's back.
|
|
58
|
+
- Another Gavel than the hosted one: `--server https://your-gavel` (the page adds it to the line).
|
|
59
|
+
|
|
60
|
+
The rest of this page is the advanced path for IT: a YAML file and `gremlinlabs-connector run --config`.
|
|
61
|
+
|
|
62
|
+
## Set up
|
|
63
|
+
|
|
64
|
+
1. In Gavel, open **Models → Connectors**, create a connector and copy its token (`gvc_…`). It is shown once.
|
|
65
|
+
2. Put the token in an environment variable (recommended) and write `gremlinlabs-connector.yaml`. `token_env` is the
|
|
66
|
+
variable's **name**, never the token itself:
|
|
67
|
+
|
|
68
|
+
```yaml
|
|
69
|
+
server: https://gavel.example.com # Gavel's address (https; http only for localhost)
|
|
70
|
+
token_env: GREMLINLABS_CONNECTOR_TOKEN # or: token: gvc_... (then keep this file private)
|
|
71
|
+
# product: gavel # the Gremlin Labs product (default gavel)
|
|
72
|
+
concurrency: 4 # requests handled at once (1-32)
|
|
73
|
+
proxy: system # how to reach Gavel: system (HTTPS_PROXY), none, or a proxy URL
|
|
74
|
+
|
|
75
|
+
targets:
|
|
76
|
+
# A model: any OpenAI-compatible server (Ollama, LM Studio, vLLM, llama.cpp ...)
|
|
77
|
+
- name: ollama
|
|
78
|
+
kind: model
|
|
79
|
+
base_url: http://localhost:11434/v1
|
|
80
|
+
# api_key_env: OLLAMA_KEY # if the server wants a key (read from this environment variable)
|
|
81
|
+
# models: [qwen2.5:7b] # optional allow-list: only these models may be called
|
|
82
|
+
|
|
83
|
+
# A chatbot behind its own HTTP API
|
|
84
|
+
- name: support-bot
|
|
85
|
+
kind: chatbot
|
|
86
|
+
url: http://support.internal:8080/api/chat
|
|
87
|
+
method: POST # POST (default), PUT, PATCH or GET
|
|
88
|
+
headers:
|
|
89
|
+
X-Api-Key: "${SUPPORT_BOT_KEY}" # ${VAR} is read from the environment when calling
|
|
90
|
+
body_template: '{"message": {{message}}, "history": {{history_json}}, "session": {{session_id}}}'
|
|
91
|
+
response_path: data.answer # where the reply is in the JSON response
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Placeholders in `body_template` are replaced with JSON values, so don't put quotes around them:
|
|
95
|
+
`{{message}}` (the new user message), `{{history_json}}` (earlier messages as `[{role, content}]`),
|
|
96
|
+
`{{messages}}` (all messages including the new one) and `{{session_id}}` (the same through one conversation).
|
|
97
|
+
|
|
98
|
+
3. Check it, then run it:
|
|
99
|
+
|
|
100
|
+
```sh
|
|
101
|
+
export GREMLINLABS_CONNECTOR_TOKEN=gvc_...
|
|
102
|
+
gremlinlabs-connector check --config gremlinlabs-connector.yaml # validates the file, reaches Gavel and every target
|
|
103
|
+
gremlinlabs-connector run --config gremlinlabs-connector.yaml
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`check` prints a table (target, kind, address, ok/FAIL, detail). It lists the models of model targets and sends a
|
|
107
|
+
`HEAD` request to chatbot targets: no message is sent to your chatbot.
|
|
108
|
+
|
|
109
|
+
4. In Gavel the connector shows as **online** with its targets. Add a model under **On Your Computer Or Office
|
|
110
|
+
Network** (connector + target + model; model IDs are case-sensitive, like `qwen2.5:7b`), or a chatbot of kind
|
|
111
|
+
"connector" (connector + target).
|
|
112
|
+
|
|
113
|
+
From version 0.2.0 a model target also serves embeddings (its `/v1/embeddings`, e.g. an Ollama embedding model
|
|
114
|
+
such as `nomic-embed-text`), so a judge profile can use it as its embedding model. An older connector gets a
|
|
115
|
+
clear "install gremlinlabs-connector 0.3.0 or later" message instead; everything else keeps working with it.
|
|
116
|
+
|
|
117
|
+
Run it as a service (systemd, launchd, a container) so it restarts with the machine. It handles `SIGTERM` and
|
|
118
|
+
`Ctrl-C` cleanly.
|
|
119
|
+
|
|
120
|
+
### Running against a local Gavel (development)
|
|
121
|
+
|
|
122
|
+
```yaml
|
|
123
|
+
server: http://localhost:8000 # gavel-web; http is allowed for localhost
|
|
124
|
+
token: gvc_...
|
|
125
|
+
targets:
|
|
126
|
+
- {name: ollama, kind: model, base_url: "http://localhost:11434/v1"}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
To reach a Gavel on another machine over plain http (a LAN test), add `allow_insecure_http: true`.
|
|
130
|
+
|
|
131
|
+
## Products and extending
|
|
132
|
+
|
|
133
|
+
The connector's core is the same for every Gremlin Labs product: pairing (`setup`), the token store, model detection,
|
|
134
|
+
start-at-login, reconnect and revoke, and the WebSocket. What differs per product lives in
|
|
135
|
+
`gremlinlabs_connector/products.py`: a `Product` with its `name` (sent as `product` in the hello and the pairing
|
|
136
|
+
exchange), its default server (and the environment variable that overrides it), and its request kinds, each mapped to
|
|
137
|
+
a handler `async (http, config, payload, timeout) -> dict`.
|
|
138
|
+
|
|
139
|
+
| Product | `product` | Request kinds |
|
|
140
|
+
| --- | --- | --- |
|
|
141
|
+
| Gavel | `gavel` (the default) | `model.chat`, `chatbot.turn`, `discover`, `embed` |
|
|
142
|
+
|
|
143
|
+
To add a product, register a `Product` with its own kinds (`products.register(...)`); the hello then announces only
|
|
144
|
+
those kinds, and a request of any other kind is answered `bad_request`. Pair with it with `setup CODE --product
|
|
145
|
+
<name>`; its config says `product: <name>`. A server treats a hello or pairing without `product` as `gavel`, and Gavel
|
|
146
|
+
refuses a connector set up for another product (Gavel RULES.md RB-CONN-07). Today one install serves one product per
|
|
147
|
+
config file.
|
|
148
|
+
|
|
149
|
+
## How it stays safe
|
|
150
|
+
|
|
151
|
+
- **Outbound only.** The connector dials out to Gavel over `wss://`; nothing listens on your side, and no firewall
|
|
152
|
+
rule or tunnel is needed.
|
|
153
|
+
- **Allow-list.** It only calls the targets in its config file, at the addresses in that file. Gavel names a target;
|
|
154
|
+
it never supplies a URL. A request for anything else is refused (`unknown_target`). A model target with `models:`
|
|
155
|
+
refuses other model ids.
|
|
156
|
+
- **Your secrets stay with you.** Target API keys and header values come from your environment and are never sent to
|
|
157
|
+
Gavel.
|
|
158
|
+
- **No payload logging.** Logs carry request ids, kinds, target names, durations and status codes only; never
|
|
159
|
+
messages, replies, headers or the token.
|
|
160
|
+
- **One token, one connector.** Tokens are stored hashed in Gavel. Revoking the connector in Gavel closes its
|
|
161
|
+
connection at once and the token stops working. If a second connector starts with the same token, the newest
|
|
162
|
+
connection wins and the older one stops.
|
|
163
|
+
- Answers are kept in memory for up to 10 minutes so a request re-sent after a reconnect isn't run twice.
|
|
164
|
+
|
|
165
|
+
## Troubleshooting
|
|
166
|
+
|
|
167
|
+
| Symptom | What to do |
|
|
168
|
+
| --- | --- |
|
|
169
|
+
| `config error: ...` (exit 2) | The message names the setting. Run `gremlinlabs-connector check`. |
|
|
170
|
+
| `Gavel rejected the connector token (HTTP 401)` (exit 3) | The token is mistyped or the connector was revoked. Create a new connector in Gavel. |
|
|
171
|
+
| `this connector was revoked in Gavel` (exit 3) | Someone revoked it. Create a new one and update the token. |
|
|
172
|
+
| `another gremlinlabs-connector connected with the same token` (exit 4) | Only one connector may run per token. Stop the other one, or create a second connector. |
|
|
173
|
+
| `connection to Gavel failed or dropped`, `reconnecting in N s` | Network or Gavel restart. It retries with backoff (1 s up to 60 s). Check `server:` and any proxy (`proxy: system` uses `HTTPS_PROXY`). |
|
|
174
|
+
| Gavel says `connector_offline` | The connector isn't running or can't reach Gavel; Gavel counts it offline after 60 s of silence. |
|
|
175
|
+
| Gavel says `unknown_target` | The target name isn't in this connector's config (or has a different kind). Fix the YAML and restart the connector. |
|
|
176
|
+
| `unreachable` / `timeout` from a target | The connector can't reach that URL or it's slow. `gremlinlabs-connector check` shows which. |
|
|
177
|
+
| `model_not_found` | The model id isn't served by the target (or not in its `models:` list). |
|
|
178
|
+
| `target_http_error` / `bad_response` | The chatbot answered with an HTTP error, or the reply isn't at `response_path`. |
|
|
179
|
+
|
|
180
|
+
Exit codes: 0 stopped normally, 1 a check failed, 2 config error, 3 token rejected or revoked, 4 replaced by a newer
|
|
181
|
+
connector with the same token.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "gremlinlabs-connector"
|
|
3
|
+
dynamic = ["version"]
|
|
4
|
+
description = "Connect Gremlin Labs products (Gavel) to models and chatbots on your own computer or network: one outbound WebSocket, an allow-list of targets"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = "LicenseRef-Proprietary"
|
|
8
|
+
authors = [{ name = "GremlinLabs" }]
|
|
9
|
+
keywords = ["gremlinlabs", "gavel", "llm", "ollama", "chatbot", "evaluation", "connector"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 4 - Beta",
|
|
12
|
+
"Environment :: Console",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Topic :: Software Development :: Testing",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"websockets>=15",
|
|
25
|
+
"httpx>=0.27",
|
|
26
|
+
"pyyaml>=6",
|
|
27
|
+
"keyring>=24",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://34-233-150-41.sslip.io"
|
|
32
|
+
Documentation = "https://34-233-150-41.sslip.io/connect-local-model"
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
gremlinlabs-connector = "gremlinlabs_connector.main:main"
|
|
36
|
+
|
|
37
|
+
[dependency-groups]
|
|
38
|
+
dev = ["pytest>=8"]
|
|
39
|
+
|
|
40
|
+
[build-system]
|
|
41
|
+
requires = ["hatchling>=1.27"]
|
|
42
|
+
build-backend = "hatchling.build"
|
|
43
|
+
|
|
44
|
+
# One version: gremlinlabs_connector.__version__ (also what `gremlinlabs-connector --version` and Gavel's Connectors list show).
|
|
45
|
+
[tool.hatch.version]
|
|
46
|
+
path = "src/gremlinlabs_connector/__init__.py"
|
|
47
|
+
|
|
48
|
+
# Metadata 2.4 (PEP 639 licence expression): what PyPI and twine accept today.
|
|
49
|
+
[tool.hatch.build.targets.wheel]
|
|
50
|
+
packages = ["src/gremlinlabs_connector"]
|
|
51
|
+
core-metadata-version = "2.4"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.sdist]
|
|
54
|
+
core-metadata-version = "2.4"
|
|
55
|
+
include = ["src/gremlinlabs_connector", "tests/*.py", "README.md", "pyproject.toml"]
|
|
56
|
+
|
|
57
|
+
[tool.pytest.ini_options]
|
|
58
|
+
testpaths = ["tests"]
|
|
59
|
+
pythonpath = ["src"]
|