summaryrefslogtreecommitdiff
path: root/docs/tools-schema.md
diff options
context:
space:
mode:
authortanaka takashi <isazaka@gmail.com>2026-10-20 02:03:54 +0900
committertanaka takashi <isazaka@gmail.com>2026-10-20 02:03:54 +0900
commit4e9c66ee25ed77858985765382f41d0cf22ea588 (patch)
treefcde86704f98035e8dbae8814c07b0cb07d19bdb /docs/tools-schema.md
parentfbda00608e52eef6a0e7b01ce831b1e6c3666909 (diff)
Improve web search region selection and normalize provider resultsHEADmain
Update ddgs to 9.16.0 and keep backend="auto" while preserving the LLM-facing query/max_results inputs and title/href/body result schema. Implementation: - Add OLLAMA_WEB_SEARCH_REGION with auto/us-en/jp-jp values, normalized configuration input, and a clear startup error for unsupported values. - In auto mode, detect kana after NFKC normalization and exclusion of URLs and site:/filetype: tokens. Select jp-jp for kana and us-en otherwise, without modifying the original query or sharing per-call region state. - Preserve href/url and body/snippet fallbacks and normalize None values. - Reject malformed HTTP(S) URLs without DNS lookups or extra requests. - Unwrap known Yahoo redirect URLs before excluding Bing aclick ads. - Represent missing and URL-only titles as empty strings rather than inventing titles from snippets. Preserve remaining provider order and allow fewer results after filtering, without additional searches. - Preserve provider exception propagation and identify ddgs in error logs. Coverage and documentation: - Add 72 regression cases for configuration, region routing, concurrency, public schemas, title/URL/ad boundaries, limits, and search_and_fetch continuation. Update existing provider mocks and log assertions. - Document the region environment setting and result semantics in both READMEs and tools-schema.md; update the changelog. - Keep only a short backend availability caveat in tools-schema.md and remove the temporary backend comparison, design, and validation docs. Validation: - pytest: 222 passed; ruff check . and mypy src/ passed. - uv lock --check and git diff --check passed. - Initial live acceptance: 56 searches plus 3 registry smoke checks; default-region auto succeeded 8/18 times and real ad filtering removed two ads. Stable relevance/title quality targets remain unmet because provider acquisition is unreliable. - Follow-up backend study: 234 comparative searches plus 3 Yahoo response diagnostics. Yahoo led individual backends at 9/18; restricted multi- backend combinations did not outperform the contemporaneous auto control. Authentication, access restrictions, temporary upstream failures, and Yahoo HTML/parser mismatches were observed. Do not claim search reliability is fixed or add backend configuration, custom retries, ranking changes, or challenge bypasses. Running app processes were not restarted; restart is needed to load the changes.
Diffstat (limited to 'docs/tools-schema.md')
-rw-r--r--docs/tools-schema.md11
1 files changed, 7 insertions, 4 deletions
diff --git a/docs/tools-schema.md b/docs/tools-schema.md
index 0b3f556..a3f1f43 100644
--- a/docs/tools-schema.md
+++ b/docs/tools-schema.md
@@ -31,7 +31,7 @@ ollama-web は LLM(Ollama)にツール呼び出し(function calling)機è
| ツール名 | 実装ファイル | 概要 | ページング対応 |
|----------|--------------|------|----------------|
-| `web_search` | [`search.py`](src/ollama_web/tools/search.py:1) | DuckDuckGo による Web 検索 | ❌ 対象外 |
+| `web_search` | [`search.py`](src/ollama_web/tools/search.py:1) | ddgs による複数検索元の Web 検索 | ❌ 対象外 |
| `scrape_url` | [`scrape.py`](src/ollama_web/tools/scrape.py:1) | URL のページ本文抽出 | ✅ 文字オフセット |
| `pdf_to_text` | [`pdf.py`](src/ollama_web/tools/pdf.py:1) | リモート PDF のテキスト抽出 | ✅ ページオフセット |
| `search_and_fetch` | [`fetch.py`](src/ollama_web/tools/fetch.py:1) | ファイル種別検索+取得 | ✅ ファイル単位 |
@@ -41,7 +41,7 @@ ollama-web は LLM(Ollama)にツール呼び出し(function calling)機è
## 1. web_search
- **実装**: [`web_search()`](src/ollama_web/tools/search.py:10)
-- **バックエンド**: [`ddgs`](https://pypi.org/project/ddgs/) (DuckDuckGo Search)
+- **バックエンド**: [`ddgs`](https://pypi.org/project/ddgs/) 9.16.0(ロック版)の `auto`。DuckDuckGo 専用ではなく、利用可能な検索元をライブラリが選択します。
### スキーマ
@@ -56,13 +56,16 @@ ollama-web は LLM(Ollama)にツール呼び出し(function calling)機è
| キー | 型 | 説明 |
|------|----|------|
-| `title` | `str` | 検索結果のタイトル |
+| `title` | `str` | 検索結果のタイトル。空・欠損・URL形式の場合は空文字。本文で補完しない |
| `href` | `str` | 結果URL(`href` が無い場合は `url` をフォールバック) |
| `body` | `str` | スニペット(`body` が無い場合は `snippet` をフォールバック) |
### 設計上の注意点
-- 検索失敗時は例外を握りつぶし空リスト `[]` を返す(チャットループ継続のため)。
+- provider の失敗はログへ記録して例外を伝播し、ツール実行層がエラー応答へ変換します。空クエリや provider が正常に空リストを返した場合とは区別します。
+- region は `OLLAMA_WEB_SEARCH_REGION`(既定 `auto`)から内部選択します。かなを含む検索本文は `jp-jp`、それ以外は `us-en`。固定指定も可能です。公開スキーマには追加しません。
+- backend は `auto` を維持します。検索元の認証・アクセス制限やHTML抽出不整合で取得に失敗する場合があり、今回の比較では複数backend指定による成功率向上も確認できていません。
+- 構文上無効なURLと、Yahoo包装解除後を含む既知のBing広告遷移URLを除外します。残る結果の順序は保持し、除外後の不足分を埋める追加検索はしません。
- **ページング対象外**。検索結果キャッシュが必要になること、DuckDuckGo API 呼び出し回数増でアクセス制限に引っかかりやすくなる懸念から除外。
---