Telygent AI SDK

Client-side SDK to connect your app to Telygent AI. The SDK stores conversation history in your Redis, executes database tools locally, and sends tool results to Telygent for AI reasoning.

Install

npm install @telygent/ai-sdk

Required dependencies

npm install ioredis mongodb

Usage

import { createAiClient, createRedisHistoryStore, createMongoAdapter, type ModelRegistry } from "@telygent/ai-sdk";
import { MongoClient } from "mongodb";

const historyStore = createRedisHistoryStore({
  url: process.env.REDIS_URL as string,
  ttlSeconds: 3600,
});

const mongoClient = new MongoClient(process.env.MONGO_URI as string);
await mongoClient.connect();
const mongoDb = mongoClient.db(process.env.MONGO_DB_NAME as string);

const registry = {
  Statute: {
    collectionName: "canadian_statutes",
    allowedFields: ["title", "shortTitle", "year", "jurisdiction", "topics", "createdAt"],
    links: {
      list: "/laws/statutes",
      detail: "/laws/statutes/{_id}",
      allowedQueryParams: ["year", "jurisdiction", "topics", "createdAt"],
      queryParamMap: {
        year: "year",
        jurisdiction: "jurisdiction",
        topics: "topic",
        createdAt: { gte: "fromDate", lte: "toDate" },
      },
      allowedQueryValues: {
        jurisdiction: ["federal", "provincial"],
      },
    },
    fieldTypes: {
      _id: "objectId",
      createdAt: "date",
    },
    requiredFilters: [
      { field: "jurisdiction", contextKey: "jurisdiction", type: "string" }
    ],
    instructions:
      "Use jurisdiction filters (federal or provincial) and default to the most recent 5 years when dates are missing.",
  },
  CaseLaw: {
    collectionName: "canadian_cases",
    allowedFields: ["title", "citation", "court", "decisionDate", "topics", "summary"],
    links: {
      list: "/laws/cases",
      detail: "/laws/cases/{_id}",
      allowedQueryParams: ["court", "decisionDate", "topics"],
      queryParamMap: {
        court: "court",
        decisionDate: { gte: "fromDate", lte: "toDate" },
        topics: "topic",
      },
    },
    fieldTypes: {
      _id: "objectId",
      decisionDate: "date",
    },
    customServices: [
      {
        name: "case_search",
        description: "Search Canadian case law by title, citation, or topic.",
        inputSchema: {
          properties: {
            query: { type: "string", optional: false, description: "Title, citation, or keyword." },
            court: { type: "string", optional: true, description: "e.g., SCC, FCA, ONSC." },
            year: { type: "number", optional: true, description: "Decision year filter." },
            limit: { type: "number", optional: true, description: "Maximum results to return." }
          }
        }
      },
      {
        name: "case_summary",
        description: "Fetch a short summary for a single case by citation.",
        inputSchema: {
          properties: {
            citation: { type: "string", optional: false, description: "Case citation, e.g. 2018 SCC 10." }
          }
        }
      }
    ]
  },
} satisfies ModelRegistry;

// If you don't have Redis yet, omit `historyStore` and the SDK will use empty history.

const dbAdapter = createMongoAdapter({
  db: mongoDb,
  registry,
});

const client = createAiClient({
  apiKey: process.env.TELYGENT_API_KEY as string,
  aiName: "Atlas",
  registry,
  historyStore,
  dbAdapter,
  customServices: {
    CaseLaw: {
      case_search: async (input) => caseService.search(input),
      case_summary: async (input) => caseService.summary(input),
    },
  },
  log: false,
});

const response = await client.query({
  question: "Show me federal statutes on privacy passed after 2018",
  conversationId: "conv_123",
  userContext: {
    userId: "user_1",
    jurisdiction: "federal",
  },
});

console.log(response.content);

const messages = await client.getConversationMessages("conv_123");
console.log(messages);

Reload conversation history

import { createAiClient, createRedisHistoryStore, type ModelRegistry } from "@telygent/ai-sdk";

const historyStore = createRedisHistoryStore({
  url: process.env.REDIS_URL as string,
});

// Requires Redis. If you don't pass a history store, this returns an empty list.

const client = createAiClient({
  apiKey: process.env.TELYGENT_API_KEY as string,
  aiName: "Atlas",
  historyStore,
});

const messages = await client.getConversationMessages("conv_123");
console.log(messages);

Notes

• Conversation history lives in your Redis and is sent to Telygent each request.
• Database queries are executed locally through the adapter you provide.
• Registry is static and versioned by hash after initial sync.
• Use requiredFilters to inject fixed constraints into queries.
• Custom services are optional and let the AI call your own per-model lookup handlers.
• Use getConversationMessages to reload message history from Redis.
• For Redis, create a single shared client (or use createRedisHistoryStore) to avoid exhausting the max client limit.

Express middleware

import express from "express";
import { attachAiClient, RedisHistoryStore, createMongoAdapter } from "@telygent/ai-sdk";

const app = express();
app.use(express.json());

app.use(
  attachAiClient({
    apiKey: process.env.TELYGENT_API_KEY as string,
    registry,
    historyStore: new RedisHistoryStore({ client: redisClient }),
    dbAdapter: createMongoAdapter({ db: mongoDb, registry }),
  })
);

app.post("/ask", async (req, res) => {
  const { question, conversationId, userContext } = req.body;
  const response = await req.aiClient!.query({ question, conversationId, userContext });
  res.json(response);
});