Metadata-Version: 2.4
Name: pydantic-ai-chdb
Version: 0.1.0
Summary: Pydantic AI capability for chDB, the in-process ClickHouse engine: analytical SQL tools with engine-level read-only safety and typed engine errors mapped to ModelRetry.
Project-URL: Homepage, https://github.com/chdb-io/pydantic-ai-chdb
Project-URL: Repository, https://github.com/chdb-io/pydantic-ai-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,capability,chdb,clickhouse,olap,pydantic-ai,sql
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: pydantic-ai-slim<3,>=2.0
Description-Content-Type: text/markdown

# pydantic-ai-chdb

A [Pydantic AI](https://ai.pydantic.dev) capability for [chDB](https://clickhouse.com/docs/en/chdb), the in-process ClickHouse engine: give agents analytical SQL over local files, object storage, and remote databases — no server to start, no connection string, no credentials.

## Installation

```shell
pip install pydantic-ai-chdb
```

## Usage

```python
from pydantic_ai import Agent
from pydantic_ai_chdb import ChDBCapability

agent = Agent(
    "openai:gpt-4o-mini",
    capabilities=[ChDBCapability(attachments={"events": "data/events.parquet"})],
)

result = agent.run_sync("What are the top 5 event types by count?")
print(result.output)
```

The capability registers the chDB tool suite — `run_select_query` (read-only ClickHouse SQL with `{name:Type}` parameter binding), `list_databases`, `list_tables`, `describe_table`, `get_sample_data`, `list_functions`, and (on writable sessions) `attach_file` — plus schema-first usage instructions for the system prompt. Tool names and descriptions come from the descriptors bundled with the `chdb` package, its single source of truth across bindings.

## Typed errors become retries

The capability's `on_tool_execute_error` hook maps typed `chdb.agents.errors.ChDBError` failures to `ModelRetry`, so the model sees the engine's error type, code, and message —

```
chDB UNKNOWN_IDENTIFIER (code 47): Unknown expression identifier `SELEC` ...
```

— and corrects the query within the agent's retry budget instead of the run dying on an exception. Non-chDB errors propagate unchanged.

## Safety defaults

- **Read-only by default.** Sessions are locked with the ClickHouse `readonly=2` setting: `INSERT`/`CREATE`/`ALTER`/`DROP` are rejected by the engine while `SELECT` and the `file()`/`s3()`/`url()` table functions keep working. Pass `read_only=False` for a writable session (this also exposes `attach_file`).
- **Capped results.** `max_rows` (default 1000) and `max_bytes` (default 1 MB) bound every payload; truncated results carry a `truncated` flag. `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.

## Sharing and lifecycle

To control the engine's lifecycle yourself — or to share one session across capabilities and other chDB bindings — create it explicitly and inject it:

```python
from chdb.agents import ChDBTool
from pydantic_ai_chdb import ChDBCapability

engine = ChDBTool("analytics_dir", read_only=False)
capability = ChDBCapability(engine=engine)
...
engine.close()
```

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

Spec-based construction works out of the box: `ChDBCapability.from_spec(path="analytics_dir", read_only=True)`.

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