@framers/agentos 0.5.1 → 0.5.3

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.d.ts

@@ -2,7 +2,7 @@
  * @file TypedNetworkObserver.ts
  * @description LLM-driven extractor that turns a conversation block
  * into 0+ {@link TypedFact}s. Wraps the 6-step extraction prompt and
- * the zod-validated parsing of the LLM's structured-output response.
+ * the tolerant zod parsing of the LLM's structured-output response.
  *
  * Production wiring: a typical caller constructs the observer once per
  * pipeline (re-using the same `gpt-5-mini` adapter), then invokes
@@ -10,6 +10,30 @@
  * are then upserted into a {@link TypedNetworkStore} and embedded by
  * the host's {@link IEmbeddingManager}.
  *
+ * **Tolerance design (Phase 4c smoke fix):** the parser accepts the
+ * common deviations gpt-5-mini emits at scale, rather than throwing on
+ * any deviation:
+ *
+ * 1. **Code-fence stripping**: triple-backtick fences (with or without
+ *    language tag) are removed before JSON parse.
+ * 2. **Top-level array auto-wrap**: a bare `[fact, fact]` is wrapped
+ *    as `{facts: [...]}` before schema validation.
+ * 3. **Per-fact tolerance**: facts are validated one at a time via
+ *    `TypedExtractionFactSchema.safeParse`. Bad facts are dropped
+ *    silently; good facts in the same response are kept.
+ * 4. **Schema-level defaults**: `temporal`, `participants`,
+ *    `reasoning_markers`, and `entities` default to sensible empties
+ *    when the LLM omits them. `bank` is uppercase-coerced. See
+ *    {@link TypedExtractionFactSchema} for the full tolerance surface.
+ * 5. **Retry-on-outer-failure**: if the catastrophic outer parse
+ *    fails (invalid JSON, primitive value, neither array nor object
+ *    with `facts`), the extractor retries once with the validation
+ *    error appended to the user prompt. Implements spec section 6's
+ *    retry path that was specified but never shipped.
+ *
+ * The extract method NEVER throws on extractable input; persistent
+ * outer failure returns `[]` so the caller can continue ingest.
+ *
  * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkObserver
  */
 import type { TypedFact } from './types.js';
@@ -38,6 +62,14 @@ export interface TypedNetworkObserverOptions {
     maxTokens?: number;
     /** Temperature. Default 0 for deterministic extraction. */
     temperature?: number;
+    /**
+     * Per-attempt request timeout in milliseconds. When the underlying
+     * `llm.invoke()` does not resolve within this window the attempt is
+     * abandoned and the observer falls through to the retry path. Used
+     * to prevent stale TCP sockets / hung OpenAI requests from
+     * deadlocking long-running ingest pipelines. Default 30 000 ms (30 s).
+     */
+    timeoutMs?: number;
 }
 /**
  * The 6-step extractor. Stateless aside from its constructor options;
@@ -47,21 +79,35 @@ export declare class TypedNetworkObserver {
     private readonly llm;
     private readonly maxTokens;
     private readonly temperature;
+    private readonly timeoutMs;
     constructor(options: TypedNetworkObserverOptions);
     /**
-     * Extract typed facts from a conversation block. Uses the 6-step
-     * prompt + zod-validated parsing. The resulting facts have stable
-     * IDs of the form `<sessionId>-fact-<index>` so re-extraction
-     * against the same content reproduces the same IDs.
+     * Extract typed facts from a conversation block.
+     *
+     * Resulting facts have stable IDs of the form
+     * `<sessionId>-fact-<index>`, where `<index>` is the sequential
+     * POST-DROP position so dropped facts produce contiguous IDs in the
+     * returned array.
+     *
+     * **Never throws on extractable input.** Catastrophic outer parse
+     * failures (invalid JSON, primitive value, missing facts key) get
+     * one retry; persistent failure returns `[]`. Bad individual facts
+     * are dropped silently via per-fact `safeParse`.
      *
      * @param sessionText - Full conversation text. Will be wrapped in
      *   the user prompt's delimiters automatically.
      * @param sessionId - Stable identifier used to namespace the
      *   resulting fact IDs.
      * @returns Array of {@link TypedFact}s, possibly empty.
-     * @throws ZodError if the LLM output fails schema validation.
-     * @throws SyntaxError if the LLM output is not valid JSON.
      */
     extract(sessionText: string, sessionId: string): Promise<TypedFact[]>;
+    /**
+     * Run `this.llm.invoke()` with a per-attempt timeout. Throws an
+     * `Error('TypedNetworkObserver: extraction timed out after Nms')`
+     * when the timer fires before the LLM responds. The timer is cleared
+     * on resolution to avoid leaking pending timeouts into subsequent
+     * extractions.
+     */
+    private invokeWithTimeout;
 }
 //# sourceMappingURL=TypedNetworkObserver.d.ts.map

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypedNetworkObserver.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,IAAI,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,GAAG,EAAE,mBAAmB,CAAC;IACzB,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,2BAA2B;IAMhD;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAwB5E"}
+{"version":3,"file":"TypedNetworkObserver.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,IAAI,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,GAAG,EAAE,mBAAmB,CAAC;IACzB,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,2BAA2B;IAOhD;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAuE3E;;;;;;OAMG;YACW,iBAAiB;CAuBhC"}

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.js

@@ -2,7 +2,7 @@
  * @file TypedNetworkObserver.ts
  * @description LLM-driven extractor that turns a conversation block
  * into 0+ {@link TypedFact}s. Wraps the 6-step extraction prompt and
- * the zod-validated parsing of the LLM's structured-output response.
+ * the tolerant zod parsing of the LLM's structured-output response.
  *
  * Production wiring: a typical caller constructs the observer once per
  * pipeline (re-using the same `gpt-5-mini` adapter), then invokes
@@ -10,10 +10,40 @@
  * are then upserted into a {@link TypedNetworkStore} and embedded by
  * the host's {@link IEmbeddingManager}.
  *
+ * **Tolerance design (Phase 4c smoke fix):** the parser accepts the
+ * common deviations gpt-5-mini emits at scale, rather than throwing on
+ * any deviation:
+ *
+ * 1. **Code-fence stripping**: triple-backtick fences (with or without
+ *    language tag) are removed before JSON parse.
+ * 2. **Top-level array auto-wrap**: a bare `[fact, fact]` is wrapped
+ *    as `{facts: [...]}` before schema validation.
+ * 3. **Per-fact tolerance**: facts are validated one at a time via
+ *    `TypedExtractionFactSchema.safeParse`. Bad facts are dropped
+ *    silently; good facts in the same response are kept.
+ * 4. **Schema-level defaults**: `temporal`, `participants`,
+ *    `reasoning_markers`, and `entities` default to sensible empties
+ *    when the LLM omits them. `bank` is uppercase-coerced. See
+ *    {@link TypedExtractionFactSchema} for the full tolerance surface.
+ * 5. **Retry-on-outer-failure**: if the catastrophic outer parse
+ *    fails (invalid JSON, primitive value, neither array nor object
+ *    with `facts`), the extractor retries once with the validation
+ *    error appended to the user prompt. Implements spec section 6's
+ *    retry path that was specified but never shipped.
+ *
+ * The extract method NEVER throws on extractable input; persistent
+ * outer failure returns `[]` so the caller can continue ingest.
+ *
  * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkObserver
  */
-import { TypedExtractionSchema } from './prompts/extraction-schema.js';
+import { TypedExtractionFactSchema } from './prompts/extraction-schema.js';
 import { TYPED_EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt, } from './prompts/extraction-prompt.js';
+/**
+ * Maximum total LLM invocations per `extract` call. The first attempt
+ * uses the base prompt; the second appends the validation error from
+ * the first attempt for the model to self-correct against.
+ */
+const MAX_ATTEMPTS = 2;
 /**
  * The 6-step extractor. Stateless aside from its constructor options;
  * safe to share across concurrent extractions.
@@ -23,35 +53,129 @@ export class TypedNetworkObserver {
         this.llm = options.llm;
         this.maxTokens = options.maxTokens ?? 4096;
         this.temperature = options.temperature ?? 0;
+        this.timeoutMs = options.timeoutMs ?? 30000;
     }
     /**
-     * Extract typed facts from a conversation block. Uses the 6-step
-     * prompt + zod-validated parsing. The resulting facts have stable
-     * IDs of the form `<sessionId>-fact-<index>` so re-extraction
-     * against the same content reproduces the same IDs.
+     * Extract typed facts from a conversation block.
+     *
+     * Resulting facts have stable IDs of the form
+     * `<sessionId>-fact-<index>`, where `<index>` is the sequential
+     * POST-DROP position so dropped facts produce contiguous IDs in the
+     * returned array.
+     *
+     * **Never throws on extractable input.** Catastrophic outer parse
+     * failures (invalid JSON, primitive value, missing facts key) get
+     * one retry; persistent failure returns `[]`. Bad individual facts
+     * are dropped silently via per-fact `safeParse`.
      *
      * @param sessionText - Full conversation text. Will be wrapped in
      *   the user prompt's delimiters automatically.
      * @param sessionId - Stable identifier used to namespace the
      *   resulting fact IDs.
      * @returns Array of {@link TypedFact}s, possibly empty.
-     * @throws ZodError if the LLM output fails schema validation.
-     * @throws SyntaxError if the LLM output is not valid JSON.
      */
     async extract(sessionText, sessionId) {
-        const raw = await this.llm.invoke({
+        const baseUserPrompt = buildExtractionUserPrompt(sessionText);
+        let lastValidationError = null;
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+            // First attempt uses the bare prompt; retry appends the
+            // validation error so the model can self-correct.
+            const userPrompt = lastValidationError === null
+                ? baseUserPrompt
+                : `${baseUserPrompt}\n\nThe previous response failed validation: ${lastValidationError}\nReturn JSON matching the schema strictly. Do not add commentary.`;
+            // Race the underlying invoke against a per-attempt timeout. A
+            // hung TCP socket / unresponsive provider would otherwise
+            // deadlock long-running ingest pipelines — at concurrency=1 a
+            // single hung request stalls every subsequent session forever.
+            // The timeout fires from the agentos side without requiring the
+            // adapter to surface AbortSignal support; the underlying request
+            // is abandoned (its socket leaks until GC / process exit) but
+            // the observer moves to its retry path.
+            let raw;
+            try {
+                raw = await this.invokeWithTimeout(userPrompt);
+            }
+            catch (err) {
+                lastValidationError = err instanceof Error ? err.message : String(err);
+                continue;
+            }
+            const stripped = stripCodeFence(raw);
+            // Parse JSON. SyntaxError captures bad-JSON outer failures into
+            // the retry path.
+            let json;
+            try {
+                json = JSON.parse(stripped);
+            }
+            catch (err) {
+                lastValidationError = err instanceof Error ? err.message : String(err);
+                continue;
+            }
+            // Auto-wrap top-level array. gpt-5-mini frequently emits a bare
+            // facts array instead of `{facts: [...]}`; this recovers the
+            // most common deviation.
+            const container = Array.isArray(json) ? { facts: json } : json;
+            // Outer-shape validation. We accept any object with a `facts`
+            // array; per-fact validation runs in `extractFactsFromContainer`.
+            if (typeof container !== 'object' ||
+                container === null ||
+                !('facts' in container) ||
+                !Array.isArray(container.facts)) {
+                lastValidationError =
+                    'expected JSON object with a "facts" array; got unexpected outer shape';
+                continue;
+            }
+            return extractFactsFromContainer(container.facts, sessionId);
+        }
+        // Both attempts failed at the outer layer; return empty rather
+        // than throwing so the caller can continue ingest. The caller is
+        // responsible for downstream "no typed facts in this session"
+        // semantics.
+        return [];
+    }
+    /**
+     * Run `this.llm.invoke()` with a per-attempt timeout. Throws an
+     * `Error('TypedNetworkObserver: extraction timed out after Nms')`
+     * when the timer fires before the LLM responds. The timer is cleared
+     * on resolution to avoid leaking pending timeouts into subsequent
+     * extractions.
+     */
+    async invokeWithTimeout(userPrompt) {
+        let timeoutHandle = null;
+        const invokePromise = this.llm.invoke({
             system: TYPED_EXTRACTION_SYSTEM_PROMPT,
-            user: buildExtractionUserPrompt(sessionText),
+            user: userPrompt,
             maxTokens: this.maxTokens,
             temperature: this.temperature,
         });
-        // Strip markdown code fences if the LLM wraps the JSON in them
-        // (some models do this even with explicit "no commentary" prompts).
-        const stripped = stripCodeFence(raw);
-        const json = JSON.parse(stripped);
-        const parsed = TypedExtractionSchema.parse(json);
-        return parsed.facts.map((f, idx) => ({
-            id: `${sessionId}-fact-${idx}`,
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timeoutHandle = setTimeout(() => {
+                reject(new Error(`TypedNetworkObserver: extraction timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+        });
+        try {
+            return await Promise.race([invokePromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutHandle !== null)
+                clearTimeout(timeoutHandle);
+        }
+    }
+}
+/**
+ * Run per-fact tolerance over a candidate array. Returns only the
+ * facts that pass {@link TypedExtractionFactSchema} validation;
+ * silently drops the rest. IDs are sequential post-drop indices to
+ * keep the output array contiguously addressable.
+ */
+function extractFactsFromContainer(candidates, sessionId) {
+    const facts = [];
+    for (const candidate of candidates) {
+        const result = TypedExtractionFactSchema.safeParse(candidate);
+        if (!result.success)
+            continue;
+        const f = result.data;
+        facts.push({
+            id: `${sessionId}-fact-${facts.length}`,
             bank: f.bank,
             text: f.text,
             embedding: [],
@@ -60,8 +184,9 @@ export class TypedNetworkObserver {
             reasoningMarkers: f.reasoning_markers,
             entities: f.entities,
             confidence: f.confidence,
-        }));
+        });
     }
+    return facts;
 }
 /**
  * Strip leading/trailing markdown code fences. Tolerates triple-backtick

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.js.map

@@ -1 +1 @@
-{"version":3,"file":"TypedNetworkObserver.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AA+BxC;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAK/B,YAAY,OAAoC;QAC9C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;QAC3C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,SAAiB;QAClD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAChC,MAAM,EAAE,8BAA8B;YACtC,IAAI,EAAE,yBAAyB,CAAC,WAAW,CAAC;YAC5C,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,+DAA+D;QAC/D,oEAAoE;QACpE,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACnC,EAAE,EAAE,GAAG,SAAS,SAAS,GAAG,EAAE;YAC9B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,SAAS,EAAE,EAAE;YACb,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,gBAAgB,EAAE,CAAC,CAAC,iBAAiB;YACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,UAAU,EAAE,CAAC,CAAC,UAAU;SACzB,CAAC,CAAC,CAAC;IACN,CAAC;CACF;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,CAAS;IAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/C,sFAAsF;IACtF,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;IAClE,OAAO,WAAW,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"TypedNetworkObserver.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"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"}

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.d.ts

@@ -8,59 +8,92 @@
  * schema's snake_case shape to the camelCase TypedFact at construction
  * time.
  *
+ * **Tolerance design (Phase 4c smoke fix):** the schema accepts the
+ * common deviations gpt-5-mini emits at scale, rather than throwing on
+ * any deviation:
+ *
+ * - `bank` is preprocessed to uppercase before enum validation. The
+ *   prompt asks for uppercase; if the model emits lowercase, the
+ *   coercion recovers the fact instead of dropping it.
+ * - `temporal.mention` is optional and defaults to empty string. The
+ *   model sometimes omits it when it cannot infer a mention timestamp.
+ *   Downstream {@link rankByTemporalOverlap} already handles empty
+ *   mentions gracefully (falls back to interval endpoints).
+ * - `temporal` itself defaults to `{mention: ''}`. The model sometimes
+ *   omits the temporal block entirely on non-temporal facts.
+ * - `participants`, `reasoning_markers`, `entities` default to `[]`.
+ *   The model frequently emits the fact without these keys when no
+ *   participants/entities/markers apply.
+ *
+ * Per-fact failures (text below minimum length, bank not in
+ * WORLD/EXPERIENCE/OPINION/OBSERVATION after uppercase coercion,
+ * confidence outside [0, 1]) still cause the INDIVIDUAL fact to drop.
+ * The {@link TypedNetworkObserver} validates
+ * facts one by one (`safeParse` per fact) and keeps the valid ones.
+ *
  * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-schema
  */
 import { z } from 'zod';
 /**
  * Schema for one extracted fact, matching the LLM's expected output.
- * `confidence` defaults to 1.0 when missing — the schema permits
- * omission for non-Opinion facts where the value is structurally 1.0.
+ *
+ * Defaults applied when the LLM omits fields:
+ * - `temporal.mention`: `''` (downstream tolerates empty mention)
+ * - `participants`: `[]`
+ * - `reasoning_markers`: `[]`
+ * - `entities`: `[]`
+ * - `confidence`: `1.0`
+ *
+ * `bank` is uppercase-coerced before enum validation so a lowercase
+ * model output (e.g. `'world'`) passes as `'WORLD'`.
  */
 export declare const TypedExtractionFactSchema: z.ZodObject<{
     text: z.ZodString;
-    bank: z.ZodEnum<{
+    bank: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
         WORLD: "WORLD";
         EXPERIENCE: "EXPERIENCE";
         OPINION: "OPINION";
         OBSERVATION: "OBSERVATION";
-    }>;
-    temporal: z.ZodObject<{
+    }>>;
+    temporal: z.ZodDefault<z.ZodObject<{
         start: z.ZodOptional<z.ZodString>;
         end: z.ZodOptional<z.ZodString>;
-        mention: z.ZodString;
-    }, z.core.$strip>;
-    participants: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        role: z.ZodString;
+        mention: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     }, z.core.$strip>>;
-    reasoning_markers: z.ZodArray<z.ZodString>;
-    entities: z.ZodArray<z.ZodString>;
+    participants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+    reasoning_markers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    entities: z.ZodDefault<z.ZodArray<z.ZodString>>;
     confidence: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /**
  * Top-level schema. Wraps the fact array under a `facts` key so the
- * LLM has a stable structural anchor to emit against.
+ * LLM has a stable structural anchor to emit against. The
+ * {@link TypedNetworkObserver} additionally tolerates a top-level
+ * array (no `facts` key) by auto-wrapping it before this schema runs.
  */
 export declare const TypedExtractionSchema: z.ZodObject<{
     facts: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
-        bank: z.ZodEnum<{
+        bank: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
             WORLD: "WORLD";
             EXPERIENCE: "EXPERIENCE";
             OPINION: "OPINION";
             OBSERVATION: "OBSERVATION";
-        }>;
-        temporal: z.ZodObject<{
+        }>>;
+        temporal: z.ZodDefault<z.ZodObject<{
             start: z.ZodOptional<z.ZodString>;
             end: z.ZodOptional<z.ZodString>;
-            mention: z.ZodString;
-        }, z.core.$strip>;
-        participants: z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            role: z.ZodString;
+            mention: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         }, z.core.$strip>>;
-        reasoning_markers: z.ZodArray<z.ZodString>;
-        entities: z.ZodArray<z.ZodString>;
+        participants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+        reasoning_markers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        entities: z.ZodDefault<z.ZodArray<z.ZodString>>;
         confidence: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction-schema.d.ts","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;iBAcpC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;iBAEhC,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"extraction-schema.d.ts","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;iBAwBpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;iBAEhC,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.js

@@ -8,30 +8,70 @@
  * schema's snake_case shape to the camelCase TypedFact at construction
  * time.
  *
+ * **Tolerance design (Phase 4c smoke fix):** the schema accepts the
+ * common deviations gpt-5-mini emits at scale, rather than throwing on
+ * any deviation:
+ *
+ * - `bank` is preprocessed to uppercase before enum validation. The
+ *   prompt asks for uppercase; if the model emits lowercase, the
+ *   coercion recovers the fact instead of dropping it.
+ * - `temporal.mention` is optional and defaults to empty string. The
+ *   model sometimes omits it when it cannot infer a mention timestamp.
+ *   Downstream {@link rankByTemporalOverlap} already handles empty
+ *   mentions gracefully (falls back to interval endpoints).
+ * - `temporal` itself defaults to `{mention: ''}`. The model sometimes
+ *   omits the temporal block entirely on non-temporal facts.
+ * - `participants`, `reasoning_markers`, `entities` default to `[]`.
+ *   The model frequently emits the fact without these keys when no
+ *   participants/entities/markers apply.
+ *
+ * Per-fact failures (text below minimum length, bank not in
+ * WORLD/EXPERIENCE/OPINION/OBSERVATION after uppercase coercion,
+ * confidence outside [0, 1]) still cause the INDIVIDUAL fact to drop.
+ * The {@link TypedNetworkObserver} validates
+ * facts one by one (`safeParse` per fact) and keeps the valid ones.
+ *
  * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-schema
  */
 import { z } from 'zod';
 /**
  * Schema for one extracted fact, matching the LLM's expected output.
- * `confidence` defaults to 1.0 when missing — the schema permits
- * omission for non-Opinion facts where the value is structurally 1.0.
+ *
+ * Defaults applied when the LLM omits fields:
+ * - `temporal.mention`: `''` (downstream tolerates empty mention)
+ * - `participants`: `[]`
+ * - `reasoning_markers`: `[]`
+ * - `entities`: `[]`
+ * - `confidence`: `1.0`
+ *
+ * `bank` is uppercase-coerced before enum validation so a lowercase
+ * model output (e.g. `'world'`) passes as `'WORLD'`.
  */
 export const TypedExtractionFactSchema = z.object({
     text: z.string().min(1),
-    bank: z.enum(['WORLD', 'EXPERIENCE', 'OPINION', 'OBSERVATION']),
-    temporal: z.object({
+    bank: z.preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['WORLD', 'EXPERIENCE', 'OPINION', 'OBSERVATION'])),
+    temporal: z
+        .object({
         start: z.string().optional(),
         end: z.string().optional(),
-        mention: z.string(),
-    }),
-    participants: z.array(z.object({ name: z.string(), role: z.string() })),
-    reasoning_markers: z.array(z.string()),
-    entities: z.array(z.string()),
+        mention: z.string().optional().default(''),
+    })
+        .default({ mention: '' }),
+    participants: z
+        .array(z.object({
+        name: z.string(),
+        role: z.string().default(''),
+    }))
+        .default([]),
+    reasoning_markers: z.array(z.string()).default([]),
+    entities: z.array(z.string()).default([]),
     confidence: z.number().min(0).max(1).default(1.0),
 });
 /**
  * Top-level schema. Wraps the fact array under a `facts` key so the
- * LLM has a stable structural anchor to emit against.
+ * LLM has a stable structural anchor to emit against. The
+ * {@link TypedNetworkObserver} additionally tolerates a top-level
+ * array (no `facts` key) by auto-wrapping it before this schema runs.
  */
 export const TypedExtractionSchema = z.object({
     facts: z.array(TypedExtractionFactSchema),

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"extraction-schema.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAC/D,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;KACpB,CAAC;IACF,YAAY,EAAE,CAAC,CAAC,KAAK,CACnB,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CACjD;IACD,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACtC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;CAClD,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;CAC1C,CAAC,CAAC"}
+{"version":3,"file":"extraction-schema.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,UAAU,CAChB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EACpD,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAC1D;IACD,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC;QACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;KAC3C,CAAC;SACD,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC3B,YAAY,EAAE,CAAC;SACZ,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;KAC7B,CAAC,CACH;SACA,OAAO,CAAC,EAAE,CAAC;IACd,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAClD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;CAClD,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;CAC1C,CAAC,CAAC"}