Metadata-Version: 2.4
Name: antahkarana
Version: 1.1.0
Summary: A trainable continual-learning architecture (manas/buddhi/ahaṃkāra/citta) you train on your own data — no forgetting (DER++ · O-LoRA · forgetting-curve replay), energy + feature-space + one-class novelty, calibrated abstention, scale-stable mātrā-LAMB optimization, adaptive plasticity, and a swappable risk-tier control ring. Stable 1.x API.
Author: Deepak Soni
License: Apache-2.0
Project-URL: Homepage, https://huggingface.co/deepakdsoni/antahkarana-base
Keywords: continual-learning,lifelong-learning,catastrophic-forgetting,ood,lora,antahkarana
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy
Provides-Extra: text
Requires-Dist: transformers>=4.40; extra == "text"
Requires-Dist: peft>=0.10; extra == "text"
Dynamic: license-file

# antahkarana — train a continual-learning mind on **your** data

[![PyPI](https://img.shields.io/pypi/v/antahkarana.svg)](https://pypi.org/project/antahkarana/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/antahkarana/)
[![Model card](https://img.shields.io/badge/🤗-model%20card-yellow.svg)](https://huggingface.co/deepakdsoni/antahkarana-base)

`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.

![architecture](https://huggingface.co/deepakdsoni/antahkarana-base/resolve/main/assets/architecture.png)

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

## Install
```bash
pip install antahkarana            # core + tabular
pip install antahkarana[text]      # + HuggingFace LLM adapter
```

## Train on your data in ~10 lines (tabular)
```python
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 1.0.0 — 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](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).

![two-layer architecture](https://huggingface.co/deepakdsoni/antahkarana-base/resolve/main/assets/control_ring_architecture.png)

*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.*

![control ring performance](https://huggingface.co/deepakdsoni/antahkarana-base/resolve/main/assets/control_ring_performance.png)

*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.*
```python
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.
```python
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.
```python
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)
```python
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
```bash
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
```bash
python examples/try_it.py        # no-forgetting · zero-day · abstention · control ring
```
(API stability + the frozen `BackboneAdapter` contract are covered under *New in 1.0.0* above; full surface in
[API.md](API.md).)

---
*Author — Deepak Soni · Apache-2.0*
