Skip to content

feature: 优化安装速度 #291

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
raychen911 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feature: 优化安装速度 #291

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 48 additions & 18 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Install optional extensions:

```bash
# Choose as needed, multiple extensions can be combined with commas
pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

---
Expand All @@ -77,47 +77,73 @@ pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
git clone https://github.com/trpc-group/trpc-agent-python.git
cd trpc-agent-python
# Create and activate a virtual environment
python3 -m venv .venv
./build.sh
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows
# Install
pip install -e .
```

### uv Installation

[uv](https://docs.astral.sh/uv/) manages the Python toolchain, virtual environment and dependencies based on the repository's `pyproject.toml` for fast, reproducible installs. This project provides a script for one-shot setup on macOS:
[uv](https://docs.astral.sh/uv/) provides fast dependency installation.

#### Install in a user project (recommended)

```bash
# Install uv if it is not already available
python -m pip install uv

# Install the published package in a virtual environment
uv venv --python 3.12
source .venv/bin/activate
uv pip install trpc-agent-py

# Install optional capabilities as needed
# uv pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

For a project managed by uv:

```bash
# Core package only
uv add trpc-agent-py
# Or: core + optional extras (one command is enough)
# uv add "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

#### Develop this repository from source

After cloning the repository, use the same cross-platform build script:

```bash
git clone https://github.com/trpc-group/trpc-agent-python.git
cd trpc-agent-python

# Install uv on macOS (see https://docs.astral.sh/uv/getting-started/installation/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# One-shot setup
bash build_mac_uv.sh
./build.sh uv

# add optional extras
EXTRAS="a2a knowledge" bash build_mac_uv.sh
# Or: core + optional extras (one command is enough; installer defaults to uv)
# ./build.sh "[dev,graph,a2a,knowledge,knowledge-hf]"
# ./build.sh uv "[dev,graph,a2a,knowledge,knowledge-hf]"
source .venv/bin/activate
```

Or run the steps manually:

```bash
uv venv --python-preference only-system # use the local Python
uv sync --extra dev # core + dev tooling
uv sync --extra a2a --extra knowledge # add optional extras
uv sync --extra graph --extra a2a --extra knowledge --extra knowledge-hf
uv sync # production install (core only)

# Run commands inside the environment without activating it for evaluation
# Run commands inside the environment without activating it
uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
```

To speed up downloads via a mirror, pass `--default-index`, e.g.:

```bash
uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
# Or in a user project:
# uv pip install trpc-agent-py --index-url https://mirrors.cloud.tencent.com/pypi/simple
```

### Optional Dependencies Reference
Expand All @@ -127,7 +153,9 @@ uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
| `a2a` | Google A2A protocol | `pip install "trpc-agent-py[a2a]"` |
| `ag-ui` | AG-UI protocol | `pip install "trpc-agent-py[ag-ui]"` |
| `agent-claude` | Claude Agent | `pip install "trpc-agent-py[agent-claude]"` |
| `graph` | LangGraphAgent and graph DSL (includes langchain) | `pip install "trpc-agent-py[graph]"` |
| `knowledge` | Knowledge base / RAG | `pip install "trpc-agent-py[knowledge]"` |
| `knowledge-hf` | Hugging Face embeddings | `pip install "trpc-agent-py[knowledge-hf]"` |
| `mem0` | Long-term memory (Mem0) | `pip install "trpc-agent-py[mem0]"` |
| `langchain_tool` | LangChain Tool integration | `pip install "trpc-agent-py[langchain_tool]"` |
| `langfuse` | Langfuse observability | `pip install "trpc-agent-py[langfuse]"` |
Expand Down Expand Up @@ -163,6 +191,7 @@ TRPC_AGENT_MODEL_NAME="your-model-name"
**Option 2**: Export directly to the shell environment

```bash
# Export environment variables
export TRPC_AGENT_API_KEY="your-api-key"
export TRPC_AGENT_BASE_URL="your-base-url"
export TRPC_AGENT_MODEL_NAME="your-model-name"
Expand Down Expand Up @@ -202,6 +231,7 @@ Expected output:
```
All core modules imported successfully.
```

### Run Unit Tests

```bash
Expand All @@ -220,10 +250,10 @@ pytest tests/ -v
**Solution**: Use a mirror to speed up downloads.

```bash
# Temporary usage Tencent Cloud mirror
# Temporary usage
pip install trpc-agent-py -i https://mirrors.cloud.tencent.com/pypi/simple

# Set global Tencent Cloud mirror
# Set global mirror
pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple
```

Expand All @@ -243,10 +273,10 @@ Other available mirrors:
ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10'
```

**Solution**: Upgrade to Python 3.12.
**Solution**: Upgrade to Python3.12.

```bash
# Solution 1: Using pyenv to install Python 3.12
# Solution 1: Using pyenv to install Python3.12
pyenv install 3.12
pyenv local 3.12

Expand Down
64 changes: 47 additions & 17 deletions INSTALL.zh_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@

### Pip 安装

#### 在用户项目中安装（推荐）

```bash
# 创建虚拟环境
python3 -m venv .venv
Expand All @@ -65,49 +67,73 @@ pip install trpc-agent-py

```bash
# 按需选择，多个扩展可用逗号组合
pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

---

### 源码安装
#### 从源码开发本仓库

```bash
# 克隆仓库
git clone https://github.com/trpc-group/trpc-agent-python.git
cd trpc-agent-python
# 创建并激活虚拟环境
python3 -m venv .venv
./build.sh pip
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows
# 安装
pip install -e .
```

---

### uv 安装

[uv](https://docs.astral.sh/uv/) 会基于仓库中 `pyproject.toml` 管理 Python 工具链、虚拟环境与依赖，实现快速、可复现的安装，本项目提供脚本在 macOS 上一键安装运行：
[uv](https://docs.astral.sh/uv/) 可以快速安装依赖。

#### 在用户项目中安装（推荐）

```bash
# 如果尚未安装 uv，先安装
python -m pip install uv

# 在虚拟环境中安装已发布的包
uv venv --python 3.12
source .venv/bin/activate
uv pip install trpc-agent-py

# 按需安装扩展能力
# uv pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

对于由 uv 管理的项目：

```bash
# 只要核心能力
uv add trpc-agent-py
# 需要扩展能力（一条就够）
# uv add "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
```

#### 从源码开发本仓库

克隆仓库后，可使用与其他平台相同的构建脚本：

```bash
git clone https://github.com/trpc-group/trpc-agent-python.git
cd trpc-agent-python

# 在 macOS 上安装 uv（参考 https://docs.astral.sh/uv/getting-started/installation/）
curl -LsSf https://astral.sh/uv/install.sh | sh
./build.sh uv

# 一键初始化核心依赖
bash build_mac_uv.sh

# 按需追加可选扩展
EXTRAS="a2a knowledge" bash build_mac_uv.sh
# 需要扩展能力（一条就够；省略 uv 时默认仍用 uv）
# ./build.sh "[dev,graph,a2a,knowledge,knowledge-hf]"
# ./build.sh uv "[dev,graph,a2a,knowledge,knowledge-hf]"
source .venv/bin/activate
```

或者使用手动执行的方式：

```bash
uv venv --python-preference only-system # 使用本地已安装的 Python
uv sync --extra dev # 核心依赖 + 开发工具
uv sync --extra a2a --extra knowledge # 按需追加可选扩展
uv sync --extra graph --extra a2a --extra knowledge --extra knowledge-hf
uv sync # 生产安装（仅核心依赖）

# 无需激活环境即可运行命令验证
Expand All @@ -118,6 +144,8 @@ uv run python -c "from trpc_agent_sdk.version import __version__; print(__versio

```bash
uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
# 或在用户项目中：
# uv pip install trpc-agent-py --index-url https://mirrors.cloud.tencent.com/pypi/simple
```

### 可选依赖对照表
Expand All @@ -127,7 +155,9 @@ uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
| `a2a` | Google A2A 协议 | `pip install "trpc-agent-py[a2a]"` |
| `ag-ui` | AG-UI 协议 | `pip install "trpc-agent-py[ag-ui]"` |
| `agent-claude` | Claude Agent | `pip install "trpc-agent-py[agent-claude]"` |
| `graph` | LangGraphAgent 与图 DSL（含 langchain） | `pip install "trpc-agent-py[graph]"` |
| `knowledge` | 知识库 / RAG | `pip install "trpc-agent-py[knowledge]"` |
| `knowledge-hf` | Hugging Face 嵌入模型 | `pip install "trpc-agent-py[knowledge-hf]"` |
| `mem0` | 长期记忆（Mem0） | `pip install "trpc-agent-py[mem0]"` |
| `langchain_tool` | LangChain Tool 集成 | `pip install "trpc-agent-py[langchain_tool]"` |
| `langfuse` | Langfuse 可观测性 | `pip install "trpc-agent-py[langfuse]"` |
Expand Down Expand Up @@ -245,7 +275,7 @@ pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple
ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10'
```

**解决方案**：升级到 Python 3.12。
**解决方案**：升级到 Python3.12。

```bash
# 解决方案 1: 使用 pyenv 安装
Expand Down
54 changes: 38 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ tRPC-Agent-Python provides an end-to-end foundation for agent building, orchestr

### Prerequisites

- Python 3.10+ (Python 3.12 recommended)
- Python3.10+ (Python3.12 recommended)
- Available model API key (OpenAI-like / Anthropic, or route via LiteLLM)

### Installation
Expand All @@ -86,34 +86,56 @@ pip install trpc-agent-py
Install optional capabilities as needed:

```bash
pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]"
pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf,agent-claude,mem0,mempalace,langfuse]"
```

#### Install with uv

[uv](https://docs.astral.sh/uv/) provides fast, reproducible installs:

```bash
uv venv --python-preference only-system # use the local Python
uv sync # production install (core only)
uv sync --extra dev # core + dev tooling
uv sync --extra a2a --extra knowledge # add optional extras
# Install uv if it is not already available
python -m pip install uv

# Install the published package in a virtual environment
uv venv --python 3.12
source .venv/bin/activate
uv pip install trpc-agent-py

# Run commands inside the environment without activating it for evaluation
uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
# Install optional capabilities as needed
# uv pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]"
```

This project also provides a script for one-shot setup on macOS：
For a project managed by uv:

```bash
# One-shot setup
bash build_mac_uv.sh
# Core package only
uv add trpc-agent-py
# Or: core + optional extras (one command is enough)
# uv add "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]"
```

Install optional capabilities as needed:
When developing this repository:

```bash
uv sync --extra dev
./build.sh # uv (default; installed automatically if missing)
# ./build.sh "[graph]" # uv by default, extras only
# ./build.sh pip # use pip instead
# ./build.sh uv "[dev,graph]" # explicit uv with selected extras

# Install dependencies required by feature-specific test suites
./build.sh uv "[dev,graph,ag-ui,agent-claude,a2a]"
uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
```

On macOS, use the same cross-platform build script inside a virtual environment:
```bash
EXTRAS="a2a knowledge" bash build_mac_uv.sh
./build.sh # creates .venv automatically; default uv
#./build.sh "[dev,graph,knowledge]" # uv by default with selected extras
#./build.sh pip "[dev]" # use pip
#./build.sh uv "[dev,graph,knowledge]" # explicit uv
source .venv/bin/activate # activate it in the current shell
```

### Develop Weather Agent
Expand Down Expand Up @@ -371,7 +393,7 @@ Recommended first:

- [examples/langgraph_agent](./examples/langgraph_agent/README.md) - Integrate pre-built and compiled LangGraph workflows
- [examples/langgraph_agent_with_cancel](./examples/langgraph_agent_with_cancel/README.md) - `LangGraphAgent` cancellation
- [examples/langgraphagent_with_human_in_the_loop](./examples/langgraphagent_with_human_in_the_loop/README.md) - `LangGraphAgent` human-in-the-loop
- [examples/langgraph_agent_with_HITL](./examples/langgraph_agent_with_HITL/README.md) - `LangGraphAgent` human-in-the-loop
- [examples/claude_agent](./examples/claude_agent/README.md) - `ClaudeAgent` basics
- [examples/claude_agent_with_streaming_tool](./examples/claude_agent_with_streaming_tool/README.md) - `ClaudeAgent` streaming tools
- [examples/claude_agent_with_skills](./examples/claude_agent_with_skills/README.md) - `ClaudeAgent` + Skills
Expand Down Expand Up @@ -615,8 +637,8 @@ We love contributions! Join our growing developer community and help build the f
git clone https://github.com/YOUR_USERNAME/trpc-agent-python.git
cd trpc-agent-python

# Install development dependencies and run tests
pip install -e ".[dev]"
# Install development and feature-test dependencies, then run tests
pip install -e ".[dev,graph,ag-ui,agent-claude,a2a]"
pytest

# Make your changes and open a PR!
Expand Down
Loading
Loading