Mirror of https://github.com/roostorg/coop-integration-example
github.com/roostorg/coop-integration-example
[Types] Upgrade types and include new required model card fields (#2)
* [Types] Upgrade types and include new required model card fields
* add codeowners
* code review changes
+112
-44
+6
.github/CODEOWNERS
+6
.github/CODEOWNERS
+4
-4
README.md
+4
-4
README.md
···
10
10
11
11
- **Integration:** `COOP_INTEGRATION_EXAMPLE`
12
12
- **Signal 1 – Random Signal Selection** (`RANDOM_SIGNAL_SELECTION`): Returns `true` or `false` at random. The probability (0–100%) comes from the org’s integration config (“True percentage”). Set e.g. `70` in Org settings → Integrations; the signal returns `true` about 70% of the time. Use this to test config saving and boolean conditions.
13
-
- **Signal 2 – Random Score** (`RANDOM_SCORE`): Returns a random number between 0 and 1. No integration config needed. In the rule builder you set a **threshold** (e.g. `0.5`) and choose **above** or **below**. Use this to test numeric score conditions (e.g. “score ≥ 0.5” or “score < 0.3”).
13
+
- **Signal 2 – Random Score** (`RANDOM_SCORE`): Returns a random number from **0 up to (but not including) 100**—the same 0–100 style as “True percentage,” so thresholds feel consistent. No integration config needed. In the rule builder set a **threshold** (e.g. `50`) and choose **above** or **below**. Use this to test numeric score conditions (e.g. “score ≥ 50” or “score < 30”).
14
14
15
15
## Install
16
16
···
61
61
1. **Org settings → Integrations** – you should see “COOP Integration Example”. Open it and set **True percentage (0–100)** (e.g. `70`) for Random Signal Selection. Save.
62
62
2. **Rules (routing or enforcement)** – when adding a condition:
63
63
- **Random Signal Selection**: Pick that signal; the condition uses your configured percentage (true/false).
64
-
- **Random Score**: Pick “Random Score”, then set a **threshold** (e.g. `0.5`) and choose **above** or **below**. The rule compares the random score to your threshold.
64
+
- **Random Score**: Pick “Random Score”, then set a **threshold** on the 0–100 scale (e.g. `50`) and choose **above** or **below**. The rule compares the random score to your threshold.
65
65
66
66
## Contract
67
67
68
68
This package implements the COOP plugin contract from `@roostorg/types`:
69
69
70
70
- **Default export:** `CoopIntegrationPlugin` with `manifest` and `createSignals(context)`.
71
-
- **Manifest:** `id`, `name`, `version`, `requiresConfig`, `configurationFields`, `signalTypeIds`, `modelCard` (with required sections `modelDetails` and `technicalIntegration`).
71
+
- **Manifest:** `id`, `name`, `version`, `requiresConfig`, `configurationFields`, `signalTypeIds`, `modelCard` (must include every section id in `REQUIRED_MODEL_CARD_SECTION_IDS` from `@roostorg/types`; call `assertModelCardHasRequiredSections(modelCard)` when registering).
72
72
- **createSignals:** Returns two descriptors:
73
73
- `RANDOM_SIGNAL_SELECTION`: `run(input)` uses `context.getCredential(orgId)` for true percentage; returns `{ outputType: { scalarType: 'BOOLEAN' }, score: boolean }`.
74
-
- `RANDOM_SCORE`: `run()` returns `{ outputType: { scalarType: 'NUMBER' }, score: number }` in [0, 1]; no config. Threshold is set in the rule (above/below).
74
+
- `RANDOM_SCORE`: `run()` returns `{ outputType: { scalarType: 'NUMBER' }, score: number }` in **[0, 100)** (`Math.random() * 100`); no config. Threshold is set in the rule on the same scale (above/below).
75
75
76
76
## Publishing
77
77
+8
-8
package-lock.json
+8
-8
package-lock.json
···
1
1
{
2
2
"name": "@roostorg/coop-integration-example",
3
-
"version": "1.0.0",
3
+
"version": "2.0.0",
4
4
"lockfileVersion": 3,
5
5
"requires": true,
6
6
"packages": {
7
7
"": {
8
8
"name": "@roostorg/coop-integration-example",
9
-
"version": "1.0.0",
10
-
"license": "ISC",
9
+
"version": "2.0.0",
10
+
"license": "Apache-2.0",
11
11
"devDependencies": {
12
-
"@roostorg/types": "^1.1.1",
12
+
"@roostorg/types": "^2.0.0",
13
13
"typescript": "^5.0.0"
14
14
},
15
15
"engines": {
16
16
"node": ">=18"
17
17
},
18
18
"peerDependencies": {
19
-
"@roostorg/types": ">=1.0.0"
19
+
"@roostorg/types": ">=2.0.0"
20
20
}
21
21
},
22
22
"node_modules/@babel/runtime": {
···
30
30
}
31
31
},
32
32
"node_modules/@roostorg/types": {
33
-
"version": "1.1.1",
34
-
"resolved": "https://registry.npmjs.org/@roostorg/types/-/types-1.1.1.tgz",
35
-
"integrity": "sha512-NhPYlG27wAQaD7AzWkL3LJHu52/QfK8lt9QMahUx7fbRtB4fYILy4fGcLQvt45gNQANoU78evW1UJftAB0B89Q==",
33
+
"version": "2.0.0",
34
+
"resolved": "https://registry.npmjs.org/@roostorg/types/-/types-2.0.0.tgz",
35
+
"integrity": "sha512-EyLecshJqiZdughsBgaJcR6nOmZ6cT5ioNeRB1Cif6b0ZrXc9LfBirXd2FPZ1qzxxIjgMUOA1HSxfFVThMRZlw==",
36
36
"dev": true,
37
37
"license": "ISC",
38
38
"dependencies": {
+4
-4
package.json
+4
-4
package.json
···
1
1
{
2
2
"name": "@roostorg/coop-integration-example",
3
-
"version": "1.0.0",
3
+
"version": "2.0.0",
4
4
"description": "Example package to show how a custom integration and signal can be used in COOP this is meant to be a reference repository and provide basic determination",
5
5
"type": "module",
6
6
"main": "dist/index.js",
···
23
23
"example"
24
24
],
25
25
"author": "Roostorg",
26
-
"license": "apache-2.0",
26
+
"license": "Apache-2.0",
27
27
"repository": {
28
28
"type": "git",
29
29
"url": "https://github.com/roostorg/coop-integration-example.git"
···
33
33
},
34
34
"homepage": "https://github.com/roostorg/coop-integration-example#readme",
35
35
"peerDependencies": {
36
-
"@roostorg/types": ">=1.0.0"
36
+
"@roostorg/types": ">=2.0.0"
37
37
},
38
38
"devDependencies": {
39
-
"@roostorg/types": "^1.1.1",
39
+
"@roostorg/types": "^2.0.0",
40
40
"typescript": "^5.0.0"
41
41
},
42
42
"engines": {
+90
-28
src/index.ts
+90
-28
src/index.ts
···
1
1
/**
2
2
* Example COOP integration plugin with two signal types:
3
3
* 1. Random Signal Selection – boolean, probability from org config (tests config saving).
4
-
* 2. Random Score – numeric [0, 1], threshold set in the rule (tests score vs threshold).
4
+
* 2. Random Score – numeric 0–100, threshold set in the rule (tests score vs threshold).
5
5
*/
6
6
7
-
import type {
8
-
CoopIntegrationPlugin,
9
-
IntegrationManifest,
10
-
ModelCard,
11
-
PluginSignalContext,
12
-
PluginSignalDescriptor,
7
+
import {
8
+
assertModelCardHasRequiredSections,
9
+
type CoopIntegrationPlugin,
10
+
type IntegrationManifest,
11
+
type ModelCard,
12
+
type PluginSignalContext,
13
+
type PluginSignalDescriptor,
13
14
} from '@roostorg/types';
14
15
15
16
const SIGNAL_TYPE_RANDOM_SELECTION = 'RANDOM_SIGNAL_SELECTION';
···
19
20
20
21
const modelCard: ModelCard = {
21
22
modelName: 'COOP Integration Example',
22
-
version: '1.0.0',
23
-
releaseDate: '2026',
23
+
version: '2.0.0',
24
+
releaseDate: 'March 2026',
24
25
sections: [
25
26
{
26
-
id: 'modelDetails',
27
-
title: 'Model Details',
27
+
id: 'trainingData',
28
+
title: 'Training Data',
29
+
fields: [
30
+
{
31
+
label: 'Overview',
32
+
value:
33
+
'This reference integration does not use a trained model. Outputs are randomly generated for demonstration and testing of COOP rules, configuration, and UI only.',
34
+
},
35
+
],
36
+
},
37
+
{
38
+
id: 'policyAndTaxonomy',
39
+
title: 'Policy and Taxonomy',
40
+
fields: [
41
+
{
42
+
label: 'Scope',
43
+
value:
44
+
'Not a content policy engine. Signals are placeholders: boolean “coin flip” with configurable probability and a numeric random score for threshold exercises in rules.',
45
+
},
46
+
],
47
+
},
48
+
{
49
+
id: 'annotationMethodology',
50
+
title: 'Annotation Methodology',
28
51
fields: [
29
-
{ label: 'Model Name', value: 'COOP Integration Example' },
30
52
{
31
-
label: 'Purpose',
53
+
label: 'Method',
32
54
value:
33
-
'Example plugin with two signals: one uses org config (boolean), one returns a numeric score so you can set a threshold in the rule (over/under).',
55
+
'No human or automated labeling pipeline. Values are produced with Math.random() (or equivalent logic) at evaluation time.',
34
56
},
57
+
],
58
+
},
59
+
{
60
+
id: 'performanceBenchmarks',
61
+
title: 'Performance and Benchmarks',
62
+
fields: [
63
+
{
64
+
label: 'Benchmarks',
65
+
value:
66
+
'No precision, recall, or latency benchmarks apply. Do not use performance claims from this package in production decisions.',
67
+
},
68
+
],
69
+
},
70
+
{
71
+
id: 'biasAndLimitations',
72
+
title: 'Bias and Limitations',
73
+
fields: [
74
+
{
75
+
label: 'Limitations',
76
+
value:
77
+
'Outputs are uncorrelated with input content. Unsuitable for safety, compliance, or moderation decisions. For integration testing and developer learning only.',
78
+
},
79
+
],
80
+
},
81
+
{
82
+
id: 'implementationGuidance',
83
+
title: 'Implementation Guidance',
84
+
fields: [
35
85
{
36
86
label: 'Signals',
37
-
value: `${SIGNAL_TYPE_RANDOM_SELECTION} (boolean, config-driven) and ${SIGNAL_TYPE_RANDOM_SCORE} (number 0–1, threshold in rule).`,
87
+
value: `${SIGNAL_TYPE_RANDOM_SELECTION} (boolean; org config truePercentage 0–100). ${SIGNAL_TYPE_RANDOM_SCORE} (number 0–100; set threshold and above/below in the rule).`,
88
+
},
89
+
{
90
+
label: 'Configuration',
91
+
value:
92
+
'Random Signal Selection requires org integration config (true percentage). Random Score requires no integration config.',
93
+
},
94
+
{
95
+
label: 'Versioning',
96
+
value:
97
+
'modelCard.version and manifest.version identify this integration plugin release. They are independent of the @roostorg/types dependency major version (e.g. 2.x).',
38
98
},
39
99
],
40
100
},
41
101
{
42
-
id: 'technicalIntegration',
43
-
title: 'Technical Integration',
102
+
id: 'relevantLinks',
103
+
title: 'Relevant Links',
44
104
fields: [
45
105
{
46
-
label: 'Signal types',
47
-
value: `${SIGNAL_TYPE_RANDOM_SELECTION}, ${SIGNAL_TYPE_RANDOM_SCORE}`,
106
+
label: 'Repository',
107
+
value: 'https://github.com/roostorg/coop-integration-example',
48
108
},
49
109
{
50
-
label: 'Config',
51
-
value: 'truePercentage (0–100) for Random Signal Selection only; Random Score needs no config.',
110
+
label: 'Documentation',
111
+
value: 'https://roostorg.github.io/coop/INTEGRATIONS_PLUGIN.html',
52
112
},
53
113
],
54
114
},
55
115
],
56
116
};
57
117
118
+
assertModelCardHasRequiredSections(modelCard);
119
+
58
120
const manifest: IntegrationManifest = {
59
121
id: INTEGRATION_ID,
60
122
name: 'COOP Integration Example',
61
-
version: '1.0.0',
123
+
/** Same semver as modelCard.version: this plugin’s release, not @roostorg/types. */
124
+
version: '2.0.0',
62
125
description:
63
126
'Example plugin with two signals: config-driven boolean and a numeric score you compare with a threshold in the rule.',
64
-
docsUrl: 'https://github.com/roostorg/coop/tree/main/coop-integration-example',
127
+
docsUrl: 'https://roostorg.github.io/coop/INTEGRATIONS_PLUGIN.html',
65
128
requiresConfig: true,
66
129
configurationFields: [
67
130
{
···
158
221
id: { type: SIGNAL_TYPE_RANDOM_SCORE },
159
222
displayName: 'Random Score',
160
223
description:
161
-
'Returns a random number between 0 and 1. Set a threshold in the rule (e.g. 0.5) and choose "above" or "below" to test numeric conditions.',
224
+
'Returns a random number from 0 up to (but not including) 100. Set a threshold in the rule (e.g. 50) and choose "above" or "below" to test numeric conditions.',
162
225
docsUrl: null,
163
226
recommendedThresholds: {
164
-
highPrecisionThreshold: 0.5,
165
-
highRecallThreshold: 0.5,
227
+
highPrecisionThreshold: 50,
228
+
highRecallThreshold: 50,
166
229
},
167
230
supportedLanguages: 'ALL',
168
231
pricingStructure: { type: 'FREE' },
···
178
241
async run(
179
242
_input: unknown,
180
243
): Promise<{ outputType: typeof outputType; score: number }> {
181
-
// Returns a random number between 0 and 100.
182
-
// Because outputType is { scalarType: 'NUMBER' }, Coop can take the score and compare it to a threshold in the rule.
244
+
// [0, 100) — same scale as percentages elsewhere in this plugin (e.g. truePercentage).
183
245
const score = Math.random() * 100;
184
246
return { outputType, score };
185
247
},