@tenet-ai/sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,357 @@
+# @tenet-ai/sdk
+
+**Git for AI Agent Decisions** - Complete audit trail, replay, and drift detection for enterprise AI agents.
+
+[![npm version](https://badge.fury.io/js/@tenet-ai%2Fsdk.svg)](https://www.npmjs.com/package/@tenet-ai/sdk)
+[![Node.js 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why Tenet AI?
+
+When your AI agent approves a $10,000 refund or denies a loan application, can you answer:
+
+- **Why** did the agent make that decision?
+- **What context** did it have at the time?
+- **Would it decide the same way** if we ran it again?
+- **Who overrode** the agent's recommendation?
+
+Tenet AI captures every decision your agent makes with full context, enabling **audit trails**, **replay verification**, and **drift detection**.
+
+---
+
+## Installation
+
+```bash
+npm install @tenet-ai/sdk
+```
+
+---
+
+## Quick Start
+
+### High-Level: `trace()`
+
+Wrap any agent function call in a single line:
+
+```ts
+import { Tenet } from "@tenet-ai/sdk";
+
+const tenet = new Tenet({ apiKey: "tnt_your_key" });
+
+const result = await tenet.trace({
+  agentId: "support-agent",
+  fn: async () => {
+    // Your agent logic here
+    return { action: "approve_refund", amount: 149.99 };
+  },
+  tags: ["production", "refunds"],
+  metadata: { customer_id: "C-123" },
+});
+
+console.log(result.executionId); // Stored in Tenet for audit
+console.log(result.output);      // { action: "approve_refund", amount: 149.99 }
+```
+
+### Low-Level: Full Control
+
+For fine-grained tracking with context, decisions, and executions:
+
+```ts
+import { Tenet, ResultType, ActorType } from "@tenet-ai/sdk";
+
+const tenet = new Tenet({ apiKey: "tnt_your_key" });
+
+// 1. Create an intent
+const intent = await tenet.createIntent({
+  goal: "Process refund request",
+  agentId: "support-agent",
+});
+
+// 2. Capture what the agent saw
+await intent.snapshotContext({
+  customer_tier: "gold",
+  order_amount: 149.99,
+  days_since_delivery: 5,
+});
+
+// 3. Record the decision with options considered
+await intent.decide({
+  options: [
+    { action: "approve_refund", score: 0.95, reason: "Gold customer, within policy" },
+    { action: "deny_refund", score: 0.05, reason: "N/A" },
+  ],
+  chosenAction: "approve_refund",
+  confidence: 0.95,
+  reasoning: "Customer eligible per 30-day return policy",
+});
+
+// 4. Record execution
+const executionId = await intent.execute({
+  action: "approve_refund",
+  target: { order_id: "ORD-123" },
+  result: ResultType.SUCCESS,
+});
+```
+
+---
+
+## Key Features
+
+### Decision Replay with Drift Detection
+
+Store the prompt and re-run decisions to verify consistency:
+
+```ts
+const intent = await tenet.createIntent({
+  goal: "Handle support ticket",
+  agentId: "support-agent",
+});
+
+await intent.snapshotContext({ ticket_id: "T-123", priority: "high" });
+
+await intent.decide({
+  options: [{ action: "escalate", score: 0.9 }],
+  chosenAction: "escalate",
+  confidence: 0.9,
+  reasoning: "High priority ticket requires escalation",
+  replayPrompt: "You are a support agent. Ticket: high priority. Action?",
+  replayConfig: { model: "gpt-4o-mini", temperature: 0.0 },
+});
+
+const execId = await intent.execute({
+  action: "escalate",
+  target: { ticket_id: "T-123" },
+  result: ResultType.SUCCESS,
+});
+
+// Later: verify the decision is still consistent
+const replay = await tenet.replay({ executionId: execId });
+
+console.log(replay.drift_score); // 0.0 = identical, 1.0 = fully diverged
+if (replay.diverged) {
+  console.log("WARNING: Model behavior changed!");
+}
+```
+
+### Multi-Agent Tracking (Parent-Child Intents)
+
+Track complex workflows with multiple agents or MCP tool calls:
+
+```ts
+const parent = await tenet.createIntent({
+  goal: "Process customer request",
+  agentId: "orchestrator",
+});
+
+await parent.snapshotContext({ request: "refund for order 123" });
+
+// Spawn child intent for sub-agent
+const child = await parent.childIntent({
+  goal: "Search order history",
+  mcpServer: "database",
+});
+
+await child.snapshotContext({ query: "order 123" });
+await child.decide({
+  options: [{ action: "query_db", score: 1.0 }],
+  chosenAction: "query_db",
+  confidence: 1.0,
+});
+await child.execute({
+  action: "query_db",
+  target: { order_id: "123" },
+  result: ResultType.SUCCESS,
+});
+
+// Parent continues with child's result
+await parent.decide({
+  options: [
+    { action: "approve_refund", score: 0.9, reason: "Order found, within policy" },
+  ],
+  chosenAction: "approve_refund",
+  confidence: 0.9,
+});
+await parent.execute({
+  action: "approve_refund",
+  target: { order_id: "123" },
+  result: ResultType.SUCCESS,
+});
+```
+
+### Human Override Tracking
+
+When humans override agent decisions:
+
+```ts
+await intent.execute({
+  action: "deny_refund",              // Human chose differently
+  target: { order_id: "123" },
+  result: ResultType.SUCCESS,
+  actor: ActorType.HUMAN,
+  overrideReason: "Customer has history of fraud",
+});
+```
+
+---
+
+## Framework Integrations
+
+### LangChain.js
+
+```ts
+import { Tenet } from "@tenet-ai/sdk";
+import { TenetCallbackHandler } from "@tenet-ai/sdk/integrations/langchain";
+
+const tenet = new Tenet({ apiKey: "tnt_your_key" });
+const handler = new TenetCallbackHandler({
+  client: tenet,
+  agentId: "langchain-agent",
+});
+
+// Pass as a callback to any LangChain.js chain or agent
+const result = await chain.invoke({ input: "Process refund" }, { callbacks: [handler] });
+```
+
+### OpenAI Node SDK
+
+```ts
+import OpenAI from "openai";
+import { Tenet } from "@tenet-ai/sdk";
+import { TenetOpenAITracker } from "@tenet-ai/sdk/integrations/openai";
+
+const openai = new OpenAI();
+const tenet = new Tenet({ apiKey: "tnt_your_key" });
+const tracker = new TenetOpenAITracker({
+  client: tenet,
+  agentId: "openai-agent",
+});
+
+// Wrap the OpenAI client — all chat completions are tracked automatically
+const tracked = tracker.wrap(openai);
+const response = await tracked.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Process this refund" }],
+});
+```
+
+### Vercel AI SDK
+
+```ts
+import { generateText } from "ai";
+import { Tenet } from "@tenet-ai/sdk";
+import { TenetVercelAITracker } from "@tenet-ai/sdk/integrations/vercel-ai";
+
+const tenet = new Tenet({ apiKey: "tnt_your_key" });
+const tracker = new TenetVercelAITracker({
+  client: tenet,
+  agentId: "vercel-agent",
+});
+
+// Wrap generateText — all calls are tracked automatically
+const trackedGenerateText = tracker.wrapGenerateText(generateText);
+const result = await trackedGenerateText({
+  model: yourModel,
+  prompt: "Process this refund",
+});
+```
+
+---
+
+## API Reference
+
+### Constructor
+
+```ts
+const tenet = new Tenet({
+  apiKey: "tnt_your_key",                              // Required
+  endpoint: "https://tenet-backend.onrender.com",      // Optional (default: production)
+  environment: "production",                            // Optional
+  timeout: 30000,                                       // Optional (ms)
+});
+```
+
+### High-Level Methods
+
+| Method | Description |
+|--------|-------------|
+| `tenet.trace({ agentId, fn, ... })` | Wrap a function call with automatic audit trail |
+| `tenet.replay({ executionId })` | Replay a past decision and detect drift |
+
+### Low-Level Methods
+
+| Method | Description |
+|--------|-------------|
+| `tenet.createIntent({ goal, agentId })` | Create an intent, returns `IntentHandle` |
+| `intent.snapshotContext(inputs)` | Capture what the agent sees |
+| `intent.decide({ options, chosenAction, confidence })` | Record a decision |
+| `intent.execute({ action, target, result })` | Record execution |
+| `intent.childIntent({ goal, mcpServer })` | Create a child intent (multi-agent) |
+
+### Read Methods
+
+| Method | Description |
+|--------|-------------|
+| `tenet.getIntent(id)` | Get intent details |
+| `tenet.getIntentChildren(id)` | Get child intents |
+| `tenet.getIntentHierarchy(id)` | Get parent chain (breadcrumbs) |
+| `tenet.getIntentTree(id)` | Get full descendant tree |
+| `tenet.getDecision(id)` | Get decision details |
+| `tenet.listDecisions({ agentId, tags, ... })` | List and filter decisions |
+| `tenet.getExecution(id)` | Get execution details |
+| `tenet.getSessionTimeline(sessionId)` | Get full session timeline |
+
+### Advanced
+
+| Method | Description |
+|--------|-------------|
+| `tenet.checkDrift({ sampleSize, timeWindowHours })` | Batch drift detection |
+| `tenet.generateComplianceReport({ regulation })` | Generate compliance report |
+| `tenet.revert({ executionId, reason })` | Revert an execution |
+
+---
+
+## Getting Started
+
+### 1. Create an Account
+
+Go to [tenetai.dev](https://tenetai.dev) and sign in with Google.
+
+### 2. Create a Workspace
+
+After signing in, create a workspace (e.g., "Production Agents").
+
+### 3. Generate an API Key
+
+Navigate to **API Keys** > **Create API Key** > Copy your key (`tnt_xxxx...`).
+
+### 4. Install the SDK
+
+```bash
+npm install @tenet-ai/sdk
+```
+
+---
+
+## Use Cases
+
+| Industry | Use Case |
+|----------|----------|
+| **FinTech** | Audit loan decisions, fraud detection reasoning |
+| **Healthcare** | Track triage recommendations, document clinical AI decisions |
+| **E-commerce** | Refund approvals, pricing decisions, inventory management |
+| **Legal** | Contract analysis decisions, compliance checking |
+| **HR** | Resume screening, candidate ranking explanations |
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Links
+
+- **Dashboard**: [tenetai.dev](https://tenetai.dev)
+- **npm**: [npmjs.com/package/@tenet-ai/sdk](https://www.npmjs.com/package/@tenet-ai/sdk)
+- **Python SDK**: [pypi.org/project/tenet-ai](https://pypi.org/project/tenet-ai/)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@tenet-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node.js SDK for Tenet AI - Audit trail and replay for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",