Registry & Tools
Teach Telygent about your data
The registry is a static contract describing collections, fields, and allowed query shapes. Telygent uses it to plan tool calls, validate filters, and generate safe links.
Models
A model represents a logical dataset the AI can query. Each model maps to a Mongo collection and defines what the AI is allowed to filter, aggregate, or summarize.
You identify a model by its key in the registry object (for example, Transaction or Statute). The key is the name the AI uses when it requests tool calls.
Core fields per model
collectionName
The Mongo collection the adapter will query. Keep this in sync with your database schema and naming.
allowedFields
An allowlist of fields the AI can filter, sort, or select. Anything not listed here is off-limits for tool calls.
instructions
Prompt guidance scoped to this model. Use this to encode domain assumptions, default date ranges, or naming conventions.
allowCounts
Enables count-style queries for this model. Turn this on when you want the AI to answer questions like "how many" or "count of" without returning full documents.
1const registry = {
2 User: {
3 collectionName: "app_users",
4 allowedFields: ["userId", "email", "status", "createdAt"],
5 fieldAliases: {
6 userId: ["u_id_01", "uid", "user_id"],
7 createdAt: ["created_date", "created_at"],
8 },
9 },
10};Field types
Field type hints help the AI format filters correctly, especially for ObjectId and date comparisons. Use this to avoid invalid query shapes.
1fieldTypes: {
2 _id: "objectId",
3 createdAt: "date",
4 amount: "number",
5 status: "string",
6},Relations
Relations describe how models connect, so the AI can reason about join-like lookups or enrich results. Use local and foreign fields to define the relationship.
1relations: {
2 Merchant: {
3 model: "Merchant",
4 localField: "merchantId",
5 foreignField: "_id",
6 },
7},Field aliases
Aliases map natural-language phrases to canonical field names. This helps the AI translate user phrasing into valid filters.
1fieldAliases: {
2 status: ["state", "current status"],
3 createdAt: ["created", "created date"],
4},Links
Link templates let the AI generate safe list and detail URLs based on tool filters. Restrict params to a known allowlist and map fields to query parameters explicitly.
1links: {
2 list: "/transactions",
3 detail: "/transactions/{_id}",
4 allowedQueryParams: ["status", "createdAt"],
5 queryParamMap: {
6 status: "status",
7 createdAt: { gte: "from", lte: "to" },
8 },
9},Required filters
Required filters enforce hard constraints like tenant or account scoping. These are injected into every tool call, either from userContext or fixed values.
1requiredFilters: [
2 { field: "tenantId", contextKey: "tenantId", type: "string" },
3 { field: "createdAt", value: { gte: "2025-01-01" }, type: "date" },
4],Example registry
1const registry = {
2 Statute: {
3 collectionName: "canadian_statutes",
4 allowedFields: ["title", "shortTitle", "year", "jurisdiction", "topics", "createdAt"],
5 allowCounts: true,
6 instructions:
7 "Use jurisdiction filters (federal or provincial) and default to the most recent 5 years when dates are missing.",
8 links: {
9 list: "/laws/statutes",
10 detail: "/laws/statutes/{_id}",
11 allowedQueryParams: ["year", "jurisdiction", "topics", "createdAt"],
12 queryParamMap: {
13 year: "year",
14 jurisdiction: "jurisdiction",
15 topics: "topic",
16 createdAt: { gte: "fromDate", lte: "toDate" },
17 },
18 allowedQueryValues: {
19 jurisdiction: ["federal", "provincial"],
20 },
21 },
22 fieldTypes: {
23 _id: "objectId",
24 createdAt: "date",
25 },
26 requiredFilters: [
27 { field: "jurisdiction", contextKey: "jurisdiction", type: "string" }
28 ],
29 fieldAliases: {
30 "shortTitle": ["short title", "abbrev title"],
31 },
32 relations: {
33 amendments: { model: "Amendment", localField: "_id", foreignField: "statuteId" },
34 },
35 },
36};Custom services
Custom services let you run logic outside Mongo queries, like search or enrichment. Each service is a named tool the AI can call for that model.
1customServices: {
2 CaseLaw: {
3 case_search: async (input) => caseService.search(input),
4 case_summary: async (input) => caseService.summary(input),
5 },
6},