Metadata-Version: 2.4
Name: llama-index-tools-chdb
Version: 0.1.0
Summary: LlamaIndex tool spec for chDB, the in-process ClickHouse engine: analytical SQL over local files, object storage, and remote databases with engine-level read-only safety.
Project-URL: Homepage, https://github.com/chdb-io/llama-index-tools-chdb
Project-URL: Repository, https://github.com/chdb-io/llama-index-tools-chdb
Project-URL: Documentation, https://clickhouse.com/docs/en/chdb
Author-email: chDB team <auxtenwpc@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,chdb,clickhouse,llama-index,olap,sql,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: chdb>=4.2.1
Requires-Dist: llama-index-core<0.16,>=0.13.0
Description-Content-Type: text/markdown

# LlamaIndex Tools Integration: chDB

Give agents analytical SQL over local and remote data with [chDB](https://clickhouse.com/docs/en/chdb), the in-process ClickHouse engine. The engine runs inside the Python process — no server to start, no connection string, no credentials — and queries local files (Parquet/CSV/JSON), object storage, and remote databases through ClickHouse table functions.

## Installation

```shell
pip install llama-index-tools-chdb
```

## Usage

```python
from llama_index.tools.chdb import ChDBToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

spec = ChDBToolSpec(attachments={"events": "data/events.parquet"})

agent = FunctionAgent(
    tools=spec.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

print(await agent.run("What are the top 5 event types by count?"))
```

The spec exposes seven tools, mirroring the tool surface chDB ships for agents (`chdb.agents`):

- `run_select_query` — read-only ClickHouse SQL with `{name:Type}` parameter binding (full dialect: 1000+ functions, window functions, arrays, JSON)
- `list_databases`, `list_tables`, `describe_table`, `get_sample_data`, `list_functions` — schema discovery, including describing table-function expressions such as `s3('https://bucket/f.parquet','Parquet')`
- `attach_file` — register a local file as a named table (writable sessions only; on read-only sessions declare files via the `attachments` argument instead)

Every tool has an async twin (`arun_select_query`, …) backed by the engine's native async path, so `to_tool_list()` produces tools usable in both sync and async agents.

## Safety defaults

- **Read-only by default.** Sessions are locked with the ClickHouse `readonly=2` setting: `INSERT`/`CREATE`/`ALTER`/`DROP` are rejected by the engine (not by prompt), while `SELECT` and the `file()`/`s3()`/`url()` table functions keep working. Pass `read_only=False` for a writable session.
- **Capped results.** `max_rows` (default 1000) and `max_bytes` (default 1 MB) bound every payload; truncated results carry a `truncated` flag the agent can react to. `max_execution_time` adds an engine-side wall-clock limit.
- **Optional source allowlist.** With `file_allowlist=["/data/"]`, file-like sources may only read under the listed prefixes and DSN-based sources (`postgresql()`, `mysql()`, `remote()`, …) are refused.
- **Errors go to the model, not the run.** Every call returns a JSON envelope — `{"ok": true, "result": …}` or `{"ok": false, "error": {"code", "type", "message"}}` — so a bad query becomes feedback the agent corrects instead of an exception.

## Querying remote data

```python
spec = ChDBToolSpec()
spec.run_select_query(
    "SELECT status, count() FROM url('https://example.com/logs.ndjson', 'JSONEachRow') GROUP BY status"
)
```

`s3(...)`, `postgresql(...)`, `mysql(...)`, `mongodb(...)`, `remoteSecure(...)`, `iceberg(...)`, and `deltaLake(...)` work the same way, subject to the read-only lock and allowlist.

## Sharing and lifecycle

To control the engine's lifecycle yourself — or to share one session across several specs — create the engine explicitly and inject it:

```python
from chdb.agents import ChDBTool
from llama_index.tools.chdb import ChDBToolSpec

engine = ChDBTool("analytics_dir", read_only=False)
spec = ChDBToolSpec(engine=engine)
...
engine.close()
```

`spec.close()` closes only an engine the spec created itself.

This package is maintained by the [chDB](https://github.com/chdb-io/chdb) team.
