rb-context 0.4.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. rb_context-0.4.5/.gitignore +20 -0
  2. rb_context-0.4.5/LICENSE +21 -0
  3. rb_context-0.4.5/PKG-INFO +182 -0
  4. rb_context-0.4.5/README.md +159 -0
  5. rb_context-0.4.5/pyproject.toml +184 -0
  6. rb_context-0.4.5/src/rb_context/__init__.py +1 -0
  7. rb_context-0.4.5/src/rb_context/_distribution.py +24 -0
  8. rb_context-0.4.5/src/rb_context/cli.py +69 -0
  9. rb_context-0.4.5/src/rb_context/commands/__init__.py +1 -0
  10. rb_context-0.4.5/src/rb_context/commands/auth.py +74 -0
  11. rb_context-0.4.5/src/rb_context/commands/config.py +87 -0
  12. rb_context-0.4.5/src/rb_context/commands/describe.py +34 -0
  13. rb_context-0.4.5/src/rb_context/commands/doctor.py +57 -0
  14. rb_context-0.4.5/src/rb_context/commands/init.py +48 -0
  15. rb_context-0.4.5/src/rb_context/commands/login.py +76 -0
  16. rb_context-0.4.5/src/rb_context/commands/project.py +55 -0
  17. rb_context-0.4.5/src/rb_context/commands/search.py +165 -0
  18. rb_context-0.4.5/src/rb_context/commands/skill.py +138 -0
  19. rb_context-0.4.5/src/rb_context/commands/status.py +35 -0
  20. rb_context-0.4.5/src/rb_context/core/__init__.py +1 -0
  21. rb_context-0.4.5/src/rb_context/core/data_files.py +20 -0
  22. rb_context-0.4.5/src/rb_context/core/deps.py +165 -0
  23. rb_context-0.4.5/src/rb_context/core/errors.py +243 -0
  24. rb_context-0.4.5/src/rb_context/core/models.py +88 -0
  25. rb_context-0.4.5/src/rb_context/core/opencli.py +285 -0
  26. rb_context-0.4.5/src/rb_context/core/services.py +210 -0
  27. rb_context-0.4.5/src/rb_context/core/skills.py +64 -0
  28. rb_context-0.4.5/src/rb_context/core/version.py +89 -0
  29. rb_context-0.4.5/src/rb_context/credentials/__init__.py +1 -0
  30. rb_context-0.4.5/src/rb_context/credentials/health.py +178 -0
  31. rb_context-0.4.5/src/rb_context/credentials/manager.py +119 -0
  32. rb_context-0.4.5/src/rb_context/credentials/ninerouter.py +39 -0
  33. rb_context-0.4.5/src/rb_context/data/SKILL.md +90 -0
  34. rb_context-0.4.5/src/rb_context/data/__init__.py +1 -0
  35. rb_context-0.4.5/src/rb_context/output/__init__.py +279 -0
  36. rb_context-0.4.5/src/rb_context/output/human.py +34 -0
  37. rb_context-0.4.5/src/rb_context/output/json.py +11 -0
  38. rb_context-0.4.5/src/rb_context/providers/__init__.py +67 -0
  39. rb_context-0.4.5/src/rb_context/providers/base.py +204 -0
  40. rb_context-0.4.5/src/rb_context/providers/brave.py +102 -0
  41. rb_context-0.4.5/src/rb_context/providers/exa.py +155 -0
  42. rb_context-0.4.5/src/rb_context/providers/github.py +121 -0
  43. rb_context-0.4.5/src/rb_context/providers/hackernews.py +62 -0
  44. rb_context-0.4.5/src/rb_context/providers/http.py +125 -0
  45. rb_context-0.4.5/src/rb_context/providers/serp.py +128 -0
  46. rb_context-0.4.5/src/rb_context/providers/tavily.py +107 -0
  47. rb_context-0.4.5/src/rb_context/providers/wikipedia.py +64 -0
  48. rb_context-0.4.5/tests/__init__.py +1 -0
  49. rb_context-0.4.5/tests/conftest.py +29 -0
  50. rb_context-0.4.5/tests/contracts/fixtures.yaml +11 -0
  51. rb_context-0.4.5/tests/contracts/schema.json +89 -0
  52. rb_context-0.4.5/tests/contracts/tools-catalog/context.yaml +20 -0
  53. rb_context-0.4.5/tests/data/contracts/windmill-serp.yaml +106 -0
  54. rb_context-0.4.5/tests/data/opencli.schema.json +350 -0
  55. rb_context-0.4.5/tests/help_allowlist.txt +3 -0
  56. rb_context-0.4.5/tests/snapshots/describe.json +1356 -0
  57. rb_context-0.4.5/tests/snapshots/help/auth-login.txt +28 -0
  58. rb_context-0.4.5/tests/snapshots/help/auth-logout.txt +21 -0
  59. rb_context-0.4.5/tests/snapshots/help/auth-status.txt +29 -0
  60. rb_context-0.4.5/tests/snapshots/help/auth.txt +15 -0
  61. rb_context-0.4.5/tests/snapshots/help/config-get.txt +16 -0
  62. rb_context-0.4.5/tests/snapshots/help/config-list.txt +13 -0
  63. rb_context-0.4.5/tests/snapshots/help/config-set.txt +17 -0
  64. rb_context-0.4.5/tests/snapshots/help/config.txt +14 -0
  65. rb_context-0.4.5/tests/snapshots/help/describe.txt +18 -0
  66. rb_context-0.4.5/tests/snapshots/help/doctor.txt +17 -0
  67. rb_context-0.4.5/tests/snapshots/help/init.txt +16 -0
  68. rb_context-0.4.5/tests/snapshots/help/search.txt +106 -0
  69. rb_context-0.4.5/tests/snapshots/help/skill-install.txt +18 -0
  70. rb_context-0.4.5/tests/snapshots/help/skill-list.txt +13 -0
  71. rb_context-0.4.5/tests/snapshots/help/skill.txt +13 -0
  72. rb_context-0.4.5/tests/snapshots/help/status.txt +14 -0
  73. rb_context-0.4.5/tests/test_auth.py +457 -0
  74. rb_context-0.4.5/tests/test_cli.py +406 -0
  75. rb_context-0.4.5/tests/test_contract_runner.py +257 -0
  76. rb_context-0.4.5/tests/test_contracts.py +397 -0
  77. rb_context-0.4.5/tests/test_cost.py +390 -0
  78. rb_context-0.4.5/tests/test_deps.py +150 -0
  79. rb_context-0.4.5/tests/test_describe.py +181 -0
  80. rb_context-0.4.5/tests/test_detach.py +161 -0
  81. rb_context-0.4.5/tests/test_free_sources.py +211 -0
  82. rb_context-0.4.5/tests/test_help.py +495 -0
  83. rb_context-0.4.5/tests/test_http_provider.py +114 -0
  84. rb_context-0.4.5/tests/test_ninerouter.py +105 -0
  85. rb_context-0.4.5/tests/test_project.py +155 -0
  86. rb_context-0.4.5/tests/test_providers.py +56 -0
  87. rb_context-0.4.5/tests/test_scripts.py +54 -0
  88. rb_context-0.4.5/tests/test_search.py +718 -0
  89. rb_context-0.4.5/tests/test_services.py +50 -0
  90. rb_context-0.4.5/tests/test_skills.py +181 -0
@@ -0,0 +1,20 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ *.egg-info/
8
+ .python-version
9
+ .coverage
10
+ htmlcov/
11
+ # mutmut's working copy and results (uv run --group mutation mutmut run)
12
+ mutants/
13
+ # Local env files hold keys: keys never go into the repo (the gate's secret scan)
14
+ .env
15
+ .env.*
16
+ # The root lines Antagor adds
17
+ .DS_Store
18
+ Thumbs.db
19
+ .pdm-build/
20
+ .cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Bolandau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,182 @@
1
+ Metadata-Version: 2.5
2
+ Name: rb-context
3
+ Version: 0.4.5
4
+ Summary: Web context for LLMs through search providers (Exa, Tavily, Brave).
5
+ Project-URL: Repository, https://homeserver.tailee01ab.ts.net:3000/bolandeu/context
6
+ Author: bolandeu
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Python: >=3.14
10
+ Requires-Dist: exa-py>=2.22
11
+ Requires-Dist: httpx[socks]>=0.27
12
+ Requires-Dist: keyring>=25.0
13
+ Requires-Dist: packaging>=24.0
14
+ Requires-Dist: platformdirs>=4.2
15
+ Requires-Dist: pydantic>=2.6
16
+ Requires-Dist: rb-credentials<1,>=0.7.1
17
+ Requires-Dist: requests[socks]>=2.31
18
+ Requires-Dist: rich>=13.7
19
+ Requires-Dist: tavily-python>=0.8
20
+ Requires-Dist: tomli-w>=1.0
21
+ Requires-Dist: typer<0.29,>=0.27
22
+ Description-Content-Type: text/markdown
23
+
24
+ # context
25
+
26
+ Веб-поиск как контекст для LLM через провайдеров [Exa](https://exa.ai),
27
+ [Tavily](https://tavily.com), [Brave Search](https://brave.com/search/api/), выдачу
28
+ Яндекса/Google через CLI [`serp`](https://github.com/bolandeu/serp) и бесплатные источники без ключа:
29
+ Hacker News, GitHub и Википедия.
30
+ Выбранные провайдеры опрашиваются параллельно, результаты приходят в общем
31
+ виде (URL, заголовок, сниппет-контекст) с пометкой, откуда каждый.
32
+ Python-пакет — `rb-context` (импорт `rb_context`), команда в терминале — `context`.
33
+
34
+ ## Установка
35
+
36
+ ```bash
37
+ ```
38
+
39
+ Из git-тега:
40
+
41
+ ```bash
42
+ uv tool install "rb-context @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/context.git@vX.Y.Z"
43
+ ```
44
+
45
+ Вместо `vX.Y.Z` — последний тег релиза. Одинаково на macOS, Linux и Windows; обновление —
46
+ `uv tool upgrade rb-context`.
47
+
48
+ ## Ключи
49
+
50
+ Ключи хранятся в связке ключей ОС (keychain), не в файлах проекта:
51
+
52
+ ```bash
53
+ context auth login -p exa # спросит API-ключ
54
+ context auth login -p tavily
55
+ context auth login -p brave
56
+ context doctor # версия, проект, какие ключи есть
57
+ context auth status --check # каждый ключ: откуда и работает ли (exit 3 — проблема)
58
+ ```
59
+
60
+ Без keychain (CI, headless Linux) — переменные `CONTEXT_EXA_API_KEY`,
61
+ `CONTEXT_TAVILY_API_KEY`, `CONTEXT_BRAVE_API_KEY` (их же читает
62
+ `auth login --non-interactive`).
63
+
64
+ У провайдера `serp` своих ключей в context нет: его доступы (XML River / XMLStock)
65
+ хранит и проверяет сам `serp` — `serp auth login`. `context doctor` спрашивает у него
66
+ `serp auth status`. В `context auth status` serp не входит; exa — обязательный,
67
+ tavily и brave — необязательные (без ключа не ошибка).
68
+
69
+ ## Использование
70
+
71
+ ```bash
72
+ context search "rag chunking strategies" # только exa (по умолчанию)
73
+ context search "запрос" -p tavily # один конкретный
74
+ context search "запрос" -p exa,serp -n 5 # несколько, по 5 результатов
75
+ context search "запрос" -p all # все
76
+ context search "купить диван" -p serp # выдача Яндекса
77
+ context search "купить диван" -p serp --serp-engine google
78
+ context search "купить диван" -p serp --serp-engine yandex,google # оба
79
+ context search "сравнение векторных БД" -p exa --exa-mode deep
80
+ context search "news about uv" --json # для агентов
81
+ context search "sqlite wal" -p hackernews,github,wikipedia --wikipedia-lang en # бесплатные
82
+ context search "typer callback" -p github --github-mode issues
83
+
84
+ # ключи и прокси из локальной базы 9router (пакет rb-9router, не публикуется)
85
+ context search "запрос" -p exa --source 9router # ключ + прокси + схема из 9router
86
+ context search "запрос" -p exa --source 9router --key netparadox # конкретное подключение
87
+ context search "запрос" -p exa --source 9router --rotation least-used
88
+ context search "запрос" -p brave --proxy socks5://u:p@host:1080 # прокси для этого запуска
89
+ ```
90
+
91
+ **Источник ключа.** По умолчанию ключ берётся из окружения и keychain (`--source env`, он же
92
+ умолчание). `--source 9router` берёт ключ из локальной базы 9router, а вместе с ним — прокси,
93
+ привязанный к этому ключу, и схему ротации из настроек 9router (`providerStrategies`).
94
+ `--key <имя>` выбирает конкретное подключение вместо схемы, `--rotation` перебивает схему,
95
+ `--proxy` перебивает прокси ключа. Живых ключей нет — ошибка аргументов, молчаливого отката
96
+ на окружение нет.
97
+
98
+ **Лимиты.** Каждый опрошенный провайдер тратит свой лимит, поэтому без `-p` опрашивается
99
+ только один — `exa`, а все сразу — только явно, `-p all`. Свой набор по умолчанию для
100
+ проекта: `context init`, затем `context config set providers exa,serp` (`all` — все).
101
+ Упавший провайдер не мешает остальным: его ошибка в `sources[].error`. Exa, Tavily и Brave —
102
+ только бесплатные лимиты: исчерпан — `QUOTA_EXHAUSTED` («лимит исчерпан»), на платный тариф
103
+ context не переходит.
104
+
105
+ **Стоимость** (`--json`): у каждого вызова в `sources[]` — `billable_requests`, `cost`,
106
+ `cost_currency` (RUB), `cost_source`, `would_cost`/`would_cost_unit`; в конверте `cost_total` и
107
+ `billable_requests_total`. Exa/Tavily/Brave — `cost_source: "free_tier"`, cost 0; что вызов стоил
108
+ бы по словам провайдера — `would_cost` (Exa `costDollars` в USD, Tavily — кредиты, Brave — null),
109
+ в cost не входит. serp платный — его cost и `cost_source` берутся из конверта serp; не отдал
110
+ (`serp snippets` пока без стоимости) — cost и `cost_total` null с предупреждением в stderr.
111
+ Проверка ключа Brave (`auth status --check`) — поиск `count=1`, тратит 1 запрос лимита
112
+ (бесплатной у Brave нет): не запускать по расписанию.
113
+
114
+ Режимы: `--exa-mode` (auto, fast, instant, deep-lite, deep, deep-reasoning),
115
+ `--tavily-mode` (basic, advanced, fast, ultra-fast), `--serp-engine` (yandex, google или оба —
116
+ `yandex,google`; по умолчанию yandex), `--github-mode` (repositories, issues, code — code только
117
+ с токеном), `--wikipedia-lang` (ru, en). У Brave и Hacker News режимов нет.
118
+
119
+ **Бесплатные источники.** `hackernews` (API поиска Algolia) и `wikipedia` (MediaWiki API) —
120
+ без ключа и без лимита: cost 0, `billable_requests` 0. `github` — REST search; токен
121
+ необязателен (`context auth login -p github`, `CONTEXT_GITHUB_API_KEY` или `GITHUB_TOKEN`): без
122
+ него 10 поисков в минуту вместо 30 и нет поиска по коду. Кончился минутный лимит —
123
+ `QUOTA_EXHAUSTED`.
124
+
125
+ ## Почему такие библиотеки
126
+
127
+ | Провайдер | Как подключён | Почему |
128
+ | --- | --- | --- |
129
+ | Exa | официальный SDK [`exa-py`](https://github.com/exa-labs/exa-py) | поддерживается Exa, типы ответа; сниппет — `highlights` (рекомендация Exa для LLM-контекста) |
130
+ | Tavily | официальный SDK [`tavily-python`](https://github.com/tavily-ai/tavily-python) | поддерживается Tavily, свои классы ошибок (ключ / лимит) |
131
+ | Brave | REST через `providers/http.py` (`HttpProvider` на httpx) | официального Python SDK нет; сторонние обёртки ничего не дают поверх одного GET |
132
+ | Hacker News, GitHub, Википедия | REST через `HttpProvider` | открытые API (Algolia, GitHub REST, MediaWiki); SDK ради одного GET не нужен |
133
+ | serp (Яндекс/Google) | вызов установленного CLI `serp snippets --json` (subprocess) | **пакет `rb-serp` в зависимостях нет, и это намеренно** — см. ниже |
134
+
135
+ **Почему serp — через CLI, а не библиотекой `rb-serp`.** `--json` у serp — его стабильный
136
+ контракт для агентов (конверт, коды ошибок), ключи XML River / XMLStock остаются в serp и
137
+ не дублируются, версии двух пакетов не связаны. Импорт `rb-serp` потребовал бы зависимость
138
+ от приватного git-репозитория в `uv.lock` (CI её не скачает) и синхронных релизов.
139
+ Цена — serp должен быть установлен отдельно, не старше 0.7.2 (`MIN_SERP` в
140
+ `providers/serp.py`, проверяется по `serp --version`):
141
+ `uv tool install "git+https://github.com/bolandeu/serp.git"`; без него или со старым провайдер
142
+ `serp` отвечает `DEPENDENCY_TOO_OLD` с командой установки/обновления в `action`, остальные работают.
143
+
144
+ Отвергнуто: LangChain / LlamaIndex tools для этих сервисов — тяжёлая зависимость
145
+ ради трёх вызовов, и ошибки всё равно пришлось бы переводить в коды CLI. Исключения
146
+ SDK переводятся в `AuthRequired` / `ProviderError` в самих модулях `providers/`,
147
+ выше них никто не видит вендорских ошибок.
148
+
149
+ ## Разработка
150
+
151
+ ```bash
152
+ uv sync
153
+ uv run context --help
154
+ # гейт перед коммитом — `gate check` на этой машине (команда — `[publish] gate_command`
155
+ # в `.agents/antagor/antagor.toml`); workflow его не гоняет
156
+ uv run pytest --snapshot-update # после правки справки команды; смотреть tests/snapshots/help/
157
+ ```
158
+
159
+ Гейт: `uv lock --check`, ruff (с правилами безопасности `S`), ty, pytest с порогом
160
+ покрытия, снапшоты `--help`, форма `auth status`, контракты потребителей, сборка и установка
161
+ колеса во временный venv; `osv-scanner` и `gitleaks`, если они установлены.
162
+
163
+ Новый провайдер: модуль в `src/rb_context/providers/` с подклассом `SearchProvider`
164
+ (`name`, `required`, `search`, `health_check`) и строка в `PROVIDERS` (`providers/__init__.py`).
165
+
166
+ ## Релиз
167
+
168
+ Версия — git-тег `vX.Y.Z`, строки `version =` в `pyproject.toml` нет. Релиз делает
169
+ `antagor publish` (гейт, `CHANGELOG.md`, тег, push); `CHANGELOG.md` руками не правится.
170
+
171
+ ## Архитектура
172
+
173
+ Проект следует архитектуре шаблона `cli-generator`:
174
+
175
+ - `src/rb_context/commands/` — только разбор аргументов.
176
+ - `src/rb_context/core/` — сервисы, модели, ошибки.
177
+ - `src/rb_context/providers/` — Exa, Tavily, Brave, serp.
178
+ - `src/rb_context/credentials/` — ключи: связка ключей ОС и env.
179
+ - `src/rb_context/output/` — человеческий вывод и `--json`.
180
+
181
+ Памятка для агентов — `src/rb_context/data/SKILL.md`: `context skill install`
182
+ ставит её в AI-инструмент, `context --ai` печатает.
@@ -0,0 +1,159 @@
1
+ # context
2
+
3
+ Веб-поиск как контекст для LLM через провайдеров [Exa](https://exa.ai),
4
+ [Tavily](https://tavily.com), [Brave Search](https://brave.com/search/api/), выдачу
5
+ Яндекса/Google через CLI [`serp`](https://github.com/bolandeu/serp) и бесплатные источники без ключа:
6
+ Hacker News, GitHub и Википедия.
7
+ Выбранные провайдеры опрашиваются параллельно, результаты приходят в общем
8
+ виде (URL, заголовок, сниппет-контекст) с пометкой, откуда каждый.
9
+ Python-пакет — `rb-context` (импорт `rb_context`), команда в терминале — `context`.
10
+
11
+ ## Установка
12
+
13
+ ```bash
14
+ ```
15
+
16
+ Из git-тега:
17
+
18
+ ```bash
19
+ uv tool install "rb-context @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/context.git@vX.Y.Z"
20
+ ```
21
+
22
+ Вместо `vX.Y.Z` — последний тег релиза. Одинаково на macOS, Linux и Windows; обновление —
23
+ `uv tool upgrade rb-context`.
24
+
25
+ ## Ключи
26
+
27
+ Ключи хранятся в связке ключей ОС (keychain), не в файлах проекта:
28
+
29
+ ```bash
30
+ context auth login -p exa # спросит API-ключ
31
+ context auth login -p tavily
32
+ context auth login -p brave
33
+ context doctor # версия, проект, какие ключи есть
34
+ context auth status --check # каждый ключ: откуда и работает ли (exit 3 — проблема)
35
+ ```
36
+
37
+ Без keychain (CI, headless Linux) — переменные `CONTEXT_EXA_API_KEY`,
38
+ `CONTEXT_TAVILY_API_KEY`, `CONTEXT_BRAVE_API_KEY` (их же читает
39
+ `auth login --non-interactive`).
40
+
41
+ У провайдера `serp` своих ключей в context нет: его доступы (XML River / XMLStock)
42
+ хранит и проверяет сам `serp` — `serp auth login`. `context doctor` спрашивает у него
43
+ `serp auth status`. В `context auth status` serp не входит; exa — обязательный,
44
+ tavily и brave — необязательные (без ключа не ошибка).
45
+
46
+ ## Использование
47
+
48
+ ```bash
49
+ context search "rag chunking strategies" # только exa (по умолчанию)
50
+ context search "запрос" -p tavily # один конкретный
51
+ context search "запрос" -p exa,serp -n 5 # несколько, по 5 результатов
52
+ context search "запрос" -p all # все
53
+ context search "купить диван" -p serp # выдача Яндекса
54
+ context search "купить диван" -p serp --serp-engine google
55
+ context search "купить диван" -p serp --serp-engine yandex,google # оба
56
+ context search "сравнение векторных БД" -p exa --exa-mode deep
57
+ context search "news about uv" --json # для агентов
58
+ context search "sqlite wal" -p hackernews,github,wikipedia --wikipedia-lang en # бесплатные
59
+ context search "typer callback" -p github --github-mode issues
60
+
61
+ # ключи и прокси из локальной базы 9router (пакет rb-9router, не публикуется)
62
+ context search "запрос" -p exa --source 9router # ключ + прокси + схема из 9router
63
+ context search "запрос" -p exa --source 9router --key netparadox # конкретное подключение
64
+ context search "запрос" -p exa --source 9router --rotation least-used
65
+ context search "запрос" -p brave --proxy socks5://u:p@host:1080 # прокси для этого запуска
66
+ ```
67
+
68
+ **Источник ключа.** По умолчанию ключ берётся из окружения и keychain (`--source env`, он же
69
+ умолчание). `--source 9router` берёт ключ из локальной базы 9router, а вместе с ним — прокси,
70
+ привязанный к этому ключу, и схему ротации из настроек 9router (`providerStrategies`).
71
+ `--key <имя>` выбирает конкретное подключение вместо схемы, `--rotation` перебивает схему,
72
+ `--proxy` перебивает прокси ключа. Живых ключей нет — ошибка аргументов, молчаливого отката
73
+ на окружение нет.
74
+
75
+ **Лимиты.** Каждый опрошенный провайдер тратит свой лимит, поэтому без `-p` опрашивается
76
+ только один — `exa`, а все сразу — только явно, `-p all`. Свой набор по умолчанию для
77
+ проекта: `context init`, затем `context config set providers exa,serp` (`all` — все).
78
+ Упавший провайдер не мешает остальным: его ошибка в `sources[].error`. Exa, Tavily и Brave —
79
+ только бесплатные лимиты: исчерпан — `QUOTA_EXHAUSTED` («лимит исчерпан»), на платный тариф
80
+ context не переходит.
81
+
82
+ **Стоимость** (`--json`): у каждого вызова в `sources[]` — `billable_requests`, `cost`,
83
+ `cost_currency` (RUB), `cost_source`, `would_cost`/`would_cost_unit`; в конверте `cost_total` и
84
+ `billable_requests_total`. Exa/Tavily/Brave — `cost_source: "free_tier"`, cost 0; что вызов стоил
85
+ бы по словам провайдера — `would_cost` (Exa `costDollars` в USD, Tavily — кредиты, Brave — null),
86
+ в cost не входит. serp платный — его cost и `cost_source` берутся из конверта serp; не отдал
87
+ (`serp snippets` пока без стоимости) — cost и `cost_total` null с предупреждением в stderr.
88
+ Проверка ключа Brave (`auth status --check`) — поиск `count=1`, тратит 1 запрос лимита
89
+ (бесплатной у Brave нет): не запускать по расписанию.
90
+
91
+ Режимы: `--exa-mode` (auto, fast, instant, deep-lite, deep, deep-reasoning),
92
+ `--tavily-mode` (basic, advanced, fast, ultra-fast), `--serp-engine` (yandex, google или оба —
93
+ `yandex,google`; по умолчанию yandex), `--github-mode` (repositories, issues, code — code только
94
+ с токеном), `--wikipedia-lang` (ru, en). У Brave и Hacker News режимов нет.
95
+
96
+ **Бесплатные источники.** `hackernews` (API поиска Algolia) и `wikipedia` (MediaWiki API) —
97
+ без ключа и без лимита: cost 0, `billable_requests` 0. `github` — REST search; токен
98
+ необязателен (`context auth login -p github`, `CONTEXT_GITHUB_API_KEY` или `GITHUB_TOKEN`): без
99
+ него 10 поисков в минуту вместо 30 и нет поиска по коду. Кончился минутный лимит —
100
+ `QUOTA_EXHAUSTED`.
101
+
102
+ ## Почему такие библиотеки
103
+
104
+ | Провайдер | Как подключён | Почему |
105
+ | --- | --- | --- |
106
+ | Exa | официальный SDK [`exa-py`](https://github.com/exa-labs/exa-py) | поддерживается Exa, типы ответа; сниппет — `highlights` (рекомендация Exa для LLM-контекста) |
107
+ | Tavily | официальный SDK [`tavily-python`](https://github.com/tavily-ai/tavily-python) | поддерживается Tavily, свои классы ошибок (ключ / лимит) |
108
+ | Brave | REST через `providers/http.py` (`HttpProvider` на httpx) | официального Python SDK нет; сторонние обёртки ничего не дают поверх одного GET |
109
+ | Hacker News, GitHub, Википедия | REST через `HttpProvider` | открытые API (Algolia, GitHub REST, MediaWiki); SDK ради одного GET не нужен |
110
+ | serp (Яндекс/Google) | вызов установленного CLI `serp snippets --json` (subprocess) | **пакет `rb-serp` в зависимостях нет, и это намеренно** — см. ниже |
111
+
112
+ **Почему serp — через CLI, а не библиотекой `rb-serp`.** `--json` у serp — его стабильный
113
+ контракт для агентов (конверт, коды ошибок), ключи XML River / XMLStock остаются в serp и
114
+ не дублируются, версии двух пакетов не связаны. Импорт `rb-serp` потребовал бы зависимость
115
+ от приватного git-репозитория в `uv.lock` (CI её не скачает) и синхронных релизов.
116
+ Цена — serp должен быть установлен отдельно, не старше 0.7.2 (`MIN_SERP` в
117
+ `providers/serp.py`, проверяется по `serp --version`):
118
+ `uv tool install "git+https://github.com/bolandeu/serp.git"`; без него или со старым провайдер
119
+ `serp` отвечает `DEPENDENCY_TOO_OLD` с командой установки/обновления в `action`, остальные работают.
120
+
121
+ Отвергнуто: LangChain / LlamaIndex tools для этих сервисов — тяжёлая зависимость
122
+ ради трёх вызовов, и ошибки всё равно пришлось бы переводить в коды CLI. Исключения
123
+ SDK переводятся в `AuthRequired` / `ProviderError` в самих модулях `providers/`,
124
+ выше них никто не видит вендорских ошибок.
125
+
126
+ ## Разработка
127
+
128
+ ```bash
129
+ uv sync
130
+ uv run context --help
131
+ # гейт перед коммитом — `gate check` на этой машине (команда — `[publish] gate_command`
132
+ # в `.agents/antagor/antagor.toml`); workflow его не гоняет
133
+ uv run pytest --snapshot-update # после правки справки команды; смотреть tests/snapshots/help/
134
+ ```
135
+
136
+ Гейт: `uv lock --check`, ruff (с правилами безопасности `S`), ty, pytest с порогом
137
+ покрытия, снапшоты `--help`, форма `auth status`, контракты потребителей, сборка и установка
138
+ колеса во временный venv; `osv-scanner` и `gitleaks`, если они установлены.
139
+
140
+ Новый провайдер: модуль в `src/rb_context/providers/` с подклассом `SearchProvider`
141
+ (`name`, `required`, `search`, `health_check`) и строка в `PROVIDERS` (`providers/__init__.py`).
142
+
143
+ ## Релиз
144
+
145
+ Версия — git-тег `vX.Y.Z`, строки `version =` в `pyproject.toml` нет. Релиз делает
146
+ `antagor publish` (гейт, `CHANGELOG.md`, тег, push); `CHANGELOG.md` руками не правится.
147
+
148
+ ## Архитектура
149
+
150
+ Проект следует архитектуре шаблона `cli-generator`:
151
+
152
+ - `src/rb_context/commands/` — только разбор аргументов.
153
+ - `src/rb_context/core/` — сервисы, модели, ошибки.
154
+ - `src/rb_context/providers/` — Exa, Tavily, Brave, serp.
155
+ - `src/rb_context/credentials/` — ключи: связка ключей ОС и env.
156
+ - `src/rb_context/output/` — человеческий вывод и `--json`.
157
+
158
+ Памятка для агентов — `src/rb_context/data/SKILL.md`: `context skill install`
159
+ ставит её в AI-инструмент, `context --ai` печатает.
@@ -0,0 +1,184 @@
1
+ [project]
2
+ name = "rb-context"
3
+ # Version comes from the git tag vX.Y.Z (uv-dynamic-versioning) — never add `version =`.
4
+ dynamic = ["version"]
5
+ description = "Web context for LLMs through search providers (Exa, Tavily, Brave)."
6
+ readme = "README.md"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "bolandeu" }]
10
+ requires-python = ">=3.14"
11
+ dependencies = [
12
+ "rb-credentials>=0.7.1,<1",
13
+ "typer>=0.27,<0.29",
14
+ "rich>=13.7",
15
+ "pydantic>=2.6",
16
+ "tomli-w>=1.0",
17
+ "platformdirs>=4.2",
18
+ "httpx[socks]>=0.27", # socks5-прокси из 9router (httpx берёт socksio)
19
+ "requests[socks]>=2.31", # то же для exa/tavily: PySocks
20
+ "packaging>=24.0",
21
+ "exa-py>=2.22",
22
+ "tavily-python>=0.8",
23
+ "keyring>=25.0",
24
+ ]
25
+
26
+ [project.scripts]
27
+ context = "rb_context.cli:main"
28
+
29
+ [project.urls]
30
+ Repository = "https://homeserver.tailee01ab.ts.net:3000/bolandeu/context"
31
+
32
+ [build-system]
33
+ requires = ["hatchling", "uv-dynamic-versioning"]
34
+ build-backend = "hatchling.build"
35
+
36
+ [tool.hatch.version]
37
+ source = "uv-dynamic-versioning"
38
+
39
+ [tool.uv-dynamic-versioning]
40
+ vcs = "git"
41
+ style = "pep440"
42
+ fallback-version = "0.0.0"
43
+
44
+ [tool.uv]
45
+ # Rebuild the editable install when a commit or tag moves, so `--version` follows the tag.
46
+ cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
47
+
48
+ # Siblings resolve from disk: a version range in `dependencies` plus a `path` source, never an index.
49
+ [tool.uv.sources]
50
+ rb-credentials = { path = "../rb-credentials", editable = true }
51
+ rb-9router = { path = "../rb-9router", editable = true } # private, never published
52
+
53
+ [tool.hatch.build.targets.sdist]
54
+ # What a release must not carry: the agent's own files, the forge configs and the dev tooling. The wheel is
55
+ # narrow already (`packages = ["src/<pkg>"]`); this is about the sdist, which is otherwise a copy of the repo.
56
+ exclude = [
57
+ "/.agents",
58
+ "/.claude",
59
+ "/.claude-plugin",
60
+ "/.gitea",
61
+ "/.github",
62
+ "/docs",
63
+ "/scripts",
64
+ "/uv.lock",
65
+ "/AGENTS.md",
66
+ "/CLAUDE.md",
67
+ "/CODING_STANDARDS.md",
68
+ "/CONTEXT.md",
69
+ "/.copier-answers.yml",
70
+ "^\\.gitignore$",
71
+ "/.gitleaks.toml",
72
+ ]
73
+
74
+ [tool.hatch.build.targets.wheel]
75
+ packages = ["src/rb_context"]
76
+
77
+ [tool.hatch.build.targets.wheel.force-include]
78
+ # The installed CLI reads [[tool.rb.external]] from here (core/deps.py).
79
+ "pyproject.toml" = "rb_context/_pyproject.toml"
80
+
81
+ [dependency-groups]
82
+ # Mutation testing, run now and then and before big releases — not in the gate:
83
+ # `uv run --group mutation mutmut run`, then `mutmut results` / `mutmut browse`.
84
+ # Needs fork(): macOS/Linux (WSL on Windows). Settings: [tool.mutmut] below.
85
+ mutation = ["mutmut>=3.3"]
86
+ dev = [
87
+ "jsonschema>=4.23",
88
+ "pytest>=8.0",
89
+ "pyyaml>=6.0", # .copier-answers.yml, the CI workflow, tests/contracts/*.yaml
90
+ "pytest-cov>=5.0",
91
+ "ruff>=0.6",
92
+ "syrupy>=4.8",
93
+ "ty>=0.0.80",
94
+ "rb-9router", # dev only: keys and proxies from 9router's local database (`--source 9router`)
95
+ ]
96
+
97
+ # External (non-Python) dependencies — every CLI this tool runs (require_cli,
98
+ # shutil.which, subprocess with a literal program, npx). The gate checks this
99
+ # list against the code both ways; doctor and require_cli read it at runtime;
100
+ # the tools catalog reads it (the Standard, Technology).
101
+ # [[tool.rb.external]]
102
+ # name = "ffmpeg"
103
+ # required = true # false: the tool works without it (doctor stays healthy)
104
+ # min_version = "6.0" # optional
105
+ # check = "ffmpeg -version" # prints the version; default "<name> --version"
106
+ # why = "transcodes the downloaded videos"
107
+ # detect = false # run via an injected runner / absolute path the gate can't see
108
+ # dist = "rb-serp" # for one of our CLIs: its distribution (default rb-<name>)
109
+ # url = "https://github.com/bolandeu/serp" # its repo: DEPENDENCY_TOO_OLD then prints a pinned install
110
+
111
+ [[tool.rb.external]]
112
+ name = "serp"
113
+ required = false
114
+ min_version = "0.7.2"
115
+ why = "провайдер serp: выдача Яндекса/Google со сниппетами (`serp snippets --json`)"
116
+ dist = "rb-serp"
117
+ url = "https://github.com/bolandeu/serp"
118
+
119
+ # Where sysadmin's tool-updater installs this tool after its first tag. The
120
+ # installation is sysadmin's; this section only says where. homeserver: users
121
+ # to install for (empty = build and publish only); mac: install on the Mac.
122
+ # extras (optional): the extras to install with, e.g. extras = ["browser"].
123
+ [tool.rb.install]
124
+ homeserver = ["rbtools"]
125
+ mac = true
126
+
127
+ [tool.cli-generator]
128
+ # Where scripts/check_command_docstrings.py (called by the project's checks)
129
+ # looks for commands: a glob or a list of globs, relative to the repo root.
130
+ commands = ["src/rb_context/commands/*.py"]
131
+ # gate check (the gate): extras to install before ruff/ty/pytest.
132
+ # gate_extras = ["browser"]
133
+
134
+ [tool.pytest.ini_options]
135
+ # Only tests/: mutmut leaves a copy of the tree in mutants/.
136
+ testpaths = ["tests"]
137
+ addopts = "--cov --cov-report=term-missing:skip-covered"
138
+ # tests/test_help.py keeps help snapshots at tests/snapshots/help/<command>.txt
139
+ # (the Standard, Commands), not in syrupy's own `__snapshots__/<test file>/` layout, so
140
+ # syrupy warns it "can not relate" each file to its test. It can — by name.
141
+ filterwarnings = ["ignore:(?s).*Can not relate snapshot:UserWarning"]
142
+
143
+ [tool.mutmut]
144
+ source_paths = ["src/rb_context"]
145
+ also_copy = ["scripts/", "pyproject.toml"] # tests read them (test_scripts.py, the distribution checks)
146
+ pytest_add_cli_args = ["--no-cov"] # fail_under would kill every mutant
147
+ # only_mutate = ["*/core/normalize.py"] # one module at a time on a big tool
148
+
149
+ [tool.coverage.run]
150
+ source = ["src"]
151
+ # sysmon (default on 3.14) keeps a record per recompiled code object; Typer recompiles annotations on every invoke, so memory grows.
152
+ core = "ctrace"
153
+
154
+ [tool.coverage.report]
155
+ # The template ships at ~94%; keep the bar where it is instead of letting
156
+ # new commands land untested. Raise it, never lower it.
157
+ fail_under = 90
158
+ show_missing = true
159
+
160
+ [tool.ty.terminal]
161
+ # Only errors fail the gate; recent ty (>= 0.0.84) otherwise exits 1 on warnings too.
162
+ # Legacy code that can't be fixed yet: downgrade specific rules instead of
163
+ # ignoring them, e.g. [tool.ty.rules] possibly-unbound-attribute = "warn".
164
+ error-on-warning = false
165
+
166
+ [tool.ruff]
167
+ line-length = 120
168
+
169
+ [tool.ruff.lint]
170
+ select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF", "S", "T20", "TID251"]
171
+ # Тексты и комментарии на русском: кириллица — не «похожие символы».
172
+ ignore = ["RUF001", "RUF002", "RUF003"]
173
+
174
+ [tool.ruff.lint.per-file-ignores]
175
+ "tests/*" = ["S101", "T201", "TID251"] # assert is the point of a test; print in code strings; httpx for mocks
176
+ "scripts/*" = ["S603", "S607", "T201"] # subprocess with fixed argv lists (git, uv), no shell; scripts print to the console
177
+ "src/*/providers/*" = ["TID251"] # external APIs live here
178
+
179
+ [tool.ruff.lint.flake8-tidy-imports.banned-api]
180
+ "httpx".msg = "Call external APIs through providers/ (subclass providers.HttpProvider)."
181
+
182
+ [tool.ruff.lint.flake8-bugbear]
183
+ # Typer's `param: T = typer.Option(...)` style is a call in a default on purpose.
184
+ extend-immutable-calls = ["typer.Option", "typer.Argument"]
@@ -0,0 +1 @@
1
+ """The package: its modules are the CLI (`cli`), its commands, the output and the core they share."""
@@ -0,0 +1,24 @@
1
+ """The distribution name and the tool namespace copier writes from its answers, because an editable install cannot map
2
+ this import package to its distribution at runtime.
3
+ """
4
+
5
+ # Rendered by copier from the `dist_name` answer: the [project] name in
6
+ # pyproject.toml (`rb-<slug>`, the Standard, Technology), which may differ from this
7
+ # import package's name. importlib.metadata finds this package's version,
8
+ # summary and console script by it; an editable install (`uv sync`) can't be
9
+ # mapped from package to distribution at runtime, so it is written down here.
10
+ # tests/test_cli.py fails if it drifts from pyproject.toml.
11
+ DIST_NAME = "rb-context"
12
+ # The previous distribution name during a rename: an install made
13
+ # under it (not yet reinstalled) still finds its own version. Drop it once
14
+ # every machine has the new name.
15
+ DIST_NAME_LEGACY: str | None = None
16
+ # The command name (`cli_name`) as an identifier: the namespace of this tool's
17
+ # shared-database names (core/db.py) — table prefix `<TOOL>_`, env var
18
+ # `<TOOL>_DATABASE_URL`, Alembic table `alembic_version_<TOOL>`. Written down,
19
+ # not derived at runtime: a bare source run falls back to the package name,
20
+ # and a table name must never depend on how the tool was started.
21
+ TOOL = "context"
22
+ # The cli-generator release this project was generated or last updated from
23
+ # (copier's `_commit`), for `describe --json`; None for a project not made by copier.
24
+ TEMPLATE_VERSION: str | None = "v1.27.3"