@framers/agentos 0.3.1 → 0.3.3

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

@@ -0,0 +1,47 @@
+/**
+ * @file extraction-prompt.ts
+ * @description The 6-step extraction prompt for the Hindsight 4-network
+ * typed observer. The system prompt defines the six decomposition
+ * steps verbatim from Hindsight §2.3 (coreference resolution, temporal
+ * normalization, participant attribution, reasoning preservation, fact
+ * type classification, entity extraction). The user prompt frames the
+ * conversation as a single block and asks the model to emit structured
+ * JSON conforming to {@link TypedExtractionSchema}.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-prompt
+ */
+/**
+ * System prompt for the 6-step extraction. Verbatim from Hindsight
+ * §2.3 with one omission: the spec doesn't include the "do not
+ * commentate" line, but the LLM tends to drift into prose without it,
+ * which breaks JSON parsing. Included.
+ */
+export const TYPED_EXTRACTION_SYSTEM_PROMPT = `You are an information extractor for a typed memory network. Process the conversation below into structured facts.
+
+For each fact, perform these six steps:
+
+1. COREFERENCE: resolve "he/she/they/it/this/that" to the actual referent.
+2. TEMPORAL: normalize times to ISO 8601. Extract ranges as (start, end) when applicable.
+3. PARTICIPANTS: list every named participant and their role.
+4. REASONING: preserve any explicit reasoning marker (because, since, therefore, etc.) verbatim.
+5. FACT TYPE: classify into ONE of:
+   - WORLD: objective facts about the external world
+   - EXPERIENCE: biographical / first-person events
+   - OPINION: claims with confidence < 1.0
+   - OBSERVATION: preference-neutral summaries of entities
+6. ENTITIES: list every named entity (proper nouns, organizations, places, products).
+
+Output JSON matching the schema strictly. Do not add commentary.`;
+/**
+ * Build the user prompt for a single conversation block. Wraps the
+ * source text in delimiters that resist accidental inline-injection
+ * if the conversation contains JSON-looking content.
+ *
+ * @param sessionText - The conversation text to extract from. Whole
+ *   session passed as one block; the model decomposes per turn
+ *   internally.
+ */
+export function buildExtractionUserPrompt(sessionText) {
+    return `CONVERSATION:\n<<<\n${sessionText}\n>>>`;
+}
+//# sourceMappingURL=extraction-prompt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-prompt.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;;;;;;;;;;iEAemB,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB;IAC3D,OAAO,uBAAuB,WAAW,OAAO,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,71 @@
+/**
+ * @file extraction-schema.ts
+ * @description Zod schema for parsing the LLM's structured-output
+ * response in the typed-network extraction pipeline. Mirrors
+ * {@link TypedFact} fields but uses snake_case for the LLM API
+ * boundary (LLMs tend to emit snake_case more reliably than
+ * camelCase). The {@link TypedNetworkObserver} translates from this
+ * schema's snake_case shape to the camelCase TypedFact at construction
+ * time.
+ *
+ * @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.
+ */
+export declare const TypedExtractionFactSchema: z.ZodObject<{
+    text: z.ZodString;
+    bank: z.ZodEnum<{
+        WORLD: "WORLD";
+        EXPERIENCE: "EXPERIENCE";
+        OPINION: "OPINION";
+        OBSERVATION: "OBSERVATION";
+    }>;
+    temporal: 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;
+    }, z.core.$strip>>;
+    reasoning_markers: z.ZodArray<z.ZodString>;
+    entities: 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.
+ */
+export declare const TypedExtractionSchema: z.ZodObject<{
+    facts: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        bank: z.ZodEnum<{
+            WORLD: "WORLD";
+            EXPERIENCE: "EXPERIENCE";
+            OPINION: "OPINION";
+            OBSERVATION: "OBSERVATION";
+        }>;
+        temporal: 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;
+        }, z.core.$strip>>;
+        reasoning_markers: z.ZodArray<z.ZodString>;
+        entities: z.ZodArray<z.ZodString>;
+        confidence: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** TypeScript type inferred from {@link TypedExtractionSchema}. */
+export type TypedExtractionOutput = z.infer<typeof TypedExtractionSchema>;
+/** Per-fact type inferred from {@link TypedExtractionFactSchema}. */
+export type TypedExtractionFact = z.infer<typeof TypedExtractionFactSchema>;
+//# sourceMappingURL=extraction-schema.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,39 @@
+/**
+ * @file extraction-schema.ts
+ * @description Zod schema for parsing the LLM's structured-output
+ * response in the typed-network extraction pipeline. Mirrors
+ * {@link TypedFact} fields but uses snake_case for the LLM API
+ * boundary (LLMs tend to emit snake_case more reliably than
+ * camelCase). The {@link TypedNetworkObserver} translates from this
+ * schema's snake_case shape to the camelCase TypedFact at construction
+ * time.
+ *
+ * @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.
+ */
+export const TypedExtractionFactSchema = z.object({
+    text: z.string().min(1),
+    bank: 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()),
+    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.
+ */
+export const TypedExtractionSchema = z.object({
+    facts: z.array(TypedExtractionFactSchema),
+});
+//# sourceMappingURL=extraction-schema.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,123 @@
+/**
+ * @file types.ts
+ * @description Core types for the Hindsight 4-network typed observer.
+ * Each fact lives in one of four typed banks: World (objective external
+ * facts), Experience (first-person biographical), Opinion (claims with
+ * confidence < 1), Observation (preference-neutral entity summaries).
+ *
+ * The schema follows Hindsight paper Equation 1
+ * (arxiv.org/html/2512.12818v1 §2.1):
+ *
+ *   f = (u, b, t, v, τs, τe, τm, ℓ, c, x)
+ *
+ * mapped to TypeScript field names below. See spec
+ * `packages/agentos-bench/docs/specs/2026-04-26-hindsight-4network-observer-design.md`
+ * §2.1-§2.2 for the verbatim definition.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/types
+ */
+/**
+ * Bank identifier — one of four typed networks per Hindsight §2.2. The
+ * bank determines retrieval semantics: World facts compose under
+ * objective truth, Experience under first-person continuity, Opinion
+ * under belief evolution, Observation under entity descriptions.
+ */
+export declare const BANK_IDS: readonly ["WORLD", "EXPERIENCE", "OPINION", "OBSERVATION"];
+/** {@link BANK_IDS} as a TypeScript literal type. */
+export type BankId = (typeof BANK_IDS)[number];
+/**
+ * Type guard: narrows an arbitrary string to {@link BankId}. Use to
+ * validate untrusted inputs (LLM extraction output, deserialized
+ * persistence) before routing into the typed network.
+ */
+export declare function isBankId(s: string): s is BankId;
+/**
+ * Edge kind in the typed-network graph. Each kind carries a different
+ * spreading-activation multiplier μ(ℓ) per Hindsight Eq. 12 (§2.4.1).
+ *
+ * - **temporal**: connects facts that share an occurrence-interval
+ *   overlap. Weight derived from `exp(−Δt / σt)`.
+ * - **semantic**: connects facts whose embeddings exceed a cosine
+ *   threshold θs.
+ * - **entity**: bidirectional link between facts mentioning the same
+ *   named entity. Weight 1.0.
+ * - **causal**: explicit reasoning marker linking premise → conclusion
+ *   facts. LLM-extracted at observation time; weight 1.0.
+ */
+export declare const EDGE_KINDS: readonly ["temporal", "semantic", "entity", "causal"];
+/** {@link EDGE_KINDS} as a TypeScript literal type. */
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+/**
+ * Single named participant in a fact (e.g. "Alice", "the deployment
+ * server"). Roles match the participant's grammatical / conversational
+ * function — speaker, addressee, subject, object, etc.
+ */
+export interface Participant {
+    /** Resolved name (after coreference). */
+    name: string;
+    /** Conversational or semantic role. */
+    role: string;
+}
+/**
+ * Temporal envelope per Hindsight Eq. 1 fields τs, τe, τm. ISO 8601
+ * strings; missing `start` / `end` indicates an instant rather than an
+ * interval. `mention` is always populated — it's the timestamp at
+ * which the fact was authored.
+ */
+export interface FactTemporal {
+    /** Interval start (inclusive). ISO 8601. Optional for instant facts. */
+    start?: string;
+    /** Interval end (inclusive). ISO 8601. Optional for instant facts. */
+    end?: string;
+    /** Mention timestamp — when the fact was first authored. ISO 8601. */
+    mention: string;
+}
+/**
+ * A typed fact in the Hindsight memory schema. Carries narrative text,
+ * embedding, temporal envelope, participants, reasoning markers,
+ * extracted entities, and a confidence score in [0, 1]. Confidence
+ * defaults to 1.0 for World/Experience/Observation facts; the Opinion
+ * bank stores `(text, confidence, timestamp)` tuples per §2.2.
+ */
+export interface TypedFact {
+    /** Stable unique identifier. Convention: `<sessionId>-fact-<index>`. */
+    id: string;
+    /** Bank assignment from the LLM extractor's fact-type classification. */
+    bank: BankId;
+    /** Narrative text of the fact, post-coreference resolution. */
+    text: string;
+    /** Embedding vector. Empty until {@link IEmbeddingManager.embed} populates. */
+    embedding: number[];
+    /** Temporal envelope (occurrence interval + mention timestamp). */
+    temporal: FactTemporal;
+    /** Named participants and their roles. */
+    participants: Participant[];
+    /**
+     * Verbatim reasoning markers preserved from the source content
+     * ("because", "since", "therefore", etc.). Used downstream to
+     * extract causal edges.
+     */
+    reasoningMarkers: string[];
+    /** Named entities mentioned in the fact (proper nouns, products, places). */
+    entities: string[];
+    /** Confidence ∈ [0, 1]. 1.0 for non-Opinion facts; LLM-output for Opinion. */
+    confidence: number;
+    /** Optional auxiliary metadata (source ID, conversation turn index, etc.). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Typed edge between two facts in the network graph. Direction matters
+ * for causal edges (premise → conclusion); other kinds are
+ * bidirectional and stored as a pair of edges.
+ */
+export interface TypedEdge {
+    /** Source fact ID. */
+    fromFactId: string;
+    /** Target fact ID. */
+    toFactId: string;
+    /** Edge kind — drives μ(ℓ) multiplier in spreading activation. */
+    kind: EdgeKind;
+    /** Edge weight. Composed with decay δ and μ(ℓ) at activation time. */
+    weight: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,4DAA6D,CAAC;AAEnF,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,uDAAwD,CAAC;AAChF,uDAAuD;AACvD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mEAAmE;IACnE,QAAQ,EAAE,YAAY,CAAC;IACvB,0CAA0C;IAC1C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,QAAQ,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB"}

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

@@ -0,0 +1,48 @@
+/**
+ * @file types.ts
+ * @description Core types for the Hindsight 4-network typed observer.
+ * Each fact lives in one of four typed banks: World (objective external
+ * facts), Experience (first-person biographical), Opinion (claims with
+ * confidence < 1), Observation (preference-neutral entity summaries).
+ *
+ * The schema follows Hindsight paper Equation 1
+ * (arxiv.org/html/2512.12818v1 §2.1):
+ *
+ *   f = (u, b, t, v, τs, τe, τm, ℓ, c, x)
+ *
+ * mapped to TypeScript field names below. See spec
+ * `packages/agentos-bench/docs/specs/2026-04-26-hindsight-4network-observer-design.md`
+ * §2.1-§2.2 for the verbatim definition.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/types
+ */
+/**
+ * Bank identifier — one of four typed networks per Hindsight §2.2. The
+ * bank determines retrieval semantics: World facts compose under
+ * objective truth, Experience under first-person continuity, Opinion
+ * under belief evolution, Observation under entity descriptions.
+ */
+export const BANK_IDS = ['WORLD', 'EXPERIENCE', 'OPINION', 'OBSERVATION'];
+/**
+ * Type guard: narrows an arbitrary string to {@link BankId}. Use to
+ * validate untrusted inputs (LLM extraction output, deserialized
+ * persistence) before routing into the typed network.
+ */
+export function isBankId(s) {
+    return BANK_IDS.includes(s);
+}
+/**
+ * Edge kind in the typed-network graph. Each kind carries a different
+ * spreading-activation multiplier μ(ℓ) per Hindsight Eq. 12 (§2.4.1).
+ *
+ * - **temporal**: connects facts that share an occurrence-interval
+ *   overlap. Weight derived from `exp(−Δt / σt)`.
+ * - **semantic**: connects facts whose embeddings exceed a cosine
+ *   threshold θs.
+ * - **entity**: bidirectional link between facts mentioning the same
+ *   named entity. Weight 1.0.
+ * - **causal**: explicit reasoning marker linking premise → conclusion
+ *   facts. LLM-extracted at observation time; weight 1.0.
+ */
+export const EDGE_KINDS = ['temporal', 'semantic', 'entity', 'causal'];
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAU,CAAC;AAKnF;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAQ,QAA8B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",