multi-agent-swarm 3.0.0__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.
- multi_agent_swarm-3.0.0/LICENSE +21 -0
- multi_agent_swarm-3.0.0/PKG-INFO +193 -0
- multi_agent_swarm-3.0.0/README.md +143 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/PKG-INFO +193 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/SOURCES.txt +39 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/dependency_links.txt +1 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/entry_points.txt +2 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/requires.txt +27 -0
- multi_agent_swarm-3.0.0/multi_agent_swarm.egg-info/top_level.txt +1 -0
- multi_agent_swarm-3.0.0/pyproject.toml +74 -0
- multi_agent_swarm-3.0.0/setup.cfg +4 -0
- multi_agent_swarm-3.0.0/swarm/__init__.py +3 -0
- multi_agent_swarm-3.0.0/swarm/__main__.py +413 -0
- multi_agent_swarm-3.0.0/swarm/app.py +90 -0
- multi_agent_swarm-3.0.0/swarm/backends.py +390 -0
- multi_agent_swarm-3.0.0/swarm/config.py +71 -0
- multi_agent_swarm-3.0.0/swarm/errors.py +54 -0
- multi_agent_swarm-3.0.0/swarm/evaluate.py +166 -0
- multi_agent_swarm-3.0.0/swarm/export.py +158 -0
- multi_agent_swarm-3.0.0/swarm/limiter.py +40 -0
- multi_agent_swarm-3.0.0/swarm/orchestrator.py +496 -0
- multi_agent_swarm-3.0.0/swarm/planner.py +67 -0
- multi_agent_swarm-3.0.0/swarm/policy.py +256 -0
- multi_agent_swarm-3.0.0/swarm/pricing.py +106 -0
- multi_agent_swarm-3.0.0/swarm/reliability.py +170 -0
- multi_agent_swarm-3.0.0/swarm/research.py +904 -0
- multi_agent_swarm-3.0.0/swarm/safety.py +86 -0
- multi_agent_swarm-3.0.0/swarm/search/__init__.py +29 -0
- multi_agent_swarm-3.0.0/swarm/search/base.py +91 -0
- multi_agent_swarm-3.0.0/swarm/search/cache.py +68 -0
- multi_agent_swarm-3.0.0/swarm/search/local.py +93 -0
- multi_agent_swarm-3.0.0/swarm/search/mock.py +42 -0
- multi_agent_swarm-3.0.0/swarm/search/tinyfish.py +118 -0
- multi_agent_swarm-3.0.0/swarm/server.py +257 -0
- multi_agent_swarm-3.0.0/swarm/task.py +93 -0
- multi_agent_swarm-3.0.0/swarm/web/index.html +217 -0
- multi_agent_swarm-3.0.0/swarm/workloads.py +43 -0
- multi_agent_swarm-3.0.0/tests/test_product.py +171 -0
- multi_agent_swarm-3.0.0/tests/test_research.py +126 -0
- multi_agent_swarm-3.0.0/tests/test_swarm.py +437 -0
- multi_agent_swarm-3.0.0/tests/test_v3.py +270 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Multi-Agent Swarm contributors
|
|
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,193 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: multi-agent-swarm
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: Deep research with a multi-agent swarm on Claude: free web search, parallel cited workers, every quote checked against its source
|
|
5
|
+
Author: Multi-Agent Swarm contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Chetan0246/multi-agent-swarm
|
|
8
|
+
Project-URL: Documentation, https://chetan0246.github.io/multi-agent-swarm/
|
|
9
|
+
Project-URL: Changelog, https://github.com/Chetan0246/multi-agent-swarm/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Issues, https://github.com/Chetan0246/multi-agent-swarm/issues
|
|
11
|
+
Keywords: llm,multi-agent,agents,claude,deep-research,web-search,citations,fact-checking,tinyfish,research-assistant
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Environment :: Web Environment
|
|
15
|
+
Classifier: Framework :: AsyncIO
|
|
16
|
+
Classifier: Framework :: FastAPI
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Intended Audience :: Science/Research
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: anthropic<3,>=2.12
|
|
30
|
+
Requires-Dist: httpx2>=2.0
|
|
31
|
+
Requires-Dist: tomli>=2.0; python_version < "3.11"
|
|
32
|
+
Provides-Extra: server
|
|
33
|
+
Requires-Dist: fastapi>=0.110; extra == "server"
|
|
34
|
+
Requires-Dist: uvicorn>=0.29; extra == "server"
|
|
35
|
+
Provides-Extra: pdf
|
|
36
|
+
Requires-Dist: pypdf>=4; extra == "pdf"
|
|
37
|
+
Provides-Extra: all
|
|
38
|
+
Requires-Dist: multi-agent-swarm[pdf,server]; extra == "all"
|
|
39
|
+
Provides-Extra: dev
|
|
40
|
+
Requires-Dist: multi-agent-swarm[pdf,server]; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
43
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
44
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
45
|
+
Requires-Dist: matplotlib>=3.8; extra == "dev"
|
|
46
|
+
Requires-Dist: httpx>=0.27; extra == "dev"
|
|
47
|
+
Provides-Extra: docs
|
|
48
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
# Multi-Agent Swarm
|
|
52
|
+
|
|
53
|
+
**Ask a question; get a cited research report you can check.**
|
|
54
|
+
|
|
55
|
+
Parallel Claude workers each research one part of your question. They search the web for
|
|
56
|
+
**free** through [TinyFish](https://tinyfish.ai) and read the sources themselves. Code then
|
|
57
|
+
checks every quote a worker cites against the page it actually read, and throws away quotes
|
|
58
|
+
that don't match. Once the report is written, each cited sentence is checked again against
|
|
59
|
+
those quotes, and anything unsupported is marked.
|
|
60
|
+
|
|
61
|
+
[](https://github.com/Chetan0246/multi-agent-swarm/actions/workflows/ci.yml)
|
|
62
|
+

|
|
63
|
+

|
|
64
|
+

|
|
65
|
+
[](https://chetan0246.github.io/multi-agent-swarm/)
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pip install "multi-agent-swarm[all]"
|
|
69
|
+
export ANTHROPIC_API_KEY=... # Claude
|
|
70
|
+
export TINYFISH_API_KEY=... # free search + fetch: https://agent.tinyfish.ai/api-keys
|
|
71
|
+
swarm research "How do heat pumps compare to gas boilers in cold climates?" --out report.html
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Try it with no keys and no cost first: `swarm research "any question" --mock --out demo.html`.
|
|
75
|
+
|
|
76
|
+
## Features
|
|
77
|
+
|
|
78
|
+
| | |
|
|
79
|
+
|---|---|
|
|
80
|
+
| **Free web search** | TinyFish Search and Fetch as Claude tools: free within a daily allowance (12,000 searches and 1,000 pages per day). Claude's server-side search ($10 per 1,000 searches) is optional. |
|
|
81
|
+
| **Checked citations** | every quote is matched against the retrieved text; every cited claim is checked against its quotes; unsupported claims are marked in the report |
|
|
82
|
+
| **Predictable cost** | an estimate before the run, the actual cost after it, and a hard cap (`--max-usd`; presets default to $0.75, $2 or $6) |
|
|
83
|
+
| **Safe by default** | web text treated as data, not instructions; findings with injected instructions excluded; reports stripped of images, HTML and unknown links |
|
|
84
|
+
| **Your documents** | PDFs, Markdown, HTML and text files as sources (`--docs`), alone or alongside the web |
|
|
85
|
+
| **Follow-ups** | `--follow-up report.json` researches only what's new and rewrites the report |
|
|
86
|
+
| **Source filters** | domain allow/block lists, recency, news or research papers, language |
|
|
87
|
+
| **Exports** | Markdown, JSON, and self-contained HTML with hover-over source quotes |
|
|
88
|
+
| **Web UI and REST API** | `swarm serve`: live progress, history, downloads, follow-ups; Docker image |
|
|
89
|
+
| **Local cache** | repeated searches and pages cost nothing and use no quota |
|
|
90
|
+
|
|
91
|
+
## How it works
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
question ─► cost estimate (refuse if over the cap)
|
|
95
|
+
─► plan: independent sub-questions, count scaled to the question
|
|
96
|
+
─► one worker per sub-question, in parallel (a code scheduler, not an LLM manager)
|
|
97
|
+
tools: web_search / web_fetch (TinyFish), search_documents / read_document (your files)
|
|
98
|
+
answer = text + sources with VERBATIM quotes
|
|
99
|
+
code: drop any quote not found in the retrieved text
|
|
100
|
+
gate: ≥ 2 grounded sources from ≥ 2 domains, no injection markers
|
|
101
|
+
weak finding → re-researched at higher effort (low → medium → high)
|
|
102
|
+
─► synthesis from clean findings only, inline [n] citations
|
|
103
|
+
─► reference check → claim check (each cited sentence vs. its quotes) → sanitise
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The design follows the research summarised in
|
|
107
|
+
[docs/research](docs/research/Multi%20agent%20swarms%20state%20of%20the%20art.md):
|
|
108
|
+
- **Parallel workers on broad questions.** Breadth-first research is where multi-agent
|
|
109
|
+
systems have the strongest evidence: Anthropic's research system scored +90.2% over a
|
|
110
|
+
single agent.
|
|
111
|
+
- **No agent-to-agent chat.** Inter-agent misalignment is about a third of failures in the
|
|
112
|
+
MAST study.
|
|
113
|
+
- **Verification in code.** Adding verification gave +15.6% in MAST, and self-reported
|
|
114
|
+
confidence turns out to be a weak signal.
|
|
115
|
+
|
|
116
|
+
Details are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
117
|
+
|
|
118
|
+
## Usage
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
swarm research "question" --estimate # what will it cost?
|
|
122
|
+
swarm research "question" --preset quick --out r.html # quick | standard | deep
|
|
123
|
+
swarm research "question" --news --recency-days 30 # recent news only
|
|
124
|
+
swarm research "question" --papers --include-domains arxiv.org,nature.com
|
|
125
|
+
swarm research "question" --docs ./papers ./notes.md # your files + the web
|
|
126
|
+
swarm research "question" --docs ./contracts --docs-only # your files only
|
|
127
|
+
swarm research "and costs?" --follow-up r.json --out r2.html # build on an earlier report
|
|
128
|
+
swarm serve # web UI on http://127.0.0.1:8000
|
|
129
|
+
swarm doctor --online # check keys and setup
|
|
130
|
+
swarm eval --estimate # known-answer evaluation vs a single agent
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The full flag reference is in [docs/cli.md](docs/cli.md); config files and environment
|
|
134
|
+
variables are in [docs/configuration.md](docs/configuration.md); the web UI and REST API are
|
|
135
|
+
in [docs/web-api.md](docs/web-api.md).
|
|
136
|
+
|
|
137
|
+
## Costs and privacy
|
|
138
|
+
|
|
139
|
+
- **TinyFish search and fetch:** free within the daily allowance.
|
|
140
|
+
- **Claude:** charged per token. For example, `claude-opus-5-5` costs $4 per million input
|
|
141
|
+
tokens and $20 per million output tokens; `--worker-model claude-sonnet-5-5` makes the
|
|
142
|
+
workers cheaper.
|
|
143
|
+
- **Data flow:** your question and retrieved text go to Anthropic, and search queries go to
|
|
144
|
+
TinyFish. Caches stay on your machine. There is no telemetry. See
|
|
145
|
+
[docs/privacy.md](docs/privacy.md).
|
|
146
|
+
|
|
147
|
+
## Engine
|
|
148
|
+
|
|
149
|
+
Under the research layer sits a general **cost-aware, fault-tolerant scheduler** for large LLM
|
|
150
|
+
workloads (`swarm run`, `swarm bench`). It has:
|
|
151
|
+
- a pull-based queue sized to the fewest agents that still finish fast;
|
|
152
|
+
- multi-task batching, with batch size and effort learned online by Thompson sampling;
|
|
153
|
+
- effort escalation for failed tasks only;
|
|
154
|
+
- an AIMD rate limiter that understands Anthropic's 429 types;
|
|
155
|
+
- a circuit breaker, request hedging, a token budget and a write-ahead journal;
|
|
156
|
+
- a Batches API backend at half price.
|
|
157
|
+
|
|
158
|
+
On a simulated hostile endpoint it is **9–12× cheaper per task and about 3–4× faster than a
|
|
159
|
+
naive swarm, with about 4× fewer agents**:
|
|
160
|
+
|
|
161
|
+

|
|
162
|
+
|
|
163
|
+
## Development
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
pip install -e '.[dev]'
|
|
167
|
+
make lint test # ruff, mypy, 61 tests (all offline: no keys, no cost)
|
|
168
|
+
make bench chart # engine benchmark + charts
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
swarm/
|
|
175
|
+
research.py deep research: planner, tool-using workers, quote grounding, synthesis, claim check
|
|
176
|
+
search/ TinyFish (free), local documents (BM25), disk cache, mock
|
|
177
|
+
app.py options → configured run (shared by CLI and server)
|
|
178
|
+
server.py REST API + web UI (web/index.html), job store, SSE progress
|
|
179
|
+
export.py Markdown / JSON / safe self-contained HTML
|
|
180
|
+
safety.py prompt-injection detection, report sanitising
|
|
181
|
+
pricing.py list prices, run cost, estimates
|
|
182
|
+
evaluate.py known-answer evaluation vs a compute-matched single agent
|
|
183
|
+
orchestrator.py, policy.py, reliability.py, limiter.py, backends.py the scheduling engine
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Roadmap
|
|
187
|
+
|
|
188
|
+
- [ ] Publish `swarm eval` results on live search, then scale to a BrowseComp-style set.
|
|
189
|
+
- [ ] Semantic (meaning-based) matching of quotes and claims, alongside exact matching.
|
|
190
|
+
- [ ] Per-message effort escalation, so the prompt cache survives across effort levels.
|
|
191
|
+
- [ ] More search providers, and OpenTelemetry traces.
|
|
192
|
+
|
|
193
|
+
MIT licensed. Not affiliated with Anthropic or TinyFish.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Multi-Agent Swarm
|
|
2
|
+
|
|
3
|
+
**Ask a question; get a cited research report you can check.**
|
|
4
|
+
|
|
5
|
+
Parallel Claude workers each research one part of your question. They search the web for
|
|
6
|
+
**free** through [TinyFish](https://tinyfish.ai) and read the sources themselves. Code then
|
|
7
|
+
checks every quote a worker cites against the page it actually read, and throws away quotes
|
|
8
|
+
that don't match. Once the report is written, each cited sentence is checked again against
|
|
9
|
+
those quotes, and anything unsupported is marked.
|
|
10
|
+
|
|
11
|
+
[](https://github.com/Chetan0246/multi-agent-swarm/actions/workflows/ci.yml)
|
|
12
|
+

|
|
13
|
+

|
|
14
|
+

|
|
15
|
+
[](https://chetan0246.github.io/multi-agent-swarm/)
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install "multi-agent-swarm[all]"
|
|
19
|
+
export ANTHROPIC_API_KEY=... # Claude
|
|
20
|
+
export TINYFISH_API_KEY=... # free search + fetch: https://agent.tinyfish.ai/api-keys
|
|
21
|
+
swarm research "How do heat pumps compare to gas boilers in cold climates?" --out report.html
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Try it with no keys and no cost first: `swarm research "any question" --mock --out demo.html`.
|
|
25
|
+
|
|
26
|
+
## Features
|
|
27
|
+
|
|
28
|
+
| | |
|
|
29
|
+
|---|---|
|
|
30
|
+
| **Free web search** | TinyFish Search and Fetch as Claude tools: free within a daily allowance (12,000 searches and 1,000 pages per day). Claude's server-side search ($10 per 1,000 searches) is optional. |
|
|
31
|
+
| **Checked citations** | every quote is matched against the retrieved text; every cited claim is checked against its quotes; unsupported claims are marked in the report |
|
|
32
|
+
| **Predictable cost** | an estimate before the run, the actual cost after it, and a hard cap (`--max-usd`; presets default to $0.75, $2 or $6) |
|
|
33
|
+
| **Safe by default** | web text treated as data, not instructions; findings with injected instructions excluded; reports stripped of images, HTML and unknown links |
|
|
34
|
+
| **Your documents** | PDFs, Markdown, HTML and text files as sources (`--docs`), alone or alongside the web |
|
|
35
|
+
| **Follow-ups** | `--follow-up report.json` researches only what's new and rewrites the report |
|
|
36
|
+
| **Source filters** | domain allow/block lists, recency, news or research papers, language |
|
|
37
|
+
| **Exports** | Markdown, JSON, and self-contained HTML with hover-over source quotes |
|
|
38
|
+
| **Web UI and REST API** | `swarm serve`: live progress, history, downloads, follow-ups; Docker image |
|
|
39
|
+
| **Local cache** | repeated searches and pages cost nothing and use no quota |
|
|
40
|
+
|
|
41
|
+
## How it works
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
question ─► cost estimate (refuse if over the cap)
|
|
45
|
+
─► plan: independent sub-questions, count scaled to the question
|
|
46
|
+
─► one worker per sub-question, in parallel (a code scheduler, not an LLM manager)
|
|
47
|
+
tools: web_search / web_fetch (TinyFish), search_documents / read_document (your files)
|
|
48
|
+
answer = text + sources with VERBATIM quotes
|
|
49
|
+
code: drop any quote not found in the retrieved text
|
|
50
|
+
gate: ≥ 2 grounded sources from ≥ 2 domains, no injection markers
|
|
51
|
+
weak finding → re-researched at higher effort (low → medium → high)
|
|
52
|
+
─► synthesis from clean findings only, inline [n] citations
|
|
53
|
+
─► reference check → claim check (each cited sentence vs. its quotes) → sanitise
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The design follows the research summarised in
|
|
57
|
+
[docs/research](docs/research/Multi%20agent%20swarms%20state%20of%20the%20art.md):
|
|
58
|
+
- **Parallel workers on broad questions.** Breadth-first research is where multi-agent
|
|
59
|
+
systems have the strongest evidence: Anthropic's research system scored +90.2% over a
|
|
60
|
+
single agent.
|
|
61
|
+
- **No agent-to-agent chat.** Inter-agent misalignment is about a third of failures in the
|
|
62
|
+
MAST study.
|
|
63
|
+
- **Verification in code.** Adding verification gave +15.6% in MAST, and self-reported
|
|
64
|
+
confidence turns out to be a weak signal.
|
|
65
|
+
|
|
66
|
+
Details are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
67
|
+
|
|
68
|
+
## Usage
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
swarm research "question" --estimate # what will it cost?
|
|
72
|
+
swarm research "question" --preset quick --out r.html # quick | standard | deep
|
|
73
|
+
swarm research "question" --news --recency-days 30 # recent news only
|
|
74
|
+
swarm research "question" --papers --include-domains arxiv.org,nature.com
|
|
75
|
+
swarm research "question" --docs ./papers ./notes.md # your files + the web
|
|
76
|
+
swarm research "question" --docs ./contracts --docs-only # your files only
|
|
77
|
+
swarm research "and costs?" --follow-up r.json --out r2.html # build on an earlier report
|
|
78
|
+
swarm serve # web UI on http://127.0.0.1:8000
|
|
79
|
+
swarm doctor --online # check keys and setup
|
|
80
|
+
swarm eval --estimate # known-answer evaluation vs a single agent
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The full flag reference is in [docs/cli.md](docs/cli.md); config files and environment
|
|
84
|
+
variables are in [docs/configuration.md](docs/configuration.md); the web UI and REST API are
|
|
85
|
+
in [docs/web-api.md](docs/web-api.md).
|
|
86
|
+
|
|
87
|
+
## Costs and privacy
|
|
88
|
+
|
|
89
|
+
- **TinyFish search and fetch:** free within the daily allowance.
|
|
90
|
+
- **Claude:** charged per token. For example, `claude-opus-5-5` costs $4 per million input
|
|
91
|
+
tokens and $20 per million output tokens; `--worker-model claude-sonnet-5-5` makes the
|
|
92
|
+
workers cheaper.
|
|
93
|
+
- **Data flow:** your question and retrieved text go to Anthropic, and search queries go to
|
|
94
|
+
TinyFish. Caches stay on your machine. There is no telemetry. See
|
|
95
|
+
[docs/privacy.md](docs/privacy.md).
|
|
96
|
+
|
|
97
|
+
## Engine
|
|
98
|
+
|
|
99
|
+
Under the research layer sits a general **cost-aware, fault-tolerant scheduler** for large LLM
|
|
100
|
+
workloads (`swarm run`, `swarm bench`). It has:
|
|
101
|
+
- a pull-based queue sized to the fewest agents that still finish fast;
|
|
102
|
+
- multi-task batching, with batch size and effort learned online by Thompson sampling;
|
|
103
|
+
- effort escalation for failed tasks only;
|
|
104
|
+
- an AIMD rate limiter that understands Anthropic's 429 types;
|
|
105
|
+
- a circuit breaker, request hedging, a token budget and a write-ahead journal;
|
|
106
|
+
- a Batches API backend at half price.
|
|
107
|
+
|
|
108
|
+
On a simulated hostile endpoint it is **9–12× cheaper per task and about 3–4× faster than a
|
|
109
|
+
naive swarm, with about 4× fewer agents**:
|
|
110
|
+
|
|
111
|
+

|
|
112
|
+
|
|
113
|
+
## Development
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install -e '.[dev]'
|
|
117
|
+
make lint test # ruff, mypy, 61 tests (all offline: no keys, no cost)
|
|
118
|
+
make bench chart # engine benchmark + charts
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
swarm/
|
|
125
|
+
research.py deep research: planner, tool-using workers, quote grounding, synthesis, claim check
|
|
126
|
+
search/ TinyFish (free), local documents (BM25), disk cache, mock
|
|
127
|
+
app.py options → configured run (shared by CLI and server)
|
|
128
|
+
server.py REST API + web UI (web/index.html), job store, SSE progress
|
|
129
|
+
export.py Markdown / JSON / safe self-contained HTML
|
|
130
|
+
safety.py prompt-injection detection, report sanitising
|
|
131
|
+
pricing.py list prices, run cost, estimates
|
|
132
|
+
evaluate.py known-answer evaluation vs a compute-matched single agent
|
|
133
|
+
orchestrator.py, policy.py, reliability.py, limiter.py, backends.py the scheduling engine
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Roadmap
|
|
137
|
+
|
|
138
|
+
- [ ] Publish `swarm eval` results on live search, then scale to a BrowseComp-style set.
|
|
139
|
+
- [ ] Semantic (meaning-based) matching of quotes and claims, alongside exact matching.
|
|
140
|
+
- [ ] Per-message effort escalation, so the prompt cache survives across effort levels.
|
|
141
|
+
- [ ] More search providers, and OpenTelemetry traces.
|
|
142
|
+
|
|
143
|
+
MIT licensed. Not affiliated with Anthropic or TinyFish.
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: multi-agent-swarm
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: Deep research with a multi-agent swarm on Claude: free web search, parallel cited workers, every quote checked against its source
|
|
5
|
+
Author: Multi-Agent Swarm contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Chetan0246/multi-agent-swarm
|
|
8
|
+
Project-URL: Documentation, https://chetan0246.github.io/multi-agent-swarm/
|
|
9
|
+
Project-URL: Changelog, https://github.com/Chetan0246/multi-agent-swarm/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Issues, https://github.com/Chetan0246/multi-agent-swarm/issues
|
|
11
|
+
Keywords: llm,multi-agent,agents,claude,deep-research,web-search,citations,fact-checking,tinyfish,research-assistant
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Environment :: Web Environment
|
|
15
|
+
Classifier: Framework :: AsyncIO
|
|
16
|
+
Classifier: Framework :: FastAPI
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Intended Audience :: Science/Research
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: anthropic<3,>=2.12
|
|
30
|
+
Requires-Dist: httpx2>=2.0
|
|
31
|
+
Requires-Dist: tomli>=2.0; python_version < "3.11"
|
|
32
|
+
Provides-Extra: server
|
|
33
|
+
Requires-Dist: fastapi>=0.110; extra == "server"
|
|
34
|
+
Requires-Dist: uvicorn>=0.29; extra == "server"
|
|
35
|
+
Provides-Extra: pdf
|
|
36
|
+
Requires-Dist: pypdf>=4; extra == "pdf"
|
|
37
|
+
Provides-Extra: all
|
|
38
|
+
Requires-Dist: multi-agent-swarm[pdf,server]; extra == "all"
|
|
39
|
+
Provides-Extra: dev
|
|
40
|
+
Requires-Dist: multi-agent-swarm[pdf,server]; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
43
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
44
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
45
|
+
Requires-Dist: matplotlib>=3.8; extra == "dev"
|
|
46
|
+
Requires-Dist: httpx>=0.27; extra == "dev"
|
|
47
|
+
Provides-Extra: docs
|
|
48
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
# Multi-Agent Swarm
|
|
52
|
+
|
|
53
|
+
**Ask a question; get a cited research report you can check.**
|
|
54
|
+
|
|
55
|
+
Parallel Claude workers each research one part of your question. They search the web for
|
|
56
|
+
**free** through [TinyFish](https://tinyfish.ai) and read the sources themselves. Code then
|
|
57
|
+
checks every quote a worker cites against the page it actually read, and throws away quotes
|
|
58
|
+
that don't match. Once the report is written, each cited sentence is checked again against
|
|
59
|
+
those quotes, and anything unsupported is marked.
|
|
60
|
+
|
|
61
|
+
[](https://github.com/Chetan0246/multi-agent-swarm/actions/workflows/ci.yml)
|
|
62
|
+

|
|
63
|
+

|
|
64
|
+

|
|
65
|
+
[](https://chetan0246.github.io/multi-agent-swarm/)
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pip install "multi-agent-swarm[all]"
|
|
69
|
+
export ANTHROPIC_API_KEY=... # Claude
|
|
70
|
+
export TINYFISH_API_KEY=... # free search + fetch: https://agent.tinyfish.ai/api-keys
|
|
71
|
+
swarm research "How do heat pumps compare to gas boilers in cold climates?" --out report.html
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Try it with no keys and no cost first: `swarm research "any question" --mock --out demo.html`.
|
|
75
|
+
|
|
76
|
+
## Features
|
|
77
|
+
|
|
78
|
+
| | |
|
|
79
|
+
|---|---|
|
|
80
|
+
| **Free web search** | TinyFish Search and Fetch as Claude tools: free within a daily allowance (12,000 searches and 1,000 pages per day). Claude's server-side search ($10 per 1,000 searches) is optional. |
|
|
81
|
+
| **Checked citations** | every quote is matched against the retrieved text; every cited claim is checked against its quotes; unsupported claims are marked in the report |
|
|
82
|
+
| **Predictable cost** | an estimate before the run, the actual cost after it, and a hard cap (`--max-usd`; presets default to $0.75, $2 or $6) |
|
|
83
|
+
| **Safe by default** | web text treated as data, not instructions; findings with injected instructions excluded; reports stripped of images, HTML and unknown links |
|
|
84
|
+
| **Your documents** | PDFs, Markdown, HTML and text files as sources (`--docs`), alone or alongside the web |
|
|
85
|
+
| **Follow-ups** | `--follow-up report.json` researches only what's new and rewrites the report |
|
|
86
|
+
| **Source filters** | domain allow/block lists, recency, news or research papers, language |
|
|
87
|
+
| **Exports** | Markdown, JSON, and self-contained HTML with hover-over source quotes |
|
|
88
|
+
| **Web UI and REST API** | `swarm serve`: live progress, history, downloads, follow-ups; Docker image |
|
|
89
|
+
| **Local cache** | repeated searches and pages cost nothing and use no quota |
|
|
90
|
+
|
|
91
|
+
## How it works
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
question ─► cost estimate (refuse if over the cap)
|
|
95
|
+
─► plan: independent sub-questions, count scaled to the question
|
|
96
|
+
─► one worker per sub-question, in parallel (a code scheduler, not an LLM manager)
|
|
97
|
+
tools: web_search / web_fetch (TinyFish), search_documents / read_document (your files)
|
|
98
|
+
answer = text + sources with VERBATIM quotes
|
|
99
|
+
code: drop any quote not found in the retrieved text
|
|
100
|
+
gate: ≥ 2 grounded sources from ≥ 2 domains, no injection markers
|
|
101
|
+
weak finding → re-researched at higher effort (low → medium → high)
|
|
102
|
+
─► synthesis from clean findings only, inline [n] citations
|
|
103
|
+
─► reference check → claim check (each cited sentence vs. its quotes) → sanitise
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The design follows the research summarised in
|
|
107
|
+
[docs/research](docs/research/Multi%20agent%20swarms%20state%20of%20the%20art.md):
|
|
108
|
+
- **Parallel workers on broad questions.** Breadth-first research is where multi-agent
|
|
109
|
+
systems have the strongest evidence: Anthropic's research system scored +90.2% over a
|
|
110
|
+
single agent.
|
|
111
|
+
- **No agent-to-agent chat.** Inter-agent misalignment is about a third of failures in the
|
|
112
|
+
MAST study.
|
|
113
|
+
- **Verification in code.** Adding verification gave +15.6% in MAST, and self-reported
|
|
114
|
+
confidence turns out to be a weak signal.
|
|
115
|
+
|
|
116
|
+
Details are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
117
|
+
|
|
118
|
+
## Usage
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
swarm research "question" --estimate # what will it cost?
|
|
122
|
+
swarm research "question" --preset quick --out r.html # quick | standard | deep
|
|
123
|
+
swarm research "question" --news --recency-days 30 # recent news only
|
|
124
|
+
swarm research "question" --papers --include-domains arxiv.org,nature.com
|
|
125
|
+
swarm research "question" --docs ./papers ./notes.md # your files + the web
|
|
126
|
+
swarm research "question" --docs ./contracts --docs-only # your files only
|
|
127
|
+
swarm research "and costs?" --follow-up r.json --out r2.html # build on an earlier report
|
|
128
|
+
swarm serve # web UI on http://127.0.0.1:8000
|
|
129
|
+
swarm doctor --online # check keys and setup
|
|
130
|
+
swarm eval --estimate # known-answer evaluation vs a single agent
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The full flag reference is in [docs/cli.md](docs/cli.md); config files and environment
|
|
134
|
+
variables are in [docs/configuration.md](docs/configuration.md); the web UI and REST API are
|
|
135
|
+
in [docs/web-api.md](docs/web-api.md).
|
|
136
|
+
|
|
137
|
+
## Costs and privacy
|
|
138
|
+
|
|
139
|
+
- **TinyFish search and fetch:** free within the daily allowance.
|
|
140
|
+
- **Claude:** charged per token. For example, `claude-opus-5-5` costs $4 per million input
|
|
141
|
+
tokens and $20 per million output tokens; `--worker-model claude-sonnet-5-5` makes the
|
|
142
|
+
workers cheaper.
|
|
143
|
+
- **Data flow:** your question and retrieved text go to Anthropic, and search queries go to
|
|
144
|
+
TinyFish. Caches stay on your machine. There is no telemetry. See
|
|
145
|
+
[docs/privacy.md](docs/privacy.md).
|
|
146
|
+
|
|
147
|
+
## Engine
|
|
148
|
+
|
|
149
|
+
Under the research layer sits a general **cost-aware, fault-tolerant scheduler** for large LLM
|
|
150
|
+
workloads (`swarm run`, `swarm bench`). It has:
|
|
151
|
+
- a pull-based queue sized to the fewest agents that still finish fast;
|
|
152
|
+
- multi-task batching, with batch size and effort learned online by Thompson sampling;
|
|
153
|
+
- effort escalation for failed tasks only;
|
|
154
|
+
- an AIMD rate limiter that understands Anthropic's 429 types;
|
|
155
|
+
- a circuit breaker, request hedging, a token budget and a write-ahead journal;
|
|
156
|
+
- a Batches API backend at half price.
|
|
157
|
+
|
|
158
|
+
On a simulated hostile endpoint it is **9–12× cheaper per task and about 3–4× faster than a
|
|
159
|
+
naive swarm, with about 4× fewer agents**:
|
|
160
|
+
|
|
161
|
+

|
|
162
|
+
|
|
163
|
+
## Development
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
pip install -e '.[dev]'
|
|
167
|
+
make lint test # ruff, mypy, 61 tests (all offline: no keys, no cost)
|
|
168
|
+
make bench chart # engine benchmark + charts
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
swarm/
|
|
175
|
+
research.py deep research: planner, tool-using workers, quote grounding, synthesis, claim check
|
|
176
|
+
search/ TinyFish (free), local documents (BM25), disk cache, mock
|
|
177
|
+
app.py options → configured run (shared by CLI and server)
|
|
178
|
+
server.py REST API + web UI (web/index.html), job store, SSE progress
|
|
179
|
+
export.py Markdown / JSON / safe self-contained HTML
|
|
180
|
+
safety.py prompt-injection detection, report sanitising
|
|
181
|
+
pricing.py list prices, run cost, estimates
|
|
182
|
+
evaluate.py known-answer evaluation vs a compute-matched single agent
|
|
183
|
+
orchestrator.py, policy.py, reliability.py, limiter.py, backends.py the scheduling engine
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Roadmap
|
|
187
|
+
|
|
188
|
+
- [ ] Publish `swarm eval` results on live search, then scale to a BrowseComp-style set.
|
|
189
|
+
- [ ] Semantic (meaning-based) matching of quotes and claims, alongside exact matching.
|
|
190
|
+
- [ ] Per-message effort escalation, so the prompt cache survives across effort levels.
|
|
191
|
+
- [ ] More search providers, and OpenTelemetry traces.
|
|
192
|
+
|
|
193
|
+
MIT licensed. Not affiliated with Anthropic or TinyFish.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
multi_agent_swarm.egg-info/PKG-INFO
|
|
5
|
+
multi_agent_swarm.egg-info/SOURCES.txt
|
|
6
|
+
multi_agent_swarm.egg-info/dependency_links.txt
|
|
7
|
+
multi_agent_swarm.egg-info/entry_points.txt
|
|
8
|
+
multi_agent_swarm.egg-info/requires.txt
|
|
9
|
+
multi_agent_swarm.egg-info/top_level.txt
|
|
10
|
+
swarm/__init__.py
|
|
11
|
+
swarm/__main__.py
|
|
12
|
+
swarm/app.py
|
|
13
|
+
swarm/backends.py
|
|
14
|
+
swarm/config.py
|
|
15
|
+
swarm/errors.py
|
|
16
|
+
swarm/evaluate.py
|
|
17
|
+
swarm/export.py
|
|
18
|
+
swarm/limiter.py
|
|
19
|
+
swarm/orchestrator.py
|
|
20
|
+
swarm/planner.py
|
|
21
|
+
swarm/policy.py
|
|
22
|
+
swarm/pricing.py
|
|
23
|
+
swarm/reliability.py
|
|
24
|
+
swarm/research.py
|
|
25
|
+
swarm/safety.py
|
|
26
|
+
swarm/server.py
|
|
27
|
+
swarm/task.py
|
|
28
|
+
swarm/workloads.py
|
|
29
|
+
swarm/search/__init__.py
|
|
30
|
+
swarm/search/base.py
|
|
31
|
+
swarm/search/cache.py
|
|
32
|
+
swarm/search/local.py
|
|
33
|
+
swarm/search/mock.py
|
|
34
|
+
swarm/search/tinyfish.py
|
|
35
|
+
swarm/web/index.html
|
|
36
|
+
tests/test_product.py
|
|
37
|
+
tests/test_research.py
|
|
38
|
+
tests/test_swarm.py
|
|
39
|
+
tests/test_v3.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
anthropic<3,>=2.12
|
|
2
|
+
httpx2>=2.0
|
|
3
|
+
|
|
4
|
+
[:python_version < "3.11"]
|
|
5
|
+
tomli>=2.0
|
|
6
|
+
|
|
7
|
+
[all]
|
|
8
|
+
multi-agent-swarm[pdf,server]
|
|
9
|
+
|
|
10
|
+
[dev]
|
|
11
|
+
multi-agent-swarm[pdf,server]
|
|
12
|
+
pytest>=8
|
|
13
|
+
pytest-cov>=5
|
|
14
|
+
ruff>=0.6
|
|
15
|
+
mypy>=1.10
|
|
16
|
+
matplotlib>=3.8
|
|
17
|
+
httpx>=0.27
|
|
18
|
+
|
|
19
|
+
[docs]
|
|
20
|
+
mkdocs-material>=9.5
|
|
21
|
+
|
|
22
|
+
[pdf]
|
|
23
|
+
pypdf>=4
|
|
24
|
+
|
|
25
|
+
[server]
|
|
26
|
+
fastapi>=0.110
|
|
27
|
+
uvicorn>=0.29
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
swarm
|