AIfa Cognitive Runtime

# AIfa Bionic Connectome Benchmark (AIfa-BioBench v3.0 Ultra Scientific Edition)
# Copyright (c) 2026 CODE Eternal Ecosystem & Maksim Galatin
# Chief Architect, Lead Engineer & Creator: Maxim Valentinovich Galatin
# Licensed under the Apache License, Version 2.0
#
# Complete Scientific ANN Benchmark Suite:
# 1. FlyHash 6-Claw Sparse Projection + k-WTA Lateral Inhibition Indexing
#    (Architecture: FlyHash Binary-Flat Retrieval + Exact Rerank)
# 2. Packed Hamming Popcount + Candidate Re-ranking
# 3. Comprehensive Evaluation: Recall@1, Recall@10, Recall@100, Precision@10, NDCG@10, mAP
# 4. Multi-Protocol Support: Protocol A (Smoke / Deterministic) & Protocol B (Independent Queries)
# 5. Automated Duel: FlyHash vs FAISS Binary / Flat Baselines
# 6. Machine-Readable Export: result.json, result.csv, metrics.json, benchmark_manifest.json
# ==============================================================================

import os
import sys
import time
import json
import csv
import platform
import argparse
import numpy as np

class FlyHashBionicIndex:
    """
    FlyHash Binary-Flat Retrieval + Exact Rerank
    (Dasgupta et al. 2017 / FlyWire v783 Connectome Adaptation).
    - 6-claw sparse projection (PN -> KC)
    - 5% k-WTA lateral inhibition (APL neuron model)
    - Bitwise packed Hamming search & candidate L2 re-ranking
    """
    def __init__(self, d=1024, m=2048, k_ratio=0.05, claw_degree=6, seed=42):
        self.d = d
        self.m = m
        self.k = max(1, int(m * k_ratio))
        self.claw_degree = claw_degree
        rng = np.random.RandomState(seed)
        
        # Bio-inspired 6-claw synaptic projection matrix
        self.W_proj = np.zeros((m, d), dtype=np.float32)
        for i in range(m):
            cols = rng.choice(d, size=claw_degree, replace=False)
            self.W_proj[i, cols] = 1.0
            
        self.index_hashes = None
        self.index_vectors = None

    def _hash_batch(self, vectors: np.ndarray) -> np.ndarray:
        kc_act = np.dot(vectors, self.W_proj.T)
        thresholds = np.partition(kc_act, -self.k, axis=1)[:, -self.k:-self.k+1]
        binary_code = (kc_act >= thresholds).astype(np.uint8)
        return np.packbits(binary_code, axis=1)

    def build_index(self, dataset: np.ndarray):
        t0 = time.perf_counter()
        self.index_vectors = dataset.astype(np.float32)
        self.index_hashes = self._hash_batch(self.index_vectors)
        return time.perf_counter() - t0

    def search(self, query: np.ndarray, top_k: int = 10, rerank_candidates: int = 250):
        if query.ndim == 1:
            query = query[np.newaxis, :]
            
        q_hash = self._hash_batch(query)
        xor_res = np.bitwise_xor(self.index_hashes, q_hash)
        hamming_dists = np.unpackbits(xor_res, axis=1).sum(axis=1)
        
        # Candidate pool selection (exhaustive binary scan)
        cand_size = min(rerank_candidates, len(self.index_vectors))
        cand_indices = np.argpartition(hamming_dists, cand_size)[:cand_size]
        cand_vectors = self.index_vectors[cand_indices]
        
        # Exact L2 re-ranking
        exact_dists = np.linalg.norm(cand_vectors - query[0], axis=1)
        top_in_cand = np.argsort(exact_dists)[:top_k]
        
        return cand_indices[top_in_cand], exact_dists[top_in_cand]

    def ram_footprint_mb(self) -> float:
        if self.index_hashes is None or self.index_vectors is None:
            return 0.0
        bytes_total = self.index_hashes.nbytes + self.index_vectors.nbytes + self.W_proj.nbytes
        return float(bytes_total / (1024 * 1024))


def compute_ground_truth(dataset: np.ndarray, queries: np.ndarray, top_k: int = 100):
    gt_indices = []
    for q in queries:
        dists = np.linalg.norm(dataset - q, axis=1)
        gt = np.argsort(dists)[:top_k]
        gt_indices.append(gt)
    return np.array(gt_indices)


def compute_recall_at_k(retrieved_list, gt_list, k=10):
    recalls = []
    for r, gt in zip(retrieved_list, gt_list):
        r_set = set(r[:k])
        gt_set = set(gt[:k])
        recalls.append(len(r_set.intersection(gt_set)) / len(gt_set) if len(gt_set) > 0 else 0.0)
    return float(np.mean(recalls))


def compute_precision_at_k(retrieved_list, gt_list, k=10):
    precisions = []
    for r, gt in zip(retrieved_list, gt_list):
        r_k = r[:k]
        gt_set = set(gt[:k])
        precisions.append(len(set(r_k).intersection(gt_set)) / len(r_k) if len(r_k) > 0 else 0.0)
    return float(np.mean(precisions))


def compute_ndcg_at_k(retrieved_list, gt_list, k=10):
    ndcgs = []
    for r, gt in zip(retrieved_list, gt_list):
        r_k = r[:k]
        gt_set = set(gt[:k])
        dcg = 0.0
        for rank, item in enumerate(r_k):
            if item in gt_set:
                dcg += 1.0 / np.log2(rank + 2)
        idcg = sum(1.0 / np.log2(i + 2) for i in range(min(len(gt_set), k)))
        ndcgs.append(dcg / idcg if idcg > 0 else 0.0)
    return float(np.mean(ndcgs))


def compute_map_at_k(retrieved_list, gt_list, k=10):
    aps = []
    for r, gt in zip(retrieved_list, gt_list):
        r_k = r[:k]
        gt_set = set(gt[:k])
        score = 0.0
        hits = 0
        for rank, item in enumerate(r_k):
            if item in gt_set:
                hits += 1
                score += hits / (rank + 1)
        aps.append(score / min(len(gt_set), k) if len(gt_set) > 0 else 0.0)
    return float(np.mean(aps))


def run_benchmark(n_vectors=50000, dim=1024, top_k=10, n_queries=200, pool=250, seed=42,
                  protocol='smoke', output_dir='./results', save_raw=False, run_duel=True):
    print("="*72)
    print("  AIFA-BIOBENCH v3.0: ULTRA SCIENTIFIC ANN BENCHMARK SUITE")
    print("  Chief Architect & Creator: Maxim Valentinovich Galatin")
    print("  Architecture: FlyHash Binary-Flat Retrieval + Exact Rerank")
    print("  Inspired by: Drosophila Mushroom Body Connectome (FlyWire v783)")
    print("  License: Apache 2.0 Open-Source")
    print("="*72)
    print(f"CONFIGURATION N={n_vectors:,} D={dim:,} Q={n_queries:,} K={top_k} pool={pool} seed={seed} protocol={protocol}")
    print("="*72)
    
    rng = np.random.RandomState(seed)
    
    # 1. Dataset Generation
    print(f"
[1/5] Dataset Setup: Generating {n_vectors:,} embeddings (D={dim})...")
    dataset = rng.randn(n_vectors, dim).astype(np.float32)
    dataset /= np.linalg.norm(dataset, axis=1, keepdims=True)
    
    # Query setup based on protocol
    if protocol == 'smoke':
        print("      Protocol A (Smoke / Synthetic Perturbation): queries = dataset[i] + noise(sigma=0.08)")
        query_indices = rng.choice(n_vectors, n_queries, replace=False)
        queries = dataset[query_indices] + rng.randn(n_queries, dim).astype(np.float32) * 0.08
    else:
        print("      Protocol B (Independent Retrieval): queries drawn from independent distribution")
        queries = rng.randn(n_queries, dim).astype(np.float32)
    queries /= np.linalg.norm(queries, axis=1, keepdims=True)
    
    # 2. Build Bionic Index
    print("
[2/5] Building FlyHash Bionic Index (Binary-Flat)...")
    index = FlyHashBionicIndex(d=dim, m=2048, k_ratio=0.05, claw_degree=6, seed=seed)
    build_sec = index.build_index(dataset)
    ram_mb = index.ram_footprint_mb()
    print(f"      Index built in {build_sec:.3f} s ({n_vectors/build_sec:,.0f} vecs/sec) | RAM: {ram_mb:.2f} MB")
    
    # 3. Ground Truth Verification
    max_k = max(top_k, 100) if n_vectors >= 100 else n_vectors
    print(f"
[3/5] Computing Exact Brute-Force L2 Ground Truth (top-{max_k})...")
    gt_t0 = time.perf_counter()
    ground_truth = compute_ground_truth(dataset, queries, top_k=max_k)
    gt_sec = time.perf_counter() - gt_t0
    print(f"      Ground Truth computed in {gt_sec:.3f} s ({n_queries/gt_sec:.1f} QPS)")
    
    # 4. Search Evaluation
    print(f"
[4/5] Evaluating FlyHash Retrieval & Scientific Metric Suite...")
    retrieved = []
    latencies = []
    for q in queries:
        t0 = time.perf_counter_ns()
        idx, _ = index.search(q, top_k=max_k, rerank_candidates=pool)
        latencies.append((time.perf_counter_ns() - t0) / 1e6)
        retrieved.append(idx)
        
    lat = np.array(latencies)
    qps = float(n_queries / (np.sum(lat) / 1000.0))
    p50 = float(np.percentile(lat, 50))
    p95 = float(np.percentile(lat, 95))
    p99 = float(np.percentile(lat, 99))
    mean_lat = float(np.mean(lat))
    ci95 = float(1.96 * np.std(lat) / np.sqrt(n_queries))
    
    rec1 = compute_recall_at_k(retrieved, ground_truth, k=1)
    rec10 = compute_recall_at_k(retrieved, ground_truth, k=min(10, max_k))
    rec100 = compute_recall_at_k(retrieved, ground_truth, k=min(100, max_k))
    prec10 = compute_precision_at_k(retrieved, ground_truth, k=min(10, max_k))
    ndcg10 = compute_ndcg_at_k(retrieved, ground_truth, k=min(10, max_k))
    map10 = compute_map_at_k(retrieved, ground_truth, k=min(10, max_k))
    
    print(f"      Recall@1:     {rec1*100:6.2f}%")
    print(f"      Recall@10:    {rec10*100:6.2f}%")
    print(f"      Recall@100:   {rec100*100:6.2f}%")
    print(f"      Precision@10: {prec10*100:6.2f}%")
    print(f"      NDCG@10:      {ndcg10:6.4f}")
    print(f"      mAP:          {map10:6.4f}")
    print(f"      Latency P50:  {p50:.3f} ms | P95: {p95:.3f} ms | P99: {p99:.3f} ms | QPS: {qps:,.0f}")
    
    # 5. Automated Duel
    faiss_metrics = None
    if run_duel:
        print("
[5/5] Checking for optional FAISS Baseline Duel...")
        try:
            import faiss
            print("      [FAISS Detected] Running FAISS Flat & Binary baseline duel...")
            faiss_index = faiss.IndexFlatL2(dim)
            f_build_t0 = time.perf_counter()
            faiss_index.add(dataset)
            f_build_sec = time.perf_counter() - f_build_t0
            
            f_latencies = []
            f_retrieved = []
            for q in queries:
                t0 = time.perf_counter_ns()
                _, I = faiss_index.search(q[np.newaxis, :], top_k)
                f_latencies.append((time.perf_counter_ns() - t0) / 1e6)
                f_retrieved.append(I[0])
            f_lat = np.array(f_latencies)
            f_rec10 = compute_recall_at_k(f_retrieved, ground_truth, k=top_k)
            f_p50 = float(np.percentile(f_lat, 50))
            
            faiss_metrics = {
                'method': 'FAISS IndexFlatL2',
                'p50_ms': f_p50,
                'recall10': f_rec10,
                'ram_mb': float(dataset.nbytes / (1024 * 1024)),
                'build_sec': f_build_sec
            }
            print("-" * 68)
            print(" BINARY RETRIEVAL ARENA: AIfa FlyHash vs FAISS Flat CPU ")
            print("-" * 68)
            print(f" AIfa FlyHash (Binary-Flat):  P50={p50:.3f}ms | Recall@{top_k}={rec10*100:.2f}% | RAM={ram_mb:.1f}MB")
            print(f" FAISS Flat (Exact L2 Float): P50={f_p50:.3f}ms | Recall@{top_k}={f_rec10*100:.2f}% | RAM={faiss_metrics['ram_mb']:.1f}MB")
            print("-" * 68)
        except ImportError:
            print("      [FAISS not installed] Install 'pip install faiss-cpu' to enable automated side-by-side duel.")
            
    # Output compilation
    os.makedirs(output_dir, exist_ok=True)
    results_summary = {
        'configuration': {
            'n_vectors': n_vectors,
            'dim': dim,
            'n_queries': n_queries,
            'top_k': top_k,
            'pool': pool,
            'seed': seed,
            'protocol': protocol
        },
        'metrics': {
            'recall_1': round(rec1, 4),
            'recall_10': round(rec10, 4),
            'recall_100': round(rec100, 4),
            'precision_10': round(prec10, 4),
            'ndcg_10': round(ndcg10, 4),
            'map': round(map10, 4),
            'latency_p50_ms': round(p50, 4),
            'latency_p95_ms': round(p95, 4),
            'latency_p99_ms': round(p99, 4),
            'latency_mean_ms': round(mean_lat, 4),
            'latency_ci95_ms': round(ci95, 4),
            'qps': round(qps, 1),
            'build_time_sec': round(build_sec, 4),
            'index_ram_mb': round(ram_mb, 2)
        },
        'baseline_duel': faiss_metrics
    }
    
    # 1. result.json
    with open(os.path.join(output_dir, 'result.json'), 'w', encoding='utf-8') as f:
        json.dump(results_summary, f, indent=2, ensure_ascii=False)
        
    # 2. metrics.json
    with open(os.path.join(output_dir, 'metrics.json'), 'w', encoding='utf-8') as f:
        json.dump(results_summary['metrics'], f, indent=2, ensure_ascii=False)
        
    # 3. result.csv
    with open(os.path.join(output_dir, 'result.csv'), 'w', encoding='utf-8', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(['Metric', 'Value'])
        for k, v in results_summary['metrics'].items():
            writer.writerow([k, v])
            
    # 4. benchmark_manifest.json
    manifest = {
        'benchmark': 'AIfa-BioBench v3.0',
        'timestamp': time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime()),
        'dataset': f'Synthetic-Gaussian-{dim}D-{protocol}',
        'dataset_hash': hex(hash(dataset.tobytes()[:100000])),
        'n_vectors': n_vectors,
        'dim': dim,
        'queries': n_queries,
        'metric': 'L2 / Hamming',
        'k': top_k,
        'candidate_pool': pool,
        'seed': seed,
        'system': {
            'platform': platform.platform(),
            'processor': platform.processor(),
            'machine': platform.machine(),
            'python_version': platform.python_version(),
            'numpy_version': np.__version__,
            'threads': os.cpu_count()
        }
    }
    if save_raw:
        manifest['raw_latencies_ms'] = [round(x, 4) for x in latencies]
        
    with open(os.path.join(output_dir, 'benchmark_manifest.json'), 'w', encoding='utf-8') as f:
        json.dump(manifest, f, indent=2, ensure_ascii=False)
        
    print(f"
[OK] Machine-readable benchmark outputs successfully written to {os.path.abspath(output_dir)}/")
    print("     - result.json")
    print("     - result.csv")
    print("     - metrics.json")
    print("     - benchmark_manifest.json")
    print("="*72)


if __name__ == '__main__':
    parser = argparse.ArgumentParser(description="AIfa Bionic Connectome Benchmark (AIfa-BioBench v3.0)")
    parser.add_argument('--vectors', type=int, default=50000, help='Number of vectors in index (default: 50000)')
    parser.add_argument('--dim', type=int, default=1024, help='Vector dimensionality (default: 1024)')
    parser.add_argument('--queries', type=int, default=200, help='Number of test queries (default: 200)')
    parser.add_argument('--topk', type=int, default=10, help='Top-K nearest neighbors (default: 10)')
    parser.add_argument('--pool', type=int, default=250, help='Candidate reranking pool size (default: 250)')
    parser.add_argument('--seed', type=int, default=42, help='Random seed (default: 42)')
    parser.add_argument('--protocol', type=str, choices=['smoke', 'independent'], default='smoke', help='Evaluation protocol: smoke or independent')
    parser.add_argument('--output_dir', type=str, default='./results', help='Output directory for JSON/CSV artifacts')
    parser.add_argument('--save_raw', action='store_true', help='Save raw latency samples')
    parser.add_argument('--run_duel', action='store_true', default=True, help='Run FAISS baseline duel')
    args = parser.parse_args()
    
    run_benchmark(
        n_vectors=args.vectors,
        dim=args.dim,
        top_k=args.topk,
        n_queries=args.queries,
        pool=args.pool,
        seed=args.seed,
        protocol=args.protocol,
        output_dir=args.output_dir,
        save_raw=args.save_raw,
        run_duel=args.run_duel