@letsping/adapters 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,85 @@
+# @letsping/adapters
+
+Drop-in Human-in-the-Loop tool adapters for popular AI agent frameworks.
+
+This package provides strictly-typed wrappers around `@letsping/sdk` that integrate seamlessly with:
+
+- Vercel AI SDK (as `CoreTool`)
+- LangChain / LangGraph (as `DynamicStructuredTool`)
+
+When a model invokes one of these tools, execution pauses until the request is approved or rejected via the LetsPing dashboard.
+
+## Installation
+
+```bash
+npm install @letsping/adapters @letsping/sdk zod
+```
+
+## Vercel AI SDK Integration
+
+Export: `@letsping/adapters/vercel`
+
+```ts
+import { letsPing } from "@letsping/adapters/vercel";
+import { z } from "zod";
+
+const tools = {
+  deployToProd: letsPing({
+    name: "deploy_production",
+    description: "Deploys the current codebase to production. Requires human approval.",
+    apiKey: process.env.LETSPING_API_KEY!,
+    // Schema controls the editable form presented to the human operator
+    schema: z.object({
+      version: z.string().describe("Git commit SHA or version tag"),
+      canary: z.boolean().default(false).describe("Deploy as canary release"),
+      force: z.boolean().optional().describe("Bypass additional safety checks"),
+    }),
+  }),
+};
+```
+
+The tool automatically suspends model generation until a decision is made in the LetsPing dashboard.
+
+## LangChain / LangGraph Integration
+
+Export: `@letsping/adapters/langchain`
+
+```ts
+import { createLetsPingTool } from "@letsping/adapters/langchain";
+import { z } from "zod";
+
+const approvalTool = createLetsPingTool({
+  name: "sensitive_action",
+  description: "Request human permission before proceeding with this operation.",
+  apiKey: process.env.LETSPING_API_KEY!,
+  schema: z.object({
+    reason: z.string().min(10).describe("Explain why this step is required"),
+    estimated_impact: z.enum(["low", "medium", "high"]).default("medium"),
+  }),
+});
+
+// Example usage in LangGraph or classic LangChain
+const agent = new AgentExecutor({
+  tools: [approvalTool /*, other tools */],
+  llm,
+  // ...
+});
+```
+
+## Peer Dependencies
+
+Make sure the following compatible versions are installed in your project:
+
+| Package                  | Minimum Version | Purpose                                 |
+|--------------------------|------------------|-----------------------------------------|
+| `zod`                    | `>= 3.0.0`      | Schema definition & validation          |
+| `ai`                     | `>= 2.0.0`      | Vercel AI SDK (for `/vercel` adapter)   |
+| `@langchain/core`        | `>= 0.1.0`      | LangChain core types & tools            |
+
+## Notes
+
+- The `apiKey` is passed per-tool. For most applications you will use the same key across tools.
+- The `schema` (Zod) is used both for type safety and to generate an editable form in the LetsPing dashboard.
+- If the human modifies values in the form, the resolved payload will contain the updated values (`patched_payload` in the LetsPing SDK response).
+
+For full LetsPing API documentation, see: https://letsping.co/docs

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@letsping/adapters",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Drop-in Human-in-the-Loop adapters for Vercel AI SDK and LangChain",
     "files": [
         "dist"