@axiom-lattice/protocols 1.0.1

package/src/AgentLatticeProtocol.ts

@@ -0,0 +1,60 @@
+/**
+ * AgentLatticeProtocol
+ *
+ * 智能体Lattice的协议，定义了智能体的行为和组合方式
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { ZodSchema } from "zod";
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * 智能体类型枚举
+ */
+export enum AgentType {
+  REACT = "react",
+  DEEP_AGENT = "deep_agent",
+  PLAN_EXECUTE = "plan_execute",
+  SEQUENTIAL = "sequential",
+}
+
+/**
+ * 智能体配置接口
+ */
+export interface AgentConfig {
+  key: string; // 唯一键
+  name: string; // 名称
+  description: string; // 描述
+  type: AgentType; // 智能体类型
+  tools?: string[]; // 使用的工具列表
+  subAgents?: string[]; // 子智能体列表
+  prompt: string; // 提示词
+  schema?: ZodSchema<any>; // 输入验证模式
+  modelKey?: string; // 使用的模型键
+}
+
+/**
+ * 智能体客户端类型
+ */
+export type AgentClient = CompiledStateGraph<any, any, any, any, any>;
+
+/**
+ * Graph构建选项
+ */
+export interface GraphBuildOptions {
+  overrideTools?: string[];
+  overrideModel?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * 智能体Lattice协议接口
+ */
+export interface AgentLatticeProtocol
+  extends BaseLatticeProtocol<AgentConfig, AgentClient> {
+  // 智能体执行函数
+  invoke: (input: any, options?: any) => Promise<any>;
+
+  // 构建智能体图
+  buildGraph: (options?: GraphBuildOptions) => Promise<AgentClient>;
+}

package/src/BaseLatticeProtocol.ts

@@ -0,0 +1,59 @@
+/**
+ * BaseLatticeProtocol
+ *
+ * 所有Lattice类型的基础协议，定义了通用接口和行为
+ */
+
+/**
+ * 基础Lattice协议接口
+ * @template TConfig 配置类型
+ * @template TClient 客户端类型
+ */
+export interface BaseLatticeProtocol<TConfig = any, TClient = any> {
+  // 唯一标识符
+  key: string;
+
+  // 配置信息
+  config: TConfig;
+
+  // 实际执行客户端
+  client: TClient;
+}
+
+/**
+ * Lattice消息接口
+ */
+export interface LatticeMessage {
+  type: string; // 消息类型
+  source: string; // 源Lattice ID
+  target?: string; // 目标Lattice ID (可选)
+  payload: any; // 消息内容
+  timestamp: number; // 时间戳
+  metadata?: Record<string, any>; // 元数据
+}
+
+/**
+ * Lattice错误接口
+ */
+export interface LatticeError {
+  code: string; // 错误代码
+  message: string; // 错误信息
+  source: string; // 错误源
+  stack?: string; // 堆栈跟踪
+  metadata?: Record<string, any>; // 元数据
+}
+
+/**
+ * Lattice事件总线接口
+ */
+export interface LatticeEventBus {
+  subscribe: (
+    eventType: string,
+    handler: (message: LatticeMessage) => void
+  ) => void;
+  unsubscribe: (
+    eventType: string,
+    handler: (message: LatticeMessage) => void
+  ) => void;
+  publish: (eventType: string, message: LatticeMessage) => void;
+}

package/src/MemoryLatticeProtocol.ts

@@ -0,0 +1,55 @@
+/**
+ * MemoryLatticeProtocol
+ *
+ * 记忆Lattice的协议，用于管理智能体的上下文和记忆
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * 记忆类型枚举
+ */
+export enum MemoryType {
+  SHORT_TERM = "short_term",
+  LONG_TERM = "long_term",
+  EPISODIC = "episodic",
+  SEMANTIC = "semantic",
+  WORKING = "working",
+}
+
+/**
+ * 记忆配置接口
+ */
+export interface MemoryConfig {
+  name: string; // 名称
+  description: string; // 描述
+  type: MemoryType; // 记忆类型
+  ttl?: number; // 生存时间
+  capacity?: number; // 容量限制
+}
+
+/**
+ * 记忆客户端接口
+ */
+export interface MemoryClient {
+  add: (key: string, value: any) => Promise<void>;
+  get: (key: string) => Promise<any>;
+  update: (key: string, value: any) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  search: (query: string, options?: any) => Promise<any[]>;
+  clear: () => Promise<void>;
+}
+
+/**
+ * 记忆Lattice协议接口
+ */
+export interface MemoryLatticeProtocol
+  extends BaseLatticeProtocol<MemoryConfig, MemoryClient> {
+  // 记忆操作方法
+  add: (key: string, value: any) => Promise<void>;
+  get: (key: string) => Promise<any>;
+  update: (key: string, value: any) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  search: (query: string, options?: any) => Promise<any[]>;
+  clear: () => Promise<void>;
+}

package/src/MessageProtocol.ts

@@ -0,0 +1,108 @@
+/**
+ * MessageProtocol
+ *
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * Base message interface
+ */
+export interface BaseMessage {
+  id: string; // Unique identifier for the message
+  role: string; // Role of the sender (user, assistant, system, tool, developer)
+  content?: string; // Optional text content of the message
+  name?: string; // Optional name of the sender
+}
+
+/**
+ * User message interface
+ */
+export interface UserMessage extends BaseMessage {
+  role: "human";
+  content: string; // Text input from the user
+  files?: Array<{ name: string; id: string }>; // Optional files attached to the message
+}
+
+/**
+ * Tool call interface
+ */
+export interface ToolCall {
+  id: string; // Unique identifier for this tool call
+  name: string; // Name of the tool/function to call
+  args: Record<string, any>; // Arguments as an object
+  type: "tool_call"; // Type of tool call
+  response?: string; // Optional response from the tool execution
+}
+
+/**
+ * Assistant message interface
+ */
+export interface AssistantMessage extends BaseMessage {
+  role: "ai";
+  content?: string; // Text response from the assistant (optional if using tool calls)
+  tool_calls?: ToolCall[]; // Optional tool calls made by the assistant
+}
+
+/**
+ * System message interface
+ */
+export interface SystemMessage extends BaseMessage {
+  role: "system";
+  content: string; // Instructions or context for the assistant
+}
+
+/**
+ * Tool message interface
+ */
+export interface ToolMessage extends BaseMessage {
+  role: "tool";
+  content: string; // Result from the tool execution
+  tool_call_id: string; // ID of the tool call this message responds to
+}
+
+/**
+ * Developer message interface
+ */
+export interface DeveloperMessage extends BaseMessage {
+  role: "developer";
+  content: string; // Content for development or debugging
+}
+
+export interface MessageChunk {
+  type: string;
+  data: {
+    id: string;
+    content?: string;
+    tool_call_chunks?: Array<{
+      name?: string;
+      args?: string;
+      id?: string;
+      index: number;
+    }>;
+    tool_calls?: Array<{
+      name: string;
+      args: Record<string, any>;
+      id: string;
+      type: string;
+      response?: string;
+    }>;
+    additional_kwargs?: {
+      tool_calls?: Array<{
+        function?: { name?: string; arguments?: any };
+        id?: string;
+      }>;
+    };
+    tool_call_id?: string;
+  };
+}
+
+/**
+ * Message type union
+ */
+export type Message =
+  | UserMessage
+  | AssistantMessage
+  | SystemMessage
+  | ToolMessage
+  | DeveloperMessage;

package/src/ModelLatticeProtocol.ts

@@ -0,0 +1,45 @@
+/**
+ * ModelLatticeProtocol
+ *
+ * 模型Lattice的协议，用于封装各种LLM模型的统一接口
+ */
+
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { BaseMessage } from "@langchain/core/messages";
+import { ChatResult } from "@langchain/core/outputs";
+import { ZodSchema } from "zod";
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * LLM配置接口
+ */
+export interface LLMConfig {
+  provider: "azure" | "openai" | "deepseek" | "siliconcloud" | "volcengine";
+  model: string;
+  maxTokens?: number;
+  temperature?: number;
+  timeout?: number;
+  maxRetries?: number;
+  streaming?: boolean;
+  apiKeyEnvName?: string;
+  baseURL?: string;
+}
+
+/**
+ * 模型Lattice协议接口
+ */
+export interface ModelLatticeProtocol
+  extends BaseLatticeProtocol<LLMConfig, BaseChatModel> {
+  // 模型调用方法
+  generate: (messages: BaseMessage[], options?: any) => Promise<ChatResult>;
+
+  // 结构化输出调用
+  invokeWithStructuredOutput: <T>(
+    input: any,
+    schema: ZodSchema<T>,
+    options?: any
+  ) => Promise<T>;
+
+  // 绑定工具
+  bindTools: (tools: any[], options?: any) => any;
+}

package/src/StorageLatticeProtocol.ts

@@ -0,0 +1,55 @@
+/**
+ * StorageLatticeProtocol
+ *
+ * 存储Lattice的协议，用于数据持久化和状态管理
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * 存储类型枚举
+ */
+export enum StorageType {
+  MEMORY = "memory",
+  LOCAL = "local",
+  DATABASE = "database",
+  CLOUD = "cloud",
+  DISTRIBUTED = "distributed",
+}
+
+/**
+ * 存储配置接口
+ */
+export interface StorageConfig {
+  name: string; // 名称
+  description: string; // 描述
+  type: StorageType; // 存储类型
+  connectionString?: string; // 连接字符串
+  options?: Record<string, any>; // 其他选项
+}
+
+/**
+ * 存储客户端接口
+ */
+export interface StorageClient {
+  set: (key: string, value: any) => Promise<void>;
+  get: (key: string) => Promise<any>;
+  has: (key: string) => Promise<boolean>;
+  delete: (key: string) => Promise<boolean>;
+  clear: () => Promise<void>;
+  transaction: <T>(operations: () => Promise<T>) => Promise<T>;
+}
+
+/**
+ * 存储Lattice协议接口
+ */
+export interface StorageLatticeProtocol
+  extends BaseLatticeProtocol<StorageConfig, StorageClient> {
+  // 存储操作方法
+  set: (key: string, value: any) => Promise<void>;
+  get: (key: string) => Promise<any>;
+  has: (key: string) => Promise<boolean>;
+  delete: (key: string) => Promise<boolean>;
+  clear: () => Promise<void>;
+  transaction: <T>(operations: () => Promise<T>) => Promise<T>;
+}

package/src/ToolLatticeProtocol.ts

@@ -0,0 +1,40 @@
+/**
+ * ToolLatticeProtocol
+ *
+ * 工具Lattice的协议，用于定义可执行的功能单元
+ */
+
+import { StructuredTool } from "@langchain/core/tools";
+import { ZodSchema } from "zod";
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * 工具配置接口
+ */
+export interface ToolConfig {
+  name: string; // 工具名称
+  description: string; // 工具描述
+  schema?: ZodSchema<any>; // 输入参数验证模式
+  returnDirect?: boolean; // 是否直接返回结果
+  needUserApprove?: boolean; // 是否需要用户确认
+}
+
+/**
+ * 工具执行函数类型
+ */
+export type ToolExecutor<TInput = any, TOutput = any> = (
+  input: TInput,
+  config?: any
+) => Promise<TOutput>;
+
+/**
+ * 工具Lattice协议接口
+ */
+export interface ToolLatticeProtocol
+  extends BaseLatticeProtocol<ToolConfig, StructuredTool> {
+  // 工具执行函数
+  execute: ToolExecutor;
+
+  // 验证工具输入
+  validate: (input: any) => boolean;
+}

package/src/UILatticeProtocol.ts

@@ -0,0 +1,57 @@
+/**
+ * UILatticeProtocol
+ *
+ * UI Lattice的协议，用于定义用户界面组件
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * UI组件类型枚举
+ */
+export enum UIComponentType {
+  CONTAINER = "container",
+  INPUT = "input",
+  BUTTON = "button",
+  LIST = "list",
+  TABLE = "table",
+  CHART = "chart",
+  FORM = "form",
+  CARD = "card",
+  MODAL = "modal",
+  CUSTOM = "custom",
+}
+
+/**
+ * UI配置接口
+ */
+export interface UIConfig {
+  name: string; // 组件名称
+  description: string; // 组件描述
+  type: UIComponentType; // 组件类型
+  props?: Record<string, any>; // 组件属性
+  children?: string[]; // 子组件列表
+}
+
+/**
+ * UI组件接口
+ * 使用泛型以适应不同的UI框架(React, Vue等)
+ */
+export interface UIComponent<T = any> {
+  render: (props?: any) => T;
+  addEventListener: (event: string, handler: Function) => void;
+  removeEventListener: (event: string, handler: Function) => void;
+}
+
+/**
+ * UI Lattice协议接口
+ */
+export interface UILatticeProtocol<T = any>
+  extends BaseLatticeProtocol<UIConfig, UIComponent<T>> {
+  // UI渲染方法
+  render: (props?: any) => T;
+
+  // 事件处理
+  addEventListener: (event: string, handler: Function) => void;
+  removeEventListener: (event: string, handler: Function) => void;
+}

package/src/examples/MessageProtocolExample.ts

@@ -0,0 +1,183 @@
+/**
+ * MessageProtocol Example
+ *
+ * Demonstrates how to use MessageProtocol for message interaction
+ */
+
+import {
+  Message,
+  UserMessage,
+  AssistantMessage,
+  SystemMessage,
+  ToolMessage,
+  ToolCall,
+  MessageEventType,
+  MessagesSnapshotEvent,
+} from "../MessageProtocol";
+
+// Example 1: Basic message interaction
+function basicMessageExample() {
+  // Create a simple conversation
+  const conversation: Message[] = [
+    // System message
+    {
+      id: "sys_1",
+      role: "system",
+      content: "You are a helpful AI assistant.",
+    },
+
+    // User message
+    {
+      id: "user_1",
+      role: "user",
+      content: "Can you help me check the weather in New York?",
+    },
+
+    // Assistant message (with tool call)
+    {
+      id: "asst_1",
+      role: "assistant",
+      content: "Let me check the weather for you.",
+      toolCalls: [
+        {
+          id: "tool_call_1",
+          type: "function",
+          function: {
+            name: "get_weather",
+            arguments: '{"location": "New York", "unit": "celsius"}',
+          },
+        },
+      ],
+    },
+
+    // Tool message (tool execution result)
+    {
+      id: "tool_1",
+      role: "tool",
+      content:
+        '{"temperature": 22, "condition": "Partly Cloudy", "humidity": 65}',
+      toolCallId: "tool_call_1",
+    },
+
+    // Assistant final response
+    {
+      id: "asst_2",
+      role: "assistant",
+      content:
+        "The weather in New York is partly cloudy with a temperature of 22°C and 65% humidity.",
+    },
+  ];
+
+  return conversation;
+}
+
+// Example 2: Message conversion (vendor neutrality)
+function vendorNeutralityExample() {
+  const agUiMessages = basicMessageExample();
+
+  // Convert to OpenAI format
+  const openaiMessages = agUiMessages
+    .filter((msg) => ["user", "system", "assistant"].includes(msg.role))
+    .map((msg) => ({
+      role: msg.role as "user" | "system" | "assistant",
+      content: msg.content || "",
+      // Map tool calls if present
+      ...(msg.role === "assistant" && (msg as AssistantMessage).toolCalls
+        ? {
+            tool_calls: (msg as AssistantMessage).toolCalls?.map((tc) => ({
+              id: tc.id,
+              type: tc.type,
+              function: {
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+              },
+            })),
+          }
+        : {}),
+    }));
+
+  return { agUiMessages, openaiMessages };
+}
+
+// Example 3: Message event handling
+function messageEventsExample() {
+  // Message snapshot event
+  const snapshotEvent: MessagesSnapshotEvent = {
+    type: MessageEventType.MESSAGES_SNAPSHOT,
+    messages: basicMessageExample(),
+  };
+
+  // Handle events
+  function handleEvent(event: any) {
+    switch (event.type) {
+      case MessageEventType.MESSAGES_SNAPSHOT:
+        console.log(
+          "Received message snapshot with",
+          event.messages.length,
+          "messages"
+        );
+        break;
+      case MessageEventType.TEXT_MESSAGE_START:
+        console.log(
+          "New message started:",
+          event.messageId,
+          "role:",
+          event.role
+        );
+        break;
+      case MessageEventType.TEXT_MESSAGE_CONTENT:
+        console.log("Message content:", event.messageId, "delta:", event.delta);
+        break;
+      case MessageEventType.TEXT_MESSAGE_END:
+        console.log("Message ended:", event.messageId);
+        break;
+      // Other event handling...
+    }
+  }
+
+  // Simulate event handling
+  handleEvent(snapshotEvent);
+}
+
+// Example 4: Streaming message handling
+function streamingMessageExample() {
+  // Simulate streaming message processing
+  const messageId = "stream_msg_1";
+  const chunks = [
+    "Hello",
+    ", I am ",
+    "an AI assistant",
+    ". How ",
+    "can I help ",
+    "you today?",
+  ];
+
+  // Start message
+  console.log({
+    type: MessageEventType.TEXT_MESSAGE_START,
+    messageId,
+    role: "assistant",
+  });
+
+  // Stream content
+  chunks.forEach((chunk) => {
+    console.log({
+      type: MessageEventType.TEXT_MESSAGE_CONTENT,
+      messageId,
+      delta: chunk,
+    });
+  });
+
+  // End message
+  console.log({
+    type: MessageEventType.TEXT_MESSAGE_END,
+    messageId,
+  });
+}
+
+export {
+  basicMessageExample,
+  vendorNeutralityExample,
+  messageEventsExample,
+  streamingMessageExample,
+};

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Protocols
+ *
+ * 导出所有Lattice协议接口，为整个系统提供统一的接口规范
+ */
+
+export * from "./BaseLatticeProtocol";
+export * from "./ToolLatticeProtocol";
+export * from "./ModelLatticeProtocol";
+export * from "./AgentLatticeProtocol";
+export * from "./MemoryLatticeProtocol";
+export * from "./StorageLatticeProtocol";
+export * from "./UILatticeProtocol";
+export * from "./MessageProtocol";
+
+// 导出通用类型
+export * from "./types";