integration: Create LlamaIndex Tool/Agent Guard Plugin

[akarlaraytu]

🚧 LlamaIndex Integration Plugin for CSL-Core

📝 Context

CSL-Core provides a universal safety layer for AI agents via ChimeraPlugin in base.py.\ We currently support Lang, but LlamaIndex is heavily used for RAG-based agents and data engines.

To expand framework coverage, we need a lightweight plugin in:

chimera_core/plugins/llamaindex.py

This plugin must wrap LlamaIndex tools (starting with FunctionTool, optionally QueryEngineTool) so they cannot execute if a CSL policy is violated.

The enforcement lifecycle (normalize → verify → visualize) already exists in base.py.\ The LlamaIndex plugin should only implement the framework-specific interception layer.

🎯 Goal

Create:

• GuardedLlamaTool
• guard_tools() helper

Design philosophy must mirror the LangChain plugin:

• Composition over inheritance
• Fail-closed semantics
• Optional dependency
• Support for context injection and custom context mappers

---

🏗️ Implementation Requirements

1️⃣ Create Plugin File

chimera_core/plugins/llamaindex.py

---

2️⃣ Execution Interception (Critical)

LlamaIndex tools execute primarily through:

• call(...)
• acall(...)
• __call__ (delegates to call)

The wrapper MUST:

• Intercept before execution
• Call self._plugin.run_guard(tool_input, extra_context=...)
• Raise ChimeraError on violation
• Only execute original tool if policy allows

Both sync and async paths must be supported.

---

3️⃣ Context Mapping

Default behavior:

tool_input = {
    "args": args,
    "kwargs": kwargs
}

Additionally: - Merge kwargs into the top-level context for ergonomic CSL variable matching. - Support optional context_mapper - Support optional inject - Support optional tool_field (inject tool name into context)

This ensures parity with the LangChain plugin.

---

4️⃣ Composition Over Inheritance

Use composition to wrap LlamaIndex tools. Do NOT subclass framework internals directly.

---

5️⃣ Optional Dependency

LlamaIndex must remain optional:

try:
    from llama_index.core.tools import BaseTool
except ImportError:
    raise ImportError(
        "LlamaIndex required. Install with: pip install llama-index-core"
    )

---

🧪 Tests

Add:

tests/integration/test_llamaindex.py

Test scenarios:

• ✅ Allowed tool call executes normally
• ❌ Policy violation raises ChimeraError
• ❌ Tool is NOT executed when blocked
• ✅ Custom context_mapper works
• ✅ Async acall is enforced

---

📦 Example

Add demo:

examples/integrations/llamaindex_agent_demo.py

Demonstrate:

• Simple FunctionTool
• Basic CSL policy
• Block + allow cases

---

✅ Acceptance Criteria

• chimera_core/plugins/llamaindex.py created
• Exposes guard_tools() API
• Enforces policy before execution
• Supports sync + async
• Supports inject + context_mapper + tool_field
• Raises ChimeraError on violation
• Fails safely if dependency missing
• Integration test added
• Example script added

---

🔐 Security Model

• Fail-closed
• Deterministic enforcement
• No execution before verification
• Consistent lifecycle with ChimeraPlugin

---

🚀 Why This Matters

LlamaIndex is widely used for RAG agents and data-driven AI systems.

Adding this plugin:

• Expands CSL-Core's ecosystem reach
• Strengthens "Universal Safety Layer" positioning
• Keeps enforcement consistent across AI frameworks
• Moves toward framework-agnostic AI governance

[Flames4fun]

Hi! I’d love to take this issue if it’s still available. :))
I’ve been working with CSL-Core recently and this LlamaIndex integration is exactly the kind of work I want to contribute.
If that works for you, please assign it to me. Thanks for let me help in this awesome project!

[akarlaraytu]

Hey @Flames4fun welcome back! 🚀

I was thrilled to see your VS Code extension, and I'm even more excited to have you tackle the LlamaIndex integration. You are officially assigned!

Since you've already been working with CSL-Core, you know the drill. The 'chimera_core/plugins/langchain.py' implementation is your best friend here as a reference for the 'ChimeraPlugin' enforcement lifecycle (normalize -> verify).

The most critical part for LlamaIndex will be gracefully intercepting the call/acall methods of BaseTool while ensuring the context_mapper and inject behaviors remain consistent with our fail-closed philosophy.

Feel free to open a Draft PR as soon as you have a working skeleton. I'd be happy to review it iteratively and brainstorm any blockers with you.

Let's build AI safety language together. Happy coding! 🎉