ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

pyproject.toml

@@ -0,0 +1,388 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentbook"
+version = "0.1.0"
+description = "Shared packaging and plumbing for the ai-agent-book companion experiments"
+readme = "README.md"
+# 3.11 matches what the chapter READMEs document (chapter2/local_llm_serving,
+# chapter7/orpheus, chapter8/prompt-distillation all state Python 3.10+, which
+# 3.11 continues to satisfy). The CUDA/ML stacks used by the training chapters
+# do not yet publish a coherent Python 3.14 wheel set, and the maintained
+# `python-constraint2` solver (imported as `constraint` by chapter 5) requires
+# >=3.11, so 3.11 is the lowest version the lockfile can actually reproduce.
+requires-python = ">=3.11,<3.14"
+license = { text = "Apache-2.0" }
+
+# The core that nearly every experiment needs.
+# openai: 131 declarations across the repo; python-dotenv: 114; requests: 50.
+dependencies = [
+    # chapter 8 (self-evolution-eval, self-modifying-agent, trajectory-verifier,
+    # gaia-experience) calls client.responses.create, added in 1.68. A lower
+    # floor is satisfiable by an already-installed older SDK that then fails at
+    # runtime rather than at install time.
+    "openai>=1.68",
+    "pydantic>=2.9.0",
+    "python-dotenv>=1.0",
+    "requests>=2.31",
+]
+
+# ---------------------------------------------------------------------------
+# Capability groups.
+#
+# Install only what an experiment actually needs:
+#     uv sync --extra ch1          # chapter 1, no GPU stack (uses uv.lock)
+#     uv sync --extra ch7          # heavy fine-tuning deps, opt in explicitly
+#
+# pip works identically for readers without uv, but resolves fresh rather
+# than from the lockfile:
+#     pip install -e ".[ch1]"
+#
+# Groups are derived from an AST audit of the imports in every non-vendored
+# chapter module, cross-checked against the per-project requirements.txt files.
+# Vendored third-party trees (chapter8/gaia-experience/AWorld,
+# chapter8/browser-use-rpa/browser-use, chapter2/prompt-engineering/tau_bench)
+# are deliberately excluded -- they carry their own requirements.
+#
+# Platform-specific stacks are opt-in extras rather than chapter aggregates,
+# so a chapter install never fails on macOS or CPU-only machines:
+#     pip install -e ".[unsloth]"   # chapter 7 Unsloth fine-tuning (Linux/GPU)
+#     pip install -e ".[vllm]"      # chapter 2 local serving, chapter 8 data gen
+#
+# Test tooling lives in `dev` (`pip install -e ".[dev]"`), not in the chapter
+# aggregates, so running an experiment does not pull a test stack.
+# ---------------------------------------------------------------------------
+[project.optional-dependencies]
+
+# Plotting, tables and dataframes used by most analysis/eval experiments.
+viz = [
+    "colorama>=0.4.6",
+    "matplotlib>=3.8.0",
+    "numpy>=1.26.4",
+    "pandas>=2.2.0",
+    "rich>=13.7",
+    "seaborn>=0.13.0",
+    "tabulate>=0.9",
+    "tenacity>=9.0.0",
+    "tqdm>=4.66.1",
+]
+
+# Document parsing and generation (PDF/Office).
+# PyPDF2 is kept alongside pypdf because several experiments still
+# `import PyPDF2` directly (chapter1/context/agent.py,
+# chapter2/local_llm_serving/tools.py, chapter4/perception-tools/...).
+# Migrating those imports to pypdf is tracked separately.
+docs = [
+    "pypdf>=4.0",
+    "PyPDF2>=3.0",
+    "pdfplumber>=0.10.3",
+    "reportlab>=4.0",
+    "python-docx>=1.1",
+    "python-pptx>=0.6.23",
+    "openpyxl>=3.1",
+]
+
+# Image and video processing.
+media = [
+    "pillow>=10.2",
+    "opencv-python>=4.9",
+]
+
+# HTML fetching/parsing and browser automation.
+web = [
+    "aiohttp>=3.9.3",
+    "anyio>=4.5.0",
+    "beautifulsoup4>=4.12",
+    "httpx>=0.27",
+    "lxml>=5.1.0",
+    "html2text>=2020.1.16",
+    "playwright>=1.40",
+]
+
+# Browser-driving agents (chapter 4 collaboration tools, chapter 8 RPA).
+# browser-use declares requires-python >=3.11, which the project floor already
+# satisfies, so `.[ch4]`/`.[ch8]`/`.[all]` install it unconditionally.
+browser = [
+    "agentbook[web]",
+    "browser-use>=0.1.40; python_version >= '3.11'",
+]
+
+# HTTP services used by the interactive/demo experiments.
+serve = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "python-multipart>=0.0.9",
+]
+
+# Token counting. Small and widely used, so it is its own group rather than
+# forcing a chapter that only counts tokens to pull the whole `rag` stack.
+tokens = [
+    "tiktoken>=0.7.0",
+]
+
+# Statistics, symbolic math and interactive plots for the
+# evaluation/benchmark experiments.
+analysis = [
+    "scikit-learn>=1.5.0",
+    "scipy>=1.11",
+    "plotly>=5.18",
+    "sympy>=1.12",
+    "numba>=0.59",
+]
+
+# Transformer runtime. Needed by experiments that load models locally for
+# inference (e.g. chapter 2's attention visualization) without the full
+# fine-tuning stack in `train`.
+torch = [
+    # PyTorch 2.4, previously selected by the universal lock through an old
+    # vLLM/xformers combination, has no Blackwell (sm_120) kernels.  Keep the
+    # shared runtime new enough for the documented local-GPU experiments.
+    "torch>=2.11",
+    "transformers>=4.40,<6",
+]
+
+# Retrieval / vector stores / embeddings.
+rag = [
+    "agentbook[tokens]",
+    "chromadb>=0.5.0",
+    # Chroma does not cap onnxruntime; onnxruntime 1.24+ ships wheels for the
+    # supported 3.11+ interpreters, so no version pin is needed here.
+
+    "faiss-cpu>=1.7.4",
+    "sentence-transformers>=2.2.2",
+    "rank-bm25>=0.2.2",
+    "FlagEmbedding>=1.2.11",
+    "huggingface-hub>=0.34.0",
+    "annoy>=1.17.3",
+    "hnswlib>=0.8",
+    "jieba>=0.42.1",
+    "networkx>=3.2",
+    "umap-learn>=0.5.4",
+    "aiofiles>=24.1.0",
+    "colorlog>=6.8",
+    "loguru>=0.7.2",
+    "markdown>=3.5",
+    "PyYAML>=6.0",
+]
+
+# Third-party data-source and productivity integrations used by the
+# chapter 4 tool-building experiments.
+integrations = [
+    "arxiv>=2.1",
+    "wikipedia>=1.4",
+    "waybackpy>=3.0",
+    "yfinance>=0.2",
+    "youtube-transcript-api>=0.6",
+    "yt-dlp>=2024.4",
+    "python-chess>=1.10",
+    "notion-client>=2.2",
+    "sendgrid>=6.11",
+    "aiosmtplib>=3.0",
+    "PyGithub>=2.3",
+    "google-api-python-client>=2.126",
+    "google-auth>=2.29",
+    "google-auth-oauthlib>=1.2",
+    "psutil>=5.9.8",
+    "langchain-openai>=0.1",
+]
+
+# LangChain wrappers and workplace integrations used by the chapter 8
+# self-evolution / RPA experiments.
+orchestration = [
+    "langchain-core>=0.2",
+    "langchain-openai>=0.1",
+    "slack-sdk>=3.27",
+    "python-dateutil>=2.9",
+]
+
+# Constraint solving (chapter 5 code-for-logic). The original `python-constraint`
+# 1.4.0 ships only a non-PEP 625-compliant sdist that uv refuses to build, so we
+# use the maintained `python-constraint2` fork, which exposes the same
+# `constraint` module (`from constraint import Problem`) and publishes wheels
+# for every supported platform and Python version.
+solvers = [
+    "python-constraint2>=2.0.2",
+]
+
+# Long-term memory backends used by the chapter 3 memory experiments.
+# mem0ai[nlp]>=2.0,<3; memobase declares requires-python >=3.11, which the
+# project floor satisfies, so it installs for every supported interpreter.
+mem = [
+    "mem0ai[nlp]>=2.0,<3",
+    "memobase>=0.0.27; python_version >= '3.11'",
+]
+
+# Model Context Protocol servers and clients.
+mcp = [
+    "mcp[cli]>=1.0",
+    "fastmcp>=0.2",
+]
+
+# Alternative model providers beyond the OpenAI-compatible core.
+providers = [
+    "anthropic>=0.40.0",
+    "google-genai>=0.3",
+    "mistralai>=1.2.0",
+    "litellm>=1.41.0",
+    "ollama>=0.5.1",
+]
+
+# Local fine-tuning / training stack. Large downloads, GPU-oriented.
+# Intentionally NOT part of `all`.
+train = [
+    "agentbook[torch]",
+    "datasets>=3.4.1",
+    "accelerate>=0.30",
+    "peft>=0.17.0",
+    # chapter7/MultilingualReasoning uses SFTConfig(max_length=...) and
+    # SFTTrainer(processing_class=...), both of which need TRL 0.20+.
+    "trl>=0.22.2",
+    "sentencepiece>=0.2",
+    "wandb>=0.17",
+    # Experiment tracking backend requested by name at runtime
+    # (chapter7/MultilingualReasoning sets SFTConfig(report_to="trackio")),
+    # so it must be installed even though nothing imports it directly.
+    "trackio>=0.1",
+    # chapter7/MultilingualReasoning imports transformers.Mxfp4Config, added
+    # in 4.55. Without this floor the aggregate is satisfiable by an older
+    # transformers already present in the environment.
+    "transformers>=4.55,<6",
+    # macOS wheels only exist from 0.45 onwards; the floor keeps `train`
+    # installable on Apple Silicon instead of resolving to a Linux-only build.
+    "bitsandbytes>=0.45",
+]
+
+# Unsloth-accelerated fine-tuning (chapter 7). Split from `train` because it
+# pins tightly against torch/transformers and is Linux/GPU oriented, so a
+# macOS or CPU-only reader can still install `train`.
+unsloth = [
+    "agentbook[train]",
+    "unsloth>=2026.7.6; sys_platform == 'linux' and platform_machine == 'x86_64'",
+    "unsloth_zoo>=2026.7.7; sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+# Local high-throughput inference server. Linux/GPU only -- vLLM publishes no
+# macOS wheels, so it is opt-in rather than part of any chapter aggregate.
+# Needed by chapter2/local_llm_serving and by the data-generation step of
+# chapter8/prompt-distillation (create_data.py imports it lazily).
+vllm = [
+    "agentbook[torch]",
+    # vLLM 0.6 pins the pre-Blackwell torch 2.4 stack.  The 0.26 runtime is
+    # compatible with the torch floor above and current CUDA 13 wheels.
+    "vllm>=0.26; sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+# Audio processing for the local speech/TTS training experiments (chapter 7).
+# Note: chapter 9 uses hosted speech APIs and needs only the core.
+audio = [
+    "librosa>=0.10",
+    "soundfile>=0.12",
+    "torchaudio>=2.11",
+    "snac>=1.2",
+]
+
+# Test and lint tooling.
+dev = [
+    # Root registry tests collect Chapter 4 perception-tool modules directly;
+    # those modules import httpx before individual tests can exercise helpers.
+    "httpx>=0.27,<1",
+    "Markdown>=3.5,<4",
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-mock>=3.14.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+]
+
+# ---------------------------------------------------------------------------
+# Chapter aggregates -- what a reader installs to run one chapter.
+# ---------------------------------------------------------------------------
+ch1  = ["agentbook[viz,docs]"]
+ch2  = ["agentbook[viz,docs,web,serve,providers,tokens,torch]"]
+ch3  = ["agentbook[viz,docs,web,serve,rag,mem,analysis,torch,providers]"]
+ch4  = [
+    "agentbook[viz,docs,media,browser,serve,mcp,tokens,analysis,integrations]",
+    "PyMuPDF>=1.24.0",
+]
+ch5  = ["agentbook[viz,docs,media,web,serve,mcp,providers,analysis,solvers]", "PyMuPDF>=1.25.0"]
+ch6  = ["agentbook[viz,tokens,analysis,providers]", "fish-audio-sdk>=1.3.0,<2"]
+# `train` floors transformers at >=4.55 for MultilingualReasoning's
+# Mxfp4Config. chapter7/sesame pins transformers==4.52.3, which no single
+# aggregate can satisfy alongside it -- run that one experiment from its own
+# requirements.txt in a separate venv. Add the `unsloth` extra for the
+# Unsloth-accelerated experiments.
+ch7  = ["agentbook[train,audio,viz]"]
+# Ordinary Chapter 8 experiments are inference/RAG/browser/orchestration demos.
+# The prompt-distillation training project keeps its Linux/CUDA stack isolated in
+# its own requirements.txt because it also needs vLLM and tighter training-stack
+# compatibility than the shared chapter aggregate should impose.
+ch8  = ["agentbook[viz,docs,media,browser,serve,rag,mcp,providers,orchestration]"]
+ch9  = [
+    "agentbook[serve]",
+    "httpx>=0.27",
+    "playwright>=1.40",
+    "aiortc>=1.10",
+    # The historical 9-2 add-on transcribes the exact browser-microphone RTP capture.
+    # The 20231106 metadata installs Linux-only Triton unconditionally on
+    # macOS.  The maintained release has platform-correct dependencies.
+    "openai-whisper>=20240930",
+    "torch>=2.2",
+]
+ch10 = ["agentbook[tokens,web]"]              # token counting and browser research
+
+# Everything except the heavy local-training stack, so `all` stays CPU-friendly.
+all = ["agentbook[viz,docs,media,web,browser,serve,rag,mem,mcp,providers,tokens,analysis,solvers,integrations,orchestration,dev]"]
+
+[tool.uv]
+# These GPU stacks are deliberately separate execution environments (see the
+# extra comments above) and currently require disjoint Transformers versions.
+conflicts = [
+    [
+        { extra = "unsloth" },
+        { extra = "vllm" },
+    ],
+]
+# Resolve the lockfile for every platform readers actually use, not just the
+# machine that generated it. Without this, `uv lock` would encode a single
+# platform's resolution and break everyone else.
+environments = [
+    "sys_platform == 'darwin' and platform_machine == 'arm64'",
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+    "sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/bojieli/ai-agent-book"
+Issues = "https://github.com/bojieli/ai-agent-book/issues"
+
+[tool.setuptools.packages.find]
+include = ["agentbook*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+# Apply the exclusions below even when a path is named on the command line.
+# Without this, `ruff format chapter1/web-search-agent/tests` would reformat
+# files the exclusion is meant to protect, because an explicit path overrides
+# discovery-time filtering.
+# Apply the exclusions below even when a path is named on the command line,
+# which is how pre-commit invokes ruff and how the mistake below happens.
+force-exclude = true
+extend-exclude = [
+    "chapter8/gaia-experience/AWorld",
+    "chapter8/browser-use-rpa/browser-use",
+    "chapter2/prompt-engineering/tau_bench",
+    "_web",
+]
+
+[tool.ruff.format]
+# black owns formatting here: these files are checked at its default 88 columns
+# by .github/workflows/web-search-agent-tests.yml, so reflowing them to the 100
+# set above turns that check red.
+#
+# Formatter-only, not an entry in extend-exclude above -- that list is global,
+# so excluding them there would also end `ruff check` coverage for the
+# directory. The trailing /* matters: a bare directory name is not matched here.
+exclude = ["chapter1/web-search-agent/tests/*"]