@metad/contracts 3.6.0 → 3.6.1

package/src/ai/xpert-tool.model.ts

@@ -0,0 +1,211 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model'
+import { I18nObject } from '../types'
+import { AiProviderRole } from './copilot.model'
+import { TAvatar } from '../types'
+import { IXpertToolset } from './xpert-toolset.model'
+
+/**
+ * Tools for Xpert
+ */
+export interface IXpertTool extends IBasePerTenantAndOrganizationEntityModel, XpertToolType {}
+
+export type XpertToolType = {
+  name: string
+  description?: string
+  avatar?: TAvatar
+  /**
+   * @deprecated use disabled
+   */
+  enabled?: boolean
+  /**
+   * Is disabled in toolset
+   */
+  disabled?: boolean
+  
+  options?: Record<string, any>
+  /**
+   * Schema of tool
+   */
+  schema?: Record<string, any> | TXpertToolEntity | IBuiltinTool
+  /**
+   * Default input parameters of tool
+   */
+  parameters?: Record<string, any>
+
+  /**
+   * Priority role of AI provider
+   * @default `AiProviderRole.Secondary`
+   */
+  aiProviderRole?: AiProviderRole
+
+  toolset?: IXpertToolset
+  toolsetId?: string
+
+  // Temporary properties
+  provider?: IBuiltinTool
+}
+
+export type TToolProviderIdentity = {
+  name: string
+  author: string
+  label: I18nObject
+  provider: string
+  entity?: string
+}
+
+interface ToolParameterOption {
+  value: string;
+  label: I18nObject;
+}
+
+export enum ToolParameterType {
+  STRING = "string",
+  NUMBER = "number",
+  BOOLEAN = "boolean",
+  ARRAY = "array",
+  SELECT = "select",
+  SECRET_INPUT = "secret-input",
+  FILE = "file"
+}
+
+export enum ToolParameterForm {
+  SCHEMA = "schema",  // should be set while adding tool
+  FORM = "form",      // should be set before invoking tool
+  LLM = "llm"         // will be set by LLM
+}
+
+export type TToolParameter = {
+  name: string;
+  label: I18nObject;
+  human_description?: I18nObject;
+  placeholder?: I18nObject;
+  type: ToolParameterType;
+  form: ToolParameterForm;
+  llm_description?: string;
+  required?: boolean;
+  default?: number | string;
+  min?: number;
+  max?: number;
+  options?: ToolParameterOption[];
+  items?: {
+    type: ToolParameterType
+  }
+
+  /**
+   * Is visible for ai tool parameters
+   */
+  visible?: boolean
+}
+
+export interface ApiToolBundle {
+  /**
+   * This interface is used to store the schema information of an api based tool,
+   * such as the url, the method, the parameters, etc.
+   */
+
+  // server_url
+  server_url: string;
+  // method
+  method: string;
+  // summary
+  summary?: string;
+  // operation_id
+  operation_id?: string;
+  // parameters
+  parameters?: TToolParameter[];
+  // author
+  author: string;
+  // icon
+  icon?: string;
+  // openapi operation
+  openapi: Record<string, any>;
+}
+
+export interface IBuiltinTool {
+  identity: TToolProviderIdentity
+  description: {
+    human: I18nObject
+    llm: string
+  }
+  /**
+   * Definition of input parameters (yaml schema)
+   */
+  parameters?: TToolParameter[]
+  /**
+   * Schema of tool (zod/json-schema)
+   */
+  schema?: any
+  /**
+   * @deprecated how to use?
+   */
+  entity?: string
+}
+
+// Types for OData
+export type TXpertToolEntity = {
+  name: string
+  method: 'create' | 'get' | 'query' | 'update' | 'delete'
+  entity: string
+  path: string
+  /**
+   * Definition of properties
+   */
+  parameters: Partial<TToolParameter>[]
+
+  description?: string
+}
+
+export const TOOL_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+// Helper functions for tools
+/**
+ * 
+ * @param tool Tool
+ * @param disableToolDefault Is default disable tools
+ * @returns Tool is enabled?
+ */
+export function isToolEnabled(tool: IXpertTool, disableToolDefault = false) {
+  let disabled = tool.disabled
+  if (disabled == null && tool.enabled != null) {
+    disabled = !tool.enabled
+  }
+  if (disabled == null) {
+    disabled = disableToolDefault
+  }
+  return !disabled
+}
+
+/**
+ * Tool is enabled?
+ * 
+ * @deprecated use isToolEnabled
+ */
+export function isEnableTool(tool: IXpertTool, toolset: IXpertToolset) {
+  let disabled = tool.disabled
+  if (disabled == null && tool.enabled != null) {
+    disabled = !tool.enabled
+  }
+  if (disabled == null) {
+    disabled = toolset.options?.disableToolDefault
+  }
+  return !disabled
+}
+
+export function getEnabledTools(toolset: IXpertToolset) {
+  if (!toolset) return null
+  const disableToolDefault = toolset.options?.disableToolDefault
+  const positions = toolset?.options?.toolPositions
+  const tools = toolset?.tools?.filter((_) => isToolEnabled(_, disableToolDefault))
+  return positions && tools
+    ? tools.sort((a, b) => (positions[a.name] ?? Infinity) - (positions[b.name] ?? Infinity))
+    : tools
+}
+
+export function getToolLabel(tool: IXpertTool): I18nObject | string {
+  if (!tool) return ''
+  const identity = (tool.schema as IBuiltinTool)?.identity
+  if (identity) {
+    return identity.label || tool.name || ''
+  }
+  return tool.name || ''
+}

package/src/ai/xpert-toolset.model.ts

@@ -0,0 +1,220 @@
+import { AiProviderRole } from './copilot.model'
+import { TAvatar } from '../types'
+import { IXpertTool, XpertToolType } from './xpert-tool.model'
+import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model'
+import { ITag } from '../tag-entity.model'
+import { TCopilotModel } from './copilot-model.model'
+import { Subscriber } from 'rxjs'
+import { I18nObject } from '../types'
+
+
+export enum XpertToolsetCategoryEnum {
+  BUILTIN = 'builtin',
+  API = 'api',
+  /**
+   * [Anthropic Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
+   */
+  MCP = 'mcp',
+  /**
+   * @deprecated
+   */
+  WORKFLOW = 'workflow'
+}
+
+export type XpertToolsetType = string
+export type TXpertToolset = {
+  key?: string
+  /**
+   * toolset name
+   */
+  name: string
+  type?: XpertToolsetType
+  category?: 'command' | XpertToolsetCategoryEnum
+  description?: string
+  /**
+   * avatar object
+   */
+  avatar?: TAvatar
+  /**
+   * Priority role of AI provider
+   * @default `AiProviderRole.Secondary`
+   */
+  aiProviderRole?: AiProviderRole
+
+  /**
+   * Privacy policy of this toolset
+   */
+  privacyPolicy?: string
+  /**
+   * Custom disclaimer for the toolset
+   */
+  customDisclaimer?: string
+
+  options?: TXpertToolsetOptions
+  credentials?: TToolCredentials
+  schema?: string
+  schemaType?: 'openapi_json' | 'openapi_yaml'
+
+  tools?: IXpertTool[]
+
+  tags?: ITag[]
+}
+
+/**
+ * Toolset for Xpert
+ */
+export interface IXpertToolset extends IBasePerWorkspaceEntityModel, TXpertToolset {}
+
+export type TXpertToolsetOptions = {
+  provider?: IToolProvider
+  baseUrl?: string
+  toolPositions?: Record<string, number>
+  disableToolDefault?: boolean
+  needSandbox?: boolean
+  [key: string]: any
+}
+
+/**
+ * Context env when tool call in langchain.js
+ */
+export type XpertToolContext = {
+  tenantId: string
+  organizationId?: string
+  userId: string
+  copilotModel: TCopilotModel
+  chatModel: unknown // BaseChatModel in langchain
+  tool_call_id: string
+  subscriber: Subscriber<MessageEvent>
+}
+
+export enum CredentialsType {
+  SECRET_INPUT = 'secret-input',
+  TEXT_INPUT = 'text-input',
+  SELECT = 'select',
+  REMOTE_SELECT = 'remote-select',
+  COPILOT_MODEL = 'copilot-model',
+  BOOLEAN = 'boolean',
+  INT = 'int',
+  NUMBER = 'number'
+}
+
+export interface ToolCredentialsOption {
+  value: string
+  label: I18nObject | string
+}
+
+export interface ToolProviderCredentials {
+  name: string
+  type: CredentialsType
+  required?: boolean
+  default?: number | string
+  options?: ToolCredentialsOption[]
+  /**
+   * Url for fetch remote select options
+   */
+  selectUrl?: string
+  /**
+   * Is multiple select
+   */
+  multi?: boolean
+  /**
+   * Depends on credentials
+   */
+  depends?: string[]
+  label?: I18nObject
+  help?: I18nObject
+  /**
+   * Url for help document
+   */
+  url?: string
+  placeholder?: I18nObject
+  max?: number
+  config?: Record<string, any>
+}
+
+export enum ApiProviderSchemaType {
+  /**
+   * Enum class for api provider schema type.
+   */
+  OPENAPI = "openapi",
+  SWAGGER = "swagger",
+  OPENAI_PLUGIN = "openai_plugin",
+  OPENAI_ACTIONS = "openai_actions"
+}
+
+export enum ToolTagEnum {
+	SEARCH = 'search',
+	IMAGE = 'image',
+	VIDEOS = 'videos',
+	WEATHER = 'weather',
+	FINANCE = 'finance',
+	DESIGN = 'design',
+	TRAVEL = 'travel',
+	SOCIAL = 'social',
+	NEWS = 'news',
+	MEDICAL = 'medical',
+	PRODUCTIVITY = 'productivity',
+	EDUCATION = 'education',
+	BUSINESS = 'business',
+	ENTERTAINMENT = 'entertainment',
+	UTILITIES = 'utilities',
+	ANALYSIS = 'analysis',
+	SANDBOX = 'sandbox',
+	PROJECT = 'project',
+	AGENT = 'agent',
+	OTHER = 'other'
+}
+
+export interface IToolTag {
+	name: string
+	label: I18nObject
+	icon: string
+  description?: I18nObject
+}
+
+export interface IToolProvider {
+  not_implemented?: boolean
+  pro?: boolean
+  id: string;
+  author: string;
+  name: string; // identifier
+  description: I18nObject;
+  /**
+   * @deprecated use avatar
+   */
+  icon?: string;
+  avatar: TAvatar
+  label: I18nObject; // label
+  help_url?: string
+  type: XpertToolsetCategoryEnum;
+  masked_credentials?: Record<string, any>
+  original_credentials?: Record<string, any>
+  is_team_authorization: boolean
+  allow_delete: boolean
+  tools?: XpertToolType[]
+  tags: ToolTagEnum[];
+}
+
+export type TToolCredentials = Record<string, string | number | boolean | any>
+
+export type TToolsetParams = {
+  tenantId: string
+  organizationId?: string
+  projectId?: string
+	userId?: string
+	xpertId?: string
+  conversationId?: string
+	agentKey?: string
+	signal?: AbortSignal
+	env: Record<string, unknown>
+}
+
+export interface IBaseToolset {
+  toolNamePrefix?: string
+}
+
+export type TProgramToolMessage = {
+  code: string
+	output: string
+  error?: string
+}

package/src/ai/xpert-workflow-task.prompt.ts

@@ -0,0 +1,71 @@
+export const TASK_DESCRIPTION_PREFIX = 
+`Launch a new agent to handle complex, multi-step tasks autonomously. 
+
+Available agent types and the tools they have access to:`
+
+export const TASK_DESCRIPTION_SUFFIX =
+`When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When to use the Agent tool:
+- When you are instructed to execute custom slash commands. Use the Agent tool with the slash command invocation as the entire prompt. The slash command can take arguments. For example: Task(description="Check the file")
+
+When NOT to use the Agent tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
+- If you are searching for a specific term or definition within a known location, use the Glob tool instead, to find the match more quickly
+- If you are searching for content within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+
+Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+4. The agent's outputs should generally be trusted
+5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+
+Example usage:
+
+<example_agent_descriptions>
+"content-reviewer": use this agent after you are done creating significant content or documents
+"greeting-responder": use this agent when to respond to user greetings with a friendly joke
+"research-analyst": use this agent to conduct thorough research on complex topics
+</example_agent_description>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since significant content was created and the task was completed, now use the content-reviewer agent to review the work
+</commentary>
+assistant: Now let me use the content-reviewer agent to review the code
+assistant: Uses the Task tool to launch with the content-reviewer agent 
+</example>
+
+<example>
+user: "Can you help me research the environmental impact of different renewable energy sources and create a comprehensive report?"
+<commentary>
+This is a complex research task that would benefit from using the research-analyst agent to conduct thorough analysis
+</commentary>
+assistant: I'll help you research the environmental impact of renewable energy sources. Let me use the research-analyst agent to conduct comprehensive research on this topic.
+assistant: Uses the Task tool to launch with the research-analyst agent, providing detailed instructions about what research to conduct and what format the report should take
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Task tool to launch with the greeting-responder agent"
+</example>`