agentid-sdk 0.1.18 → 0.1.20

package/README.md

@@ -1,65 +1,226 @@
-# 🛡️ AgentID: Enterprise AI Governance & PII Shield
+# agentid-sdk (Node.js / TypeScript)
 
-AgentID je inteligentní brána (gateway) pro vaše LLM aplikace. Monitoruje náklady, filtruje PII (osobní údaje) v reálném čase a zajišťuje soulad s GDPR.
+[![npm version](https://img.shields.io/npm/v/agentid-sdk.svg)](https://www.npmjs.com/package/agentid-sdk)
+[![Node](https://img.shields.io/node/v/agentid-sdk.svg)](https://www.npmjs.com/package/agentid-sdk)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## 🚀 Rychlý start (60 sekund)
+## 1. Introduction
 
-### 1. Instalace
+`agentid-sdk` is the official Node.js/TypeScript SDK for AgentID, an AI security and compliance System of Record. It allows you to gate LLM traffic through guard checks, enforce policy before execution, and capture durable telemetry for audit and governance workflows.
 
-```bash
-# Pro Python projekty
-pip install agentid-sdk
+### The Mental Model
 
-# Pro JavaScript/TypeScript projekty
-npm install agentid-sdk
+AgentID sits between your application and the LLM runtime:
+
+```text
+User Input -> guard() -> [AgentID Policy] -> verdict
+                              | allowed
+                              v
+                         LLM Provider
+                              v
+                           log() -> [Immutable Ledger]
 ```
 
-### 2. Integrace (Python)
+- `guard()`: evaluates prompt and context before model execution.
+- Model call: executes only if guard verdict is allowed.
+- `log()`: persists immutable telemetry (prompt, output, latency) for audit and compliance.
 
-Stačí zabalit vašeho stávajícího OpenAI klienta.
+## 2. Installation
 
-```python
-from openai import OpenAI
-from agentid import AgentID
+```bash
+npm install agentid-sdk
+```
+
+## 3. Prerequisites
 
-client = OpenAI(api_key="your_openai_key")
-agent = AgentID(api_key="ag_prod_...")
+1. Create an account at `https://app.getagentid.com`.
+2. Create an AI system and copy:
+   - `AGENTID_API_KEY` (for example `sk_live_...`)
+   - `AGENTID_SYSTEM_ID` (UUID)
+3. If using OpenAI/LangChain, set:
+   - `OPENAI_API_KEY`
 
-# Automaticky filtruje PII a loguje metriky
-response = agent.wrap_openai(client, system_id="sys_...").chat.completions.create(
-    model="gpt-4",
-    messages=[{"role": "user", "content": "Můj email je jan.novak@firma.cz"}]
-)
+```bash
+export AGENTID_API_KEY="sk_live_..."
+export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
+export OPENAI_API_KEY="sk-proj-..."
 ```
 
-### 3. Integrace (Node.js)
+### Compatibility
+
+- **Node.js:** v18+ / **Python:** 3.9+ (cross-SDK matrix)
+- **Thread Safety:** AgentID clients are thread-safe and intended to be instantiated once and reused across concurrent requests.
+- **Latency:** async `log()` is non-blocking for model execution paths; sync `guard()` typically adds network latency (commonly ~50-100ms, environment-dependent).
+
+## 4. Quickstart
 
 ```ts
 import { AgentID } from "agentid-sdk";
+
+const agent = new AgentID(); // auto-loads AGENTID_API_KEY
+const systemId = process.env.AGENTID_SYSTEM_ID!;
+
+const verdict = await agent.guard({
+  system_id: systemId,
+  input: "Summarize this ticket in one sentence.",
+  model: "gpt-4o-mini",
+  user_id: "quickstart-user",
+});
+if (!verdict.allowed) throw new Error(`Blocked: ${verdict.reason}`);
+
+await agent.log({
+  system_id: systemId,
+  event_id: verdict.client_event_id,
+  model: "gpt-4o-mini",
+  input: "Summarize this ticket in one sentence.",
+  output: "Summary generated.",
+  metadata: { agent_role: "support-assistant" },
+});
+```
+
+## 5. Core Integrations
+
+### OpenAI Wrapper
+
+```bash
+npm install agentid-sdk openai
+```
+
+```ts
 import OpenAI from "openai";
+import { AgentID } from "agentid-sdk";
 
-const openai = new OpenAI();
 const agent = new AgentID({
-  apiKey: "ag_prod_...",
-  strictMode: false, // default (fail-open on timeout/unreachable AgentID API)
-  guardTimeoutMs: 6000, // optional: timeout for AgentID /guard call in ms
-  // strictMode: true, // fail-closed for high-risk workloads
+  piiMasking: true,
+});
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
+const secured = agent.wrapOpenAI(openai, {
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  user_id: "customer-123",
 });
 
-const proxiedOpenAI = agent.wrapOpenAI(openai, {
-  system_id: "sys_...",
-  user_id: "system-auto-summary", // optional service/user identity
+const response = await secured.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "What is the capital of the Czech Republic?" }],
 });
+
+console.log(response.choices[0]?.message?.content ?? "");
 ```
 
-## 🔒 Klíčové vlastnosti
+### LangChain Integration
+
+```bash
+npm install agentid-sdk openai @langchain/core @langchain/openai
+```
+
+```ts
+import { AgentID } from "agentid-sdk";
+import { AgentIDCallbackHandler } from "agentid-sdk/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { ChatPromptTemplate } from "@langchain/core/prompts";
+import { StringOutputParser } from "@langchain/core/output_parsers";
+
+const agent = new AgentID();
+const handler = new AgentIDCallbackHandler(agent, {
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+});
+
+const prompt = ChatPromptTemplate.fromTemplate("Answer in one sentence: {question}");
+const model = new ChatOpenAI({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-4o-mini",
+});
+const chain = prompt.pipe(model).pipe(new StringOutputParser());
+
+const result = await chain.invoke(
+  { question: "What is the capital of the Czech Republic?" },
+  { callbacks: [handler] }
+);
+console.log(result);
+```
+
+### Raw Ingest API (Telemetry Only)
+
+```ts
+import { AgentID } from "agentid-sdk";
+
+const agent = new AgentID();
+
+await agent.log({
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  event_type: "complete",
+  severity: "info",
+  model: "gpt-4o-mini",
+  input: "Raw telemetry prompt",
+  output: '{"ok": true}',
+  metadata: { agent_role: "batch-worker", channel: "manual_ingest" },
+});
+```
+
+## 6. Advanced Configuration
+
+### Custom identity / role metadata
+
+```ts
+await agent.guard({
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  input: "Process user request",
+  user_id: "service:billing-agent",
+  model: "gpt-4o-mini",
+});
+
+await agent.log({
+  system_id: process.env.AGENTID_SYSTEM_ID!,
+  model: "gpt-4o-mini",
+  input: "Process user request",
+  output: "Done",
+  metadata: { agent_role: "billing-agent", environment: "prod" },
+});
+```
+
+### Strict mode and timeout tuning
+
+```ts
+const agent = new AgentID({
+  strictMode: true,      // fail-closed on guard connectivity/timeouts
+  guardTimeoutMs: 10000, // default guard timeout is 10000ms
+  ingestTimeoutMs: 10000 // default ingest timeout is 10000ms
+});
+```
+
+### Error Handling & Strict Mode
+
+By default, AgentID is designed to keep your application running if the AgentID API has a timeout or is temporarily unreachable.
+
+| Mode | Connectivity Failure | LLM Execution | Best For |
+| :--- | :--- | :--- | :--- |
+| **Default** (Strict Off) | API Timeout / Unreachable | **Fail-Open** (continues) | Standard SaaS, chatbots |
+| **Strict Mode** (`strictMode: true`) | API Timeout / Unreachable | **Fail-Closed** (blocks) | Healthcare, FinTech, high-risk |
+
+- `guard()` returns a verdict (`allowed`, `reason`); handle deny paths explicitly.
+- `wrapOpenAI()` and LangChain handlers throw `SecurityBlockError` when a prompt is blocked.
+- If `strictMode` is not explicitly set in SDK code, runtime behavior follows the system configuration from AgentID (`strict_security_mode` / `failure_mode`).
+- Ingest retries transient failures (5xx/429) and logs warnings if persistence fails.
+
+## 7. Security & Compliance
+
+- Optional local PII masking and local policy enforcement before model dispatch.
+- Prompt-injection scanning in the SDK request path.
+- Guard checks run pre-execution; ingest telemetry captures prompt/output lifecycle.
+- Safe for server and serverless runtimes (including async completion flows).
+- Supports compliance and forensics workflows with durable event records.
+
+## 8. Support
+
+- Dashboard: `https://app.getagentid.com`
+- Repository: `https://github.com/ondrejsukac-rgb/agentid/tree/main/js-sdk`
+- Issues: `https://github.com/ondrejsukac-rgb/agentid/issues`
 
-- PII Scrubbing: Automatická redakce e-mailů, rodných čísel a hesel před odesláním do cloudu.
-- Crypto-Shredding: Možnost nenávratně smazat citlivá data z logů na žádost uživatele (GDPR).
-- Fail-Safe architektura: Inteligentní přepínání mezi bezpečností a dostupností (Fail-Open/Closed).
-- Strict mode: při timeoutu Guard API můžeš vynutit fail-closed (`strictMode: true`).
+## 9. Publishing Notes (NPM)
 
-## Guard transformed input
+NPM automatically renders `README.md` from the package root during `npm publish`.
 
-If `/guard` returns `transformed_input`, the OpenAI and LangChain wrappers automatically
-forward that transformed value to the downstream LLM call.
+- File location: next to `package.json` in `js-sdk/`.
+- No additional NPM config is required for README rendering.