Metadata-Version: 2.4
Name: easycome-langchain
Version: 0.1.0
Summary: LangChain tools for easycome social media data APIs
License: MIT
Keywords: bilibili,douyin,langchain,social-media,weibo,xiaohongshu,zhihu
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: langchain>=0.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# EasyCome LangChain SDK

让 [easycome](https://www.easycome.com.cn) 社媒数据 API 无缝接入 LangChain 智能体。

## 安装

```bash
pip install easycome-langchain
```

## 快速开始

```python
import os
os.environ["EASYCOME_BASE_URL"] = "https://www.easycome.com.cn"
os.environ["EASYCOME_API_KEY"] = "dg_xxxxxxxxxxxx"
os.environ["EASYCOME_COOKIE_XHS"] = "a1=xxx; web_session=yyy"

from easycome_langchain import get_tools
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

tools = get_tools()  # 自动发现所有 API
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools)

result = agent.invoke({
    "messages": [{"role": "user", "content": "搜索小红书关于"成都美食"的笔记，只看前3条"}]
})
```

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `EASYCOME_BASE_URL` | 是 | API 基础 URL |
| `EASYCOME_API_KEY` | 是 | API 密钥 (dg_ 开头) |
| `EASYCOME_COOKIE_XHS` | 按需 | 小红书平台 Cookie |
| `EASYCOME_COOKIE_DOUYIN` | 按需 | 抖音平台 Cookie |
| `EASYCOME_COOKIE_BIlibili` | 按需 | B站平台 Cookie |
| `EASYCOME_COOKIE_WEIBO` | 按需 | 微博平台 Cookie |
| `EASYCOME_COOKIE_ZHIHU` | 按需 | 知乎平台 Cookie |
| `EASYCOME_COOKIES` | 按需 | JSON 格式: `{"xhs":"...", "bilibili":"..."}` |

## API

### `get_tools(...)`

主入口，返回 `list[StructuredTool]` 供 LangChain Agent 使用。

```python
from easycome_langchain import get_tools

# 获取所有工具
tools = get_tools()

# 筛选特定平台
xhs_tools = get_tools(platform="xhs")

# 筛选特定分类
stock_tools = get_tools(category="stock")

# 只获取指定工具
tools = get_tools(slugs=["xhs_search", "bilibili_video_detail"])

# 显式传参（替代环境变量）
tools = get_tools(
    base_url="https://www.easycome.com.cn",
    api_key="dg_xxx",
    cookies={"xhs": "a1=xxx; web_session=yyy"},
)
```

### `EasyComeClient`

底层 REST 客户端，也可以独立使用。

```python
from easycome_langchain import EasyComeClient

client = EasyComeClient(
    base_url="https://www.easycome.com.cn",
    api_key="dg_xxx",
    cookies={"xhs": "a1=xxx"},
)

# 同步调用
data = client.call_sync("xhs_search", {"keyword": "美食", "page": "1"})

# 异步调用
data = await client.call("xhs_search", {"keyword": "美食"})
```

### `fetch_catalog()`

获取 API 目录（不依赖 LangChain）。

```python
from easycome_langchain import fetch_catalog

entries = fetch_catalog("https://www.easycome.com.cn")
for e in entries:
    print(f"{e.slug}: {e.name} [{e.platform}]")
```

## Cookie 管理

SDK 自动处理 Cookie 注入——Agent 不需要知道 Cookie 参数的存在。

- Cookie 按**平台**配置（不是按端点）
- 创建 Tool 时自动匹配 platform → cookie
- 端点需要 cookie 但未配置时，调用会抛出 `CookieRequiredError`

多平台 Cookie 示例：

```python
os.environ["EASYCOME_COOKIE_XHS"] = "a1=xxx; web_session=yyy"
os.environ["EASYCOME_COOKIE_BIlibili"] = "SESSDATA=xxx; bili_jct=yyy"
os.environ["EASYCOME_COOKIE_WEIBO"] = "SUB=xxx"

tools = get_tools()  # 自动匹配各平台的 Cookie
```

## 异常处理

```python
from easycome_langchain import (
    AuthError,         # API Key 无效
    QuotaError,        # 余额不足
    RateLimitError,    # 请求过于频繁
    UpstreamError,     # 上游平台返回错误
    NotFoundError,     # 端点不存在
    CookieRequiredError,  # 缺少必需的 Cookie
)
```

## 结合 LangGraph 使用

```python
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from easycome_langchain import get_tools

tools = get_tools(platform="xhs")
agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)

async for event in agent.astream_events(
    {"messages": [{"role": "user", "content": "帮我分析小红书'穿搭'话题的热门笔记"}]},
    version="v2",
):
    # 处理流式事件
    pass
```
