@msm-core/brain

Production AI brain for Arabic and English agents. HDC perception gate + native-language Qwen reasoning. Fast path first — most requests never touch an LLM.

How it works

User input
    │
    ▼
HDC Perception (<1ms)
    │
    ├─ confidence ≥ 0.85 → skip  → return instantly, no LLM
    ├─ confidence ≥ 0.45 → assist → LLM call with domain hint
    └─ confidence < 0.45 → full  → full LLM call

The HDC layer is a 10,000-dimensional hypervector space. It classifies domain in under 1ms using pure math — no neural network, no GPU. The LLM (Qwen 2.5 1.5B via Ollama) only runs when the HDC is uncertain. In a well-seeded domain, 60–70% of requests skip the LLM entirely.

Install

npm install @msm-core/brain

Requires: Node 18+, @msm-core/cst peer, and Ollama running locally for LLM reasoning.

Quick start

import { createBrain } from "@msm-core/brain";

const brain = createBrain({
  provider: "ollama", // or 'dummy' for tests
  autoSeed: true, // seed with 144 built-in EN+AR examples
  gate: {
    skipThreshold: 0.85, // skip LLM if HDC confidence ≥ 85%
    assistThreshold: 0.45, // hint-inject if ≥ 45%
  },
  ollama: {
    baseUrl: "http://localhost:11434",
    model: "qwen2.5:1.5b",
  },
});

// Use with @msm-core/mini loop
const payload = await brain.run({
  raw: "أصلح الخطأ في الكود",
  system_context: "You are a helpful assistant.",
  history: [],
  tools: [],
});

console.log(payload.perception);
// { field: 'tech', confidence: 0.91, gate: 'skip', lang: 'ar', latency_ms: 1 }

Language support

Brain is natively bilingual. No translation pipeline — Arabic goes in, Arabic comes out.

| Input | HDC gate | LLM | | ------- | --------------------------- | ------------------------- | | Arabic | runs on Arabic tokens | Qwen responds in Arabic | | English | runs on English tokens | Qwen responds in English | | Mixed | auto-detected by char ratio | matches detected language |

Built-in seed corpus

autoSeed: true loads 144 examples across 6 fields (12 EN + 12 AR each):

| Field | Examples | | --------- | ----------------------------------------- | | tech | "fix the bug", "أصلح الخطأ في الكود" | | health | "I have a headache", "أعاني من صداع شديد" | | weather | "will it rain today", "هل ستمطر اليوم" | | food | "how to make pasta", "وصفة كبسة الدجاج" | | trade | "buy Apple shares", "ما سعر الذهب اليوم" | | move | "book a taxi", "احجز تاكسي إلى الفندق" |

For production, teach the brain your domain before deploying:

import { createBrain, HDVEncoder, HDCAgent, seedBrain } from "@msm-core/brain";

const encoder = new HDVEncoder();
const agent = new HDCAgent();

// Observe domain examples (your data)
for (const phrase of myDomainPhrases) {
  const { tokens } = tokenize(phrase);
  const [hv] = encoder.encode(tokens);
  agent.observe(hv, "my_field");
}
agent.calibrate();

API

createBrain(config?)

Returns a Brain compatible with @msm-core/mini.

interface BrainConfig {
  provider?: "ollama" | "dummy"; // default: 'ollama'
  autoSeed?: boolean; // default: true
  gate?: {
    skipThreshold?: number; // default: 0.85
    assistThreshold?: number; // default: 0.45
  };
  ollama?: {
    baseUrl?: string; // default: http://localhost:11434
    model?: string; // default: qwen2.5:1.5b
    timeoutMs?: number; // default: 30000
  };
}

BrainPayload

The returned payload is compatible with @msm-core/mini's BrainPayload and adds a perception field:

payload.orchestration; // { action, confidence, reasoning, ... }
payload.generation; // { response_text, response_text_ar? }
payload.perception; // { field, confidence, gate, lang, latency_ms }

Advanced exports

import {
  HDVEncoder, // hypervector encoder
  HDCAgent, // classify / observe / calibrate
  perceive, // perceive(text, agent, encoder) → PerceptionResult
  seedBrain, // seed agent+encoder with built-in corpus
  SEED_CORPUS, // raw corpus object
  SEED_FIELDS, // ['tech', 'health', ...]
} from "@msm-core/brain";

Gate decisions

| Gate | Condition | LLM call? | Payload | | -------- | ------------------------ | --------------- | ------------------------------------------------------------------- | | skip | confidence ≥ 0.85 | No | orchestration.action = 'respond', generation.response_text = '' | | assist | 0.45 ≤ confidence < 0.85 | Yes (with hint) | Full Qwen response | | full | confidence < 0.45 | Yes (no hint) | Full Qwen response |

On skip, the caller is responsible for filling the response from their tool or knowledge base. The brain signals "I know what domain this is, handle it yourself."

Performance

Measured on M1 MacBook Pro, Ollama running locally:

| Path | Latency | LLM calls | | -------- | ------- | ------------- | | skip | < 2ms | 0 | | assist | ~300ms | 1 (Qwen 1.5B) | | full | ~400ms | 1 (Qwen 1.5B) |

HDC skip rate after seeding a custom domain: 60–70%.

Relationship to other packages

@msm-core/cst    — tokenizer (CST adapter, this package's only runtime dep)
@msm-core/nemo   — standalone HDC library (reference; brain reimplements HDC internally)
@msm-core/mini   — execution loop (brain implements mini's Brain interface)
@msm-core/brain  — this package

License

MIT