SDK Registry

Connection with your data

The Model Registry serves as the client-side declarative schema that the SDK uses to validate and constrain tool calls. It acts as a metadata bridge between your database collections/tables and the Telygent AI SDK. Rather than hard-coding data access patterns, the Registry allows you to define a declarative blueprint for every entity in your system. It governs everything from security whitelisting and type enforcement to complex relational lookups and automated link generation. By configuring a ModelConfig, you provide the SDK with the intelligence it needs to transform raw database documents into structured, navigable, and context-aware objects for your frontend and AI services.

Core Identification & Security

collectionName

The direct mapping to your underlying database collection/table. This tells the SDK exactly where the physical data resides.

allowedFields

The security "whitelist". Only fields listed here are exposed to the SDK. This prevents sensitive internal data from leaking into the client layer or to the AI while ensuring the SDK only interacts with verified properties.

fieldAliases

Optional

An abstraction layer for your data. This allows you to map internal database keys/fields/column names (e.g., u_id_01) to ergonomic, developer-friendly names (e.g., userId) within the SDK.

instructions

Optional

This is the contextual compass for the AI when using this model. While the schema defines what the data is, the instructions define how it should be handled or prioritized. Think of this as a model-specific system prompt. It allows you to pass business rules or "hints" directly to the AI to influence its reasoning.

Example: For a Ticket model, an instruction might be: "When a user asks for 'urgent' tickets, always filter for priority > 3 and status: 'open'."

Example:

registry.ts

const registry = {
    Ticket: {
      collectionName: "support_tickets",
      allowedFields: ["ticketId", "status", "priority", "createdAt"],
      fieldAliases: {
        ticketId: ["ticket_id", "t_id", "case_id"],
        createdAt: ["created_at", "created_date"],
      },
      instructions: "When a user asks for 'urgent' tickets, always filter for priority > 3 and status: 'open'"
      ...
    },
  };

Data Typing

fieldTypes

Optional

Field types are used to coerce filter values (and requiredFilters) into the correct shape before queries run. This helps with dates and ObjectIds in particular. If you don’t supply fieldTypes, the SDK does not infer types — it passes values through as provided.

requiredFilters

Optional

Mandatory "guardrails" for your data access. They ensures that every query made through the SDK is scoped correctly, usually for security, ownership, or multi-tenancy purposes. If a query is attempted without these parameters, or if the SDK cannot resolve the necessary values from the application context, the request will be blocked.

The requiredFilters need the following fields:

field: The specific field in the table/collection that must be filtered (e.g., userId).
contextKey: This is the "Source of Truth." It tells the SDK to look into the Active Session/Application Context for a specific key (like the logged-in user's ID). The SDK then injects this value into the database query automatically.
type: The expected data type for the filter value (e.g., string, objectId). This ensures that the injected context value matches the database schema.

Note: You do not need to manually add these filters to every SDK call. The Registry handles the injection of contextKey values into the field query at the middleware level, ensuring data isolation is enforced by default.

Example:

registry.ts

const registry = {
    Ticket: {
      collectionName: "support_tickets",
      allowedFields: ["ticketId", "status", "priority","userId", "createdAt"],
      fieldTypes: {
        ticketId: "objectId",
        createdAt: "date",
        priority: "number",
        status: "string",
      },
      requiredFilters: [
        { field: "userId", contextKey: "userId", type: "string" },
      ],
      ...
    },
  };

Relations & Joins

relations

Optional

Defines the entity graph, how this model connects to other collections. The SDK uses these to perform lookups.

path: The attribute name in the resulting object where the associated data is merged.
target: The name of the related Model Configuration collection/table name
singleResult: A cardinality flag. If true, the SDK treats the relationship as a 1:1 or Many:1 and returns a single object. If false, it treats it as 1:Many and returns a list.
localField / foreignField: The matching keys used to link the two entities (e.g., Primary and Foreign keys).
select (optional) : to limit fields pulled from the related collection.
description (optional) : This allows you to describe the type of connection this is and give the AI a sense of what to expect

Example:

registry.ts

const registry = {
    Ticket: {
      collectionName: "support_tickets",
      allowedFields: ["ticketId", "status", "priority", "createdAt", "customerId"],
      relations: [
        {
          path: "customer",
          target: "customers",
          localField: "customerId",
          foreignField: "_id",
          select: ["_id", "name", "email", "tier"],
          singleResult: true,
          description: "Attach the customer for each ticket",
        },
      ],
      ...
    },
  };

Navigation & Link Generation

If you require Telygent AI to provide routing and links to data resources in a website, the links field helps define how the application translates internal data queries into clickable, navigable URLs. By configuring the links object, you enable the AI to move from "answering a question" to "providing a call-to-action" that takes the user exactly where they need to go in your UI.

Links field require the following:

list

Optional

The base URL path for the entity's index or search page (e.g., /tickets). This is where the AI will point users when they want to see multiple records.

detail

Optional

The template for a single resource view. It uses curly-brace placeholders (e.g., {_id} or {id}) which the SDK automatically populates with the record's Primary Key to generate a direct link to that specific item.

allowedQueryParams

Optional

A security whitelist of parameters the UI is capable of handling. The AI and SDK will refuse to generate links containing parameters not explicitly listed here, preventing "dead" or broken links.

queryParamMap

Optional

The URL Translator. It maps internal field names to the specific keys your front-end expects in the URL.

Simple Mapping: Maps a field like assigneeId to a URL param like assignee (e.g., ?assignee=123).
Range Mapping: Uses gte (Greater Than or Equal) and lte (Less Than or Equal) to map a single date field to two different URL parameters.

Example: If createdAt is mapped to { gte: "from", lte: "to" }, a query for tickets from Jan 1st will generate a link ending in?from=2024-01-01.

allowedQueryValues

Optional

Strict validation for parameter values. This tells the AI and SDK exactly what "tags" or "statuses" are valid for this entity. For example, if the AI tries to filter by a status of "broken," but the registry only allows ["open", "pending", "closed"], the SDK will catch the error before a bad link is generated.

The Transformation Logic:

Internal SDK Query	Registry Mapping	Resulting Web URL
View Ticket #42	`detail: "/tickets/{_id}"`	`/tickets/42`
View "Open" Tickets	`status: "status"`	`/tickets?status=open`
View Assigned to "Bob"	`assigneeId: "assignee"`	`/tickets?assignee=bob`
Tickets after Jan 1st	`createdAt: { gte: "from" }`	`/tickets?from=2024-01-01`

Example:

registry.ts

 const registry = {
    Ticket: {
      collectionName: "support_tickets",
      allowedFields: ["status", "priority", "createdAt", "assigneeId"],
      links: {
        list: "/tickets",
        detail: "/tickets/{_id}",
        allowedQueryParams: ["status", "priority", "createdAt", "assigneeId"],
        queryParamMap: {
          status: "status",
          priority: "priority",
          assigneeId: "assignee",
          createdAt: { gte: "from", lte: "to" },
        },
        allowedQueryValues: {
          status: ["open", "pending", "closed"],
          priority: ["low", "medium", "high"],
        },
      },
    },
  };

Custom services

By design, the AI is restricted to read-only access to your data stores. To enable actions such as updating a status, sending a notification, or performing a complex analytical summary, you must define a Custom Service. This architecture ensures the AI cannot perform "Write" operations directly to your database, forcing all actions through your verified business logic.

Each service in the customServices array acts as a Function Contract that the AI discovers and understands.

name

The unique identifier for the service. This must match the key used in your SDK implementation block (the "Handshake").

description

A detailed, natural-language explanation. The AI uses this to decide when it should call this specific service versus a standard database query.

inputSchema

A standard JSON Schema defining the parameters the AI must provide.

properties: Defines the variables (e.g., timeRangeDays or query).
required: Lists the fields the AI must collect from the user before it is allowed to trigger the function.

Custom Services aren't just for writing data; they are also used for System Functions that replace standard lookups.

If your application uses a specialized search engine (like Elasticsearch or a Vector store for AI embeddings), or if you need to perform cross-entity summaries that a standard SQL/NoSQL query cannot handle efficiently, you can define a custom_search service. The AI will then defer to your function instead of trying to build its own database query.

Key Benefits for Developers:

Database Agnostic Execution: Your service can pull data from a MongoDB collection, a PostgreSQL table, and a 3rd-party API simultaneously and return a unified result to the AI
Input Validation: The inputSchema ensures the AI never sends malformed data to your backend.
Encapsulation: Your core database remains protected. The AI only sees the "Input" and "Output," never the raw connection strings or internal logic.

Example:

registry.ts

const registry = {
    Ticket: {
      collectionName: "support_tickets",
      allowedFields: ["ticketId", "status", "priority", "createdAt", "assigneeId"],
      customServices: [
        {
          name: "ticket_search",
          description: "Search tickets by keyword and filters.",
          inputSchema: {
            type: "object",
            properties: {
              query: { type: "string" },
              status: { type: "string" },
              priority: { type: "string" },
              limit: { type: "number" },
            },
            required: ["query"],
          },
        },
        {
          name: "ticket_summary",
          description: "Summarize ticket patterns over a time range.",
          inputSchema: {
            type: "object",
            properties: {
              timeRangeDays: { type: "number" },
              tags: { type: "array", items: { type: "string" } },
            },
            required: ["timeRangeDays"],
          },
        },
      ],
    },
  };

  const client = createAiClient({
    apiKey: process.env.TELYGENT_API_KEY,
    registry,
    customServices: {
      Ticket: {
        ticket_search: async (input) => ticketService.search(input),
        ticket_summary: async (input) => ticketService.summary(input),
      },
    },
  });

Next steps

Configure AI Client

Setup the Telygent client with all required configuration

Sending requests

Create request handlers with client.query().