ory-llamaindex 0.13.9__tar.gz

ory_llamaindex-0.13.9/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.local
+
+# Python (uv workspace under python/)
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+*.pyc
+
+# Debug logs
+*.log
+
+# Harness sandbox dirs
+.sandbox/
+
+# Staged install-surface repo contents (see scripts/sync-install-surfaces.mjs)
+.install-surfaces/
+
+# Local dev environment (local Ory stack + Verdaccio registry)
+.ory-dev/
+
+# Worktrees for changes
+.worktrees/
+.claude/worktrees/
+
+# Gemini CLI extension assets — materialized at install time from
+# @ory/argus templates. The repo source is the canonical templates;
+# these subdirs are generated wherever the install runs.
+packages/gemini-cli/gemini-extension/skills/
+packages/gemini-cli/gemini-extension/commands/

ory_llamaindex-0.13.9/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: ory-llamaindex
+Version: 0.13.9
+Summary: Ory Agent Security for LlamaIndex — per-tool authorization, tracing, and identity propagation by wrapping FunctionTools. Built on ory-argus.
+Author: Ory
+License-Expression: Apache-2.0
+Keywords: agent,ai,authorization,llamaindex,ory,permissions
+Requires-Python: >=3.10
+Requires-Dist: llama-index-core>=0.11
+Requires-Dist: ory-argus<1,>=0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ory-llamaindex
+
+Ory Agent Security for [LlamaIndex](https://docs.llamaindex.ai).
+
+Wraps your LlamaIndex tools so every call is authorized against Ory Permissions, traced, and
+tied to the user → agent identity — built on [`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-llamaindex
+```
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from ory_llamaindex import guard_tools
+
+agent = FunctionAgent(tools=guard_tools([search_tool, email_tool]), llm=llm)
+```
+
+In **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a denied tool raises an error surfaced to
+the agent; the tool never runs. In **observe** mode (default) it runs and a
+`permission.observe_deny` span is recorded.
+
+For tracing across paths that bypass the wrapped tools, register the instrumentation handler:
+
+```python
+from llama_index.core.instrumentation import get_dispatcher
+from ory_llamaindex import ory_event_handler
+get_dispatcher().add_event_handler(ory_event_handler())
+```
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`.

ory_llamaindex-0.13.9/README.md

@@ -0,0 +1,31 @@
+# ory-llamaindex
+
+Ory Agent Security for [LlamaIndex](https://docs.llamaindex.ai).
+
+Wraps your LlamaIndex tools so every call is authorized against Ory Permissions, traced, and
+tied to the user → agent identity — built on [`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-llamaindex
+```
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from ory_llamaindex import guard_tools
+
+agent = FunctionAgent(tools=guard_tools([search_tool, email_tool]), llm=llm)
+```
+
+In **enforce** mode (`ORY_PERMISSION_MODE=enforce`) a denied tool raises an error surfaced to
+the agent; the tool never runs. In **observe** mode (default) it runs and a
+`permission.observe_deny` span is recorded.
+
+For tracing across paths that bypass the wrapped tools, register the instrumentation handler:
+
+```python
+from llama_index.core.instrumentation import get_dispatcher
+from ory_llamaindex import ory_event_handler
+get_dispatcher().add_event_handler(ory_event_handler())
+```
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`.

ory_llamaindex-0.13.9/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ory-llamaindex"
+version = "0.13.9"
+description = "Ory Agent Security for LlamaIndex — per-tool authorization, tracing, and identity propagation by wrapping FunctionTools. Built on ory-argus."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Ory" }]
+keywords = ["ory", "llamaindex", "authorization", "agent", "ai", "permissions"]
+dependencies = [
+    "ory-argus>=0.8,<1",
+    "llama-index-core>=0.11",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ory_llamaindex"]

ory_llamaindex-0.13.9/src/ory_llamaindex/__init__.py

@@ -0,0 +1,14 @@
+"""Ory Agent Security for LlamaIndex.
+
+    from ory_llamaindex import guard_tools
+
+    agent = FunctionAgent(tools=guard_tools([search_tool, email_tool]), llm=llm)
+"""
+
+from __future__ import annotations
+
+from .tools import guard_tool_async_fn, guard_tool_fn, guard_tools, ory_event_handler
+
+__version__ = "0.13.9"
+
+__all__ = ["guard_tools", "guard_tool_fn", "guard_tool_async_fn", "ory_event_handler", "__version__"]

ory_llamaindex-0.13.9/src/ory_llamaindex/tools.py

@@ -0,0 +1,209 @@
+"""Ory Agent Security for LlamaIndex.
+
+LlamaIndex's per-tool gate point is the ``FunctionTool``'s underlying callables.
+``guard_tools(tools)`` wraps each tool's sync function (``_fn`` / ``fn``, the ``tool.call()``
+path) *and* its async function (``_async_fn`` / ``async_fn``, the ``tool.acall()`` path used
+by FunctionAgent workflows) so every call is authorized against Ory Permissions, traced, and
+(on first call) preceded by the Ory session gates:
+
+  - allow / observe / fail-open / interactive → run the tool and record ``tool.complete``.
+  - deny (enforce) → raise ``OryDenialError`` so the agent surfaces the denial and the tool
+    never runs.
+
+Pair with :func:`ory_event_handler` (LlamaIndex instrumentation dispatcher) for trace-only
+coverage of paths that bypass the wrapped tools. Gate logic lives in ``ory_argus``;
+``llama_index`` is imported lazily.
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from ory_argus import (
+    DenialContext,
+    GateResult,
+    OryAgentClient,
+    OryDenialError,
+    complete,
+    gate,
+    session_start,
+)
+
+HARNESS = "llamaindex"
+
+
+def _gate_or_deny(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    args: tuple,
+    kwargs: dict,
+    can_block: bool,
+    project_url: str | None,
+    state: dict,
+) -> None:
+    """Run session-start (once) + the permission gate; raise OryDenialError on enforce-deny."""
+    if not state.get("started"):
+        state["started"] = True
+        try:
+            session_start(client, harness=HARNESS, project_url=project_url)
+        except Exception as err:  # noqa: BLE001
+            client.logger.warn("session_start.failed", {"message": str(err)})
+    result: GateResult = gate(
+        client, harness=HARNESS, tool_name=tool_name,
+        tool_args={"args": args, "kwargs": kwargs}, can_block=can_block,
+    )
+    if result.blocked:
+        raise OryDenialError(
+            DenialContext(tool=tool_name, subject_id=result.subject, namespace=result.namespace)
+        )
+
+
+def guard_tool_fn(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    fn: Callable[..., Any],
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_state: dict | None = None,
+) -> Callable[..., Any]:
+    """Return a gated wrapper around a tool callable. SDK-free — testable directly."""
+    state = _session_state if _session_state is not None else {}
+
+    def _wrapped(*args: Any, **kwargs: Any) -> Any:
+        _gate_or_deny(
+            client, tool_name=tool_name, args=args, kwargs=kwargs,
+            can_block=can_block, project_url=project_url, state=state,
+        )
+        output = fn(*args, **kwargs)
+        complete(client, tool_name=tool_name, output=output)
+        return output
+
+    return _wrapped
+
+
+def guard_tool_async_fn(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    fn: Callable[..., Any],
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_state: dict | None = None,
+) -> Callable[..., Any]:
+    """Return a gated *async* wrapper around a tool's async callable (``tool.acall()`` path).
+
+    Same semantics as :func:`guard_tool_fn` — the gate runs (and an enforce-deny raises
+    ``OryDenialError``) BEFORE the tool body executes; observe/fail-open proceed with spans.
+    """
+    state = _session_state if _session_state is not None else {}
+
+    async def _awrapped(*args: Any, **kwargs: Any) -> Any:
+        _gate_or_deny(
+            client, tool_name=tool_name, args=args, kwargs=kwargs,
+            can_block=can_block, project_url=project_url, state=state,
+        )
+        output = fn(*args, **kwargs)
+        if inspect.isawaitable(output):
+            output = await output
+        complete(client, tool_name=tool_name, output=output)
+        return output
+
+    return _awrapped
+
+
+def _warn_wrap_failed(client: OryAgentClient, event: str, tool_name: str, err: Exception) -> None:
+    """Wrapping failed: the tool will run UNGATED. Log + always warn on stderr (never stdout)."""
+    client.logger.warn(event, {"tool": tool_name, "message": str(err)})
+    print(
+        f"[ory] WARNING: failed to wrap tool '{tool_name}' ({err}); "
+        "it will run UNGATED by Ory permission checks.",
+        file=sys.stderr,
+    )
+
+
+def _tool_name(tool: Any) -> str:
+    meta = getattr(tool, "metadata", None)
+    return (
+        getattr(meta, "name", None)
+        or getattr(tool, "name", None)
+        or type(tool).__name__
+    )
+
+
+def guard_tools(
+    tools: list,
+    *,
+    client: OryAgentClient | None = None,
+    can_block: bool = True,
+    project_url: str | None = None,
+) -> list:
+    """Wrap each LlamaIndex tool's sync AND async callables with the Ory gate. Returns the same list."""
+    c = client or OryAgentClient.from_env(HARNESS)
+    state: dict = {}
+    for tool in tools:
+        name = _tool_name(tool)
+
+        # Sync path: tool.call() → _fn / fn.
+        fn = getattr(tool, "_fn", None) or getattr(tool, "fn", None)
+        if callable(fn):
+            wrapped = guard_tool_fn(
+                c, tool_name=name, fn=fn, can_block=can_block,
+                project_url=project_url, _session_state=state,
+            )
+            try:
+                if getattr(tool, "_fn", None) is not None:
+                    tool._fn = wrapped  # type: ignore[attr-defined]
+                else:
+                    tool.fn = wrapped  # type: ignore[attr-defined]
+            except Exception as err:  # noqa: BLE001
+                _warn_wrap_failed(c, "llamaindex.wrap_tool.failed", name, err)
+
+        # Async path: tool.acall() → _async_fn / async_fn. FunctionTool.from_defaults
+        # materializes _async_fn from the ORIGINAL fn, so wrapping _fn alone leaves
+        # acall() (the FunctionAgent workflow path) ungated.
+        afn = getattr(tool, "_async_fn", None) or getattr(tool, "async_fn", None)
+        if callable(afn):
+            awrapped = guard_tool_async_fn(
+                c, tool_name=name, fn=afn, can_block=can_block,
+                project_url=project_url, _session_state=state,
+            )
+            try:
+                if getattr(tool, "_async_fn", None) is not None:
+                    tool._async_fn = awrapped  # type: ignore[attr-defined]
+                else:
+                    tool.async_fn = awrapped  # type: ignore[attr-defined]
+            except Exception as err:  # noqa: BLE001
+                _warn_wrap_failed(c, "llamaindex.wrap_async_tool.failed", name, err)
+    return tools
+
+
+def ory_event_handler(*, client: OryAgentClient | None = None):
+    """Build a LlamaIndex instrumentation event handler that traces tool calls (trace-only)."""
+    from llama_index.core.instrumentation.event_handlers import BaseEventHandler  # type: ignore
+
+    c = client or OryAgentClient.from_env(HARNESS)
+
+    class _OryEventHandler(BaseEventHandler):  # type: ignore[misc]
+        @classmethod
+        def class_name(cls) -> str:
+            return "OryEventHandler"
+
+        def handle(self, event, **kwargs):  # noqa: ANN001
+            name = type(event).__name__
+            if "ToolCall" in name and "Result" not in name:
+                c.tracer.record(
+                    "tool.invoke", "ok",
+                    attributes={"toolName": getattr(event, "tool_name", "unknown"), "source": "event"},
+                )
+            elif "ToolCall" in name and "Result" in name:
+                c.tracer.record("tool.complete", "ok", attributes={"source": "event"})
+
+    return _OryEventHandler()
+
+
+__all__ = ["HARNESS", "guard_tool_async_fn", "guard_tool_fn", "guard_tools", "ory_event_handler"]

ory_llamaindex-0.13.9/tests/test_realsdk.py

@@ -0,0 +1,73 @@
+"""Real-SDK test: wrap an actual LlamaIndex ``FunctionTool`` and enforce.
+
+Runs only when ``llama_index.core`` is importable; the default workspace venv skips it.
+Complements ``test_tools.py`` (fake tool): validates that wrapping a *real* ``FunctionTool``'s
+callable actually intercepts it. The permission decision is stubbed (no backend).
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+pytest.importorskip("llama_index.core")
+
+from llama_index.core.tools import FunctionTool  # noqa: E402
+
+from ory_argus.adapters import GateResult  # noqa: E402
+from ory_argus.denial import OryDenialError  # noqa: E402
+from ory_argus.permissions import PermissionDecision  # noqa: E402
+from ory_argus.testing import create_mock_client  # noqa: E402
+from ory_llamaindex import guard_tools  # noqa: E402
+from ory_llamaindex import tools as tools_mod  # noqa: E402
+
+
+def _stub_gate(monkeypatch, *, blocked):
+    monkeypatch.setattr(
+        tools_mod, "gate",
+        lambda client, **kw: GateResult(
+            proceed=not blocked, blocked=blocked,
+            decision=PermissionDecision(kind="deny" if blocked else "allow"),
+            subject="User:t", namespace="AgentTools",
+            denial_message="Ory: permission denied" if blocked else None,
+        ),
+    )
+
+
+def _real_tool():
+    return FunctionTool.from_defaults(fn=lambda: "RAN", name="MyRealTool")
+
+
+def test_real_functiontool_blocked_on_deny(monkeypatch):
+    _stub_gate(monkeypatch, blocked=True)
+    tool = _real_tool()
+    guard_tools([tool], client=create_mock_client(harness="llamaindex"))
+    wrapped = getattr(tool, "_fn", None) or getattr(tool, "fn", None)
+    with pytest.raises(OryDenialError):
+        wrapped()
+
+
+def test_real_functiontool_runs_on_allow(monkeypatch):
+    _stub_gate(monkeypatch, blocked=False)
+    tool = _real_tool()
+    guard_tools([tool], client=create_mock_client(harness="llamaindex"))
+    wrapped = getattr(tool, "_fn", None) or getattr(tool, "fn", None)
+    assert wrapped() == "RAN"
+
+
+def test_real_functiontool_acall_blocked_on_deny(monkeypatch):
+    # acall() invokes _async_fn (the FunctionAgent workflow path) — it must be gated too.
+    _stub_gate(monkeypatch, blocked=True)
+    tool = _real_tool()
+    guard_tools([tool], client=create_mock_client(harness="llamaindex"))
+    with pytest.raises(OryDenialError):
+        asyncio.run(tool.acall())
+
+
+def test_real_functiontool_acall_runs_on_allow(monkeypatch):
+    _stub_gate(monkeypatch, blocked=False)
+    tool = _real_tool()
+    guard_tools([tool], client=create_mock_client(harness="llamaindex"))
+    result = asyncio.run(tool.acall())
+    assert "RAN" in str(result)

ory_llamaindex-0.13.9/tests/test_tools.py

@@ -0,0 +1,167 @@
+"""Hermetic tests for the LlamaIndex tool-wrap gate (SDK-free).
+
+Covers the native veto shape (``OryDenialError`` raised from the wrapped ``_fn``) and
+request-shape extraction (``metadata.name`` on a FunctionTool-shaped object). The full
+permission decision matrix is core-owned (``ory-argus/tests/test_adapters.py``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from ory_argus.client import PrincipalIdentity
+from ory_argus.denial import OryDenialError
+from ory_argus.testing import (
+    create_mock_client,
+    get_trace_spans,
+    stub_permission_allowed,
+    stub_permission_denied,
+)
+from ory_llamaindex import guard_tool_fn, guard_tools  # type: ignore
+
+
+@pytest.fixture(autouse=True)
+def _isolate(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    monkeypatch.delenv("ORY_PERMISSION_MODE", raising=False)
+
+
+def client_with_user():
+    c = create_mock_client(harness="llamaindex")
+    c.set_user_principal(PrincipalIdentity(subject="user:alice"))
+    return c
+
+
+def fake_tool(name, fn):
+    # Mirrors FunctionTool: metadata.name + _fn.
+    return SimpleNamespace(metadata=SimpleNamespace(name=name), _fn=fn)
+
+
+def fake_async_tool(name, fn, afn):
+    # Mirrors FunctionTool.from_defaults: metadata.name + _fn + _async_fn (acall path).
+    return SimpleNamespace(metadata=SimpleNamespace(name=name), _fn=fn, _async_fn=afn)
+
+
+def test_guard_tool_fn_allow():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    wrapped = guard_tool_fn(c, tool_name="search", fn=lambda q: f"hit:{q}")
+    assert wrapped("x") == "hit:x"
+    assert get_trace_spans(c, "tool.invoke")[0].attributes["allowed"] is True
+    assert get_trace_spans(c, "tool.complete")
+
+
+def test_guard_tools_wraps_fn_and_enforces(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    ran = {}
+
+    def rm():
+        ran["yes"] = True
+        return "deleted"
+
+    tool = fake_tool("rm", rm)
+    guard_tools([tool], client=c)
+    # Native veto shape: the replaced _fn raises OryDenialError at the tool boundary.
+    with pytest.raises(OryDenialError):
+        tool._fn()
+    assert "yes" not in ran  # underlying fn never invoked
+    assert get_trace_spans(c, "tool.block")[0].attributes["blocked"] is True
+
+
+def test_guard_tools_observe_runs():
+    c = client_with_user()
+    stub_permission_denied(c)
+    tool = fake_tool("rm", lambda: "ran")
+    guard_tools([tool], client=c)
+    assert tool._fn() == "ran"
+    assert get_trace_spans(c, "permission.observe_deny")
+
+
+def test_guard_tools_async_path_enforce_blocks_before_run(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    ran = {}
+
+    async def arm():
+        ran["yes"] = True
+        return "deleted"
+
+    tool = fake_async_tool("rm", lambda: "deleted", arm)
+    guard_tools([tool], client=c)
+    with pytest.raises(OryDenialError):
+        asyncio.run(tool._async_fn())
+    assert "yes" not in ran
+    assert get_trace_spans(c, "tool.block")[0].attributes["blocked"] is True
+
+
+def test_guard_tools_async_path_allow_runs():
+    c = client_with_user()
+    stub_permission_allowed(c)
+
+    async def search(q):
+        return f"hit:{q}"
+
+    tool = fake_async_tool("search", lambda q: f"hit:{q}", search)
+    guard_tools([tool], client=c)
+    assert asyncio.run(tool._async_fn("x")) == "hit:x"
+    assert get_trace_spans(c, "tool.invoke")[0].attributes["allowed"] is True
+    assert get_trace_spans(c, "tool.complete")
+
+
+def test_guard_tools_async_path_observe_runs():
+    c = client_with_user()
+    stub_permission_denied(c)
+
+    async def rm():
+        return "ran"
+
+    tool = fake_async_tool("rm", lambda: "ran", rm)
+    guard_tools([tool], client=c)
+    assert asyncio.run(tool._async_fn()) == "ran"
+    assert get_trace_spans(c, "permission.observe_deny")
+
+
+def test_guard_tools_async_only_tool_is_gated(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+
+    async def rm():
+        return "ran"
+
+    tool = SimpleNamespace(metadata=SimpleNamespace(name="rm"), _async_fn=rm)
+    guard_tools([tool], client=c)
+    with pytest.raises(OryDenialError):
+        asyncio.run(tool._async_fn())
+
+
+def test_guard_tools_wrap_failure_warns_on_stderr(capsys):
+    c = client_with_user()
+    stub_permission_allowed(c)
+
+    class FrozenTool:
+        metadata = SimpleNamespace(name="frozen")
+
+        @property
+        def _fn(self):
+            return lambda: "x"
+
+    guard_tools([FrozenTool()], client=c)
+    err = capsys.readouterr().err
+    assert "UNGATED" in err
+    assert "frozen" in err
+
+
+def test_guard_tools_uses_metadata_name():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    tool = fake_tool("custom_name", lambda: "ok")
+    guard_tools([tool], client=c)
+    tool._fn()
+    assert get_trace_spans(c, "tool.invoke")[0].attributes["toolName"] == "custom_name"