@godspeedai/cognate-provider-typesafe 0.8.0 → 0.9.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.
Files changed (2) hide show
  1. package/package.json +4 -4
  2. package/src/EGM.md +35 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-provider-typesafe",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Native TypeSafe/System One typed decision provider, not a chat completion shim.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -22,8 +22,8 @@
22
22
  ".": "./src/index.ts"
23
23
  },
24
24
  "dependencies": {
25
- "@godspeedai/cognate-capabilities": "^0.8.0",
26
- "@godspeedai/cognate-events": "^0.8.0",
27
- "@godspeedai/cognate-provider-auth": "^0.8.0"
25
+ "@godspeedai/cognate-capabilities": "^0.9.0",
26
+ "@godspeedai/cognate-events": "^0.9.0",
27
+ "@godspeedai/cognate-provider-auth": "^0.9.0"
28
28
  }
29
29
  }
package/src/EGM.md ADDED
@@ -0,0 +1,35 @@
1
+ # provider-typesafe / src — System One judgment and ranking adapters
2
+
3
+ ## Overview
4
+
5
+ A `JudgmentProvider` over the `/v1/systemone` endpoint plus two `Ranker` bridges that let a judgment order the selector's eligible set `[index.ts:typeSafeProvider]`. The judgment adapter validates the request before dispatch and validates every answer against the question it answers `[index.ts:validatedAnswers]`. The module exports `typeSafeProvider`, `typeSafeRanker`, `typeSafeDirectRanker`, and `TypeSafeRankerOptions` `[index.ts:44]`.
6
+
7
+ ## Interface
8
+
9
+ - `typeSafeProvider` — builds the judgment provider `[index.ts:typeSafeProvider]`
10
+ - `typeSafeRanker` — ranker that judges in groups then the shortlist `[ranker.ts:typeSafeRanker]`
11
+ - `typeSafeDirectRanker` — ranker variant over the eligible set `[ranker.ts:typeSafeDirectRanker]`
12
+ - `TypeSafeRankerOptions` — `describe`, `groupSize` (2-8), `shortlistSize` `[ranker.ts:TypeSafeRankerOptions]`
13
+ - `validate` — internal request validation `[index.ts:validate]`
14
+ - `validatedAnswers` — internal per-question answer validation `[index.ts:validatedAnswers]`
15
+
16
+ ## Invariants
17
+
18
+ - A request must carry 1-32 questions; each id must match `^[A-Za-z0-9_.-]{1,100}$` with non-empty instructions `[index.ts:validate]`
19
+ - A `choice` question needs at least two criteria; a `score` question needs 2-10 levels `[index.ts:validate]`
20
+ - A returned choice must be a key of the question's criteria, and a returned score must be an integer-range number within `0..levels-1` `[index.ts:validatedAnswers]`
21
+ - A missing or type-mismatched answer for any requested id throws `judgment: missing or mismatched answer for <id>` `[index.ts:validatedAnswers]`
22
+ - An upstream non-OK status throws `judgment: upstream HTTP <status>`; unparseable JSON throws `judgment: malformed JSON response` `[index.ts:typeSafeProvider]`
23
+ - A malformed decision response payload is rejected unless `answers` is a record and `model` is a string `[index.ts:typeSafeProvider]`
24
+ - The adapter sees only the eligible set and its output is validated, so a judgment can order but never reintroduce an eliminated candidate or fail open `[ranker.ts:1]`
25
+
26
+ ## Side Effects
27
+
28
+ - Outbound HTTP POST to `${baseURL}/v1/systemone`, with trailing slash and `/v1` stripped from the base `[index.ts:typeSafeProvider]`
29
+ - Optional `idempotency-key` header set from `request.operationKey` `[index.ts:typeSafeProvider]`
30
+ - Timeout via `AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])` when `timeoutMs` is set `[index.ts:typeSafeProvider]`
31
+ - Credential headers through the injected `CredentialSource` `[index.ts:typeSafeProvider]`
32
+
33
+ ## Verification
34
+
35
+ - Run: `cd packages/provider-typesafe && bun test`