Skip to content

Commit 736f2cb

Browse files
asiridalugodaasiridalugoda
committed
docs: add LlamaIndex integration to main README
- Badges: LangChain, LlamaIndex, llama-index-callbacks-hdp PyPI - Packages table: llama-index-callbacks-hdp and hdp-llamaindex rows - Install: LlamaIndex pip install section - Integration section: all three hook points with code examples and design considerations table - Releasing: hdp-langchain, llama-index-callbacks-hdp, hdp-llamaindex tag commands - ReleaseGuard: local vet commands for langchain and llama-index-callbacks-hdp
1 parent fc6ad34 commit 736f2cb

1 file changed

Lines changed: 113 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ _Every action an AI agent takes, traceable back to the human who authorized it._
2323
[![CrewAI](https://img.shields.io/badge/CrewAI-integration-f43f5e?style=flat-square)](./packages/hdp-crewai)
2424
[![Grok / xAI](https://img.shields.io/badge/Grok%20%2F%20xAI-integration-000000?style=flat-square)](./packages/hdp-grok)
2525
[![AutoGen](https://img.shields.io/badge/AutoGen-integration-10b981?style=flat-square)](./packages/hdp-autogen)
26+
[![LangChain](https://img.shields.io/badge/LangChain-integration-1c7c4c?style=flat-square)](./packages/hdp-langchain)
27+
[![LlamaIndex](https://img.shields.io/badge/LlamaIndex-integration-7c3aed?style=flat-square)](./packages/llama-index-callbacks-hdp)
28+
[![PyPI llama-index-callbacks-hdp](https://img.shields.io/pypi/v/llama-index-callbacks-hdp?style=flat-square&logo=pypi&logoColor=white&color=7c3aed&label=llama-index-callbacks-hdp)](https://pypi.org/project/llama-index-callbacks-hdp/)
2629
[![ReleaseGuard](https://img.shields.io/badge/artifacts-ReleaseGuard%20vetted-22c55e?style=flat-square&logo=shield)](https://github.com/Helixar-AI/ReleaseGuard)
2730
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19332023-blue?style=flat-square)](https://doi.org/10.5281/zenodo.19332023)
2831
[![arXiv](https://img.shields.io/badge/arXiv-2604.04522-b31b1b?style=flat-square)](https://arxiv.org/abs/2604.04522)
@@ -58,6 +61,8 @@ When a person authorizes an AI agent to act — and that agent delegates to anot
5861
| [`hdp-autogen`](./packages/hdp-autogen) | [PyPI](https://pypi.org/project/hdp-autogen/) | Python | AutoGen | AutoGen middleware — attaches HDP to any AutoGen agent or GroupChat |
5962
| [`@helixar_ai/hdp-autogen`](./packages/hdp-autogen-ts) | [npm](https://www.npmjs.com/package/@helixar_ai/hdp-autogen) | TypeScript | AutoGen | AutoGen middleware — HdpAgentWrapper + hdpMiddleware for AutoGen flows |
6063
| [`hdp-langchain`](./packages/hdp-langchain) | [PyPI](https://pypi.org/project/hdp-langchain/) | Python | LangChain / LangGraph | LangChain middleware — attaches HDP to any chain, agent, or LangGraph node |
64+
| [`llama-index-callbacks-hdp`](./packages/llama-index-callbacks-hdp) | [PyPI](https://pypi.org/project/llama-index-callbacks-hdp/) | Python | LlamaIndex | LlamaIndex integration — callback handler, instrumentation dispatcher, node postprocessor |
65+
| [`hdp-llamaindex`](./packages/hdp-llamaindex) | [PyPI](https://pypi.org/project/hdp-llamaindex/) | Python | LlamaIndex | Metapackage — `pip install hdp-llamaindex` for HDP-first users |
6166

6267
## Install
6368

@@ -103,6 +108,14 @@ pip install hdp-autogen
103108
pip install hdp-langchain
104109
```
105110

111+
**Python / LlamaIndex**
112+
113+
```bash
114+
pip install llama-index-callbacks-hdp
115+
# or, from the HDP side:
116+
pip install hdp-llamaindex
117+
```
118+
106119
---
107120

108121
## Quickstart — TypeScript
@@ -405,6 +418,80 @@ print(result.valid, result.hop_count, result.violations)
405418

406419
---
407420

421+
## LlamaIndex Integration
422+
423+
`llama-index-callbacks-hdp` covers all three LlamaIndex hook points. Use whichever layer fits your pipeline — they share the same ContextVar-backed session so all three can be active simultaneously.
424+
425+
### Option 1 — Instrumentation dispatcher (recommended, LlamaIndex ≥0.10.20)
426+
427+
```python
428+
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
429+
from llama_index.callbacks.hdp import HdpInstrumentationHandler, HdpPrincipal, ScopePolicy, verify_chain
430+
431+
private_key = Ed25519PrivateKey.generate()
432+
433+
HdpInstrumentationHandler.init(
434+
signing_key=private_key.private_bytes_raw(),
435+
principal=HdpPrincipal(id="alice@corp.com", id_type="email"),
436+
scope=ScopePolicy(
437+
intent="Research RAG pipeline",
438+
authorized_tools=["web_search", "retriever"],
439+
max_hops=10,
440+
),
441+
on_token_ready=lambda token: print(token["header"]["token_id"]),
442+
)
443+
# All subsequent LlamaIndex queries are now covered — no further changes required
444+
```
445+
446+
### Option 2 — Legacy CallbackManager
447+
448+
```python
449+
from llama_index.callbacks.hdp import HdpCallbackHandler, HdpPrincipal, ScopePolicy
450+
from llama_index.core import Settings
451+
from llama_index.core.callbacks import CallbackManager
452+
453+
handler = HdpCallbackHandler(
454+
signing_key=private_key.private_bytes_raw(),
455+
principal=HdpPrincipal(id="alice@corp.com", id_type="email"),
456+
scope=ScopePolicy(intent="Research pipeline"),
457+
)
458+
Settings.callback_manager = CallbackManager([handler])
459+
```
460+
461+
### Option 3 — Node postprocessor (RAG retrieval enforcement)
462+
463+
```python
464+
from llama_index.callbacks.hdp import HdpNodePostprocessor
465+
466+
postprocessor = HdpNodePostprocessor(
467+
signing_key=private_key.private_bytes_raw(),
468+
strict=False,
469+
check_data_classification=True,
470+
)
471+
query_engine = index.as_query_engine(node_postprocessors=[postprocessor])
472+
```
473+
474+
### Verifying the chain
475+
476+
```python
477+
from llama_index.callbacks.hdp import verify_chain
478+
479+
result = verify_chain(token_dict, private_key.public_key())
480+
print(result.valid, result.hop_count, result.violations)
481+
```
482+
483+
| # | Consideration | Behaviour |
484+
|---|---|---|
485+
| 1 | **Hook coverage** | Instrumentation dispatcher captures `QueryStartEvent`, `AgentToolCallEvent`, `LLMChatStartEvent`, `QueryEndEvent`. Callback handler covers legacy `FUNCTION_CALL` and `LLM` events. |
486+
| 2 | **Shared session** | All three layers read/write the same `ContextVar` — a token issued by the instrumentation handler is visible to the node postprocessor in the same asyncio task. |
487+
| 3 | **Scope enforcement** | `strict=True` raises `HDPScopeViolationError` on out-of-scope tool calls; default logs and records in the audit trail. |
488+
| 4 | **Data classification** | Postprocessor checks token `data_classification` against a 4-level hierarchy: `public < internal < confidential < restricted`. |
489+
| 5 | **Observability overlap** | HDP complements Arize Phoenix and Langfuse — they record *what* happened; HDP records *who authorized it* with a cryptographic proof. |
490+
491+
→ [Full LlamaIndex integration docs](./packages/llama-index-callbacks-hdp/README.md)
492+
493+
---
494+
408495
## Key Management
409496

410497
HDP ships a `KeyRegistry` for `kid → publicKey` resolution and a well-known endpoint format for automated key distribution.
@@ -620,6 +707,30 @@ git tag python/hdp-autogen/v0.1.2 && git push origin python/hdp-autogen/v0.1.2
620707

621708
Pipeline: `test-hdp-autogen` → `vet-hdp-autogen` (ReleaseGuard) → `publish-hdp-autogen`
622709

710+
### hdp-langchain → PyPI
711+
712+
```bash
713+
git tag python/hdp-langchain/v0.1.1 && git push origin python/hdp-langchain/v0.1.1
714+
```
715+
716+
Pipeline: `test-hdp-langchain` → `vet-hdp-langchain` (ReleaseGuard) → `publish-hdp-langchain`
717+
718+
### llama-index-callbacks-hdp → PyPI
719+
720+
```bash
721+
git tag python/llama-index-callbacks-hdp/v0.1.1 && git push origin python/llama-index-callbacks-hdp/v0.1.1
722+
```
723+
724+
Pipeline: `test-llama-index-callbacks-hdp` → `vet-llama-index-callbacks-hdp` (ReleaseGuard) → `publish-llama-index-callbacks-hdp`
725+
726+
### hdp-llamaindex → PyPI
727+
728+
```bash
729+
git tag python/hdp-llamaindex/v0.1.1 && git push origin python/hdp-llamaindex/v0.1.1
730+
```
731+
732+
Pipeline: `test-hdp-llamaindex` → `vet-hdp-llamaindex` (ReleaseGuard) → `publish-hdp-llamaindex`
733+
623734
### Artifact vetting — ReleaseGuard
624735

625736
Every artifact is scanned by [ReleaseGuard](https://github.com/Helixar-AI/ReleaseGuard) before it reaches PyPI or npm — checking for secrets, unexpected files, license compliance, and generating a CycloneDX SBOM. The exact vetted artifact is what gets published. If ReleaseGuard fails, the publish job never runs.
@@ -629,6 +740,8 @@ Every artifact is scanned by [ReleaseGuard](https://github.com/Helixar-AI/Releas
629740
cd packages/hdp-grok && python -m build && releaseguard check ./dist
630741
cd packages/hdp-crewai && python -m build && releaseguard check ./dist
631742
cd packages/hdp-autogen && python -m build && releaseguard check ./dist
743+
cd packages/hdp-langchain && python -m build && releaseguard check ./dist
744+
cd packages/llama-index-callbacks-hdp && python -m build && releaseguard check ./dist
632745
cd packages/hdp-autogen-ts && npm run build && releaseguard check ./dist
633746
```
634747

0 commit comments

Comments
 (0)