@easynet/agent-llm 1.0.2 → 1.0.4

package/README.md

@@ -1,101 +1,87 @@
-# Agent LLM
+# @easynet/agent-llm
 
-**LLM component for the Agent ecosystem** (standalone: no dependency on agent-tool or agent-memory). Supports **OpenAI-compatible** format (`/v1/chat/completions`) and **extension providers** loaded by npm package name. Multi-instance: each LLM has an **id** and **type** (chat / image). Supports **baseURL** for Azure, Ollama, Groq, and other /v1-compatible endpoints. Has its own **llm** section in agent.yaml.
+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.).
 
-## Install
+## Command line
+
+Install and run with a question:
 
 ```bash
-cd agent-llm
-npm install
+npx @easynet/agent-llm "hi"
+npx @easynet/agent-llm "What is 10 + 20?"
 ```
 
-## Config (agent.yaml llm or models section)
+Config is read from **llm.yaml** or **config/llm.yaml** in the current directory (or parent). See [config/llm.yaml.example](config/llm.yaml.example). Placeholders like `${OPENAI_API_KEY}` are replaced from the environment.
 
-**provider** supports `openai`, `openai-compatible`, and providers registered by extensions (see **llm.type**). Optional **base_url** / **baseURL** for Groq, Ollama, and other compatible endpoints.
+## Use in a LangChain agent
 
-**Flat format** (id → base_url, name, options):
+**1.** Get the LLM from config with `createAgentLlM()`:
 
-```yaml
-llm:
-  default: strong
-  strong:
-    provider: openai
-    base_url: https://api.groq.com/openai
-    name: openai/gpt-oss-120b
-    options:
-      apiKey: ${GROQ_API_KEY}
-      temperature: 0.7
-  medium:
-    provider: openai
-    base_url: http://192.168.0.201:11434
-    name: qwen3:4b
-    options:
-      apiKey: ${API_KEY}
+```ts
+import { createAgentLlM } from "@easynet/agent-llm";
+import { createAgent, tool } from "langchain";
+import { z } from "zod";
+
+const llm = createAgentLlM();
 ```
 
-**Single object** (one default chat):
+**2.** Create your agent with LangChain’s `createAgent` and your tools:
 
-```yaml
-llm:
-  provider: openai
-  model: gpt-4o-mini
-  temperature: 0
-  apiKey: ${OPENAI_API_KEY}
-  # base_url: https://api.groq.com/openai
+```ts
+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] });
 ```
 
-**Multi-instance** (instances array with id, type, provider, model) see llm.yaml.example. Use **llm.type** to load extension packages that register additional providers.
+**3.** Invoke with messages:
 
-## LangChain adapter
+```ts
+import { HumanMessage } from "@langchain/core/messages";
 
-Build a LangChain ChatModel from the llm section of agent.yaml (for `createAgent`, etc.):
+const result = await agent.invoke({ messages: [new HumanMessage("What is 10 + 20?")] });
+console.log(result.messages?.slice(-1)[0]?.content);
+```
 
-- **`createChatModelFromLlmConfig({ llmSection })`** — returns `ChatOpenAI` (openai) or an extension-registered ChatModel for other providers.
-- Extension packages can register ChatModel factories via `registerChatModelProvider`; call **loadLLMExtensions** before use.
+Full example: [examples/langchain-react-agent.ts](examples/langchain-react-agent.ts).
 
-The agent package re-exports these; you can also depend on `@easynet/agent-llm` directly.
+## Config
 
-## Usage
+Put **llm.yaml** (or **config/llm.yaml**) in your project. Example:
 
-```ts
-import { createLLMRegistry } from "@easynet/agent-llm";
-
-const config = await loadAgentConfig("agent.yaml");
-const registry = createLLMRegistry({ llmSection: config.llm });
-
-const defaultId = registry.defaultId();
-if (defaultId) {
-  const llm = registry.get(defaultId)!;
-  const result = await llm.chat([
-    { role: "user", content: "Hello" },
-  ]);
-  console.log(result.content);
-}
-
-const imageLlm = registry.get("image");
-if (imageLlm?.generateImage) {
-  const img = await imageLlm.generateImage({ prompt: "A cat" });
-  console.log(img.url);
-}
+```yaml
+provider: openai
+model: gpt-4o-mini
+temperature: 0
+apiKey: ${OPENAI_API_KEY}
+# baseURL: https://api.openai.com/v1  # or Ollama, Groq, etc.
 ```
 
-## API
+Optional: pass a path when calling `createAgentLlM({ configPath: "/path/to/llm.yaml" })`.
+
+## npm: protocol in provider (install on demand)
 
-- **createLLMRegistry({ llmSection })** — create registry from agent config llm section
-- **registry.get(id)** — get ILLMClient by id
-- **registry.defaultId()** — default LLM id
-- **registry.ids()** — all ids
-- **ILLMClient.chat(messages)** — chat (type=chat)
-- **ILLMClient.generateImage?(options)** — image generation (type=image)
+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.
 
-## Ecosystem
+**Recommended format:** `npm:<package>@<version>#<provider>` — e.g. **`provider: "npm:wallee-llm@0.1.0#cis"`**.
 
-- **agent** — orchestration; agent.yaml has llm section and uses agent-llm’s createLLMRegistry(config.llm).
-- **agent-llm** — this repo: OpenAI-compatible and extension providers; config parsing and multi-instance chat/image API.
+- **`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`).
 
-## Publishing to npm
+Use **createChatModelFromLlmConfigWithNpm** or **createAgentLlMAsync** so npm: providers are resolved (and optionally installed) before creating the model:
 
-Releases are published as **@easynet/agent-llm** to https://www.npmjs.com via GitHub Actions (patch-only, starting at 0.0.1).
+```ts
+import { createChatModelFromLlmConfigWithNpm, createAgentLlMAsync } from "@easynet/agent-llm";
+
+// From a raw llm section (e.g. from loadLlmConfig)
+const model = await createChatModelFromLlmConfigWithNpm({ llmSection });
+
+// From config file (llm.yaml / config/llm.yaml)
+const llm = await createAgentLlMAsync();
+```
 
-1. In this repo: **Settings → Secrets and variables → Actions**, add secret **NPM_TOKEN** (npm token with Automation or Publish, allow bypass 2FA). Create at https://www.npmjs.com/settings/~/tokens.
-2. Push to **master** or run **Actions → Release → Run workflow** to trigger the release. The workflow runs tests, builds, then semantic-release to bump patch and publish to npm.
+Options: **installNpmIfMissing** (default `true`) and **cwd** (default `process.cwd()` for npm install). Exports: `parseNpmProviderSpec`, `ensureNpmPackageInstalled`, `resolveNpmProvider`, `resolveLlmSectionWithNpm`, `isNpmProviderSpec`, `createChatModelFromLlmConfigWithNpm`, `createAgentLlMAsync`.