@persql/context 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @persql/context/core — zero-runtime-dependency engine.
+ *
+ * Schema DDL, SQL builders, and the extraction/compaction contracts shared by
+ * the `@persql/context` SDK (client-side, over `@persql/sdk`) and the hosted
+ * PerSQL Context worker (server-side, over `@persql/ai`). Keeping both sides on
+ * the same builders means client-recall and server-recall can never drift.
+ *
+ * Retrieval is lexical: FTS5 with the porter stemmer, BM25-ranked. No vectors.
+ */
+declare const SCHEMA_VERSION = 1;
+declare const TABLE_PREFIX = "ctx_";
+type MemoryKind = "fact" | "episode" | "artifact";
+interface MemoryRow {
+    id: string;
+    kind: MemoryKind;
+    topic: string | null;
+    body: string;
+    tags: string | null;
+    source: string | null;
+    createdAt: number;
+    supersededBy: string | null;
+}
+interface Entity {
+    id: string;
+    name: string;
+    kind: string | null;
+    body: string | null;
+    createdAt: number;
+}
+interface Edge {
+    id: string;
+    src: string;
+    rel: string;
+    dst: string;
+    source: string | null;
+    createdAt: number;
+}
+interface RememberInput {
+    body: string;
+    topic?: string;
+    kind?: MemoryKind;
+    tags?: string[] | string;
+    source?: string;
+    supersedes?: string | string[];
+    id?: string;
+}
+interface EntityInput {
+    name: string;
+    kind?: string;
+    body?: string;
+    id?: string;
+}
+interface EdgeInput {
+    src: string;
+    rel: string;
+    dst: string;
+    source?: string;
+}
+interface RecallOptions {
+    limit?: number;
+    kind?: MemoryKind;
+    operator?: "or" | "and";
+    mode?: "terms" | "raw";
+    sinceMs?: number;
+    withinDays?: number;
+    includeSuperseded?: boolean;
+}
+interface ListOptions {
+    limit?: number;
+    kind?: MemoryKind;
+    includeSuperseded?: boolean;
+}
+/** The shape an extractor (LLM or the hosted worker) returns from raw text. */
+interface ExtractedContext {
+    facts?: Array<{
+        body: string;
+        topic?: string;
+        tags?: string[];
+        kind?: MemoryKind;
+    }>;
+    entities?: EntityInput[];
+    edges?: EdgeInput[];
+}
+interface SqlStatement {
+    sql: string;
+    params: unknown[];
+}
+declare const SCHEMA_SQL: string[];
+declare function buildInit(): SqlStatement[];
+declare function normalizeTags(tags?: string[] | string | null): string | null;
+/**
+ * Turn arbitrary user text into a safe FTS5 MATCH expression. `terms` mode
+ * (default) extracts word tokens, drops bare boolean operators, and ORs the
+ * rest as quoted terms — so a caller can paste "invoice OR billing" or just
+ * "invoice billing" and neither crashes the parser nor injects FTS syntax.
+ * `raw` mode passes a hand-written FTS expression through untouched.
+ */
+declare function toFtsQuery(input: string, opts?: {
+    operator?: "or" | "and";
+    mode?: "terms" | "raw";
+}): string | null;
+/** Deterministic id for an entity, keyed on its name (case-insensitive). */
+declare function entityId(name: string): string;
+declare function buildRemember(input: RememberInput, now: number, id: string): SqlStatement;
+declare function buildSupersede(oldId: string, newId: string): SqlStatement;
+declare function buildForget(id: string): SqlStatement;
+declare function buildGet(id: string): SqlStatement;
+declare function buildRecall(query: string, opts?: RecallOptions): SqlStatement | null;
+declare function buildRecent(opts?: ListOptions): SqlStatement;
+declare function buildByTag(tag: string, opts?: ListOptions): SqlStatement;
+declare function buildStats(): SqlStatement;
+declare function buildUpsertEntity(e: EntityInput, now: number): SqlStatement;
+declare function buildUpsertEdge(e: EdgeInput, now: number): SqlStatement;
+/** Entities reachable from a seed within `depth` hops (seed excluded). */
+declare function buildNeighborEntities(seedId: string, depth: number, limit: number): SqlStatement;
+declare function buildEdgesAmong(ids: string[]): SqlStatement;
+declare const EXTRACTION_SYSTEM_PROMPT = "You extract durable, shareable context from raw text for a team of AI agents that will read it later by keyword.\n\nReturn JSON: { \"facts\": [...], \"entities\": [...], \"edges\": [...] }.\n- facts: atomic, self-contained statements worth remembering across sessions \u2014 decisions, conventions, constraints, identifiers, preferences. Each: { \"body\": string, \"topic\"?: string, \"tags\"?: string[] }. Prefer specific and stable over transient chatter.\n- entities: named things \u2014 services, people, tables, repos, concepts. Each: { \"name\": string, \"kind\"?: string, \"body\"?: short description }.\n- edges: relationships between entities, referencing entity names. Each: { \"src\": name, \"rel\": string, \"dst\": name }.\n\nBe conservative: omit anything ephemeral or low-value. Use lowercase tags. If nothing is worth keeping, return empty arrays.";
+declare function buildExtractionMessages(raw: string, opts?: {
+    hint?: string;
+}): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+declare const EXTRACTION_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly facts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly body: {
+                        readonly type: "string";
+                    };
+                    readonly topic: {
+                        readonly type: "string";
+                    };
+                    readonly tags: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["body"];
+            };
+        };
+        readonly entities: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["name"];
+            };
+        };
+        readonly edges: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly src: {
+                        readonly type: "string";
+                    };
+                    readonly rel: {
+                        readonly type: "string";
+                    };
+                    readonly dst: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["src", "rel", "dst"];
+            };
+        };
+    };
+};
+
+export { EXTRACTION_JSON_SCHEMA, EXTRACTION_SYSTEM_PROMPT, type Edge, type EdgeInput, type Entity, type EntityInput, type ExtractedContext, type ListOptions, type MemoryKind, type MemoryRow, type RecallOptions, type RememberInput, SCHEMA_SQL, SCHEMA_VERSION, type SqlStatement, TABLE_PREFIX, buildByTag, buildEdgesAmong, buildExtractionMessages, buildForget, buildGet, buildInit, buildNeighborEntities, buildRecall, buildRecent, buildRemember, buildStats, buildSupersede, buildUpsertEdge, buildUpsertEntity, entityId, normalizeTags, toFtsQuery };

package/dist/core.js

@@ -0,0 +1,49 @@
+import {
+  EXTRACTION_JSON_SCHEMA,
+  EXTRACTION_SYSTEM_PROMPT,
+  SCHEMA_SQL,
+  SCHEMA_VERSION,
+  TABLE_PREFIX,
+  buildByTag,
+  buildEdgesAmong,
+  buildExtractionMessages,
+  buildForget,
+  buildGet,
+  buildInit,
+  buildNeighborEntities,
+  buildRecall,
+  buildRecent,
+  buildRemember,
+  buildStats,
+  buildSupersede,
+  buildUpsertEdge,
+  buildUpsertEntity,
+  entityId,
+  normalizeTags,
+  toFtsQuery
+} from "./chunk-RMG66FDI.js";
+export {
+  EXTRACTION_JSON_SCHEMA,
+  EXTRACTION_SYSTEM_PROMPT,
+  SCHEMA_SQL,
+  SCHEMA_VERSION,
+  TABLE_PREFIX,
+  buildByTag,
+  buildEdgesAmong,
+  buildExtractionMessages,
+  buildForget,
+  buildGet,
+  buildInit,
+  buildNeighborEntities,
+  buildRecall,
+  buildRecent,
+  buildRemember,
+  buildStats,
+  buildSupersede,
+  buildUpsertEdge,
+  buildUpsertEntity,
+  entityId,
+  normalizeTags,
+  toFtsQuery
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}