@tagma/completion-llm-judge 0.1.4 → 0.2.0
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.
- package/LICENSE +21 -21
- package/README.md +99 -99
- package/package.json +2 -2
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Tagma
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tagma
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,99 +1,99 @@
|
|
|
1
|
-
# @tagma/completion-llm-judge
|
|
2
|
-
|
|
3
|
-
LLM-as-judge completion plugin for [@tagma/sdk](https://www.npmjs.com/package/@tagma/sdk).
|
|
4
|
-
|
|
5
|
-
Uses an OpenAI-compatible chat completions endpoint to verify whether a task's output satisfies a rubric. Complements the deterministic built-in completions (`exit_code`, `file_exists`, `output_check`) when task success is defined semantically rather than by a grep-able pattern.
|
|
6
|
-
|
|
7
|
-
**Default backend**: local [Ollama](https://ollama.com/) with `qwen3:4b` — a small reasoning model that runs on CPU with no API key. Swap `endpoint` + `model` to point at any OpenAI-compatible server (OpenAI, vLLM, llama.cpp, LM Studio, Groq, Together, OpenRouter, ...).
|
|
8
|
-
|
|
9
|
-
## Install
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
bun add @tagma/completion-llm-judge
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Then make sure Ollama is running with the default model pulled:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
ollama pull qwen3:4b
|
|
19
|
-
ollama serve # usually auto-started
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
## Usage
|
|
23
|
-
|
|
24
|
-
```yaml
|
|
25
|
-
pipeline:
|
|
26
|
-
name: qa-loop
|
|
27
|
-
plugins:
|
|
28
|
-
- '@tagma/completion-llm-judge'
|
|
29
|
-
tracks:
|
|
30
|
-
- id: qa
|
|
31
|
-
name: QA
|
|
32
|
-
driver: claude-code
|
|
33
|
-
tasks:
|
|
34
|
-
- id: find-bugs
|
|
35
|
-
name: Find failing tests
|
|
36
|
-
prompt: 'List all failing tests in the current workspace with their file paths.'
|
|
37
|
-
completion:
|
|
38
|
-
type: llm_judge
|
|
39
|
-
rubric: |
|
|
40
|
-
The output must list at least 3 failing tests. Each entry must
|
|
41
|
-
include the test name, the file path, and the assertion that
|
|
42
|
-
failed. The output must not be an empty placeholder.
|
|
43
|
-
# endpoint / model / api_key_env all default to local Ollama + qwen3:4b
|
|
44
|
-
timeout: 120s
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Swap to a hosted backend:
|
|
48
|
-
|
|
49
|
-
```yaml
|
|
50
|
-
completion:
|
|
51
|
-
type: llm_judge
|
|
52
|
-
rubric: '...'
|
|
53
|
-
endpoint: https://api.openai.com/v1/chat/completions
|
|
54
|
-
model: gpt-4o-mini
|
|
55
|
-
api_key_env: OPENAI_API_KEY
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Or load it programmatically:
|
|
59
|
-
|
|
60
|
-
```ts
|
|
61
|
-
import { bootstrapBuiltins, loadPlugins } from '@tagma/sdk';
|
|
62
|
-
|
|
63
|
-
bootstrapBuiltins();
|
|
64
|
-
await loadPlugins(['@tagma/completion-llm-judge']);
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
## Config
|
|
68
|
-
|
|
69
|
-
| Field | Type | Default | Notes |
|
|
70
|
-
| ------------------ | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
71
|
-
| `rubric` | string | _(required)_ | Plain-language success criteria the judge should verify |
|
|
72
|
-
| `model` | string | `qwen3:4b` | Judge model name. Swap for `qwen3:8b`, `deepseek-r1:7b`, `gpt-4o-mini`, etc. |
|
|
73
|
-
| `endpoint` | string | `http://localhost:11434/v1/chat/completions` | OpenAI-compatible chat completions URL. Default points at local Ollama |
|
|
74
|
-
| `api_key_env` | string | _(none)_ | Env var holding the bearer token. Leave unset for local Ollama; set for hosted backends |
|
|
75
|
-
| `timeout` | duration | `120s` | Max time to wait for the judge response (reasoning models need more time than chat models) |
|
|
76
|
-
| `max_output_chars` | number | `8000` | Truncate task stdout before judging (head+tail preserved) |
|
|
77
|
-
|
|
78
|
-
## Behavior
|
|
79
|
-
|
|
80
|
-
- **Verdict format**: the judge is instructed to answer `PASS` or `FAIL` on the first line. Missing or ambiguous answers are treated as FAIL — a judge that errs open defeats the purpose of the gate.
|
|
81
|
-
- **Reasoning-model support**: `<think>...</think>` and `<thinking>...</thinking>` blocks are stripped from the response before verdict parsing, so qwen3, DeepSeek-R1, and other thinkers work without any extra config.
|
|
82
|
-
- **Truncation**: task stdout longer than `max_output_chars` is truncated head-and-tail (70/30 split) with a marker in the middle, so the judge still sees the task's intent and its final summary.
|
|
83
|
-
- **Error handling**: network errors, auth errors, timeout, or malformed responses all mark the task as not-complete and log a warning with the judge's verbatim response (if any).
|
|
84
|
-
- **Abort propagation**: the pipeline abort signal is wired into the judge fetch call, so cancelling a pipeline also cancels any in-flight judge request.
|
|
85
|
-
- **Determinism**: the call uses `temperature: 0` to keep verdicts as stable as the model allows.
|
|
86
|
-
|
|
87
|
-
## Alternative endpoints
|
|
88
|
-
|
|
89
|
-
Any OpenAI-compatible endpoint works — just point `endpoint` and `api_key_env` at it:
|
|
90
|
-
|
|
91
|
-
- **Local Ollama** (default): `http://localhost:11434/v1/chat/completions`, no API key
|
|
92
|
-
- **OpenAI**: `https://api.openai.com/v1/chat/completions`, `api_key_env: OPENAI_API_KEY`
|
|
93
|
-
- **Local models** via LM Studio, vLLM, llama.cpp OpenAI-compatible servers
|
|
94
|
-
- **Hosted**: Groq, Together, Fireworks, OpenRouter, DeepInfra, etc.
|
|
95
|
-
- **Anthropic** via an OpenAI-compat proxy (e.g. `anthropic-openai-proxy`)
|
|
96
|
-
|
|
97
|
-
## License
|
|
98
|
-
|
|
99
|
-
MIT
|
|
1
|
+
# @tagma/completion-llm-judge
|
|
2
|
+
|
|
3
|
+
LLM-as-judge completion plugin for [@tagma/sdk](https://www.npmjs.com/package/@tagma/sdk).
|
|
4
|
+
|
|
5
|
+
Uses an OpenAI-compatible chat completions endpoint to verify whether a task's output satisfies a rubric. Complements the deterministic built-in completions (`exit_code`, `file_exists`, `output_check`) when task success is defined semantically rather than by a grep-able pattern.
|
|
6
|
+
|
|
7
|
+
**Default backend**: local [Ollama](https://ollama.com/) with `qwen3:4b` — a small reasoning model that runs on CPU with no API key. Swap `endpoint` + `model` to point at any OpenAI-compatible server (OpenAI, vLLM, llama.cpp, LM Studio, Groq, Together, OpenRouter, ...).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
bun add @tagma/completion-llm-judge
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Then make sure Ollama is running with the default model pulled:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
ollama pull qwen3:4b
|
|
19
|
+
ollama serve # usually auto-started
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
```yaml
|
|
25
|
+
pipeline:
|
|
26
|
+
name: qa-loop
|
|
27
|
+
plugins:
|
|
28
|
+
- '@tagma/completion-llm-judge'
|
|
29
|
+
tracks:
|
|
30
|
+
- id: qa
|
|
31
|
+
name: QA
|
|
32
|
+
driver: claude-code
|
|
33
|
+
tasks:
|
|
34
|
+
- id: find-bugs
|
|
35
|
+
name: Find failing tests
|
|
36
|
+
prompt: 'List all failing tests in the current workspace with their file paths.'
|
|
37
|
+
completion:
|
|
38
|
+
type: llm_judge
|
|
39
|
+
rubric: |
|
|
40
|
+
The output must list at least 3 failing tests. Each entry must
|
|
41
|
+
include the test name, the file path, and the assertion that
|
|
42
|
+
failed. The output must not be an empty placeholder.
|
|
43
|
+
# endpoint / model / api_key_env all default to local Ollama + qwen3:4b
|
|
44
|
+
timeout: 120s
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Swap to a hosted backend:
|
|
48
|
+
|
|
49
|
+
```yaml
|
|
50
|
+
completion:
|
|
51
|
+
type: llm_judge
|
|
52
|
+
rubric: '...'
|
|
53
|
+
endpoint: https://api.openai.com/v1/chat/completions
|
|
54
|
+
model: gpt-4o-mini
|
|
55
|
+
api_key_env: OPENAI_API_KEY
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Or load it programmatically:
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import { bootstrapBuiltins, loadPlugins } from '@tagma/sdk';
|
|
62
|
+
|
|
63
|
+
bootstrapBuiltins();
|
|
64
|
+
await loadPlugins(['@tagma/completion-llm-judge']);
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Config
|
|
68
|
+
|
|
69
|
+
| Field | Type | Default | Notes |
|
|
70
|
+
| ------------------ | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
71
|
+
| `rubric` | string | _(required)_ | Plain-language success criteria the judge should verify |
|
|
72
|
+
| `model` | string | `qwen3:4b` | Judge model name. Swap for `qwen3:8b`, `deepseek-r1:7b`, `gpt-4o-mini`, etc. |
|
|
73
|
+
| `endpoint` | string | `http://localhost:11434/v1/chat/completions` | OpenAI-compatible chat completions URL. Default points at local Ollama |
|
|
74
|
+
| `api_key_env` | string | _(none)_ | Env var holding the bearer token. Leave unset for local Ollama; set for hosted backends |
|
|
75
|
+
| `timeout` | duration | `120s` | Max time to wait for the judge response (reasoning models need more time than chat models) |
|
|
76
|
+
| `max_output_chars` | number | `8000` | Truncate task stdout before judging (head+tail preserved) |
|
|
77
|
+
|
|
78
|
+
## Behavior
|
|
79
|
+
|
|
80
|
+
- **Verdict format**: the judge is instructed to answer `PASS` or `FAIL` on the first line. Missing or ambiguous answers are treated as FAIL — a judge that errs open defeats the purpose of the gate.
|
|
81
|
+
- **Reasoning-model support**: `<think>...</think>` and `<thinking>...</thinking>` blocks are stripped from the response before verdict parsing, so qwen3, DeepSeek-R1, and other thinkers work without any extra config.
|
|
82
|
+
- **Truncation**: task stdout longer than `max_output_chars` is truncated head-and-tail (70/30 split) with a marker in the middle, so the judge still sees the task's intent and its final summary.
|
|
83
|
+
- **Error handling**: network errors, auth errors, timeout, or malformed responses all mark the task as not-complete and log a warning with the judge's verbatim response (if any).
|
|
84
|
+
- **Abort propagation**: the pipeline abort signal is wired into the judge fetch call, so cancelling a pipeline also cancels any in-flight judge request.
|
|
85
|
+
- **Determinism**: the call uses `temperature: 0` to keep verdicts as stable as the model allows.
|
|
86
|
+
|
|
87
|
+
## Alternative endpoints
|
|
88
|
+
|
|
89
|
+
Any OpenAI-compatible endpoint works — just point `endpoint` and `api_key_env` at it:
|
|
90
|
+
|
|
91
|
+
- **Local Ollama** (default): `http://localhost:11434/v1/chat/completions`, no API key
|
|
92
|
+
- **OpenAI**: `https://api.openai.com/v1/chat/completions`, `api_key_env: OPENAI_API_KEY`
|
|
93
|
+
- **Local models** via LM Studio, vLLM, llama.cpp OpenAI-compatible servers
|
|
94
|
+
- **Hosted**: Groq, Together, Fireworks, OpenRouter, DeepInfra, etc.
|
|
95
|
+
- **Anthropic** via an OpenAI-compat proxy (e.g. `anthropic-openai-proxy`)
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tagma/completion-llm-judge",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "LLM-as-judge completion plugin for tagma-sdk pipelines",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"prepublishOnly": "bun run build"
|
|
50
50
|
},
|
|
51
51
|
"peerDependencies": {
|
|
52
|
-
"@tagma/types": "0.
|
|
52
|
+
"@tagma/types": "0.4.0"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
55
|
"bun-types": "^1.3.11",
|