ssci-subagent-skills 1.0.0

package/skills/grounded-theory-expert-enhanced/tools/llm_expert_coder.py

@@ -0,0 +1,469 @@
+"""
+LLM专家编码器 - 真正的AI驱动扎根理论编码
+支持多种LLM提供商: OpenAI, Claude, DeepSeek, 智谱AI等
+"""
+
+import json
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class LLMConfig:
+    """LLM配置"""
+    provider: str  # openai, claude, deepseek, zhipu
+    api_key: str
+    base_url: Optional[str] = None
+    model: str = "gpt-3.5-turbo"
+    temperature: float = 0.3
+    max_tokens: int = 4096
+
+
+class BaseLLMClient(ABC):
+    """LLM客户端基类"""
+
+    @abstractmethod
+    def chat(self, messages: List[Dict[str, str]]) -> str:
+        pass
+
+
+class OpenAIClient(BaseLLMClient):
+    """OpenAI客户端"""
+
+    def __init__(self, config: LLMConfig):
+        self.config = config
+        try:
+            import openai
+            self.client = openai.OpenAI(
+                api_key=config.api_key,
+                base_url=config.base_url
+            )
+        except ImportError:
+            raise ImportError("请安装openai: pip install openai")
+
+    def chat(self, messages: List[Dict[str, str]]) -> str:
+        response = self.client.chat.completions.create(
+            model=self.config.model,
+            messages=messages,
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens
+        )
+        return response.choices[0].message.content
+
+
+class ClaudeClient(BaseLLMClient):
+    """Anthropic Claude客户端"""
+
+    def __init__(self, config: LLMConfig):
+        self.config = config
+        try:
+            import anthropic
+            self.client = anthropic.Anthropic(
+                api_key=config.api_key,
+                base_url=config.base_url
+            )
+        except ImportError:
+            raise ImportError("请安装anthropic: pip install anthropic")
+
+    def chat(self, messages: List[Dict[str, str]]) -> str:
+        # Claude使用不同的消息格式
+        system_msg = None
+        user_msgs = []
+        for msg in messages:
+            if msg["role"] == "system":
+                system_msg = msg["content"]
+            else:
+                user_msgs.append(f"{msg['role']}: {msg['content']}")
+
+        response = self.client.messages.create(
+            model=self.config.model,
+            system=system_msg,
+            messages=[{"role": "user", "content": "\n".join(user_msgs)}],
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens
+        )
+        return response.content[0].text
+
+
+class DeepSeekClient(BaseLLMClient):
+    """DeepSeek客户端"""
+
+    def __init__(self, config: LLMConfig):
+        self.config = config
+        try:
+            import openai
+            self.client = openai.OpenAI(
+                api_key=config.api_key,
+                base_url=config.base_url or "https://api.deepseek.com"
+            )
+        except ImportError:
+            raise ImportError("请安装openai: pip install openai")
+
+    def chat(self, messages: List[Dict[str, str]]) -> str:
+        response = self.client.chat.completions.create(
+            model=self.config.model,
+            messages=messages,
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens
+        )
+        return response.choices[0].message.content
+
+
+class ZhipuAIClient(BaseLLMClient):
+    """智谱AI客户端"""
+
+    def __init__(self, config: LLMConfig):
+        self.config = config
+        try:
+            from zhipuai import ZhipuAI
+            self.client = ZhipuAI(api_key=config.api_key)
+        except ImportError:
+            raise ImportError("请安装zhipuai: pip install zhipuai")
+
+    def chat(self, messages: List[Dict[str, str]]) -> str:
+        # 转换为智谱格式
+        system_msg = None
+        user_content = ""
+        for msg in messages:
+            if msg["role"] == "system":
+                system_msg = msg["content"]
+            else:
+                user_content += f"{msg['role']}: {msg['content']}\n"
+
+        response = self.client.chat.completions.create(
+            model=self.config.model,
+            messages=[
+                {"role": "system", "content": system_msg} if system_msg else {"role": "system", "content": ""},
+                {"role": "user", "content": user_content}
+            ],
+            temperature=self.config.temperature
+        )
+        return response.choices[0].message.content
+
+
+class LLMExpertCoder:
+    """LLM专家编码器"""
+
+    EXPERT_PROMPTS = {
+        "phenomenological": """你是一位现象学专家，擅长从文本中识别人们的主观体验、感受和意义建构。
+
+任务：对以下文本进行开放编码，提取人们的：
+- 情绪状态（喜悦、悲伤、焦虑、愤怒等）
+- 身体感受
+- 主观感受和体验
+- 对世界的感知方式
+- 生活世界中的意义建构
+
+请以JSON格式返回，每个编码需包含：
+1. 原始引文（quote）
+2. 概念名称（concept）- 使用"体验_"前缀
+3. 简要说明
+
+要求：提取10-15个有意义的概念。""",
+
+        "positivist": """你是一位实证主义研究者，擅长从文本中识别可客观测量的指标、事实和特征。
+
+任务：对以下文本进行开放编码，提取：
+- 具体的事件、行为、行动
+- 可测量的指标（时间、数量、频率等）
+- 客观事实描述
+- 可观察的行为模式
+- 因果关系线索
+
+请以JSON格式返回，每个编码需包含：
+1. 原始引文（quote）
+2. 概念名称（concept）- 使用"数据_"前缀
+3. 简要说明
+
+要求：提取10-15个有意义的概念。""",
+
+        "constructivist": """你是一位社会建构主义者，擅长从文本中识别社会互动、关系和意义协商过程。
+
+任务：对以下文本进行开放编码，提取：
+- 人与人之间的互动
+- 社会关系和角色
+- 意义建构和协商过程
+- 语言和符号使用
+- 社会规范的遵从或挑战
+
+请以JSON格式返回，每个编码需包含：
+1. 原始引文（quote）
+2. 概念名称（concept）- 使用"建构_"前缀
+3. 简要说明
+
+要求：提取10-15个有意义的概念。""",
+
+        "localization": """你是一位中国本土社会学研究专家，擅长识别中国文化语境下的特殊概念和表达。
+
+任务：对以下文本进行开放编码，提取：
+- 中国特有的文化概念（人情、面子、关系等）
+- 本土化的社会行为模式
+- 中国历史文化的独特表达
+- 符合中国语境的解释框架
+- 传统文化价值观的体现
+
+请以JSON格式返回，每个编码需包含：
+1. 原始引文（quote）
+2. 概念名称（concept）- 使用"本土_"前缀
+3. 简要说明
+
+要求：提取10-15个有意义的概念。"""
+    }
+
+    AXIAL_PROMPTS = {
+        "phenomenological": """作为现象学专家，请对以下概念进行轴心编码（范畴构建）。
+
+分析这些概念之间的关系，将相似概念归类形成范畴，并识别：
+- 条件（什么情境下产生这种体验）
+- 行动/互动（在这种情境下人们做了什么）
+- 结果（这种体验导致了什么）
+
+请以JSON格式返回，包含范畴名称、包含的概念、关系类型和因果链条。""",
+
+        "positivist": """作为实证主义研究者，请对以下概念进行轴心编码（范畴构建）。
+
+将概念按逻辑关系分类，建立：
+- 前因条件
+- 中介变量
+- 结果变量
+- 边界条件
+
+请以JSON格式返回，包含范畴名称、概念、变量关系和因果模型。""",
+
+        "constructivist": """作为社会建构主义者，请对以下概念进行轴心编码（范畴构建）。
+
+分析社会建构过程，建立：
+- 参与者及其角色
+- 互动模式和过程
+- 意义协商机制
+- 社会秩序的维护或变革
+
+请以JSON格式返回，包含范畴、参与者、互动模式和社会过程。""",
+
+        "localization": """作为中国本土化专家，请对以下概念进行轴心编码（范畴构建）。
+
+在中国文化语境下分析这些概念：
+- 文化传统的影响
+- 本土社会机制的作用
+- 人情关系网络的运作
+- 面子和关系的互动
+
+请以JSON格式返回，包含范畴、文化机制和本土化解释。"""
+    }
+
+    SELECTIVE_PROMPT = """作为扎根理论专家，请进行选择式编码（核心范畴识别）。
+
+基于以下所有专家的轴心编码结果：
+{axail_results}
+
+请识别：
+1. 最核心的范畴（能够统摄其他所有范畴）
+2. 这个核心范畴如何与其他范畴关联
+3. 构建故事线（Story Line）
+4. 提出初步理论框架
+
+请详细说明你的推理过程，并以JSON格式返回核心范畴名称、理论整合和故事线。"""
+
+    def __init__(self, config: Optional[LLMConfig] = None):
+        self.config = config or self._load_config()
+        self.client = self._create_client()
+
+    def _load_config(self) -> LLMConfig:
+        """从环境变量加载配置，优先使用已配置的API密钥"""
+        # 检查可用的提供商
+        providers_config = {
+            "openai": {
+                "api_key": os.getenv("OPENAI_API_KEY", ""),
+                "model": os.getenv("OPENAI_MODEL", "gpt-3.5-turbo"),
+                "base_url": os.getenv("OPENAI_BASE_URL", None)
+            },
+            "claude": {
+                "api_key": os.getenv("CLAUDE_API_KEY", os.getenv("ANTHROPIC_API_KEY", "")),
+                "model": os.getenv("CLAUDE_MODEL", "claude-sonnet-4-20250514"),
+                "base_url": os.getenv("CLAUDE_BASE_URL", None)
+            },
+            "deepseek": {
+                "api_key": os.getenv("DEEPSEEK_API_KEY", ""),
+                "model": os.getenv("DEEPSEEK_MODEL", "deepseek-chat"),
+                "base_url": os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com")
+            },
+            "zhipu": {
+                "api_key": os.getenv("ZHIPU_API_KEY", os.getenv("GLM_API_KEY", "")),
+                "model": os.getenv("ZHIPU_MODEL", "glm-4"),
+                "base_url": os.getenv("ZHIPU_BASE_URL", None)
+            }
+        }
+        
+        # 获取用户指定的提供商
+        specified_provider = os.getenv("LLM_PROVIDER", "")
+        
+        # 选择提供商优先级：
+        # 1. 如果用户指定了且有密钥，使用指定的
+        # 2. 否则按顺序检查可用的提供商
+        provider = None
+        for p in ["openai", "claude", "deepseek", "zhipu"]:
+            if specified_provider:
+                if p == specified_provider:
+                    if providers_config[p]["api_key"]:
+                        provider = p
+                        break
+            else:
+                if providers_config[p]["api_key"]:
+                    provider = p
+                    break
+        
+        # 如果没有可用的提供商，使用第一个并标记为未配置
+        if provider is None:
+            provider = specified_provider if specified_provider else "openai"
+        
+        config = providers_config.get(provider, providers_config["openai"])
+        
+        return LLMConfig(
+            provider=provider,
+            api_key=config["api_key"],
+            base_url=config["base_url"],
+            model=config["model"],
+            temperature=0.3,
+            max_tokens=4096
+        )
+
+    def _create_client(self) -> BaseLLMClient:
+        """创建LLM客户端"""
+        if self.config.provider == "openai":
+            return OpenAIClient(self.config)
+        elif self.config.provider == "claude":
+            return ClaudeClient(self.config)
+        elif self.config.provider == "deepseek":
+            return DeepSeekClient(self.config)
+        elif self.config.provider == "zhipu":
+            return ZhipuAIClient(self.config)
+        else:
+            # 默认使用DeepSeek
+            return DeepSeekClient(self.config)
+
+    def _call_llm(self, system_prompt: str, user_content: str) -> str:
+        """调用LLM"""
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content}
+        ]
+        return self.client.chat(messages)
+
+    def _parse_json_response(self, response: str) -> Dict[str, Any]:
+        """解析JSON响应"""
+        # 尝试提取JSON块
+        import re
+        json_match = re.search(r'```json\s*([\s\S]*?)\s*```', response)
+        if json_match:
+            json_str = json_match.group(1)
+        else:
+            # 尝试找到JSON对象
+            start = response.find('{')
+            end = response.rfind('}') + 1
+            if start >= 0 and end > start:
+                json_str = response[start:end]
+            else:
+                json_str = response
+
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            # 如果JSON解析失败，返回原始文本
+            return {"raw_response": response, "error": "JSON解析失败"}
+
+    def run_open_coding(self, expert_role: str, text: str) -> Dict[str, Any]:
+        """执行开放编码（一级编码）"""
+        prompt = self.EXPERT_PROMPTS.get(expert_role, self.EXPERT_PROMPTS["phenomenological"])
+        user_content = f"待分析文本：\n\n{text[:3000]}"  # 限制文本长度
+
+        response = self._call_llm(prompt, user_content)
+        result = self._parse_json_response(response)
+
+        return {
+            "expert_role": expert_role,
+            "coding_level": 1,
+            "concepts": result.get("concepts", []),
+            "raw_response": result,
+            "text_length": len(text)
+        }
+
+    def run_axial_coding(self, expert_role: str, concepts: List[Dict], text: str) -> Dict[str, Any]:
+        """执行轴心编码（二级编码）"""
+        prompt = self.AXIAL_PROMPTS.get(expert_role, self.AXIAL_PROMPTS["phenomenological"])
+        concepts_json = json.dumps(concepts, ensure_ascii=False, indent=2)
+        user_content = f"已有概念：\n{concepts_json}\n\n原始文本：\n{text[:2000]}"
+
+        response = self._call_llm(prompt, user_content)
+        result = self._parse_json_response(response)
+
+        return {
+            "expert_role": expert_role,
+            "coding_level": 2,
+            "categories": result.get("categories", []),
+            "raw_response": result
+        }
+
+    def run_selective_coding(self, axial_results: Dict[str, Any]) -> Dict[str, Any]:
+        """执行选择式编码（三级编码）"""
+        axail_json = json.dumps(axial_results, ensure_ascii=False, indent=2)
+        prompt = self.SELECTIVE_PROMPT.format(axail_results=axail_json)
+
+        response = self._call_llm(prompt, axail_json)
+        result = self._parse_json_response(response)
+
+        return {
+            "coding_level": 3,
+            "core_category": result.get("core_category", ""),
+            "story_line": result.get("story_line", ""),
+            "theory": result.get("theory", ""),
+            "raw_response": result
+        }
+
+    def run_four_expert_coding(self, text: str) -> Dict[str, Any]:
+        """执行四位专家平行编码"""
+        experts = ["phenomenological", "positivist", "constructivist", "localization"]
+        results = {}
+
+        for expert in experts:
+            results[expert] = self.run_open_coding(expert, text)
+
+        return results
+
+    def check_api_available(self) -> bool:
+        """检查API是否可用"""
+        try:
+            test_response = self._call_llm(
+                "你是一个帮助分析文本的AI助手。",
+                "请回复：OK"
+            )
+            return "OK" in test_response or test_response.strip()
+        except Exception as e:
+            print(f"API连接失败: {e}")
+            return False
+
+
+def create_llm_coder(provider: str = "deepseek", api_key: str = "") -> LLMExpertCoder:
+    """创建LLM专家编码器"""
+    config = LLMConfig(
+        provider=provider,
+        api_key=api_key or os.getenv(f"{provider.upper()}_API_KEY", ""),
+        base_url=os.getenv(f"{provider.upper()}_BASE_URL", None),
+        model=os.getenv(f"{provider.upper()}_MODEL", "deepseek-chat")
+    )
+    return LLMExpertCoder(config)
+
+
+if __name__ == "__main__":
+    # 测试
+    coder = LLMExpertCoder()
+    if coder.check_api_available():
+        print("✅ LLM API可用")
+        
+        test_text = "刘备，字玄德，涿郡涿县人，汉中山靖王刘胜之后。少与河间张合、涿郡张飞结交，志在匡扶汉室。"
+        result = coder.run_open_coding("phenomenological", test_text)
+        print(f"\n开放编码结果: {json.dumps(result, ensure_ascii=False, indent=2)}")
+    else:
+        print("❌ LLM API不可用，请检查配置")