agentnova 0.2.6__tar.gz → 0.3.1__tar.gz

agentnova-0.3.1/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: agentnova
+Version: 0.3.1
+Summary: ⚛️ AgentNova - A minimal, hackable agentic framework for local LLM inference
+Author-email: VTSTech <veritas@vts-tech.org>
+Maintainer-email: VTSTech <veritas@vts-tech.org>
+License: MIT
+Project-URL: Homepage, https://www.vts-tech.org
+Project-URL: Documentation, https://github.com/VTSTech/AgentNova#readme
+Project-URL: Repository, https://github.com/VTSTech/AgentNova
+Project-URL: Issues, https://github.com/VTSTech/AgentNova/issues
+Keywords: llm,agent,ollama,bitnet,local-inference,tool-calling,react,autonomous,agentic,ai-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# ⚛️ AgentNova R03.1
+
+**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)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VTSTech/AgentNova/blob/main/AgentNova.ipynb)
+[![GitHub commits](https://badgen.net/github/commits/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/) [![GitHub latest commit](https://badgen.net/github/last-commit/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/)
+
+[![pip - agentnova](https://img.shields.io/badge/pip-agentnova-2ea44f?logo=PyPi)](https://pypi.org/project/agentnova/) [![PyPI version fury.io](https://badge.fury.io/py/agentnova.svg)](https://pypi.org/project/agentnova/) [![PyPI download month](https://img.shields.io/pypi/dm/agentnova.svg)](https://pypi.org/project/agentnova/) [![PyPI download day](https://img.shields.io/pypi/dd/agentnova.svg)](https://pypi.org/project/agentnova/)
+
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license) [![Go to Python website](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FVTSTech%2FAgentNova%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=project.requires-python&label=python&logo=python&logoColor=white)](https://python.org)
+
+<img width="801" height="603" alt="image" src="https://github.com/user-attachments/assets/457acc38-231f-4d75-aec6-fa4897fbbb88" />
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.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 |
+
+## Features
+
+- **Zero dependencies** — Uses Python stdlib only (urllib for HTTP)
+- **Ollama + BitNet backends** — Switch with `--backend` flag
+- **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
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/VTSTech/AgentNova.git
+cd AgentNova
+pip install -e .
+
+# Or from PyPI (when published)
+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
+
+# 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")
+```
+
+### 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 `<think/>` 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
+```
+
+## 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 suite of tests for validating agent capabilities:
+
+```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)
+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
+```
+
+### Test Categories
+
+| Test | Questions | Focus |
+|------|-----------|-------|
+| Quick Diagnostic | 5 | Calculator tool, multi-step reasoning |
+| Tool Test | 10 | Calculator, shell, datetime tools |
+| Reasoning Test | 13 | Logic, deduction, patterns, spatial |
+| GSM8K Benchmark | 50 | Math word problems |
+
+### 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 | react |
+| qwen3:0.6b | 5/5 (100%) | 70s | react |
+
+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! Please read the contributing guidelines first.
+
+## Acknowledgments
+
+- Built for local inference with [Ollama](https://ollama.ai)
+- Optimized for small, efficient models
+- Inspired by ReAct and other agentic frameworks

agentnova-0.3.1/README.md

@@ -0,0 +1,271 @@
+# ⚛️ AgentNova R03.1
+
+**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)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VTSTech/AgentNova/blob/main/AgentNova.ipynb)
+[![GitHub commits](https://badgen.net/github/commits/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/) [![GitHub latest commit](https://badgen.net/github/last-commit/VTSTech/AgentNova)](https://GitHub.com/VTSTech/AgentNova/commit/)
+
+[![pip - agentnova](https://img.shields.io/badge/pip-agentnova-2ea44f?logo=PyPi)](https://pypi.org/project/agentnova/) [![PyPI version fury.io](https://badge.fury.io/py/agentnova.svg)](https://pypi.org/project/agentnova/) [![PyPI download month](https://img.shields.io/pypi/dm/agentnova.svg)](https://pypi.org/project/agentnova/) [![PyPI download day](https://img.shields.io/pypi/dd/agentnova.svg)](https://pypi.org/project/agentnova/)
+
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license) [![Go to Python website](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FVTSTech%2FAgentNova%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=project.requires-python&label=python&logo=python&logoColor=white)](https://python.org)
+
+<img width="801" height="603" alt="image" src="https://github.com/user-attachments/assets/457acc38-231f-4d75-aec6-fa4897fbbb88" />
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture.md](https://github.com/VTSTech/AgentNova/blob/main/Architecture.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 |
+
+## Features
+
+- **Zero dependencies** — Uses Python stdlib only (urllib for HTTP)
+- **Ollama + BitNet backends** — Switch with `--backend` flag
+- **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
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/VTSTech/AgentNova.git
+cd AgentNova
+pip install -e .
+
+# Or from PyPI (when published)
+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
+
+# 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")
+```
+
+### 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 `<think/>` 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
+```
+
+## 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 suite of tests for validating agent capabilities:
+
+```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)
+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
+```
+
+### Test Categories
+
+| Test | Questions | Focus |
+|------|-----------|-------|
+| Quick Diagnostic | 5 | Calculator tool, multi-step reasoning |
+| Tool Test | 10 | Calculator, shell, datetime tools |
+| Reasoning Test | 13 | Logic, deduction, patterns, spatial |
+| GSM8K Benchmark | 50 | Math word problems |
+
+### 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 | react |
+| qwen3:0.6b | 5/5 (100%) | 70s | react |
+
+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! Please read the contributing guidelines first.
+
+## Acknowledgments
+
+- Built for local inference with [Ollama](https://ollama.ai)
+- Optimized for small, efficient models
+- Inspired by ReAct and other agentic frameworks