Truthlocks for LlamaIndex

Capture structured evidence about LlamaIndex operations in your Python application. Inspect input/output hashes and execution metadata alongside the original result.

Package: truthlocks-llamaindex · Python: 3.9+ · License: Apache-2.0

Developer documentation · Truthlocks Console

Install

python -m pip install truthlocks-llamaindex

This package re-exports the LlamaIndex integration from maip-ai-connectors and installs its corresponding optional dependencies. Keep compatible versions of the integration and your provider/framework in your application's lockfile.

Run a complete local example

This example creates local receipt data without calling a paid model or submitting anything to Truthlocks. It deliberately sets auto_receipt=False.

from truthlocks_llamaindex import MAIPQueryEngineWrapper
from maip_ai_connectors.config import MAIPConfig

class DemoQueryEngine:
    def query(self, query_str, **kwargs):
        return "A proof bundle contains evidence for a signed record."

wrapped = MAIPQueryEngineWrapper(DemoQueryEngine(), config=MAIPConfig(auto_receipt=False))
print(wrapped.query("What is a proof bundle?"))
receipt = wrapped.get_receipts()[0]
print(receipt.payload_hash)
wrapped.clear_receipts()

Connect your application

Replace DemoQueryEngine() with your configured query engine. The wrapper records the query and response hashes, and retrieval information when source nodes are available. It does not capture every internal model call; use the callback handler with compatible LlamaIndex event instrumentation for additional detail.

Provider credentials belong to the underlying provider client. A Truthlocks key does not authenticate a model provider, and provider charges are separate.

Understand the result

payload_hash is a hash of locally constructed receipt data. It is not a server receipt ID, a signature, proof of transparency-log inclusion, or confirmation that Truthlocks accepted the event. The local receipt has no receipt_id property. Export its structured fields with receipt.model_dump() or receipt.model_dump_json(). Hashing application-supplied data does not independently establish that an AI provider performed an operation or that the output is correct.

API and configuration

Hosted receipt submission

Submit and verify hosted evidence (1.1.0+)

Register a machine identity in your workspace before submission. Set MAIP_AGENT_ID to its identifier and MAIP_API_KEY to a workspace API key with access to machine identities and receipts. Provider keys are separate. A tl_test_ key selects the sandbox host unless MAIP_API_URL overrides it; production defaults to https://api.truthlocks.com/v1. Do not use a tenant header as authentication.

This example submits the local receipt created above only when credentials are set:

import asyncio
import os
from maip_ai_connectors.client import MAIPClient
from maip_ai_connectors.config import MAIPConfig

async def submit_and_verify(local_receipt):
    config = MAIPConfig(agent_id=os.environ["MAIP_AGENT_ID"],
                        api_key=os.environ["MAIP_API_KEY"])
    async with MAIPClient(config) as client:
        stored = await client.create_receipt(local_receipt)
        check = await client.verify_receipt(stored.receipt_id)
        if not check.valid or not check.signature_verified:
            raise RuntimeError(check.reason or check.verdict)
        print(stored.receipt_id, check.verdict)

if os.environ.get("MAIP_API_KEY") and os.environ.get("MAIP_AGENT_ID"):
    asyncio.run(submit_and_verify(receipt))

The server stores integration metadata in a signed MAIP action receipt. Its receipt_id differs from the local payload_hash. Verification checks the signature and current lifecycle state; it does not establish transparency-log inclusion. Old receipts whose signing key was lost return UNVERIFIABLE.

For automatic hooks, enable auto_receipt=True. In synchronous code delivery is confirmed before the hook returns. In asynchronous code, call await wrapper.flush() and await wrapper.aclose() before shutdown; inspect get_submitted_receipts() for server responses. These lifecycle methods apply to AI wrappers/callbacks; data clients use their async context manager or create_receipt_sync() instead. Read retries are bounded; writes are never automatically replayed. After a timeout, check the agent's receipts before retrying. Listing returns up to the latest 100 receipts for one agent, with integration filters applied to that page.

Troubleshooting

No fixed latency, automatic compliance certification, or universal event coverage is promised. Measure overhead in your application and inspect the fields you retain. For support, include the package version and a sanitized reproduction; exclude keys, raw customer content and authentication tokens.