mirror of
https://github.com/danny-avila/LibreChat.git
synced 2025-12-19 01:40:15 +01:00
🧵 refactor: Migrate Endpoint Initialization to TypeScript (#10794)
* refactor: move endpoint initialization methods to typescript * refactor: move agent init to packages/api - Introduced `initialize.ts` for agent initialization, including file processing and tool loading. - Updated `resources.ts` to allow optional appConfig parameter. - Enhanced endpoint configuration handling in various initialization files to support model parameters. - Added new artifacts and prompts for React component generation. - Refactored existing code to improve type safety and maintainability. * refactor: streamline endpoint initialization and enhance type safety - Updated initialization functions across various endpoints to use a consistent request structure, replacing `unknown` types with `ServerResponse`. - Simplified request handling by directly extracting keys from the request body. - Improved type safety by ensuring user IDs are safely accessed with optional chaining. - Removed unnecessary parameters and streamlined model options handling for better clarity and maintainability. * refactor: moved ModelService and extractBaseURL to packages/api - Added comprehensive tests for the models fetching functionality, covering scenarios for OpenAI, Anthropic, Google, and Ollama models. - Updated existing endpoint index to include the new models module. - Enhanced utility functions for URL extraction and model data processing. - Improved type safety and error handling across the models fetching logic. * refactor: consolidate utility functions and remove unused files - Merged `deriveBaseURL` and `extractBaseURL` into the `@librechat/api` module for better organization. - Removed redundant utility files and their associated tests to streamline the codebase. - Updated imports across various client files to utilize the new consolidated functions. - Enhanced overall maintainability by reducing the number of utility modules. * refactor: replace ModelService references with direct imports from @librechat/api and remove ModelService file * refactor: move encrypt/decrypt methods and key db methods to data-schemas, use `getProviderConfig` from `@librechat/api` * chore: remove unused 'res' from options in AgentClient * refactor: file model imports and methods - Updated imports in various controllers and services to use the unified file model from '~/models' instead of '~/models/File'. - Consolidated file-related methods into a new file methods module in the data-schemas package. - Added comprehensive tests for file methods including creation, retrieval, updating, and deletion. - Enhanced the initializeAgent function to accept dependency injection for file-related methods. - Improved error handling and logging in file methods. * refactor: streamline database method references in agent initialization * refactor: enhance file method tests and update type references to IMongoFile * refactor: consolidate database method imports in agent client and initialization * chore: remove redundant import of initializeAgent from @librechat/api * refactor: move checkUserKeyExpiry utility to @librechat/api and update references across endpoints * refactor: move updateUserPlugins logic to user.ts and simplify UserController * refactor: update imports for user key management and remove UserService * refactor: remove unused Anthropics and Bedrock endpoint files and clean up imports * refactor: consolidate and update encryption imports across various files to use @librechat/data-schemas * chore: update file model mock to use unified import from '~/models' * chore: import order * refactor: remove migrated to TS agent.js file and its associated logic from the endpoints * chore: add reusable function to extract imports from source code in unused-packages workflow * chore: enhance unused-packages workflow to include @librechat/api dependencies and improve dependency extraction * chore: improve dependency extraction in unused-packages workflow with enhanced error handling and debugging output * chore: add detailed debugging output to unused-packages workflow for better visibility into unused dependencies and exclusion lists * chore: refine subpath handling in unused-packages workflow to correctly process scoped and non-scoped package imports * chore: clean up unused debug output in unused-packages workflow and reorganize type imports in initialize.ts
This commit is contained in:
Danny Avila
parent
1a11b64266
commit
04a4a2aa44
103 changed files with 4135 additions and 2647 deletions
315
packages/api/src/agents/initialize.ts
Normal file
315
packages/api/src/agents/initialize.ts
Normal file
|
|
@ -0,0 +1,315 @@
|
|||
import { Providers } from '@librechat/agents';
|
||||
import {
|
||||
ErrorTypes,
|
||||
EModelEndpoint,
|
||||
EToolResources,
|
||||
paramEndpoints,
|
||||
isAgentsEndpoint,
|
||||
replaceSpecialVars,
|
||||
providerEndpointMap,
|
||||
} from 'librechat-data-provider';
|
||||
import type {
|
||||
AgentToolResources,
|
||||
TEndpointOption,
|
||||
TFile,
|
||||
Agent,
|
||||
TUser,
|
||||
} from 'librechat-data-provider';
|
||||
import type { Response as ServerResponse } from 'express';
|
||||
import type { IMongoFile } from '@librechat/data-schemas';
|
||||
import type { GenericTool } from '@librechat/agents';
|
||||
import type { InitializeResultBase, ServerRequest, EndpointDbMethods } from '~/types';
|
||||
import { getModelMaxTokens, extractLibreChatParams, optionalChainWithEmptyCheck } from '~/utils';
|
||||
import { filterFilesByEndpointConfig } from '~/files';
|
||||
import { generateArtifactsPrompt } from '~/prompts';
|
||||
import { getProviderConfig } from '~/endpoints';
|
||||
import { primeResources } from './resources';
|
||||
|
||||
/**
|
||||
* Extended agent type with additional fields needed after initialization
|
||||
*/
|
||||
export type InitializedAgent = Agent & {
|
||||
tools: GenericTool[];
|
||||
attachments: IMongoFile[];
|
||||
toolContextMap: Record<string, unknown>;
|
||||
maxContextTokens: number;
|
||||
useLegacyContent: boolean;
|
||||
resendFiles: boolean;
|
||||
userMCPAuthMap?: Record<string, Record<string, string>>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Parameters for initializing an agent
|
||||
* Matches the CJS signature from api/server/services/Endpoints/agents/agent.js
|
||||
*/
|
||||
export interface InitializeAgentParams {
|
||||
/** Request object */
|
||||
req: ServerRequest;
|
||||
/** Response object */
|
||||
res: ServerResponse;
|
||||
/** Agent to initialize */
|
||||
agent: Agent;
|
||||
/** Conversation ID (optional) */
|
||||
conversationId?: string | null;
|
||||
/** Request files */
|
||||
requestFiles?: IMongoFile[];
|
||||
/** Function to load agent tools */
|
||||
loadTools?: (params: {
|
||||
req: ServerRequest;
|
||||
res: ServerResponse;
|
||||
provider: string;
|
||||
agentId: string;
|
||||
tools: string[];
|
||||
model: string | null;
|
||||
tool_resources: AgentToolResources | undefined;
|
||||
}) => Promise<{
|
||||
tools: GenericTool[];
|
||||
toolContextMap: Record<string, unknown>;
|
||||
userMCPAuthMap?: Record<string, Record<string, string>>;
|
||||
} | null>;
|
||||
/** Endpoint option (contains model_parameters and endpoint info) */
|
||||
endpointOption?: Partial<TEndpointOption>;
|
||||
/** Set of allowed providers */
|
||||
allowedProviders: Set<string>;
|
||||
/** Whether this is the initial agent */
|
||||
isInitialAgent?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Database methods required for agent initialization
|
||||
* Most methods come from data-schemas via createMethods()
|
||||
* getConvoFiles not yet in data-schemas but included here for consistency
|
||||
*/
|
||||
export interface InitializeAgentDbMethods extends EndpointDbMethods {
|
||||
/** Update usage tracking for multiple files */
|
||||
updateFilesUsage: (files: Array<{ file_id: string }>, fileIds?: string[]) => Promise<unknown[]>;
|
||||
/** Get files from database */
|
||||
getFiles: (filter: unknown, sort: unknown, select: unknown, opts?: unknown) => Promise<unknown[]>;
|
||||
/** Get tool files by IDs */
|
||||
getToolFilesByIds: (fileIds: string[], toolSet: Set<EToolResources>) => Promise<unknown[]>;
|
||||
/** Get conversation file IDs */
|
||||
getConvoFiles: (conversationId: string) => Promise<string[] | null>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Initializes an agent for use in requests.
|
||||
* Handles file processing, tool loading, provider configuration, and context token calculations.
|
||||
*
|
||||
* This function is exported from @librechat/api and replaces the CJS version from
|
||||
* api/server/services/Endpoints/agents/agent.js
|
||||
*
|
||||
* @param params - Initialization parameters
|
||||
* @param deps - Optional dependency injection for testing
|
||||
* @returns Promise resolving to initialized agent with tools and configuration
|
||||
* @throws Error if agent provider is not allowed or if required dependencies are missing
|
||||
*/
|
||||
export async function initializeAgent(
|
||||
params: InitializeAgentParams,
|
||||
db?: InitializeAgentDbMethods,
|
||||
): Promise<InitializedAgent> {
|
||||
const {
|
||||
req,
|
||||
res,
|
||||
agent,
|
||||
loadTools,
|
||||
requestFiles = [],
|
||||
conversationId,
|
||||
endpointOption,
|
||||
allowedProviders,
|
||||
isInitialAgent = false,
|
||||
} = params;
|
||||
|
||||
if (!db) {
|
||||
throw new Error('initializeAgent requires db methods to be passed');
|
||||
}
|
||||
|
||||
if (
|
||||
isAgentsEndpoint(endpointOption?.endpoint) &&
|
||||
allowedProviders.size > 0 &&
|
||||
!allowedProviders.has(agent.provider)
|
||||
) {
|
||||
throw new Error(
|
||||
`{ "type": "${ErrorTypes.INVALID_AGENT_PROVIDER}", "info": "${agent.provider}" }`,
|
||||
);
|
||||
}
|
||||
|
||||
let currentFiles: IMongoFile[] | undefined;
|
||||
|
||||
const _modelOptions = structuredClone(
|
||||
Object.assign(
|
||||
{ model: agent.model },
|
||||
agent.model_parameters ?? { model: agent.model },
|
||||
isInitialAgent === true ? endpointOption?.model_parameters : {},
|
||||
),
|
||||
);
|
||||
|
||||
const { resendFiles, maxContextTokens, modelOptions } = extractLibreChatParams(
|
||||
_modelOptions as Record<string, unknown>,
|
||||
);
|
||||
|
||||
const provider = agent.provider;
|
||||
agent.endpoint = provider;
|
||||
|
||||
if (isInitialAgent && conversationId != null && resendFiles) {
|
||||
const fileIds = (await db.getConvoFiles(conversationId)) ?? [];
|
||||
const toolResourceSet = new Set<EToolResources>();
|
||||
for (const tool of agent.tools ?? []) {
|
||||
if (EToolResources[tool as keyof typeof EToolResources]) {
|
||||
toolResourceSet.add(EToolResources[tool as keyof typeof EToolResources]);
|
||||
}
|
||||
}
|
||||
const toolFiles = (await db.getToolFilesByIds(fileIds, toolResourceSet)) as IMongoFile[];
|
||||
if (requestFiles.length || toolFiles.length) {
|
||||
currentFiles = (await db.updateFilesUsage(requestFiles.concat(toolFiles))) as IMongoFile[];
|
||||
}
|
||||
} else if (isInitialAgent && requestFiles.length) {
|
||||
currentFiles = (await db.updateFilesUsage(requestFiles)) as IMongoFile[];
|
||||
}
|
||||
|
||||
if (currentFiles && currentFiles.length) {
|
||||
let endpointType: EModelEndpoint | undefined;
|
||||
if (!paramEndpoints.has(agent.endpoint ?? '')) {
|
||||
endpointType = EModelEndpoint.custom;
|
||||
}
|
||||
|
||||
currentFiles = filterFilesByEndpointConfig(req, {
|
||||
files: currentFiles,
|
||||
endpoint: agent.endpoint ?? '',
|
||||
endpointType,
|
||||
});
|
||||
}
|
||||
|
||||
const { attachments: primedAttachments, tool_resources } = await primeResources({
|
||||
req: req as never,
|
||||
getFiles: db.getFiles as never,
|
||||
appConfig: req.config,
|
||||
agentId: agent.id,
|
||||
attachments: currentFiles
|
||||
? (Promise.resolve(currentFiles) as unknown as Promise<TFile[]>)
|
||||
: undefined,
|
||||
tool_resources: agent.tool_resources,
|
||||
requestFileSet: new Set(requestFiles?.map((file) => file.file_id)),
|
||||
});
|
||||
|
||||
const {
|
||||
tools: structuredTools,
|
||||
toolContextMap,
|
||||
userMCPAuthMap,
|
||||
} = (await loadTools?.({
|
||||
req,
|
||||
res,
|
||||
provider,
|
||||
agentId: agent.id,
|
||||
tools: agent.tools ?? [],
|
||||
model: agent.model,
|
||||
tool_resources,
|
||||
})) ?? { tools: [], toolContextMap: {}, userMCPAuthMap: undefined };
|
||||
|
||||
const { getOptions, overrideProvider } = getProviderConfig({
|
||||
provider,
|
||||
appConfig: req.config,
|
||||
});
|
||||
if (overrideProvider !== agent.provider) {
|
||||
agent.provider = overrideProvider;
|
||||
}
|
||||
|
||||
const finalModelOptions = {
|
||||
...modelOptions,
|
||||
model: agent.model,
|
||||
};
|
||||
|
||||
const options: InitializeResultBase = await getOptions({
|
||||
req,
|
||||
endpoint: provider,
|
||||
model_parameters: finalModelOptions,
|
||||
db,
|
||||
});
|
||||
|
||||
const llmConfig = options.llmConfig as Record<string, unknown>;
|
||||
const tokensModel =
|
||||
agent.provider === EModelEndpoint.azureOpenAI ? agent.model : (llmConfig?.model as string);
|
||||
const maxOutputTokens = optionalChainWithEmptyCheck(
|
||||
llmConfig?.maxOutputTokens as number | undefined,
|
||||
llmConfig?.maxTokens as number | undefined,
|
||||
0,
|
||||
);
|
||||
const agentMaxContextTokens = optionalChainWithEmptyCheck(
|
||||
maxContextTokens,
|
||||
getModelMaxTokens(
|
||||
tokensModel ?? '',
|
||||
providerEndpointMap[provider as keyof typeof providerEndpointMap],
|
||||
options.endpointTokenConfig,
|
||||
),
|
||||
18000,
|
||||
);
|
||||
|
||||
if (
|
||||
agent.endpoint === EModelEndpoint.azureOpenAI &&
|
||||
(llmConfig?.azureOpenAIApiInstanceName as string | undefined) == null
|
||||
) {
|
||||
agent.provider = Providers.OPENAI;
|
||||
}
|
||||
|
||||
if (options.provider != null) {
|
||||
agent.provider = options.provider;
|
||||
}
|
||||
|
||||
let tools: GenericTool[] = options.tools?.length
|
||||
? (options.tools as GenericTool[])
|
||||
: structuredTools;
|
||||
if (
|
||||
(agent.provider === Providers.GOOGLE || agent.provider === Providers.VERTEXAI) &&
|
||||
options.tools?.length &&
|
||||
structuredTools?.length
|
||||
) {
|
||||
throw new Error(`{ "type": "${ErrorTypes.GOOGLE_TOOL_CONFLICT}"}`);
|
||||
} else if (
|
||||
(agent.provider === Providers.OPENAI ||
|
||||
agent.provider === Providers.AZURE ||
|
||||
agent.provider === Providers.ANTHROPIC) &&
|
||||
options.tools?.length &&
|
||||
structuredTools?.length
|
||||
) {
|
||||
tools = structuredTools.concat(options.tools as GenericTool[]);
|
||||
}
|
||||
|
||||
agent.model_parameters = { ...options.llmConfig } as Agent['model_parameters'];
|
||||
if (options.configOptions) {
|
||||
(agent.model_parameters as Record<string, unknown>).configuration = options.configOptions;
|
||||
}
|
||||
|
||||
if (agent.instructions && agent.instructions !== '') {
|
||||
agent.instructions = replaceSpecialVars({
|
||||
text: agent.instructions,
|
||||
user: req.user ? (req.user as unknown as TUser) : null,
|
||||
});
|
||||
}
|
||||
|
||||
if (typeof agent.artifacts === 'string' && agent.artifacts !== '') {
|
||||
const artifactsPromptResult = generateArtifactsPrompt({
|
||||
endpoint: agent.provider,
|
||||
artifacts: agent.artifacts as never,
|
||||
});
|
||||
agent.additional_instructions = artifactsPromptResult ?? undefined;
|
||||
}
|
||||
|
||||
const agentMaxContextNum = Number(agentMaxContextTokens) || 18000;
|
||||
const maxOutputTokensNum = Number(maxOutputTokens) || 0;
|
||||
|
||||
const finalAttachments: IMongoFile[] = (primedAttachments ?? [])
|
||||
.filter((a): a is TFile => a != null)
|
||||
.map((a) => a as unknown as IMongoFile);
|
||||
|
||||
const initializedAgent: InitializedAgent = {
|
||||
...agent,
|
||||
tools: (tools ?? []) as GenericTool[] & string[],
|
||||
attachments: finalAttachments,
|
||||
resendFiles,
|
||||
userMCPAuthMap,
|
||||
toolContextMap: toolContextMap ?? {},
|
||||
useLegacyContent: !!options.useLegacyContent,
|
||||
maxContextTokens: Math.round((agentMaxContextNum - maxOutputTokensNum) * 0.9),
|
||||
};
|
||||
|
||||
return initializedAgent;
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue