API Reference¶
Auto-generated reference for the deep_db_agents package, extracted from source docstrings.
Public API¶
deep_db_agents ¶
deep-db-agents: factory for Deep Agents specialized on different databases.
GuardrailConfig
dataclass
¶
GuardrailConfig(default_rows: int = 100, hard_max_rows: int = 1000, explain_row_threshold: int = 1000000, query_timeout_s: int = 30, allowed_statements: frozenset[str] = frozenset({'SELECT'}), row_budget: int | None = 50000)
Safety thresholds that cannot be bypassed by the agent.
Attributes:
| Name | Type | Description |
|---|---|---|
default_rows |
int
|
LIMIT applied automatically when the agent does not specify one. |
hard_max_rows |
int
|
Hard cap on rows per single query, never exceedable. |
explain_row_threshold |
int
|
If the row estimate from |
query_timeout_s |
int
|
Maximum execution timeout for a query, enforced by the driver/database. |
allowed_statements |
frozenset[str]
|
Whitelist of allowed statement types (only |
row_budget |
int | None
|
Cumulative row budget returned per session ( |
check_estimate ¶
check_estimate(estimated_rows: int, metrics: SessionMetrics | None = None) -> None
Block the query if the EXPLAIN estimate exceeds the threshold.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
estimated_rows
|
int
|
The estimated number of rows the query would return,
typically obtained via |
required |
metrics
|
SessionMetrics | None
|
Optional session counters to update when the query is blocked. |
None
|
Raises:
| Type | Description |
|---|---|
GuardrailError
|
If |
Source code in src/deep_db_agents/guardrails.py
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | |
clamp_limit ¶
clamp_limit(requested: int | None) -> int
Compute the effective LIMIT to apply, capped by hard_max_rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
requested
|
int | None
|
The row limit requested by the agent, or |
required |
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
The effective limit, never greater than |
Source code in src/deep_db_agents/guardrails.py
44 45 46 47 48 49 50 51 52 53 54 55 56 | |
ConnectionConfig
dataclass
¶
ConnectionConfig(scheme: str, host: str | None, port: int | None, credential: dict[str, Any] = dict(), path: str | None = None)
Connection parameters for a database.
credential is a free-form dictionary whose content depends on the specific DB
(e.g. {"user": ..., "password": ...} or {"secret_key": ...}). Well-known keys
(database/db) are exposed as convenience properties.
Attributes:
| Name | Type | Description |
|---|---|---|
scheme |
str
|
The URL scheme identifying the dialect (e.g. |
host |
str | None
|
Hostname for network databases, or |
port |
int | None
|
Port for network databases, or |
credential |
dict[str, Any]
|
Free-form credential/connection dictionary. |
path |
str | None
|
File/directory path for file-based databases ( |
database
property
¶
database: str | None
Return the logical database/schema name, if provided in the credentials.
Returns:
| Type | Description |
|---|---|
str | None
|
str | None: The value of the |
str | None
|
|
__repr__ ¶
__repr__() -> str
Return a repr with credentials masked.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
A string representation of this config where |
str
|
is masked so passwords never leak into logs, tracebacks, or error messages. |
Source code in src/deep_db_agents/connection.py
44 45 46 47 48 49 50 51 52 53 54 55 56 57 | |
SessionMetrics
dataclass
¶
SessionMetrics(queries_run: int = 0, rows_returned: int = 0, budget_exhausted: int = 0, estimate_blocked: int = 0, _lock: Lock = threading.Lock())
Cumulative counters for a session/agent, updated by the guardrails.
Thread-safe: tool calls may run in parallel. Pass an instance to the factory
(metrics parameter) and read it after invoking the agent.
Attributes:
| Name | Type | Description |
|---|---|---|
queries_run |
int
|
Total number of queries executed. |
rows_returned |
int
|
Total number of rows returned across all queries. |
budget_exhausted |
int
|
Number of times the session row budget was exhausted. |
estimate_blocked |
int
|
Number of times a query was blocked by the EXPLAIN row-estimate threshold. |
record_budget_exhausted ¶
record_budget_exhausted() -> None
Record that the session row budget was exhausted.
Returns:
| Type | Description |
|---|---|
None
|
None. |
Source code in src/deep_db_agents/observability.py
89 90 91 92 93 94 95 96 | |
record_estimate_blocked ¶
record_estimate_blocked() -> None
Record that a query was blocked by the EXPLAIN row-estimate threshold.
Returns:
| Type | Description |
|---|---|
None
|
None. |
Source code in src/deep_db_agents/observability.py
98 99 100 101 102 103 104 105 | |
record_query ¶
record_query(rows: int) -> None
Record that a query ran and returned rows rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rows
|
int
|
Number of rows returned by the query. |
required |
Returns:
| Type | Description |
|---|---|
None
|
None. |
Source code in src/deep_db_agents/observability.py
76 77 78 79 80 81 82 83 84 85 86 87 | |
summary ¶
summary() -> str
Build a human-readable summary of the session counters.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
A one-line summary of queries run, rows returned, and blocks. |
Source code in src/deep_db_agents/observability.py
107 108 109 110 111 112 113 114 115 116 117 | |
create_deep_db_agents ¶
create_deep_db_agents(db_url: str, credential: dict[str, Any] | None = None, system: str = '', *, guardrails: GuardrailConfig | None = None, enable_code_interpreter: bool = False, metrics: SessionMetrics | None = None, **kwargs: Any)
Create a Deep Agent specialized on the database pointed to by db_url.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_url
|
str
|
Database URL in the form |
required |
credential
|
dict[str, Any] | None
|
Access credentials; the expected keys depend on the target database
(e.g. |
None
|
system
|
str
|
Database-specific system prompt, appended to the dialect's generic prompt. |
''
|
guardrails
|
GuardrailConfig | None
|
Safety thresholds for the tools (max LIMIT, timeout, EXPLAIN threshold,
row budget). Defaults to |
None
|
enable_code_interpreter
|
bool
|
If |
False
|
metrics
|
SessionMetrics | None
|
Optional |
None
|
**kwargs
|
Any
|
Forwarded as-is to |
{}
|
Returns:
| Type | Description |
|---|---|
|
The compiled agent, with an |
|
|
interface. Also supports |
|
|
under |
|
|
calls concurrently (see |
Example
from deep_db_agents import create_deep_db_agents
agent = create_deep_db_agents(
"postgres://localhost:5432/mydb",
credential={"user": "reader", "password": "secret"},
system="Focus on the `orders` and `customers` tables.",
)
result = agent.invoke(
{"messages": [{"role": "user", "content": "How many orders last week?"}]}
)
Source code in src/deep_db_agents/factory.py
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | |
create_deep_db_multi_agents ¶
create_deep_db_multi_agents(db_agents: Mapping[str, Mapping[str, Any]], system: str = '', **kwargs: Any)
Create a Deep Agent orchestrator that coordinates multiple deep_db_agents.
The orchestrator never queries a database directly: it delegates each sub-question to
the sub-agent specialized on the relevant database (exposed through the task tool)
and combines the results. This enables answering questions that span multiple databases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_agents
|
Mapping[str, Mapping[str, Any]]
|
Mapping of |
required |
system
|
str
|
Extra system prompt, appended to the orchestrator's generic prompt and the sub-agent roster, to provide additional context (domain, join rules, ...). |
''
|
**kwargs
|
Any
|
Forwarded as-is to |
{}
|
Returns:
| Type | Description |
|---|---|
|
The compiled orchestrator agent, with an |
|
|
interface. |
Raises:
| Type | Description |
|---|---|
InvalidMultiAgentConfigError
|
If |
Example
from deep_db_agents import create_deep_db_agents, create_deep_db_multi_agents
orders_agent = create_deep_db_agents("postgres://localhost:5432/orders")
events_agent = create_deep_db_agents("mongodb://localhost:27017/events")
orchestrator = create_deep_db_multi_agents(
{
"orders": {
"description": "Orders and customers (Postgres)",
"agent": orders_agent,
},
"events": {"description": "Raw event log (MongoDB)", "agent": events_agent},
}
)
query = "Compare orders vs. events last week."
result = orchestrator.invoke({"messages": [{"role": "user", "content": query}]})
Source code in src/deep_db_agents/factory.py
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 | |
create_db_agents ¶
create_db_agents(db_url: str, credential: dict[str, Any] | None = None, system: str = '', *, guardrails: GuardrailConfig | None = None, metrics: SessionMetrics | None = None, **kwargs: Any)
Create a plain LangChain Agent specialized on the database pointed to by db_url.
Unlike :func:create_deep_db_agents, the file-materialization tools (materialize_*)
are not exposed: they require the deepagents filesystem backend, which the plain agent
does not have.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_url
|
str
|
Database URL in the form |
required |
credential
|
dict[str, Any] | None
|
Access credentials; the expected keys depend on the target database
(e.g. |
None
|
system
|
str
|
Database-specific system prompt, appended to the dialect's generic prompt. |
''
|
guardrails
|
GuardrailConfig | None
|
Safety thresholds for the tools (max LIMIT, timeout, EXPLAIN threshold,
row budget). Defaults to |
None
|
metrics
|
SessionMetrics | None
|
Optional |
None
|
**kwargs
|
Any
|
Forwarded as-is to |
{}
|
Returns:
| Type | Description |
|---|---|
|
The compiled agent, with an |
|
|
interface. Also supports |
|
|
thread pool). |
Example
from deep_db_agents import create_db_agents
agent = create_db_agents(
"sqlite:///./data/app.db",
system="Answer briefly, cite the exact table and column names.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "List all tables."}]})
Source code in src/deep_db_agents/factory.py
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 | |
configure_logging ¶
configure_logging(level: int = logging.INFO) -> None
Attach a stderr handler to the library logger (convenience, idempotent).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
level
|
int
|
Logging level to set on the library logger. Defaults to
|
INFO
|
Returns:
| Type | Description |
|---|---|
None
|
None. |
Source code in src/deep_db_agents/observability.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | |
available_schemes ¶
available_schemes() -> list[str]
List the schemes currently registered.
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: The list of registered scheme names. |
Source code in src/deep_db_agents/registry.py
69 70 71 72 73 74 75 | |