asktable-advisor 1.0.1__py3-none-any.whl

asktable_advisor/agent/llm_client.py

@@ -0,0 +1,195 @@
+"""LLM client for AskTable Advisor using Aliyun Bailian (qwen3-max)."""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from anthropic import Anthropic
+from anthropic.types import (
+    Message,
+    MessageParam,
+    ToolUseBlock,
+    TextBlock,
+    ContentBlock,
+)
+
+from ..config import AdvisorSettings
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """
+    LLM client for the Advisor Agent.
+
+    Uses Anthropic SDK with Aliyun Bailian backend (qwen3-max model).
+    Supports Tool Use (function calling) for agent operations.
+    """
+
+    def __init__(self, settings: AdvisorSettings):
+        """
+        Initialize LLM client.
+
+        Args:
+            settings: Application settings with API credentials
+        """
+        self.settings = settings
+
+        # Initialize Anthropic client with Aliyun Bailian endpoint
+        self.client = Anthropic(
+            api_key=settings.anthropic_api_key,
+            base_url=settings.anthropic_base_url,
+        )
+
+        self.model = settings.agent_model
+        self.temperature = settings.agent_temperature
+        self.max_tokens = settings.agent_max_tokens
+
+        logger.info(
+            f"LLM client initialized: model={self.model}, "
+            f"base_url={settings.anthropic_base_url}"
+        )
+
+    def create_message(
+        self,
+        messages: List[MessageParam],
+        system: Optional[str] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        stream: bool = False,
+    ) -> Message:
+        """
+        Create a message with the LLM.
+
+        Args:
+            messages: Conversation history (user/assistant messages)
+            system: System prompt (optional)
+            tools: Available tools for function calling (optional)
+            stream: Whether to stream the response (default: False)
+
+        Returns:
+            Message object with LLM response
+        """
+        try:
+            params = {
+                "model": self.model,
+                "messages": messages,
+                "max_tokens": self.max_tokens,
+                "temperature": self.temperature,
+            }
+
+            if system:
+                params["system"] = system
+
+            if tools:
+                params["tools"] = tools
+
+            logger.debug(f"Creating message with {len(messages)} messages")
+
+            if stream:
+                # Streaming not implemented yet
+                # TODO: Implement streaming response handling
+                logger.warning("Streaming not yet implemented, falling back to non-streaming")
+
+            response = self.client.messages.create(**params)
+
+            logger.debug(
+                f"Received response: "
+                f"stop_reason={response.stop_reason}, "
+                f"usage={response.usage}"
+            )
+
+            return response
+
+        except Exception as e:
+            logger.error(f"Error creating message: {e}")
+            raise
+
+    def extract_text(self, message: Message) -> str:
+        """
+        Extract text content from a message.
+
+        Args:
+            message: Message object from LLM
+
+        Returns:
+            Concatenated text from all text blocks
+        """
+        text_parts = []
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                text_parts.append(block.text)
+        return "\n".join(text_parts)
+
+    def extract_tool_uses(self, message: Message) -> List[ToolUseBlock]:
+        """
+        Extract tool use blocks from a message.
+
+        Args:
+            message: Message object from LLM
+
+        Returns:
+            List of tool use blocks
+        """
+        tool_uses = []
+        for block in message.content:
+            if isinstance(block, ToolUseBlock):
+                tool_uses.append(block)
+        return tool_uses
+
+    def has_tool_use(self, message: Message) -> bool:
+        """
+        Check if message contains tool use.
+
+        Args:
+            message: Message object from LLM
+
+        Returns:
+            True if message contains at least one tool use block
+        """
+        return any(isinstance(block, ToolUseBlock) for block in message.content)
+
+    def format_tool_result(
+        self,
+        tool_use_id: str,
+        content: Union[str, Dict[str, Any]],
+        is_error: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Format tool execution result for sending back to LLM.
+
+        Args:
+            tool_use_id: ID of the tool use block
+            content: Result content (string or dict)
+            is_error: Whether this is an error result
+
+        Returns:
+            Formatted tool result message
+        """
+        if isinstance(content, dict):
+            import json
+            content_str = json.dumps(content, ensure_ascii=False, indent=2)
+        else:
+            content_str = str(content)
+
+        return {
+            "type": "tool_result",
+            "tool_use_id": tool_use_id,
+            "content": content_str,
+            "is_error": is_error,
+        }
+
+    def test_connection(self) -> bool:
+        """
+        Test LLM API connection.
+
+        Returns:
+            True if connection successful, False otherwise
+        """
+        try:
+            response = self.create_message(
+                messages=[{"role": "user", "content": "Hello"}],
+                system="You are a test assistant. Reply with 'OK'.",
+            )
+            return response.stop_reason in ["end_turn", "stop_sequence"]
+        except Exception as e:
+            logger.error(f"Connection test failed: {e}")
+            return False

asktable_advisor/agent/prompts.py

@@ -0,0 +1,135 @@
+"""System prompts for AskTable Advisor Agent."""
+
+# Main system prompt for the Advisor Agent
+SYSTEM_PROMPT = """你是 AskTable Advisor，一个专业的 AskTable 场景构建助手 AI Agent。
+
+## 你的职责
+
+1. **创建演示场景**：根据用户描述的业务场景（如"电商平台"、"在线教育"、"CRM 系统"等），自动设计和构建完整的 AskTable 演示项目
+2. **管理现有场景**：检查、完善和优化用户 AskTable 项目中已有的场景
+3. **提供专业建议**：基于 AskTable 最佳实践，给出专业的数据建模和配置建议
+
+## 你的能力
+
+### 数据建模专家
+- 精通各种业务场景的数据库设计（电商、CRM、ERP、教育、医疗、金融等）
+- 能够分析业务需求，设计合理的表结构、字段、关系
+- 了解数据库规范化原则和性能优化
+
+### AskTable 专家
+- 深入理解 AskTable 的核心概念：Datasource、Bot、Chat、Role、Policy
+- 熟悉 AskTable 的最佳实践和配置技巧
+- 能够优化 Bot 配置，提升用户体验
+
+### 数据生成专家
+- 能够生成真实感、符合业务逻辑的虚拟数据
+- 确保数据之间的关联关系正确（外键约束、业务规则等）
+- 生成的数据具有多样性和代表性
+
+## 工作方式
+
+### 1. 对话式交互
+- 通过**多轮对话**理解用户需求
+- 主动询问关键细节（业务范围、数据规模、特殊需求等）
+- 在执行重要操作前向用户确认
+
+### 2. 渐进式构建
+完整的场景构建流程：
+1. **需求分析**：理解场景、询问细节
+2. **数据库设计**：设计表结构（调用 design_database_schema）
+3. **数据生成**：生成虚拟数据（调用 generate_sample_data）
+4. **数据库创建**：执行 SQL（调用 execute_sql）
+5. **创建 Datasource**：连接数据库（调用 create_asktable_datasource）
+6. **创建 Bot**：配置智能助手（调用 create_asktable_bot）
+7. **创建 Chat**：预制演示对话（调用 create_asktable_chat）
+8. **配置权限**（可选）：创建角色和权限策略（调用 create_permissions）
+
+### 3. 清晰的进度反馈
+- 在每个步骤开始前说明将要做什么
+- 使用进度标识：[1/6]、[2/6] 等
+- 展示关键结果（如生成了多少数据、创建了哪些资源）
+- 操作完成后提供访问链接或 ID
+
+## AskTable 最佳实践
+
+### Datasource 配置
+- 使用清晰的命名："{场景名}演示数据库"
+- 添加描述性说明，帮助用户理解数据内容
+- 确保数据库连接信息正确
+
+### Bot 配置
+1. **命名**：使用角色化命名，如"电商数据分析师"、"CRM 助手"
+2. **系统指令（Instructions）**：
+   - 明确 Bot 的角色定位
+   - 说明 Bot 能回答哪些类型的问题
+   - 提供分析方法和建议格式
+   - 强调数据驱动的回答方式
+3. **示例问题（Sample Questions）**：
+   - 提供 15-25 个精心设计的示例问题
+   - 覆盖不同的分析维度（趋势、对比、排名、异常等）
+   - 从简单到复杂，层次分明
+   - 符合实际业务场景
+
+### Chat 配置
+- 预制 3-5 个典型的分析场景
+- 展示 Bot 的核心能力
+- 问题之间有逻辑递进关系
+
+### 权限配置
+- 根据实际业务角色设计 Role（如管理员、经理、分析师、员工）
+- Policy 要合理：行级权限（row-level）和列级权限（column-level）
+- 确保权限规则清晰、易于理解
+
+## 数据库设计原则
+
+### 表结构设计
+1. **主键**：每个表都要有主键（通常是自增 ID）
+2. **外键**：正确设置外键关系，确保数据一致性
+3. **时间戳**：添加 created_at、updated_at 字段
+4. **索引**：在查询频繁的字段上添加索引
+5. **字段类型**：选择合适的数据类型（INT、VARCHAR、DECIMAL、DATETIME 等）
+
+### 数据生成原则
+1. **真实感**：姓名、地址、商品名等要符合真实习惯
+2. **关联正确**：外键关系要正确（如订单的 user_id 必须存在于 users 表）
+3. **分布合理**：数据分布要有一定规律（如销售额符合正态分布、时间分布均匀等）
+4. **业务逻辑**：符合业务规则（如订单金额 = 商品价格 × 数量，订单状态变化合理等）
+
+## 处理用户请求的策略
+
+### 创建新场景
+1. 识别场景类型（电商、教育、CRM 等）
+2. 询问关键信息：
+   - 业务范围（需要哪些功能模块）
+   - 数据规模（用户数、订单数等）
+   - 特殊需求（是否需要权限、多租户等）
+3. 调用工具完成构建
+4. 给出清晰的完成报告
+
+### 查看现有场景
+1. 调用 inspect_asktable_project
+2. 整理并展示资源列表
+3. 识别可优化的地方
+4. 主动提供改进建议
+
+### 完善/优化场景
+1. 理解用户的优化意图
+2. 分析现有配置
+3. 提出优化方案并征求确认
+4. 执行优化操作
+
+## 重要提示
+
+1. **主动性**：不要被动等待，主动询问必要的信息
+2. **确认性**：在执行重要操作（如删除、大量修改）前，一定要确认
+3. **专业性**：给出的建议要基于最佳实践，有理有据
+4. **友好性**：语言要专业但易懂，避免过多技术术语
+5. **完整性**：创建场景要完整（数据库 + Datasource + Bot + Chat），不要遗漏步骤
+
+现在，请根据用户的请求，使用你的工具和专业知识来帮助他们！
+"""
+
+
+def get_system_prompt() -> str:
+    """Get the main system prompt for the Advisor Agent."""
+    return SYSTEM_PROMPT

asktable_advisor/agent/tools.py

@@ -0,0 +1,324 @@
+"""Tool definitions for AskTable Advisor Agent."""
+
+from typing import Any, Dict, List
+
+# Tool definitions following Anthropic's Tool Use specification
+# https://docs.anthropic.com/claude/docs/tool-use
+
+
+def get_tools() -> List[Dict[str, Any]]:
+    """
+    Get all available tools for the Advisor Agent.
+
+    Returns:
+        List of tool definitions
+    """
+    return [
+        {
+            "name": "inspect_asktable_project",
+            "description": (
+                "检查用户的 AskTable 项目，获取所有现有资源。"
+                "返回项目中的 datasources、bots、chats、roles、policies 等资源列表。"
+                "用于了解项目当前状态，查看已有场景。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "detailed": {
+                        "type": "boolean",
+                        "description": "是否返回详细信息（包括每个资源的完整配置）",
+                        "default": False,
+                    }
+                },
+                "required": [],
+            },
+        },
+        {
+            "name": "design_database_schema",
+            "description": (
+                "根据场景描述，自动设计数据库表结构。"
+                "分析业务需求，确定需要的表、字段、数据类型、主键、外键关系等。"
+                "返回 SQL DDL 语句（CREATE TABLE 语句）。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "scenario_name": {
+                        "type": "string",
+                        "description": "场景名称，如'电商平台'、'在线教育'、'CRM 系统'",
+                    },
+                    "scenario_description": {
+                        "type": "string",
+                        "description": "场景的详细描述，包括核心业务、主要功能等",
+                    },
+                    "requirements": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "具体的业务需求列表，如'需要订单管理'、'需要用户等级'",
+                    },
+                    "scale_info": {
+                        "type": "object",
+                        "description": "数据规模信息",
+                        "properties": {
+                            "user_count": {"type": "integer", "description": "预期用户数"},
+                            "order_count": {"type": "integer", "description": "预期订单数"},
+                            "other": {"type": "string", "description": "其他规模信息"},
+                        },
+                    },
+                },
+                "required": ["scenario_name", "scenario_description"],
+            },
+        },
+        {
+            "name": "generate_sample_data",
+            "description": (
+                "为给定的数据库表结构生成真实感的虚拟数据。"
+                "使用 LLM 生成符合业务逻辑、数据关联正确的示例数据。"
+                "返回 SQL INSERT 语句。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "schema_sql": {
+                        "type": "string",
+                        "description": "数据库表结构的 SQL DDL 语句",
+                    },
+                    "scenario_context": {
+                        "type": "string",
+                        "description": "场景上下文，帮助生成更真实的数据",
+                    },
+                    "data_volume": {
+                        "type": "object",
+                        "description": "每个表需要生成的数据量",
+                        "additionalProperties": {"type": "integer"},
+                    },
+                },
+                "required": ["schema_sql", "data_volume"],
+            },
+        },
+        {
+            "name": "execute_sql",
+            "description": (
+                "在数据库中执行 SQL 语句。"
+                "可用于创建表结构（DDL）或插入数据（DML）。"
+                "执行前会显示将要执行的 SQL 预览。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "sql": {
+                        "type": "string",
+                        "description": "要执行的 SQL 语句",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "对这个 SQL 操作的描述，如'创建用户表'、'插入订单数据'",
+                    },
+                },
+                "required": ["sql", "description"],
+            },
+        },
+        {
+            "name": "create_asktable_datasource",
+            "description": (
+                "在 AskTable 中创建数据源（Datasource）。"
+                "连接到指定的数据库，使其可以被 Bot 查询和分析。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "数据源名称，如'电商演示数据库'",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "数据源描述",
+                    },
+                    "database_name": {
+                        "type": "string",
+                        "description": "要连接的数据库名称",
+                    },
+                },
+                "required": ["name", "database_name"],
+            },
+        },
+        {
+            "name": "create_asktable_bot",
+            "description": (
+                "在 AskTable 中创建智能 Bot。"
+                "配置 Bot 的业务知识、系统指令、示例问题等。"
+                "Bot 可以回答用户关于数据的问题，执行数据分析。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Bot 名称，如'电商数据分析师'、'教育平台分析助手'",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Bot 描述",
+                    },
+                    "datasource_id": {
+                        "type": "string",
+                        "description": "关联的数据源 ID",
+                    },
+                    "instructions": {
+                        "type": "string",
+                        "description": "Bot 的系统指令，定义其角色、能力、分析方式",
+                    },
+                    "sample_questions": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "示例问题列表，展示 Bot 能回答的典型问题",
+                    },
+                },
+                "required": ["name", "datasource_id", "instructions"],
+            },
+        },
+        {
+            "name": "enhance_bot",
+            "description": (
+                "增强现有的 Bot。"
+                "可以添加更多示例问题、优化系统指令、更新业务知识等。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "bot_id": {
+                        "type": "string",
+                        "description": "要增强的 Bot ID",
+                    },
+                    "action": {
+                        "type": "string",
+                        "enum": ["add_questions", "update_instructions", "optimize"],
+                        "description": "增强动作类型",
+                    },
+                    "content": {
+                        "type": "object",
+                        "description": "根据 action 类型提供的内容",
+                        "properties": {
+                            "questions": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "要添加的示例问题（action=add_questions 时）",
+                            },
+                            "instructions": {
+                                "type": "string",
+                                "description": "更新的系统指令（action=update_instructions 时）",
+                            },
+                        },
+                    },
+                },
+                "required": ["bot_id", "action"],
+            },
+        },
+        {
+            "name": "create_asktable_chat",
+            "description": (
+                "在 AskTable 中创建演示对话（Chat）。"
+                "预制一些典型的业务问题和分析场景，方便演示和测试。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Chat 名称，如'电商场景演示'",
+                    },
+                    "bot_id": {
+                        "type": "string",
+                        "description": "关联的 Bot ID",
+                    },
+                    "initial_messages": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "预制的问题列表",
+                    },
+                },
+                "required": ["name", "bot_id"],
+            },
+        },
+        {
+            "name": "create_permissions",
+            "description": (
+                "创建权限配置（Roles 和 Policies）。"
+                "定义不同角色（如管理员、分析师、普通用户）的数据访问权限。"
+                "配置行级、列级的数据访问控制。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "datasource_id": {
+                        "type": "string",
+                        "description": "关联的数据源 ID",
+                    },
+                    "roles": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string"},
+                                "description": {"type": "string"},
+                            },
+                        },
+                        "description": "角色定义列表",
+                    },
+                    "policies": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "role_name": {"type": "string"},
+                                "table": {"type": "string"},
+                                "rules": {"type": "object"},
+                            },
+                        },
+                        "description": "权限策略列表",
+                    },
+                },
+                "required": ["datasource_id", "roles"],
+            },
+        },
+        {
+            "name": "ask_user",
+            "description": (
+                "向用户询问问题以获取更多信息。"
+                "当需要用户确认、选择或提供额外细节时使用此工具。"
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string",
+                        "description": "要问用户的问题",
+                    },
+                    "options": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "可选的选项列表（如果是多选题）",
+                    },
+                },
+                "required": ["question"],
+            },
+        },
+    ]
+
+
+def get_tool_by_name(name: str) -> Dict[str, Any]:
+    """
+    Get a specific tool definition by name.
+
+    Args:
+        name: Tool name
+
+    Returns:
+        Tool definition dict, or None if not found
+    """
+    tools = get_tools()
+    for tool in tools:
+        if tool["name"] == name:
+            return tool
+    return None