jevascript 0.1.0

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Provider-neutral vocabulary.
+ *
+ * Deliberately NOT named after any one provider (see design rule: no `jevNoul()`
+ * in the public API). Jev's `noul` is our `truth`, Jev's `score` is our `level`.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * What gets evaluated. Providers accept text only, so objects are serialised
+ * as JSON before they are sent.
+ *
+ * Typed as `object` rather than `Record<string, unknown>` on purpose: an
+ * `interface` has no implicit index signature, so the narrower type would
+ * reject exactly the case this library exists for — handing it the domain
+ * object you already have.
+ */
+export type State = string | readonly string[] | object;
+/**
+ * A yes/no proposition. The provider returns P(true), which carries both the
+ * answer and its uncertainty — there is no separate confidence for this kind.
+ */
+export interface TruthQuestion {
+    readonly kind: "truth";
+    /** Written as a proposition, not a noun phrase. */
+    readonly instructions: string | JsonValue;
+    /** What clearly counts as true. Materially improves accuracy on edge cases. */
+    readonly trueWhen?: string | JsonValue;
+    /** What clearly does *not* count, even if it looks close. */
+    readonly falseWhen?: string | JsonValue;
+}
+export interface ChoiceOptionSpec {
+    readonly what: string;
+    readonly not_for?: string;
+    readonly examples?: readonly string[];
+}
+/** Pick exactly one of a fixed set. */
+export interface ChoiceQuestion {
+    readonly kind: "choice";
+    readonly instructions: string | JsonValue;
+    readonly options: Readonly<Record<string, string | ChoiceOptionSpec>>;
+}
+export interface LevelSpec {
+    readonly summary: string;
+    readonly signals?: readonly string[];
+}
+/**
+ * Position on an ordered rubric. Levels describe *situations*, not degrees —
+ * "feature broken, workaround exists" rather than "moderately severe".
+ */
+export interface LevelQuestion {
+    readonly kind: "level";
+    readonly instructions: string | JsonValue;
+    readonly levels: readonly (string | LevelSpec)[];
+}
+export type SemanticQuestion = TruthQuestion | ChoiceQuestion | LevelQuestion;
+export interface TruthAnswer {
+    readonly kind: "truth";
+    /** P(the proposition is true), 0–1. */
+    readonly probability: number;
+}
+export interface ChoiceAnswer {
+    readonly kind: "choice";
+    readonly choice: string;
+    readonly probabilities: Readonly<Record<string, number>>;
+    /** How concentrated the distribution is, 0–1. */
+    readonly confidence: number;
+}
+export interface LevelAnswer {
+    readonly kind: "level";
+    /**
+     * Probability-weighted mean over levels, **0-indexed**: 0 is the first level
+     * and probabilities.length - 1 the last. Verified against the live API, which
+     * indexes from 0 even though the published example reads as 1-indexed.
+     * May land between levels.
+     */
+    readonly level: number;
+    readonly probabilities: readonly number[];
+    readonly confidence: number;
+}
+export type SemanticAnswer = TruthAnswer | ChoiceAnswer | LevelAnswer;
+export interface Usage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+/**
+ * Multi-question by construction. A single-question shape would make batching
+ * impossible to express through the adapter, and batching is where nearly all
+ * of the cost and latency savings live.
+ */
+export interface SemanticRequest {
+    readonly state: State;
+    readonly questions: Readonly<Record<string, SemanticQuestion>>;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface SemanticProviderResponse {
+    readonly answers: Readonly<Record<string, SemanticAnswer>>;
+    readonly usage?: Usage;
+    readonly model?: string;
+}
+/**
+ * Providers differ sharply in what they can express. Stating capabilities up
+ * front lets the runtime reject impossible requests at configuration time
+ * rather than failing deep inside a production call path.
+ */
+export interface ProviderCapabilities {
+    readonly maxChoiceOptions: number;
+    /** Inclusive [min, max] number of rubric levels. */
+    readonly levelRange: readonly [number, number];
+    readonly maxStateTokens?: number;
+    readonly maxTotalTokens?: number;
+    /** False for decision-only models: no generated rationale is possible. */
+    readonly generatesText: boolean;
+    /** Whether many questions in one request cost less than many requests. */
+    readonly batching: boolean;
+}
+export interface SemanticProvider {
+    readonly name: string;
+    /** Pinned model identity. Must be a concrete version, never a moving alias. */
+    readonly model: string;
+    readonly capabilities: ProviderCapabilities;
+    evaluate(request: SemanticRequest): Promise<SemanticProviderResponse>;
+}
+export interface EvaluationEvent {
+    readonly operation: "is" | "score" | "choose" | "batch" | "evaluate" | "rank" | "filter" | "find" | "compare";
+    readonly keys: readonly string[];
+    readonly provider: string;
+    readonly model: string;
+    readonly latencyMs: number;
+    readonly cached: boolean;
+    readonly batched: boolean;
+    readonly questionCount: number;
+    /** Requests actually issued. Greater than one when `samples` was in play. */
+    readonly requestCount: number;
+    readonly samples: number;
+    readonly usage?: Usage;
+    readonly metric?: {
+        name: string;
+        version?: string;
+    };
+}
+export interface Observability {
+    onEvaluation?(event: EvaluationEvent): void;
+    /** Fired when calls that could have shared a request did not. */
+    onUnbatched?(info: {
+        context: string;
+        flushCount: number;
+    }): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Provider-neutral vocabulary.
+ *
+ * Deliberately NOT named after any one provider (see design rule: no `jevNoul()`
+ * in the public API). Jev's `noul` is our `truth`, Jev's `score` is our `level`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "jevascript",
+  "version": "0.1.0",
+  "description": "Semantic values for deterministic TypeScript: is, score and choose as ordinary values, backed by a decision model.",
+  "license": "MIT",
+  "homepage": "https://jevascript.org",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./testing": { "types": "./dist/testing.d.ts", "default": "./dist/testing.js" }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": { "node": ">=22.6" },
+  "keywords": ["llm", "semantic", "decision-model", "jev", "typescript", "classification", "scoring"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "npm run build && tsc -p tsconfig.test.json",
+    "test": "npm run typecheck && node --test test/*.test.ts",
+    "example": "node --env-file=.env --experimental-strip-types",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}