github-reachout 0.1.0__py3-none-any.whl

github_reachout/github_client.py

@@ -0,0 +1,178 @@
+"""
+GitHub API 客户端模块。
+
+功能：
+  - 获取用户基本信息（/users/{login}）
+  - 获取用户公开仓库列表（/users/{login}/repos）
+  - 从 bio/blog 等字段中提取 LinkedIn URL
+  - 速率控制：遵守 GitHub API 限制
+"""
+from __future__ import annotations
+
+import os
+import re
+import time
+from typing import Optional, Dict, List, Any
+
+import requests
+
+
+class GitHubClient:
+    """轻量级 GitHub API 客户端，支持认证和速率控制。"""
+
+    API_BASE = "https://api.github.com"
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        per_page: int = 30,
+        max_repos: int = 10,
+    ):
+        """
+        Args:
+            token: GitHub Personal Access Token（可选，不传则使用匿名请求，限制更严）
+            per_page: 每页返回数量
+            max_repos: 最多获取的仓库数量
+        """
+        self.token = token or os.getenv("GITHUB_TOKEN", "")
+        self.per_page = per_page
+        self.max_repos = max_repos
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Accept": "application/vnd.github.v3+json",
+        })
+        if self.token:
+            self.session.headers.update({
+                "Authorization": f"token {self.token}",
+            })
+
+    def get_user(self, login: str) -> Dict[str, Any]:
+        """
+        获取用户基本信息。
+
+        Returns:
+            {login, name, bio, location, company, blog, public_repos,
+             followers, avatar_url, html_url, email}
+        """
+        resp = self.session.get(f"{self.API_BASE}/users/{login}", timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+
+        return {
+            "login": data.get("login", login),
+            "name": data.get("name", "") or "",
+            "bio": data.get("bio", "") or "",
+            "location": data.get("location", "") or "",
+            "company": data.get("company", "") or "",
+            "blog": data.get("blog", "") or "",
+            "public_repos": data.get("public_repos", 0),
+            "followers": data.get("followers", 0),
+            "avatar_url": data.get("avatar_url", ""),
+            "html_url": data.get("html_url", f"https://github.com/{login}"),
+            "email": data.get("email", "") or "",
+        }
+
+    def get_user_repos(self, login: str) -> List[Dict[str, Any]]:
+        """
+        获取用户公开仓库列表（按 star 数降序，最多 max_repos 个）。
+
+        Returns:
+            [{name, description, language, stargazers_count, html_url, fork}]
+        """
+        repos = []
+        page = 1
+
+        while len(repos) < self.max_repos:
+            resp = self.session.get(
+                f"{self.API_BASE}/users/{login}/repos",
+                params={
+                    "type": "public",
+                    "sort": "updated",
+                    "per_page": self.per_page,
+                    "page": page,
+                },
+                timeout=30,
+            )
+            resp.raise_for_status()
+            page_data = resp.json()
+
+            if not page_data:
+                break
+
+            for repo in page_data:
+                if len(repos) >= self.max_repos:
+                    break
+                # 跳过 fork 的仓库
+                if repo.get("fork", False):
+                    continue
+                repos.append({
+                    "name": repo.get("name", ""),
+                    "description": repo.get("description", "") or "",
+                    "language": repo.get("language", "") or "",
+                    "stargazers_count": repo.get("stargazers_count", 0),
+                    "html_url": repo.get("html_url", ""),
+                    "fork": repo.get("fork", False),
+                })
+
+            page += 1
+            # 速率控制
+            time.sleep(0.5)
+
+        # 按 star 数降序排列
+        repos.sort(key=lambda r: r.get("stargazers_count", 0), reverse=True)
+        return repos
+
+    def fetch_person(self, login: str) -> Dict[str, Any]:
+        """
+        获取一个用户的完整信息（基本信息 + 仓库列表 + LinkedIn 提取）。
+
+        Returns:
+            PersonInfo 字典
+        """
+        user = self.get_user(login)
+        repos = self.get_user_repos(login)
+
+        # 从 bio/blog 中提取 LinkedIn URL
+        linkedin_url = self._extract_linkedin(user.get("bio", ""), user.get("blog", ""))
+
+        return {
+            **user,
+            "repos": repos,
+            "linkedin_url": linkedin_url,
+            "web_summary": "",
+            "tech_direction": "",
+            "reachout_email": "",
+            "email_ready": False,
+            "email_sent": False,
+            "email_sent_error": "",
+        }
+
+    @staticmethod
+    def _extract_linkedin(bio: str, blog: str) -> str:
+        """
+        从 bio 和 blog 字段中提取 LinkedIn URL。
+
+        支持格式：
+          - https://www.linkedin.com/in/xxx
+          - https://linkedin.com/in/xxx
+          - linkedin.com/in/xxx
+        """
+        text = f"{bio} {blog}"
+        patterns = [
+            r'https?://(?:www\.)?linkedin\.com/in/[a-zA-Z0-9_-]+',
+            r'linkedin\.com/in/[a-zA-Z0-9_-]+',
+        ]
+        for pattern in patterns:
+            match = re.search(pattern, text)
+            if match:
+                url = match.group(0)
+                if not url.startswith("http"):
+                    url = f"https://{url}"
+                return url
+        return ""
+
+    def check_rate_limit(self) -> Dict[str, Any]:
+        """检查当前 API 速率限制状态。"""
+        resp = self.session.get(f"{self.API_BASE}/rate_limit", timeout=10)
+        resp.raise_for_status()
+        return resp.json()

github_reachout/graph.py

@@ -0,0 +1,107 @@
+"""
+LangGraph 图编排模块。
+
+图结构：
+  plan → [条件路由] → fetch → enrich → summarize → generate → validate → send → evaluate
+                                                                                      │
+                                                      continue_loop=True → 回到 plan
+                                                      continue_loop=False → 结束
+"""
+from __future__ import annotations
+
+from typing import Dict, Any
+
+from langgraph.graph import StateGraph, END
+
+from github_reachout.state import ReachoutState
+from github_reachout.nodes import (
+    plan_node, fetch_node, enrich_node, summarize_node,
+    generate_node, validate_node, send_node, evaluate_node,
+    route_after_plan, route_after_step, route_after_evaluate,
+)
+from github_reachout.llm import LLMClient
+from github_reachout.github_client import GitHubClient
+from github_reachout.web_reader import WebReader
+from github_reachout.email_client import EmailClient
+
+# 执行步骤名（不含 plan/evaluate）
+EXECUTION_STEPS = ["fetch", "enrich", "summarize", "generate", "validate", "send"]
+
+# 条件路由映射：步骤名 → 节点名（所有执行步骤 + evaluate 共用）
+STEP_ROUTE_MAP = {s: s for s in EXECUTION_STEPS + ["evaluate"]}
+
+
+def build_graph(
+    llm: LLMClient,
+    github: GitHubClient,
+    web_reader: WebReader,
+    email_client: EmailClient,
+) -> StateGraph:
+    """构建 LangGraph 状态图，使用依赖注入。"""
+    # 节点名 → 构造函数（闭包注入依赖）
+    node_builders = {
+        "plan": lambda s: plan_node(s, llm),
+        "fetch": lambda s: fetch_node(s, github),
+        "enrich": lambda s: enrich_node(s, web_reader),
+        "summarize": lambda s: summarize_node(s, llm),
+        "generate": lambda s: generate_node(s, llm),
+        "validate": lambda s: validate_node(s, llm),
+        "send": lambda s: send_node(s, email_client),
+        "evaluate": lambda s: evaluate_node(s, llm),
+    }
+
+    graph = StateGraph(ReachoutState)
+
+    # 注册节点
+    for name, builder in node_builders.items():
+        graph.add_node(name, builder)
+
+    graph.set_entry_point("plan")
+
+    # plan 后：路由到第一个 planned 步骤
+    graph.add_conditional_edges("plan", route_after_plan, STEP_ROUTE_MAP)
+
+    # 每个执行步骤后：路由到下一个 planned 步骤
+    for step in EXECUTION_STEPS:
+        graph.add_conditional_edges(step, route_after_step(step), STEP_ROUTE_MAP)
+
+    # evaluate 后：继续循环或结束
+    graph.add_conditional_edges("evaluate", route_after_evaluate, {
+        "plan": "plan",
+        "__end__": END,
+    })
+
+    return graph.compile()
+
+
+def create_initial_state(
+    login_ids: list,
+    target_tech_direction: str = "",
+    company_name: str = "",
+    sender_name: str = "",
+    sender_title: str = "",
+    sender_email: str = "",
+    max_loops: int = 3,
+    run_id: str = "",
+) -> ReachoutState:
+    """创建初始 state。"""
+    return ReachoutState(
+        login_ids=login_ids,
+        target_tech_direction=target_tech_direction,
+        company_name=company_name,
+        sender_name=sender_name,
+        sender_title=sender_title,
+        sender_email=sender_email,
+        planned_steps=[],
+        loop_count=0,
+        max_loops=max_loops,
+        continue_loop=True,
+        persons=[],
+        processed_logins=[],
+        emails_to_send=[],
+        sent_results=[],
+        loop_history=[],
+        errors=[],
+        run_id=run_id,
+        step_index=0,
+    )

github_reachout/llm.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import os
+import json
+import time
+from typing import Optional, Union, Dict, List
+from openai import OpenAI
+from openai._exceptions import RateLimitError, APITimeoutError
+
+
+
+
+class LLMClient:
+    """
+    轻量级 LLM 客户端，基于 openai 官方库封装。
+    支持 OpenAI / DeepSeek / 本地 Ollama 等任何兼容 OpenAI Chat API 的服务。
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        model: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ):
+        # 配置参数读取逻辑
+        self.api_key = api_key or os.getenv("LLM_API_KEY", "")
+        self.base_url = (base_url or os.getenv("LLM_BASE_URL", "")).rstrip("/")
+        self.model = model or os.getenv("LLM_MODEL", "deepseek-v3.1-terminus-chat")
+        self.timeout = timeout or float(os.getenv("LLM_TIMEOUT", "120"))
+        self.max_retries = max_retries or int(os.getenv("LLM_MAX_RETRIES", "3"))
+        
+        # 初始化 OpenAI 客户端
+        # 注意：openai 库的 max_retries 参数在较新版本中可能行为不同，
+        # 这里我们将重试逻辑主要放在调用层，确保对 429/500 等特定状态码的精细控制。
+        self.client = OpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_retries=0  # 暂时在客户端层禁用默认重试，由本类手动控制以兼容旧逻辑
+        )
+
+    def chat(self, system: str, user: str, temperature: float = 0.3) -> str:
+        """
+        同步调用 Chat Completion API，返回助手回复文本。
+        内置指数退避重试机制。
+        
+        Args:
+            system: 系统提示词
+            user: 用户消息
+            temperature: 生成温度
+
+        Returns:
+            助手回复的文本内容
+        """
+        last_error = None
+        
+        # 构建消息列表
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+
+        for attempt in range(self.max_retries):
+            try:
+                # 使用流式请求以支持更好的大模型长文本处理，并手动拼接
+                stream = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=messages,
+                    stream=True,
+                    temperature=temperature,
+                    timeout=self.timeout
+                )
+                
+                response_content = ""
+                for chunk in stream:
+                    if chunk.choices and chunk.choices[0].delta.content:
+                        response_content += chunk.choices[0].delta.content
+                
+                # 成功返回
+                return response_content.strip()
+
+            except (RateLimitError, APITimeoutError) as e:
+                # 可重试错误
+                last_error = e
+                wait = 2 ** attempt  # 指数退避: 1s, 2s, 4s
+                print(f"  [LLM] 请求失败 (HTTP 429/Timeout)，第 {attempt + 1}/{self.max_retries} 次重试，等待 {wait}s...")
+                time.sleep(wait)
+                continue
+                
+            except Exception as e:
+                # 不可重试的错误 (如 401, 403, 404 或 JSON 解析错误) 直接抛出
+                raise e
+
+        # 所有重试都失败
+        raise ConnectionError(
+            f"LLM API 调用失败，已重试 {self.max_retries} 次。最后错误: {last_error}"
+        )
+
+    def chat_json(self, system: str, user: str, temperature: float = 0.1) -> Union[Dict, List]:
+        """
+        调用 Chat API 并解析 JSON 响应。
+        自动从 markdown 代码块中提取 JSON。
+        """
+        raw = self.chat(system, user, temperature)
+        return self._extract_json(raw)
+
+    @staticmethod
+    def _extract_json(text: str) -> Union[Dict, List]:
+        """从 LLM 回复中提取 JSON（支持 markdown 代码块包裹）"""
+        text = text.strip()
+        
+        # 1. 尝试直接解析
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            pass
+
+        # 2. 尝试从 ```json ... ``` 中提取
+        if "```json" in text:
+            start = text.index("```json") + 7
+            end = text.index("```", start)
+            return json.loads(text[start:end].strip())
+        
+        # 3. 尝试从 ``` ... ``` 中提取 (不指定语言)
+        if "```" in text:
+            start = text.index("```") + 3
+            end = text.index("```", start)
+            return json.loads(text[start:end].strip())
+
+        raise ValueError(f"无法从 LLM 回复中提取 JSON: {text[:200]}")