{"_id":"@ahzan-agentforge/core","_rev":"4-421148ab292e421a738c12556acd5b47","name":"@ahzan-agentforge/core","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@ahzan-agentforge/core","version":"0.1.0","keywords":["ai","agent","framework","llm","anthropic","openai"],"license":"MIT","_id":"@ahzan-agentforge/core@0.1.0","maintainers":[{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"}],"homepage":"https://github.com/ahzan-agentforge/AgentForge#readme","bugs":{"url":"https://github.com/ahzan-agentforge/AgentForge/issues"},"bin":{"agentforge":"dist/cli/index.js"},"dist":{"shasum":"df0db0ab0330a961ed3c620ee1bc53e86907bb32","tarball":"https://registry.npmjs.org/@ahzan-agentforge/core/-/core-0.1.0.tgz","fileCount":4,"integrity":"sha512-oiPIkxvjX0yrQxun1MsI6O+axhvIk4FLIV+gMDT8mCGVPCEuOSrn4OBD/43+3txz2RmHweJD85n+v2Vl3dJRZQ==","signatures":[{"sig":"MEUCIQDbw2EJOcbKC6ScmXDgd4FAdg6NelFzqtieeSyeBhVUswIgAskOF4K6CU3EaV3cwkJYo9fmE7FGp0vFNLTkJY7bdIg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1109773},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2e6dede0f2bc760f6e8b5b1145f7d54e1a01a28e","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","test:e2e":"vitest run tests/e2e","test:unit":"vitest run --exclude tests/e2e","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"},"repository":{"url":"git+https://github.com/ahzan-agentforge/AgentForge.git","type":"git"},"_npmVersion":"10.9.3","description":"Production-grade AI agent framework — the Next.js for AI agents","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.23.0","nanoid":"^5.0.0","openai":"^4.73.0","ioredis":"^5.4.0","commander":"^12.1.0","@anthropic-ai/sdk":"^0.39.0","zod-to-json-schema":"^3.23.0","@google/generative-ai":"^0.21.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.0_1773393877478_0.271178022475399","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ahzan-agentforge/core","version":"0.1.1","keywords":["ai","agent","framework","llm","anthropic","openai"],"license":"MIT","_id":"@ahzan-agentforge/core@0.1.1","maintainers":[{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"}],"homepage":"https://github.com/ahzan-dev/ahzan-agentforge#readme","bugs":{"url":"https://github.com/ahzan-dev/ahzan-agentforge/issues"},"bin":{"agentforge":"dist/cli/index.js"},"dist":{"shasum":"fcd929b57daeaa5ce6bf7c6840c3364d2ef9c524","tarball":"https://registry.npmjs.org/@ahzan-agentforge/core/-/core-0.1.1.tgz","fileCount":5,"integrity":"sha512-71PNdiPd/np4tzIvw78VwCnXGh2UQBrgjQ9+tQwTTocdJZ23SmjekOisCBnQv8yibvBYpE0oPk3PhR7VUKgRrQ==","signatures":[{"sig":"MEUCIAPz8SWa61lxytJBtP6XEb9eTsgBwxcORRuTv0hgO+6aAiEAlvjg3rvM23uSYPC4uDq3MKT9oyfUn1LUzrFBN0XM224=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1117226},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a7f0ee1cb1885dff8daa3a21053c4e4c42e76de0","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","test:e2e":"vitest run tests/e2e","test:unit":"vitest run --exclude tests/e2e","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"},"repository":{"url":"git+https://github.com/ahzan-dev/ahzan-agentforge.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.3","description":"Production-grade AI agent framework — the Next.js for AI agents","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.23.0","nanoid":"^5.0.0","openai":"^4.73.0","ioredis":"^5.4.0","commander":"^12.1.0","@anthropic-ai/sdk":"^0.39.0","zod-to-json-schema":"^3.23.0","@google/generative-ai":"^0.21.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.1_1773397172026_0.7766483763050207","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@ahzan-agentforge/core","version":"0.1.2","keywords":["ai","agent","framework","llm","anthropic","openai"],"license":"MIT","_id":"@ahzan-agentforge/core@0.1.2","maintainers":[{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"}],"homepage":"https://docs.agentforge.trynewways.com","bin":{"agentforge":"dist/cli/index.js"},"dist":{"shasum":"41da8f53d566ef743f7fee219d7599f5ac7ec0c4","tarball":"https://registry.npmjs.org/@ahzan-agentforge/core/-/core-0.1.2.tgz","fileCount":5,"integrity":"sha512-trK/G+j9QbTsPI0d0HUJ/pmEVyoB+li2tEl6LrSnv0kUn9lMWITdonfHHMs8qpZQxn/QY6kAjXwkST/m1AOXNg==","signatures":[{"sig":"MEUCIC6xEd1KUV7Zx9wUETT79DAcaLS+WHOPexsEEnhtC6oqAiEAnuqDw+yBMrvj1p/YDXN0GppN5tIqCocE8iDxgotEoNg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1116994},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"8465e76aba402c98b732bc7525c5447f8abefa50","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","test:e2e":"vitest run tests/e2e","test:unit":"vitest run --exclude tests/e2e","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"},"_npmVersion":"10.9.3","description":"Production-grade AI agent framework — the Next.js for AI agents","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.23.0","nanoid":"^5.0.0","openai":"^4.73.0","ioredis":"^5.4.0","commander":"^12.1.0","@anthropic-ai/sdk":"^0.39.0","zod-to-json-schema":"^3.23.0","@google/generative-ai":"^0.21.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.2_1773403251125_0.9763380264788943","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@ahzan-agentforge/core","version":"0.1.3","description":"Production-grade AI agent framework — the Next.js for AI agents","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"homepage":"https://docs.agentforge.trynewways.com","bin":{"agentforge":"dist/cli/index.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:unit":"vitest run --exclude tests/e2e","test:e2e":"vitest run tests/e2e","test:watch":"vitest","lint":"tsc --noEmit","typecheck":"tsc --noEmit"},"dependencies":{"@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.21.0","commander":"^12.1.0","ioredis":"^5.4.0","nanoid":"^5.0.0","openai":"^4.73.0","zod":"^3.23.0","zod-to-json-schema":"^3.23.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.7.0","vitest":"^3.0.0"},"keywords":["ai","agent","framework","llm","anthropic","openai"],"license":"MIT","_id":"@ahzan-agentforge/core@0.1.3","gitHead":"8465e76aba402c98b732bc7525c5447f8abefa50","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-+faqlS9yp+j96VTdGkSDOAKwVYC42op+8VaavkMgSRn11tVQGK/lm7OdyPK2YAK7/iC4K766Bh9a++PLIf8RFQ==","shasum":"68a9feb516ebce1626b6f1478477c1406a393565","tarball":"https://registry.npmjs.org/@ahzan-agentforge/core/-/core-0.1.3.tgz","fileCount":5,"unpackedSize":1116994,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDGzlBehSjqtuAmunUTs4gnvftZ1bndrPxgcojA5DFIXAIgatU6cDA6nLb4cnDQUYu88ySIdnusdjwZdrBmZJyNTmY="}]},"_npmUser":{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"},"directories":{},"maintainers":[{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.1.3_1773403434375_0.3026543704705733"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-13T09:24:37.365Z","modified":"2026-03-13T12:03:54.661Z","0.1.0":"2026-03-13T09:24:37.674Z","0.1.1":"2026-03-13T10:19:32.181Z","0.1.2":"2026-03-13T12:00:51.291Z","0.1.3":"2026-03-13T12:03:54.519Z"},"license":"MIT","homepage":"https://docs.agentforge.trynewways.com","keywords":["ai","agent","framework","llm","anthropic","openai"],"description":"Production-grade AI agent framework — the Next.js for AI agents","maintainers":[{"name":"farhan_ahzan","email":"mf.farhanahzan@gmail.com"}],"readme":"# @ahzan-agentforge/core\n\nProduction-grade AI agent framework. Define business logic. The framework handles execution, memory, observability, and reliability.\n\nAgentForge owns the agent loop — LLM calls, tool execution, state checkpointing, crash recovery, cost governance, rollback, and full run tracing. You write tools and prompts. Everything else is handled.\n\n[![npm](https://img.shields.io/npm/v/@ahzan-agentforge/core)](https://www.npmjs.com/package/@ahzan-agentforge/core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ahzan-dev/ahzan-agentforge/blob/main/LICENSE)\n\n## Quick Start\n\n```bash\nnpm install @ahzan-agentforge/core zod\n```\n\n```typescript\nimport { defineAgent, defineTool, createLLM } from '@ahzan-agentforge/core'\nimport { z } from 'zod'\n\nconst getOrder = defineTool({\n  name: 'get_order',\n  description: 'Fetch order details by ID',\n  input: z.object({ orderId: z.string() }),\n  output: z.object({ id: z.string(), status: z.string(), total: z.number() }),\n  execute: async ({ orderId }) => {\n    return { id: orderId, status: 'shipped', total: 49.99 }\n  },\n})\n\nconst agent = defineAgent({\n  name: 'support-agent',\n  description: 'Customer support agent',\n  tools: [getOrder],\n  llm: createLLM({ provider: 'openai', model: 'gpt-4o', maxTokens: 4096 }),\n  maxSteps: 15,\n  systemPrompt: 'You are a customer support agent. Look up orders and help customers.',\n})\n\nconst result = await agent.run({ task: 'Order #4521 arrived damaged' })\nconsole.log(result.output) // \"I've looked up order #4521...\"\n```\n\n## Why AgentForge\n\n- **Own the loop, not the LLM.** The LLM is a swappable dependency. The framework controls execution, retries, checkpointing, and tracing around every decision.\n- **State is sacred.** Every step is checkpointed. Kill the process at any point — resume from the last checkpoint with zero data loss.\n- **Observability is not optional.** Every LLM call, tool execution, token count, and timing is recorded via OpenTelemetry.\n- **Framework errors != model errors.** When something breaks, you know whether it's your code, the LLM, or a tool.\n\n## Features\n\n### LLM Providers\n\n```typescript\ncreateLLM({ provider: 'anthropic', model: 'claude-sonnet-4-20250514' })\ncreateLLM({ provider: 'openai', model: 'gpt-4o' })\ncreateLLM({ provider: 'gemini', model: 'gemini-2.0-flash' })\ncreateLLM({ provider: 'ollama', model: 'llama3.1' })  // local, zero cost\n```\n\nAll providers support token-level streaming via `agent.stream()`.\n\n### Tool System\n\n- Zod schema validation on input AND output\n- Configurable retry with exponential/linear/fixed backoff\n- Per-tool timeout enforcement\n- Result caching for idempotent tools\n- Compensating actions for rollback support\n\n### Streaming\n\n```typescript\nfor await (const event of agent.stream({ task: 'Help customer' })) {\n  if (event.type === 'llm_token') process.stdout.write(event.content)\n  if (event.type === 'tool_start') console.log(`Calling ${event.toolName}...`)\n  if (event.type === 'done') console.log(`\\nResult: ${event.result.output}`)\n}\n```\n\n### State & Recovery\n\n- **InMemoryStateStore** — for development and testing\n- **RedisStateStore** — production checkpointing with ioredis\n- Resume any run from its last checkpoint via `runId`\n\n### Memory\n\n- **InMemoryMemoryStore** — development and testing\n- **PgVectorMemoryStore** — production long-term memory with embedding-based retrieval\n- Auto-capture of run outcomes, errors, and tool results\n- Memory consolidation to manage growth\n\n### Cost Governor & Autonomy Policy\n\n- Per-run token and cost budget limits with built-in model pricing\n- Per-tool allow/deny/escalate rules\n- Escalation thresholds on cost and step count\n- Rate limiting per tool\n\n### Multi-Agent Coordination\n\n```typescript\nimport { pipeline, parallel, supervisor, debate } from '@ahzan-agentforge/core'\n\nconst result = await pipeline([researcher, writer, editor], { task: 'Write a report' })\nconst result = await supervisor(manager, { researcher, writer }, { task: 'Complete project' })\nconst result = await parallel([agent1, agent2], { task: 'Analyze data' }, mergeResults)\nconst result = await debate([optimist, pessimist], { task: 'Evaluate proposal' }, judge)\n```\n\n### Observability\n\n- OpenTelemetry spans for runs, LLM calls, and tool executions\n- Metrics: run duration, token usage, tool call counts, error rates, estimated cost\n- Export to any OTLP-compatible backend (Jaeger, Grafana, Datadog)\n\n### Testing\n\n```typescript\nimport { createMockLLM, createTestHarness } from '@ahzan-agentforge/core'\n\nconst harness = createTestHarness({\n  agent: myAgentConfig,\n  llm: createMockLLM({\n    responses: [\n      { toolCalls: [{ name: 'get_order', input: { orderId: '4521' } }] },\n      { text: 'Order found and ticket created.' },\n    ],\n  }),\n})\n\nconst result = await harness.run({ task: 'Handle order issue' })\nexpect(result.status).toBe('completed')\nexpect(result.toolCalls('get_order')).toHaveLength(1)\n```\n\n### Pre-built Integrations\n\nReady-to-use tool factories for common services:\n\n- **HTTP** — `createHttpGetTool()`, `createHttpPostTool()`\n- **Slack** — `createSlackTools()`\n- **GitHub** — `createGitHubTools()`\n- **Gmail** — `createGmailTools()`\n- **Stripe** — `createStripeTools()`\n- **Notion** — `createNotionTools()`\n- **Supabase** — `createSupabaseTools()`\n- **WooCommerce** — `createWooCommerceTools()`\n- **Database** — `createDatabaseTool()` (SQL queries)\n\n### Agent Templates\n\nPre-configured agents you can customize:\n\n```typescript\nimport { createCustomerSupportAgent, createResearchAssistant } from '@ahzan-agentforge/core'\n\nconst support = createCustomerSupportAgent({ llm, tools: [orderLookup] })\nconst researcher = createResearchAssistant({ llm, tools: [webSearch] })\n```\n\nAlso available: `createDataProcessor`, `createCodeReviewer`, `createWorkflowAutomator`\n\n### MCP (Model Context Protocol)\n\n```typescript\nimport { MCPClient, MCPServer, toMCPTool, fromMCPTool } from '@ahzan-agentforge/core'\n\n// Expose AgentForge tools as MCP tools\nconst server = new MCPServer({ tools: [getOrder], name: 'my-agent' })\n\n// Use external MCP tools in your agent\nconst client = new MCPClient({ serverUrl: 'http://localhost:3001' })\n```\n\n## CLI\n\n```bash\nnpx agentforge init my-agent               # scaffold a new project\nnpx agentforge run src/agent.ts --task \"…\"  # execute an agent\nnpx agentforge run src/agent.ts --mock      # run with mock LLM (no API cost)\nnpx agentforge trace <runId>                # inspect a past run\nnpx agentforge replay <runId> --diff        # re-execute and compare\nnpx agentforge dev --agent src/agent.ts     # dev server with hot reload\n```\n\n## Configuration\n\n```typescript\nimport { defineConfig } from '@ahzan-agentforge/core'\n\nexport default defineConfig({\n  defaultLLM: {\n    provider: 'anthropic',\n    model: 'claude-sonnet-4-20250514',\n    maxTokens: 4096,\n  },\n  state: {\n    provider: 'redis',\n    redis: { url: 'redis://localhost:6379', ttl: 604800 },\n  },\n  trace: {\n    outputDir: '.agentforge/traces',\n    retainDays: 30,\n  },\n})\n```\n\n## Requirements\n\n- Node.js >= 22\n- Redis (optional, for persistent state)\n- PostgreSQL + pgvector (optional, for long-term memory)\n\n## License\n\n[MIT](https://github.com/ahzan-dev/ahzan-agentforge/blob/main/LICENSE)\n","readmeFilename":"README.md"}