SDK DB Adapters
Run queries locally
A DB Adapter is a pluggable execution layer used by the SDK to handle tool calls within your backend environment. It serves as a translator: it takes the structured, validated tool call generated by the AI and converts it into a native database query (e.g., a MongoDB MQL or a PostgreSQL SQL statement).
Why adapters exist
The primary driver is data sovereignty:
- Local Execution: The adapter runs queries locally on your server.
- Privacy: Raw data never leaves your infrastructure.
- Reasoning Only: Only the results of the query (often filtered and normalized) are sent to Telygent for reasoning, ensuring that sensitive database internals remain hidden.
Core responsibilities
The adapter is responsible for the heavy lifting of data retrieval and formatting:
- Constraint Enforcement: It respects the Registry constraints. If a model tries to filter by an unindexed field or access a "hidden" field not in the
allowedFieldslist, the adapter blocks it. - Normalization: It converts database-specific types (like MongoDB
ObjectIdorISODate) into clean, standard JSON that the LLM can easily interpret. - Relation Lookups: It uses the Registry to resolve IDs into related document data automatically.
Installation & initialization
Currently, the MongoDB Adapter (v1) is ready for use, with Postgres/Supabase support coming soon.
mongo-adapter.ts
1import { MongoClient } from 'mongodb';
2import { createMongoAdapter } from '@telygent/sdk/adapters/mongo';
3import { registry } from './registry';
4
5const client = new MongoClient(process.env.MONGO_URI);
6const db = client.db('production');
7
8// Initialize the adapter with your DB instance and registry
9const adapter = createMongoAdapter({
10 db,
11 registry
12});The registry & safety tie-in
The Registry is the adapter's "rulebook." Before any query hits the database, the adapter checks the Registry to ensure:
- Safety: The model is only querying fields explicitly marked as
allowedFields. - Type Integrity: The fieldTypes match what the DB expects, preventing query errors
- Performance: requiredFilters are applied to prevent the AI from accidentally triggering massive, unindexed table scans.