@easynet/agent-llm 1.0.10 → 1.0.12

package/README.md

@@ -1,42 +1,64 @@
 # @easynet/agent-llm
 
-Load an LLM from **llm.yaml** (or your config) and use it from the command line or in a LangChain agent. Supports OpenAI and OpenAI-compatible endpoints (Ollama, Groq, Azure, etc.).
+Load an LLM from **llm.yaml** for CLI or LangChain. Releases are automated via semantic-release on push to `master`.
 
-## Command line
+**Extensible:** define your own extension (implement `ILLMExtension`).
 
-Install and run with a question:
+---
+
+## Quick start
+
+**1.** Add `llm.yaml` in your project root:
+
+```yaml
+llm:
+  default: small
+  strong:
+    provider: npm:@scope/package-name@latest#provider-name
+    base_url: https://your-api.example.com
+    model: your-model
+  small:
+    provider: openai
+    base_url: http://localhost:11434/v1
+    model: qwen3:0.6b
+```
+
+**2.** Run:
 
 ```bash
-npx @easynet/agent-llm "hi"
-npx @easynet/agent-llm "What is 10 + 20?"
+npx @easynet/agent-llm "your prompt"
 ```
 
-Config is read from **llm.yaml** in the current directory. See [config/llm.yaml.example](config/llm.yaml.example). Placeholders like `${OPENAI_API_KEY}` are replaced from the environment.
+---
 
-## Use in a LangChain agent
+## LangChain agent
 
-**1.** Get the LLM from config with `createAgentLlM()` (async; resolves npm: providers):
+1. **Get the LLM** (async; resolves `npm:` providers and installs packages if needed):
 
 ```ts
 import { createAgentLlM } from "@easynet/agent-llm";
-import { createAgent, tool } from "langchain";
-import { z } from "zod";
 
 const llm = await createAgentLlM();
 ```
 
-**2.** Create your agent with LangChain’s `createAgent` and your tools:
+2. **Build the agent** with LangChain's `createAgent` and tools:
 
 ```ts
+import { createAgent, tool } from "langchain";
+import { z } from "zod";
+
 const add = tool(
   (input: { a: number; b: number }) => String(input.a + input.b),
   { name: "add", description: "Add two numbers.", schema: z.object({ a: z.number(), b: z.number() }) }
 );
 
-const agent = createAgent({ model: llm as unknown as Parameters<typeof createAgent>[0]["model"], tools: [add] });
+const agent = createAgent({
+  model: llm as unknown as Parameters<typeof createAgent>[0]["model"],
+  tools: [add],
+});
 ```
 
-**3.** Invoke with messages:
+3. **Invoke** with messages:
 
 ```ts
 import { HumanMessage } from "@langchain/core/messages";
@@ -45,59 +67,25 @@ const result = await agent.invoke({ messages: [new HumanMessage("What is 10 + 20
 console.log(result.messages?.slice(-1)[0]?.content);
 ```
 
-Full example: [examples/langchain-react-agent.ts](examples/langchain-react-agent.ts).
-
-## Config
+Full runnable example: [examples/langchain-react-agent.ts](examples/langchain-react-agent.ts).
 
-Put **llm.yaml** in your project (current directory). Example:
-
-```yaml
-provider: openai
-model: gpt-4o-mini
-temperature: 0
-apiKey: ${OPENAI_API_KEY}
-# baseURL: https://api.openai.com/v1  # or Ollama, Groq, etc.
-```
+---
 
-Optional: pass a path — `createAgentLlM("path/to/llm.yaml")` or `createAgentLlM({ configPath: "/path/to/llm.yaml" })`.
+## npm provider protocol
 
-## npm: protocol in provider (install on demand)
+Use a provider from an **npm package**. If the package is missing, the framework can install it and then load the provider.
 
-You can set the provider by **npm package name** (and optional version) in config. If the package is not installed, the framework will **install it** and then use it as the provider.
+Example in a named entry:
 
-**Recommended format:** `npm:<package>@<version>#<provider>` — e.g. **`provider: "npm:wallee-llm@0.1.0#cis"`**.
-
-- **`provider: "npm:wallee-llm@0.1.0#cis"`** – **(recommended)** install `wallee-llm@0.1.0` if missing, then use provider `cis`.
-- **`provider: "npm:wallee-llm@0.1.0"`** – use a specific version; default provider is used.
-- **`provider: "npm:wallee-llm#cis"`** – load wallee-llm and use the provider named `cis`.
-- **`provider: "npm:wallee-llm"`** – load wallee-llm and use its default provider (e.g. `cis`).
-
-**createAgentLlM()** resolves npm: providers (and optionally installs packages) when reading config. For a raw llm section use **createChatModelFromLlmConfigWithNpm**:
-
-```ts
-import { createChatModelFromLlmConfigWithNpm, createAgentLlM } from "@easynet/agent-llm";
-
-// From a raw llm section (e.g. from loadLlmConfig)
-const model = await createChatModelFromLlmConfigWithNpm({ llmSection });
-
-// From llm.yaml in the current directory
-const llm = await createAgentLlM();
-// Or with a path: createAgentLlM("path/to/llm.yaml")
+```yaml
+strong:
+  provider: "npm:@scope/package-name@latest#provider-name"
+  base_url: https://your-api.example.com
+  model: your-model
 ```
 
-Options: **installNpmIfMissing** (default `true`) and **cwd** (default `process.cwd()` for npm install). Exports: `parseNpmProviderSpec`, `ensureNpmPackageInstalled`, `resolveNpmProvider`, `resolveLlmSectionWithNpm`, `isNpmProviderSpec`, `createChatModelFromLlmConfigWithNpm`, `createAgentLlM`.
-
-## Using with Workday Artifactory
+---
 
-If **@easynet/agent-llm** is installed from Artifactory but your default registry is **npm-sandbox**, npm may 404 when resolving dependencies (@langchain/core, axios, openai, etc.). Use an **.npmrc** so the default registry is public npm and only **@easynet** comes from Artifactory:
-
-```ini
-registry=https://registry.npmjs.org/
-@easynet:registry=https://artifactory.workday.com/artifactory/api/npm/npm-virtual/
-```
+## License
 
-Copy from [.npmrc.example](.npmrc.example) into your project (e.g. `/tmp/test`) or home `~/.npmrc`, then run:
-
-```bash
-npx @easynet/agent-llm hi
-```
+MIT · [GitHub](https://github.com/easynet-world/agent-llm)

package/dist/{createAgentLlM.d.ts → api/create-agent-llm.d.ts}

@@ -1,4 +1,4 @@
-import { createChatModelFromLlmConfig } from "./llmAdapter.js";
+import { createChatModelFromLlmConfig } from "../langchain/adapter.js";
 export interface CreateAgentLlMOptions {
     /** Path to YAML config file. If omitted, uses llm.yaml in the current directory (cwd). */
     configPath?: string;
@@ -12,4 +12,4 @@ export interface CreateAgentLlMOptions {
  * - createAgentLlM({ configPath: "...", installNpmIfMissing: true }) — options object
  */
 export declare function createAgentLlM(configPathOrOptions?: string | CreateAgentLlMOptions): Promise<ReturnType<typeof createChatModelFromLlmConfig>>;
-//# sourceMappingURL=createAgentLlM.d.ts.map
+//# sourceMappingURL=create-agent-llm.d.ts.map

package/dist/api/create-agent-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-agent-llm.d.ts","sourceRoot":"","sources":["../../src/api/create-agent-llm.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAIvE,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAgDD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,mBAAmB,CAAC,EAAE,MAAM,GAAG,qBAAqB,GACnD,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAiB1D"}

package/dist/{chunk-L3K6IEC6.js → chunk-VR7BRFGB.js}

@@ -1,4 +1,4 @@
-// src/config.ts
+// src/config/parser.ts
 var DEFAULT_LLM_ID = "default";
 var RESERVED_KEYS = /* @__PURE__ */ new Set([
   "default",
@@ -108,81 +108,48 @@ function normalizeLlmConfig(o) {
   return config;
 }
 
-// src/chatModelRegistry.ts
-var CHAT_MODEL_FACTORIES = /* @__PURE__ */ new Map();
-function registerChatModelProvider(providerName, factory) {
-  CHAT_MODEL_FACTORIES.set(providerName.toLowerCase(), factory);
-}
-function getChatModelFactory(providerName) {
-  return CHAT_MODEL_FACTORIES.get(providerName.toLowerCase());
+// src/config/loader.ts
+import { readFileSync, existsSync } from "fs";
+import { parse as parseYaml } from "yaml";
+function substituteEnv(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj === "string") {
+    const m = obj.match(/^\$\{(\w+)\}$/);
+    return m ? process.env[m[1]] ?? obj : obj;
+  }
+  if (Array.isArray(obj)) return obj.map(substituteEnv);
+  if (typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = substituteEnv(v);
+    return out;
+  }
+  return obj;
 }
-
-// src/llmAdapter.ts
-import { ChatOpenAI } from "@langchain/openai";
-var DEFAULT_MODEL = "gpt-4o-mini";
-function normalizeAgentLlMError(e, context) {
-  if (e instanceof Error) return new Error(`${context}: ${e.message}`, { cause: e });
-  return new Error(`${context}: ${String(e)}`);
+function parseLlmYaml(content, options = {}) {
+  const { substituteEnv: doSub = true } = options;
+  const parsed = parseYaml(content);
+  const llm = parsed?.llm;
+  if (llm == null) return void 0;
+  return doSub ? substituteEnv(llm) : llm;
 }
-function createChatModelFromLlmConfig(options) {
-  const { llmSection, modelEnv, apiKeyEnv } = options;
-  let defaultId;
-  let configs;
+function loadLlmConfig(filePath, options = {}) {
+  if (typeof filePath !== "string" || filePath.trim().length === 0) {
+    throw new Error("agent-llm: loadLlmConfig requires a non-empty file path");
+  }
+  if (!existsSync(filePath)) return null;
+  let raw;
   try {
-    const parsed = parseLlmSection(llmSection ?? null);
-    defaultId = parsed.defaultId;
-    configs = parsed.configs;
+    raw = readFileSync(filePath, "utf8");
   } catch (e) {
-    throw normalizeAgentLlMError(e, "agent-llm: failed to parse llm section");
-  }
-  const defaultConfig = configs.find((c) => c.id === defaultId) ?? configs[0];
-  if (!defaultConfig) {
-    const model2 = modelEnv ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
-    const apiKey2 = apiKeyEnv ?? process.env.OPENAI_API_KEY;
-    try {
-      return new ChatOpenAI({
-        model: model2,
-        temperature: 0,
-        ...apiKey2 ? { apiKey: apiKey2 } : {}
-      });
-    } catch (e) {
-      throw normalizeAgentLlMError(e, "agent-llm: failed to create default ChatOpenAI");
-    }
-  }
-  const provider = defaultConfig.provider ?? "openai";
-  const chatModelFactory = getChatModelFactory(provider);
-  if (chatModelFactory) {
-    const config = {
-      ...defaultConfig,
-      model: modelEnv ?? defaultConfig.model,
-      temperature: typeof defaultConfig.temperature === "number" ? defaultConfig.temperature : 0
-    };
-    try {
-      return chatModelFactory(config);
-    } catch (e) {
-      throw normalizeAgentLlMError(e, `agent-llm: failed to create ChatModel for provider "${provider}"`);
-    }
-  }
-  const model = modelEnv ?? defaultConfig?.model ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
-  let apiKey = apiKeyEnv ?? defaultConfig?.apiKey ?? process.env.OPENAI_API_KEY;
-  let baseURL = defaultConfig?.baseURL;
-  if (baseURL && !baseURL.replace(/\/$/, "").endsWith("/v1")) {
-    baseURL = baseURL.replace(/\/$/, "") + "/v1";
-  }
-  if (baseURL && apiKey === void 0) {
-    apiKey = "ollama";
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`agent-llm: failed to read config file ${filePath}: ${msg}`, { cause: e });
   }
-  const temperature = typeof defaultConfig?.temperature === "number" ? defaultConfig.temperature : 0;
-  const constructorOptions = {
-    model,
-    temperature,
-    ...apiKey ? { apiKey } : {},
-    ...baseURL ? { configuration: { baseURL } } : {}
-  };
   try {
-    return new ChatOpenAI(constructorOptions);
+    const llm = parseLlmYaml(raw, options);
+    return llm ?? null;
   } catch (e) {
-    throw normalizeAgentLlMError(e, "agent-llm: failed to create ChatOpenAI from config");
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`agent-llm: failed to parse config file ${filePath}: ${msg}`, { cause: e });
   }
 }
 
@@ -316,8 +283,86 @@ function registerProvider(name, factory) {
   PROVIDERS[name.toLowerCase()] = factory;
 }
 
-// src/loadLLMExtensions.ts
-import { readdirSync, readFileSync, existsSync } from "fs";
+// src/registry/chat-model.ts
+var CHAT_MODEL_FACTORIES = /* @__PURE__ */ new Map();
+function registerChatModelProvider(providerName, factory) {
+  CHAT_MODEL_FACTORIES.set(providerName.toLowerCase(), factory);
+}
+function getChatModelFactory(providerName) {
+  return CHAT_MODEL_FACTORIES.get(providerName.toLowerCase());
+}
+
+// src/langchain/adapter.ts
+import { ChatOpenAI } from "@langchain/openai";
+var DEFAULT_MODEL = "gpt-4o-mini";
+function normalizeAgentLlMError(e, context) {
+  if (e instanceof Error) return new Error(`${context}: ${e.message}`, { cause: e });
+  return new Error(`${context}: ${String(e)}`);
+}
+function createChatModelFromLlmConfig(options) {
+  const { llmSection, modelEnv, apiKeyEnv } = options;
+  let defaultId;
+  let configs;
+  try {
+    const parsed = parseLlmSection(llmSection ?? null);
+    defaultId = parsed.defaultId;
+    configs = parsed.configs;
+  } catch (e) {
+    throw normalizeAgentLlMError(e, "agent-llm: failed to parse llm section");
+  }
+  const defaultConfig = configs.find((c) => c.id === defaultId) ?? configs[0];
+  if (!defaultConfig) {
+    const model2 = modelEnv ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
+    const apiKey2 = apiKeyEnv ?? process.env.OPENAI_API_KEY;
+    try {
+      return new ChatOpenAI({
+        model: model2,
+        temperature: 0,
+        ...apiKey2 ? { apiKey: apiKey2 } : {}
+      });
+    } catch (e) {
+      throw normalizeAgentLlMError(e, "agent-llm: failed to create default ChatOpenAI");
+    }
+  }
+  const provider = defaultConfig.provider ?? "openai";
+  const chatModelFactory = getChatModelFactory(provider);
+  if (chatModelFactory) {
+    const config = {
+      ...defaultConfig,
+      model: modelEnv ?? defaultConfig.model,
+      temperature: typeof defaultConfig.temperature === "number" ? defaultConfig.temperature : 0
+    };
+    try {
+      return chatModelFactory(config);
+    } catch (e) {
+      throw normalizeAgentLlMError(e, `agent-llm: failed to create ChatModel for provider "${provider}"`);
+    }
+  }
+  const model = modelEnv ?? defaultConfig?.model ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
+  let apiKey = apiKeyEnv ?? defaultConfig?.apiKey ?? process.env.OPENAI_API_KEY;
+  let baseURL = defaultConfig?.baseURL;
+  if (baseURL && !baseURL.replace(/\/$/, "").endsWith("/v1")) {
+    baseURL = baseURL.replace(/\/$/, "") + "/v1";
+  }
+  if (baseURL && apiKey === void 0) {
+    apiKey = "ollama";
+  }
+  const temperature = typeof defaultConfig?.temperature === "number" ? defaultConfig.temperature : 0;
+  const constructorOptions = {
+    model,
+    temperature,
+    ...apiKey ? { apiKey } : {},
+    ...baseURL ? { configuration: { baseURL } } : {}
+  };
+  try {
+    return new ChatOpenAI(constructorOptions);
+  } catch (e) {
+    throw normalizeAgentLlMError(e, "agent-llm: failed to create ChatOpenAI from config");
+  }
+}
+
+// src/extensions/loader.ts
+import { readdirSync, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
 import { join } from "path";
 import { pathToFileURL } from "url";
 var loadedPackages = /* @__PURE__ */ new Set();
@@ -356,9 +401,9 @@ function resolveLLMExtensionPackages(types) {
   );
 }
 function readPackageProviderName(pkgPath) {
-  if (!existsSync(pkgPath)) return null;
+  if (!existsSync2(pkgPath)) return null;
   try {
-    const raw = readFileSync(pkgPath, "utf-8");
+    const raw = readFileSync2(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
     const declared = pkg.agentLlmProvider === true || Array.isArray(pkg.keywords) && pkg.keywords.includes("agent-llm-provider");
     return declared && typeof pkg.name === "string" ? pkg.name : null;
@@ -369,7 +414,7 @@ function readPackageProviderName(pkgPath) {
 function discoverLLMExtensions(cwd = process.cwd()) {
   const dir = typeof cwd === "string" && cwd.trim().length > 0 ? cwd : process.cwd();
   const nodeModules = join(dir, "node_modules");
-  if (!existsSync(nodeModules)) return [];
+  if (!existsSync2(nodeModules)) return [];
   const names = [];
   const seen = /* @__PURE__ */ new Set();
   try {
@@ -401,13 +446,13 @@ function discoverLLMExtensions(cwd = process.cwd()) {
 }
 async function loadModuleFromPath(pkgDir) {
   const pkgJsonPath = join(pkgDir, "package.json");
-  if (!existsSync(pkgJsonPath)) {
+  if (!existsSync2(pkgJsonPath)) {
     throw new Error(`package.json not found in ${pkgDir}`);
   }
-  const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+  const pkgJson = JSON.parse(readFileSync2(pkgJsonPath, "utf-8"));
   const main = pkgJson?.main ?? "index.js";
   const entryPath = join(pkgDir, main);
-  if (!existsSync(entryPath)) {
+  if (!existsSync2(entryPath)) {
     throw new Error(`Entry ${main} not found in ${pkgDir}`);
   }
   const entryUrl = pathToFileURL(entryPath).href;
@@ -424,9 +469,9 @@ async function loadLLMExtensions(extensionPackages, options) {
     loadedPackages.add(pkg);
     let loaded = false;
     const cwdPkgDir = join(cwd, "node_modules", pkg);
-    const cwdIsProject = existsSync(join(cwd, "package.json")) && (() => {
+    const cwdIsProject = existsSync2(join(cwd, "package.json")) && (() => {
       try {
-        const name = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8")).name;
+        const name = JSON.parse(readFileSync2(join(cwd, "package.json"), "utf-8")).name;
         return name === pkg;
       } catch {
         return false;
@@ -434,7 +479,7 @@ async function loadLLMExtensions(extensionPackages, options) {
     })();
     const dirsToTry = [cwdPkgDir, ...cwdIsProject ? [cwd] : []];
     for (const pkgDir of dirsToTry) {
-      if (!existsSync(join(pkgDir, "package.json"))) continue;
+      if (!existsSync2(join(pkgDir, "package.json"))) continue;
       try {
         const m = await loadModuleFromPath(pkgDir);
         const ext = getExtensionFromModule(m);
@@ -480,7 +525,7 @@ async function loadDiscoveredExtensions(cwd = process.cwd()) {
   return names;
 }
 
-// src/npmProviderProtocol.ts
+// src/extensions/npm-protocol.ts
 import { execSync } from "child_process";
 var NPM_PROTOCOL_PREFIX = "npm:";
 function parseNpmProviderSpec(spec) {
@@ -636,52 +681,7 @@ async function createChatModelFromLlmConfigWithNpm(options) {
   }
 }
 
-// src/loadLlmConfig.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
-import { parse as parseYaml } from "yaml";
-function substituteEnv(obj) {
-  if (obj === null || obj === void 0) return obj;
-  if (typeof obj === "string") {
-    const m = obj.match(/^\$\{(\w+)\}$/);
-    return m ? process.env[m[1]] ?? obj : obj;
-  }
-  if (Array.isArray(obj)) return obj.map(substituteEnv);
-  if (typeof obj === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) out[k] = substituteEnv(v);
-    return out;
-  }
-  return obj;
-}
-function parseLlmYaml(content, options = {}) {
-  const { substituteEnv: doSub = true } = options;
-  const parsed = parseYaml(content);
-  const llm = parsed?.llm;
-  if (llm == null) return void 0;
-  return doSub ? substituteEnv(llm) : llm;
-}
-function loadLlmConfig(filePath, options = {}) {
-  if (typeof filePath !== "string" || filePath.trim().length === 0) {
-    throw new Error("agent-llm: loadLlmConfig requires a non-empty file path");
-  }
-  if (!existsSync2(filePath)) return null;
-  let raw;
-  try {
-    raw = readFileSync2(filePath, "utf8");
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    throw new Error(`agent-llm: failed to read config file ${filePath}: ${msg}`, { cause: e });
-  }
-  try {
-    const llm = parseLlmYaml(raw, options);
-    return llm ?? null;
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    throw new Error(`agent-llm: failed to parse config file ${filePath}: ${msg}`, { cause: e });
-  }
-}
-
-// src/createAgentLlM.ts
+// src/api/create-agent-llm.ts
 import { join as join2 } from "path";
 function resolveDefaultConfigPath() {
   const cwd = process.cwd();
@@ -717,14 +717,17 @@ async function createAgentLlM(configPathOrOptions) {
 
 export {
   parseLlmSection,
-  registerChatModelProvider,
-  getChatModelFactory,
-  createChatModelFromLlmConfig,
+  substituteEnv,
+  parseLlmYaml,
+  loadLlmConfig,
   createOpenAIChatClient,
   createOpenAIImageClient,
   createOpenAIClient,
   createClient,
   registerProvider,
+  registerChatModelProvider,
+  getChatModelFactory,
+  createChatModelFromLlmConfig,
   resolveLLMExtensionPackages,
   discoverLLMExtensions,
   loadLLMExtensions,
@@ -736,9 +739,6 @@ export {
   resolveNpmProvider,
   resolveLlmSectionWithNpm,
   createChatModelFromLlmConfigWithNpm,
-  substituteEnv,
-  parseLlmYaml,
-  loadLlmConfig,
   createAgentLlM
 };
-//# sourceMappingURL=chunk-L3K6IEC6.js.map
+//# sourceMappingURL=chunk-VR7BRFGB.js.map