@hviana/sema 0.1.5 → 0.1.7

package/AGENTS.md

@@ -44,7 +44,7 @@ store.ts             AbstractStore: ALL domain logic of the DAG store
 store-sqlite.ts      the one concrete backend (thin SQL wrappers)
 geometry.ts + vec/alphabet/sema
                      vectors, the fold, and every derived threshold
-derive/ · alu/ · rabitq-hnsw/
+derive/ · alu/ · rabitq-ivf/
                      firewalled sublibraries with their own READMEs and tests
 ```
 
@@ -80,7 +80,8 @@ D, the perception window W, or the corpus size N, defined once in
 `src/geometry.ts` (`mergeThreshold`, `identityBar`, `reachThreshold`,
 `significanceBar`, `estimatorNoise`, `conceptThreshold`, `consensusFloor`,
 `dominates`, …). `src/config.ts` holds **capacities and budgets only** (cache
-byte budgets, batch sizes, HNSW parameters, query k, ALU precision, the seed).
+byte budgets, batch sizes, vector-index parameters, query k, ALU precision, the
+seed).
 
 _Follow it:_ if you are about to add a tunable cutoff to config, derive it in
 `geometry.ts` instead. A threshold knob is a design bug here — one was already
@@ -360,7 +361,7 @@ story of the fix.
 | Post-grounding (reason, fuse, articulate)     | `src/mind/reasoning.ts`, `src/mind/articulation.ts`                    |
 | Rationale / trace                             | `src/mind/rationale.ts`, `src/mind/trace.ts`                           |
 | Extension host types                          | `src/extension.ts`                                                     |
-| Sublibraries (own READMEs, own tests)         | `src/derive/`, `src/alu/`, `src/rabitq-hnsw/`                          |
+| Sublibraries (own READMEs, own tests)         | `src/derive/`, `src/alu/`, `src/rabitq-ivf/`                           |
 
 Mind functions are **free functions over `MindContext`** (`mind/types.ts`), not
 methods — `mind.ts` is a thin assembly that implements the context and
@@ -453,9 +454,9 @@ against the built `dist/` (`npm test`; one suite:
   silence). A "simplification" that fails an existing test is wrong until you
   can argue the _test_ is wrong — several guards exist precisely because a
   plausible simplification once failed a dozen suites.
-- Sublibraries test themselves (`src/{alu,derive,rabitq-hnsw}/test/`) with zero
+- Sublibraries test themselves (`src/{alu,derive,rabitq-ivf}/test/`) with zero
   Sema dependency. Keep it so.
-- Performance claims are tested (the rabitq-hnsw benchmark asserts sub-linear
+- Performance claims are tested (the rabitq-ivf benchmark asserts sub-linear
   scaling and compression). Changing index behaviour means running it.
 
 ---

package/CITATION.cff

@@ -0,0 +1,49 @@
+cff-version: 1.2.0
+message: >-
+  If you use Sema in academic work, please cite the accompanying preprint.
+  For software-specific references, you may also cite this repository.
+title: "Sema"
+abstract: >-
+  Sema is a non-parametric, instance-based reasoning system built as a
+  Vector Symbolic Architecture over content-addressable memory, with
+  inference performed by weighted automated deduction.
+type: software
+authors:
+  - family-names: "Viana"
+    given-names: "Henrique Emanoel"
+    orcid: "https://orcid.org/0000-0002-7119-5867"
+    affiliation: "NONE"
+repository-code: "https://github.com/hviana/sema"
+url: "https://github.com/hviana/sema"
+license: "PolyForm-Noncommercial-1.0.0"
+version: "0.1.0"
+date-released: "2026-07-16"
+keywords:
+  - artificial intelligence
+  - cognitive architecture
+  - non-parametric reasoning
+  - instance-based reasoning
+  - vector symbolic architecture
+  - hyperdimensional computing
+  - content-addressable memory
+  - weighted automated deduction
+  - symbolic reasoning
+  - explainable artificial intelligence
+  - TypeScript
+
+preferred-citation:
+  type: article
+  title: "Sema: Reasoning by Example over a Vector-Symbolic Memory"
+  authors:
+    - family-names: "Viana"
+      given-names: "Henrique Emanoel"
+      orcid: "https://orcid.org/0000-0002-7119-5867"
+      affiliation: "NONE"
+  year: 2026
+  month: 7
+  day: 16
+  version: "0.1.0"
+  doi: "10.5281/zenodo.21385723"
+  url: "https://doi.org/10.5281/zenodo.21385723"
+  publisher:
+    name: "Zenodo"

package/HOW_IT_WORKS.md

@@ -575,11 +575,13 @@ controlled amount of recall for sub-linear query time.
 
 Sema uses two established techniques in combination:
 
-- **HNSW** — Hierarchical Navigable Small World graphs (Malkov & Yashunin 2018).
-  Vectors are connected into a multi-layer proximity graph; a query descends
-  greedily from a sparse top layer to a dense bottom layer, examining only a
-  logarithmic-ish neighbourhood of the collection. Empirically the work grows
-  around N^0.3 in Sema's configuration — decisively sub-linear.
+- **IVF (inverted-file partitioning)** — the collection is split into clusters,
+  each with a binary pivot code; a query ranks the pivots and scans only the few
+  nearest clusters. Cluster size is bounded (an oversized cluster
+  deterministically splits in two), so the work per query is set by the number
+  of probes, not by the collection — decisively sub-linear. Inserting is
+  route-and-append: one RAM scan of the pivot table, no graph maintenance, so
+  ingestion cost stays flat as the collection grows.
 - **RaBitQ 1-bit quantization** (Gao & Long 2024). Each stored vector is
   randomly rotated and reduced to one _sign bit_ per dimension — a 32×
   compression — with an unbiased, theoretically-grounded estimator of the
@@ -663,7 +665,7 @@ RELATIONS             │  continuation edges (what follows what)  │
 (distributional, §4)  │  halos (what company each node keeps)    │
                       ├─────────────────────────────────────────┤
 INDEXES               │  gist index + halo index                 │
-(ANN, §6)             │  (HNSW over 1-bit RaBitQ codes)          │
+(ANN, §6)             │  (IVF over 1-bit RaBitQ codes)           │
                       └──────────────────┬──────────────────────┘
                                          │ axioms & rule candidates
                                          ▼
@@ -1696,7 +1698,7 @@ requirements:
 
 - **ANN index: 1-bit RaBitQ, irreversible.** The same halo vector, projected
   through a random rotation and reduced to one sign bit per dimension (32×
-  compression), serves as a search code in the HNSW index. This code is _never_
+  compression), serves as a search code in the IVF index. This code is _never_
   decoded back — it only answers "which halos are near this query?" The
   estimator is unbiased (expected cosine is recoverable from the bit count), so
   ranking quality is preserved despite the loss of reversibility.
@@ -4124,8 +4126,8 @@ terms of art borrowed from the literature.
   §4.
 - **Hash-consing** — constructing structures modulo equality so equal
   substructures are shared. §3.2.
-- **HNSW** — Hierarchical Navigable Small World graph; sub-linear ANN search
-  (Malkov & Yashunin 2018). §6.1.
+- **IVF** — inverted-file partitioned ANN index; bounded-probe sub-linear search
+  over clustered codes. §6.1.
 - **Hilbert curve** — the locality-preserving space-filling curve used to
   linearize grids. §6.3.
 - **Hyperdimensional computing** — Kanerva's (2009) umbrella term for computing
@@ -4193,9 +4195,6 @@ Foundations cited in this document, in alphabetical order:
   Processing Letters 6(1), 1–5.
 - Kolodner, J. L. (1992). _An Introduction to Case-Based Reasoning._ Artificial
   Intelligence Review 6, 3–34.
-- Malkov, Y. A. & Yashunin, D. A. (2018). _Efficient and Robust Approximate
-  Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs._ IEEE
-  TPAMI 42(4), 824–836.
 - Merkle, R. C. (1987). _A Digital Signature Based on a Conventional Encryption
   Function._ Proc. CRYPTO.
 - Plate, T. A. (1995). _Holographic Reduced Representations._ IEEE Transactions

package/README.md

@@ -1,3 +1,5 @@
+[![npm version](https://img.shields.io/npm/v/@hviana/sema.svg)](https://www.npmjs.com/package/@hviana/sema)
+
 <div align="center">
 
 ```
@@ -223,11 +225,11 @@ Pablo Picasso co-founded the Cubist movement
 Sema is composed of three self-contained, independently documented engines. They
 are fully decoupled — Sema reaches them only through interfaces.
 
-| Engine            | What it solves                                                                             | Result                                                                                                                       |
-| :---------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
-| **`rabitq-hnsw`** | _"Given a vector, find the nodes whose gist resonates with it — fast, at scale, on disk."_ | HNSW over 1-bit RaBitQ codes · ~32× compression · bounded RAM · sub-linear queries                                           |
-| **`derive`**      | _"Explore a huge implicit space of derivations and return the single lightest one."_       | adapted A\*LD (adapted A\* Lightest Derivation) over a weighted deduction hypergraph — Sema's thinking _is_ one call to this |
-| **`alu`**         | _"Compute, exactly and symbolically, the things that are rules, not facts."_               | A tiny irreducible kernel from which arithmetic, logic, and n-dimensional computation are derived                            |
+| Engine           | What it solves                                                                             | Result                                                                                                                       |
+| :--------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| **`rabitq-ivf`** | _"Given a vector, find the nodes whose gist resonates with it — fast, at scale, on disk."_ | Partitioned (IVF) index over 1-bit RaBitQ codes · ~32× compression · bounded RAM · flat inserts, bounded queries             |
+| **`derive`**     | _"Explore a huge implicit space of derivations and return the single lightest one."_       | adapted A\*LD (adapted A\* Lightest Derivation) over a weighted deduction hypergraph — Sema's thinking _is_ one call to this |
+| **`alu`**        | _"Compute, exactly and symbolically, the things that are rules, not facts."_               | A tiny irreducible kernel from which arithmetic, logic, and n-dimensional computation are derived                            |
 
 ---
 

package/dist/example/demo.js

@@ -10,30 +10,30 @@
 import { Mind } from "../src/index.js";
 import { SQliteStore } from "../src/store-sqlite.js";
 async function main() {
-  const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
-  const ask = async (q) => (await mind.respondText(q)).trim();
-  // ── Jot down what we know. Each line is just (context → what follows). ──
-  await mind.ingest([
-    // One relation, shown three times — a pattern taught purely by example:
-    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
-    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
-    [
-      "The Night Watch was painted by Rembrandt van Rijn.",
-      "Rembrandt van Rijn",
-    ],
-    // One stray fact, keyed on a name none of the examples mention:
-    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
-  ]);
-  // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
-  //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
-  //    by analogy to the three examples.
-  console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
-  // → "Pablo Picasso co-founded the Cubist movement"
-  //   …and, having found the painter, it KEEPS GOING: the name bridges into the
-  //   one fact it holds about him. The answer appears in no word of the question.
-  // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
-  console.log(await ask("a museum charges 12*4 for a family ticket"));
-  // → "48"
-  await mind.store.close();
+    const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
+    const ask = async (q) => (await mind.respondText(q)).trim();
+    // ── Jot down what we know. Each line is just (context → what follows). ──
+    await mind.ingest([
+        // One relation, shown three times — a pattern taught purely by example:
+        ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+        ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+        [
+            "The Night Watch was painted by Rembrandt van Rijn.",
+            "Rembrandt van Rijn",
+        ],
+        // One stray fact, keyed on a name none of the examples mention:
+        ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+    ]);
+    // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
+    //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
+    //    by analogy to the three examples.
+    console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
+    // → "Pablo Picasso co-founded the Cubist movement"
+    //   …and, having found the painter, it KEEPS GOING: the name bridges into the
+    //   one fact it holds about him. The answer appears in no word of the question.
+    // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
+    console.log(await ask("a museum charges 12*4 for a family ticket"));
+    // → "48"
+    await mind.store.close();
 }
 main();

package/dist/example/train_base.d.ts

@@ -1,6 +1,6 @@
 export interface Episode {
-  context: string;
-  continuation: string;
+    context: string;
+    continuation: string;
 }
 export type TrainingItem = string | Episode;
 /** Dedup + trim a concept's items: drop empty/degenerate pairs and exact
@@ -8,10 +8,10 @@ export type TrainingItem = string | Episode;
 export declare function refineItems(items: TrainingItem[]): TrainingItem[];
 /** One normalized SmolSent row. */
 export interface SmolSentRow {
-  src: string;
-  trg: string;
-  sl: string;
-  tl: string;
+    src: string;
+    trg: string;
+    sl: string;
+    tl: string;
 }
 /** Normalize a raw datasets-server row into a SmolSentRow, or null when it lacks
  *  both sides or a side is implausibly large (a dump, not a sentence). */
@@ -22,9 +22,9 @@ export declare function toSmolSentRow(row: unknown): SmolSentRow | null;
 export declare function smolSentRowToItems(row: SmolSentRow): TrainingItem[];
 /** One normalized Aya row. */
 export interface AyaRow {
-  inputs: string;
-  targets: string;
-  language: string;
+    inputs: string;
+    targets: string;
+    language: string;
 }
 /** Normalize a raw datasets-server row object into an AyaRow, or null when it
  *  lacks a usable prompt/answer or a field is implausibly large (a dump, not a
@@ -38,16 +38,16 @@ export declare function toAyaRow(row: unknown): AyaRow | null;
 export declare function ayaRowToItems(row: AyaRow): TrainingItem[];
 /** A single oasst2 message node (the fields we use; the tree nests via replies). */
 interface OasstNode {
-  role?: string;
-  text?: string;
-  rank?: number | null;
-  deleted?: boolean;
-  replies?: OasstNode[];
+    role?: string;
+    text?: string;
+    rank?: number | null;
+    deleted?: boolean;
+    replies?: OasstNode[];
 }
 /** One conversational turn extracted from a tree. */
 export interface OasstTurn {
-  role: string;
-  text: string;
+    role: string;
+    text: string;
 }
 /** Collapse a conversation tree to ONE linear path: at each node, descend into
  *  its best-ranked, non-deleted reply (rank 0 preferred; unranked sorts last).
@@ -72,13 +72,11 @@ export declare function bestOasstPath(root: OasstNode): OasstTurn[];
  *
  *  Returns [] for a conversation below the multi-turn threshold, so callers can
  *  simply skip empties. */
-export declare function oasstConversationToItems(
-  turns: OasstTurn[],
-): TrainingItem[];
+export declare function oasstConversationToItems(turns: OasstTurn[]): TrainingItem[];
 /** One normalized General-Knowledge row. */
 export interface GenKnowRow {
-  question: string;
-  answer: string;
+    question: string;
+    answer: string;
 }
 /** Normalize a raw datasets-server row into a GenKnowRow, or null when it lacks
  *  a usable question/answer or a side is implausibly large (corruption). */