{"_id":"@aifluens/agent-kit","_rev":"2-7378b04e21b322b83d564b2988b80836","name":"@aifluens/agent-kit","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aifluens/agent-kit","version":"0.1.0","keywords":["agent","llm","langchain","anthropic","claude","openai","rag","mcp"],"license":"MIT","_id":"@aifluens/agent-kit@0.1.0","maintainers":[{"name":"hashmishariq","email":"hashmishariq@gmail.com"}],"bin":{"agent-kit-ingest":"dist/bin/ingest.js"},"dist":{"shasum":"dd4e971c6395e72be6f2e00de61731eb54a486c4","tarball":"https://registry.npmjs.org/@aifluens/agent-kit/-/agent-kit-0.1.0.tgz","fileCount":48,"integrity":"sha512-sLdFRVB/SjdpLy6w9vwp5qJg7XqUWsabg7IkzVxN//sBoQAFhptOI/1YQuWbP4HZGwjl8AEKRBO8dk82W5Fk2A==","signatures":[{"sig":"MEUCICQcvaem5j/1WopsGNnK9YCO/5XId3DBFjM2dh2lV+JIAiEAusMrj8TBc91pkyPkpIPf75lgdGtC30F1Kh5wvriM9i8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107251},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.11"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"955036a0dc790b3bc468a1a842f525b44afa5753","scripts":{"lint":"eslint src","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit -p tsconfig.json","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"hashmishariq","email":"hashmishariq@gmail.com"},"_npmVersion":"10.8.2","description":"Local copy-paste runtime for the AIFluensLab learning labs. Build and run an agent on your own machine with your own provider key.","directories":{},"_nodeVersion":"20.19.5","dependencies":{"@langchain/core":"^0.3.58","@langchain/anthropic":"0.3.34"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"pg":"^8.13.0","@types/pg":"^8.11.0","@types/node":"^20.16.0","@langchain/aws":"^0.1.15","@langchain/openai":"^0.3.17","@xenova/transformers":"^2.17.0","@langchain/google-genai":"^0.1.12","@langchain/google-vertexai":"^0.1.8"},"peerDependencies":{"pg":"^8.13.0","@langchain/aws":"^0.1.15","@langchain/openai":"^0.3.17","@xenova/transformers":"^2.17.0","@langchain/google-genai":"^0.1.12","@langchain/google-vertexai":"^0.1.8"},"peerDependenciesMeta":{"pg":{"optional":true},"@langchain/aws":{"optional":true},"@langchain/openai":{"optional":true},"@xenova/transformers":{"optional":true},"@langchain/google-genai":{"optional":true},"@langchain/google-vertexai":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/agent-kit_0.1.0_1782513148244_0.4988669225888722","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aifluens/agent-kit","version":"0.2.0","description":"Local copy-paste runtime for the AIFluensLab learning labs. Build and run an agent on your own machine with your own provider key.","license":"MIT","type":"module","publishConfig":{"access":"public"},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"agent-kit-ingest":"dist/bin/ingest.js"},"engines":{"node":">=20.11"},"scripts":{"lint":"eslint src","typecheck":"tsc --noEmit -p tsconfig.json","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","prepublishOnly":"npm run build && npm run test"},"keywords":["agent","llm","langchain","anthropic","claude","openai","rag","mcp"],"dependencies":{"@langchain/anthropic":"0.3.34","@langchain/core":"^0.3.58"},"peerDependencies":{"@langchain/aws":"^0.1.15","@langchain/google-genai":"^0.1.12","@langchain/google-vertexai":"^0.1.8","@langchain/openai":"^0.3.17","@xenova/transformers":"^2.17.0","pg":"^8.13.0"},"peerDependenciesMeta":{"@langchain/aws":{"optional":true},"@langchain/google-genai":{"optional":true},"@langchain/google-vertexai":{"optional":true},"@langchain/openai":{"optional":true},"@xenova/transformers":{"optional":true},"pg":{"optional":true}},"devDependencies":{"@langchain/aws":"^0.1.15","@langchain/google-genai":"^0.1.12","@langchain/google-vertexai":"^0.1.8","@langchain/openai":"^0.3.17","@types/node":"^20.16.0","@types/pg":"^8.11.0","@xenova/transformers":"^2.17.0","pg":"^8.13.0"},"_id":"@aifluens/agent-kit@0.2.0","gitHead":"6921cdbc4ac5cba38dad74d562f477a66fbd740d","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-/nEI05Jbth4K7Mfa+Ziw701zArJNqdFoTBi+RwqWKcI4OeG46yoHPOt+G43/I9UPRI90fB0/xg3vtEBJpUxFHA==","shasum":"64741930c2b4ba1a31262401740fa6c97cb89d03","tarball":"https://registry.npmjs.org/@aifluens/agent-kit/-/agent-kit-0.2.0.tgz","fileCount":48,"unpackedSize":107649,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA5bFdaxr8ODMpsHBWCU8WOS/PJEM9x8eOV6YeHvvn8LAiEA//iYM2S2WEItW9K49cqTbGyUHn+YA+Gf0yx6FHlkJIs="}]},"_npmUser":{"name":"hashmishariq","email":"hashmishariq@gmail.com"},"directories":{},"maintainers":[{"name":"hashmishariq","email":"hashmishariq@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-kit_0.2.0_1782706314825_0.6725777220122735"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T22:32:28.043Z","modified":"2026-06-29T04:11:55.119Z","0.1.0":"2026-06-26T22:32:28.400Z","0.2.0":"2026-06-29T04:11:54.963Z"},"license":"MIT","keywords":["agent","llm","langchain","anthropic","claude","openai","rag","mcp"],"description":"Local copy-paste runtime for the AIFluensLab learning labs. Build and run an agent on your own machine with your own provider key.","maintainers":[{"name":"hashmishariq","email":"hashmishariq@gmail.com"}],"readme":"# @aifluens/agent-kit\n\nThe local copy-paste runtime for the **AIFluensLab** learning labs. The lab code you see\nimports from `@aifluens/agent-kit`; this package makes those imports real so you can run the same\nsnippet on your own machine, with **your own provider key**.\n\n```ts\nimport { Agent } from \"@aifluens/agent-kit\";\n\nconst agent = new Agent({\n  model: \"claude-sonnet\",\n  systemPrompt: \"You are a friendly billing support rep.\",\n  temperature: 0.4,\n});\n\nconst response = await agent.run(\"Hi, can you help me?\");\nconsole.log(response);\n```\n\n```bash\nnpm install @aifluens/agent-kit @langchain/anthropic @langchain/core\nexport LLM_PROVIDER=\"anthropic\"          # which provider to use (required)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nnpx tsx agent.ts\n```\n\n> This is a learner-convenience runtime. The hosted platform runs a more featured version\n> (tracing, observability, retries, managed credentials); `agent-kit` keeps just what you need to\n> see your agent work locally.\n\n## Install matrix\n\n`agent-kit` keeps the base install tiny and loads extras only when a lab needs them:\n\n| You want to run… | Also install |\n| --- | --- |\n| Basic agents (M1, M2, M9) on Anthropic | `@langchain/anthropic @langchain/core` |\n| …on OpenAI | `@langchain/openai` |\n| …on Google Gemini | `@langchain/google-genai` |\n| …on Google Vertex AI | `@langchain/google-vertexai` |\n| …on AWS Bedrock | `@langchain/aws` |\n| Retrieval / RAG (M4) | `pg @xenova/transformers` |\n| MCP / connections (M5) | _(nothing extra — uses built-in `fetch`)_ |\n\n## Bring your own key (BYOK)\n\nYou pick the provider **explicitly** with the `LLM_PROVIDER` env var — it is read verbatim and is\n**never inferred** from the model string. Set `LLM_PROVIDER` to one of `anthropic`, `openai`,\n`google`, `bedrock`, `azure-openai`, `vertex`, then set that provider's **standard public env\nvar(s)**. The `model` you pass to `Agent` is just the model id.\n\n| `LLM_PROVIDER` | Example `model` | Env var(s) |\n| --- | --- | --- |\n| `anthropic` | `claude-sonnet` / `claude-opus-4-8` | `ANTHROPIC_API_KEY` |\n| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` |\n| `google` | `gemini-1.5-flash` | `GOOGLE_API_KEY` |\n| `bedrock` | `anthropic.claude-3-5-sonnet` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_SESSION_TOKEN?` |\n| `azure-openai` | `<deployment>` | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_VERSION?` |\n| `vertex` | `gemini-1.5-pro` | `GOOGLE_APPLICATION_CREDENTIALS`, `GCP_PROJECT`, `GCP_LOCATION?` |\n\n`LLM_PROVIDER` is required — if it is unset or not one of the values above, agent-kit throws a clear\nerror listing the valid values rather than guessing.\n\nFriendly Anthropic shortnames resolve automatically: `claude-sonnet` → `claude-sonnet-4-6`,\n`claude-opus` → `claude-opus-4-8`, `claude-haiku` → `claude-haiku-4-5-20251001`.\n\nSwitch providers by changing `LLM_PROVIDER` (and setting that provider's key) — nothing in the lab\ncode changes:\n\n```bash\nexport LLM_PROVIDER=\"openai\"\nexport OPENAI_API_KEY=\"sk-...\"\n```\n```ts\nconst agent = new Agent({ model: \"gpt-4o-mini\", systemPrompt: \"…\", temperature: 0.4 });\n```\n\n## Run M4 (retrieval) locally\n\nThe `Retriever` searches **your own** Postgres + pgvector database, using the same public\n`Xenova/all-MiniLM-L6-v2` (384-dim) embeddings the platform uses, so results are comparable.\n\n```bash\n# 1. A Postgres with pgvector (Docker is easy):\ndocker run -d -e POSTGRES_PASSWORD=pw -p 5432:5432 pgvector/pgvector:pg16\nexport DATABASE_URL=\"postgres://postgres:pw@localhost:5432/postgres\"\n\n# 2. Create the schema (ships with this package):\npsql \"$DATABASE_URL\" -f node_modules/@aifluens/agent-kit/schema.sql\n\n# 3. Load your documents (chunks + embeds them):\nnpm install pg @xenova/transformers\nnpx agent-kit-ingest ./docs/*.md --kb 1\n\n# 4. Run the M4 lab. `new Retriever()` searches kb 1 by default\n#    (override with AGENT_KIT_KB_ID or new Retriever({ kbId })).\nnpx tsx retriever.ts\n```\n\n`search(query, { topK, searchType })` supports `searchType: \"vector\" | \"keyword\" | \"hybrid\"`\n(hybrid fuses both legs with Reciprocal Rank Fusion). The first embed downloads the model\n(~30 MB) once and caches it.\n\n## Run M5 (MCP / connections) locally\n\nPoint `MCPClient` / `callConnectionHttp` at **your own** MCP or HTTP server via\n`AGENT_KIT_CONNECTIONS` — a JSON map of `provider → { kind, url, token? }`:\n\n```bash\nexport AGENT_KIT_CONNECTIONS='{\n  \"helpdesk-sandbox\": { \"kind\": \"mcp\",  \"url\": \"http://localhost:8000/mcp\" },\n  \"helpdesk-http\":    { \"kind\": \"http\", \"url\": \"http://localhost:8001\", \"token\": \"secret\" }\n}'\nnpx tsx agent-mcp.ts\n```\n\n- `MCPClient.connect(provider)` speaks **MCP Streamable HTTP**: it runs the `initialize` →\n  `tools/list` handshake and returns the discovered tools ready to spread into `new Agent({ tools })`.\n- `callConnectionHttp(provider, { method, path, query?, body? })` makes a plain HTTP request to the\n  configured base URL (with `Authorization: Bearer <token>` if you set one).\n\nYou supply the server. Any MCP server that speaks Streamable HTTP, or any HTTP API, works.\n\n## API\n\n| Export | What it is |\n| --- | --- |\n| `Agent` | `new Agent(options).run(input)` — the agent loop. `input` is a string or `{ role, content }[]`. |\n| `tool` | `tool({ name, description, parameters, handler })` — define a tool (`parameters` is JSON Schema). |\n| `Guardrail` | `new Guardrail(name, { position, scope? })` — illustrative input/output guardrails. |\n| `Retriever` | `new Retriever().search(query, { topK, searchType })` — local pgvector search (M4). |\n| `MCPClient` | `MCPClient.connect(provider)` — MCP tool discovery against your server (M5). |\n| `callConnectionHttp` | raw HTTP to a configured connection (M5). |\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}