@lakimi/external-schema

@lakimi/external-schema is a library that facilitates integrating Node.js applications with Lakimi's function execution pipeline. It allows you to register custom tools and respond to events using socket.io, ensuring real-time communication with the Lakimi platform.

🚀 Features

• Register tools with input schemas defined using JSONSchema.
• Support for authentication and role-based access control.
• Real-time communication with socket.io.
• Event handling for tool execution and schema registration.

📦 Installation

npm install @lakimi/external-schema

Or with Yarn:

yarn add @lakimi/external-schema

⚙️ Configuration

Create a client instance

The first step is to create an instance of LakiExternalSchemaClient, providing the necessary connection options.

import { LakiExternalSchemaClient } from "@lakimi/external-schema";

const client = new LakiExternalSchemaClient({
  clientId: "your-client-id",
  secretKey: "your-secret-key",
  environment: "production", // or "development"
  name: "MyApp",
  url: "https://api.lakimi.io/external-schema" // optional
});

Connect the client

To start communicating with the Lakimi platform, call the connect method:

client.connect();

🛠 Registering and Handling Tools

You can register tools that the client will execute upon receiving a request from Lakimi. Each tool must define its input schema (input_schema) and provide a handler function (handle) to implement the desired logic.

Defining a Tool

import { JSONSchema7 } from "json-schema";
import { LakiTool } from "@lakimi/external-schema";

const myTool: LakiTool = {
  name: "example_tool",
  description: "An example tool that adds two numbers.",
  input_schema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  },
  handle: async ({ input }) => {
    const { a, b } = input as { a: number; b: number };
    return { result: a + b };
  }
};

Registering the Tool with the Client

client.useTool(myTool);

📡 Events Handled by the Client

• connect: Notifies that the client has successfully connected to the Lakimi platform.
• disconnect: Notifies that the client has disconnected.
• request_schema: Requests the client to register its tool schema.
• execute_tool: Requests the execution of a registered tool.

📚 Full Example

import { LakiExternalSchemaClient, LakiTool } from "@lakimi/external-schema";
import { JSONSchema7 } from "json-schema";

const client = new LakiExternalSchemaClient({
  clientId: "my-client-id",
  secretKey: "my-secret-key",
  environment: "development",
  name: "MyAwesomeApp"
});

const sumTool: LakiTool = {
  name: "sum_tool",
  description: "Adds two numbers.",
  input_schema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  },
  handle: async ({ input }) => {
    const { a, b } = input as { a: number; b: number };
    return { result: a + b };
  }
};

client.useTool(sumTool);
client.connect();

⚠️ Common Errors

• Tool not found: Make sure the tool is registered with the correct name.
• Connection failed: Verify your clientId, secretKey, and the url field.

📖 API Reference

LakiExternalSchemaClient(options: LakiExternalSchemaClientOptions)

Creates a new client instance.

• options.clientId: The client ID.
• options.secretKey: The client secret key.
• options.environment: The environment (production or development).
• options.name: The application name.
• options.url: (optional) The server URL.

useTool(tool: LakiTool): LakiExternalSchemaClient

Registers a tool in the client.

connect(): void

Connects the client to the Lakimi platform.

📑 Types and Schemas

LakiExternalSchemaClientOptions

interface LakiExternalSchemaClientOptions {
  clientId: string;
  secretKey: string;
  environment: string;
  name: string;
  url?: string;
}

LakiTool

interface LakiTool {
  name: string;
  description: string;
  input_schema: JSONSchema7;
  constraints?: LakiConstraints;
  handle: (context: LakiToolContext) => Promise<any>;
}

📝 License

ISC © 2025 Lakimi Solutions S.L.