indagar 0.2.0__tar.gz → 0.2.1__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.
- {indagar-0.2.0 → indagar-0.2.1}/.env.example +7 -0
- {indagar-0.2.0 → indagar-0.2.1}/AGENTS.md +4 -0
- {indagar-0.2.0 → indagar-0.2.1}/CHANGELOG.md +14 -0
- {indagar-0.2.0 → indagar-0.2.1}/PKG-INFO +32 -7
- {indagar-0.2.0 → indagar-0.2.1}/README.md +31 -6
- {indagar-0.2.0 → indagar-0.2.1}/SPEC.md +22 -8
- {indagar-0.2.0 → indagar-0.2.1}/pyproject.toml +1 -1
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/__init__.py +1 -1
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/cli.py +59 -2
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/config.py +30 -0
- indagar-0.2.1/src/indagar/estimate.py +112 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/llm/anthropic.py +10 -1
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/llm/factory.py +17 -3
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/llm/openai_compatible.py +10 -1
- indagar-0.2.1/src/indagar/rate_limit.py +99 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_config.py +16 -0
- indagar-0.2.1/tests/test_estimate.py +69 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_llm.py +65 -1
- indagar-0.2.1/tests/test_rate_limit.py +123 -0
- {indagar-0.2.0 → indagar-0.2.1}/.github/workflows/ci.yml +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/.gitignore +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/LICENSE +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/__main__.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/citations.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/llm/__init__.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/llm/base.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/models.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/__init__.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/deep.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/extract.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/gaps.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/json_utils.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/loop.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/planner.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/reader.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/research/synthesize.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/search/__init__.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/search/base.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/search/chain.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/search/providers.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/store.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/src/indagar/usage.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_chain.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_citations.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_deep.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_extract.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_gaps.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_loop.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_planner.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_reader.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_synthesize.py +0 -0
- {indagar-0.2.0 → indagar-0.2.1}/tests/test_usage.py +0 -0
|
@@ -24,6 +24,13 @@ INDAGAR_WRITER_MODEL=
|
|
|
24
24
|
INDAGAR_LLM_MAX_TOKENS=1024
|
|
25
25
|
INDAGAR_LLM_TEMPERATURE=0.2
|
|
26
26
|
INDAGAR_LLM_TIMEOUT=60
|
|
27
|
+
INDAGAR_LLM_MAX_RETRIES=2
|
|
28
|
+
INDAGAR_RETRY_BASE_SECONDS=0.5
|
|
29
|
+
INDAGAR_LLM_MIN_INTERVAL=0
|
|
30
|
+
|
|
31
|
+
# Optional user-supplied rates for estimates, USD per million tokens.
|
|
32
|
+
# INDAGAR_INPUT_COST_PER_MTOK=
|
|
33
|
+
# INDAGAR_OUTPUT_COST_PER_MTOK=
|
|
27
34
|
|
|
28
35
|
ANTHROPIC_API_KEY=
|
|
29
36
|
# ANTHROPIC_BASE_URL=https://api.anthropic.com
|
|
@@ -12,6 +12,8 @@ pytest -q
|
|
|
12
12
|
indagar doctor
|
|
13
13
|
indagar llm "Say hello" --role writer
|
|
14
14
|
indagar research "What is X?" --llm --depth 0 --max-sources 3
|
|
15
|
+
indagar estimate "What is X?" --max-sources 3 --depth 0
|
|
16
|
+
indagar research "What is X?" --llm --dry-run
|
|
15
17
|
```
|
|
16
18
|
|
|
17
19
|
## Invariants
|
|
@@ -26,6 +28,8 @@ indagar research "What is X?" --llm --depth 0 --max-sources 3
|
|
|
26
28
|
- Synthesis may cite only ledger IDs. Unknown IDs are a hard error and trigger
|
|
27
29
|
the evidence-table fallback.
|
|
28
30
|
- Do not store raw LLM prompts or provider payloads in run records. Store the final report, citations, source-read status, and usage.
|
|
31
|
+
- Retry only transient failures (`408`, `425`, `429`, `5xx`, transport errors) and honour `Retry-After`.
|
|
32
|
+
- Estimates are rough upper bounds. Cost estimates use user-supplied per-million-token rates, not built-in pricing.
|
|
29
33
|
- Web and media sources are not peer-reviewed and must not be labelled as such.
|
|
30
34
|
- Keep the CLI flow: `doctor` is offline, `search` is retrieval-only, `research`
|
|
31
35
|
writes a run record and a report or dossier.
|
|
@@ -3,6 +3,20 @@
|
|
|
3
3
|
All notable changes to Indagar are documented here. The format follows Keep a
|
|
4
4
|
Changelog, and the project uses semantic versioning.
|
|
5
5
|
|
|
6
|
+
## [0.2.1] - 2026-11-21
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
- `indagar estimate` and `research --dry-run` for offline pre-run budgets.
|
|
11
|
+
- Optional input/output cost rates for dollar estimates.
|
|
12
|
+
- LLM retry/backoff on `429`, `5xx`, and transport errors, with `Retry-After`.
|
|
13
|
+
- Shared minimum interval between LLM calls.
|
|
14
|
+
- Tests for retries, rate limiting, estimates, and retry/cost settings.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- `indagar doctor` reports retry count and minimum request interval.
|
|
19
|
+
|
|
6
20
|
## [0.2.0] - 2026-11-21
|
|
7
21
|
|
|
8
22
|
### Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: indagar
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: Deep research from the command line: plan, search, read, and synthesize with citations.
|
|
5
5
|
Author: Michael Borck
|
|
6
6
|
License: MIT
|
|
@@ -34,6 +34,13 @@ Phase 1 core loop is implemented. `research` is retrieval-only by default;
|
|
|
34
34
|
adding `--llm` turns on LLM planning, source reading, grounded quote
|
|
35
35
|
extraction, a bounded gap check, and citation-checked synthesis.
|
|
36
36
|
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
uv pip install indagar
|
|
41
|
+
# or: pip install indagar
|
|
42
|
+
```
|
|
43
|
+
|
|
37
44
|
## Quick start
|
|
38
45
|
|
|
39
46
|
```bash
|
|
@@ -51,6 +58,12 @@ indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
|
51
58
|
# Full Phase 1 loop; requires an LLM provider and model.
|
|
52
59
|
indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
53
60
|
--llm --max-sources 10 --depth 1
|
|
61
|
+
|
|
62
|
+
# See the rough budget before running.
|
|
63
|
+
indagar estimate "Does retrieval augmented generation reduce hallucination?" \
|
|
64
|
+
--max-sources 10 --depth 1
|
|
65
|
+
indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
66
|
+
--llm --dry-run
|
|
54
67
|
```
|
|
55
68
|
|
|
56
69
|
If the checkout is on an exFAT drive, create the virtual environment on a
|
|
@@ -122,6 +135,11 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
122
135
|
| `INDAGAR_LLM_MAX_TOKENS` | Tokens per call. Default `1024` |
|
|
123
136
|
| `INDAGAR_LLM_TEMPERATURE` | Sampling temperature. Default `0.2` |
|
|
124
137
|
| `INDAGAR_LLM_TIMEOUT` | LLM request timeout in seconds. Default `60` |
|
|
138
|
+
| `INDAGAR_LLM_MAX_RETRIES` | Retries on 429/5xx/transport errors. Default `2` |
|
|
139
|
+
| `INDAGAR_RETRY_BASE_SECONDS` | Exponential backoff base. Default `0.5` |
|
|
140
|
+
| `INDAGAR_LLM_MIN_INTERVAL` | Minimum seconds between LLM calls. Default `0` |
|
|
141
|
+
| `INDAGAR_INPUT_COST_PER_MTOK` | Optional input USD per million tokens |
|
|
142
|
+
| `INDAGAR_OUTPUT_COST_PER_MTOK` | Optional output USD per million tokens |
|
|
125
143
|
| `INDAGAR_MAX_SOURCES` | Sources per run. Default `12` |
|
|
126
144
|
| `INDAGAR_MAX_SECONDS` | Wall-clock budget. Default `300` |
|
|
127
145
|
| `INDAGAR_SEARCH_LIMIT` | Results requested per sub-question. Default `8` |
|
|
@@ -132,11 +150,18 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
132
150
|
| `INDAGAR_SYNTHESIS_MAX_TOKENS` | Synthesis output cap. Default `2048` |
|
|
133
151
|
| `INDAGAR_READER_TIMEOUT` | Page read timeout in seconds. Default `45` |
|
|
134
152
|
|
|
135
|
-
`indagar doctor` shows what is configured.
|
|
153
|
+
`indagar doctor` shows what is configured. `indagar estimate` is offline and
|
|
154
|
+
prints a rough upper bound for searches, sources, LLM calls, and tokens. Set
|
|
155
|
+
the two cost variables above to add a dollar estimate; rates are user-supplied
|
|
156
|
+
and model-specific.
|
|
157
|
+
|
|
158
|
+
LLM requests retry on `429`, `5xx`, and transport failures with exponential
|
|
159
|
+
backoff and `Retry-After` support. `INDAGAR_LLM_MIN_INTERVAL` spaces calls
|
|
160
|
+
across the planner, reader, and writer roles.
|
|
136
161
|
|
|
137
162
|
## Status
|
|
138
163
|
|
|
139
|
-
- [x] CLI with `doctor`, `llm`, `search`, and `research`
|
|
164
|
+
- [x] CLI with `doctor`, `llm`, `estimate`, `search`, and `research`
|
|
140
165
|
- [x] Firecrawl, Brave, Serper, and SearXNG adapters
|
|
141
166
|
- [x] Ordered fallback, over-fetch, URL dedupe, and a 10-minute cache
|
|
142
167
|
- [x] Deterministic research plan and cited source dossier
|
|
@@ -144,12 +169,12 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
144
169
|
- [x] LLM planner, source reader, verbatim quote extraction, gap loop, and synthesis
|
|
145
170
|
- [x] Citation ledger with dedupe, source grouping, and Markdown rendering
|
|
146
171
|
- [x] Per-run source-read and model-usage tables
|
|
147
|
-
- [
|
|
148
|
-
- [ ]
|
|
172
|
+
- [x] Pre-run token/cost estimate, LLM retry/backoff, and request spacing
|
|
173
|
+
- [ ] Resume, concurrency, and web UI
|
|
174
|
+
- [ ] Desktop shell
|
|
149
175
|
- [ ] Academic, podcast, and video sources
|
|
150
176
|
|
|
151
|
-
PyPI has `0.
|
|
152
|
-
published yet.
|
|
177
|
+
PyPI has `0.2.0`, which includes the Phase 1 core loop. Phase 2 is next.
|
|
153
178
|
|
|
154
179
|
See [SPEC.md](SPEC.md) for the design and roadmap.
|
|
155
180
|
|
|
@@ -10,6 +10,13 @@ Phase 1 core loop is implemented. `research` is retrieval-only by default;
|
|
|
10
10
|
adding `--llm` turns on LLM planning, source reading, grounded quote
|
|
11
11
|
extraction, a bounded gap check, and citation-checked synthesis.
|
|
12
12
|
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
uv pip install indagar
|
|
17
|
+
# or: pip install indagar
|
|
18
|
+
```
|
|
19
|
+
|
|
13
20
|
## Quick start
|
|
14
21
|
|
|
15
22
|
```bash
|
|
@@ -27,6 +34,12 @@ indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
|
27
34
|
# Full Phase 1 loop; requires an LLM provider and model.
|
|
28
35
|
indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
29
36
|
--llm --max-sources 10 --depth 1
|
|
37
|
+
|
|
38
|
+
# See the rough budget before running.
|
|
39
|
+
indagar estimate "Does retrieval augmented generation reduce hallucination?" \
|
|
40
|
+
--max-sources 10 --depth 1
|
|
41
|
+
indagar research "Does retrieval augmented generation reduce hallucination?" \
|
|
42
|
+
--llm --dry-run
|
|
30
43
|
```
|
|
31
44
|
|
|
32
45
|
If the checkout is on an exFAT drive, create the virtual environment on a
|
|
@@ -98,6 +111,11 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
98
111
|
| `INDAGAR_LLM_MAX_TOKENS` | Tokens per call. Default `1024` |
|
|
99
112
|
| `INDAGAR_LLM_TEMPERATURE` | Sampling temperature. Default `0.2` |
|
|
100
113
|
| `INDAGAR_LLM_TIMEOUT` | LLM request timeout in seconds. Default `60` |
|
|
114
|
+
| `INDAGAR_LLM_MAX_RETRIES` | Retries on 429/5xx/transport errors. Default `2` |
|
|
115
|
+
| `INDAGAR_RETRY_BASE_SECONDS` | Exponential backoff base. Default `0.5` |
|
|
116
|
+
| `INDAGAR_LLM_MIN_INTERVAL` | Minimum seconds between LLM calls. Default `0` |
|
|
117
|
+
| `INDAGAR_INPUT_COST_PER_MTOK` | Optional input USD per million tokens |
|
|
118
|
+
| `INDAGAR_OUTPUT_COST_PER_MTOK` | Optional output USD per million tokens |
|
|
101
119
|
| `INDAGAR_MAX_SOURCES` | Sources per run. Default `12` |
|
|
102
120
|
| `INDAGAR_MAX_SECONDS` | Wall-clock budget. Default `300` |
|
|
103
121
|
| `INDAGAR_SEARCH_LIMIT` | Results requested per sub-question. Default `8` |
|
|
@@ -108,11 +126,18 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
108
126
|
| `INDAGAR_SYNTHESIS_MAX_TOKENS` | Synthesis output cap. Default `2048` |
|
|
109
127
|
| `INDAGAR_READER_TIMEOUT` | Page read timeout in seconds. Default `45` |
|
|
110
128
|
|
|
111
|
-
`indagar doctor` shows what is configured.
|
|
129
|
+
`indagar doctor` shows what is configured. `indagar estimate` is offline and
|
|
130
|
+
prints a rough upper bound for searches, sources, LLM calls, and tokens. Set
|
|
131
|
+
the two cost variables above to add a dollar estimate; rates are user-supplied
|
|
132
|
+
and model-specific.
|
|
133
|
+
|
|
134
|
+
LLM requests retry on `429`, `5xx`, and transport failures with exponential
|
|
135
|
+
backoff and `Retry-After` support. `INDAGAR_LLM_MIN_INTERVAL` spaces calls
|
|
136
|
+
across the planner, reader, and writer roles.
|
|
112
137
|
|
|
113
138
|
## Status
|
|
114
139
|
|
|
115
|
-
- [x] CLI with `doctor`, `llm`, `search`, and `research`
|
|
140
|
+
- [x] CLI with `doctor`, `llm`, `estimate`, `search`, and `research`
|
|
116
141
|
- [x] Firecrawl, Brave, Serper, and SearXNG adapters
|
|
117
142
|
- [x] Ordered fallback, over-fetch, URL dedupe, and a 10-minute cache
|
|
118
143
|
- [x] Deterministic research plan and cited source dossier
|
|
@@ -120,12 +145,12 @@ Copy `.env.example` to `.env` and set the providers you have.
|
|
|
120
145
|
- [x] LLM planner, source reader, verbatim quote extraction, gap loop, and synthesis
|
|
121
146
|
- [x] Citation ledger with dedupe, source grouping, and Markdown rendering
|
|
122
147
|
- [x] Per-run source-read and model-usage tables
|
|
123
|
-
- [
|
|
124
|
-
- [ ]
|
|
148
|
+
- [x] Pre-run token/cost estimate, LLM retry/backoff, and request spacing
|
|
149
|
+
- [ ] Resume, concurrency, and web UI
|
|
150
|
+
- [ ] Desktop shell
|
|
125
151
|
- [ ] Academic, podcast, and video sources
|
|
126
152
|
|
|
127
|
-
PyPI has `0.
|
|
128
|
-
published yet.
|
|
153
|
+
PyPI has `0.2.0`, which includes the Phase 1 core loop. Phase 2 is next.
|
|
129
154
|
|
|
130
155
|
See [SPEC.md](SPEC.md) for the design and roadmap.
|
|
131
156
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Indagar — design specification
|
|
2
2
|
|
|
3
|
-
**Status:** Phase 1 core loop implemented
|
|
3
|
+
**Status:** Phase 1 core loop and polish implemented
|
|
4
4
|
**Name:** Indagar (Spanish: to investigate, inquire, probe)
|
|
5
5
|
**Licence:** MIT
|
|
6
6
|
|
|
@@ -130,12 +130,18 @@ Every run has explicit caps:
|
|
|
130
130
|
|
|
131
131
|
Controls:
|
|
132
132
|
|
|
133
|
-
-
|
|
134
|
-
|
|
133
|
+
- LLM requests retry on `429`, `5xx`, and transport failures with exponential
|
|
134
|
+
backoff, jitter, and `Retry-After` support.
|
|
135
|
+
- A shared minimum interval spaces calls across the planner, reader, and writer
|
|
136
|
+
roles (`INDAGAR_LLM_MIN_INTERVAL`).
|
|
137
|
+
- Search results and identical queries are cached; page-level caching is still
|
|
138
|
+
to come.
|
|
135
139
|
- Small/local model for extraction and summarisation.
|
|
136
|
-
- Stop and resume: a run is a saved state, not a single function call
|
|
137
|
-
|
|
138
|
-
|
|
140
|
+
- Stop and resume: a run is a saved state, not a single function call; resume
|
|
141
|
+
is Phase 2.
|
|
142
|
+
- A pre-run estimate reports upper-bound searches, sources, calls, tokens, and
|
|
143
|
+
an optional dollar cost from user-supplied per-million-token rates.
|
|
144
|
+
- Actual token usage is recorded per provider/model after the run.
|
|
139
145
|
|
|
140
146
|
Deep research is mostly a scheduling and grounding problem. Treat every network
|
|
141
147
|
call as budgeted.
|
|
@@ -151,6 +157,8 @@ src/indagar/
|
|
|
151
157
|
citations.py Citation ledger, dedupe, Markdown rendering
|
|
152
158
|
store.py Run JSON + Markdown storage
|
|
153
159
|
usage.py Per-model call and token accounting
|
|
160
|
+
estimate.py Pre-run tokens, calls, and optional cost estimate
|
|
161
|
+
rate_limit.py LLM retry/backoff and request spacing
|
|
154
162
|
llm/
|
|
155
163
|
base.py LLMProvider protocol, response, errors
|
|
156
164
|
anthropic.py Anthropic Messages adapter
|
|
@@ -181,9 +189,11 @@ limiting, resume, and the web UI remain.
|
|
|
181
189
|
```bash
|
|
182
190
|
indagar doctor
|
|
183
191
|
indagar llm "prompt" --role writer
|
|
192
|
+
indagar estimate "question" --max-sources 12 --depth 1
|
|
184
193
|
indagar search "question" --limit 8
|
|
185
194
|
indagar research "question" --max-sources 12 --out report.md
|
|
186
195
|
indagar research "question" --llm --depth 1 --max-sources 12
|
|
196
|
+
indagar research "question" --llm --dry-run
|
|
187
197
|
```
|
|
188
198
|
|
|
189
199
|
### Web UI (Phase 2)
|
|
@@ -239,7 +249,11 @@ Do not fork these projects. Borrow patterns and keep Indagar thin.
|
|
|
239
249
|
- Synthesis rejects unknown citation IDs and falls back to the evidence table.
|
|
240
250
|
- The citation ledger rejects empty quotes and dedupes identical evidence.
|
|
241
251
|
- Reports render sources, citations, source-read status, and per-model usage.
|
|
252
|
+
- `indagar estimate` and `research --dry-run` report an upper-bound budget
|
|
253
|
+
without calling a provider.
|
|
254
|
+
- LLM calls retry transient failures and can be spaced by a shared interval.
|
|
242
255
|
- Raw prompts, provider payloads, and API keys never enter run records.
|
|
243
|
-
- Tests cover request shaping, responses, errors,
|
|
244
|
-
synthesis, citation validation, and the
|
|
256
|
+
- Tests cover request shaping, responses, errors, retries, rate limiting,
|
|
257
|
+
estimates, readers, extraction, gaps, synthesis, citation validation, and the
|
|
258
|
+
full loop with fakes.
|
|
245
259
|
- `ruff check`, `ruff format --check`, and `pytest` pass.
|
|
@@ -12,6 +12,7 @@ from rich.table import Table
|
|
|
12
12
|
|
|
13
13
|
from . import __version__
|
|
14
14
|
from .config import Settings
|
|
15
|
+
from .estimate import cost_for_tokens, estimate_run
|
|
15
16
|
from .llm.base import LLM_ROLES, LLMError
|
|
16
17
|
from .llm.factory import build_llm, build_llms
|
|
17
18
|
from .research.deep import run_deep_research
|
|
@@ -74,7 +75,9 @@ def doctor() -> None:
|
|
|
74
75
|
console.print(
|
|
75
76
|
f"Budgets: sources={settings.max_sources}, "
|
|
76
77
|
f"seconds={settings.max_seconds}, search_limit={settings.search_limit}, "
|
|
77
|
-
f"depth={settings.max_depth},
|
|
78
|
+
f"depth={settings.max_depth}, retries={settings.llm_max_retries}, "
|
|
79
|
+
f"min_interval={settings.llm_min_interval}s, "
|
|
80
|
+
f"llm_max_tokens={settings.llm_max_tokens}"
|
|
78
81
|
)
|
|
79
82
|
if not configured:
|
|
80
83
|
console.print(
|
|
@@ -132,6 +135,46 @@ def llm_prompt(
|
|
|
132
135
|
console.print(detail)
|
|
133
136
|
|
|
134
137
|
|
|
138
|
+
@app.command()
|
|
139
|
+
def estimate(
|
|
140
|
+
question: str = typer.Argument(..., help="Question or topic to estimate"),
|
|
141
|
+
llm: bool = typer.Option(True, "--llm/--no-llm", help="Include LLM calls"),
|
|
142
|
+
depth: int | None = typer.Option(None, "--depth", min=0, max=2),
|
|
143
|
+
max_sources: int = typer.Option(0, "--max-sources", min=0, help="0 uses INDAGAR_MAX_SOURCES"),
|
|
144
|
+
) -> None:
|
|
145
|
+
"""Print a rough pre-run budget estimate without calling any provider."""
|
|
146
|
+
settings = _settings_or_exit()
|
|
147
|
+
try:
|
|
148
|
+
result = estimate_run(
|
|
149
|
+
question,
|
|
150
|
+
settings,
|
|
151
|
+
max_sources=max_sources or None,
|
|
152
|
+
depth=depth,
|
|
153
|
+
llm=llm,
|
|
154
|
+
)
|
|
155
|
+
except ValueError as exc:
|
|
156
|
+
console.print(f"[red]{exc}[/red]")
|
|
157
|
+
raise typer.Exit(1) from exc
|
|
158
|
+
|
|
159
|
+
table = Table(title="Run estimate")
|
|
160
|
+
table.add_column("Item")
|
|
161
|
+
table.add_column("Value", justify="right")
|
|
162
|
+
table.add_row("Searches", str(result.searches))
|
|
163
|
+
table.add_row("Sources", str(result.sources))
|
|
164
|
+
table.add_row("LLM calls", str(result.llm_calls))
|
|
165
|
+
table.add_row("Input tokens", f"~{result.input_tokens:,}")
|
|
166
|
+
table.add_row("Output tokens", f"~{result.output_tokens:,}")
|
|
167
|
+
if result.cost_usd is not None:
|
|
168
|
+
table.add_row("Estimated cost", f"~${result.cost_usd:.4f}")
|
|
169
|
+
console.print(table)
|
|
170
|
+
if result.llm_calls and result.cost_usd is None:
|
|
171
|
+
console.print(
|
|
172
|
+
"[dim]Set INDAGAR_INPUT_COST_PER_MTOK and "
|
|
173
|
+
"INDAGAR_OUTPUT_COST_PER_MTOK for a dollar estimate.[/dim]"
|
|
174
|
+
)
|
|
175
|
+
console.print("[dim]Rough upper bound; actual usage is recorded in the run.[/dim]")
|
|
176
|
+
|
|
177
|
+
|
|
135
178
|
@app.command()
|
|
136
179
|
def search(
|
|
137
180
|
query: str = typer.Argument(..., help="Search query"),
|
|
@@ -186,12 +229,23 @@ def research(
|
|
|
186
229
|
),
|
|
187
230
|
max_sources: int = typer.Option(0, "--max-sources", min=0, help="0 uses INDAGAR_MAX_SOURCES"),
|
|
188
231
|
out: Path | None = typer.Option(None, "--out", "-o", help="Markdown output path"),
|
|
232
|
+
dry_run: bool = typer.Option(False, "--dry-run", help="Print the estimate and exit"),
|
|
189
233
|
) -> None:
|
|
190
234
|
"""Plan sub-questions, search, and write a source dossier or cited report."""
|
|
191
235
|
settings = _settings_or_exit()
|
|
192
236
|
if max_sources:
|
|
193
237
|
settings = replace(settings, max_sources=max_sources)
|
|
194
238
|
|
|
239
|
+
try:
|
|
240
|
+
estimate = estimate_run(question, settings, depth=depth, llm=llm)
|
|
241
|
+
except ValueError as exc:
|
|
242
|
+
console.print(f"[red]{exc}[/red]")
|
|
243
|
+
raise typer.Exit(1) from exc
|
|
244
|
+
if llm or dry_run:
|
|
245
|
+
console.print(estimate.line())
|
|
246
|
+
if dry_run:
|
|
247
|
+
return
|
|
248
|
+
|
|
195
249
|
try:
|
|
196
250
|
if llm:
|
|
197
251
|
llms = build_llms(settings)
|
|
@@ -231,10 +285,13 @@ def research(
|
|
|
231
285
|
input_tokens = sum(item.input_tokens for item in run.usage)
|
|
232
286
|
output_tokens = sum(item.output_tokens for item in run.usage)
|
|
233
287
|
console.print(f"LLM usage: {calls} calls · {input_tokens} in / {output_tokens} out")
|
|
288
|
+
cost = cost_for_tokens(input_tokens, output_tokens, settings)
|
|
289
|
+
if cost is not None:
|
|
290
|
+
console.print(f"Token cost: ${cost:.4f}")
|
|
234
291
|
|
|
235
292
|
json_path, markdown_path = save_run(run, out=out)
|
|
236
293
|
console.print(f"Run record: {json_path}")
|
|
237
|
-
console.print(f"
|
|
294
|
+
console.print(f"Markdown: {markdown_path}")
|
|
238
295
|
|
|
239
296
|
|
|
240
297
|
def main() -> None:
|
|
@@ -36,6 +36,16 @@ def _env_float(
|
|
|
36
36
|
return default
|
|
37
37
|
|
|
38
38
|
|
|
39
|
+
def _env_optional_float(name: str) -> float | None:
|
|
40
|
+
raw = (os.getenv(name) or "").strip()
|
|
41
|
+
if not raw:
|
|
42
|
+
return None
|
|
43
|
+
try:
|
|
44
|
+
return max(0.0, float(raw))
|
|
45
|
+
except ValueError:
|
|
46
|
+
return None
|
|
47
|
+
|
|
48
|
+
|
|
39
49
|
def _normalize_llm_provider(raw: str | None) -> str | None:
|
|
40
50
|
value = (raw or "").strip().lower().replace("_", "-")
|
|
41
51
|
if not value:
|
|
@@ -73,6 +83,11 @@ class Settings:
|
|
|
73
83
|
llm_max_tokens: int = 1024
|
|
74
84
|
llm_temperature: float = 0.2
|
|
75
85
|
llm_timeout: float = 60.0
|
|
86
|
+
llm_max_retries: int = 2
|
|
87
|
+
retry_base_seconds: float = 0.5
|
|
88
|
+
llm_min_interval: float = 0.0
|
|
89
|
+
input_cost_per_mtok: float | None = None
|
|
90
|
+
output_cost_per_mtok: float | None = None
|
|
76
91
|
max_sources: int = 12
|
|
77
92
|
max_seconds: int = 300
|
|
78
93
|
search_limit: int = 8
|
|
@@ -112,6 +127,21 @@ class Settings:
|
|
|
112
127
|
minimum=1.0,
|
|
113
128
|
maximum=3600.0,
|
|
114
129
|
),
|
|
130
|
+
llm_max_retries=_env_int("INDAGAR_LLM_MAX_RETRIES", 2, minimum=0),
|
|
131
|
+
retry_base_seconds=_env_float(
|
|
132
|
+
"INDAGAR_RETRY_BASE_SECONDS",
|
|
133
|
+
0.5,
|
|
134
|
+
minimum=0.0,
|
|
135
|
+
maximum=60.0,
|
|
136
|
+
),
|
|
137
|
+
llm_min_interval=_env_float(
|
|
138
|
+
"INDAGAR_LLM_MIN_INTERVAL",
|
|
139
|
+
0.0,
|
|
140
|
+
minimum=0.0,
|
|
141
|
+
maximum=60.0,
|
|
142
|
+
),
|
|
143
|
+
input_cost_per_mtok=_env_optional_float("INDAGAR_INPUT_COST_PER_MTOK"),
|
|
144
|
+
output_cost_per_mtok=_env_optional_float("INDAGAR_OUTPUT_COST_PER_MTOK"),
|
|
115
145
|
max_sources=_env_int("INDAGAR_MAX_SOURCES", 12),
|
|
116
146
|
max_seconds=_env_int("INDAGAR_MAX_SECONDS", 300),
|
|
117
147
|
search_limit=_env_int("INDAGAR_SEARCH_LIMIT", 8),
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import asdict, dataclass
|
|
4
|
+
|
|
5
|
+
from .config import Settings
|
|
6
|
+
|
|
7
|
+
PLANNER_INPUT_TOKENS = 800
|
|
8
|
+
PLANNER_OUTPUT_TOKENS = 500
|
|
9
|
+
GAP_INPUT_TOKENS = 1200
|
|
10
|
+
GAP_OUTPUT_TOKENS = 400
|
|
11
|
+
SYNTHESIS_BASE_INPUT_TOKENS = 1200
|
|
12
|
+
PER_SOURCE_OUTPUT_TOKENS = 140
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class RunEstimate:
|
|
17
|
+
question: str
|
|
18
|
+
sources: int
|
|
19
|
+
searches: int
|
|
20
|
+
llm_calls: int
|
|
21
|
+
input_tokens: int
|
|
22
|
+
output_tokens: int
|
|
23
|
+
cost_usd: float | None = None
|
|
24
|
+
|
|
25
|
+
def to_dict(self) -> dict[str, object]:
|
|
26
|
+
return asdict(self)
|
|
27
|
+
|
|
28
|
+
def line(self) -> str:
|
|
29
|
+
if self.llm_calls:
|
|
30
|
+
text = (
|
|
31
|
+
f"Estimate: {self.searches} searches · {self.sources} sources · "
|
|
32
|
+
f"{self.llm_calls} LLM calls · ~{self.input_tokens:,} in / "
|
|
33
|
+
f"{self.output_tokens:,} out tokens"
|
|
34
|
+
)
|
|
35
|
+
else:
|
|
36
|
+
text = f"Estimate: {self.searches} searches · {self.sources} sources · retrieval only"
|
|
37
|
+
if self.cost_usd is not None:
|
|
38
|
+
text += f" · ~${self.cost_usd:.4f}"
|
|
39
|
+
return text
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def cost_for_tokens(
|
|
43
|
+
input_tokens: int,
|
|
44
|
+
output_tokens: int,
|
|
45
|
+
settings: Settings,
|
|
46
|
+
) -> float | None:
|
|
47
|
+
if settings.input_cost_per_mtok is None and settings.output_cost_per_mtok is None:
|
|
48
|
+
return None
|
|
49
|
+
input_rate = settings.input_cost_per_mtok or 0.0
|
|
50
|
+
output_rate = settings.output_cost_per_mtok or 0.0
|
|
51
|
+
return (input_tokens / 1_000_000) * input_rate + (output_tokens / 1_000_000) * output_rate
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def estimate_run(
|
|
55
|
+
question: str,
|
|
56
|
+
settings: Settings,
|
|
57
|
+
*,
|
|
58
|
+
max_sources: int | None = None,
|
|
59
|
+
depth: int | None = None,
|
|
60
|
+
llm: bool = True,
|
|
61
|
+
) -> RunEstimate:
|
|
62
|
+
normalized = " ".join(question.split())
|
|
63
|
+
if not normalized:
|
|
64
|
+
raise ValueError("question is required")
|
|
65
|
+
|
|
66
|
+
sources = max(1, max_sources or settings.max_sources)
|
|
67
|
+
rounds = 0 if not llm else (settings.max_depth if depth is None else depth)
|
|
68
|
+
rounds = max(0, min(2, rounds))
|
|
69
|
+
searches = 4 + rounds * settings.max_follow_ups
|
|
70
|
+
|
|
71
|
+
if not llm:
|
|
72
|
+
return RunEstimate(
|
|
73
|
+
question=normalized,
|
|
74
|
+
sources=sources,
|
|
75
|
+
searches=searches,
|
|
76
|
+
llm_calls=0,
|
|
77
|
+
input_tokens=0,
|
|
78
|
+
output_tokens=0,
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
per_source_input = settings.max_content_chars // 4 + 500
|
|
82
|
+
per_source_output = settings.max_claims * PER_SOURCE_OUTPUT_TOKENS
|
|
83
|
+
synthesis_input = (
|
|
84
|
+
SYNTHESIS_BASE_INPUT_TOKENS + sources * settings.max_claims * 150 + sources * 60
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
input_tokens = (
|
|
88
|
+
PLANNER_INPUT_TOKENS
|
|
89
|
+
+ sources * per_source_input
|
|
90
|
+
+ rounds * GAP_INPUT_TOKENS
|
|
91
|
+
+ synthesis_input
|
|
92
|
+
)
|
|
93
|
+
output_tokens = (
|
|
94
|
+
PLANNER_OUTPUT_TOKENS
|
|
95
|
+
+ sources * per_source_output
|
|
96
|
+
+ rounds * GAP_OUTPUT_TOKENS
|
|
97
|
+
+ settings.synthesis_max_tokens
|
|
98
|
+
)
|
|
99
|
+
calls = 1 + sources + rounds + 1
|
|
100
|
+
|
|
101
|
+
return RunEstimate(
|
|
102
|
+
question=normalized,
|
|
103
|
+
sources=sources,
|
|
104
|
+
searches=searches,
|
|
105
|
+
llm_calls=calls,
|
|
106
|
+
input_tokens=input_tokens,
|
|
107
|
+
output_tokens=output_tokens,
|
|
108
|
+
cost_usd=cost_for_tokens(input_tokens, output_tokens, settings),
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
__all__ = ["RunEstimate", "cost_for_tokens", "estimate_run"]
|
|
@@ -6,6 +6,7 @@ from contextlib import asynccontextmanager
|
|
|
6
6
|
import httpx
|
|
7
7
|
|
|
8
8
|
from ..config import DEFAULT_ANTHROPIC_BASE_URL
|
|
9
|
+
from ..rate_limit import RateLimiter, RetryPolicy
|
|
9
10
|
from .base import LLMError, LLMResponse, status_error
|
|
10
11
|
|
|
11
12
|
ANTHROPIC_VERSION = "2023-06-01"
|
|
@@ -30,6 +31,8 @@ class AnthropicProvider:
|
|
|
30
31
|
temperature: float = 0.2,
|
|
31
32
|
timeout: float = 60.0,
|
|
32
33
|
client: httpx.AsyncClient | None = None,
|
|
34
|
+
retry: RetryPolicy | None = None,
|
|
35
|
+
limiter: RateLimiter | None = None,
|
|
33
36
|
):
|
|
34
37
|
self.api_key = api_key
|
|
35
38
|
self.base_url = base_url.rstrip("/")
|
|
@@ -40,6 +43,8 @@ class AnthropicProvider:
|
|
|
40
43
|
self.temperature = temperature
|
|
41
44
|
self.timeout = timeout
|
|
42
45
|
self._client = client
|
|
46
|
+
self.retry = retry or RetryPolicy()
|
|
47
|
+
self.limiter = limiter
|
|
43
48
|
|
|
44
49
|
@asynccontextmanager
|
|
45
50
|
async def _client_ctx(self) -> AsyncIterator[httpx.AsyncClient]:
|
|
@@ -89,8 +94,12 @@ class AnthropicProvider:
|
|
|
89
94
|
}
|
|
90
95
|
|
|
91
96
|
try:
|
|
97
|
+
if self.limiter is not None:
|
|
98
|
+
await self.limiter.wait()
|
|
92
99
|
async with self._client_ctx() as client:
|
|
93
|
-
response = await
|
|
100
|
+
response = await self.retry.request(
|
|
101
|
+
client,
|
|
102
|
+
"POST",
|
|
94
103
|
f"{self.base_url}/v1/messages",
|
|
95
104
|
json=payload,
|
|
96
105
|
headers=headers,
|
|
@@ -3,6 +3,7 @@ from __future__ import annotations
|
|
|
3
3
|
from dataclasses import dataclass
|
|
4
4
|
|
|
5
5
|
from ..config import DEFAULT_OPENAI_BASE_URL, Settings
|
|
6
|
+
from ..rate_limit import RateLimiter, RetryPolicy
|
|
6
7
|
from .anthropic import AnthropicProvider
|
|
7
8
|
from .base import LLM_ROLES, LLMError, LLMProvider
|
|
8
9
|
from .openai_compatible import OpenAICompatibleProvider
|
|
@@ -13,6 +14,7 @@ def build_llm(
|
|
|
13
14
|
role: str = "writer",
|
|
14
15
|
*,
|
|
15
16
|
model: str | None = None,
|
|
17
|
+
limiter: RateLimiter | None = None,
|
|
16
18
|
) -> LLMProvider:
|
|
17
19
|
"""Build the configured provider for a model role."""
|
|
18
20
|
role = role.lower()
|
|
@@ -34,6 +36,13 @@ def build_llm(
|
|
|
34
36
|
f"or INDAGAR_{role.upper()}_MODEL.",
|
|
35
37
|
)
|
|
36
38
|
|
|
39
|
+
retry = RetryPolicy(
|
|
40
|
+
max_retries=settings.llm_max_retries,
|
|
41
|
+
base_seconds=settings.retry_base_seconds,
|
|
42
|
+
)
|
|
43
|
+
if limiter is None and settings.llm_min_interval > 0:
|
|
44
|
+
limiter = RateLimiter(settings.llm_min_interval)
|
|
45
|
+
|
|
37
46
|
if provider == "anthropic":
|
|
38
47
|
if not settings.anthropic_api_key:
|
|
39
48
|
raise LLMError(
|
|
@@ -47,6 +56,8 @@ def build_llm(
|
|
|
47
56
|
max_tokens=settings.llm_max_tokens,
|
|
48
57
|
temperature=settings.llm_temperature,
|
|
49
58
|
timeout=settings.llm_timeout,
|
|
59
|
+
retry=retry,
|
|
60
|
+
limiter=limiter,
|
|
50
61
|
)
|
|
51
62
|
|
|
52
63
|
if provider == "openai-compatible":
|
|
@@ -62,6 +73,8 @@ def build_llm(
|
|
|
62
73
|
max_tokens=settings.llm_max_tokens,
|
|
63
74
|
temperature=settings.llm_temperature,
|
|
64
75
|
timeout=settings.llm_timeout,
|
|
76
|
+
retry=retry,
|
|
77
|
+
limiter=limiter,
|
|
65
78
|
)
|
|
66
79
|
|
|
67
80
|
raise LLMError("config", f"Unknown LLM provider: {provider}")
|
|
@@ -76,10 +89,11 @@ class LLMSet:
|
|
|
76
89
|
|
|
77
90
|
def build_llms(settings: Settings) -> LLMSet:
|
|
78
91
|
"""Build one provider per role so models can differ by job."""
|
|
92
|
+
limiter = RateLimiter(settings.llm_min_interval) if settings.llm_min_interval > 0 else None
|
|
79
93
|
return LLMSet(
|
|
80
|
-
planner=build_llm(settings, role="planner"),
|
|
81
|
-
reader=build_llm(settings, role="reader"),
|
|
82
|
-
writer=build_llm(settings, role="writer"),
|
|
94
|
+
planner=build_llm(settings, role="planner", limiter=limiter),
|
|
95
|
+
reader=build_llm(settings, role="reader", limiter=limiter),
|
|
96
|
+
writer=build_llm(settings, role="writer", limiter=limiter),
|
|
83
97
|
)
|
|
84
98
|
|
|
85
99
|
|
|
@@ -6,6 +6,7 @@ from contextlib import asynccontextmanager
|
|
|
6
6
|
import httpx
|
|
7
7
|
|
|
8
8
|
from ..config import DEFAULT_OPENAI_BASE_URL
|
|
9
|
+
from ..rate_limit import RateLimiter, RetryPolicy
|
|
9
10
|
from .base import LLMError, LLMResponse, status_error
|
|
10
11
|
|
|
11
12
|
|
|
@@ -40,6 +41,8 @@ class OpenAICompatibleProvider:
|
|
|
40
41
|
temperature: float = 0.2,
|
|
41
42
|
timeout: float = 60.0,
|
|
42
43
|
client: httpx.AsyncClient | None = None,
|
|
44
|
+
retry: RetryPolicy | None = None,
|
|
45
|
+
limiter: RateLimiter | None = None,
|
|
43
46
|
):
|
|
44
47
|
self.base_url = base_url.rstrip("/")
|
|
45
48
|
self.api_key = api_key
|
|
@@ -48,6 +51,8 @@ class OpenAICompatibleProvider:
|
|
|
48
51
|
self.temperature = temperature
|
|
49
52
|
self.timeout = timeout
|
|
50
53
|
self._client = client
|
|
54
|
+
self.retry = retry or RetryPolicy()
|
|
55
|
+
self.limiter = limiter
|
|
51
56
|
|
|
52
57
|
@asynccontextmanager
|
|
53
58
|
async def _client_ctx(self) -> AsyncIterator[httpx.AsyncClient]:
|
|
@@ -89,8 +94,12 @@ class OpenAICompatibleProvider:
|
|
|
89
94
|
payload["response_format"] = {"type": "json_object"}
|
|
90
95
|
|
|
91
96
|
try:
|
|
97
|
+
if self.limiter is not None:
|
|
98
|
+
await self.limiter.wait()
|
|
92
99
|
async with self._client_ctx() as client:
|
|
93
|
-
response = await
|
|
100
|
+
response = await self.retry.request(
|
|
101
|
+
client,
|
|
102
|
+
"POST",
|
|
94
103
|
f"{self.base_url}/chat/completions",
|
|
95
104
|
json=payload,
|
|
96
105
|
headers=headers,
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import random
|
|
5
|
+
import time
|
|
6
|
+
from collections.abc import Awaitable, Callable
|
|
7
|
+
|
|
8
|
+
import httpx
|
|
9
|
+
|
|
10
|
+
RETRY_STATUSES = {408, 425, 429, 500, 502, 503, 504}
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class RetryPolicy:
|
|
14
|
+
"""Exponential backoff for transient HTTP failures."""
|
|
15
|
+
|
|
16
|
+
def __init__(
|
|
17
|
+
self,
|
|
18
|
+
max_retries: int = 2,
|
|
19
|
+
base_seconds: float = 0.5,
|
|
20
|
+
max_seconds: float = 8.0,
|
|
21
|
+
*,
|
|
22
|
+
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
|
|
23
|
+
rng: Callable[[], float] = random.random,
|
|
24
|
+
):
|
|
25
|
+
self.max_retries = max(0, max_retries)
|
|
26
|
+
self.base_seconds = max(0.0, base_seconds)
|
|
27
|
+
self.max_seconds = max(0.0, max_seconds)
|
|
28
|
+
self._sleep = sleep
|
|
29
|
+
self._rng = rng
|
|
30
|
+
|
|
31
|
+
async def request(
|
|
32
|
+
self,
|
|
33
|
+
client: httpx.AsyncClient,
|
|
34
|
+
method: str,
|
|
35
|
+
url: str,
|
|
36
|
+
**kwargs,
|
|
37
|
+
) -> httpx.Response:
|
|
38
|
+
for attempt in range(self.max_retries + 1):
|
|
39
|
+
try:
|
|
40
|
+
response = await client.request(method, url, **kwargs)
|
|
41
|
+
except httpx.TransportError:
|
|
42
|
+
if attempt >= self.max_retries:
|
|
43
|
+
raise
|
|
44
|
+
await self._sleep(self._delay(attempt))
|
|
45
|
+
continue
|
|
46
|
+
|
|
47
|
+
if response.status_code not in RETRY_STATUSES:
|
|
48
|
+
return response
|
|
49
|
+
if attempt >= self.max_retries:
|
|
50
|
+
return response
|
|
51
|
+
await self._sleep(self._retry_after(response) or self._delay(attempt))
|
|
52
|
+
|
|
53
|
+
raise AssertionError("retry loop exhausted without a response")
|
|
54
|
+
|
|
55
|
+
def _delay(self, attempt: int) -> float:
|
|
56
|
+
delay = min(self.max_seconds, self.base_seconds * (2**attempt))
|
|
57
|
+
return delay * (0.5 + self._rng() / 2)
|
|
58
|
+
|
|
59
|
+
def _retry_after(self, response: httpx.Response) -> float | None:
|
|
60
|
+
raw = response.headers.get("retry-after")
|
|
61
|
+
if not raw:
|
|
62
|
+
return None
|
|
63
|
+
try:
|
|
64
|
+
value = float(raw)
|
|
65
|
+
except ValueError:
|
|
66
|
+
return None
|
|
67
|
+
if value < 0:
|
|
68
|
+
return None
|
|
69
|
+
return min(self.max_seconds, value)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class RateLimiter:
|
|
73
|
+
"""Space requests by a minimum interval, sharing one lock."""
|
|
74
|
+
|
|
75
|
+
def __init__(
|
|
76
|
+
self,
|
|
77
|
+
min_interval: float,
|
|
78
|
+
*,
|
|
79
|
+
clock: Callable[[], float] = time.monotonic,
|
|
80
|
+
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
|
|
81
|
+
):
|
|
82
|
+
self.min_interval = max(0.0, min_interval)
|
|
83
|
+
self._clock = clock
|
|
84
|
+
self._sleep = sleep
|
|
85
|
+
self._next_at = 0.0
|
|
86
|
+
self._lock = asyncio.Lock()
|
|
87
|
+
|
|
88
|
+
async def wait(self) -> None:
|
|
89
|
+
if self.min_interval <= 0:
|
|
90
|
+
return
|
|
91
|
+
async with self._lock:
|
|
92
|
+
now = self._clock()
|
|
93
|
+
delay = self._next_at - now
|
|
94
|
+
if delay > 0:
|
|
95
|
+
await self._sleep(delay)
|
|
96
|
+
self._next_at = self._clock() + self.min_interval
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
__all__ = ["RETRY_STATUSES", "RateLimiter", "RetryPolicy"]
|
|
@@ -32,6 +32,22 @@ def test_llm_provider_normalization(monkeypatch):
|
|
|
32
32
|
assert Settings.from_env().llm_provider == "openai-compatible"
|
|
33
33
|
|
|
34
34
|
|
|
35
|
+
def test_retry_and_cost_settings(monkeypatch):
|
|
36
|
+
monkeypatch.setenv("INDAGAR_LLM_MAX_RETRIES", "4")
|
|
37
|
+
monkeypatch.setenv("INDAGAR_RETRY_BASE_SECONDS", "1.5")
|
|
38
|
+
monkeypatch.setenv("INDAGAR_LLM_MIN_INTERVAL", "0.25")
|
|
39
|
+
monkeypatch.setenv("INDAGAR_INPUT_COST_PER_MTOK", "3")
|
|
40
|
+
monkeypatch.setenv("INDAGAR_OUTPUT_COST_PER_MTOK", "15")
|
|
41
|
+
|
|
42
|
+
settings = Settings.from_env()
|
|
43
|
+
|
|
44
|
+
assert settings.llm_max_retries == 4
|
|
45
|
+
assert settings.retry_base_seconds == 1.5
|
|
46
|
+
assert settings.llm_min_interval == 0.25
|
|
47
|
+
assert settings.input_cost_per_mtok == 3.0
|
|
48
|
+
assert settings.output_cost_per_mtok == 15.0
|
|
49
|
+
|
|
50
|
+
|
|
35
51
|
def test_llm_timeout_uses_seconds_not_temperature_bounds(monkeypatch):
|
|
36
52
|
monkeypatch.setenv("INDAGAR_LLM_TIMEOUT", "60")
|
|
37
53
|
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import pytest
|
|
4
|
+
|
|
5
|
+
from indagar.config import Settings
|
|
6
|
+
from indagar.estimate import cost_for_tokens, estimate_run
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def test_estimate_scales_with_depth():
|
|
10
|
+
shallow = estimate_run(
|
|
11
|
+
"What is X?",
|
|
12
|
+
Settings(max_sources=4, max_depth=0),
|
|
13
|
+
depth=0,
|
|
14
|
+
)
|
|
15
|
+
deeper = estimate_run(
|
|
16
|
+
"What is X?",
|
|
17
|
+
Settings(max_sources=4, max_depth=1),
|
|
18
|
+
depth=1,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
assert shallow.sources == 4
|
|
22
|
+
assert shallow.searches == 4
|
|
23
|
+
assert shallow.llm_calls == 6
|
|
24
|
+
assert shallow.input_tokens > 0
|
|
25
|
+
assert shallow.output_tokens > 0
|
|
26
|
+
assert deeper.searches == 7
|
|
27
|
+
assert deeper.llm_calls == 7
|
|
28
|
+
assert deeper.input_tokens > shallow.input_tokens
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def test_retrieval_only_estimate_has_no_llm_calls():
|
|
32
|
+
estimate = estimate_run("What is X?", Settings(max_sources=3), llm=False)
|
|
33
|
+
|
|
34
|
+
assert estimate.llm_calls == 0
|
|
35
|
+
assert estimate.searches == 4
|
|
36
|
+
assert estimate.input_tokens == 0
|
|
37
|
+
assert estimate.output_tokens == 0
|
|
38
|
+
assert "retrieval only" in estimate.line()
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def test_cost_uses_user_supplied_rates():
|
|
42
|
+
settings = Settings(
|
|
43
|
+
input_cost_per_mtok=3.0,
|
|
44
|
+
output_cost_per_mtok=15.0,
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
assert cost_for_tokens(1_000_000, 1_000_000, settings) == 18.0
|
|
48
|
+
estimate = estimate_run("What is X?", settings, max_sources=1, depth=0)
|
|
49
|
+
assert estimate.cost_usd is not None
|
|
50
|
+
assert estimate.cost_usd > 0
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def test_estimate_line_includes_sources_and_calls():
|
|
54
|
+
estimate = estimate_run(
|
|
55
|
+
"What is X?",
|
|
56
|
+
Settings(max_sources=2, max_depth=0),
|
|
57
|
+
depth=0,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
line = estimate.line()
|
|
61
|
+
|
|
62
|
+
assert "4 searches" in line
|
|
63
|
+
assert "2 sources" in line
|
|
64
|
+
assert "4 LLM calls" in line
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def test_empty_question_is_rejected():
|
|
68
|
+
with pytest.raises(ValueError, match="question"):
|
|
69
|
+
estimate_run(" ", Settings())
|
|
@@ -9,8 +9,9 @@ import pytest
|
|
|
9
9
|
from indagar.config import Settings
|
|
10
10
|
from indagar.llm.anthropic import AnthropicProvider
|
|
11
11
|
from indagar.llm.base import LLMError
|
|
12
|
-
from indagar.llm.factory import build_llm
|
|
12
|
+
from indagar.llm.factory import build_llm, build_llms
|
|
13
13
|
from indagar.llm.openai_compatible import OpenAICompatibleProvider
|
|
14
|
+
from indagar.rate_limit import RetryPolicy
|
|
14
15
|
|
|
15
16
|
|
|
16
17
|
def test_openai_compatible_request_and_response():
|
|
@@ -107,6 +108,7 @@ def test_provider_error_includes_status_and_detail():
|
|
|
107
108
|
base_url="https://llm.example/v1",
|
|
108
109
|
model="test-model",
|
|
109
110
|
client=client,
|
|
111
|
+
retry=RetryPolicy(max_retries=0),
|
|
110
112
|
)
|
|
111
113
|
await provider.complete("Hello")
|
|
112
114
|
|
|
@@ -118,6 +120,51 @@ def test_provider_error_includes_status_and_detail():
|
|
|
118
120
|
assert "rate limited" in str(excinfo.value)
|
|
119
121
|
|
|
120
122
|
|
|
123
|
+
def test_openai_provider_retries_a_transient_error():
|
|
124
|
+
calls = {"count": 0}
|
|
125
|
+
|
|
126
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
127
|
+
calls["count"] += 1
|
|
128
|
+
if calls["count"] == 1:
|
|
129
|
+
return httpx.Response(429, json={"error": {"message": "rate limited"}})
|
|
130
|
+
return httpx.Response(
|
|
131
|
+
200,
|
|
132
|
+
json={
|
|
133
|
+
"model": "test-model",
|
|
134
|
+
"choices": [{"message": {"content": "Recovered."}}],
|
|
135
|
+
"usage": {"prompt_tokens": 2, "completion_tokens": 1},
|
|
136
|
+
},
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
async def run() -> object:
|
|
140
|
+
sleeps: list[float] = []
|
|
141
|
+
|
|
142
|
+
async def sleep(delay: float) -> None:
|
|
143
|
+
sleeps.append(delay)
|
|
144
|
+
|
|
145
|
+
transport = httpx.MockTransport(handler)
|
|
146
|
+
async with httpx.AsyncClient(transport=transport) as client:
|
|
147
|
+
provider = OpenAICompatibleProvider(
|
|
148
|
+
base_url="https://llm.example/v1",
|
|
149
|
+
model="test-model",
|
|
150
|
+
client=client,
|
|
151
|
+
retry=RetryPolicy(
|
|
152
|
+
max_retries=1,
|
|
153
|
+
base_seconds=0.1,
|
|
154
|
+
sleep=sleep,
|
|
155
|
+
rng=lambda: 0.5,
|
|
156
|
+
),
|
|
157
|
+
)
|
|
158
|
+
response = await provider.complete("Hello")
|
|
159
|
+
return response, sleeps
|
|
160
|
+
|
|
161
|
+
response, sleeps = asyncio.run(run())
|
|
162
|
+
|
|
163
|
+
assert response.text == "Recovered."
|
|
164
|
+
assert calls["count"] == 2
|
|
165
|
+
assert len(sleeps) == 1
|
|
166
|
+
|
|
167
|
+
|
|
121
168
|
def test_build_anthropic_from_settings():
|
|
122
169
|
settings = Settings(
|
|
123
170
|
anthropic_api_key="key",
|
|
@@ -131,6 +178,23 @@ def test_build_anthropic_from_settings():
|
|
|
131
178
|
assert provider.model == "claude-test"
|
|
132
179
|
|
|
133
180
|
|
|
181
|
+
def test_factory_wires_retry_and_shared_limiter():
|
|
182
|
+
settings = Settings(
|
|
183
|
+
anthropic_api_key="key",
|
|
184
|
+
llm_provider="anthropic",
|
|
185
|
+
llm_model="claude-test",
|
|
186
|
+
llm_max_retries=3,
|
|
187
|
+
llm_min_interval=1.0,
|
|
188
|
+
)
|
|
189
|
+
|
|
190
|
+
llms = build_llms(settings)
|
|
191
|
+
|
|
192
|
+
assert llms.planner.retry.max_retries == 3
|
|
193
|
+
assert llms.planner.limiter is not None
|
|
194
|
+
assert llms.planner.limiter is llms.reader.limiter
|
|
195
|
+
assert llms.reader.limiter is llms.writer.limiter
|
|
196
|
+
|
|
197
|
+
|
|
134
198
|
def test_build_openai_compatible_local_without_key():
|
|
135
199
|
settings = Settings(
|
|
136
200
|
openai_base_url="http://localhost:11434/v1",
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
|
|
5
|
+
import httpx
|
|
6
|
+
|
|
7
|
+
from indagar.rate_limit import RateLimiter, RetryPolicy
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_retry_honours_retry_after():
|
|
11
|
+
calls = {"count": 0}
|
|
12
|
+
|
|
13
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
14
|
+
calls["count"] += 1
|
|
15
|
+
if calls["count"] == 1:
|
|
16
|
+
return httpx.Response(429, headers={"retry-after": "0.2"})
|
|
17
|
+
return httpx.Response(200, json={"ok": True})
|
|
18
|
+
|
|
19
|
+
async def run() -> tuple[httpx.Response, list[float]]:
|
|
20
|
+
sleeps: list[float] = []
|
|
21
|
+
|
|
22
|
+
async def sleep(delay: float) -> None:
|
|
23
|
+
sleeps.append(delay)
|
|
24
|
+
|
|
25
|
+
async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
|
|
26
|
+
policy = RetryPolicy(max_retries=2, sleep=sleep)
|
|
27
|
+
response = await policy.request(client, "GET", "https://example.com")
|
|
28
|
+
return response, sleeps
|
|
29
|
+
|
|
30
|
+
response, sleeps = asyncio.run(run())
|
|
31
|
+
|
|
32
|
+
assert response.status_code == 200
|
|
33
|
+
assert calls["count"] == 2
|
|
34
|
+
assert sleeps == [0.2]
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def test_retry_ignores_non_transient_4xx():
|
|
38
|
+
calls = {"count": 0}
|
|
39
|
+
|
|
40
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
41
|
+
calls["count"] += 1
|
|
42
|
+
return httpx.Response(400, json={"error": "bad"})
|
|
43
|
+
|
|
44
|
+
async def run() -> httpx.Response:
|
|
45
|
+
sleeps: list[float] = []
|
|
46
|
+
|
|
47
|
+
async def sleep(delay: float) -> None:
|
|
48
|
+
sleeps.append(delay)
|
|
49
|
+
|
|
50
|
+
async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
|
|
51
|
+
policy = RetryPolicy(max_retries=3, sleep=sleep)
|
|
52
|
+
return await policy.request(client, "GET", "https://example.com")
|
|
53
|
+
|
|
54
|
+
response = asyncio.run(run())
|
|
55
|
+
|
|
56
|
+
assert response.status_code == 400
|
|
57
|
+
assert calls["count"] == 1
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def test_retry_stops_after_max_retries():
|
|
61
|
+
calls = {"count": 0}
|
|
62
|
+
|
|
63
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
64
|
+
calls["count"] += 1
|
|
65
|
+
return httpx.Response(503)
|
|
66
|
+
|
|
67
|
+
async def run() -> httpx.Response:
|
|
68
|
+
async def sleep(delay: float) -> None:
|
|
69
|
+
return None
|
|
70
|
+
|
|
71
|
+
async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
|
|
72
|
+
policy = RetryPolicy(max_retries=2, base_seconds=0.0, sleep=sleep)
|
|
73
|
+
return await policy.request(client, "GET", "https://example.com")
|
|
74
|
+
|
|
75
|
+
response = asyncio.run(run())
|
|
76
|
+
|
|
77
|
+
assert response.status_code == 503
|
|
78
|
+
assert calls["count"] == 3
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def test_retry_recovers_from_transport_error():
|
|
82
|
+
calls = {"count": 0}
|
|
83
|
+
|
|
84
|
+
def handler(request: httpx.Request) -> httpx.Response:
|
|
85
|
+
calls["count"] += 1
|
|
86
|
+
if calls["count"] == 1:
|
|
87
|
+
raise httpx.ConnectError("boom", request=request)
|
|
88
|
+
return httpx.Response(200, json={"ok": True})
|
|
89
|
+
|
|
90
|
+
async def run() -> httpx.Response:
|
|
91
|
+
async def sleep(delay: float) -> None:
|
|
92
|
+
return None
|
|
93
|
+
|
|
94
|
+
async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
|
|
95
|
+
policy = RetryPolicy(max_retries=1, base_seconds=0.0, sleep=sleep)
|
|
96
|
+
return await policy.request(client, "GET", "https://example.com")
|
|
97
|
+
|
|
98
|
+
response = asyncio.run(run())
|
|
99
|
+
|
|
100
|
+
assert response.status_code == 200
|
|
101
|
+
assert calls["count"] == 2
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def test_rate_limiter_spaces_requests():
|
|
105
|
+
now = [0.0]
|
|
106
|
+
sleeps: list[float] = []
|
|
107
|
+
|
|
108
|
+
def clock() -> float:
|
|
109
|
+
return now[0]
|
|
110
|
+
|
|
111
|
+
async def sleep(delay: float) -> None:
|
|
112
|
+
sleeps.append(delay)
|
|
113
|
+
now[0] += delay
|
|
114
|
+
|
|
115
|
+
limiter = RateLimiter(1.0, clock=clock, sleep=sleep)
|
|
116
|
+
|
|
117
|
+
async def run() -> None:
|
|
118
|
+
await limiter.wait()
|
|
119
|
+
await limiter.wait()
|
|
120
|
+
|
|
121
|
+
asyncio.run(run())
|
|
122
|
+
|
|
123
|
+
assert sleeps == [1.0]
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|