https://github.com/vtstech/agentnova
⚛️ AgentNova - Inspired by OpenClaw - Aims to do similar things using local models only. Supports BitNet and Ollama Inference
https://github.com/vtstech/agentnova
agentnova agents ai bitnet-llm llm localclaw ollama openclaw
Last synced: 3 months ago
JSON representation
⚛️ AgentNova - Inspired by OpenClaw - Aims to do similar things using local models only. Supports BitNet and Ollama Inference
- Host: GitHub
- URL: https://github.com/vtstech/agentnova
- Owner: VTSTech
- License: mit
- Created: 2026-03-20T19:08:16.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-28T07:14:11.000Z (3 months ago)
- Last Synced: 2026-03-28T11:34:48.864Z (3 months ago)
- Topics: agentnova, agents, ai, bitnet-llm, llm, localclaw, ollama, openclaw
- Language: Python
- Homepage: https://www.vts-tech.org/
- Size: 12.2 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Audit: audit/AgentNova_Security_Audit_Report_page_1.png
Awesome Lists containing this project
README
# ⚛️ AgentNova R04.3
**Status: Alpha**
A minimal, hackable agentic framework engineered to run **entirely locally** with [Ollama](https://ollama.com) or [BitNet](https://github.com/microsoft/BitNet).
Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.
**Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/AgentNova)
[](https://colab.research.google.com/github/VTSTech/AgentNova/blob/main/AgentNova.ipynb)
[](https://GitHub.com/VTSTech/AgentNova/commit/) [](https://GitHub.com/VTSTech/AgentNova/commit/)
[](https://pypi.org/project/agentnova/) [](https://pypi.org/project/agentnova/) [](https://pypi.org/project/agentnova/) [](https://pypi.org/project/agentnova/)
[](#license) [](https://python.org)
## 📚 Documentation
| Document | Description |
|----------|-------------|
| [ARCH.md](https://github.com/VTSTech/AgentNova/blob/main/ARCH.md) | Technical documentation for developers (directory structure, core design, orchestrator modes) |
| [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) | Version history and release notes (includes LocalClaw history) |
| [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) | Benchmark results, model recommendations, and testing guide |
| [CREDITS.md](https://github.com/VTSTech/AgentNova/blob/main/CREDITS.md) | Acknowledges every project, inspiration, API, model creator, and specification that makes AgentNova possible |
## Features
- **Zero dependencies** — Uses Python stdlib only (urllib for HTTP)
- **Ollama + BitNet backends** — Switch with `--backend` flag
- **Dual API support** — OpenResponses (`--api openre`) and OpenAI Chat-Completions (`--api openai`)
- **Three-tier tool support** — Native, ReAct, or none (auto-detected)
- **Small model optimized** — Fuzzy matching, argument normalization
- **Built-in security** — Path validation, command blocklist, SSRF protection
- **Multi-agent orchestration** — Router, pipeline, and parallel modes
- **Soul Spec v0.5** — Persona packages with progressive disclosure
- **ACP v1.0.5 integration** — Agent Control Panel for monitoring and control
- **AgentSkills spec** — Skill loading with SPDX license validation
- **Thinking models support** — Automatic handling of qwen3, deepseek-r1 thinking mode
## Installation
```bash
# Latest Development Release
pip install git+https://github.com/VTSTech/AgentNova.git --force-reinstall
# Last Stable (as stable as Alpha can be) Release
pip install agentnova
```
## Quick Start
### CLI Usage
```bash
# Run a single prompt
agentnova run "What is 15 * 8?" --tools calculator
# Interactive chat
agentnova chat -m qwen2.5:0.5b --tools calculator,shell
# Autonomous agent mode
agentnova agent -m qwen2.5:7b --tools calculator,shell,write_file
# Use OpenAI Chat-Completions API
agentnova chat -m qwen2.5:0.5b --api openai
# List available models
agentnova models
# List available tools
agentnova tools
```
### Python API
```python
from agentnova import Agent
from agentnova.tools import make_builtin_registry
# Create tools
tools = make_builtin_registry().subset(["calculator", "shell"])
# Create agent
agent = Agent(
model="qwen2.5:0.5b",
tools=tools,
backend="ollama",
)
# Run
result = agent.run("What is 15 * 8?")
print(result.final_answer)
print(f"Completed in {result.total_ms:.0f}ms")
```
### Chat-Completions Streaming
```python
from agentnova.backends import get_backend
from agentnova.core.types import ApiMode
# Use Chat-Completions mode with streaming
backend = get_backend("ollama", api_mode=ApiMode.OPENAI)
for chunk in backend.generate_completions_stream(
model="qwen2.5:0.5b",
messages=[{"role": "user", "content": "Hello!"}],
response_format={"type": "json_object"}
):
print(chunk["delta"], end="", flush=True)
```
### Skill License Validation
```python
from agentnova.skills import validate_spdx_license, parse_compatibility
# Validate SPDX license identifier
valid, msg = validate_spdx_license("MIT") # (True, "Valid SPDX identifier: MIT")
valid, msg = validate_spdx_license("Custom") # (False, "Unknown license...")
# Parse compatibility requirements
compat = parse_compatibility("python>=3.8, ollama")
# Returns: {"python": ">=3.8", "runtimes": ["ollama"], "frameworks": []}
```
### Multi-Agent Orchestration
```python
from agentnova import Agent, Orchestrator, AgentCard
orchestrator = Orchestrator(mode="router")
# Register specialized agents
orchestrator.register(AgentCard(
name="math_agent",
description="Handles mathematical calculations",
capabilities=["calculate", "math", "compute"],
tools=["calculator"],
))
orchestrator.register(AgentCard(
name="file_agent",
description="Handles file operations",
capabilities=["read", "write", "file"],
tools=["read_file", "write_file"],
))
# Route tasks to appropriate agent
result = orchestrator.run("Calculate 15 * 8 and save to file")
```
## Tool Support Levels
AgentNova supports three levels of tool use:
1. **Native** — Models with built-in function calling (qwen2.5, llama3.1+, mistral, granite, functiongemma)
2. **ReAct** — Text-based tool use via reasoning prompts (qwen2.5-coder, qwen3)
3. **None** — Pure reasoning without tools
Tool support is auto-detected by running `agentnova models --tool-support`. Results are cached in `~/.cache/agentnova/tool_support.json`.
```bash
# Test and cache tool support for all models
agentnova models --tool-support
# Re-test (ignore cache)
agentnova models --tool-support --no-cache
```
You can also force ReAct mode:
```python
agent = Agent(model="qwen2.5:0.5b", force_react=True)
```
## Model Families
Configured model families with optimized prompts:
- **qwen2.5** — Native tool support, excellent performance
- **llama3.1/3.2/3.3** — Native tool support
- **mistral/mixtral** — Native tool support
- **gemma2/gemma3** — ReAct mode, special prompting
- **granite/granitemoe** — Native tool support
- **phi3** — Native tool support
- **deepseek** — Native with `` tag handling
## Security Features
Built-in security for safe operation:
- **Command blocklist** — Blocks dangerous shell commands (rm, sudo, etc.)
- **Path validation** — Prevents access to sensitive directories
- **SSRF protection** — Blocks requests to local/internal URLs
- **Injection detection** — Detects shell injection patterns
## Configuration
Environment variables:
```bash
# Backend URLs
OLLAMA_BASE_URL=https://your-ollama-server.com # Default: http://localhost:11434
BITNET_BASE_URL=http://localhost:8765 # BitNet server URL
BITNET_TUNNEL=https://your-tunnel.com # Alternative BitNet URL
ACP_BASE_URL=http://localhost:8766 # ACP server URL
# Agent settings
AGENTNOVA_BACKEND=ollama # Default backend: ollama or bitnet
AGENTNOVA_MODEL=qwen2.5:0.5b # Default model
AGENTNOVA_MAX_STEPS=10 # Maximum reasoning steps
AGENTNOVA_DEBUG=false # Enable debug output
```
Check current configuration:
```bash
agentnova config
agentnova config --urls # Show only URLs
```
### CLI Options (run, chat, agent)
| Option | Description |
|--------|-------------|
| `--api openre\|openai` | API mode: OpenResponses (default) or OpenAI Chat-Completions |
| `--response-format text\|json` | Response format (Chat-Completions mode) |
| `--truncation auto\|disabled` | Truncation behavior for long responses |
| `--soul ` | Load Soul Spec persona package |
| `--soul-level 1-3` | Progressive disclosure level |
| `--num-ctx ` | Context window size (default: 4096) |
| `--timeout ` | Request timeout (default: 120) |
| `--acp` | Enable ACP (Agent Control Panel) logging |
| `--acp-url ` | ACP server URL |
## LocalClaw Redirect
The `localclaw` command is provided for backward compatibility:
```bash
# Both work identically
localclaw run "What is 2+2?"
agentnova run "What is 2+2?"
```
## Tests & Examples
AgentNova includes a comprehensive suite of tests for validating agent capabilities across reasoning, knowledge, and tool usage:
```bash
# Basic agent test (no tools)
python -m agentnova.examples.00_basic_agent
# Quick 5-question diagnostic
python -m agentnova.examples.01_quick_diagnostic
# Tool usage tests (calculator, shell, datetime, file, python_repl)
python -m agentnova.examples.02_tool_test
# Logic and reasoning tests (BBH-style)
python -m agentnova.examples.03_reasoning_test
# GSM8K math benchmark (50 questions)
python -m agentnova.examples.04_gsm8k_benchmark
# Common sense reasoning (BIG-bench)
python -m agentnova.examples.05_common_sense
# Causal reasoning (BIG-bench)
python -m agentnova.examples.06_causal_reasoning
# Logical deduction (BIG-bench)
python -m agentnova.examples.07_logical_deduction
# Reading comprehension
python -m agentnova.examples.08_reading_comprehension
# General knowledge (BIG-bench)
python -m agentnova.examples.09_general_knowledge
# Implicit reasoning
python -m agentnova.examples.10_implicit_reasoning
# Analogical reasoning
python -m agentnova.examples.11_analogical_reasoning
```
### Test Categories
| Test | Questions | Focus |
|------|-----------|-------|
| Basic Agent | 1 | Single prompt, no tools |
| Quick Diagnostic | 5 | Calculator tool, multi-step reasoning |
| Tool Test | 10 | Calculator, shell, datetime, file, python_repl tools |
| Reasoning Test | 14 | Logic, deduction, patterns, spatial |
| GSM8K Benchmark | 50 | Math word problems |
| Common Sense | 25 | Physical properties, everyday reasoning |
| Causal Reasoning | 25 | Cause and effect relationships |
| Logical Deduction | 25 | Formal logic puzzles |
| Reading Comprehension | 25 | Passage-based Q&A |
| General Knowledge | 25 | Science, history, geography |
| Implicit Reasoning | 25 | Unstated assumptions and inference |
| Analogical Reasoning | 25 | Pattern matching and analogies |
### Benchmark Results (Quick Diagnostic)
| Model | Score | Time | Tool Support |
|-------|-------|------|-------------|
| functiongemma:270m | 5/5 (100%) | ~20s | native |
| granite4:350m | 5/5 (100%) | ~50s | native |
| qwen2.5:0.5b | 5/5 (100%) | 38s | native |
| qwen2.5-coder:0.5b | 5/5 (100%) | 93s | native |
| qwen3:0.6b | 5/5 (100%) | 70s | react |
| deepseek-r1:1.5b | 5/5 (100%) | ~305s | native |
All tested models achieve 100% on the Quick Diagnostic. Native models are ~2x faster than ReAct models due to direct API tool calling.
## Development
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run unit tests
pytest
# Format code
black agentnova
ruff check agentnova
```
## License
MIT License - See LICENSE file for details.
## Author
**VTSTech** — [https://www.vts-tech.org](https://www.vts-tech.org)
## Contributing
Contributions welcome!