localagentbrowser 1.63__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 (46) hide show
  1. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/CHANGELOG.md +66 -1
  2. localagentbrowser-1.64.1/PKG-INFO +337 -0
  3. localagentbrowser-1.64.1/README.md +305 -0
  4. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/agent.py +9 -3
  5. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/checks.py +17 -2
  6. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/config.py +4 -0
  7. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/coverage.py +106 -7
  8. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/grounding.py +36 -4
  9. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/pages.py +92 -1
  10. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/prompts.py +17 -5
  11. localagentbrowser-1.64.1/localagentbrowser/report.py +835 -0
  12. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/text.py +9 -0
  13. localagentbrowser-1.64.1/localagentbrowser.egg-info/PKG-INFO +337 -0
  14. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/SOURCES.txt +3 -1
  15. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/pyproject.toml +1 -1
  16. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/golden/prompts.json +26 -16
  17. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_checklist.py +429 -3
  18. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_decisions.py +26 -0
  19. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_golden_prompts.py +1 -0
  20. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_main_loop.py +5 -3
  21. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_model_turns.py +2 -2
  22. localagentbrowser-1.64.1/tests/test_page_text.py +165 -0
  23. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_regression.py +22 -0
  24. localagentbrowser-1.64.1/tests/test_show_report.py +30 -0
  25. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tools/regression.py +58 -14
  26. localagentbrowser-1.64.1/tools/windows/show_report.py +155 -0
  27. localagentbrowser-1.63/PKG-INFO +0 -565
  28. localagentbrowser-1.63/README.md +0 -533
  29. localagentbrowser-1.63/localagentbrowser/report.py +0 -316
  30. localagentbrowser-1.63/localagentbrowser.egg-info/PKG-INFO +0 -565
  31. localagentbrowser-1.63/tests/test_page_text.py +0 -89
  32. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/LICENSE +0 -0
  33. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/MANIFEST.in +0 -0
  34. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/agent_browser.py +0 -0
  35. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/__init__.py +0 -0
  36. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser/checklist.py +0 -0
  37. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/dependency_links.txt +0 -0
  38. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/entry_points.txt +0 -0
  39. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/requires.txt +0 -0
  40. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/localagentbrowser.egg-info/top_level.txt +0 -0
  41. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/setup.cfg +0 -0
  42. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/conftest.py +0 -0
  43. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/fakes.py +0 -0
  44. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_duplicates.py +0 -0
  45. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tests/test_journal.py +0 -0
  46. {localagentbrowser-1.63 → localagentbrowser-1.64.1}/tools/live_test.py +0 -0
@@ -1,11 +1,76 @@
1
1
  # Changelog
2
2
 
3
- Every version of LocalAgentBrowser, newest first. Each released version is also a tagged commit (`v1.11` … `v1.62`); 1.54 to 1.56 and 1.58 to 1.60 were internal steps
3
+ Every version of LocalAgentBrowser, newest first. Each released version is also a tagged commit (`v1.11` … `v1.63`); 1.54 to 1.56 and 1.58 to 1.60 were internal steps
4
4
  measured on the regression suite and released as part of 1.57 and 1.61 (see
5
5
  [docs/regression-history.md](docs/regression-history.md)).
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
+
18
+ ## [1.64] - 2026-11-08
19
+ The theme is **silent omission** ([issue #11](https://github.com/SnowFXXX/LocalAgentBrowser/issues/11)): a part of
20
+ the objective dropping out of the final answer without being marked "not found". It was measured on two PCs (PC A
21
+ and PC B, both Intel i5-9500, no GPU) and then on four models with identical code.
22
+
23
+ ### Added
24
+ - **Windows launcher and shortcuts.** `tools/windows/LocalAgentBrowser.cmd` checks that LM Studio is answering,
25
+ runs the agent in its own folder under `Documents\LocalAgentBrowser runs`, and opens the report when the run ends.
26
+ `tools/windows/make_shortcuts.ps1` adds Start-menu and desktop shortcuts with the project icon (from a clone of
27
+ the repository).
28
+ - **The report opens by itself** when a launcher run ends: `research_report.md` is written next to it as a dark web
29
+ page, in the project site's colors, with the final result, checklist and discoveries in separate cards and
30
+ citations shown as tags (`tools/windows/show_report.py`, standard library only). Windows has no program for `.md`
31
+ files by default.
32
+ - Regression suite: every run folder gets `run_info.json` (PC label from `LAB_PC_LABEL`, commit, and a fingerprint
33
+ of the uncommitted changes), so runs on several PCs can be tied to the exact code they ran.
34
+ - Regression suite: `LAB_BLOCKED_SITES` makes NAVIGATE refuse given sites, for benchmark runs that must not read the
35
+ benchmark's own answer pages.
36
+
37
+ ### Fixed: parts of the objective dropping out of the answer
38
+ - **The coverage check asks for the quote first.** "Does this discovery answer the item?" is now answered by first
39
+ copying the words that answer it, with a rule that words on the same topic but a different aspect don't count.
40
+ On 30 hand-labelled real cases, 25 right instead of 16 (no false "not found", 5 false "found" left).
41
+ - **A part credited to several items only counts where the item's own words appear**, so one quote can't silently
42
+ cover three parts; such an item is sent back as unanswered.
43
+ - **Missing amounts and concrete missing terms send the agent back.** When an item asks for amounts and no discovery
44
+ for it gives one, or the check names a concrete missing term ("O2") that no discovery contains, the agent is told
45
+ to find it, instead of finishing without it (an explanation once finished in 4 turns without oxygen).
46
+ - **Each fact stays under its own part.** A discovery keeps the page heading it came from, including headings inside
47
+ a discovery that crosses page sections; a heading the discovery starts with isn't replaced by the one above;
48
+ bylines, very long "headings" (numbered sentences) and the prompt's own section names don't count as headings or
49
+ names.
50
+ - **Names no discovery gives are cut,** with a note: a short cited heading's name is checked too, word forms need
51
+ an 80% shared start ("PhotoScape" over a PhotoSplice source), and words in a source's web address count as given.
52
+ - **A sentence under one label copied from another subject's sentence is cut** (SQLite's sentence under
53
+ PostgreSQL).
54
+ - **Numbers in words are checked like digits** ("two weeks" needs a 2 in a source, "one cup" equals "1 cup"), unit
55
+ abbreviations count as their words ("5,895 m (19,341 ft)" answers "in meters" and "in feet"), and a time needs
56
+ the same number as a time in a source ("2 weeks" was taken from a "2L jar").
57
+ - **Citations:** citation lines on their own are joined to the line they cite; citations are moved out of code, and
58
+ unclosed code blocks closed, so correct commands aren't cut as invented.
59
+ - A **"Recommendation" section is labelled as the model's view**, like "My view:".
60
+ - **NAVIGATE refuses text that isn't a web address** (a run lost 5 turns on it).
61
+
62
+ ### Fixed: the regression suite's scoring
63
+ - The code's own "Left out, because…" notes are no longer read as the result's claims (commands and uncited lines).
64
+ 4 of 78 earlier run folders were over-counted.
65
+ - A bold label ("**1. Creating a virtual environment:**") is a heading, not an uncited claim.
66
+
67
+ ### Measured
68
+ - 7B on two PCs: 7 of 7 on both PCs with v11 (297.8 and 269.6 model minutes), with no outside knowledge, invented
69
+ numbers or invented commands in any finished result.
70
+ - Four models, same code (v12, 90 minutes per task): Qwen2.5-7B 6 of 7, Llama 3.1 8B 7 of 7, Qwen2.5-14B 5 of 7,
71
+ Qwen2.5-3B 3 of 7. On 1.63 they were 6, 2, 2 and 0 of 7. No finished result used outside knowledge. Details in
72
+ docs/regression-history.md.
73
+
9
74
  ## [1.63] - 2026-11-01
10
75
  ### Added
11
76
  - A model call the server fails is tried again after a wait (5, 15, 30, 60 and 120 seconds, about 4 minutes in all),
@@ -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