localagentbrowser 1.64__tar.gz → 1.64.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.
Files changed (44) hide show
  1. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/CHANGELOG.md +9 -0
  2. localagentbrowser-1.64.1/PKG-INFO +337 -0
  3. localagentbrowser-1.64.1/README.md +305 -0
  4. localagentbrowser-1.64.1/localagentbrowser.egg-info/PKG-INFO +337 -0
  5. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/pyproject.toml +1 -1
  6. localagentbrowser-1.64/PKG-INFO +0 -573
  7. localagentbrowser-1.64/README.md +0 -541
  8. localagentbrowser-1.64/localagentbrowser.egg-info/PKG-INFO +0 -573
  9. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/LICENSE +0 -0
  10. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/MANIFEST.in +0 -0
  11. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/agent_browser.py +0 -0
  12. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/__init__.py +0 -0
  13. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/agent.py +0 -0
  14. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/checklist.py +0 -0
  15. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/checks.py +0 -0
  16. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/config.py +0 -0
  17. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/coverage.py +0 -0
  18. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/grounding.py +0 -0
  19. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/pages.py +0 -0
  20. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/prompts.py +0 -0
  21. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/report.py +0 -0
  22. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser/text.py +0 -0
  23. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/SOURCES.txt +0 -0
  24. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/dependency_links.txt +0 -0
  25. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/entry_points.txt +0 -0
  26. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/requires.txt +0 -0
  27. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/top_level.txt +0 -0
  28. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/setup.cfg +0 -0
  29. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/conftest.py +0 -0
  30. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/fakes.py +0 -0
  31. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/golden/prompts.json +0 -0
  32. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_checklist.py +0 -0
  33. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_decisions.py +0 -0
  34. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_duplicates.py +0 -0
  35. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_golden_prompts.py +0 -0
  36. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_journal.py +0 -0
  37. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_main_loop.py +0 -0
  38. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_model_turns.py +0 -0
  39. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_page_text.py +0 -0
  40. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_regression.py +0 -0
  41. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tests/test_show_report.py +0 -0
  42. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tools/live_test.py +0 -0
  43. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tools/regression.py +0 -0
  44. {localagentbrowser-1.64 → localagentbrowser-1.64.1}/tools/windows/show_report.py +0 -0
@@ -6,6 +6,15 @@ measured on the regression suite and released as part of 1.57 and 1.61 (see
6
6
  Timings are from live runs on the development machine (Intel i5-9500, 6 cores, no GPU, Qwen2.5-7B-Instruct
7
7
  Q4_K_M in LM Studio), where reading the prompt takes about 90% of every model call.
8
8
 
9
+ ## [1.64.1] - 2026-11-08
10
+ Documentation only; the code is unchanged from 1.64, as measured.
11
+ - **README revamped,** so PyPI's page shows it too: the four models tested near the top, with download size, RAM and
12
+ results; install steps with the virtual-environment commands; a first-run guide (load the model at 8192 context);
13
+ Windows shortcuts. The long technical sections moved to docs/how-it-works.md and docs/task-results.md.
14
+ - **Fixed in the README:** the FAQ's model table showed the October results, and a link was broken on PyPI.
15
+ - **Project site:** a "pick the model that fits your PC" section, an Install section, and its charts redrawn with
16
+ 1.64's results.
17
+
9
18
  ## [1.64] - 2026-11-08
10
19
  The theme is **silent omission** ([issue #11](https://github.com/SnowFXXX/LocalAgentBrowser/issues/11)): a part of
11
20
  the objective dropping out of the final answer without being marked "not found". It was measured on two PCs (PC A
@@ -0,0 +1,337 @@
1
+ Metadata-Version: 2.4
2
+ Name: localagentbrowser
3
+ Version: 1.64.1
4
+ Summary: An autonomous web agent driven by a local LLM (LM Studio) and Playwright. Runs entirely on your own machine.
5
+ Author: SnowFX
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/SnowFXXX/LocalAgentBrowser
8
+ Project-URL: Changelog, https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/SnowFXXX/LocalAgentBrowser/issues
10
+ Keywords: ai-agent,autonomous-agent,llm,local-llm,lm-studio,playwright,browser-automation,web-agent,web-research,qwen,offline-ai
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
22
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: openai>=2.0
27
+ Requires-Dist: playwright>=1.50
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=8; extra == "dev"
30
+ Requires-Dist: ruff>=0.15; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ # LocalAgentBrowser
34
+
35
+ **An autonomous web agent powered by a local LLM. Give it an objective; it searches, reads, takes notes and
36
+ decides when it's done, on your own computer. It gives an answer you can check, or says honestly what it couldn't
37
+ find.**
38
+
39
+ [![Tests](https://github.com/SnowFXXX/LocalAgentBrowser/actions/workflows/tests.yml/badge.svg)](https://github.com/SnowFXXX/LocalAgentBrowser/actions/workflows/tests.yml)
40
+ [![PyPI](https://img.shields.io/pypi/v/localagentbrowser.svg)](https://pypi.org/project/localagentbrowser/)
41
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/LICENSE)
42
+ ![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)
43
+ ![Runs locally](https://img.shields.io/badge/LLM-local%20(LM%20Studio)-green.svg)
44
+
45
+ <p align="center">
46
+ <img src="https://raw.githubusercontent.com/SnowFXXX/LocalAgentBrowser/main/docs/social-preview.png" alt="LocalAgentBrowser: SEARCH, NAVIGATE, READ_MORE, DISCOVER, FINISH. No cloud AI, 7B model on a CPU, LM Studio and Playwright." width="820">
47
+ </p>
48
+
49
+ A local language model served by [LM Studio](https://lmstudio.ai) decides what to do next, and
50
+ [Playwright](https://playwright.dev/python/) carries it out in a Chromium window you can watch. It is built for a
51
+ **small model on an ordinary CPU, no GPU required**, and every claim in its answer points to the page it came from.
52
+
53
+ - 🔒 **No cloud AI and no API keys.** The model runs in your own LM Studio; your objective, the model and the
54
+ report stay on your computer. (Searches go to DuckDuckGo and pages load like in any browser.)
55
+ - ✅ **Checks instead of trust.** Findings must be copied from the page shown, commands must appear on the page
56
+ exactly, and numbers no finding gives are cut. What it can't find is listed as not found, not filled in.
57
+ - 🧭 **Unattended.** It searches, opens pages, reads long pages part by part, records what's relevant and finishes
58
+ when every part of the objective is covered.
59
+ - 📝 **A report every time.** The final result with numbered citations and every finding with its source, written
60
+ however the run ends.
61
+ - 🪟 **Windows shortcuts.** A launcher with Start-menu and desktop shortcuts opens the report by itself when a run
62
+ ends. A Windows installer is coming in the next release.
63
+
64
+ 📖 [Project site](https://snowfxxx.github.io/LocalAgentBrowser/) ·
65
+ [Article: We Can Do Better: A Small AI That Can't Cover Up](https://snowfxxx.github.io/LocalAgentBrowser/article.html) ·
66
+ [Paper: Verification over Trust](https://snowfxxx.github.io/LocalAgentBrowser/paper.html) ·
67
+ [Example reports](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/examples/README.md)
68
+
69
+ ## Contents
70
+
71
+ [Tested on four models](#tested-on-four-models) · [Install](#install) · [First run](#first-run) ·
72
+ [What a run looks like](#what-a-run-looks-like) · [How it works](#how-it-works) · [Settings](#settings) ·
73
+ [FAQ](#faq) · [Limitations](#limitations) · [Roadmap](#roadmap) · [Testing](#testing) · [Contributing](#contributing)
74
+
75
+ ## Tested on four models
76
+
77
+ Every release is measured on the same seven tasks, one of each kind it's built for: a fact, a list with conditions,
78
+ a comparison with a recommendation, a how-to, an explanation, views from several sources, and a lookup in official
79
+ documentation. In 1.64, four models ran them with identical code, 90 minutes per task, on an ordinary 6-core PC with
80
+ no GPU (Intel i5-9500):
81
+
82
+ | Model (Q4_K_M) | Download | RAM | Tasks finished | Model time | Gaps filled from its own knowledge |
83
+ |---|---|---|---|---|---|
84
+ | **Qwen2.5-7B-Instruct** (default) | 4.7 GB | 8 GB | 6 of 7 | 361 min | 0 |
85
+ | **Llama-3.1-8B-Instruct** | 4.9 GB | 8 GB | **7 of 7** | 303 min | 0 |
86
+ | **Qwen2.5-14B-Instruct** | 9.0 GB | 16 GB | 5 of 7 | 565 min | 0 |
87
+ | **Qwen2.5-3B-Instruct** | 1.9 GB | 4 GB | 3 of 7 | 490 min | 0 |
88
+
89
+ - **No finished result filled a gap from the model's own knowledge**, on any model.
90
+ - **Llama finished every task.** Read by hand, its results contain no invented facts; its mistakes lean cautious
91
+ (a "not found" for something its findings do give).
92
+ - **The 14B** is about 2.5 times slower on a CPU; its two time-outs came while a correct answer was being checked.
93
+ - **The 3B** fits small PCs. It finished 3 tasks (none on 1.63), and one of them has a claim the checks missed.
94
+ - On 1.63 the same models finished 6, 2, 2 and 0 of 7. Every step and run is in the
95
+ [regression history](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/regression-history.md).
96
+
97
+ **Which to pick:** the 7B for most PCs, Llama if you have the same 8 GB and want it to finish more often, the 3B for
98
+ a PC with little memory. Any instruction-tuned model LM Studio serves should work.
99
+
100
+ ## Install
101
+
102
+ You need [LM Studio](https://lmstudio.ai) (free), which runs the model, and Python 3.10 or later.
103
+
104
+ ### Any system: pip
105
+
106
+ ```bash
107
+ python -m venv venv
108
+ venv\Scripts\activate
109
+ pip install localagentbrowser
110
+ python -m playwright install chromium
111
+ ```
112
+
113
+ On macOS or Linux, activate with `source venv/bin/activate` instead.
114
+
115
+ ### From source
116
+
117
+ ```bash
118
+ git clone https://github.com/SnowFXXX/LocalAgentBrowser.git
119
+ cd LocalAgentBrowser
120
+ python -m venv venv
121
+ venv\Scriptsctivate
122
+ pip install -r requirements.txt
123
+ python -m playwright install chromium
124
+ ```
125
+
126
+ Run it with `python agent_browser.py`.
127
+
128
+ ### Windows: Start-menu and desktop shortcuts
129
+
130
+ From a clone (above), with its packages installed in a `venv` folder inside it:
131
+
132
+ ```bash
133
+ powershell -ExecutionPolicy Bypass -File tools\windows\make_shortcuts.ps1
134
+ ```
135
+
136
+ This adds **LocalAgentBrowser** to the Start menu and the desktop. The launcher checks that LM Studio is answering,
137
+ runs each objective in its own folder under **Documents\LocalAgentBrowser runs**, and opens the report as a page in
138
+ your browser when the run ends.
139
+
140
+ **Coming in the next release:** a Windows installer that brings its own Python, lets you pick one of the four tested
141
+ models during setup, and adds the shortcuts for you.
142
+
143
+ ## First run
144
+
145
+ 1. In LM Studio, load your model with a **context length of 8192** (the agent's default; LM Studio's own default may
146
+ differ) and start the local server (Developer tab → Start Server).
147
+ 2. Start LocalAgentBrowser: the Start-menu shortcut on Windows, or `localagentbrowser` in a terminal.
148
+ 3. Type your objective, for example *What is the tallest mountain in Africa, and how tall is it in meters and in
149
+ feet?* A Chromium window opens and the agent starts working. The first step takes a minute or two on a CPU.
150
+ 4. When it finishes, the report opens in your browser (Windows launcher), or read `research_report.md` in the folder
151
+ you ran it from. Runs from the shortcut each get their own folder under **Documents\LocalAgentBrowser runs**.
152
+
153
+ A run takes about 10 to 60 minutes on a CPU. Press Ctrl+C at any time to stop; the report is still written with
154
+ everything found so far.
155
+
156
+ **Good objectives** are questions you'd research by reading pages: a fact, a list with conditions ("three free,
157
+ open-source alternatives to Photoshop"), a comparison, a how-to, an explanation, or what several sources say.
158
+ **Not yet:** anything behind a login, a form or a button (it reads pages; it doesn't click or type into them).
159
+
160
+ ## What a run looks like
161
+
162
+ A real run (1.40, with the timing lines the [test runner](#testing) adds; repetitive lines left out). Objective:
163
+ *"What is the tallest mountain in Africa, and how tall is it in meters and in feet?"*
164
+
165
+ ```text
166
+ 🧠 [TURN 1/100] Active reasoning cycle executing...
167
+ (model call 38.6s, prompt=676 tok, completion=54 tok)
168
+ 🎬 Chosen Action: [SEARCH] -> Parameter: tallest mountain in Africa
169
+
170
+ 🧠 [TURN 2/100] Active reasoning cycle executing...
171
+ 💡 Agent Thoughts: From the search results, I can see that Mount Kilimanjaro is mentioned as the tallest
172
+ mountain in Africa ... I will navigate to one of these pages to find the exact height in meters and feet.
173
+ 🎬 Chosen Action: [NAVIGATE] -> Parameter: https://en.wikipedia.org/wiki/Mount_Kilimanjaro
174
+
175
+ 🧠 [TURN 3/100] Active reasoning cycle executing...
176
+ 🎬 Chosen Action: [DISCOVER] -> Parameter: Mount Kilimanjaro is the highest mountain in Africa, with an
177
+ elevation of 5,895 m (19,341 ft) above sea level.
178
+
179
+ 🧠 [TURN 4/100] Active reasoning cycle executing...
180
+ ♻️ Cheap retry 1/2: [FINISH] refused. Your only discovery comes from
181
+ https://en.wikipedia.org/wiki/Mount_Kilimanjaro. Consider whether the objective needs more. ...
182
+ Before finishing, split the OBJECTIVE into its separate parts and, in thought_process, write each
183
+ part followed by the discovery that covers it, or 'not covered'. ...
184
+ 💡 Agent Thoughts: The objective has two parts: the name of the tallest mountain in Africa and its height
185
+ in meters and feet. Both are covered by the discovery from Mount Kilimanjaro's Wikipedia page.
186
+ 🎬 Chosen Action: [FINISH] -> Parameter: The tallest mountain in Africa is Mount Kilimanjaro ...
187
+ 🎯 Agent has signaled mission complete. Writing the final result...
188
+ ```
189
+
190
+ Four turns and 11.8 minutes of model time. The report it wrote:
191
+
192
+ > **Final result:** The tallest mountain in Africa is Mount Kilimanjaro [1], and its elevation is 5,895 meters
193
+ > (19,341 feet) above sea level [1].
194
+ >
195
+ > **Discoveries (1)**
196
+ > 1. Turn 3, from https://en.wikipedia.org/wiki/Mount_Kilimanjaro: *Mount Kilimanjaro is the highest mountain
197
+ > in Africa, with an elevation of 5,895 m (19,341 ft) above sea level.*
198
+
199
+ ## How it works
200
+
201
+ Each turn, the model sees the objective, what it has found so far, its recent actions and the current page, and
202
+ answers with one JSON action:
203
+
204
+ | Action | What it does |
205
+ |---|---|
206
+ | `SEARCH` | Searches DuckDuckGo and shows the results with their real addresses |
207
+ | `NAVIGATE` | Opens an address from the results or the current page's links |
208
+ | `READ_MORE` | Shows the next part of a long page, or the part whose outline names what's still missing |
209
+ | `DISCOVER` | Records something from the current page as a finding |
210
+ | `FINISH` | Ends the run, after each part of the objective is checked; the answer is then written in a separate step |
211
+
212
+ ```mermaid
213
+ flowchart LR
214
+ O[Objective] --> P[Build prompt]
215
+ P --> M[Local model<br/>LM Studio]
216
+ M -->|JSON action| C{Checks in code}
217
+ C -->|refused: cheap retry| M
218
+ C -->|accepted| B[Playwright<br/>Chromium]
219
+ B -->|page text, links| P
220
+ C -->|FINISH| R[Report]
221
+ ```
222
+
223
+ The model proposes; code checks before anything is accepted:
224
+ - **A fixed checklist** of the objective's parts, made once at the start, that every later check uses.
225
+ - **Findings must come from the page:** they're compared with the page text shown, and commands must appear on the
226
+ page exactly.
227
+ - **Finishing is checked part by part,** and the agent is sent back only for gaps the code can confirm: a part
228
+ nothing answers, fewer things than asked for, missing amounts, a concrete missing term such as "O2".
229
+ - **The answer is written separately,** from the findings only. Names, numbers and commands no finding gives are cut
230
+ and named, and parts nothing answers are listed as "Not found in the pages read".
231
+ - **Built for a CPU:** it reuses LM Studio's prompt cache, so most turns only process what changed.
232
+
233
+ The full details, code layout, timings and known limits:
234
+ [docs/how-it-works.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/how-it-works.md).
235
+
236
+ ## Settings
237
+
238
+ | Environment variable | Default | Meaning |
239
+ |---|---|---|
240
+ | `LMSTUDIO_BASE_URL` | `http://localhost:1234/v1` | Address of the OpenAI-compatible server |
241
+ | `LMSTUDIO_MODEL` | `qwen2.5-7b-instruct` | Model identifier as the server lists it |
242
+ | `LMSTUDIO_API_KEY` | `lm-studio` | API key, if your server requires one |
243
+ | `LMSTUDIO_CONTEXT_LENGTH` | `8192` | Context length the model is loaded with; the conversation budget follows it |
244
+
245
+ Behaviour limits are named constants in `localagentbrowser/config.py`, each with a comment.
246
+
247
+ ## FAQ
248
+
249
+ **Does it need a GPU?** No. It was developed entirely on a CPU; a GPU just makes each turn faster.
250
+
251
+ **Why does a turn take minutes?** On a CPU the model reads the prompt slowly (about 8 tokens a second on the
252
+ development PC), so a turn that brings in a new page takes a few minutes. Most other turns reuse LM Studio's cache.
253
+
254
+ **Is anything sent to the internet?** No AI service is involved, and nothing about your run is uploaded. The agent
255
+ does browse the real web: searches, written from your objective, go to DuckDuckGo, and pages load normally.
256
+
257
+ **Can I use another OpenAI-compatible server?** Probably: point `LMSTUDIO_BASE_URL` at it. The speed tricks rely
258
+ on the server reusing cached prompt prefixes (llama.cpp-based servers do).
259
+
260
+ **Where are the results?** `research_report.md` (the answer and every finding with its source) and
261
+ `research_log.txt` (every action and reason), in the run's folder.
262
+
263
+ ## Limitations
264
+
265
+ - **Judging whether a finding really answers a part is the weakest area.** The model can credit a finding about the
266
+ right topic to the wrong part (a "create" command for "activate"), or put the wrong number on a citation. Check
267
+ claims against the listed findings.
268
+ - **Reading only:** it doesn't click, fill in forms or sign in, and some sites refuse automated browsers.
269
+ - **Web pages go into the prompt,** so a page could try to manipulate the model (prompt injection); treat findings as
270
+ unverified. See [SECURITY.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/SECURITY.md).
271
+ - **Seven kinds of task so far.** Others may expose new problems; reports are welcome.
272
+
273
+ More in [docs/how-it-works.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/how-it-works.md#limitations).
274
+
275
+ ## Roadmap
276
+
277
+ - [x] A fixed checklist, a coverage check verified in code, and every change measured on a regression suite (1.53–1.61)
278
+ - [x] Exact-text command checks, and four models measured on identical code (1.63)
279
+ - [x] Parts of the objective no longer dropped silently as often; the Windows launcher (1.64)
280
+ - [ ] A Windows installer with its own Python and a choice of tested models (next release)
281
+ - [ ] Count silent omissions in the regression suite, so [issue #11](https://github.com/SnowFXXX/LocalAgentBrowser/issues/11) can close on a number
282
+ - [ ] Decide in code, not by asking the model, whether a finding answers the part it's credited to
283
+ - [ ] A tray app on Windows: new research, progress, a notification when done
284
+ - [ ] Rewind dead ends: return to a saved point instead of carrying an unused page in every later prompt
285
+ - [ ] Interacting with pages (clicking, forms) for tasks beyond reading
286
+
287
+ Ideas and requests are welcome in [issues](https://github.com/SnowFXXX/LocalAgentBrowser/issues).
288
+
289
+ ## Testing
290
+
291
+ The test suite runs in a few seconds with no model or browser: both are replaced by scripted fakes.
292
+
293
+ ```bash
294
+ pip install -r requirements-dev.txt
295
+ python -m pytest
296
+ python -m ruff check .
297
+ ```
298
+
299
+ To try the real agent with a fixed objective and a time limit, logging every model call:
300
+
301
+ ```bash
302
+ python tools/live_test.py "Your objective here" --minutes 25
303
+ ```
304
+
305
+ To measure a change on all seven kinds of task (several hours on a CPU), on any model LM Studio has:
306
+
307
+ ```bash
308
+ python tools/regression.py --model qwen2.5-7b-instruct --baseline regression_runs/<earlier run>/summary.json
309
+ ```
310
+
311
+ Each run gets a folder in `regression_runs/` with every task's report, journal and prompt trace, a `summary.md`
312
+ with honesty measures for each result, and `run_info.json` naming the PC and the exact code it ran. Results by kind
313
+ of task are in [docs/task-results.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/task-results.md),
314
+ and every step since 1.53 in
315
+ [docs/regression-history.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/regression-history.md).
316
+
317
+ ## Contributing
318
+
319
+ Contributions are welcome! See [CONTRIBUTING.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CONTRIBUTING.md)
320
+ and the [Code of Conduct](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CODE_OF_CONDUCT.md). Security issues:
321
+ [SECURITY.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/SECURITY.md).
322
+
323
+ ## Project history
324
+
325
+ Every released version is a tagged commit, and
326
+ [CHANGELOG.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CHANGELOG.md) says what changed and why, with
327
+ the measurements behind each decision.
328
+
329
+ ## Acknowledgements
330
+
331
+ Versions 1.13 onwards were developed together with [Claude](https://www.anthropic.com/claude) (Anthropic), working
332
+ in Claude Code; those commits list Claude as co-author. Built on [LM Studio](https://lmstudio.ai),
333
+ [Playwright](https://playwright.dev/python/) and the [OpenAI Python library](https://github.com/openai/openai-python).
334
+
335
+ ## License
336
+
337
+ [MIT](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/LICENSE) © 2026 SnowFX
@@ -0,0 +1,305 @@
1
+ # LocalAgentBrowser
2
+
3
+ **An autonomous web agent powered by a local LLM. Give it an objective; it searches, reads, takes notes and
4
+ decides when it's done, on your own computer. It gives an answer you can check, or says honestly what it couldn't
5
+ find.**
6
+
7
+ [![Tests](https://github.com/SnowFXXX/LocalAgentBrowser/actions/workflows/tests.yml/badge.svg)](https://github.com/SnowFXXX/LocalAgentBrowser/actions/workflows/tests.yml)
8
+ [![PyPI](https://img.shields.io/pypi/v/localagentbrowser.svg)](https://pypi.org/project/localagentbrowser/)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/LICENSE)
10
+ ![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)
11
+ ![Runs locally](https://img.shields.io/badge/LLM-local%20(LM%20Studio)-green.svg)
12
+
13
+ <p align="center">
14
+ <img src="https://raw.githubusercontent.com/SnowFXXX/LocalAgentBrowser/main/docs/social-preview.png" alt="LocalAgentBrowser: SEARCH, NAVIGATE, READ_MORE, DISCOVER, FINISH. No cloud AI, 7B model on a CPU, LM Studio and Playwright." width="820">
15
+ </p>
16
+
17
+ A local language model served by [LM Studio](https://lmstudio.ai) decides what to do next, and
18
+ [Playwright](https://playwright.dev/python/) carries it out in a Chromium window you can watch. It is built for a
19
+ **small model on an ordinary CPU, no GPU required**, and every claim in its answer points to the page it came from.
20
+
21
+ - 🔒 **No cloud AI and no API keys.** The model runs in your own LM Studio; your objective, the model and the
22
+ report stay on your computer. (Searches go to DuckDuckGo and pages load like in any browser.)
23
+ - ✅ **Checks instead of trust.** Findings must be copied from the page shown, commands must appear on the page
24
+ exactly, and numbers no finding gives are cut. What it can't find is listed as not found, not filled in.
25
+ - 🧭 **Unattended.** It searches, opens pages, reads long pages part by part, records what's relevant and finishes
26
+ when every part of the objective is covered.
27
+ - 📝 **A report every time.** The final result with numbered citations and every finding with its source, written
28
+ however the run ends.
29
+ - 🪟 **Windows shortcuts.** A launcher with Start-menu and desktop shortcuts opens the report by itself when a run
30
+ ends. A Windows installer is coming in the next release.
31
+
32
+ 📖 [Project site](https://snowfxxx.github.io/LocalAgentBrowser/) ·
33
+ [Article: We Can Do Better: A Small AI That Can't Cover Up](https://snowfxxx.github.io/LocalAgentBrowser/article.html) ·
34
+ [Paper: Verification over Trust](https://snowfxxx.github.io/LocalAgentBrowser/paper.html) ·
35
+ [Example reports](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/examples/README.md)
36
+
37
+ ## Contents
38
+
39
+ [Tested on four models](#tested-on-four-models) · [Install](#install) · [First run](#first-run) ·
40
+ [What a run looks like](#what-a-run-looks-like) · [How it works](#how-it-works) · [Settings](#settings) ·
41
+ [FAQ](#faq) · [Limitations](#limitations) · [Roadmap](#roadmap) · [Testing](#testing) · [Contributing](#contributing)
42
+
43
+ ## Tested on four models
44
+
45
+ Every release is measured on the same seven tasks, one of each kind it's built for: a fact, a list with conditions,
46
+ a comparison with a recommendation, a how-to, an explanation, views from several sources, and a lookup in official
47
+ documentation. In 1.64, four models ran them with identical code, 90 minutes per task, on an ordinary 6-core PC with
48
+ no GPU (Intel i5-9500):
49
+
50
+ | Model (Q4_K_M) | Download | RAM | Tasks finished | Model time | Gaps filled from its own knowledge |
51
+ |---|---|---|---|---|---|
52
+ | **Qwen2.5-7B-Instruct** (default) | 4.7 GB | 8 GB | 6 of 7 | 361 min | 0 |
53
+ | **Llama-3.1-8B-Instruct** | 4.9 GB | 8 GB | **7 of 7** | 303 min | 0 |
54
+ | **Qwen2.5-14B-Instruct** | 9.0 GB | 16 GB | 5 of 7 | 565 min | 0 |
55
+ | **Qwen2.5-3B-Instruct** | 1.9 GB | 4 GB | 3 of 7 | 490 min | 0 |
56
+
57
+ - **No finished result filled a gap from the model's own knowledge**, on any model.
58
+ - **Llama finished every task.** Read by hand, its results contain no invented facts; its mistakes lean cautious
59
+ (a "not found" for something its findings do give).
60
+ - **The 14B** is about 2.5 times slower on a CPU; its two time-outs came while a correct answer was being checked.
61
+ - **The 3B** fits small PCs. It finished 3 tasks (none on 1.63), and one of them has a claim the checks missed.
62
+ - On 1.63 the same models finished 6, 2, 2 and 0 of 7. Every step and run is in the
63
+ [regression history](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/regression-history.md).
64
+
65
+ **Which to pick:** the 7B for most PCs, Llama if you have the same 8 GB and want it to finish more often, the 3B for
66
+ a PC with little memory. Any instruction-tuned model LM Studio serves should work.
67
+
68
+ ## Install
69
+
70
+ You need [LM Studio](https://lmstudio.ai) (free), which runs the model, and Python 3.10 or later.
71
+
72
+ ### Any system: pip
73
+
74
+ ```bash
75
+ python -m venv venv
76
+ venv\Scripts\activate
77
+ pip install localagentbrowser
78
+ python -m playwright install chromium
79
+ ```
80
+
81
+ On macOS or Linux, activate with `source venv/bin/activate` instead.
82
+
83
+ ### From source
84
+
85
+ ```bash
86
+ git clone https://github.com/SnowFXXX/LocalAgentBrowser.git
87
+ cd LocalAgentBrowser
88
+ python -m venv venv
89
+ venv\Scriptsctivate
90
+ pip install -r requirements.txt
91
+ python -m playwright install chromium
92
+ ```
93
+
94
+ Run it with `python agent_browser.py`.
95
+
96
+ ### Windows: Start-menu and desktop shortcuts
97
+
98
+ From a clone (above), with its packages installed in a `venv` folder inside it:
99
+
100
+ ```bash
101
+ powershell -ExecutionPolicy Bypass -File tools\windows\make_shortcuts.ps1
102
+ ```
103
+
104
+ This adds **LocalAgentBrowser** to the Start menu and the desktop. The launcher checks that LM Studio is answering,
105
+ runs each objective in its own folder under **Documents\LocalAgentBrowser runs**, and opens the report as a page in
106
+ your browser when the run ends.
107
+
108
+ **Coming in the next release:** a Windows installer that brings its own Python, lets you pick one of the four tested
109
+ models during setup, and adds the shortcuts for you.
110
+
111
+ ## First run
112
+
113
+ 1. In LM Studio, load your model with a **context length of 8192** (the agent's default; LM Studio's own default may
114
+ differ) and start the local server (Developer tab → Start Server).
115
+ 2. Start LocalAgentBrowser: the Start-menu shortcut on Windows, or `localagentbrowser` in a terminal.
116
+ 3. Type your objective, for example *What is the tallest mountain in Africa, and how tall is it in meters and in
117
+ feet?* A Chromium window opens and the agent starts working. The first step takes a minute or two on a CPU.
118
+ 4. When it finishes, the report opens in your browser (Windows launcher), or read `research_report.md` in the folder
119
+ you ran it from. Runs from the shortcut each get their own folder under **Documents\LocalAgentBrowser runs**.
120
+
121
+ A run takes about 10 to 60 minutes on a CPU. Press Ctrl+C at any time to stop; the report is still written with
122
+ everything found so far.
123
+
124
+ **Good objectives** are questions you'd research by reading pages: a fact, a list with conditions ("three free,
125
+ open-source alternatives to Photoshop"), a comparison, a how-to, an explanation, or what several sources say.
126
+ **Not yet:** anything behind a login, a form or a button (it reads pages; it doesn't click or type into them).
127
+
128
+ ## What a run looks like
129
+
130
+ A real run (1.40, with the timing lines the [test runner](#testing) adds; repetitive lines left out). Objective:
131
+ *"What is the tallest mountain in Africa, and how tall is it in meters and in feet?"*
132
+
133
+ ```text
134
+ 🧠 [TURN 1/100] Active reasoning cycle executing...
135
+ (model call 38.6s, prompt=676 tok, completion=54 tok)
136
+ 🎬 Chosen Action: [SEARCH] -> Parameter: tallest mountain in Africa
137
+
138
+ 🧠 [TURN 2/100] Active reasoning cycle executing...
139
+ 💡 Agent Thoughts: From the search results, I can see that Mount Kilimanjaro is mentioned as the tallest
140
+ mountain in Africa ... I will navigate to one of these pages to find the exact height in meters and feet.
141
+ 🎬 Chosen Action: [NAVIGATE] -> Parameter: https://en.wikipedia.org/wiki/Mount_Kilimanjaro
142
+
143
+ 🧠 [TURN 3/100] Active reasoning cycle executing...
144
+ 🎬 Chosen Action: [DISCOVER] -> Parameter: Mount Kilimanjaro is the highest mountain in Africa, with an
145
+ elevation of 5,895 m (19,341 ft) above sea level.
146
+
147
+ 🧠 [TURN 4/100] Active reasoning cycle executing...
148
+ ♻️ Cheap retry 1/2: [FINISH] refused. Your only discovery comes from
149
+ https://en.wikipedia.org/wiki/Mount_Kilimanjaro. Consider whether the objective needs more. ...
150
+ Before finishing, split the OBJECTIVE into its separate parts and, in thought_process, write each
151
+ part followed by the discovery that covers it, or 'not covered'. ...
152
+ 💡 Agent Thoughts: The objective has two parts: the name of the tallest mountain in Africa and its height
153
+ in meters and feet. Both are covered by the discovery from Mount Kilimanjaro's Wikipedia page.
154
+ 🎬 Chosen Action: [FINISH] -> Parameter: The tallest mountain in Africa is Mount Kilimanjaro ...
155
+ 🎯 Agent has signaled mission complete. Writing the final result...
156
+ ```
157
+
158
+ Four turns and 11.8 minutes of model time. The report it wrote:
159
+
160
+ > **Final result:** The tallest mountain in Africa is Mount Kilimanjaro [1], and its elevation is 5,895 meters
161
+ > (19,341 feet) above sea level [1].
162
+ >
163
+ > **Discoveries (1)**
164
+ > 1. Turn 3, from https://en.wikipedia.org/wiki/Mount_Kilimanjaro: *Mount Kilimanjaro is the highest mountain
165
+ > in Africa, with an elevation of 5,895 m (19,341 ft) above sea level.*
166
+
167
+ ## How it works
168
+
169
+ Each turn, the model sees the objective, what it has found so far, its recent actions and the current page, and
170
+ answers with one JSON action:
171
+
172
+ | Action | What it does |
173
+ |---|---|
174
+ | `SEARCH` | Searches DuckDuckGo and shows the results with their real addresses |
175
+ | `NAVIGATE` | Opens an address from the results or the current page's links |
176
+ | `READ_MORE` | Shows the next part of a long page, or the part whose outline names what's still missing |
177
+ | `DISCOVER` | Records something from the current page as a finding |
178
+ | `FINISH` | Ends the run, after each part of the objective is checked; the answer is then written in a separate step |
179
+
180
+ ```mermaid
181
+ flowchart LR
182
+ O[Objective] --> P[Build prompt]
183
+ P --> M[Local model<br/>LM Studio]
184
+ M -->|JSON action| C{Checks in code}
185
+ C -->|refused: cheap retry| M
186
+ C -->|accepted| B[Playwright<br/>Chromium]
187
+ B -->|page text, links| P
188
+ C -->|FINISH| R[Report]
189
+ ```
190
+
191
+ The model proposes; code checks before anything is accepted:
192
+ - **A fixed checklist** of the objective's parts, made once at the start, that every later check uses.
193
+ - **Findings must come from the page:** they're compared with the page text shown, and commands must appear on the
194
+ page exactly.
195
+ - **Finishing is checked part by part,** and the agent is sent back only for gaps the code can confirm: a part
196
+ nothing answers, fewer things than asked for, missing amounts, a concrete missing term such as "O2".
197
+ - **The answer is written separately,** from the findings only. Names, numbers and commands no finding gives are cut
198
+ and named, and parts nothing answers are listed as "Not found in the pages read".
199
+ - **Built for a CPU:** it reuses LM Studio's prompt cache, so most turns only process what changed.
200
+
201
+ The full details, code layout, timings and known limits:
202
+ [docs/how-it-works.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/how-it-works.md).
203
+
204
+ ## Settings
205
+
206
+ | Environment variable | Default | Meaning |
207
+ |---|---|---|
208
+ | `LMSTUDIO_BASE_URL` | `http://localhost:1234/v1` | Address of the OpenAI-compatible server |
209
+ | `LMSTUDIO_MODEL` | `qwen2.5-7b-instruct` | Model identifier as the server lists it |
210
+ | `LMSTUDIO_API_KEY` | `lm-studio` | API key, if your server requires one |
211
+ | `LMSTUDIO_CONTEXT_LENGTH` | `8192` | Context length the model is loaded with; the conversation budget follows it |
212
+
213
+ Behaviour limits are named constants in `localagentbrowser/config.py`, each with a comment.
214
+
215
+ ## FAQ
216
+
217
+ **Does it need a GPU?** No. It was developed entirely on a CPU; a GPU just makes each turn faster.
218
+
219
+ **Why does a turn take minutes?** On a CPU the model reads the prompt slowly (about 8 tokens a second on the
220
+ development PC), so a turn that brings in a new page takes a few minutes. Most other turns reuse LM Studio's cache.
221
+
222
+ **Is anything sent to the internet?** No AI service is involved, and nothing about your run is uploaded. The agent
223
+ does browse the real web: searches, written from your objective, go to DuckDuckGo, and pages load normally.
224
+
225
+ **Can I use another OpenAI-compatible server?** Probably: point `LMSTUDIO_BASE_URL` at it. The speed tricks rely
226
+ on the server reusing cached prompt prefixes (llama.cpp-based servers do).
227
+
228
+ **Where are the results?** `research_report.md` (the answer and every finding with its source) and
229
+ `research_log.txt` (every action and reason), in the run's folder.
230
+
231
+ ## Limitations
232
+
233
+ - **Judging whether a finding really answers a part is the weakest area.** The model can credit a finding about the
234
+ right topic to the wrong part (a "create" command for "activate"), or put the wrong number on a citation. Check
235
+ claims against the listed findings.
236
+ - **Reading only:** it doesn't click, fill in forms or sign in, and some sites refuse automated browsers.
237
+ - **Web pages go into the prompt,** so a page could try to manipulate the model (prompt injection); treat findings as
238
+ unverified. See [SECURITY.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/SECURITY.md).
239
+ - **Seven kinds of task so far.** Others may expose new problems; reports are welcome.
240
+
241
+ More in [docs/how-it-works.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/how-it-works.md#limitations).
242
+
243
+ ## Roadmap
244
+
245
+ - [x] A fixed checklist, a coverage check verified in code, and every change measured on a regression suite (1.53–1.61)
246
+ - [x] Exact-text command checks, and four models measured on identical code (1.63)
247
+ - [x] Parts of the objective no longer dropped silently as often; the Windows launcher (1.64)
248
+ - [ ] A Windows installer with its own Python and a choice of tested models (next release)
249
+ - [ ] Count silent omissions in the regression suite, so [issue #11](https://github.com/SnowFXXX/LocalAgentBrowser/issues/11) can close on a number
250
+ - [ ] Decide in code, not by asking the model, whether a finding answers the part it's credited to
251
+ - [ ] A tray app on Windows: new research, progress, a notification when done
252
+ - [ ] Rewind dead ends: return to a saved point instead of carrying an unused page in every later prompt
253
+ - [ ] Interacting with pages (clicking, forms) for tasks beyond reading
254
+
255
+ Ideas and requests are welcome in [issues](https://github.com/SnowFXXX/LocalAgentBrowser/issues).
256
+
257
+ ## Testing
258
+
259
+ The test suite runs in a few seconds with no model or browser: both are replaced by scripted fakes.
260
+
261
+ ```bash
262
+ pip install -r requirements-dev.txt
263
+ python -m pytest
264
+ python -m ruff check .
265
+ ```
266
+
267
+ To try the real agent with a fixed objective and a time limit, logging every model call:
268
+
269
+ ```bash
270
+ python tools/live_test.py "Your objective here" --minutes 25
271
+ ```
272
+
273
+ To measure a change on all seven kinds of task (several hours on a CPU), on any model LM Studio has:
274
+
275
+ ```bash
276
+ python tools/regression.py --model qwen2.5-7b-instruct --baseline regression_runs/<earlier run>/summary.json
277
+ ```
278
+
279
+ Each run gets a folder in `regression_runs/` with every task's report, journal and prompt trace, a `summary.md`
280
+ with honesty measures for each result, and `run_info.json` naming the PC and the exact code it ran. Results by kind
281
+ of task are in [docs/task-results.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/task-results.md),
282
+ and every step since 1.53 in
283
+ [docs/regression-history.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/docs/regression-history.md).
284
+
285
+ ## Contributing
286
+
287
+ Contributions are welcome! See [CONTRIBUTING.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CONTRIBUTING.md)
288
+ and the [Code of Conduct](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CODE_OF_CONDUCT.md). Security issues:
289
+ [SECURITY.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/SECURITY.md).
290
+
291
+ ## Project history
292
+
293
+ Every released version is a tagged commit, and
294
+ [CHANGELOG.md](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/CHANGELOG.md) says what changed and why, with
295
+ the measurements behind each decision.
296
+
297
+ ## Acknowledgements
298
+
299
+ Versions 1.13 onwards were developed together with [Claude](https://www.anthropic.com/claude) (Anthropic), working
300
+ in Claude Code; those commits list Claude as co-author. Built on [LM Studio](https://lmstudio.ai),
301
+ [Playwright](https://playwright.dev/python/) and the [OpenAI Python library](https://github.com/openai/openai-python).
302
+
303
+ ## License
304
+
305
+ [MIT](https://github.com/SnowFXXX/LocalAgentBrowser/blob/main/LICENSE) © 2026 SnowFX