ragleap-tools

Install

No configuration needed for the 12 stateless tools. File operations, document ingestion and search, web search, GitHub search and image description are opt-in and each need their own config object.

pip install ragleap-tools
# or, with uv
uv add ragleap-tools

# optional, for the ragleap-rag-backed ingestion tool:
pip install ragleap-tools[ingest]

What this is (and isn't)

ragleap-tools provides Tool objects — a name, a description, a JSON Schema for parameters, and a safe handler function. It does not own a tool-calling execution loop (deciding when to call a tool, running it, feeding the result back to the model) — that's ragleap-agents's job, per the roadmap's own split. Wire these tools into your own tool-calling code, or into ragleap-agents once that ships.

Quick start

from ragleap_tools import STATELESS_TOOLS, CALCULATOR_TOOL

# Give these to your LLM provider's tools= parameter:
openai_tools = [t.to_openai_schema() for t in STATELESS_TOOLS]
gemini_tools = [t.to_gemini_schema() for t in STATELESS_TOOLS]

# When the model calls one, invoke the handler yourself:
result = CALCULATOR_TOOL.call(expression="2 + 2 * sqrt(16)")
print(result.success, result.result)  # True 10.0

Full public API

Stateless tools (v0.1.0+) — no configuration needed

File operations (v0.1.0+) — sandboxed, needs configuration

from ragleap_tools import FileOpsConfig, make_file_tools

config = FileOpsConfig(root_dir="/path/to/a/safe/directory")
read_tool, write_tool, list_tool = make_file_tools(config)

Every operation is confined to root_dir. Paths are resolved via Path.resolve() (which follows symlinks) before containment is checked with is_relative_to() — so both ../ traversal and symlink-based escapes are rejected, not just naive string-prefix checking. There is no unsandboxed mode.

Document ingestion and search (v0.1.0+) — optional, needs ragleap-rag

from ragleap import RagLeap, ProviderConfig, EmbeddingConfig
from ragleap_tools import IngestConfig, make_ingest_tool

rag = RagLeap(database_url="...", primary=ProviderConfig(...), embedder=EmbeddingConfig(...))
ingest_tool = make_ingest_tool(IngestConfig(rag=rag))

Wraps ragleap-rag's already-tested ingest_text() — no new ingestion logic, just a tool schema on top of the real 28-format-capable pipeline. Same optional-dependency pattern ragleap-graph already uses for its own optional ragleap-rag link.

Document search (v0.1.1+) — optional, needs ragleap-rag

from ragleap_tools import SearchConfig, make_search_tool

search_tool = make_search_tool(SearchConfig(rag=rag))
result = search_tool.call(query="what was the Q3 revenue?", filename="q3-report.pdf")

Wraps ragleap-rag's retrieve() for hybrid vector+keyword search. Chunk dicts are returned unmodified. The optional filename= scopes the search to one document previously ingested via ingest_document, which stores {"filename": filename} as metadata since v0.1.1.

Web search (v0.2.0+) — bring-your-own-key, no extra dependencies

from ragleap_tools import WebSearchConfig, TavilySearchProvider, make_web_search_tool

provider = TavilySearchProvider(api_key="...")  # or SerperSearchProvider(api_key="...")
search_tool = make_web_search_tool(WebSearchConfig(provider=provider))
result = search_tool.call(query="latest pgvector release", num_results=5)

No default provider and no environment-variable fallback. num_results is model-controlled and costs your API quota, so it is clamped to 1-20. Neither provider has been called against a live account yet. Results are untrusted third-party text and are not screened for prompt injection.

GitHub repository search (v0.3.0+) — token optional, no extra dependencies

from ragleap_tools import GitHubSearchConfig, make_github_search_tool

tool = make_github_search_tool(GitHubSearchConfig())  # or GitHubSearchConfig(token="...")
result = tool.call(query="language:python topic:llm", num_results=5, sort="stars")

Repository search only, via GitHub's REST API. Unauthenticated search works at a lower limit (10 requests for the search resource in a live check on 2026-10-01); authenticated requests have not been live-verified.

Image description (v0.4.0+) — bring-your-own-key, no extra dependencies

from ragleap_tools import FileOpsConfig, GeminiVisionProvider, VisionConfig, make_vision_tool

provider = GeminiVisionProvider(api_key="...", model="...")  # you choose the model
tool = make_vision_tool(VisionConfig(
    provider=provider,
    sandbox=FileOpsConfig(root_dir="/path/to/images"),
))
result = tool.call(path="chart.png", prompt="What does this chart show?")

api_key and model are both required. Images are read only from inside the sandbox directory (same path-escape and symlink protection as the file tools); URLs are deliberately not accepted. The image type is detected from the file's bytes. GeminiVisionProvider was live-checked once on 2026-10-03 (PNG input); AnthropicVisionProvider has not been called against a live account. Descriptions are untrusted text derived from an image and are not screened for prompt injection.

Network limits (v0.4.1+) — every HTTP provider

from ragleap_tools import TavilySearchProvider

provider = TavilySearchProvider(
    api_key="...",
    max_response_bytes=2_000_000,  # default 1,048,576
    total_timeout=30,              # seconds; default 20 (90 for the vision providers)
)

Tavily, Serper, GitHub search and the Gemini and Anthropic vision providers enforce a response-size cap and a hard total deadline; both are optional, validated fields on the provider (or GitHubSearchConfig). An oversize response or an exceeded deadline returns a failed ToolResult instead of hanging your loop. Per-operation timeouts are unchanged (15 seconds; 60 for vision). Python cannot kill a thread, so an abandoned request is stopped on a best-effort basis, and DNS resolution is not covered by the per-operation timeout.

Write your own tool and dispatch calls (v0.5.0+) — no configuration, no extra dependencies

from typing import Literal
from ragleap_tools import tool, ToolError, Toolkit, default_toolkit

@tool
def lookup_order(order_id: str, status: Literal["open", "closed"] = "open") -> dict:
    """Look up an order by id.

    Args:
        order_id: The order id, for example "A-1001".
        status: Which orders to search.
    """
    if order_id not in ORDERS:
        raise ToolError("order not found")   # safe to show the model
    return ORDERS[order_id]

kit = default_toolkit().add(lookup_order)       # the 12 stateless tools + yours
provider_tools = kit.to_openai_schema()          # also to_gemini_schema() / to_anthropic_schema()
result = kit.call(name_from_model, arguments_from_model)   # never raises

Version history

Real design decisions & scope boundaries this session

Not fabricated wins — each of these was a deliberate call made before writing code, not an afterthought.

• ✓ shipped
  No execution-loop ownership. ragleap-tools provides Tool objects only. The roadmap already assigns tool-calling execution + HITL approval gates to ragleap-agents — avoiding two competing execution-loop implementations in the ecosystem.
• ✓ shipped
  AST-based calculator, never eval()/exec(). Parses the expression, walks the tree, rejects anything outside an explicit allowlist of node types/functions. Verified against real code-injection payloads, not just documented as safe.
• ✓ shipped
  Symlink-aware file sandboxing. Path.resolve() before containment check, not naive string-prefix matching — closes a real escape class that string-based sandboxing misses. Verified with a real on-disk symlink pointing outside the sandbox, not just a synthetic path string.
• deliberately deferred
  Code execution, HTTP fetch, and business-system connectors remain out of scope. Each needs its own security-focused design pass. Web search was also out of scope for v0.1.0 and shipped in v0.2.0 only after its own design doc; GitHub search (v0.3.0) and image description (v0.4.0) followed the same way.
• ✓ shipped
  A model's arguments are checked before any handler runs. Toolkit.call and every @tool function validate the arguments against the tool's schema first, so a missing, unknown or mistyped argument becomes a failed result instead of a TypeError inside the caller's loop; the JSON text is size-limited, and an exception from a handler reaches the model only as its type name. Covered by 162 new tests and 89 of 89 deliberate breaks caught.
• not live-verified
  Generated schemas against real providers. The schemas @tool generates use the same shape as the built-in tools plus default and integer enum; no provider has been called with one.

Known limitations

• No tool-calling execution loop is provided — the caller (or ragleap-agents, once it ships) must decide when to call a tool and feed results back to the model.
• File ops require an explicit root_dir — there is no unsandboxed mode, and no default directory is assumed.
• Code execution, HTTP fetch, and database/business-system connectors are not included.
• Not live-verified: the Tavily and Serper web search providers, AnthropicVisionProvider, and authenticated GitHub requests. Request shapes were checked against current public documentation only.
• Search results and image descriptions are untrusted text that flows into a model's context; neither is screened for prompt injection.
• Network calls are bounded (v0.4.1), but Python cannot kill a thread: after the deadline an abandoned request is stopped on a best-effort basis (control still returns on time), DNS resolution is not covered by the per-operation timeout, and a response larger than the cap (1 MiB by default) now fails instead of succeeding.
• @tool supports sync functions only and a small set of annotations, and validates against a small JSON Schema subset (dict values and keywords such as pattern are not checked, so a handler must still validate what the schema cannot express). Toolkit.call bounds the argument JSON but not how long a handler runs or how large its result is. The generated schemas have not been sent to any provider.