Exactor Accelerator

🚀 Exactor Accelerator v2.0.9: Maximizando el Poder Cognitivo de Jev en Local

Exactor Accelerator es el primer motor híbrido neuro-simbólico que unifica Aprendizaje No Supervisado, Minimización Booleana y Destilación Autónoma desde Cero Datos (Cold-Start) en una sola librería de Python.

Su diseño está pensado para actuar en simbiosis perfecta con TypeSafe AI (Jev): toma las respuestas lógicas de su motor de decisiones y las compila localmente en un Hipercubo Booleano Exacto en Rust. ¿El resultado? Una infraestructura híbrida que lleva la inteligencia de Jev al borde de la micro-latencia local (0.05 ms), reduciendo drásticamente los costos de red y optimizando el uso de tokens.

🎯 El Gran Dilema de la Infraestructura en la Nube (Y la sinergia Jev + Exactor)

Hasta hoy, las arquitecturas de software de misión crítica enfrentaban un balance complejo entre modelos locales y servicios en la nube:

• Machine Learning Tradicional (XGBoost / Scikit-Learn): Es rápido en producción, pero es una caja negra ciega el Día 1. Requiere miles de filas de datos históricos etiquetados y es imposible de auditar bajo normativas estrictas de cumplimiento.
• El Enfoque Declarativo Avanzado (Jev): Ofrece un razonamiento brillante desde el primer segundo sin datos previos y con un rendimiento de procesamiento líder en su clase. Sin embargo, cualquier infraestructura en la nube está sujeta a la latencia inherente de la red (API calls) y a un costo de transferencia constante al procesar millones de peticiones.

La Sinergia Perfecta (Jev + Exactor): En lugar de forzar una elección, esta alianza ofrece lo mejor de ambos mundos. Jev actúa como la mente estratégica que resuelve y calibra escenarios ambiguos o cambiantes; Exactor actúa como su compilador de ejecución local rápida. Al registrar y aprender de las interacciones con Jev en un libro de contabilidad ultra rápido (SQLite en modo WAL), Exactor automatiza la ejecución local de las reglas en solo 0.05 milisegundos, liberando ancho de banda y protegiendo tus presupuestos de tokens.

📊 Tabla Comparativa: Rendimiento en Producción

🧠 Los 3 Pilares Tecnológicos en un Solo Flujo

Exactor elimina por completo los pesados e interminables ciclos de reentrenamiento offline trabajando de la mano con la memoria de tus decisiones:

• Flujo No Supervisado: Monitorea flujos de datos crudos extrayendo entropía de Shannon y puntuaciones Z en tiempo real para alertar sobre derivas de concepto (Concept Drift) antes de que afecten al negocio.
• Destilación Autónoma (Cold-Start): Despliega el sistema con cero filas históricas. La librería colabora con el motor de Jev en las primeras transacciones, guarda las respuestas y genera dinámicamente un modelo local optimizado que replica su comportamiento lógico.
• API Drop-in para Científicos de Datos: Cuenta con compatibilidad nativa con el ecosistema de Scikit-Learn. Puedes invocar .fit(X, y) y .predict(X) utilizando un reductor de hipercubos basado en código Gray que garantiza precisión matemática sin pérdidas de punto flotante.

⚡ Casos de Uso Críticos (Niches of Excellence)

• Prevención de Fraudes: Decisiones locales inmediatas complementadas con la inteligencia adaptativa de Jev en la nube.
• Triaje Médico Avanzado: Pistas de auditoría lógicas e inmutables listas para certificaciones HIPAA.
• Ciberseguridad y SOC Logs: Procesamiento de más de 50,000 eventos por segundo (TPS) detectando anomalías por ráfagas de velocidad.
• Cumplimiento Regulatorio Absoluto: Cada decisión se explica mediante una fórmula matemática exacta (IF AND OR NOT), eliminando el riesgo legal de las decisiones automatizadas.

Installation

pip install exactor-accelerator

Configuration

Exactor Accelerator connects to the EXACTOR Core engine for cloud-accelerated boolean minimization. Set your token using any of these methods:

Option 1: Environment Variable (recommended for production)

export EXACTOR_CORE_TOKEN="your-token-here"
export JEV_API_KEY="your-jev-key"          # Optional: TypeSafe Jev API
export DEEPSEEK_API_KEY="your-key"          # Optional: LLM explainer

Option 2: .env File

cp .env.example .env
# Edit .env with your tokens

Option 3: Programmatic Configuration

import exactor_accelerator

exactor_accelerator.configure(
    exactor_core_token="your-token-here",
    jev_api_key="your-jev-key",           # Optional
    deepseek_api_key="your-key",          # Optional
)

Option 4: Per-Instance Token

from exactor_accelerator import ExactorAccelerator

engine = ExactorAccelerator(
    exactor_token="your-token-here",
    use_cloud_exactor=True,
)

Note: Without an EXACTOR Core token, the library falls back to the built-in Hypercube Gray-code Reducer engine, which provides the same deterministic boolean minimization locally.

Quick Start (Copy & Run: Unsupervised + Supervised + Cold-Start)

import pandas as pd
from exactor_accelerator import (
    ExactorAccelerator,
    ExactorAcceleratorClassifier,
    get_feature_engine,
    get_regime_detector,
)

# 1. Raw unlabeled stream (or load via pd.read_csv("your_data.csv"))
raw_df = pd.DataFrame({
    "amount": [45.0, 120.5, 950.0, 15.0, 2100.0, 32.0, 1500.0, 80.0, 42.0, 310.0, 1800.0, 55.0],
    "velocity_1h": [1, 2, 8, 1, 15, 1, 12, 2, 1, 3, 14, 1],
    "device_trust": [0.95, 0.88, 0.20, 0.99, 0.10, 0.92, 0.15, 0.85, 0.90, 0.70, 0.08, 0.94],
    "ip_reputation": ["CLEAN", "CLEAN", "SUSPICIOUS", "CLEAN", "MALICIOUS", "CLEAN", "MALICIOUS", "CLEAN", "CLEAN", "SUSPICIOUS", "MALICIOUS", "CLEAN"],
    "country_risk": ["LOW", "LOW", "MEDIUM", "LOW", "HIGH", "LOW", "HIGH", "LOW", "LOW", "MEDIUM", "HIGH", "LOW"],
})

# =====================================================================
# MODE A: UNSUPERVISED (Feature Extraction, Anomaly Z-Scores & Drift)
# =====================================================================
feature_engine = get_feature_engine(domain="fraud")
df_enriched = feature_engine.extract_all(raw_df)

regime_detector = get_regime_detector(domain="fraud")
regime_info = regime_detector.analyze_regime(
    features=df_enriched.iloc[-1].to_dict(),
    history_df=df_enriched,
)
print(f"[Unsupervised] Regime: {regime_info['dominant_regime']} | Gate: {regime_info['actionability_gate']}")

# =====================================================================
# MODE B: SUPERVISED (Exact Boolean Hypercube Minimization + Audit)
# =====================================================================
target = pd.Series([0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 0], name="target")

clf = ExactorAcceleratorClassifier(domain="fraud", fast_path=True)
clf.fit(df_enriched, target)

new_tx = feature_engine.extract_all(pd.DataFrame([{
    "amount": 1850.0,
    "velocity_1h": 14,
    "device_trust": 0.12,
    "ip_reputation": "MALICIOUS",
    "country_risk": "HIGH",
}]))
prediction = clf.predict(new_tx)
explanation = clf.explain(new_tx)

print(f"\n[Supervised] Prediction (is_fraud): {prediction[0]}")
print(f"[Supervised] Exact Boolean Rule: {clf.formula_expr_}")
print(f"[Supervised] Why this decision was made:\n{explanation}")

# =====================================================================
# MODE C: AUTONOMOUS COLD-START (Zero Prior Data -> Live Auto-Distillation)
# =====================================================================
cold_engine = ExactorAccelerator(cold_start=True, auto_evolve_every=5)
live_res = cold_engine.evaluate(new_tx.iloc[0].to_dict(), fast_path=True)
print(f"\n[Cold-Start] Decision: {live_res['decision']} | Route: {live_res['route']}")
print(f"[Cold-Start] Why: {live_res['explicacion_natural']}")

Expected Output

[Unsupervised] Regime: STABLE_PATTERN | Gate: PROCEED

[Supervised] Prediction (is_fraud): 1
[Supervised] Exact Boolean Rule: (~amount_low & ~velocity_1h_high & ~velocity_1h_low & ~device_trust_above_target_median & ~device_trust_low & ~ip_reputation_eq_clean & ip_reputation_eq_suspicious)
[Supervised] Why this decision was made:
1. **What was decided?**
The operation was blocked as a preventive security measure because it was flagged as high risk.

2. **Why?**
- **The device couldn't be trusted:** The device used for this operation had a very low trust score (0.12 out of 1), meaning it didn't look like a device you normally use or one we recognize as safe.
- **The internet connection came from a dangerous source:** The IP address was flagged as malicious, with a very high risk score of 0.95.
- **The activity pattern was unusual:** There were 14 operations in just one hour, which is far more than normal, and the operation came from a high-risk country ($1,850).

3. **What does this mean for you?**
Your operation was not processed, but your account and funds remain safe.

[Cold-Start] Decision: SAFE | Route: JEV_ORACLE
[Cold-Start] Why: Autonomous action [APROBAR_TRANSACCION] executed: Legitimate transaction with confidence (92.0%). Direct pass authorized without friction.

Examples by Domain

• Fraud Detection
• Medical Triage
• Forex Trading
• Quality Monitoring
• Security Logs

Documentation

• Use Case Guide
• Why Exactor Accelerator
• Domain Implementation Guide
• Roadmap v2.0
• Executive Summary

Roadmap

See ROADMAP_V2.md for details.

Contributing

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Architecture & System Design

This architecture integrates the EXACTOR boolean minimization engine (SMLE) with the Jev typed decision model (TypeSafe AI). The system operates under a Live & Incremental Memory paradigm: it starts with optional cold-start historical ingestion and evolves organically with every new query in real time, completely eliminating heavy offline retraining cycles.

       [ PHASE A: INITIAL INGESTION ]
   Historical Files (CSV / JSON / Logs)
                 │
                 ▼
   [ Adaptive Binarization in B^k ]
                 │
                 ▼
   [ EXACTOR Core Engine (Rust/Cloud) ] ──▶ Pure Rules (AND, OR, XOR, NOT)
                 │
                 ▼
   [ Dynamic Exactor ➔ Jev Adapter ]   ──▶ Typed Schema (Noul, Choice, Score)
                 │
                 ▼
       [ PHASE B: REAL-TIME OPERATION ]
   Production Query ──▶ [ Fast-Path Boolean / Jev (0.05-500ms) ]
                                     │
                ┌────────────────────┴────────────────────┐
                ▼                                         ▼
   [ Confidence >= Threshold ]                  [ SQLite WAL Ledger ]
                │                               (Collective Memory)
                ▼                                         │
    [ AUTONOMOUS EXECUTION ]                              ▼
                                                [ Sliding Window ]
                                                          │
                                                          ▼
                                            [ DIFFERENTIAL UPDATE ]
                                                (Hot Evolution)

Operational Workflow

Phase A: Cold-Start & Ingestion

1. Historical Data Load: Users or administrators supply initial records (CSV, JSON, logs, transactions, or tabular features) via the web interface or REST API.
2. Adaptive Binarization: The preprocessing engine transforms continuous and categorical variables into discrete propositions ($0$ and $1$) projected onto the boolean hypercube $\mathbb{B}^k$ ($k \le 64$).
3. Logical Discovery (Exactor Core): The Rust/Cloud engine processes the binarized matrix, distilling an initial set of exact, immutable logical rules (AND, OR, XOR, NOT) with 100% auditability and zero black-box opacity.
4. Jev Schema Calibration: The discovered rules automatically translate into typed question schemas (Choice, Score, Noul) consumed by the Jev API.

Phase B: Continuous Operation & Live Memory (Zero Retraining)

1. Real-World Capture: Each new production query, log event, or interaction enters the runtime in raw or semi-structured form.
2. Ultra-Low Latency Evaluation: Fast-path evaluates the boolean formula in 0.05–0.1 ms ($4,770\times$ speedup); complex or borderline states route to Jev calibrated probability distributions (RLCD - Reinforcement Learning for Calibrated Decisions).
3. Memory Ledger Tracking: Every interaction is automatically logged into a high-concurrency lightweight database (SQLite in WAL mode), building cumulative system memory.
4. Differential Updates: Periodically or on-demand, the engine processes recent sliding windows to update logic rules in-place (hot evolution), allowing organic learning from real-world drift without downtime.

Component Architecture

Component 1: Ingestion & Binarization Subsystem (exactor_accelerator.ingestion)

• Function: Converts continuous and categorical features into clean boolean proposition matrices.
• Inputs: CSV/JSON datasets (at cold-start) or streaming event payloads (in production).
• Outputs: Discretized miniterm matrix with hypercube dimension mapping and target column.
• Key Modules: binarizer.py, loader.py, text_extractor.py.

Component 2: Logic Minimization Engine (exactor_accelerator.core)

• Function: Executes boolean logic minimization using Gray codes and stack-based hypercube reduction.
• Key Characteristics: Native boolean hypercube ($\mathbb{B}^k$) operation without floating-point drift, producing auditable rules.
• Native XOR Support: Detects parity and non-linear algebraic symmetry.
• Key Modules: hypercube.py, exactor_bridge.py.

Component 3: Dynamic Adapter (exactor_accelerator.adapter)

• Function: Translates Exactor boolean formulas into typed question schemas for TypeSafe Jev (typesafe-sdk).
• Payload Structure:

{
  "model": "jev-latest",
  "state": { "event": "Real-time production query data" },
  "questions": {
    "logic_criterion": {
      "type": "noul",
      "instructions": "Is the boolean condition derived from historical analysis satisfied?"
    },
    "recommended_action": {
      "type": "choice",
      "instructions": "Which business action should be executed?",
      "criteria": {
        "AUTONOMOUS_EXECUTION": "High confidence",
        "HUMAN_REVIEW": "Uncertainty / edge case",
        "DISCARD": "Condition not met"
      }
    },
    "criticality_calibration": {
      "type": "score",
      "instructions": "Impact level on a continuous ordinal scale."
    }
  }
}

• Key Modules: jev_schema.py, translator.py.

Component 4: Decision & Live Memory Layer (exactor_accelerator.ledger & exactor_accelerator.engine)

• Function: Delivers calibrated probabilistic responses to clients and records interactions for incremental learning.
• Autonomous Execution: Automatically triggers downstream workflows when confidence exceeds the configured threshold.
• Concurrent Ledger: SQLite optimized with PRAGMA journal_mode = WAL; and PRAGMA synchronous = NORMAL; for non-blocking concurrent writes.
• Key Modules: sqlite_wal.py, jev_client.py, runtime.py.

Project Structure

exactor-accelerator/
├── exactor_accelerator/
│   ├── ingestion/             # Component 1: Ingestion & Binarization
│   │   ├── binarizer.py       # Adaptive hypercube discretizer
│   │   ├── loader.py          # CSV/JSON parsers & synthetic loaders
│   │   └── text_extractor.py  # Unstructured text feature extraction
│   ├── core/                  # Component 2: Exactor Logic Engine
│   │   ├── hypercube.py       # Hypercube, Gray code & stack reduction
│   │   └── exactor_bridge.py  # Dispatcher to exactor.tech Cloud / local
│   ├── adapter/               # Component 3: Exactor -> Jev Adapter
│   │   ├── jev_schema.py      # Noul, Choice, and Score primitives
│   │   └── translator.py      # TypeSafe payload generator
│   ├── ledger/                # Component 4A: Live Memory (SQLite WAL)
│   │   └── sqlite_wal.py      # Write-Ahead Logging persistence
│   ├── engine/                # Component 4B: Runtime & Jev Client
│   │   ├── jev_client.py      # TypeSafe API client & RLCD simulator
│   │   └── runtime.py         # HybridRuntime master orchestrator
│   ├── api/                   # FastAPI REST Service
│   │   └── server.py          # OpenAPI endpoints & static UI hosting
│   ├── web/                   # Control Dashboard (Glassmorphic)
│   │   ├── index.html         # Live telemetry & 4-phase dashboard
│   │   ├── styles.css         # Cyber-logic aesthetic
│   │   └── app.js             # Client logic & WAL stream feed
│   └── data/                  # Embedded sample datasets
├── tests/                     # Automated test suite
│   ├── test_binarizer.py
│   ├── test_exactor_hypercube.py
│   ├── test_jev_adapter.py
│   └── test_live_memory.py
├── run_demo.py                # End-to-end interactive CLI demonstration
├── run_server.py              # Web dashboard & REST API server launcher
└── pyproject.toml             # Standard PEP 621 package specification

Usage Instructions

1. Run Automated Test Suite

python -m pytest tests/ -v

2. Run Interactive CLI Demonstration

Demonstrates the complete end-to-end lifecycle in one command:

python run_demo.py

3. Launch Web Server & Control Dashboard

python run_server.py

• Web Control Panel: http://localhost:8000
• Interactive Swagger Docs: http://localhost:8000/docs

REST API Endpoints