@agentforge-io/llm-langchain 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { OpenAIProvider, type OpenAIProviderOptions, } from './providers/openai-provider';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// ─── @agentforge-io/llm-langchain ────────────────────────────────────────────
+//
+// LangChain-backed providers that implement the framework-free `LLMProvider`
+// contract from `@agentforge-io/core/ai`. Drop one of these into the agent
+// runner and the agent loop, tool dispatch, approval gating, and model
+// routing keep working unchanged.
+//
+// Currently shipped:
+//   - OpenAIProvider — covers OpenAI and any OpenAI-compatible endpoint
+//     (Grok via x.ai, Together, vLLM, local Ollama) by setting `baseURL`.
+//
+// Planned (next):
+//   - GeminiProvider via `@langchain/google-genai`
+//
+// The host wires which provider runs per tenant; this package only ships
+// the adapters, not the resolution logic.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIProvider = void 0;
+var openai_provider_1 = require("./providers/openai-provider");
+Object.defineProperty(exports, "OpenAIProvider", { enumerable: true, get: function () { return openai_provider_1.OpenAIProvider; } });

package/dist/providers/openai-provider.d.ts

@@ -0,0 +1,28 @@
+import type { LLMProvider, LLMProviderCapabilities, LLMStreamEvent, LLMStreamParams } from '@agentforge-io/core/ai';
+export interface OpenAIProviderOptions {
+    apiKey: string;
+    /** Override the API base URL. Used for OpenAI-compatible endpoints
+     *  (Grok via x.ai, local Ollama, vLLM, Together, etc.) without
+     *  shipping a separate provider class. When unset LangChain uses
+     *  OpenAI's production endpoint. */
+    baseURL?: string;
+    /** Organization id (OpenAI-specific). Ignored by compatible endpoints. */
+    organization?: string;
+    /** Provider id surfaced to the platform's resolver. Defaults to
+     *  `'openai'`. Subclasses that target a compatible endpoint
+     *  (Grok, etc.) override this so the runner can attribute usage
+     *  to the right provider in telemetry. */
+    id?: string;
+    /** Human-readable label. Defaults to `'OpenAI'`. */
+    displayName?: string;
+}
+export declare class OpenAIProvider implements LLMProvider {
+    readonly id: string;
+    readonly displayName: string;
+    readonly capabilities: LLMProviderCapabilities;
+    private readonly apiKey;
+    private readonly baseURL?;
+    private readonly organization?;
+    constructor(opts: OpenAIProviderOptions);
+    stream(params: LLMStreamParams): AsyncGenerator<LLMStreamEvent>;
+}

package/dist/providers/openai-provider.js

@@ -0,0 +1,308 @@
+"use strict";
+// ─── OpenAI provider (via LangChain) ────────────────────────────────────────
+//
+// Wraps `@langchain/openai`'s ChatOpenAI behind the framework-free
+// `LLMProvider` contract from `@agentforge-io/core`. The runner doesn't
+// know it's talking to OpenAI — it gets the same stream-event shape as
+// AnthropicProvider, the same tool schema in, and the same `message_stop`
+// envelope out.
+//
+// We deliberately use LangChain (not `openai` directly) because:
+//   1. It already normalises OpenAI's two streaming shapes (Chat Completions
+//      legacy + the newer Responses API) into a single message stream.
+//   2. Drop-in support for OpenAI-compatible endpoints (Grok, local Ollama,
+//      vLLM, Together, etc.) via `configuration.baseURL` — adding Grok costs
+//      us ~5 lines, not a separate transport.
+//   3. The tool-calling adapter (`convertToOpenAITool`) is published and
+//      maintained by LangChain — we don't reinvent the JSON-schema → OpenAI
+//      function-spec translation.
+//
+// Tool flow mismatch with Anthropic worth calling out: OpenAI emits the tool
+// arguments INCREMENTALLY (one piece of the JSON object per stream event),
+// then closes the message with `finish_reason: 'tool_calls'`. Anthropic emits
+// the parsed input atomically once the `tool_use` content block is complete.
+// We bridge by buffering the streamed arguments and parsing once at the end —
+// the runner still gets the `tool_use_start` event with full input, matching
+// the Anthropic contract.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIProvider = void 0;
+const openai_1 = require("@langchain/openai");
+const messages_1 = require("@langchain/core/messages");
+class OpenAIProvider {
+    constructor(opts) {
+        this.capabilities = {
+            supportsTools: true,
+            supportsStreaming: true,
+            supportsTemperature: true,
+            // OpenAI's tool-calling lets the model emit multiple `tool_calls`
+            // in one assistant turn, same as Anthropic.
+            supportsParallelTools: true,
+        };
+        this.id = opts.id ?? 'openai';
+        this.displayName = opts.displayName ?? 'OpenAI';
+        this.apiKey = opts.apiKey;
+        this.baseURL = opts.baseURL;
+        this.organization = opts.organization;
+    }
+    async *stream(params) {
+        // ChatOpenAI is constructed PER CALL because the model id varies
+        // (the runner picks a model per turn via `selectModel()`). The HTTP
+        // client itself is stateless so there's no perf hit; if profiling
+        // ever shows one, we can cache by (model, temperature) tuple.
+        const llm = new openai_1.ChatOpenAI({
+            apiKey: this.apiKey,
+            model: params.model,
+            temperature: params.temperature,
+            maxTokens: params.maxTokens,
+            streaming: true,
+            configuration: {
+                baseURL: this.baseURL,
+                organization: this.organization,
+            },
+        });
+        // Bind tools onto a fresh model handle. LangChain's `bindTools`
+        // translates our Anthropic-shaped `LLMToolSchema[]` into OpenAI's
+        // `{ type: 'function', function: {...} }` envelope. We don't have
+        // to hand-write the converter — LC owns that mapping and keeps it
+        // in sync with the OpenAI SDK.
+        const bound = params.tools && params.tools.length > 0
+            ? llm.bindTools(params.tools.map(toLangChainTool))
+            : llm;
+        const messages = toLangChainMessages(params.systemPrompt, params.messages);
+        // Buffers built up across the stream — flushed when we emit the
+        // single `message_stop` event at the end.
+        let textBuffer = '';
+        // Tool calls arrive incrementally. Keyed by index because OpenAI
+        // can stream multiple tool calls in parallel and we have to
+        // accumulate each one's `arguments` JSON chunk-by-chunk.
+        const toolCalls = new Map();
+        let usageInput = 0;
+        let usageOutput = 0;
+        let stopReason = 'end_turn';
+        const stream = await bound.stream(messages);
+        for await (const chunk of stream) {
+            // Text token. LangChain normalises the OpenAI delta into
+            // `chunk.content` (string when single-modal, array when
+            // multi-modal — we coerce to string).
+            const text = typeof chunk.content === 'string'
+                ? chunk.content
+                : chunk.content
+                    .map((c) => (typeof c === 'string' ? c : 'text' in c ? c.text : ''))
+                    .join('');
+            if (text) {
+                textBuffer += text;
+                yield { type: 'text_delta', delta: text };
+            }
+            // Tool-call deltas. The first chunk per index carries the call's
+            // `id` and `name`; subsequent chunks just stream more of the
+            // JSON `args` string. We emit `tool_use_start` ONCE per tool
+            // call — when we've seen the name for the first time AND when
+            // arguments have been fully accumulated (we re-parse at the end
+            // because OpenAI sometimes only sends the final args in the
+            // CLOSING chunk, not per delta).
+            const deltaToolCalls = chunk.tool_call_chunks ?? [];
+            for (const tc of deltaToolCalls) {
+                const idx = tc.index ?? 0;
+                const existing = toolCalls.get(idx);
+                if (!existing) {
+                    toolCalls.set(idx, {
+                        id: tc.id ?? `call_${idx}`,
+                        name: tc.name ?? '',
+                        argsBuffer: tc.args ?? '',
+                        started: false,
+                    });
+                }
+                else {
+                    if (tc.id && !existing.id.startsWith('call_'))
+                        existing.id = tc.id;
+                    if (tc.name)
+                        existing.name = tc.name;
+                    if (tc.args)
+                        existing.argsBuffer += tc.args;
+                }
+            }
+            // Usage usually only lands in the final chunk (OpenAI sends it
+            // alongside `finish_reason`); accumulate defensively in case
+            // intermediate chunks ever carry partial counts.
+            const usageMeta = chunk
+                .usage_metadata;
+            if (usageMeta) {
+                usageInput = usageMeta.input_tokens ?? usageInput;
+                usageOutput = usageMeta.output_tokens ?? usageOutput;
+            }
+            // Finish reason — LangChain stamps this on the LAST chunk via
+            // `response_metadata.finish_reason` or similar; we read both
+            // common shapes.
+            const finishReason = chunk
+                .response_metadata?.finish_reason ??
+                chunk.finish_reason;
+            if (finishReason) {
+                stopReason = normalizeFinishReason(finishReason);
+            }
+        }
+        // Once the stream's exhausted, emit a tool_use_start per fully
+        // accumulated tool call. We parse the buffered JSON args now —
+        // doing it here (instead of incrementally) matches the Anthropic
+        // contract where the runner gets the complete input in one event.
+        const finalContent = [];
+        if (textBuffer) {
+            finalContent.push({ type: 'text', text: textBuffer });
+        }
+        for (const [, call] of toolCalls) {
+            if (!call.name)
+                continue;
+            let parsedInput = {};
+            try {
+                parsedInput = call.argsBuffer
+                    ? JSON.parse(call.argsBuffer)
+                    : {};
+            }
+            catch {
+                // If OpenAI streamed malformed JSON (it shouldn't, but
+                // gateways and proxies can corrupt it), surface empty input
+                // rather than crashing the runner — the tool dispatch will
+                // fail with a more actionable error than a JSON parse error.
+                parsedInput = {};
+            }
+            yield {
+                type: 'tool_use_start',
+                toolUseId: call.id,
+                toolName: call.name,
+                input: parsedInput,
+            };
+            finalContent.push({
+                type: 'tool_use',
+                id: call.id,
+                name: call.name,
+                input: parsedInput,
+            });
+        }
+        // If the model emitted tool calls AND text, OpenAI's finish reason
+        // is `tool_calls` (not `stop`). Mirror Anthropic's `tool_use` so
+        // the runner re-enters the loop with tool results.
+        if (toolCalls.size > 0 && stopReason !== 'max_tokens') {
+            stopReason = 'tool_use';
+        }
+        yield {
+            type: 'usage_delta',
+            usage: {
+                inputTokens: usageInput,
+                outputTokens: usageOutput,
+                totalTokens: usageInput + usageOutput,
+            },
+        };
+        yield {
+            type: 'message_stop',
+            stopReason,
+            content: finalContent,
+        };
+    }
+}
+exports.OpenAIProvider = OpenAIProvider;
+// ─── Translation helpers ────────────────────────────────────────────────────
+/**
+ * Translate our provider-agnostic tool schema into the shape LangChain's
+ * `bindTools` expects. The actual conversion to OpenAI's
+ * `{ type: 'function', function: {...} }` envelope happens inside
+ * LangChain via `convertToOpenAITool`.
+ */
+function toLangChainTool(t) {
+    return {
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            // Our `input_schema` is already JSON Schema (Anthropic uses the same
+            // dialect OpenAI does — just lives at a different key). Passing it
+            // through directly avoids a translation pass and works because
+            // LangChain inspects `parameters` for both providers.
+            parameters: t.input_schema,
+        },
+    };
+}
+/**
+ * Translate our chat history into LangChain's `BaseMessage[]`. Tool
+ * results become `ToolMessage`s (with `tool_call_id`), tool calls live
+ * inside `AIMessage.tool_calls`, and plain text content lives where
+ * you'd expect.
+ *
+ * We compose the system prompt as the first message rather than
+ * configuring it on the ChatOpenAI instance because LC handles
+ * pre-pending it identically and this keeps the call site uniform.
+ */
+function toLangChainMessages(systemPrompt, messages) {
+    const out = [];
+    if (systemPrompt) {
+        out.push(new messages_1.SystemMessage(systemPrompt));
+    }
+    for (const m of messages) {
+        if (typeof m.content === 'string') {
+            out.push(m.role === 'user' ? new messages_1.HumanMessage(m.content) : new messages_1.AIMessage(m.content));
+            continue;
+        }
+        if (m.role === 'user') {
+            // User messages with multi-part content come from the runner's
+            // tool-result flow: after a tool dispatches, the runner appends
+            // a `tool_result` content block under role='user' (mirroring
+            // Anthropic's convention). LangChain wants those as a separate
+            // ToolMessage per result; split them out here.
+            const textParts = [];
+            for (const block of m.content) {
+                if (block.type === 'text') {
+                    textParts.push(block.text);
+                }
+                else if (block.type === 'tool_result') {
+                    // Flush any pending text before the tool message so the
+                    // chronology stays right.
+                    if (textParts.length > 0) {
+                        out.push(new messages_1.HumanMessage(textParts.join('\n')));
+                        textParts.length = 0;
+                    }
+                    out.push(new messages_1.ToolMessage({
+                        tool_call_id: block.tool_use_id,
+                        content: block.content,
+                        status: block.is_error ? 'error' : 'success',
+                    }));
+                }
+            }
+            if (textParts.length > 0) {
+                out.push(new messages_1.HumanMessage(textParts.join('\n')));
+            }
+        }
+        else {
+            // Assistant turns can carry a text part AND tool_use blocks.
+            // LangChain represents that as a single AIMessage with `content`
+            // (the text) plus a `tool_calls` array.
+            const textParts = [];
+            const toolCalls = [];
+            for (const block of m.content) {
+                if (block.type === 'text')
+                    textParts.push(block.text);
+                else if (block.type === 'tool_use')
+                    toolCalls.push({
+                        id: block.id,
+                        name: block.name,
+                        args: block.input,
+                        type: 'tool_call',
+                    });
+            }
+            out.push(new messages_1.AIMessage({
+                content: textParts.join('\n'),
+                tool_calls: toolCalls,
+            }));
+        }
+    }
+    return out;
+}
+function normalizeFinishReason(raw) {
+    switch (raw) {
+        case 'tool_calls':
+        case 'function_call':
+            return 'tool_use';
+        case 'length':
+            return 'max_tokens';
+        case 'stop':
+        default:
+            return 'end_turn';
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@agentforge-io/llm-langchain",
+  "version": "0.1.0",
+  "description": "LangChain-backed LLM providers (OpenAI, Grok, Gemini) implementing the framework-free `LLMProvider` contract from @agentforge-io/core. Drop-in replacements for AnthropicProvider — same stream events, same tool schema, no changes to the agent runner.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist *.tgz",
+    "test": "node --test --import tsx --test-reporter=spec tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@agentforge-io/core": ">=2.3.0-rc.0"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.0",
+    "@langchain/openai": "^0.3.0",
+    "@langchain/google-genai": "^0.1.0"
+  },
+  "devDependencies": {
+    "@agentforge-io/core": "^2.3.0-rc.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.0"
+  }
+}