LlamaIndex

instrument_llamaindex is a context manager that registers an EntorinEventHandler on LlamaIndex’s root dispatcher and removes it on exit. Inside the with, LlamaIndex LLMChat*, LLMCompletion*, Retrieval*, and AgentRunStep* events are translated into the Entorin event taxonomy; LLM end events tick the ledger.

from decimal import Decimal
from pydantic import SecretStr

from adapters.llamaindex import instrument_llamaindex
from entorin.auth import Capability, Principal
from entorin.budget import MemoryLedger, OverflowPolicy
from entorin.context import RunContext
from entorin.events import EventBus
from entorin.model.pricing import ConstPricing, Rate

principal = Principal(
    user_id="alice",
    caps=(Capability(kind="model.openai.key", value=SecretStr("sk-...")),),
)
ctx     = RunContext(run_id="run-1", principal=principal)
bus     = EventBus()
ledger  = MemoryLedger()
ledger.set_cap("alice", Decimal("0.50"),
               bucket_id="li-research",
               overflow_policy=OverflowPolicy.FINISH_RUN)
pricing = ConstPricing({"gpt-4o-mini": Rate(
    input_per_mtok=Decimal("0.15"), output_per_mtok=Decimal("0.60"),
)})

with instrument_llamaindex(
    ctx=ctx, bus=bus, ledger=ledger, pricing=pricing,
    bucket_id="li-research",
    retrieval_id="docs",
):
    # LlamaIndex agent / retrieval calls auto-translate
    ...

Event mapping

LlamaIndex event	Entorin event	Side effect
LLMChatStartEvent / LLMCompletionStartEvent	llm.call.pre	stash model id under span key
LLMChatEndEvent / LLMCompletionEndEvent	llm.call.post	Ledger.debit from response.raw
RetrievalStartEvent	retrieval.query	—
RetrievalEndEvent	retrieval.result	hit count from event.nodes
AgentRunStepStartEvent	node.pre	—
AgentRunStepEndEvent	node.post	—

retrieval_id (default "llamaindex") is the identifier published in retrieval events. Override when wiring multiple LlamaIndex stacks under one run.

Token extraction

A runnable demo with synthetic dispatcher events: examples/llamaindex_qa.py.