palveron-llamaindex

PALVERON AI Governance adapter for LlamaIndex — RAG-aware governance with per-chunk PII detection, a drop-in CallbackHandler, and full audit trails.

---

Add one callback handler. Every LLM call, every tool invocation, and (uniquely for RAG) every retrieved document chunk is checked against your PALVERON policies. PII in a source document never silently bleeds into your model's context window.

Installation

pip install palveron-llamaindex

Quick Start

from llama_index.core import VectorStoreIndex, Settings, SimpleDirectoryReader
from llama_index.core.callbacks import CallbackManager
from palveron_llamaindex import PalveronCallbackHandler

handler = PalveronCallbackHandler(api_key="pv_live_xxx")
Settings.callback_manager = CallbackManager([handler])

documents = SimpleDirectoryReader("./customer_files").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

# PII in any retrieved chunk → PalveronGovernanceError before synthesis
response = query_engine.query("Summarize the customer file")

What Gets Checked

Event	When	What	Why it matters
LLM	Before each LLM call	Prompt text + chat history	Catches prompt injection / PII at the model boundary
RETRIEVE	After each retrieval	Every retrieved chunk individually	RAG-specific: catches PII in source documents before synthesis
FUNCTION_CALL	Before each tool runs	Tool name + arguments	Stops agents from invoking tools with sensitive args
AGENT_STEP	Each agent reasoning step (opt-in)	Step content	Audit-grade traceability for ReActAgent / function-calling agents

The retrieval check is the differentiator. Every other adapter governs the LLM I/O; LlamaIndex pipelines retrieve from a vector index that may contain PII that was never cleaned. We check it at the latest possible safe point — after retrieval, before synthesis.

Configuration

handler = PalveronCallbackHandler(
    api_key="pv_live_xxx",
    base_url="https://gateway.palveron.com",  # On-prem endpoint
    check_llm=True,              # Verify LLM prompts (default)
    check_retrievals=True,       # Verify retrieved chunks — RAG-specific (default)
    check_tools=True,            # Verify tool inputs (default)
    check_agent_steps=False,     # Verify agent steps (opt-in)
    fail_open=False,             # Block on gateway errors (Enterprise default)
    metadata={"team": "support", "index": "customer_kb"},
)

fail_open semantics:

• False (Enterprise): gateway errors block the call — never trade compliance for uptime.
• True (Community): gateway errors log a warning and let the call proceed.

Retrieval Post-Processor (Alternative)

If you want governance on retrievals without enabling the full callback handler, use the post-processor directly on a query engine:

from palveron_llamaindex import PalveronNodePostprocessor

query_engine = index.as_query_engine(
    node_postprocessors=[PalveronNodePostprocessor(api_key="pv_live_xxx")],
)

# Or drop chunks that needed modification instead of raising
query_engine = index.as_query_engine(
    node_postprocessors=[
        PalveronNodePostprocessor(api_key="pv_live_xxx", drop_modified=True),
    ],
)

Agent Tool

Register Palveron as an explicit tool so an agent can verify content during reasoning:

from llama_index.core.agent import ReActAgent
from palveron_llamaindex import palveron_verify_tool

agent = ReActAgent.from_tools(
    [
        palveron_verify_tool("pv_live_xxx"),
        search_tool,
        email_tool,
    ],
    verbose=True,
)

response = agent.chat("Draft a reply to John, then verify it before sending")

Behaviour on Decisions

Decision	Behaviour
ALLOWED / PASSED	Call proceeds
MODIFIED	Call proceeds; PII-redaction logged. (For retrievals, the original chunk is retained — set drop_modified=True to filter instead.)
FLAGGED	Call proceeds; policy hit is logged
BLOCKED	Raises PalveronGovernanceError
PENDING_APPROVAL	Raises PalveronGovernanceError (queued for human review)
RATE_LIMITED	Raises PalveronGovernanceError (quota hit)

Governance Records

Programmatic access to the audit trail after execution:

print(f"Blocked: {handler.blocked_count}")
print(f"Trace IDs: {handler.trace_ids}")

for record in handler.records:
    print(f"{record.event} [{record.surface}]: {record.decision} ({record.latency_ms:.0f}ms)")

Error Handling

from palveron_llamaindex import PalveronCallbackHandler, PalveronGovernanceError

handler = PalveronCallbackHandler(api_key="pv_live_xxx")
Settings.callback_manager = CallbackManager([handler])

try:
    response = query_engine.query("Find the file for SSN 123-45-6789")
except PalveronGovernanceError as e:
    print(e.decision)   # "BLOCKED"
    print(e.trace_id)   # "trc_abc123"
    print(e.reason)     # "PII detected in retrieved chunk customer_2024_03.txt"

Requirements

• Python 3.10+ (matches llama-index-core>=0.11.0's baseline)
• palveron-sdk >= 1.1.0
• llama-index-core >= 0.11.0

Links

• Documentation
• PALVERON Dashboard
• palveron-sdk (Python)
• GitHub

License

MIT