{"_id":"@timemachine-sdk/sdk","_rev":"2-6eb342a712552666daf10ab88309ce8b","name":"@timemachine-sdk/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@timemachine-sdk/sdk","version":"0.1.0","keywords":["ai","agents","observability","debugging","langchain","crewai","llm","tracing","ai-agents","monitoring","replay","fork"],"author":{"name":"Time Machine","email":"hello@timemachine.dev"},"license":"MIT","_id":"@timemachine-sdk/sdk@0.1.0","maintainers":[{"name":"deva00","email":"yansh2017@gmail.com"}],"homepage":"https://github.com/ya-nsh/time-machine-sdk#readme","bugs":{"url":"https://github.com/ya-nsh/time-machine-sdk/issues"},"dist":{"shasum":"67774e579cde27402a19b799f00c0b46616b5753","tarball":"https://registry.npmjs.org/@timemachine-sdk/sdk/-/sdk-0.1.0.tgz","fileCount":24,"integrity":"sha512-8yJSQzh3BuRu31/ak6U3yX7n/CZ180WJOPFzr7bRlFxC/iXw66Lzb296ijU6guPPwMa/DNIfRAIyJpxgBFje3A==","signatures":[{"sig":"MEQCIEGY49Vey6pOrBXlClzqD+gDjkNCkJAh9YFRTA97vFa3AiAP1+6z+WCmFhZln4lIbYAn5ALSW1kuHOq6lFpKWKrkLw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106432},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./utils":{"types":"./dist/utils/index.d.ts","import":"./dist/utils/index.mjs","require":"./dist/utils/index.js"},"./adapters":{"types":"./dist/adapters/index.d.ts","import":"./dist/adapters/index.mjs","require":"./dist/adapters/index.js"}},"gitHead":"d2f10a51faa473b9a36a1f76aaf5c69de16c24d0","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"deva00","email":"yansh2017@gmail.com"},"repository":{"url":"git+https://github.com/ya-nsh/time-machine-sdk.git","type":"git","directory":"packages/sdk-ts"},"_npmVersion":"10.9.3","description":"Time Machine SDK for AI Agent Observability — capture, debug, and replay AI agent executions","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.2.0","typescript":"^5.3.0","@types/node":"^20.11.0","@langchain/core":"^0.3.0","@langchain/openai":"^0.3.0","@timemachine/shared":"workspace:*"},"peerDependencies":{"@langchain/core":">=0.2.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1771859923484_0.034486122460055","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@timemachine-sdk/sdk","version":"0.1.1","description":"Time Machine SDK for AI Agent Observability — capture, debug, and replay AI agent executions","author":{"name":"Time Machine","email":"hello@timemachine.dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ya-nsh/time-machine-sdk.git","directory":"packages/sdk-ts"},"homepage":"https://github.com/ya-nsh/time-machine-sdk#readme","bugs":{"url":"https://github.com/ya-nsh/time-machine-sdk/issues"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","sideEffects":false,"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./adapters":{"types":"./dist/adapters/index.d.ts","import":"./dist/adapters/index.mjs","require":"./dist/adapters/index.js"},"./utils":{"types":"./dist/utils/index.d.ts","import":"./dist/utils/index.mjs","require":"./dist/utils/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"eslint src/","test":"vitest run","test:watch":"vitest"},"dependencies":{},"peerDependencies":{"@langchain/core":">=0.2.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true}},"devDependencies":{"@langchain/core":"^0.3.0","@langchain/openai":"^0.3.0","@timemachine/shared":"workspace:*","@types/node":"^20.11.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^1.2.0"},"keywords":["ai","agents","observability","debugging","langchain","crewai","llm","tracing","ai-agents","monitoring","replay","fork"],"publishConfig":{"access":"public"},"_id":"@timemachine-sdk/sdk@0.1.1","gitHead":"5188e4054e6d82bc1077e2b0798ad69e699f334d","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-re4WjZMduQM4fqen6batfg5Pnebb56kIlTfaPyXmkx0Xf6SNXdPni70Z7gqQawe2sT2GKlV3rF3M4CJDDDcr8g==","shasum":"1022b6fea39bf62fb446e83d7b6b6b911e8378dc","tarball":"https://registry.npmjs.org/@timemachine-sdk/sdk/-/sdk-0.1.1.tgz","fileCount":24,"unpackedSize":108710,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCkzuljJKpbpRdjP/CX3oLVuHyqFec+0GzA32/DIhvhggIgGqFeRay1RSUqSfVEVFJJBP6j3DGrzBo1xWlILk9oFUI="}]},"_npmUser":{"name":"deva00","email":"yansh2017@gmail.com"},"directories":{},"maintainers":[{"name":"deva00","email":"yansh2017@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1772389048000_0.8266556669018437"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-23T15:18:43.424Z","modified":"2026-03-01T18:17:28.292Z","0.1.0":"2026-02-23T15:18:43.654Z","0.1.1":"2026-03-01T18:17:28.172Z"},"bugs":{"url":"https://github.com/ya-nsh/time-machine-sdk/issues"},"author":{"name":"Time Machine","email":"hello@timemachine.dev"},"license":"MIT","homepage":"https://github.com/ya-nsh/time-machine-sdk#readme","keywords":["ai","agents","observability","debugging","langchain","crewai","llm","tracing","ai-agents","monitoring","replay","fork"],"repository":{"type":"git","url":"git+https://github.com/ya-nsh/time-machine-sdk.git","directory":"packages/sdk-ts"},"description":"Time Machine SDK for AI Agent Observability — capture, debug, and replay AI agent executions","maintainers":[{"name":"deva00","email":"yansh2017@gmail.com"}],"readme":"<p align=\"center\">\n  <h1 align=\"center\">@timemachine-sdk/sdk</h1>\n  <p align=\"center\">Observability and debugging SDK for AI agents. Capture every step, fork from any point, replay with changes.</p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@timemachine-sdk/sdk\"><img src=\"https://img.shields.io/npm/v/@timemachine-sdk/sdk.svg\" alt=\"npm version\"></a>\n  <a href=\"https://github.com/ya-nsh/time-machine-sdk/blob/main/packages/sdk-ts/LICENSE\"><img src=\"https://img.shields.io/npm/l/@timemachine-sdk/sdk.svg\" alt=\"license\"></a>\n  <a href=\"https://www.npmjs.com/package/@timemachine-sdk/sdk\"><img src=\"https://img.shields.io/npm/dm/@timemachine-sdk/sdk.svg\" alt=\"downloads\"></a>\n  <a href=\"https://github.com/ya-nsh/time-machine-sdk\"><img src=\"https://img.shields.io/github/stars/ya-nsh/time-machine-sdk?style=social\" alt=\"GitHub stars\"></a>\n</p>\n\n---\n\n## Why Time Machine?\n\nAI agents are hard to debug. When a 15-step agent workflow fails at step 12, you don't want to re-run the entire thing. Time Machine captures every execution step — LLM calls, tool invocations, decisions — so you can **inspect what happened**, **fork from any step**, and **replay with modifications**.\n\n- **3 lines to integrate** — drop-in for any TypeScript agent\n- **Zero-overhead in production** — fail-open design, async batching, never crashes your app\n- **LangChain native** — automatic capture via callback handler, zero manual instrumentation\n\n## Install\n\n```bash\nnpm install @timemachine-sdk/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { TimeMachine } from '@timemachine-sdk/sdk';\n\nconst tm = new TimeMachine({ apiKey: 'tm_...' });\nconst execution = await tm.startExecution({ name: 'my-agent-run' });\n\n// Record an LLM call\nconst step = execution.step('llm_call', { model: 'gpt-4o', prompt: 'Analyze this data...' });\nconst result = await yourLLMCall();\nawait step.complete({ output: { text: result }, tokensIn: 150, tokensOut: 300 });\n\n// Record a tool use\nconst toolStep = execution.step('tool_use', { tool: 'web_search', query: 'latest news' });\nconst searchResults = await webSearch('latest news');\nawait toolStep.complete({ output: { results: searchResults } });\n\nawait execution.complete();\n// View at https://app.timemachine.dev\n```\n\n## LangChain Integration\n\nAutomatically capture every LLM call, tool invocation, and agent decision — zero manual instrumentation.\n\n```typescript\nimport { TimeMachine } from '@timemachine-sdk/sdk';\nimport { createLangChainHandler } from '@timemachine-sdk/sdk/adapters';\nimport { ChatOpenAI } from '@langchain/openai';\nimport { AgentExecutor } from 'langchain/agents';\n\nconst tm = new TimeMachine({ apiKey: 'tm_...' });\n\n// One-liner: creates execution + callback handler together\nconst { handler, execution } = await createLangChainHandler(tm, {\n  name: 'research-agent',\n  metadata: { model: 'gpt-4o' },\n});\n\nconst agent = new AgentExecutor({ /* your agent config */ });\n\n// Pass the handler — everything is captured automatically\nawait agent.invoke(\n  { input: 'Research the latest AI papers' },\n  { callbacks: [handler] }\n);\n\nawait execution.complete();\n```\n\n**What gets captured automatically:**\n- LLM calls with token counts, costs, and model info\n- Tool invocations with inputs and outputs\n- Agent decisions and reasoning\n- Retriever queries and returned documents\n- Errors at any step\n\n## Generic Wrapper\n\nWrap any agent framework with manual step recording:\n\n```typescript\nimport { TimeMachine } from '@timemachine-sdk/sdk';\n\nconst tm = new TimeMachine({ apiKey: 'tm_...' });\n\nasync function runAgent(query: string) {\n  const execution = await tm.startExecution({\n    name: 'custom-agent',\n    metadata: { query },\n  });\n\n  try {\n    // Record each step of your agent loop\n    const planStep = execution.step('decision', { action: 'plan' });\n    const plan = await generatePlan(query);\n    await planStep.complete({ output: { plan } });\n\n    for (const task of plan.tasks) {\n      const taskStep = execution.step('tool_use', { tool: task.tool, args: task.args });\n      const result = await executeTool(task);\n      await taskStep.complete({\n        output: { result },\n        tokensIn: result.usage?.input,\n        tokensOut: result.usage?.output,\n      });\n    }\n\n    await execution.complete();\n  } catch (error) {\n    await execution.fail(error as Error);\n  }\n}\n```\n\n## Configuration\n\n### `TimeMachine` constructor options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `apiKey` | `string` | **(required)** | Your project API key (`tm_...`). Get one at [app.timemachine.dev](https://app.timemachine.dev). |\n| `baseUrl` | `string` | `https://api.timemachine.dev` | API endpoint. Override for self-hosted or local development. |\n| `maxRetries` | `number` | `3` | Max retry attempts for failed API calls. Uses exponential backoff. |\n| `debug` | `boolean` | `false` | Log SDK activity to console. Useful for development. |\n\n### `startExecution` options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `name` | `string` | Human-readable name for this execution run. |\n| `metadata` | `Record<string, unknown>` | Arbitrary metadata (model, version, environment, etc.). |\n\n### Step types\n\n| Type | Description |\n|------|-------------|\n| `llm_call` | LLM/chat model invocation |\n| `tool_use` | Tool or function call |\n| `decision` | Agent routing or planning decision |\n| `retrieval` | RAG or document retrieval |\n| `human_input` | Human-in-the-loop input |\n| `transform` | Data transformation step |\n| `custom` | Anything else |\n\n## Sub-path Exports\n\nImport only what you need to keep your bundle small:\n\n```typescript\n// Core SDK\nimport { TimeMachine, Execution, StepRecorder } from '@timemachine-sdk/sdk';\n\n// LangChain adapter (only loads if @langchain/core is installed)\nimport { TimeMachineCallbackHandler, createLangChainHandler } from '@timemachine-sdk/sdk/adapters';\n\n// Utility functions (cost calculation, token extraction)\nimport { calculateCost, MODEL_PRICING } from '@timemachine-sdk/sdk/utils';\n```\n\n## Cost Tracking\n\nThe SDK includes a built-in pricing table for 30+ models (OpenAI, Anthropic, Google, Mistral, Cohere) and automatically calculates costs from token usage.\n\n```typescript\nimport { calculateCost, hasModelPricing } from '@timemachine-sdk/sdk/utils';\n\n// Check if a model has known pricing\nhasModelPricing('gpt-4o'); // true\n\n// Calculate cost\ncalculateCost('gpt-4o', 1000, 500); // $0.00625\n```\n\n## Fail-Open Design\n\nThe SDK is designed to **never crash your application**. All API calls are wrapped with error handling — if Time Machine's API is down or your key is invalid, your agent keeps running. Errors are silently logged when `debug: true` is set.\n\n## Dashboard\n\nView and debug your executions at [app.timemachine.dev](https://app.timemachine.dev):\n\n- **Execution timeline** — step-by-step view of every agent run\n- **Fork & replay** — branch from any step and re-run with modifications\n- **Visual diffs** — compare original vs. replayed executions side by side\n- **Cost analytics** — track token usage and costs across runs\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/ya-nsh/time-machine-sdk/blob/main/CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}