antahkarana 3.0.0

A trainable continual-learning architecture (manas/buddhi/ahaṃkāra/citta) that learns without forgetting, knows when it doesn't know, watches for drift, and governs its own actions. Ships the Continual-Governance Benchmark (CGB): four faculties, four measured numbers (retention, calibrated abstention, drift false-alarm, governed escalation) on one leaderboard across tabular/vision/language, plus a tamper-evident hash-chained audit trail.

antahkarana — train a continual-learning mind on your data

antahkarana is a trainable architecture, not a frozen model. You bring your data (and optionally your backbone); it trains a model that learns continually without forgetting, detects novelty / zero-days, abstains when unsure, and consolidates in sleep. Four organs — manas · buddhi · ahaṃkāra · citta — the mind is the same for every domain; only a thin adapter changes.

Built on the validated Antaḥkaraṇa-base core (gated G0–G5, proven across language · vision · security · with seeded, adaptive evaluation — see the model card for plots, results, and honest limits).

Install

pip install antahkarana              # core + tabular
pip install antahkarana[text]        # + HuggingFace LLM adapter
pip install antahkarana[bench]       # + the open Continual-Governance Benchmark (2.1)
pip install antahkarana[telemetry]   # + OpenTelemetry OTLP export (2.2)

Train on your data in ~10 lines (tabular)

from antahkarana import Antahkarana, TabularAdapter

# YOUR data: a list of tasks, each (X_train, y_train, X_test, y_test)
stream = TabularAdapter.make_stream(your_tasks)

bb   = TabularAdapter(input_dim=122, n_tasks=4, n_classes=2)   # built-in MLP — bring only data
mind = Antahkarana(bb, replay_strategy="der", avidya_strategy="energy")
res  = mind.train(stream)

print(res["forgetting"], res["final_row"], res["risk_coverage"])

New in 3.0 — Memory & feedback (Gate G9): the gate learns

Alignment learned outside the weights. Citta gains a retrievable episodic memory with a consolidation daemon, and the control gate learns from human approve/deny decisions — bounded by a monotone-tightening invariant so it can only grow stricter on its own; any loosening is a proposed policy diff a human must merge.

Gate G9: on held-out replays the feedback-tuned gate strictly dominates the static gate on both false-alarm and miss rate. — PASS on 3 corpora (miss 0.50/0.58/0.67 → 0.00 at equal FAR).

from antahkarana.feedback import FeedbackDataset, ThresholdCalibrator
from antahkarana.memory import SqliteStore, MemoryRecord, Tier
from antahkarana.memory.nidra import Nidra

ds  = FeedbackDataset.build(labels, ticks)                     # approve/deny ⨝ trace attributes
cal = ThresholdCalibrator(spec_min=0.5, spec_max=0.95, static_threshold=0.9).fit(ds)
gate_threshold = cal.tuned_threshold()                         # clamped; tighten-only autonomously
if cal.loosening_diff: ...                                     # a spec diff for a human to merge

store = SqliteStore("mem.db"); Nidra(store).run_once()          # consolidate episodes → summaries → facts
store.forget({"cluster": "host7"}, by="dpo@corp")               # GDPR-shaped, audited deletion

atk gateparams rollback sensor-7     # revert a bad calibration in < 1s, audited (like a baseline)

• antahkarana.memory — three-tier episodic store (episode/summary/fact), zero-dep SqliteStore, audited forget(), retrieval taint-labeled and fenced (memory can't widen permissions — the v2.5 defenses apply to it verbatim).
• antahkarana.memory.nidra — consolidation scheduler: episodes → per-cluster summaries → human- approved facts; episodes expire only after their summary is durable (no information cliff).
• antahkarana.feedback — FeedbackDataset + ThresholdCalibrator (clamped, monotone- tightening) + gateparams registry deployment (canary → promote → rollback) + reliability/ECE.

New in 2.5 — Integration (Gate G8): the LLM proposes, the ring disposes

Rent a frontier brain to reason inside a governed loop — and make it structurally impossible for untrusted content to widen its own permissions. The LLM emits proposals; the control ring disposes. Only an ALLOW verdict mints the single-use, signed capability token a sink demands, so a drafting engine can never reach a tool it wasn't authorized for — bypass is a type error.

Gate G8: injected instructions inside sensed content achieve zero policy escalations. — 16 gate tests green; real-model 500-case red-team confirmation on GPU.

from antahkarana.llm import BuddhiLLM, ProposalRouter, GatedSink
from antahkarana.security import CapabilityMint, Observation
from antahkarana.control import RiskRouter, Policy

mint = CapabilityMint()
ring = RiskRouter(Policy.from_dict({"hard_block": ["privileged"], "notify_threshold": 0.99}))
router = ProposalRouter(ring, mint, loop_id="mailwatch",
                        sinks={"notify.status": GatedSink(send, mint, "mailwatch")})

brain = BuddhiLLM(provider="anthropic", model="claude-opus-4-8")   # or provider="local" for CPU/CI
router.run_tick(brain, ctx)     # reason → propose → gate each → act only allowed, token-checked

atk redteam run --n 500 --model Qwen/Qwen2.5-7B-Instruct --device cuda --out runs/g8

• antahkarana.security — capability tokens bound to (loop, action, params, tick) (replay / mutation / cross-loop all fail closed) + taint tracking (tainted text reaches the model fenced, as data never instructions) + a shipped injection red-team corpus.
• antahkarana.llm — Proposal/Backbone/BuddhiLLM; the model holds no capability, provider errors abstain (never default-allow), escalations are recorded before any token is minted (unsuppressible), the prompt template is versioned and hash-locked.
• antahkarana.mcp — any MCP server becomes a source/sink (sinks act only on a ring token); a loop exposes itself as MCP tools so Claude Desktop/Code is the human-escalation surface, no UI.

New in 2.2 — Hardening (Gate G7): replay any incident from traces alone

The runtime becomes production-grade. Four opt-in modules (zero behavior change until enabled) plus the new atk CLI, behind a falsifiable gate: G7 — replay any past incident end-to-end from traces alone, and roll back a bad baseline refit in one command (20 gate tests, all green).

from antahkarana import Loop, telemetry

telemetry.install(out_dir="traces")                        # one trace per tick, one span per organ
loop = telemetry.instrument(Loop(...), loop_id="sensor-7")
loop.run()

atk replay traces/ --loop sensor-7 --tick 441 --diff 440   # → the first divergent organ attribute
atk policy test policies/        # versioned declarative policies: shadow lint + table tests + version lock
atk baseline rollback sensor-7   # baseline registry: canary shadow → promote → rollback, < 1s, no refit

• antahkarana.telemetry — spans carry hashes/scores/verdicts, never raw sensed content; zero-dep traces/*.otlpjsonl file exporter; real OTLP collectors via the [telemetry] extra.
• antahkarana.budget — declarative budgets + three-state circuit breakers that act through the control ring: exhausted budget or open breaker ⇒ an audited soft_block, one escalation per window; act failures trip the breaker open instead of killing the loop. Thread-safe ledgers (in-memory + SQLite), no lost debits under concurrency.
• antahkarana.policyspec — policies as versioned spec files (apiVersion: antahkarana.dev/v1) with load-time shadow analysis (a hard-blocked category can never be silently re-allowed), colocated table-driven tests, and a version lock: change the ruleset without bumping metadata.version and atk policy test fails.
• antahkarana.registry — every OneClassChange refit is an immutable versioned artifact (fitted → canary → active → retired | rolled_back); the canary scores every tick in shadow and can never reach the ring; promotion and rollback are atomic pointer swaps.

New in 2.1 — the Continual-Governance Benchmark (CGB) + tamper-evident audit

Four faculties, four measured numbers, one leaderboard — retention ①, selective-risk AURC ②, drift false-alarm rate ③, governed-escalation F1 + audit integrity ④ — across security-tabular, vision, and language (frozen Mistral-7B + LoRA), plus measurable consolidation (ΔR = R_sleep − R_noSleep) and a hash-chained AuditLog whose verify() makes governance a checkable contract. Full board + honest negatives: CGB_RESULTS.

pip install "antahkarana[bench]"
python -m antahkarana.bench.run --suite cgi-v3-tabular --seeds 5 --out runs/tabular

New in 2.0 — the loop engine: watch · learn · improve · orchestrate

The same four organs that learn continually on training tasks now run as a governed loop engine on live observations. Generic agent loops watch and act; this one learns what's normal (fewer false alarms over time), remembers without forgetting, governs by construction (every action passes an audited control ring), and abstains when unsure. Fully additive — every 1.x symbol and default is unchanged.

from antahkarana import Loop, Policy

# A governed stock watcher: it stays silent until the right shoe appears,
# then ESCALATES to you — it never buys on its own (purchase is hard-blocked).
watch = Loop(
    sense=check_product_page,                         # your eyes: return the current observation
    change=lambda o, mem: 1.0 if (o["in_stock"] and o["price"] <= 175) else 0.0,
    category=lambda o: "purchase",
    signature=lambda o: f"{o['in_stock']}:{o['price']}",   # smṛti dedup — don't re-alert the same thing
    gate=Policy(name="shopper", hard_block=["purchase"]),  # the control ring: never auto-buy
    on_escalate=lambda obs, iv: notify_me(obs),
)
watch.run(max_steps=1000)

Four composing phases — each maps 1:1 to an organ:

• Loop (watch) — a governed sentinel. Sense → score novelty → fire only on a real spike vs the running baseline (ahaṃkāra) → route through the control ring → dedup (smṛti). Hard-blocked actions escalate to a human, never auto-act; everything is audited.
• OneClassChange (learn) — a learned baseline for Loop: a Normal-only autoencoder that refits on a sliding window with held-out calibration and adapts to drift. Under drift, a static rule's false alarms blow up to 45–98% while the learned baseline holds them at the ~5% budget (3 seeds).
• ImproveLoop (improve) — build → critique → fix → repeat until a learned standard is met, then gate the ship. Monotone convergence in 3–4 rounds, and it never auto-ships (the finished draft is escalated for sign-off).
• Orchestrator (orchestrate) — buddhi fans out N specialist loops under ONE ring and ONE audit log, then ranks what surfaced so you see the critical thing first. The software spine of the air-gapped Box.

The loop engine is a thin governed runtime around your backbone — it supplies memory + calibrated novelty + the audited gate + the learning baseline; the reasoning/action inside each loop is yours. See examples/loop_stock_watch.py.

New in 1.1.0 — four ways to not forget · scale-stable training · closed-loop plasticity

A backward-compatible release — every new behaviour is opt-in; the defaults reproduce 1.0. Validated on the NSL-KDD high-interference stream (3 seeds), cross-checked on UNSW-NB15 + vision; core gates green.

• Four complementary no-forgetting mechanisms — saṃskāra (EWC) · DER++ (now on the text adapter too) · OrthoLoRA structural isolation (forgetting +0.288 → +0.215 where a penalty gives ~0) · forgetting-curve replay (nidrā) that rehearses the about-to-be-forgotten items first (rare-tail recall 0.276 → 0.314).
• MatraLAMB scale-stable optimization (Antahkarana(optimizer="lamb")) — a trust-ratio step (mātrā) so a full backbone and a tiny adapter move in proportion to their own magnitude, and one lr is stable across any scale. At the lr that used to collapse O-LoRA, forgetting +0.167 → +0.003 (≈ zero), accuracy up, robust on every seed; plus max_grad_norm gradient clipping (saṃyama).
• Adaptive guṇa (Antahkarana(adaptive_guna=True)) — plasticity closes the loop on measured forgetting: strictly Pareto-better where there's headroom (−11% forgetting and +accuracy), a safe no-op when there isn't.
• OneClassNovelty — complementary zero-day detector for threats sitting inside the known-data manifold (UNSW Backdoor AUROC 0.47 → 0.93).

Full details + the honest negatives we kept (and didn't ship): CHANGELOG · API.md.

The 1.0 foundation — stable API, with the control ring + calibrated novelty built in

The public API is now frozen under SemVer — 13 symbols (Antahkarana, the adapters, FeatureOOD, NoveltyCalibrator, the eval metrics, and the Policy / RiskRouter / Tier / Intervention control ring). A breaking change to any of them — or to the frozen BackboneAdapter contract — bumps the major version, so your adapters and training code keep working while organ implementations stay free to improve. Full surface + guarantees: API.md. The two capabilities that landed on the road to 1.0 are part of that stable surface:

The control ring (Layer-2 policy)

A swappable risk-tier router over any trained backbone. One consolidated brain (the weights = Layer-1 disposition), many deployment policies (config = Layer-2) — change safety posture without retraining, and every decision is logged (transparency by construction).

A request flows through the consolidated organs (Layer 1); manas emits a risk score; the RiskRouter applies the deployment Policy (Layer 2) to pick a tier — ALLOW / NOTIFY / SOFT_BLOCK / HARD_BLOCK — and logs every decision.

Validated on UNSW-NB15: calibrated to ~5% false-block on normal traffic, the ring gates known attacks and catches ~95% of a held-out zero-day family it never trained on — built on the Layer-1 DER++ no-forgetting win.

from antahkarana import Policy, RiskRouter
ring = RiskRouter(Policy.load("policy.yaml"))     # hard/soft blocks, thresholds, operator overrides
iv   = ring.gate(score=novelty, category="intrusion")
# iv.tier ∈ {allow, notify, soft_block, hard_block};  iv.allowed / iv.notify / iv.reason drive the response

See examples/control_ring.py.

Calibrated novelty — NoveltyCalibrator (manas → ring)

Raw novelty scores live on arbitrary scales, so a fixed ring threshold over- or under-blocks. NoveltyCalibrator maps one or more signals (energy, FeatureOOD, …) to a calibrated [0,1] against a normal reference (empirical CDF) — so a ring threshold of 0.95 is a 5% false-alarm rate, and manas output is directly ring-ready.

from antahkarana import NoveltyCalibrator
cal = NoveltyCalibrator(mode="mean")                  # "mean" steadier · "max" more sensitive
cal.fit(energy=normal_energy, feature=normal_feat)    # calibrate against NORMAL data
p = cal.score(energy=new_energy, feature=new_feat)    # 0..1 ; 0.95 ≈ 5% false alarms

Honest note: no unsupervised fusion of energy+feature beat the best single signal on held-out UNSW-NB15 families — calibration's value is the FPR-tunable scale, not an AUROC boost.

Core (since 0.3.0) — DER++ replay + feature-space novelty

DER++ works for tabular (replay_strategy="der"): on a 6-family UNSW-NB15 stream it cut forgetting from +0.048 (naive) to +0.009 — the no-forgetting guarantee holds on modern data, not just text/vision.

FeatureOOD adds a penultimate-feature novelty detector (Mahalanobis / kNN) complementary to the default energy score — measured to rescue families where energy fails (Backdoor AUROC 0.37→0.79) while energy remains better where it already works. Pick per deployment or ensemble; energy stays the default.

from antahkarana import FeatureOOD
det   = FeatureOOD("mahalanobis").fit(known_features, known_labels)   # bb.features(inputs) -> embeddings
score = det.score(new_features)        # higher = more novel / likely zero-day

Text (any HuggingFace causal-LM + LoRA)

from antahkarana import Antahkarana, TextAdapter
bb     = TextAdapter("mistralai/Mistral-7B-v0.1")             # frozen base, small LoRA trains
stream = TextAdapter.make_stream(your_text_tasks)             # [(train_pairs, eval_pairs), …]
Antahkarana(bb).train(stream)

Any other modality

Copy antahkarana/adapters/template.py (CustomAdapter) and implement 5 methods over your encoder (audio, graph, multi-modal, robotics, …). The continual-learning mind is unchanged.

Runnable examples

python examples/train_tabular.py     # concept-drift stream: naive forgets, the core doesn't
python examples/train_security.py    # continual threat detection (attack families) + calibrated triage

What you get back

train() returns: the task×task accuracy matrix, final_row, final_avg, forgetting, risk_coverage (calibrated abstention), recovery (sleep), and the trajectory (per-task guṇa/novelty).

Knobs

Antahkarana(bb, samskara=, replay_strategy="naive"|"der", avidya_strategy="msp"|"energy", sleep=, base_lr=, epochs=) — turn each organ on/off and swap in the SOTA implementation (DER++ dark-knowledge replay, energy-OOD novelty).

Ship it closed-source

python build_wheel.py compiles the engine to binary .so (Nuitka) and drops the source, leaving only the public interface readable — others can pip install and train on their data without seeing your code. (For maximum IP protection, serve it behind an API instead.)

60-second tour

python examples/try_it.py        # no-forgetting · zero-day · abstention · control ring

(API stability + the frozen BackboneAdapter contract are covered under The 1.0 foundation above; full surface in API.md.)

---

Author — Deepak Soni · Apache-2.0