@lemoncloud/eureka-agents-api 0.26.108

package/README.md

@@ -0,0 +1,3 @@
+# @lemoncloud/eureka-agents-api
+
+- AI Powered MicroService

package/dist/cores/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * `types.ts`
+ * - common types used in `/cores`
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-06-21 optimized w/ `abstract-services`
+ * @date        2022-06-28 added `Codable` interface for general types.
+ * @date        2023-01-18 optimized with `lemon-core@3.2.4`
+ * @date        2023-02-15 optimized with `lemon-core@3.2.5`
+ * @date        2024-11-14 optimized `IdentityToken`.
+ *
+ * @copyright   (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ * @origin      `@lemoncloud/lemon-templates-api/cores`
+ */
+import { NextIdentity, CoreModel, View, Body } from 'lemon-model';
+export { CoreModel, View, Body };
+/** type: `IdentityTokenSite` */
+export interface IdentityTokenSite {
+    /** site-code (ex: kwonsun) */
+    code?: string;
+    /** name of site (ex: 권선) */
+    name?: string;
+    /** stereo of site (ex: enterprise) */
+    stereo?: string;
+}
+/** type: `IdentityTokenUser` */
+export interface IdentityTokenUser {
+    /** name of user (ex: 홍길동) */
+    name?: string;
+    /** nick of user (ex: 홍사마) */
+    nick?: string;
+    /** (optional) login-id of user */
+    login?: string;
+    /** (optional) email of user */
+    email?: string;
+}
+/** type: `IdentityTokenGroup` */
+export interface IdentityTokenGroup {
+    /** site-code (ex: kwonsun) */
+    code?: string;
+    /** name of site (ex: 권선) */
+    name?: string;
+}
+/**
+ * type: `IdentityToken` (named as `session`)
+ * - 계정토큰(= JWT(IdentityToken))으로, `/refresh`시 AWS Key와 함께 발급됨 (기본, 1일동안 유효함)
+ * - `backend-api`에서 조직/그룹/사용자에 맞게 재설정됨!
+ * - 세션토큰 검사는 `proxy.getCurrentSession()` 이용하기
+ */
+export interface IdentityToken<T = any, U extends IdentityTokenUser = IdentityTokenUser, S extends IdentityTokenSite = IdentityTokenSite, G extends IdentityTokenGroup = IdentityTokenGroup> extends NextIdentity<T> {
+    /**
+     * site-id (= id in `SiteModel(사이트)`)
+     * - `#` 일경우, 특정 site에 엮이지 않음 (무시됨)
+     * - `0000` 일경우, 기본 site 정보로 환경설정에 따름
+     * - 메인 `backend-api` (see `.iss`)에서 관리되는 `site-model`의 id
+     *
+     * @see SiteModel
+     */
+    sid: string;
+    /**
+     * group-id (= id in `GroupModel(그룹)`)
+     * - `group`은 `user`를 물리적 구분으로 나눠서 생각해볼때 이용가능함.
+     *
+     * @see GroupModel
+     */
+    gid: string;
+    /**
+     * user-id (= id in `UserModel(유저)`)
+     * - 메인 `backend-api` (see `.iss`)에서 관리되는 `user-model`의 id.
+     *
+     * @see UserModel
+     */
+    uid: string;
+    /**
+     * auth-id (= id in `AuthModel(인정정보)`)
+     * - 메인 `backend-api` (see `.iss`)에서 관리되는 `auth-model`의 id.
+     * - 인증 정보를 통해서, 로그인의 추가 상세 정보를 알 수 있음.
+     *
+     * @see AuthModel
+     */
+    aid: string;
+    /**
+     * list of roles  (like `user`, `admin`, `super`)
+     */
+    roles: string[];
+    /**
+     * (optional) internal `identity-id` (= delegated identity)
+     * - `.identityId` 는 aws cognito 인증을 통해서, 현재 인증된 `identity-id`를 알 수 있음
+     * - 다만, `delegated`된 경우에는 위임된 id 가 들어감.
+     *
+     * @deprecated 삭제될 예정! @241114
+     */
+    iid?: string;
+    /**
+     * service-name of issuer
+     * ex) `lemon-backend-api`
+     */
+    iss?: string;
+    /** Site Info */
+    Site: S;
+    /** User Info */
+    User: U;
+    /** (optional) Group Info */
+    Group?: G;
+}
+/**
+ * type `ListResult`
+ */
+export interface ListResult<T, R = any> {
+    /**
+     * total searched count
+     */
+    total?: number;
+    /**
+     * max items count in the page
+     */
+    limit?: number;
+    /**
+     * current page number.
+     */
+    page?: number;
+    /**
+     * (optional) time took in sec
+     */
+    took?: number;
+    /**
+     * items searched
+     */
+    list: T[];
+    /**
+     * (optional) aggr list
+     */
+    aggr?: R[];
+}
+export interface AggrKeyCount {
+    /** name of key(or bucket name) */
+    key: string;
+    /** number of count */
+    val: number;
+}
+/**
+ * type `PaginatedListResult`
+ */
+export interface PaginatedListResult<T, R = string> extends ListResult<T, R> {
+    /**
+     * current page
+     */
+    page: number;
+}
+/**
+ * type `ListParam`
+ */
+export interface ListParam {
+    /**
+     * max items count to be fetched
+     */
+    limit?: number;
+    /**
+     * (optional) sorting order
+     *  - 'asc': older first
+     *  - 'desc': newer first
+     *  - string: extended sorting features
+     */
+    sort?: 'asc' | 'desc' | string;
+}
+/**
+ * type `PaginateParam`
+ */
+export interface PaginateParam extends ListParam {
+    /**
+     * page # to fetch (0-indexed)
+     */
+    page?: number;
+    /**
+     * (optional) offset # from start.
+     */
+    offset?: number;
+    /**
+     * (optional) flag to filter by uid
+     */
+    uid?: string;
+    /**
+     * (optional) flag to filter by sid (only for admin role)
+     */
+    sid?: string;
+}
+/**
+ * type `BulkUpdateBody`
+ */
+export interface BulkUpdateBody<T> extends BulkBody<T> {
+    /**
+     * list bulk update model with id
+     */
+    list: T[];
+}
+/**
+ * body data for bulk
+ */
+export interface BulkBody<T> {
+    list: T[];
+}
+/**
+ * list of the selected model-id
+ */
+export interface BodyList<T extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    list: T[];
+}
+/**
+ * type `BulkItemsResult`
+ */
+export interface BulkItemsResult {
+    success: number;
+    failed: number;
+    failedItems: any[];
+}

package/dist/lib/gemini/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `gemini-types.ts`
+ * - common types definitions for gemini service
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2025-11-19 initial version.
+ * @date        2025-11-29 refactoring manager as singleton pattern
+ *
+ * @copyright   (C) lemoncloud.io 2025 - All Rights Reserved.
+ */
+import { GenAIManagerOptions } from '../types';
+/**
+ * type: `GEMINI_LUT`
+ */
+export declare const $LUT_GEMINI: {
+    /** type: EncodingFormat */
+    EncodingFormat: {
+        float: string;
+        base64: string;
+    };
+    /** type: GenRoleType */
+    GenRoleType: {
+        system: string;
+        user: string;
+        assistant: string;
+    };
+    /**
+     * as `GenModelType`
+     */
+    GenModelType: {
+        'gemini-2.5-flash': string;
+        'gemini-3-pro-image-preview': string;
+        'gemini-3.5-pro': string;
+        'gemini-4-pro': string;
+    };
+};
+/**
+ * type: `EncodingFormat`
+ */
+export declare type EncodingFormat = keyof typeof $LUT_GEMINI.EncodingFormat;
+/**
+ * type: `GenRoleType`
+ */
+export declare type GenRoleType = keyof typeof $LUT_GEMINI.GenRoleType;
+/**
+ * type: `GenModelType`
+ */
+export declare type GenModelType = keyof typeof $LUT_GEMINI.GenModelType;
+/**
+ * type: `GeminiManagerOptions`
+ */
+export interface GeminiManagerOptions extends GenAIManagerOptions {
+    /** file (yml) to save the raw response */
+    ymlFile?: string;
+    /** flag to use template (default `true`) */
+    template?: boolean;
+}

package/dist/lib/openai/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `openai-types.ts`
+ * - common types definitions for openai service
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2025-11-19 initial version.
+ * @date        2025-11-29 refactoring manager as singleton pattern
+ *
+ * @copyright   (C) lemoncloud.io 2025 - All Rights Reserved.
+ */
+import { GenAIManagerOptions } from '../types';
+/**
+ * type: `OPENAI_LUT`
+ */
+export declare const $LUT_OPENAI: {
+    /** type: EncodingFormat */
+    EncodingFormat: {
+        float: string;
+        base64: string;
+    };
+    /** type: GenRoleType */
+    GenRoleType: {
+        system: string;
+        user: string;
+        assistant: string;
+    };
+    /**
+     * as `GenModelType`
+     */
+    GenModelType: {
+        'gpt-4o': string;
+        'gpt-4o-mini': string;
+        'gpt-4-turbo': string;
+        'gpt-4': string;
+        'gpt-4.1': string;
+        'gpt-5': string;
+        'gpt-5-mini': string;
+        'gpt-5.1': string;
+        'gpt-3.5-turbo': string;
+    };
+};
+/**
+ * type: `EncodingFormat`
+ */
+export declare type EncodingFormat = keyof typeof $LUT_OPENAI.EncodingFormat;
+/**
+ * type: `GenRoleType`
+ */
+export declare type GenRoleType = keyof typeof $LUT_OPENAI.GenRoleType;
+/**
+ * type: `GenModelType`
+ */
+export declare type GenModelType = keyof typeof $LUT_OPENAI.GenModelType;
+/**
+ * type: `OpenAIManagerOptions`
+ */
+export interface OpenAIManagerOptions extends GenAIManagerOptions {
+    /** flag to save the raw response (default `false`) */
+    isSave?: boolean;
+    /** file (yml) to save the raw response */
+    ymlFile?: string;
+    /** flag to use template (default `true`) */
+    template?: boolean;
+    /** consumer to handle each streaming token */
+    consumer?: (token: string) => Promise<void>;
+}
+/**
+ * type: `TextEmbeddingOption`
+ */
+export interface TextEmbeddingOption {
+    /**
+     * text embedding model
+     * - default is `'text-embedding-3-large'`
+     */
+    embeddingModel?: 'text-embedding-ada-002' | 'text-embedding-3-small' | 'text-embedding-3-large' | string;
+    /**
+     * encoding format of embedding
+     * - default is 'float'
+     */
+    encodingFormat?: 'float' | 'base64';
+    /**
+     * vector dimensions
+     * - default is 1536
+     */
+    dimensions?: number;
+    /**
+     * input
+     * - text or array of texts to be embedded
+     */
+    input?: string | string[];
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `lib/types.ts`
+ * - contains only the hyper types.
+ * - `publish types` 할때, lemon-core 포함을 최소화하기 위한 조치!
+ *
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-10-18 initial version
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * as gemini from './gemini/types';
+export * as openai from './openai/types';
+/**
+ * interface: `GenAIAgentCommon`
+ * - common interface for GenAI agent managers
+ */
+export interface GenAIAgentCommon<
+/** generative LLM model */
+GenModel extends string = string, 
+/** possible content type */
+ContType = string, 
+/** options for the manager */
+Options extends GenAIManagerOptions = GenAIManagerOptions> {
+    /** get the type of the agent (ex: gemini) */
+    type(): string;
+    /** say hello from agent */
+    hello?(): string;
+    /** type check of ChatModelType */
+    asChatModelType(model: string): GenModel;
+    /** load request from sample files */
+    loadSampleRequest(file: string, options?: {
+        path?: string;
+    }): Promise<GenAIRequest<ContType>>;
+    /** convert body to GenAIParams<GenModelType> */
+    asGenAIParams(body: GenAIRequestBody<ContType>): GenAIParams<GenModel>;
+    /** convert body to GenAIRequest<T> */
+    asGenAIRequest(body: GenAIRequestBody<ContType> | GenAIRequest<ContType>): GenAIRequest<ContType>;
+    /**
+     * generate a response
+     *
+     * @param params the generation parameters
+     * @param request the generation request
+     * @param options the generation options
+     * @returns the generation response
+     */
+    generate(params: GenAIParams<GenModel>, request: GenAIRequest<ContType>, options?: Options): Promise<GenAIResponse<ContType>>;
+}
+/**
+ * type: `GenAIManagerOptions`
+ * - options for GenAI manager
+ */
+export interface GenAIManagerOptions {
+    /** flag to save the raw response (default `false`) */
+    isSave?: boolean;
+    /** consumer to handle each streaming token */
+    consumer?: (token: string) => Promise<void>;
+}
+/**
+ * type: `GenAIParams`
+ * - parameter for GenAI execution
+ */
+export interface GenAIParams<GenModel extends string = string> {
+    /** llm model to use */
+    model: GenModel;
+    /**
+     * (optional) temperature
+     * - a number between 0 and 2, where lower values make the output more focused and deterministic,
+     *   while higher values make it more random and creative.
+     * - default is 1.0
+     * - if not set, the default value of the model will be used.
+     */
+    temperature?: number;
+    /**
+     * (optional) topP
+     * - an alternative to sampling with temperature, called nucleus sampling,
+     *   where the model considers the results of the tokens with top P probability mass.
+     * - default is 1.0
+     * - if not set, the default value of the model will be used.
+     */
+    topP?: number;
+    /**
+     * (internal) flag in mockup mode
+     * - if input is like `#1`, then it will be in mockup mode.
+     */
+    isMocks?: boolean;
+}
+/**
+ * type: `GenAIRequest`
+ * - request for GenAI service
+ */
+export interface GenAIRequest<ContType = string> {
+    /** system prompt */
+    system?: GenAIContent<ContType>;
+    /** user input prompt */
+    prompt?: GenAIContent<ContType>;
+}
+/**
+ * the type of `GenAIContent` without `contents`.
+ */
+export interface GenAIContent<ContType = string> {
+    /** (internal) id of content */
+    id?: string;
+    /** (internal) type of content */
+    type?: string;
+    /** (internal) stereo in type */
+    stereo?: string;
+    /** content */
+    content: ContType;
+    /** (optional) embedding vector if stereo=embedding */
+    vector?: number[];
+    /** (optional) embedding dimensions */
+    dimension?: number;
+}
+/**
+ * type: `GenAIContent`
+ * - response for GenAI service
+ */
+export interface GenAIResponse<ContType = string> {
+    /** (optional) original parameter */
+    $param?: GenAIParams;
+    /** output prompt (or answer) */
+    output: GenAIContent<ContType>;
+    /** usage token in detail */
+    usage?: TokenUsageDetail;
+    /** the 1st candidate response (if any) */
+    candidate?: any;
+}
+/**
+ * type: `TokenUsageResponse`
+ */
+export interface TokenUsageDetail {
+    /** prompt token */
+    promptToken?: number;
+    /** completion token */
+    completionToken?: number;
+    /** total token */
+    totalToken?: number;
+    /** image token */
+    imageToken?: number;
+    /** embedding token */
+    embeddingToken?: number;
+    /** vision token */
+    visionToken?: number;
+    /** classification token */
+    classificationToken?: number;
+    /** search token */
+    searchToken?: number;
+}
+/**
+ * type: `GenAIRequestBody`
+ * - request body for GenAI service
+ */
+export interface GenAIRequestBody<ContType = string> {
+    /** system prompt */
+    system?: GenAIContent<ContType> | string;
+    /** user input prompt */
+    prompt?: GenAIContent<ContType> | string;
+    /** (optional) input string if no prompt is provided */
+    input?: string;
+    /**
+     * (optional) model to use
+     */
+    model?: string;
+    /** (optional) temperature */
+    temperature?: string | number;
+    /** (optional) topP */
+    topP?: string | number;
+    /** (optional) additional configuration per agent */
+    config?: object;
+    /**
+     * (optional) websocket connection id
+     * - if provided, the response will be sent via websocket
+     */
+    connectionId?: string;
+}