k-familiar

A fast, zero-training intent router that thinks in six table lookups.

~16,000 classifications/second. Zero training. numpy-only. Accurate on covered vocabulary — and it asks when it isn't sure instead of guessing.

from k_familiar import Familiar

f = Familiar()
result = f.classify("analyze the flaw in this argument")

print(result["suit"])        # "spades" (mind/analysis domain)
print(result["confidence"])  # 1.0  (all content-words agree)
print(result["k_addr"])      # "+4S"
print(result["latency_us"])  # ~60

What It Does

Classifies text into four cognitive domains using GF(4) finite field algebra. It votes over a fixed keyword→suit table, so it is accurate on covered vocabulary and returns low/zero confidence (or ASKs) on words it doesn't know — it won't invent a class:

Each classification also returns:

• Confidence (0.0–1.0) — the fraction of content-words that agree on the winner (1.0 = unanimous, 0.5 = a two-way split). An interpretable vote share, not a calibrated probability.
• Rank (1-13, intensity/complexity)
• Polarity (light/dark, positive/negative valence)
• K-address (e.g., "+7H" = high-intensity positive emotional content)

Why It's Different

How It Works

Six operations over GF(4) lookup tables:

The entire computation is table lookups. No matrix multiplies. No floating point in the critical path. Fits in L1 cache.

Install

pip install k-familiar

Quick Start

Classify text

from k_familiar import Familiar

f = Familiar()

# Classify text — accurate when the words are covered
print(f.classify("analyze the flaw in this argument"))
# {'suit': 'spades', 'confidence': 1.0, 'k_addr': '+4S', ...}

print(f.classify("I feel grateful and connected to my team"))
# {'suit': 'hearts', 'confidence': 1.0, 'k_addr': '+4H', ...}

print(f.classify("take action now and execute the plan"))
# {'suit': 'clubs', 'confidence': 1.0, 'k_addr': '+4C', ...}

print(f.classify("the server needs more memory"))
# {'suit': 'diamonds', 'confidence': 1.0, 'k_addr': '+3D', ...}

Route to templates

f = Familiar()

# Set responses for each domain
f.set_template("H", response="Take a breath. You're not alone in this.")
f.set_template("S", response="Let's break this down step by step.")
f.set_template("D", response="Check the specs, then build a prototype.")
f.set_template("C", response="Start now. Iterate later.")

# Route automatically
result = f.route("I can't figure out this algorithm")
print(result["response"])  # "Let's break this down step by step."
print(result["source"])    # "template"

Working memory

f = Familiar()

# Remember things (holographic superposition)
f.remember("morning", "had coffee with Sarah, felt good")
f.remember("task", "need to finish the API by Thursday")

print(f.status())
# {'bundle_items': 2, 'capacity': {'phase': 'green', ...}, ...}

# Capacity is bounded: ~10 items for d=64
# The Familiar KNOWS when it's full and will refuse + ASK

Use the raw opcodes

from k_familiar import bind, bundle, retrieve, fold, check
import numpy as np

# Create vectors
key = np.random.randint(0, 4, 64).astype(np.uint8)
val = np.random.randint(0, 4, 64).astype(np.uint8)

# Bind, bundle, retrieve
bound = bind(key, val)
memory = bundle(bound, np.zeros(64, dtype=np.uint8))
recovered = retrieve(memory, key)

# Compress
folded = fold(recovered)  # 64 -> 21 elements (3:1 via genetic code table)

# Check capacity
status = check(bundle_items=3, d=64)
print(status)  # {'items': 3, 'capacity': 10.67, 'ok': True, 'phase': 'green'}

Use Cases

Pre-LLM router — Classify intent locally before making expensive API calls. Route 80% of queries to templates, send only the hard 20% to GPT/Claude.

Safety layer — The Familiar can't produce harmful outputs because the codon tables don't have paths to harm. Not filtered. Absent. Use as a first-pass safety check.

Agent classifier — In multi-agent systems (CrewAI, AutoGen, LangGraph), use k-familiar to route tasks to the right agent by domain.

Offline AI — Works on airplanes, in the field, on Raspberry Pi. No internet, no API keys, no latency.

Education — Teach information theory, finite fields, and holographic memory with a working implementation.

The Math

The GF(4) field has four elements {0, 1, 2, 3} with addition and multiplication tables:

ADD:  0 1 2 3    MUL:  0 1 2 3
    0 0 1 2 3        0 0 0 0 0
    1 1 0 3 2        1 0 1 2 3
    2 2 3 0 1        2 0 2 3 1
    3 3 2 1 0        3 0 3 1 2

These 32 bytes (two 4x4 tables) are the entire "model." Everything else is derived.

The capacity bound: a bundle of k items in d dimensions can be reliably retrieved when k <= (q/(q-1)) * sqrt(d). For GF(4), d=64: capacity ~ 10.67 items.

The fold operation uses the biological genetic code (64 codons -> 21 amino acids) as a compression table. This is not a metaphor. It's the same math.

License

MIT. Use it for anything.

Links

• HoldTheLine — Project home
• K-Systems Research — The math
• Papers — GF(4) routing, holographic capacity proofs