{"id":47595725,"url":"https://github.com/vtstech/agentnova","last_synced_at":"2026-04-01T18:04:08.391Z","repository":{"id":345808356,"uuid":"1187472706","full_name":"VTSTech/AgentNova","owner":"VTSTech","description":"⚛️ AgentNova - Inspired by OpenClaw - Aims to do similar things using local models only. Supports BitNet and Ollama Inference","archived":false,"fork":false,"pushed_at":"2026-03-28T07:14:11.000Z","size":12768,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T11:34:48.864Z","etag":null,"topics":["agentnova","agents","ai","bitnet-llm","llm","localclaw","ollama","openclaw"],"latest_commit_sha":null,"homepage":"https://www.vts-tech.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VTSTech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit/AgentNova_Security_Audit_Report_page_1.png","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T19:08:16.000Z","updated_at":"2026-03-28T07:14:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VTSTech/AgentNova","commit_stats":null,"previous_names":["vtstech/agentnova"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VTSTech/AgentNova","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FAgentNova","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FAgentNova/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FAgentNova/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FAgentNova/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VTSTech","download_url":"https://codeload.github.com/VTSTech/AgentNova/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTSTech%2FAgentNova/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentnova","agents","ai","bitnet-llm","llm","localclaw","ollama","openclaw"],"created_at":"2026-04-01T18:03:56.788Z","updated_at":"2026-04-01T18:04:08.377Z","avatar_url":"https://github.com/VTSTech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚛️ AgentNova R04.3\n\n**Status: Alpha**\n\nA minimal, hackable agentic framework engineered to run **entirely locally** with [Ollama](https://ollama.com) or [BitNet](https://github.com/microsoft/BitNet).\n\nInspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.\n\n**Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/AgentNova)\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VTSTech/AgentNova/blob/main/AgentNova.ipynb)\n[![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/)\n\n[![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/)\n\n[![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\u0026query=project.requires-python\u0026label=python\u0026logo=python\u0026logoColor=white)](https://python.org)\n\n\u003cimg width=\"1432\" height=\"982\" alt=\"image\" src=\"https://github.com/user-attachments/assets/271fe287-7f9a-4120-8aa8-c8cdb0d7ac21\" /\u003e\n\u003cimg width=\"1063\" height=\"574\" alt=\"image\" src=\"https://github.com/user-attachments/assets/eab6f4ad-810c-4741-b637-e120f9ccb974\" /\u003e\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [ARCH.md](https://github.com/VTSTech/AgentNova/blob/main/ARCH.md) | Technical documentation for developers (directory structure, core design, orchestrator modes) |\n| [CHANGELOG.md](https://github.com/VTSTech/AgentNova/blob/main/CHANGELOG.md) | Version history and release notes (includes LocalClaw history) |\n| [TESTS.md](https://github.com/VTSTech/AgentNova/blob/main/TESTS.md) | Benchmark results, model recommendations, and testing guide |\n| [CREDITS.md](https://github.com/VTSTech/AgentNova/blob/main/CREDITS.md) | Acknowledges every project, inspiration, API, model creator, and specification that makes AgentNova possible |\n\n## Features\n\n- **Zero dependencies** — Uses Python stdlib only (urllib for HTTP)\n- **Ollama + BitNet backends** — Switch with `--backend` flag\n- **Dual API support** — OpenResponses (`--api openre`) and OpenAI Chat-Completions (`--api openai`)\n- **Three-tier tool support** — Native, ReAct, or none (auto-detected)\n- **Small model optimized** — Fuzzy matching, argument normalization\n- **Built-in security** — Path validation, command blocklist, SSRF protection\n- **Multi-agent orchestration** — Router, pipeline, and parallel modes\n- **Soul Spec v0.5** — Persona packages with progressive disclosure\n- **ACP v1.0.5 integration** — Agent Control Panel for monitoring and control\n- **AgentSkills spec** — Skill loading with SPDX license validation\n- **Thinking models support** — Automatic handling of qwen3, deepseek-r1 thinking mode\n\n## Installation\n\n```bash\n# Latest Development Release\npip install git+https://github.com/VTSTech/AgentNova.git --force-reinstall\n\n# Last Stable (as stable as Alpha can be) Release\npip install agentnova\n```\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Run a single prompt\nagentnova run \"What is 15 * 8?\" --tools calculator\n\n# Interactive chat\nagentnova chat -m qwen2.5:0.5b --tools calculator,shell\n\n# Autonomous agent mode\nagentnova agent -m qwen2.5:7b --tools calculator,shell,write_file\n\n# Use OpenAI Chat-Completions API\nagentnova chat -m qwen2.5:0.5b --api openai\n\n# List available models\nagentnova models\n\n# List available tools\nagentnova tools\n```\n\n### Python API\n\n```python\nfrom agentnova import Agent\nfrom agentnova.tools import make_builtin_registry\n\n# Create tools\ntools = make_builtin_registry().subset([\"calculator\", \"shell\"])\n\n# Create agent\nagent = Agent(\n    model=\"qwen2.5:0.5b\",\n    tools=tools,\n    backend=\"ollama\",\n)\n\n# Run\nresult = agent.run(\"What is 15 * 8?\")\nprint(result.final_answer)\nprint(f\"Completed in {result.total_ms:.0f}ms\")\n```\n\n### Chat-Completions Streaming\n\n```python\nfrom agentnova.backends import get_backend\nfrom agentnova.core.types import ApiMode\n\n# Use Chat-Completions mode with streaming\nbackend = get_backend(\"ollama\", api_mode=ApiMode.OPENAI)\n\nfor chunk in backend.generate_completions_stream(\n    model=\"qwen2.5:0.5b\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n    response_format={\"type\": \"json_object\"}\n):\n    print(chunk[\"delta\"], end=\"\", flush=True)\n```\n\n### Skill License Validation\n\n```python\nfrom agentnova.skills import validate_spdx_license, parse_compatibility\n\n# Validate SPDX license identifier\nvalid, msg = validate_spdx_license(\"MIT\")  # (True, \"Valid SPDX identifier: MIT\")\nvalid, msg = validate_spdx_license(\"Custom\")  # (False, \"Unknown license...\")\n\n# Parse compatibility requirements\ncompat = parse_compatibility(\"python\u003e=3.8, ollama\")\n# Returns: {\"python\": \"\u003e=3.8\", \"runtimes\": [\"ollama\"], \"frameworks\": []}\n```\n\n### Multi-Agent Orchestration\n\n```python\nfrom agentnova import Agent, Orchestrator, AgentCard\n\norchestrator = Orchestrator(mode=\"router\")\n\n# Register specialized agents\norchestrator.register(AgentCard(\n    name=\"math_agent\",\n    description=\"Handles mathematical calculations\",\n    capabilities=[\"calculate\", \"math\", \"compute\"],\n    tools=[\"calculator\"],\n))\n\norchestrator.register(AgentCard(\n    name=\"file_agent\",\n    description=\"Handles file operations\",\n    capabilities=[\"read\", \"write\", \"file\"],\n    tools=[\"read_file\", \"write_file\"],\n))\n\n# Route tasks to appropriate agent\nresult = orchestrator.run(\"Calculate 15 * 8 and save to file\")\n```\n\n## Tool Support Levels\n\nAgentNova supports three levels of tool use:\n\n1. **Native** — Models with built-in function calling (qwen2.5, llama3.1+, mistral, granite, functiongemma)\n2. **ReAct** — Text-based tool use via reasoning prompts (qwen2.5-coder, qwen3)\n3. **None** — Pure reasoning without tools\n\nTool support is auto-detected by running `agentnova models --tool-support`. Results are cached in `~/.cache/agentnova/tool_support.json`.\n\n```bash\n# Test and cache tool support for all models\nagentnova models --tool-support\n\n# Re-test (ignore cache)\nagentnova models --tool-support --no-cache\n```\n\nYou can also force ReAct mode:\n\n```python\nagent = Agent(model=\"qwen2.5:0.5b\", force_react=True)\n```\n\n## Model Families\n\nConfigured model families with optimized prompts:\n\n- **qwen2.5** — Native tool support, excellent performance\n- **llama3.1/3.2/3.3** — Native tool support\n- **mistral/mixtral** — Native tool support\n- **gemma2/gemma3** — ReAct mode, special prompting\n- **granite/granitemoe** — Native tool support\n- **phi3** — Native tool support\n- **deepseek** — Native with `\u003cthink/\u003e` tag handling\n\n## Security Features\n\nBuilt-in security for safe operation:\n\n- **Command blocklist** — Blocks dangerous shell commands (rm, sudo, etc.)\n- **Path validation** — Prevents access to sensitive directories\n- **SSRF protection** — Blocks requests to local/internal URLs\n- **Injection detection** — Detects shell injection patterns\n\n## Configuration\n\nEnvironment variables:\n\n```bash\n# Backend URLs\nOLLAMA_BASE_URL=https://your-ollama-server.com    # Default: http://localhost:11434\nBITNET_BASE_URL=http://localhost:8765              # BitNet server URL\nBITNET_TUNNEL=https://your-tunnel.com              # Alternative BitNet URL\nACP_BASE_URL=http://localhost:8766                 # ACP server URL\n\n# Agent settings\nAGENTNOVA_BACKEND=ollama      # Default backend: ollama or bitnet\nAGENTNOVA_MODEL=qwen2.5:0.5b  # Default model\nAGENTNOVA_MAX_STEPS=10        # Maximum reasoning steps\nAGENTNOVA_DEBUG=false         # Enable debug output\n```\n\nCheck current configuration:\n```bash\nagentnova config\nagentnova config --urls  # Show only URLs\n```\n\n### CLI Options (run, chat, agent)\n\n| Option | Description |\n|--------|-------------|\n| `--api openre\\|openai` | API mode: OpenResponses (default) or OpenAI Chat-Completions |\n| `--response-format text\\|json` | Response format (Chat-Completions mode) |\n| `--truncation auto\\|disabled` | Truncation behavior for long responses |\n| `--soul \u003cpath\u003e` | Load Soul Spec persona package |\n| `--soul-level 1-3` | Progressive disclosure level |\n| `--num-ctx \u003ctokens\u003e` | Context window size (default: 4096) |\n| `--timeout \u003cseconds\u003e` | Request timeout (default: 120) |\n| `--acp` | Enable ACP (Agent Control Panel) logging |\n| `--acp-url \u003curl\u003e` | ACP server URL |\n\n## LocalClaw Redirect\n\nThe `localclaw` command is provided for backward compatibility:\n\n```bash\n# Both work identically\nlocalclaw run \"What is 2+2?\"\nagentnova run \"What is 2+2?\"\n```\n\n## Tests \u0026 Examples\n\nAgentNova includes a comprehensive suite of tests for validating agent capabilities across reasoning, knowledge, and tool usage:\n\n```bash\n# Basic agent test (no tools)\npython -m agentnova.examples.00_basic_agent\n\n# Quick 5-question diagnostic\npython -m agentnova.examples.01_quick_diagnostic\n\n# Tool usage tests (calculator, shell, datetime, file, python_repl)\npython -m agentnova.examples.02_tool_test\n\n# Logic and reasoning tests (BBH-style)\npython -m agentnova.examples.03_reasoning_test\n\n# GSM8K math benchmark (50 questions)\npython -m agentnova.examples.04_gsm8k_benchmark\n\n# Common sense reasoning (BIG-bench)\npython -m agentnova.examples.05_common_sense\n\n# Causal reasoning (BIG-bench)\npython -m agentnova.examples.06_causal_reasoning\n\n# Logical deduction (BIG-bench)\npython -m agentnova.examples.07_logical_deduction\n\n# Reading comprehension\npython -m agentnova.examples.08_reading_comprehension\n\n# General knowledge (BIG-bench)\npython -m agentnova.examples.09_general_knowledge\n\n# Implicit reasoning\npython -m agentnova.examples.10_implicit_reasoning\n\n# Analogical reasoning\npython -m agentnova.examples.11_analogical_reasoning\n```\n\n### Test Categories\n\n| Test | Questions | Focus |\n|------|-----------|-------|\n| Basic Agent | 1 | Single prompt, no tools |\n| Quick Diagnostic | 5 | Calculator tool, multi-step reasoning |\n| Tool Test | 10 | Calculator, shell, datetime, file, python_repl tools |\n| Reasoning Test | 14 | Logic, deduction, patterns, spatial |\n| GSM8K Benchmark | 50 | Math word problems |\n| Common Sense | 25 | Physical properties, everyday reasoning |\n| Causal Reasoning | 25 | Cause and effect relationships |\n| Logical Deduction | 25 | Formal logic puzzles |\n| Reading Comprehension | 25 | Passage-based Q\u0026A |\n| General Knowledge | 25 | Science, history, geography |\n| Implicit Reasoning | 25 | Unstated assumptions and inference |\n| Analogical Reasoning | 25 | Pattern matching and analogies |\n\n### Benchmark Results (Quick Diagnostic)\n\n| Model | Score | Time | Tool Support |\n|-------|-------|------|-------------|\n| functiongemma:270m | 5/5 (100%) | ~20s | native |\n| granite4:350m | 5/5 (100%) | ~50s | native |\n| qwen2.5:0.5b | 5/5 (100%) | 38s | native |\n| qwen2.5-coder:0.5b | 5/5 (100%) | 93s | native |\n| qwen3:0.6b | 5/5 (100%) | 70s | react |\n| deepseek-r1:1.5b | 5/5 (100%) | ~305s | native |\n\nAll tested models achieve 100% on the Quick Diagnostic. Native models are ~2x faster than ReAct models due to direct API tool calling.\n\n## Development\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run unit tests\npytest\n\n# Format code\nblack agentnova\nruff check agentnova\n```\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Author\n\n**VTSTech** — [https://www.vts-tech.org](https://www.vts-tech.org)\n\n## Contributing\n\nContributions welcome!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtstech%2Fagentnova","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtstech%2Fagentnova","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtstech%2Fagentnova/lists"}