Metadata-Version: 2.4
Name: veloxs-nexus
Version: 2.3.0
Summary: A headless, layered data intelligence, PII sanitization, and 3072D vector projection engine.
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.7.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.28.0
Provides-Extra: postgres
Requires-Dist: pgvector>=0.2.5; extra == "postgres"
Requires-Dist: psycopg2-binary>=2.9.9; extra == "postgres"
Requires-Dist: sqlalchemy>=2.0.0; extra == "postgres"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.1; extra == "yaml"
Dynamic: license-file

# 🏛️ Nexus Enterprise AI (`veloxs-nexus`)

[![PyPI Version](https://img.shields.io/badge/pypi-v2.3.0-blue.svg)](https://pypi.org/project/veloxs-nexus/)
[![Python Versions](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://pypi.org/)
[![License: Proprietary](https://img.shields.io/badge/license-Veloxs--AI--Proprietary-red.svg)](LICENSE)
[![Vector Dimension](https://img.shields.io/badge/vector-3072D-green.svg)](#-vector-and-chunking-specification)
[![Concurrency](https://img.shields.io/badge/thread--safety-threading.Lock-brightgreen.svg)](#)

A high-performance, headless, layered data intelligence, format-aware chunking, PII sanitization, and **3072-dimensional vector projection** engine for enterprise AI applications.

---

## 📦 Installation

```bash
# Standard in-memory installation
pip install veloxs-nexus

# With PostgreSQL + pgvector support
pip install veloxs-nexus[postgres]

# With YAML configuration support
pip install veloxs-nexus[yaml]
```

---

## ⚡ Quick Start (`import nexus`)

```python
import nexus

# 1. Initialize client in pure in-memory mode (zero disk I/O, serverless safe)
client = nexus.NexusClient(tenant_id="org-acme", in_memory_only=True)

# 2. Process tabular CSV, JSON, Markdown, or Text into 3072D vectors + PII-masked chunks
doc = client.process_document(
    document_id="doc-001",
    name="department_budgets.csv",
    text="""department,quarter,budget_usd,status
Engineering,Q3 2025,1250000,Completed
Security,Q3 2025,350000,Completed""",
    file_type="csv"
)

print(f"Total chunks: {len(doc.chunks)}")
print(f"First chunk text: {doc.chunks[0].text}")
print(f"Is Tabular: {doc.chunks[0].metadata['is_tabular']}")
print(f"Embedding length: {len(doc.chunks[0].embedding)}")  # 3072 normalized floats

# 3. Ingest and execute fail-closed grounded guardrail Q&A
client.index_document(doc)
response = client.ask("What is the engineering budget?")
print(f"Decision: {response.decision}")
print(f"Answer: {response.answer}")
```

---

## 🏛️ Modular Sub-Layer Architecture

`veloxs-nexus` exports 7 decoupled sub-layers under the `nexus.*` namespace:

| Submodule | Purpose & Capabilities | Example Import |
|---|---|---|
| **`nexus.client`** | Top-level in-memory orchestrator | `from nexus import NexusClient` |
| **`nexus.processing`** | Format-aware chunking (CSV, JSON, Markdown) & FPE PAN tokenizers | `from nexus.processing.engine import ProcessingEngine` |
| **`nexus.retrieval`** | 3072D multi-gram embedding, hybrid RRF search, and knowledge graph | `from nexus.retrieval.engine import RetrievalEngine` |
| **`nexus.guardrails`** | Luhn credit card & PII masking, prompt injection defense, grounded RAG | `from nexus.guardrails.engine import GuardrailsEngine` |
| **`nexus.security`** | Multi-tenant RBAC, Fernet symmetric encryption & HKDF dynamic salting | `from nexus.security.encryption import encrypt_text` |
| **`nexus.experience`** | REST API service, assistant sessions, channel adapters | `from nexus.experience.service import ExperienceService` |
| **`nexus.pipeline`** | Batch file ingestion, API connectors, and CDC change data capture | `from nexus.pipeline.batch import run_batch_job` |
| **`nexus.observability`** | Distributed trace spans, latency metrics, and error alerting | `from nexus.observability.service import ObservabilityService` |
| **`nexus.database`** | PostgreSQL `pgvector` DDL schema and SQLAlchemy column types | `from nexus.database import PGVECTOR_DDL_SCHEMA` |

---

## 🗄️ PostgreSQL + pgvector Schema

For production database persistence, use the provided schema:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE knowledge_documents (
    document_id         VARCHAR(128) PRIMARY KEY,
    name                VARCHAR(255) NOT NULL,
    file_type           VARCHAR(32) NOT NULL,
    file_size_bytes     BIGINT NOT NULL,
    content_hash        VARCHAR(64) NOT NULL,
    classification      VARCHAR(64) DEFAULT 'general',
    created_at          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE knowledge_chunks (
    chunk_id            VARCHAR(128) PRIMARY KEY,
    document_id         VARCHAR(128) NOT NULL REFERENCES knowledge_documents(document_id) ON DELETE CASCADE,
    source_job          VARCHAR(64) NOT NULL,
    chunk_index         INTEGER NOT NULL,
    chunk_text          TEXT NOT NULL,
    metadata            JSONB DEFAULT '{}'::jsonb,
    embedding           VECTOR(3072) NOT NULL,
    created_at          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_knowledge_chunks_embedding_hnsw 
ON knowledge_chunks 
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
```

---

## 🔐 Multi-Tenant Cryptographic Isolation

Each tenant's encryption and tokenization uses dynamic salt derivation:
38524\text{salt} = \text{HKDF-SHA256}(\text{"nexus-salt-"} \parallel \text{tenant\_id} \parallel \text{"-"} \parallel \text{key\_id})38524

This guarantees that two different tenants processing the same sensitive data produce cryptographically distinct ciphertexts.

---

## 📄 License

Proprietary and confidential software. Copyright © 2026 Veloxs AI Inc. All rights reserved.
See [LICENSE](LICENSE) for license terms.
