pydantic-ai-chdb
A Pydantic AI capability for 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
pip install pydantic-ai-chdb
Usage
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=2setting:INSERT/CREATE/ALTER/DROPare rejected by the engine whileSELECTand thefile()/s3()/url()table functions keep working. Passread_only=Falsefor a writable session (this also exposesattach_file). - Capped results.
max_rows(default 1000) andmax_bytes(default 1 MB) bound every payload; truncated results carry atruncatedflag.max_execution_timeadds 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:
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 team.
Metadata
Release files for pydantic-ai-chdb 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydantic_ai_chdb-0.1.0.tar.gz | 10.9 kB | Without provenance | Details for pydantic_ai_chdb-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydantic_ai_chdb-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pydantic_ai_chdb-0.1.0-py3-none-any.whl |
Total release size: 21.9 kB
Release files / pydantic_ai_chdb-0.1.0.tar.gz
| Download URL | pydantic_ai_chdb-0.1.0.tar.gz |
|---|---|
| Size | 10.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d4fd8c3ce5d3d10bf2483e7e2ae03eeaa3b2db35a8d2a8c44746c4a3187ace19
|
|
BLAKE2b-256 checksum How to use checksums |
a3e7ee15b34a6a5f1943522d6e2a5e8face2b6a2ce024df9259703e67257ebf7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / pydantic_ai_chdb-0.1.0-py3-none-any.whl
| Download URL | pydantic_ai_chdb-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
39e96cc50d7f93c2382692060f9f4898be37b9667872d9c47b8fcfcfdf5bd7fe
|
|
BLAKE2b-256 checksum How to use checksums |
6ee132dad644417c93232914ac63dd197299e6c022489f39acad255fcb9a69e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for pydantic-ai-chdb 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.