oracular 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -764,4 +764,63 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  */
 declare function createState(config: EngineConfig): EngineState;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, observe, predict, serialize, shouldReveal };
+/** The units of {@link ms}: each takes a count and returns milliseconds. */
+interface Units {
+    /** `n` seconds in milliseconds: `n × 1000`. */
+    readonly seconds: (n: number) => number;
+    /** `n` minutes in milliseconds: `n × 60 000`. */
+    readonly minutes: (n: number) => number;
+    /** `n` hours in milliseconds: `n × 3 600 000`. */
+    readonly hours: (n: number) => number;
+    /** `n` days in milliseconds: `n × 86 400 000`. */
+    readonly days: (n: number) => number;
+    /** `n` weeks in milliseconds: `n × 604 800 000`. */
+    readonly weeks: (n: number) => number;
+}
+/**
+ * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain
+ * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and
+ * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,
+ * write durations in that unit instead: the engine only needs the two to agree.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   episodeTimeout: ms.minutes(30),
+ *   intents: {
+ *     upgrade: {
+ *       prior: 0.05,
+ *       priorStrength: 10,
+ *       halfLife: ms.days(7),
+ *       signals: { 'pricing.viewed': 3 },
+ *       reveal: { cooldown: ms.weeks(2) },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+declare const ms: Units;
+
+/**
+ * Checks a config exactly as {@link createState} and {@link deserialize} do, without building a
+ * state, and returns the normalized copy they would store: only the recognised keys, in a fixed
+ * order, with every `undefined` dropped, so it survives a JSON round trip unchanged. Use it to
+ * fail fast at startup or in a test, or on a config loaded from a file, before the engine runs.
+ *
+ * @param config - The config to check. Typed `unknown` so parsed JSON can be passed as it is.
+ * @returns A fresh, normalized {@link EngineConfig}. `config` is not mutated.
+ * @throws `TypeError` when a value has the wrong type or a key is not recognised.
+ * @throws `RangeError` when a number is out of range: a `prior` outside (0, 1), a signal weight of
+ *   0, or a weight, `priorStrength`, `learning.gain` or `learning.priorEpisodes` beyond 1e6.
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs';
+ * import { validateConfig } from 'oracular';
+ *
+ * // Throws with the offending path in the message, e.g. config.intents["upgrade"].prior
+ * const config = validateConfig(JSON.parse(readFileSync('oracular.config.json', 'utf8')));
+ * ```
+ */
+declare function validateConfig(config: unknown): EngineConfig;
+
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };

package/dist/index.d.ts

@@ -764,4 +764,63 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  */
 declare function createState(config: EngineConfig): EngineState;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, observe, predict, serialize, shouldReveal };
+/** The units of {@link ms}: each takes a count and returns milliseconds. */
+interface Units {
+    /** `n` seconds in milliseconds: `n × 1000`. */
+    readonly seconds: (n: number) => number;
+    /** `n` minutes in milliseconds: `n × 60 000`. */
+    readonly minutes: (n: number) => number;
+    /** `n` hours in milliseconds: `n × 3 600 000`. */
+    readonly hours: (n: number) => number;
+    /** `n` days in milliseconds: `n × 86 400 000`. */
+    readonly days: (n: number) => number;
+    /** `n` weeks in milliseconds: `n × 604 800 000`. */
+    readonly weeks: (n: number) => number;
+}
+/**
+ * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain
+ * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and
+ * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,
+ * write durations in that unit instead: the engine only needs the two to agree.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   episodeTimeout: ms.minutes(30),
+ *   intents: {
+ *     upgrade: {
+ *       prior: 0.05,
+ *       priorStrength: 10,
+ *       halfLife: ms.days(7),
+ *       signals: { 'pricing.viewed': 3 },
+ *       reveal: { cooldown: ms.weeks(2) },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+declare const ms: Units;
+
+/**
+ * Checks a config exactly as {@link createState} and {@link deserialize} do, without building a
+ * state, and returns the normalized copy they would store: only the recognised keys, in a fixed
+ * order, with every `undefined` dropped, so it survives a JSON round trip unchanged. Use it to
+ * fail fast at startup or in a test, or on a config loaded from a file, before the engine runs.
+ *
+ * @param config - The config to check. Typed `unknown` so parsed JSON can be passed as it is.
+ * @returns A fresh, normalized {@link EngineConfig}. `config` is not mutated.
+ * @throws `TypeError` when a value has the wrong type or a key is not recognised.
+ * @throws `RangeError` when a number is out of range: a `prior` outside (0, 1), a signal weight of
+ *   0, or a weight, `priorStrength`, `learning.gain` or `learning.priorEpisodes` beyond 1e6.
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs';
+ * import { validateConfig } from 'oracular';
+ *
+ * // Throws with the offending path in the message, e.g. config.intents["upgrade"].prior
+ * const config = validateConfig(JSON.parse(readFileSync('oracular.config.json', 'utf8')));
+ * ```
+ */
+declare function validateConfig(config: unknown): EngineConfig;
+
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };

package/dist/index.js

@@ -941,6 +941,20 @@ function reconcile(raw, config) {
   };
 }
 
-export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, observe, predict, serialize, shouldReveal };
+// src/units.ts
+var ms = {
+  seconds: (n) => n * 1e3,
+  minutes: (n) => n * 6e4,
+  hours: (n) => n * 36e5,
+  days: (n) => n * 864e5,
+  weeks: (n) => n * 6048e5
+};
+
+// src/validate.ts
+function validateConfig(config) {
+  return normalizeConfig(config);
+}
+
+export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map