agentid-sdk 0.1.19 → 0.1.20

package/README.md

@@ -9,6 +9,23 @@
 
 `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.
 
+### The Mental Model
+
+AgentID sits between your application and the LLM runtime:
+
+```text
+User Input -> guard() -> [AgentID Policy] -> verdict
+                              | allowed
+                              v
+                         LLM Provider
+                              v
+                           log() -> [Immutable Ledger]
+```
+
+- `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.
+
 ## 2. Installation
 
 ```bash
@@ -30,6 +47,12 @@ export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
 export OPENAI_API_KEY="sk-proj-..."
 ```
 
+### 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
@@ -163,16 +186,22 @@ await agent.log({
 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 behavior
+### 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()` throws `Error("AgentID: Security Blocked (...)")` when blocked.
-- Default mode is fail-open for connectivity/timeouts (`timeout_fallback`, `guard_unreachable`, `system_failure_fail_open`).
+- `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`).
-- Set `strictMode: true` to fail-closed (`network_error_strict_mode` / `server_error`) in high-sensitivity environments.
 - Ingest retries transient failures (5xx/429) and logs warnings if persistence fails.
 
 ## 7. Security & Compliance