@fllf/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# FAgent
+
+FAgent is a composable TypeScript foundation for building Agent runtimes.
+
+It provides the shared building blocks for an Agent instead of forcing users to subclass a base class. An Agent is assembled from an LLM, session-scoped message history, tools, config, and an executor.
+
+## Status
+
+The project is in an early runtime-foundation stage. The core architecture is in place:
+
+- Composable `Agent`
+- Unified `LLM.chat()` interface
+- OpenAI and local OpenAI-compatible providers
+- Streaming support through `LLM.stream()`
+- Timeout, retry, abort, and normalized LLM errors
+- `generateObject()` structured output with Zod validation
+- Session-scoped message history with an in-memory store
+- Simple chat and tool-calling executors
+- Zod-driven tool system
+- Optional observer events for debugging and tracing
+
+## Install
+
+```bash
+npm install
+```
+
+## Scripts
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+Examples:
+
+```bash
+npm run example:simple-chat
+npm run example:tool-calling
+npm run example:local-ollama
+```
+
+## Environment
+
+OpenAI:
+
+```bash
+OPENAI_API_KEY=...
+OPENAI_MODEL=gpt-4o-mini
+```
+
+Local OpenAI-compatible runtime, such as Ollama, LM Studio, vLLM, or compatible services:
+
+```bash
+LOCAL_BASE_URL=http://127.0.0.1:11434/v1
+LOCAL_MODEL=llama3
+LOCAL_API_KEY=local-key
+```
+
+If no OpenAI key is configured, FAgent falls back to the local provider.
+
+## Basic Usage
+
+```ts
+import { Agent } from 'fagent';
+
+const agent = new Agent({
+  name: 'simple-chat',
+  systemPrompt: 'You are a concise assistant.',
+});
+
+const result = await agent.run('What is FAgent?');
+console.log(result.output);
+```
+
+## Sessions
+
+FAgent uses LangChain-style session-scoped message history. The `Agent` is the reusable runtime, and `sessionId` selects the conversation context.
+
+```ts
+const agent = new Agent({
+  name: 'support-bot',
+  systemPrompt: 'You are a helpful support assistant.',
+});
+
+await agent.run('Hi, I need help with an order.', {
+  sessionId: 'session_a',
+});
+
+await agent.run('Start a separate conversation.', {
+  sessionId: 'session_b',
+});
+```
+
+Runs from different sessions can proceed concurrently. Runs for the same session are serialized so the conversation history stays ordered.
+
+If `sessionId` is omitted or blank, FAgent uses the shared `default` session. For production apps where every request should belong to an explicit user, tenant, or conversation, enable strict session ids:
+
+```ts
+const agent = new Agent({
+  name: 'support-bot',
+  requireSessionId: true,
+});
+
+await agent.run('Hi, I need help with an order.', {
+  sessionId: 'user_123:order_456',
+});
+```
+
+With `requireSessionId: true`, `run`, `addMessage`, `clearHistory`, and `getHistory` reject missing or blank session ids instead of falling back to `default`.
+
+Recoverable tool failures stay inside the agent loop: FAgent records the failure as a `tool` message, sends it back to the model, and commits the full turn if the executor completes successfully. If the run cannot continue because the model/provider fails before producing a response, FAgent leaves that session's history unchanged and reports the failure through runtime events such as `agent:error` and `llm:error`.
+
+For the built-in `InMemoryMessageHistoryStore`, `clear(sessionId)` empties a session while keeping its history entry alive. Use `deleteSession(sessionId)` to release one session entry, or `clearAll()` to release every in-memory session entry.
+
+## Tool Calling
+
+Tools are defined with Zod schemas. The framework turns the schema into an OpenAI-compatible tool schema and validates model-supplied arguments before running the tool.
+
+```ts
+import { z } from 'zod';
+import { Agent, Tool, ToolCallingExecutor } from 'fagent';
+
+const AddToolSchema = z.object({
+  left: z.number().describe('Left number.'),
+  right: z.number().describe('Right number.'),
+});
+
+class AddTool extends Tool<typeof AddToolSchema, number> {
+  constructor() {
+    super({
+      name: 'add',
+      description: 'Adds two numbers.',
+      schema: AddToolSchema,
+    });
+  }
+
+  protected run(input: z.infer<typeof AddToolSchema>): number {
+    return input.left + input.right;
+  }
+}
+
+const agent = new Agent({
+  name: 'tool-agent',
+  tools: [new AddTool()],
+  executor: new ToolCallingExecutor(),
+});
+
+const result = await agent.run('Use the add tool to calculate 19 + 23.');
+console.log(result.output);
+```
+
+## Structured Output
+
+```ts
+import { z } from 'zod';
+import { LLM } from 'fagent';
+
+const llm = new LLM();
+
+const result = await llm.generateObject({
+  messages: [
+    { role: 'user', content: 'Return a short project summary.' },
+  ],
+  schema: z.object({
+    summary: z.string(),
+    confidence: z.number(),
+  }),
+});
+
+console.log(result.value);
+```
+
+## Observability
+
+FAgent emits structured runtime events, but it does not print anything by default. Pass an observer when you want to debug or forward events to a logging system.
+
+```ts
+import { Agent, ConsoleObserver } from 'fagent';
+
+const agent = new Agent({
+  name: 'debug-agent',
+  observer: new ConsoleObserver(),
+});
+
+await agent.run('Hello');
+```
+
+Events include:
+
+- `agent:start`
+- `agent:end`
+- `agent:error`
+- `llm:start`
+- `llm:end`
+- `llm:error`
+- `tool:start`
+- `tool:end`
+- `tool:error`
+
+Custom observers can send events anywhere:
+
+```ts
+const observer = {
+  onEvent(event) {
+    myLogger.info(event);
+  },
+};
+```
+
+## Architecture
+
+```txt
+Agent
+  -> Executor
+      -> LLM
+      -> MessageHistory(sessionId)
+      -> ToolRegistry
+      -> ToolExecutor
+```
+
+Main responsibilities:
+
+- `Agent`: assembles runtime components and delegates execution.
+- `Executor`: controls the run strategy, such as simple chat or tool calling.
+- `LLM`: provides a unified model interface with timeout, retry, abort, and structured output support.
+- `Provider`: adapts OpenAI-compatible SDK calls to the unified LLM interface.
+- `MessageHistoryStore`: stores conversation history by `sessionId`.
+- `Tool`: defines external capabilities with Zod schemas.
+
+## Public Entry
+
+All public APIs are exported from:
+
+```ts
+import { Agent, LLM, Tool } from 'fagent';
+```
+
+During local development, examples import from `../src` so they can run without building first.

package/dist/agent/Agent.d.ts

@@ -0,0 +1,34 @@
+import { Config } from '../config';
+import type { AgentExecutor, AgentResult, AgentRunOptions } from '../executors';
+import type { MessageHistoryStore } from '../history';
+import type { ChatModel } from '../llm';
+import type { Message } from '../messages';
+import type { Observer } from '../observability';
+import { ToolRegistry } from '../tools';
+import type { AgentComponents } from './types';
+export declare class Agent {
+    readonly name: string;
+    readonly llm: ChatModel;
+    readonly historyStore: MessageHistoryStore;
+    readonly tools: ToolRegistry;
+    readonly systemPrompt: string | undefined;
+    readonly config: Config;
+    readonly executor: AgentExecutor;
+    readonly observer: Observer | undefined;
+    readonly requireSessionId: boolean;
+    private readonly sessionQueues;
+    constructor(components: AgentComponents);
+    /**
+     * Agent 只负责组装上下文并交给 executor。
+     * 不同 Agent 行为通过替换 executor / historyStore / tools / llm 实现。
+     */
+    run(input: string, options?: AgentRunOptions): Promise<AgentResult>;
+    private runWithSession;
+    addMessage(message: Message, sessionId?: string): Promise<void>;
+    clearHistory(sessionId?: string): Promise<void>;
+    getHistory(sessionId?: string): Promise<Message[]>;
+    toString(): string;
+    private runInSessionQueue;
+    private resolveSessionId;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/dist/agent/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,QAAQ,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAM3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,qBAAa,KAAK;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;gBAEtD,UAAU,EAAE,eAAe;IAcvC;;;OAGG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;YAS/D,cAAc;IA2DtB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQxD,QAAQ,IAAI,MAAM;IAIlB,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,gBAAgB;CAO3B"}

package/dist/agent/Agent.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const config_1 = require("../config");
+const executors_1 = require("../executors");
+const history_1 = require("../history");
+const llm_1 = require("../llm");
+const observability_1 = require("../observability");
+const tools_1 = require("../tools");
+class Agent {
+    name;
+    llm;
+    historyStore;
+    tools;
+    systemPrompt;
+    config;
+    executor;
+    observer;
+    requireSessionId;
+    sessionQueues = new Map();
+    constructor(components) {
+        this.name = components.name;
+        this.config = components.config ?? new config_1.Config();
+        this.llm = components.llm ?? createLLM(components.llmConfig, this.config);
+        this.historyStore = components.historyStore ?? new history_1.InMemoryMessageHistoryStore({
+            maxMessages: this.config.maxHistoryLength,
+        });
+        this.tools = normalizeTools(components.tools);
+        this.systemPrompt = components.systemPrompt;
+        this.executor = components.executor ?? new executors_1.SimpleChatExecutor();
+        this.observer = components.observer;
+        this.requireSessionId = components.requireSessionId ?? false;
+    }
+    /**
+     * Agent 只负责组装上下文并交给 executor。
+     * 不同 Agent 行为通过替换 executor / historyStore / tools / llm 实现。
+     */
+    async run(input, options = {}) {
+        const sessionId = this.resolveSessionId(options.sessionId);
+        return this.runInSessionQueue(sessionId, () => this.runWithSession(input, {
+            ...options,
+            sessionId,
+        }));
+    }
+    async runWithSession(input, options) {
+        const sessionId = (0, history_1.normalizeSessionId)(options.sessionId);
+        const runId = options.runId ?? (0, observability_1.createRunId)();
+        const observer = options.observer ?? this.observer;
+        const startedAt = Date.now();
+        const history = this.historyStore.get(sessionId);
+        await (0, observability_1.emitRuntimeEvent)(observer, {
+            type: 'agent:start',
+            runId,
+            timestamp: new Date(),
+            agentName: this.name,
+            sessionId,
+            metadata: options.metadata,
+        });
+        try {
+            const result = await this.executor.run({
+                runId,
+                agentName: this.name,
+                sessionId,
+                input,
+                options,
+                llm: this.llm,
+                history,
+                tools: this.tools,
+                observer,
+                systemPrompt: this.systemPrompt,
+                config: this.config,
+            });
+            await (0, observability_1.emitRuntimeEvent)(observer, {
+                type: 'agent:end',
+                runId,
+                timestamp: new Date(),
+                durationMs: Date.now() - startedAt,
+                agentName: this.name,
+                sessionId,
+                outputLength: result.output.length,
+            });
+            return result;
+        }
+        catch (error) {
+            await (0, observability_1.emitRuntimeEvent)(observer, {
+                type: 'agent:error',
+                runId,
+                timestamp: new Date(),
+                durationMs: Date.now() - startedAt,
+                agentName: this.name,
+                sessionId,
+                error: (0, observability_1.toObservedError)(error),
+            });
+            throw error;
+        }
+    }
+    async addMessage(message, sessionId) {
+        const resolvedSessionId = this.resolveSessionId(sessionId);
+        return this.runInSessionQueue(resolvedSessionId, () => (this.historyStore.get(resolvedSessionId).add(message)));
+    }
+    async clearHistory(sessionId) {
+        const resolvedSessionId = this.resolveSessionId(sessionId);
+        await this.runInSessionQueue(resolvedSessionId, () => (this.historyStore.clear(resolvedSessionId)));
+    }
+    async getHistory(sessionId) {
+        const resolvedSessionId = this.resolveSessionId(sessionId);
+        return await this.runInSessionQueue(resolvedSessionId, () => (this.historyStore.get(resolvedSessionId).get()));
+    }
+    toString() {
+        return `Agent(name=${this.name}, provider=${this.llm.name}, model=${this.llm.model})`;
+    }
+    runInSessionQueue(sessionId, operation) {
+        const previous = this.sessionQueues.get(sessionId) ?? Promise.resolve();
+        const result = previous.catch(() => undefined).then(operation);
+        let queued;
+        queued = result.then(() => undefined, () => undefined).finally(() => {
+            if (this.sessionQueues.get(sessionId) === queued) {
+                this.sessionQueues.delete(sessionId);
+            }
+        });
+        this.sessionQueues.set(sessionId, queued);
+        return result;
+    }
+    resolveSessionId(sessionId) {
+        if (this.requireSessionId && !hasExplicitSessionId(sessionId)) {
+            throw new Error('Agent requires a non-empty sessionId.');
+        }
+        return (0, history_1.normalizeSessionId)(sessionId);
+    }
+}
+exports.Agent = Agent;
+function createLLM(llmConfig, config) {
+    const resolvedConfig = {
+        ...llmConfig,
+    };
+    if (!resolvedConfig.provider && config.defaultProvider) {
+        resolvedConfig.provider = config.defaultProvider;
+    }
+    if (!resolvedConfig.model && config.defaultModel) {
+        resolvedConfig.model = config.defaultModel;
+    }
+    if (resolvedConfig.timeoutMs === undefined && config.requestTimeoutMs !== undefined) {
+        resolvedConfig.timeoutMs = config.requestTimeoutMs;
+    }
+    if (resolvedConfig.maxRetries === undefined && config.maxRetries !== undefined) {
+        resolvedConfig.maxRetries = config.maxRetries;
+    }
+    if (resolvedConfig.retryDelayMs === undefined && config.retryDelayMs !== undefined) {
+        resolvedConfig.retryDelayMs = config.retryDelayMs;
+    }
+    if (resolvedConfig.retryMaxDelayMs === undefined && config.retryMaxDelayMs !== undefined) {
+        resolvedConfig.retryMaxDelayMs = config.retryMaxDelayMs;
+    }
+    return new llm_1.LLM(resolvedConfig);
+}
+function normalizeTools(tools) {
+    if (tools instanceof tools_1.ToolRegistry) {
+        return tools;
+    }
+    if (Array.isArray(tools)) {
+        return new tools_1.ToolRegistry(tools);
+    }
+    return new tools_1.ToolRegistry();
+}
+function hasExplicitSessionId(sessionId) {
+    return sessionId !== undefined && sessionId.trim().length > 0;
+}
+//# sourceMappingURL=Agent.js.map

package/dist/agent/Agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/createAgent.d.ts

@@ -0,0 +1,4 @@
+import { Agent } from './Agent';
+import type { AgentComponents } from './types';
+export declare function createAgent(components: AgentComponents): Agent;
+//# sourceMappingURL=createAgent.d.ts.map

package/dist/agent/createAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAgent.d.ts","sourceRoot":"","sources":["../../src/agent/createAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,wBAAgB,WAAW,CAAC,UAAU,EAAE,eAAe,GAAG,KAAK,CAE9D"}

package/dist/agent/createAgent.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgent = createAgent;
+const Agent_1 = require("./Agent");
+function createAgent(components) {
+    return new Agent_1.Agent(components);
+}
+//# sourceMappingURL=createAgent.js.map

package/dist/agent/createAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAgent.js","sourceRoot":"","sources":["../../src/agent/createAgent.ts"],"names":[],"mappings":";;AAGA,kCAEC;AALD,mCAAgC;AAGhC,SAAgB,WAAW,CAAC,UAA2B;IACnD,OAAO,IAAI,aAAK,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC"}

package/dist/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { Agent } from './Agent';
+export { createAgent } from './createAgent';
+export type { AgentComponents, AgentLike, AgentResult, AgentRunOptions, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EACR,eAAe,EACf,SAAS,EACT,WAAW,EACX,eAAe,GAClB,MAAM,SAAS,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgent = exports.Agent = void 0;
+var Agent_1 = require("./Agent");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return Agent_1.Agent; } });
+var createAgent_1 = require("./createAgent");
+Object.defineProperty(exports, "createAgent", { enumerable: true, get: function () { return createAgent_1.createAgent; } });
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":";;;AAAA,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,6CAA4C;AAAnC,0GAAA,WAAW,OAAA"}

package/dist/agent/types.d.ts

@@ -0,0 +1,23 @@
+import type { Config } from '../config';
+import type { AgentExecutor, AgentResult, AgentRunOptions } from '../executors';
+import type { MessageHistoryStore } from '../history';
+import type { ChatModel, LLMConfig } from '../llm';
+import type { Observer } from '../observability';
+import type { Tool, ToolRegistry } from '../tools';
+export interface AgentComponents {
+    name: string;
+    llm?: ChatModel;
+    llmConfig?: LLMConfig;
+    historyStore?: MessageHistoryStore;
+    requireSessionId?: boolean;
+    tools?: ToolRegistry | Tool[];
+    systemPrompt?: string;
+    config?: Config;
+    executor?: AgentExecutor;
+    observer?: Observer;
+}
+export interface AgentLike {
+    run(input: string, options?: AgentRunOptions): Promise<AgentResult>;
+}
+export type { AgentResult, AgentRunOptions, };
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACtB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACvE;AAED,YAAY,EACR,WAAW,EACX,eAAe,GAClB,CAAC"}

package/dist/agent/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":""}

package/dist/config/config.d.ts

@@ -0,0 +1,35 @@
+import type { ModelProviderName } from '../llm/types';
+export interface ConfigOptions {
+    defaultModel?: string;
+    defaultProvider?: ModelProviderName;
+    temperature?: number;
+    maxTokens?: number;
+    requestTimeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    retryMaxDelayMs?: number;
+    debug?: boolean;
+    logLevel?: string;
+    maxHistoryLength?: number;
+}
+export declare class Config {
+    readonly defaultModel: string | undefined;
+    readonly defaultProvider: ModelProviderName | undefined;
+    readonly temperature: number;
+    readonly maxTokens: number | undefined;
+    readonly requestTimeoutMs: number | undefined;
+    readonly maxRetries: number | undefined;
+    readonly retryDelayMs: number | undefined;
+    readonly retryMaxDelayMs: number | undefined;
+    readonly debug: boolean;
+    readonly logLevel: string;
+    readonly maxHistoryLength: number;
+    constructor(options?: ConfigOptions);
+    /**
+     * 环境变量只负责覆盖运行参数。
+     * 如果没有显式 MODEL，就让 LLM provider 使用自己的默认模型。
+     */
+    static fromEnv(): Config;
+    toJSON(): ConfigOptions;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,MAAM;IACf,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;gBAEtB,OAAO,GAAE,aAAkB;IAcvC;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,MAAM;IAuExB,MAAM,IAAI,aAAa;CAgC1B"}