@simplr-ai/ai

Use Simplr as tools inside your AI agent. This package wraps Simplr's fraud / identity / phone / order checks as ready-to-use tools for LLM agents: first-class support for the Vercel AI SDK (tool() + zod), plus a framework-agnostic core so the exact same tools work with raw OpenAI function-calling and LangChain.

How this differs from the Simplr MCP servers. @simplr-ai/dev-mcp helps a coding agent build with Simplr (integration guides + snippets), and @simplr-ai/mcp is a runtime delegation gateway that exposes your own registered endpoints to AI agents. This package is neither — it gives you Simplr's checks as tools you drop directly into the agent you are building, with no MCP server to run. Under the hood it mirrors the @simplr-ai/node SDK's endpoints and response envelope.

Install

npm install @simplr-ai/ai ai zod

zod is a dependency. ai (Vercel AI SDK) and @langchain/core are optional peer dependencies — install only the one(s) for the framework you use. They are imported lazily, so the package works fine if they're absent (you'll get a clear error only when you call a function that needs them).

Quick start — Vercel AI SDK

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { createSimplrTools } from "@simplr-ai/ai";

const tools = createSimplrTools({ apiKey: process.env.SIMPLR_API_KEY! });

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools, // { simplr_check_identity, simplr_score_order, simplr_phone_intelligence, simplr_report_phone_outcome }
  maxSteps: 5,
  prompt: "A new user signed up with [email protected] and +14155552671. Are they risky?",
});

createSimplrTools returns an object of Vercel-AI tool() instances keyed by tool name. Prefer a framework-free shape? Use createSimplrToolDescriptors(config) to get plain { name, description, inputSchema, execute } descriptors.

Quick start — OpenAI function-calling

import OpenAI from "openai";
import { simplrOpenAITools, executeSimplrTool } from "@simplr-ai/ai/openai";

const config = { apiKey: process.env.SIMPLR_API_KEY! };
const client = new OpenAI();

const res = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Is +14155552671 a risky phone number?" }],
  tools: simplrOpenAITools(config), // [{ type: "function", function: { name, description, parameters } }]
});

const call = res.choices[0].message.tool_calls?.[0];
if (call) {
  const result = await executeSimplrTool(call.function.name, call.function.arguments, config);
  // feed `result` back to the model as a tool message…
}

No OpenAI SDK is required to build the schemas — simplrOpenAITools returns plain JSON. executeSimplrTool validates the model's arguments against the tool's zod schema before calling the API.

Quick start — LangChain

import { ChatOpenAI } from "@langchain/openai";
import { createSimplrLangChainTools } from "@simplr-ai/ai/langchain";

const tools = await createSimplrLangChainTools({ apiKey: process.env.SIMPLR_API_KEY! });
const model = new ChatOpenAI({ model: "gpt-4o" }).bindTools(tools);

Returns DynamicStructuredTool instances. Requires @langchain/core.

Tool catalog

| Tool | Endpoint | What it does | | --- | --- | --- | | simplr_check_identity | POST /v1/check | Score a user/event (email and/or phone) for fraud/identity risk — signups, logins, password resets. | | simplr_score_order | POST /v1/orders | Score a placed order/transaction for payment fraud risk. | | simplr_phone_intelligence | GET /v1/check/phone/intelligence/{phone} | Read-only lookup of stored risk intelligence for a phone number (carrier, line type, SIM-swap signals). | | simplr_report_phone_outcome | POST /v1/check/phone/report | Feedback signal: report a confirmed real-world outcome for a phone to improve future scoring. |

Every check result includes risk_score (0–100, higher = riskier) and risk_level — one of low, medium, high, critical. Use those to decide whether to allow, challenge (step-up auth / manual review), or block.

Public API by subpath

| Import | Exports | | --- | --- | | @simplr-ai/ai | createSimplrTools(config), createSimplrToolDescriptors(config), SimplrClient, schemas, SimplrError, all result types | | @simplr-ai/ai/openai | simplrOpenAITools(config), executeSimplrTool(name, args, config), zodToJsonSchema | | @simplr-ai/ai/langchain | createSimplrLangChainTools(config) |

config is { apiKey: string; baseUrl?: string; timeoutMs?: number; fetch?: typeof fetch }.

Security

Use a secret key (sk_live_… / sk_test_…) and only ever construct these tools server-side — in your API route, agent backend, or worker. Never ship a secret key (or these tool factories) to a browser, mobile app, or any client the model's user controls. The key is sent as the X-API-Key header. Default per-request timeout is 15s.

Docs & license

Full API reference: https://simplr-docs-three.vercel.app/sdks/. Commercial software; see LICENSE.