Metadata-Version: 2.4
Name: llama-index-maskena
Version: 0.1.0
Summary: LlamaIndex integration for Maskena: load documents sanitized for RAG and block prompt injection in retrieved nodes.
Author-email: Maskena <dev@maskena.com>
License-Expression: MIT
Project-URL: Homepage, https://maskena.com
Project-URL: Documentation, https://maskena.com/docs?lang=en
Keywords: llama-index,llamaindex,prompt injection,llm,rag,security,pii
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: maskena<1,>=0.1.0
Requires-Dist: llama-index-core<0.15,>=0.14
Dynamic: license-file

# llama-index-maskena

[LlamaIndex](https://www.llamaindex.ai) integration for [Maskena](https://maskena.com/docs?lang=en): load documents
with hidden text and personal data removed, and stop prompt injection in retrieved nodes before they reach the LLM.

| Component | Where it goes | What it does |
|---|---|---|
| `MaskenaReader` | Ingestion | Loads files through RAG sanitization: only safe content, already split into chunks |
| `MaskenaNodePostprocessor` | Query engine | Drops dangerous retrieved nodes; cleans suspicious ones (indirect prompt injection) |

## Installation

```bash
pip install llama-index-maskena
export MASKENA_API_KEY="sfk_..."     # create a key in the dashboard, under API
```

Requires Python 3.11 or later and `llama-index-core` 0.14.

## Quickstart

```python
from llama_index.core import VectorStoreIndex
from llama_index_maskena import MaskenaNodePostprocessor, MaskenaReader

documents = MaskenaReader().load_data(["contract.pdf", "manual.docx"])
index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine(node_postprocessors=[MaskenaNodePostprocessor()])
response = query_engine.query("How long do refunds take?")
```

## Loading documents

`MaskenaReader` sends each file to Maskena's RAG sanitization. Hidden text (white, microscopic, off-page or covered by
other elements) is removed based on how each page renders, and malicious sentences are removed according to `policy`:

```python
reader = MaskenaReader(policy="redact", ocr="auto", chunk_size=1200, chunk_overlap=150, personal_data=True)
documents = reader.load_data("contract.pdf", extra_info={"tenant": "acme"})
documents = await reader.aload_data(["a.pdf", "b.pdf"])       # files processed in parallel
```

Each chunk becomes a `Document` with `file_path`, `file_name`, `page_start`, `page_end`, `maskena_risk`,
`maskena_status` and `maskena_job_id` in its metadata. The Maskena keys are excluded from the text sent to the LLM and
to the embedding model. Chunks in quarantine (`policy="drop"`) are not returned.

## Guarding retrieved nodes

Documents in an index can carry instructions planted by whoever wrote them. `MaskenaNodePostprocessor` checks every
retrieved node before the LLM reads it:

- `dangerous` nodes are dropped;
- `suspicious` nodes continue with the clean version (dangerous passages removed, personal data replaced by
  placeholders such as `[EMAIL 1]`);
- kept nodes carry `maskena_verdict`, `maskena_score` and `maskena_cleaned` in their metadata.

```python
MaskenaNodePostprocessor(block_on="flagged")                    # also drop suspicious nodes
MaskenaNodePostprocessor(use_clean_text="always")               # remove personal data from every node
MaskenaNodePostprocessor(max_concurrency=8)                     # parallel checks in async query engines
```

| Option | Values | Default |
|---|---|---|
| `block_on` | `"dangerous"`, `"flagged"` (also suspicious), `"never"` | `"dangerous"` |
| `use_clean_text` | `"flagged"`, `"always"`, `"never"` | `"flagged"` |

Texts longer than 32,000 characters are split and checked in parts.

## Configuration and costs

```python
MaskenaNodePostprocessor(api_key="sfk_...", base_url="https://maskena.com", language="en", depth="standard")
```

Each retrieved node uses one text check from the monthly quota, and `MaskenaReader` uses one RAG page per page. To
reuse a configured client, pass `client=maskena.Maskena(...)` and `async_client=maskena.AsyncMaskena(...)`.

## Links

- [API documentation](https://maskena.com/docs?lang=en)
- [Detection accuracy](https://maskena.com/precisao?lang=en)
- [Python SDK](https://pypi.org/project/maskena/)

## License

MIT
