agentnova 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.
Files changed (69) hide show
  1. agentnova-0.0/LICENSE +21 -0
  2. agentnova-0.0/PKG-INFO +351 -0
  3. agentnova-0.0/README.md +315 -0
  4. agentnova-0.0/agentnova/__init__.py +198 -0
  5. agentnova-0.0/agentnova/__main__.py +27 -0
  6. agentnova-0.0/agentnova/acp_plugin.py +2353 -0
  7. agentnova-0.0/agentnova/agent_mode.py +802 -0
  8. agentnova-0.0/agentnova/bitnet_client.py +151 -0
  9. agentnova-0.0/agentnova/bitnet_setup.py +30 -0
  10. agentnova-0.0/agentnova/cli.py +2590 -0
  11. agentnova-0.0/agentnova/config.py +99 -0
  12. agentnova-0.0/agentnova/core/agent.py +1925 -0
  13. agentnova-0.0/agentnova/core/math_prompts.py +396 -0
  14. agentnova-0.0/agentnova/core/memory.py +191 -0
  15. agentnova-0.0/agentnova/core/ollama_client.py +532 -0
  16. agentnova-0.0/agentnova/core/orchestrator.py +191 -0
  17. agentnova-0.0/agentnova/core/orchestrator_enhanced.py +393 -0
  18. agentnova-0.0/agentnova/core/tools.py +275 -0
  19. agentnova-0.0/agentnova/examples/00_backend_demo.py +211 -0
  20. agentnova-0.0/agentnova/examples/01_basic_agent.py +182 -0
  21. agentnova-0.0/agentnova/examples/02_tool_agent.py +276 -0
  22. agentnova-0.0/agentnova/examples/03_orchestrator.py +209 -0
  23. agentnova-0.0/agentnova/examples/04_comprehensive_test.py +258 -0
  24. agentnova-0.0/agentnova/examples/05_tool_tests.py +475 -0
  25. agentnova-0.0/agentnova/examples/06_interactive_chat.py +216 -0
  26. agentnova-0.0/agentnova/examples/07_model_comparison.py +444 -0
  27. agentnova-0.0/agentnova/examples/08_robust_comparison.py +444 -0
  28. agentnova-0.0/agentnova/examples/09_expanded_benchmark.py +367 -0
  29. agentnova-0.0/agentnova/examples/10_skills_demo.py +366 -0
  30. agentnova-0.0/agentnova/examples/11_skill_creator_test.py +525 -0
  31. agentnova-0.0/agentnova/examples/12_batch_operations.py +214 -0
  32. agentnova-0.0/agentnova/examples/13_shutdown_demo.py +191 -0
  33. agentnova-0.0/agentnova/examples/14_gsm8k_benchmark.py +427 -0
  34. agentnova-0.0/agentnova/model_discovery.py +341 -0
  35. agentnova-0.0/agentnova/shared_args.py +146 -0
  36. agentnova-0.0/agentnova/skills/__init__.py +24 -0
  37. agentnova-0.0/agentnova/skills/acp/SKILL.md +328 -0
  38. agentnova-0.0/agentnova/skills/datetime/SKILL.md +25 -0
  39. agentnova-0.0/agentnova/skills/loader.py +445 -0
  40. agentnova-0.0/agentnova/skills/skill-creator/SKILL.md +111 -0
  41. agentnova-0.0/agentnova/skills/skill-creator/scripts/__init__.py +0 -0
  42. agentnova-0.0/agentnova/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
  43. agentnova-0.0/agentnova/skills/skill-creator/scripts/generate_report.py +326 -0
  44. agentnova-0.0/agentnova/skills/skill-creator/scripts/improve_description.py +247 -0
  45. agentnova-0.0/agentnova/skills/skill-creator/scripts/init_skill.py +378 -0
  46. agentnova-0.0/agentnova/skills/skill-creator/scripts/package_skill.py +139 -0
  47. agentnova-0.0/agentnova/skills/skill-creator/scripts/quick_validate.py +159 -0
  48. agentnova-0.0/agentnova/skills/skill-creator/scripts/run_eval.py +310 -0
  49. agentnova-0.0/agentnova/skills/skill-creator/scripts/run_loop.py +328 -0
  50. agentnova-0.0/agentnova/skills/skill-creator/scripts/security_scan.py +144 -0
  51. agentnova-0.0/agentnova/skills/skill-creator/scripts/test_package_skill.py +160 -0
  52. agentnova-0.0/agentnova/skills/skill-creator/scripts/test_quick_validate.py +72 -0
  53. agentnova-0.0/agentnova/skills/skill-creator/scripts/utils.py +47 -0
  54. agentnova-0.0/agentnova/skills/skill-creator/scripts/validate.py +147 -0
  55. agentnova-0.0/agentnova/skills/web_search/SKILL.md +138 -0
  56. agentnova-0.0/agentnova/tools/builtins.py +667 -0
  57. agentnova-0.0/agentnova.egg-info/PKG-INFO +351 -0
  58. agentnova-0.0/agentnova.egg-info/SOURCES.txt +67 -0
  59. agentnova-0.0/agentnova.egg-info/dependency_links.txt +1 -0
  60. agentnova-0.0/agentnova.egg-info/entry_points.txt +6 -0
  61. agentnova-0.0/agentnova.egg-info/requires.txt +5 -0
  62. agentnova-0.0/agentnova.egg-info/top_level.txt +2 -0
  63. agentnova-0.0/localclaw/__init__.py +115 -0
  64. agentnova-0.0/localclaw/__main__.py +23 -0
  65. agentnova-0.0/pyproject.toml +87 -0
  66. agentnova-0.0/setup.cfg +4 -0
  67. agentnova-0.0/tests/test_acp_integration.py +217 -0
  68. agentnova-0.0/tests/test_acp_subagents.py +310 -0
  69. agentnova-0.0/tests/test_agent.py +266 -0
agentnova-0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nigel Todman
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.
agentnova-0.0/PKG-INFO ADDED
@@ -0,0 +1,351 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentnova
3
+ Version: 0.0
4
+ Summary: A minimal, hackable agentic framework for Ollama and BitNet - local-first AI agent toolkit
5
+ Author-email: VTSTech <veritas@vts-tech.org>
6
+ Maintainer-email: VTSTech <veritas@vts-tech.org>
7
+ License: MIT
8
+ Project-URL: Homepage, https://www.vts-tech.org
9
+ Project-URL: Documentation, https://github.com/VTSTech/AgentNova#readme
10
+ Project-URL: Repository, https://github.com/VTSTech/AgentNova
11
+ Project-URL: Issues, https://github.com/VTSTech/AgentNova/issues
12
+ Project-URL: Changelog, https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md
13
+ Keywords: ai,agent,llm,ollama,bitnet,local-ai,agentic,agent-mode,tool-use,function-calling,cli
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
26
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
27
+ Classifier: Topic :: Terminals
28
+ Requires-Python: >=3.9
29
+ Description-Content-Type: text/markdown
30
+ License-File: LICENSE
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0; extra == "dev"
33
+ Requires-Dist: black>=23.0; extra == "dev"
34
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
35
+ Dynamic: license-file
36
+
37
+ # ⚛️ AgentNova R00
38
+
39
+ A minimal, hackable agentic framework engineered to run **entirely locally** with [Ollama](https://ollama.com) or [BitNet](https://github.com/microsoft/BitNet).
40
+
41
+ Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.
42
+
43
+ **Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/AgentNova)
44
+
45
+ [![PyPI version fury.io](https://badge.fury.io/py/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI status](https://img.shields.io/pypi/status/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![GitHub commits](https://badgen.net/github/commits/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/)
46
+
47
+
48
+
49
+ [![PyPI download month](https://img.shields.io/pypi/dm/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI download week](https://img.shields.io/pypi/dw/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI download day](https://img.shields.io/pypi/dd/agentnova.svg)](https://pypi.python.org/pypi/agentnova/)
50
+
51
+
52
+ ---
53
+
54
+ ## 📚 Documentation
55
+
56
+ | Document | Description |
57
+ |----------|-------------|
58
+ | [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.md) | Technical documentation for developers (directory structure, core design, orchestrator modes) |
59
+ | [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) | Version history and release notes (includes LocalClaw history) |
60
+ | [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) | Benchmark results, model recommendations, and testing guide |
61
+
62
+ ---
63
+
64
+ ## Installation
65
+
66
+ ### From PyPI (Recommended)
67
+
68
+ ```bash
69
+ pip install agentnova
70
+
71
+ # Or install from GitHub for the latest development version:
72
+ pip install git+https://github.com/VTSTech/AgentNova.git
73
+ ```
74
+
75
+ ### Backward Compatibility
76
+
77
+ The package was previously named `localclaw`. For backward compatibility:
78
+
79
+ ```bash
80
+ # Old package name still works (shows deprecation warning)
81
+ pip install localclaw
82
+
83
+ # Old CLI command still works
84
+ localclaw run "What is the capital of Japan?" # Redirects to agentnova
85
+
86
+ # Old imports still work (with deprecation warning)
87
+ import localclaw # Re-exports from agentnova
88
+ ```
89
+
90
+ We recommend updating to the new package name:
91
+
92
+ ```python
93
+ # Old
94
+ import localclaw
95
+ from localclaw import Agent
96
+
97
+ # New
98
+ import agentnova
99
+ from agentnova import Agent
100
+ ```
101
+
102
+ ### From Source
103
+
104
+ ```bash
105
+ git clone https://github.com/VTSTech/AgentNova.git
106
+ cd AgentNova
107
+ pip install -e .
108
+ ```
109
+
110
+ ### No Installation Required
111
+
112
+ AgentNova uses only Python stdlib — no dependencies! You can also just copy the `agentnova` directory into your project:
113
+
114
+ ```bash
115
+ cp -r agentnova /path/to/your/project/
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Quick Start
121
+
122
+ ### 1. Test Model Tool Support (Recommended First Step)
123
+
124
+ ```bash
125
+ # Test all models for native tool support
126
+ agentnova models --tool_support
127
+
128
+ # Results saved to tested_models.json for future reference
129
+ ```
130
+
131
+ ### 2. Single prompt
132
+
133
+ ```bash
134
+ # Simple Q&A
135
+ agentnova run "What is the capital of Japan?"
136
+
137
+ # With streaming output
138
+ agentnova run "Tell me a joke." --stream
139
+
140
+ # Specify a model
141
+ agentnova run "Explain quantum computing" -m llama3.2:3b
142
+ ```
143
+
144
+ ### 3. Interactive chat
145
+
146
+ ```bash
147
+ # Start interactive session
148
+ agentnova chat -m qwen2.5-coder:0.5b
149
+
150
+ # With tools enabled
151
+ agentnova chat -m llama3.1:8b --tools calculator,shell,read_file,write_file
152
+
153
+ # With skills loaded
154
+ agentnova chat -m llama3.2:3b --skills skill-creator --tools write_file,shell
155
+
156
+ # Fast mode (reduced context for speed)
157
+ agentnova chat -m qwen2.5-coder:0.5b --fast --verbose
158
+ ```
159
+
160
+ ### 4. Using BitNet backend
161
+
162
+ ```bash
163
+ agentnova chat --backend bitnet --force-react
164
+ agentnova run "Calculate 17 * 23" --backend bitnet --tools calculator
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Key Features
170
+
171
+ - **Zero dependencies** — uses Python stdlib only
172
+ - **Ollama + BitNet backends** — switch with `--backend` flag
173
+ - **Three-tier tool support** — native, ReAct, or none (auto-detected per model)
174
+ - **Agent Skills** — follows [Agent Skills specification](https://agentskills.io/)
175
+ - **Small model optimized** — pure reasoning mode for sub-500M models
176
+ - **Built-in security** — path validation, command blocklist, SSRF protection
177
+
178
+ ---
179
+
180
+ ## Tool Support Levels
181
+
182
+ AgentNova automatically detects each model's tool support level:
183
+
184
+ | Level | Description | When to Use |
185
+ |-------|-------------|-------------|
186
+ | `native` | Ollama API tool-calling | Models trained for function calling |
187
+ | `react` | Text-based ReAct prompting | Models that accept tools but need format guidance |
188
+ | `none` | No tool support | Models that reject tools; use pure reasoning |
189
+
190
+ ### Testing Tool Support
191
+
192
+ ```bash
193
+ # Test all models
194
+ agentnova models --tool_support
195
+
196
+ # Example output:
197
+ Model Family Context Tool Support
198
+ ──────────────────────────────────────────────────────────────────────────────
199
+ gemma3:270m gemma3 32K ○ none
200
+ granite4:350m granite 32K ✓ native
201
+ qwen2.5-coder:0.5b-instruct-q4_k_m qwen2 32K ReAct
202
+ functiongemma:270m gemma3 32K ✓ native
203
+ ```
204
+
205
+ ### Performance by Tool Support
206
+
207
+ Recent GSM8K benchmark results (50 math questions):
208
+
209
+ | Model | Params | Tool Support | Score |
210
+ |-------|--------|--------------|-------|
211
+ | `gemma3:270m` | 270M | none | **64%** |
212
+ | `functiongemma:270m` | 270M | native | 36% |
213
+ | `granite4:350m` | 350M | native | ~40% |
214
+
215
+ **Key insight**: Sub-500M models often perform better with `none` (pure reasoning) than with tools!
216
+
217
+ ---
218
+
219
+ ## CLI Commands
220
+
221
+ | Command | Description |
222
+ |---------|-------------|
223
+ | `run "prompt"` | Run single prompt and exit |
224
+ | `chat` | Interactive multi-turn conversation |
225
+ | `models` | List available Ollama models with tool support info |
226
+ | `tools` | List built-in tools |
227
+ | `skills` | List available Agent Skills |
228
+ | `test [example]` | Run example/test scripts (`--list` to see all) |
229
+ | `modelfile [model]` | Show model's Modelfile system prompt |
230
+
231
+ ### Key Flags
232
+
233
+ | Flag | Description |
234
+ |------|-------------|
235
+ | `-m`, `--model` | Model name (default: qwen2.5-coder:0.5b) |
236
+ | `--tools` | Comma-separated tool list |
237
+ | `--skills` | Comma-separated skill list |
238
+ | `--backend` | `ollama` or `bitnet` |
239
+ | `--stream` | Stream output token-by-token |
240
+ | `--fast` | Preset: reduced context for speed |
241
+ | `-v`, `--verbose` | Show tool calls and timing |
242
+ | `--acp` | Enable ACP (Agent Control Panel) integration |
243
+ | `--use-mf-sys` | Use Modelfile system prompt instead of AgentNova default |
244
+ | `--force-react` | Force ReAct mode for all models |
245
+ | `--debug` | Show debug info (parsed tool calls, fuzzy matching) |
246
+ | `--num-ctx` | Context window size for test commands |
247
+ | `--num-predict` | Max tokens to predict for test commands |
248
+
249
+ ### Models Command
250
+
251
+ ```bash
252
+ # List models with family, context size, and tool support
253
+ agentnova models
254
+
255
+ # Test each model for native tool support (recommended)
256
+ agentnova models --tool_support
257
+ ```
258
+
259
+ Output shows:
260
+ - **Model** - Model name
261
+ - **Family** - Model family from Ollama API
262
+ - **Context** - Context window size
263
+ - **Tool Support** - `✓ native`, `ReAct`, `○ none`, or `untested`
264
+
265
+ ```
266
+ ⚛️ AgentNova R00 Models
267
+ Model Family Context Tool Support
268
+ ──────────────────────────────────────────────────────────────────────────────
269
+ gemma3:270m gemma3 32K ○ none
270
+ granite4:350m granite 32K ✓ native
271
+ qwen2.5-coder:0.5b-instruct-q4_k_m qwen2 32K ReAct
272
+ functiongemma:270m gemma3 32K untested
273
+
274
+ 1 model(s) untested. Use --tool_support to detect native support.
275
+ ```
276
+
277
+ ### Test Command Examples
278
+
279
+ ```bash
280
+ # List all available tests
281
+ agentnova test --list
282
+
283
+ # Run a quick test suite
284
+ agentnova test quick
285
+
286
+ # Run GSM8K benchmark (50 math questions)
287
+ agentnova test 14 --acp --timeout 6400
288
+
289
+ # Run with debug output
290
+ agentnova test 02 --debug --verbose
291
+ ```
292
+
293
+ ---
294
+
295
+ ## Built-in Tools
296
+
297
+ | Tool | Description |
298
+ |------|-------------|
299
+ | `calculator` | Evaluate math expressions |
300
+ | `python_repl` | Execute Python code |
301
+ | `shell` | Run shell commands |
302
+ | `read_file` | Read file contents |
303
+ | `write_file` | Write content to file |
304
+ | `list_directory` | List directory contents |
305
+ | `http_get` | HTTP GET request |
306
+ | `save_note` / `get_note` | Save and retrieve notes |
307
+
308
+ ---
309
+
310
+ ## Configuration
311
+
312
+ | Variable | Description | Default |
313
+ |----------|-------------|---------|
314
+ | `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` |
315
+ | `BITNET_BASE_URL` | BitNet server URL | `http://localhost:8765` |
316
+ | `ACP_BASE_URL` | ACP (Agent Control Panel) server URL | `http://localhost:8766` |
317
+ | `AGENTNOVA_BACKEND` | Backend: `ollama` or `bitnet` | `ollama` |
318
+ | `AGENTNOVA_MODEL` | Default model | `qwen2.5-coder:0.5b-instruct-q4_k_m` |
319
+ | `AGENTNOVA_SECURITY_MODE` | Security mode: `strict`, `permissive`, `disabled` | `permissive` |
320
+
321
+ ---
322
+
323
+ ## Setup Ollama
324
+
325
+ ```bash
326
+ # Make sure Ollama is running:
327
+ ollama serve
328
+
329
+ # Pull a model:
330
+ ollama pull qwen2.5-coder:0.5b-instruct-q4_k_m
331
+
332
+ # Test tool support:
333
+ agentnova models --tool_support
334
+ ```
335
+
336
+ ---
337
+
338
+ ## About
339
+
340
+ **⚛️ AgentNova ** is written and maintained by **VTSTech**.
341
+
342
+ - 🌐 Website: [https://www.vts-tech.org](https://www.vts-tech.org)
343
+ - 📦 GitHub: [https://github.com/VTSTech/AgentNova](https://github.com/VTSTech/AgentNova)
344
+ - 💻 More projects: [https://github.com/VTSTech](https://github.com/VTSTech)
345
+
346
+ ---
347
+
348
+ For more details, see:
349
+ - [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.md) — Technical architecture and design decisions
350
+ - [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) — Version history and release notes
351
+ - [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) — Benchmark results and model recommendations
@@ -0,0 +1,315 @@
1
+ # ⚛️ AgentNova R00
2
+
3
+ A minimal, hackable agentic framework engineered to run **entirely locally** with [Ollama](https://ollama.com) or [BitNet](https://github.com/microsoft/BitNet).
4
+
5
+ Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.
6
+
7
+ **Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/AgentNova)
8
+
9
+ [![PyPI version fury.io](https://badge.fury.io/py/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI status](https://img.shields.io/pypi/status/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![GitHub commits](https://badgen.net/github/commits/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/)
10
+
11
+
12
+
13
+ [![PyPI download month](https://img.shields.io/pypi/dm/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI download week](https://img.shields.io/pypi/dw/agentnova.svg)](https://pypi.python.org/pypi/agentnova/) [![PyPI download day](https://img.shields.io/pypi/dd/agentnova.svg)](https://pypi.python.org/pypi/agentnova/)
14
+
15
+
16
+ ---
17
+
18
+ ## 📚 Documentation
19
+
20
+ | Document | Description |
21
+ |----------|-------------|
22
+ | [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.md) | Technical documentation for developers (directory structure, core design, orchestrator modes) |
23
+ | [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) | Version history and release notes (includes LocalClaw history) |
24
+ | [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) | Benchmark results, model recommendations, and testing guide |
25
+
26
+ ---
27
+
28
+ ## Installation
29
+
30
+ ### From PyPI (Recommended)
31
+
32
+ ```bash
33
+ pip install agentnova
34
+
35
+ # Or install from GitHub for the latest development version:
36
+ pip install git+https://github.com/VTSTech/AgentNova.git
37
+ ```
38
+
39
+ ### Backward Compatibility
40
+
41
+ The package was previously named `localclaw`. For backward compatibility:
42
+
43
+ ```bash
44
+ # Old package name still works (shows deprecation warning)
45
+ pip install localclaw
46
+
47
+ # Old CLI command still works
48
+ localclaw run "What is the capital of Japan?" # Redirects to agentnova
49
+
50
+ # Old imports still work (with deprecation warning)
51
+ import localclaw # Re-exports from agentnova
52
+ ```
53
+
54
+ We recommend updating to the new package name:
55
+
56
+ ```python
57
+ # Old
58
+ import localclaw
59
+ from localclaw import Agent
60
+
61
+ # New
62
+ import agentnova
63
+ from agentnova import Agent
64
+ ```
65
+
66
+ ### From Source
67
+
68
+ ```bash
69
+ git clone https://github.com/VTSTech/AgentNova.git
70
+ cd AgentNova
71
+ pip install -e .
72
+ ```
73
+
74
+ ### No Installation Required
75
+
76
+ AgentNova uses only Python stdlib — no dependencies! You can also just copy the `agentnova` directory into your project:
77
+
78
+ ```bash
79
+ cp -r agentnova /path/to/your/project/
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Quick Start
85
+
86
+ ### 1. Test Model Tool Support (Recommended First Step)
87
+
88
+ ```bash
89
+ # Test all models for native tool support
90
+ agentnova models --tool_support
91
+
92
+ # Results saved to tested_models.json for future reference
93
+ ```
94
+
95
+ ### 2. Single prompt
96
+
97
+ ```bash
98
+ # Simple Q&A
99
+ agentnova run "What is the capital of Japan?"
100
+
101
+ # With streaming output
102
+ agentnova run "Tell me a joke." --stream
103
+
104
+ # Specify a model
105
+ agentnova run "Explain quantum computing" -m llama3.2:3b
106
+ ```
107
+
108
+ ### 3. Interactive chat
109
+
110
+ ```bash
111
+ # Start interactive session
112
+ agentnova chat -m qwen2.5-coder:0.5b
113
+
114
+ # With tools enabled
115
+ agentnova chat -m llama3.1:8b --tools calculator,shell,read_file,write_file
116
+
117
+ # With skills loaded
118
+ agentnova chat -m llama3.2:3b --skills skill-creator --tools write_file,shell
119
+
120
+ # Fast mode (reduced context for speed)
121
+ agentnova chat -m qwen2.5-coder:0.5b --fast --verbose
122
+ ```
123
+
124
+ ### 4. Using BitNet backend
125
+
126
+ ```bash
127
+ agentnova chat --backend bitnet --force-react
128
+ agentnova run "Calculate 17 * 23" --backend bitnet --tools calculator
129
+ ```
130
+
131
+ ---
132
+
133
+ ## Key Features
134
+
135
+ - **Zero dependencies** — uses Python stdlib only
136
+ - **Ollama + BitNet backends** — switch with `--backend` flag
137
+ - **Three-tier tool support** — native, ReAct, or none (auto-detected per model)
138
+ - **Agent Skills** — follows [Agent Skills specification](https://agentskills.io/)
139
+ - **Small model optimized** — pure reasoning mode for sub-500M models
140
+ - **Built-in security** — path validation, command blocklist, SSRF protection
141
+
142
+ ---
143
+
144
+ ## Tool Support Levels
145
+
146
+ AgentNova automatically detects each model's tool support level:
147
+
148
+ | Level | Description | When to Use |
149
+ |-------|-------------|-------------|
150
+ | `native` | Ollama API tool-calling | Models trained for function calling |
151
+ | `react` | Text-based ReAct prompting | Models that accept tools but need format guidance |
152
+ | `none` | No tool support | Models that reject tools; use pure reasoning |
153
+
154
+ ### Testing Tool Support
155
+
156
+ ```bash
157
+ # Test all models
158
+ agentnova models --tool_support
159
+
160
+ # Example output:
161
+ Model Family Context Tool Support
162
+ ──────────────────────────────────────────────────────────────────────────────
163
+ gemma3:270m gemma3 32K ○ none
164
+ granite4:350m granite 32K ✓ native
165
+ qwen2.5-coder:0.5b-instruct-q4_k_m qwen2 32K ReAct
166
+ functiongemma:270m gemma3 32K ✓ native
167
+ ```
168
+
169
+ ### Performance by Tool Support
170
+
171
+ Recent GSM8K benchmark results (50 math questions):
172
+
173
+ | Model | Params | Tool Support | Score |
174
+ |-------|--------|--------------|-------|
175
+ | `gemma3:270m` | 270M | none | **64%** |
176
+ | `functiongemma:270m` | 270M | native | 36% |
177
+ | `granite4:350m` | 350M | native | ~40% |
178
+
179
+ **Key insight**: Sub-500M models often perform better with `none` (pure reasoning) than with tools!
180
+
181
+ ---
182
+
183
+ ## CLI Commands
184
+
185
+ | Command | Description |
186
+ |---------|-------------|
187
+ | `run "prompt"` | Run single prompt and exit |
188
+ | `chat` | Interactive multi-turn conversation |
189
+ | `models` | List available Ollama models with tool support info |
190
+ | `tools` | List built-in tools |
191
+ | `skills` | List available Agent Skills |
192
+ | `test [example]` | Run example/test scripts (`--list` to see all) |
193
+ | `modelfile [model]` | Show model's Modelfile system prompt |
194
+
195
+ ### Key Flags
196
+
197
+ | Flag | Description |
198
+ |------|-------------|
199
+ | `-m`, `--model` | Model name (default: qwen2.5-coder:0.5b) |
200
+ | `--tools` | Comma-separated tool list |
201
+ | `--skills` | Comma-separated skill list |
202
+ | `--backend` | `ollama` or `bitnet` |
203
+ | `--stream` | Stream output token-by-token |
204
+ | `--fast` | Preset: reduced context for speed |
205
+ | `-v`, `--verbose` | Show tool calls and timing |
206
+ | `--acp` | Enable ACP (Agent Control Panel) integration |
207
+ | `--use-mf-sys` | Use Modelfile system prompt instead of AgentNova default |
208
+ | `--force-react` | Force ReAct mode for all models |
209
+ | `--debug` | Show debug info (parsed tool calls, fuzzy matching) |
210
+ | `--num-ctx` | Context window size for test commands |
211
+ | `--num-predict` | Max tokens to predict for test commands |
212
+
213
+ ### Models Command
214
+
215
+ ```bash
216
+ # List models with family, context size, and tool support
217
+ agentnova models
218
+
219
+ # Test each model for native tool support (recommended)
220
+ agentnova models --tool_support
221
+ ```
222
+
223
+ Output shows:
224
+ - **Model** - Model name
225
+ - **Family** - Model family from Ollama API
226
+ - **Context** - Context window size
227
+ - **Tool Support** - `✓ native`, `ReAct`, `○ none`, or `untested`
228
+
229
+ ```
230
+ ⚛️ AgentNova R00 Models
231
+ Model Family Context Tool Support
232
+ ──────────────────────────────────────────────────────────────────────────────
233
+ gemma3:270m gemma3 32K ○ none
234
+ granite4:350m granite 32K ✓ native
235
+ qwen2.5-coder:0.5b-instruct-q4_k_m qwen2 32K ReAct
236
+ functiongemma:270m gemma3 32K untested
237
+
238
+ 1 model(s) untested. Use --tool_support to detect native support.
239
+ ```
240
+
241
+ ### Test Command Examples
242
+
243
+ ```bash
244
+ # List all available tests
245
+ agentnova test --list
246
+
247
+ # Run a quick test suite
248
+ agentnova test quick
249
+
250
+ # Run GSM8K benchmark (50 math questions)
251
+ agentnova test 14 --acp --timeout 6400
252
+
253
+ # Run with debug output
254
+ agentnova test 02 --debug --verbose
255
+ ```
256
+
257
+ ---
258
+
259
+ ## Built-in Tools
260
+
261
+ | Tool | Description |
262
+ |------|-------------|
263
+ | `calculator` | Evaluate math expressions |
264
+ | `python_repl` | Execute Python code |
265
+ | `shell` | Run shell commands |
266
+ | `read_file` | Read file contents |
267
+ | `write_file` | Write content to file |
268
+ | `list_directory` | List directory contents |
269
+ | `http_get` | HTTP GET request |
270
+ | `save_note` / `get_note` | Save and retrieve notes |
271
+
272
+ ---
273
+
274
+ ## Configuration
275
+
276
+ | Variable | Description | Default |
277
+ |----------|-------------|---------|
278
+ | `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` |
279
+ | `BITNET_BASE_URL` | BitNet server URL | `http://localhost:8765` |
280
+ | `ACP_BASE_URL` | ACP (Agent Control Panel) server URL | `http://localhost:8766` |
281
+ | `AGENTNOVA_BACKEND` | Backend: `ollama` or `bitnet` | `ollama` |
282
+ | `AGENTNOVA_MODEL` | Default model | `qwen2.5-coder:0.5b-instruct-q4_k_m` |
283
+ | `AGENTNOVA_SECURITY_MODE` | Security mode: `strict`, `permissive`, `disabled` | `permissive` |
284
+
285
+ ---
286
+
287
+ ## Setup Ollama
288
+
289
+ ```bash
290
+ # Make sure Ollama is running:
291
+ ollama serve
292
+
293
+ # Pull a model:
294
+ ollama pull qwen2.5-coder:0.5b-instruct-q4_k_m
295
+
296
+ # Test tool support:
297
+ agentnova models --tool_support
298
+ ```
299
+
300
+ ---
301
+
302
+ ## About
303
+
304
+ **⚛️ AgentNova ** is written and maintained by **VTSTech**.
305
+
306
+ - 🌐 Website: [https://www.vts-tech.org](https://www.vts-tech.org)
307
+ - 📦 GitHub: [https://github.com/VTSTech/AgentNova](https://github.com/VTSTech/AgentNova)
308
+ - 💻 More projects: [https://github.com/VTSTech](https://github.com/VTSTech)
309
+
310
+ ---
311
+
312
+ For more details, see:
313
+ - [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.md) — Technical architecture and design decisions
314
+ - [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) — Version history and release notes
315
+ - [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) — Benchmark results and model recommendations