语义保护AI

spaCy language model (required for syntactic TVE arm)

python -m spacy download en_core_web_sm

Optional: download DeBERTa NLI model (required for FV NLI)

python -c "from sentence_transformers import CrossEncoder; CrossEncoder('cross-encoder/nli-deberta-v3-small')" ```

Requirements:

---

Python Version Requirements

VORTEXRAG requires Python 3.10 or higher. Python 3.11 and 3.12 are fully supported and recommended for best performance. Python 3.9 and below are not supported due to use of match statements and modern type hint syntax.

python --version  # must be 3.10+

Dev install — all extras + test dependencies

pip install "vortexrag[dev]"

After installing the full extras, download required models:

spaCy language model — required for syntactic TVE arm

python -m spacy download en_core_web_sm

Dependency Matrix

3.6 Causal Context Builder (CCB)

Ordered slot injection:

$$W^* = \text{sort\_by}(\tilde{\Phi}) \cap \text{causal\_dependency\_graph}(q)$$

Slot position formula:

$$\text{pos}(c_i) = \text{rank}(\tilde{\Phi}(c_i)) \times \text{causal\_depth}(c_i)$$

• $\text{rank}(\tilde{\Phi}(c_i))$: position in $\tilde{\Phi}$ ranking (1 = highest)
• $\text{causal\_depth}(c_i)$: depth in causal graph (0 = root cause, 1 = immediate effect, ...)

Causal depth assignment algorithm:

1. Extract entities $E_q$ from query
2. Build directed causal graph $G$ over all chunks: edge $(c_i \to c_j)$ if $c_i$ is a causal precondition of $c_j$
3. Assign $\text{depth}(c_i) = $ shortest path from query entity to $c_i$ in $G$
4. Causal verb density bonus: chunks with high causal verb density get $\text{depth} - 1$ (promoted upward)

Deduplication (MMR-style):

$$\text{sim\_dedup}(c_i, c_j) = \cos(v_{\text{sem}}(c_i),\, v_{\text{sem}}(c_j))$$

Chunks with $\text{sim\_dedup} \geq 0.92$ are deduplicated before ordering — the lower-$\tilde{\Phi}$ chunk is removed.

Why this formula? The product balances two objectives: (1) high-$\tilde{\Phi}$ chunks should appear early; (2) root causes should appear before effects. A highly relevant root cause (rank=2, depth=0) gets pos=0 — placed first. A slightly less relevant downstream effect (rank=1, depth=3) gets pos=3 — placed after the root cause, even though its $\tilde{\Phi}$ rank is higher.

"Lost in the Middle" fix (Liu et al., 2023): LLMs attend strongest to content at the beginning and end of context windows. By placing causal depth=0 chunks first (pos formula sends them to position 0), VORTEXRAG ensures root causes receive maximum LLM attention. This is mathematically equivalent to solving the positional bias problem by design.

---

Installation

```bash

Minimal install (numpy only — pure-Python TVE, no SBERT)

pip install vortexrag

Full install with SBERT, spaCy, FAISS, CrossEncoder NLI

pip install "vortexrag[full]"

`CCBBuilder`

class CCBBuilder:
    def build(self, chunks: list[Candidate], query_vec: TVEVector) -> list[OrderedContextSlot]: ...
    def deduplicate(self, chunks: list[Candidate]) -> list[Candidate]: ...
    def to_structured_context(self, slots: list[OrderedContextSlot]) -> list[dict]: ...
    def explain_ordering(self, slots: list[OrderedContextSlot]) -> str: ...
    def causal_chain_summary(self, slots: list[OrderedContextSlot]) -> dict: ...
    def token_budget_usage(self, slots: list[OrderedContextSlot], budget: int = 4096) -> dict: ...

Extended Installation Guide

Option 1: pip (Recommended)

```bash

Minimal install — pure-Python TVE with numpy only

pip install vortexrag

Standard install — SBERT semantic arm included

pip install "vortexrag[sbert]"

Full install — SBERT + spaCy + FAISS + NLI CrossEncoder

pip install "vortexrag[full]"

Install PyTorch with CUDA (for GPU acceleration)

conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

Install FAISS GPU build

conda install -c pytorch faiss-gpu

Install VORTEXRAG and remaining deps via pip

pip install "vortexrag[full]" python -m spacy download en_core_web_sm ```

Option 3: Docker

A pre-built Docker image is available. It bundles all models and dependencies so no internet access is needed at runtime.

```bash

Run as an API server (see Production Deployment section)

docker run -p 8000:8000 \ -v $(pwd)/my_docs:/data \ -e VORTEXRAG_CORPUS=/data \ -e VORTEXRAG_DOMAIN=general \ vigneshwar234/vortexrag:latest serve

**Docker Compose** for a full stack (API + corpus volume):

docker-compose.yml

version: "3.9" services: vortexrag: image: vigneshwar234/vortexrag:latest ports: - "8000:8000" volumes: - ./corpus:/data/corpus - ./index_cache:/data/index environment: - VORTEXRAG_CORPUS=/data/corpus - VORTEXRAG_INDEX_CACHE=/data/index - VORTEXRAG_DOMAIN=general - VORTEXRAG_LOG_LEVEL=INFO command: serve --host 0.0.0.0 --port 8000 restart: unless-stopped ```

Option 4: Install from Source

```bash git clone https://github.com/vignesh2027/VORTEXRAG.git cd VORTEXRAG pip install -e ".[dev]"

Verify installation

pytest tests/ -v ```

Verifying Your Installation

```python import vortexrag print(vortexrag.version)

[WARN] faiss-gpu not installed (using faiss-cpu)

Build index from encoded chunk vectors

retriever.build_index(chunk_vecs) # list[TVEVector]

Use Cases

Quickstart

from vortexrag import VortexRAG

rag = VortexRAG(corpus="your_docs/")
rag.index()
answer = rag.query("What caused the 2008 financial crisis?")
print(answer.answer)
print(f"ESR: {answer.esr:.3f} | ΔR: {answer.delta_r:.4f} | Latency: {answer.latency_ms:.1f}ms")

With custom LLM (OpenAI):

from vortexrag import VortexRAG, VortexRAGConfig
from openai import OpenAI

client = OpenAI()

def llm_fn(context: str, query: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"Answer using only this context:\n\n{context}"},
            {"role": "user", "content": query},
        ]
    )
    return resp.choices[0].message.content

config = VortexRAGConfig(domain="legal")
rag = VortexRAG(corpus="case_files/", config=config, llm_fn=llm_fn)
rag.index()
result = rag.query("Did Brown v. Board apply to public universities before 1964?")
print(result.answer)
print(f"Faithfulness: {result.grounding:.4f} | Iterations: {result.fv_iterations}")

Domain-specific medical configuration:

from vortexrag import VortexRAG, VortexRAGConfig
from core.sdc import SDCConfig
from core.cpg import CPGConfig
from core.rfg import RFGConfig

config = VortexRAGConfig(domain="medical")
config.sdc = SDCConfig(domain="medical")     # tau=0.35 automatically
config.cpg = CPGConfig(theta_cpg=5.0)        # very clean context
config.rfg = RFGConfig(top_m=6, domain="medical")  # more context chunks

rag = VortexRAG(corpus="pubmed_abstracts/", config=config)
rag.index()
result = rag.query("What is the mechanistic difference between mRNA and viral vector vaccines?")

---

Sample Test Cases

Configuration Reference

`VortexRAGConfig`

`TVEConfig`

`VRCConfig`

`SDCConfig`

`CPGConfig`

`RFGConfig`

`CCBConfig`

`FVConfig`

---

Option 2: conda

```bash

Create a dedicated environment

conda create -n vortexrag python=3.11 conda activate vortexrag

Check which optional features are available

from vortexrag.diagnostics import feature_check feature_check()

API Reference

Comprehensive API Reference

Pipeline Overview

Query → TVE (encode) → VRC (retrieve) → SDC (drift filter) → CPG (poison purge)
      → RFG (rank fusion) → CCB (causal order) → LLM → FV (faithfulness check)

---

Compare against flat top-k (diagnostic)

comparison = retriever.compare_with_flat_topk(q_vec, k=10) print(f"VRC retrieves {comparison['additional_relevant']} extra relevant chunks " f"that flat top-k misses")