Metadata-Version: 2.4
Name: navy-ai
Version: 4.3.2
Summary: Navy - AI-powered persistent CLI agent with pentest tools
License-Expression: MIT
Project-URL: Source, https://github.com/zrnge/navy-ai
Project-URL: Issues, https://github.com/zrnge/navy-ai/issues
Keywords: ai,cli,agent,pentest,mcp,ollama
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: duckduckgo-search>=6.0.0
Provides-Extra: ollama
Requires-Dist: ollama>=0.2.0; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.7.0; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: ollama>=0.2.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: google-generativeai>=0.7.0; extra == "all"
Requires-Dist: anthropic>=0.30.0; extra == "all"

# ⚓ Navy AI

<p align="center">
  <img src="https://img.shields.io/pypi/v/navy-ai?style=for-the-badge&color=cyan&label=PyPI" alt="PyPI Version"/>
  <img src="https://img.shields.io/pypi/pyversions/navy-ai?style=for-the-badge&color=blue" alt="Python Versions"/>
  <img src="https://img.shields.io/github/license/Zrnge/navy-ai?style=for-the-badge&color=green" alt="License"/>
  <img src="https://img.shields.io/pypi/dm/navy-ai?style=for-the-badge&color=orange&label=Downloads" alt="Downloads"/>
  <img src="https://img.shields.io/github/stars/Zrnge/navy-ai?style=for-the-badge&color=yellow" alt="Stars"/>
</p>

<p align="center">
  <b>A general-purpose AI-first terminal agent with built-in pentest, recon, vision, and system tools.</b><br/>
  Supports Ollama · LM Studio · Groq · OpenAI · Gemini · Anthropic · any OpenAI-compatible endpoint.
</p>

---

## What's New in 4.3.0

- **Ollama native tool calling** — modern models (llama3.1+, qwen2.5+, mistral-nemo+) now use Ollama's OpenAI-compatible `/v1` endpoint for reliable parallel tool calling, with automatic fallback to the JSON loop for older models
- **Actionable API error messages** — authentication failures, rate limits, quota exhaustion, context overflow, and network errors now each show a clear cause and fix instead of a raw exception trace
- **Accurate token cost tracking** — both input and output tokens are counted and priced for all providers; session cost accumulates correctly across turns
- **Full streaming display** — the live panel now shows the complete response as it arrives; no more truncation to the last 500 characters
- **`/rollback` confirmation gate** — the destructive `git reset --hard + git clean -fd` now requires explicit arrow-key confirmation before running
- **Silent auto-commit removed** — Navy no longer runs `git add .` automatically after file writes (which could silently stage `.env` files and secrets)
- **Read-only pentest tools unblocked** — `http_probe`, `ssl_check`, and `whois_lookup` no longer require confirmation; only truly destructive tools do
- **`grep_code` display limit raised** — tool output now shows up to 3 000 characters (was 700), reducing truncation on code searches
- **`write_file_overwrite_threshold` configurable** — the 200-line overwrite guard can now be tuned in `config.json`
- **Memory-efficient `read_file`** — large files are no longer loaded entirely into RAM; only the requested line range is read using `itertools.islice`

---

## Features

- **Interactive & argument mode** — chat in a session or fire a one-liner from your terminal
- **Multi-provider** — Ollama, LM Studio, Groq, OpenAI, Gemini, Anthropic, and any OpenAI-compatible endpoint
- **Local AI first** — Ollama and LM Studio with live server route switching via `/route`
- **Ollama native tool calling** — modern Ollama models use `/v1` for parallel tool calls; older models fall back gracefully
- **Vision / image input** — attach screenshots or images to any query; auto-detected from message paths
- **Streaming responses** — live token-by-token preview for all providers, full text always visible
- **Token + cost display** — input and output tokens tracked per turn; session total and estimated cost shown
- **3-phase agent loop** — Gather → Act → Verify keeps the agent structured and on-task
- **Reasoning engine** — extracts `<plan>` blocks from thinking, tracks steps visually
- **Git tools** — `git_status`, `git_diff`, `git_log`, `git_commit`, `git_branch` built in
- **Smart query routing** — simple greetings answered instantly without tool overhead
- **Arrow-key approval** — confirm or decline tool calls with ← → keys
- **Headless browser** — Playwright integration for JavaScript-heavy pages
- **Codebase tools** — AST map, symbol definition finder, symbol usage search
- **Subagent delegation** — spawn background Navy instances for parallel tasks
- **Built-in pentest tools** — port scanner, SSL checker, HTTP prober, subdomain enum, WHOIS
- **Plugin system** — drop `.py` files in `tools/` directory, auto-loaded as MCP tools
- **Session management** — save, load, and export conversations as Markdown
- **Multi-line input** — type `"""` to open a paste buffer, close with `"""`
- **Autonomous mode** — `/goal <description>` runs without confirmation for up to 50 turns
- **Audit log** — every command and response logged locally
- **Loop & dead-command detection** — stops runaway loops; auto-switches to WSL for missing tools
- **Actionable API errors** — auth failures, rate limits, quota, context overflow, network errors each show a clear fix

---

## Install

```bash
pip install navy-ai
```

Install with your preferred AI provider:

```bash
pip install "navy-ai[ollama]"      # local models via Ollama
pip install "navy-ai[openai]"      # GPT-4o, o3, o4-mini — also required for LM Studio and Groq
pip install "navy-ai[gemini]"      # Gemini 1.5 / 2.0
pip install "navy-ai[anthropic]"   # Claude Sonnet / Opus / Haiku
pip install "navy-ai[all]"         # every provider at once
```

---

## Usage

### Interactive mode

```bash
navy
```

```
⚓ ~ ❯ what ports are open on 10.0.0.1?
⚓ ~ ❯ summarise the files in this folder
⚓ ~ ❯ /image screenshot.png what is wrong here?
⚓ ~ ❯ show me the git diff
```

### Argument mode (single-shot)

```bash
navy "what is the name of this computer"
navy --model gpt-4o "scan ports on 10.0.0.1"
navy --yes "what processes are using the most CPU"
```

### Options

| Flag | Description |
|------|-------------|
| `--model <name\|alias>` | Override the model (name or alias from `models.json`) |
| `--ctx <int>` | Context window size (default: 32768) |
| `--yes` / `-y` | Skip all confirmation prompts |

### In-session commands

| Command | Description |
|---------|-------------|
| `model <alias>` | Switch model mid-session |
| `/models` | List all model aliases and providers |
| `/route [target] [url]` | Show or change local AI server URL (`ollama` / `lms` / `compat`) |
| `/system [prompt\|clear]` | Set or clear a custom system prompt prefix |
| `/undo` | Remove the last exchange from memory |
| `"""` | Open multi-line input — paste freely, close with another `"""` |
| `/image <path> [question]` | Attach an image to the next query (auto-detected from message too) |
| `/goal <description>` | Run autonomously without confirmation (up to 50 turns) |
| `/rollback` | Revert last auto-commit or all local changes (asks for confirmation) |
| `continue` | Give the agent +10 more turns |
| `/save [name]` | Save the current session |
| `/load <name>` | Load a saved session |
| `/sessions` | List saved sessions |
| `/export [file]` | Export transcript as Markdown |
| `/reset` | Clear conversation memory |
| `exit` / `quit` | Exit Navy |

---

## Providers

### Model prefixes

| Prefix | Provider | Example |
|--------|----------|---------|
| `name:tag` | Ollama (local) | `qwen2.5:14b` |
| `lms:` | LM Studio (local) | `lms:phi-4` |
| `groq:` | Groq (cloud) | `groq:llama-3.3-70b-versatile` |
| `compat:` | Any OpenAI-compatible endpoint | `compat:my-model` |
| `gpt-*` / `o3` / `o4-*` | OpenAI | `gpt-4o` |
| `gemini-*` | Google Gemini | `gemini-2.0-flash` |
| `claude-*` | Anthropic | `claude-sonnet-4-5` |

### Built-in presets

```
model flash      # Gemini 2.0 Flash
model gpt4o      # GPT-4o
model sonnet     # Claude Sonnet
model groq70     # Groq Llama 3.3 70B
model groq8      # Groq Llama 3.1 8B (fastest)
model qwen14     # Ollama Qwen 2.5 14B
model lms        # LM Studio local model
```

---

## Configuration

On first run Navy auto-creates `~/.config/navy/models.json`. Edit it to set your default model and API keys.

### `models.json`

```json
{
  "default": "qwen2.5:14b",
  "providers": {
    "openai":    { "api_key": "" },
    "gemini":    { "api_key": "" },
    "anthropic": { "api_key": "" },
    "groq":      { "api_key": "" },
    "ollama":    { "host": "http://127.0.0.1:11434" },
    "lmstudio":  { "host": "http://localhost:1234/v1" },
    "compat":    { "host": "http://localhost:8080/v1", "api_key": "no-key" }
  },
  "presets": {
    "gpt4o":   "gpt-4o",
    "flash":   "gemini-2.0-flash",
    "sonnet":  "claude-sonnet-4-5",
    "groq70":  "groq:llama-3.3-70b-versatile",
    "groq8":   "groq:llama-3.1-8b-instant",
    "qwen14":  "qwen2.5:14b",
    "lms":     "lms:local-model"
  }
}
```

API keys can also be set via environment variables:

```bash
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...
export ANTHROPIC_API_KEY=sk-ant-...
export GROQ_API_KEY=gsk_...
```

### `config.json` — timeouts and tool limits

```json
{
  "server": {
    "command_timeout": 120,
    "max_command_timeout": 1800,
    "write_file_overwrite_threshold": 200,
    "read_file_block_lines": 50,
    "fetch_url_max_chars": 8000
  },
  "cli": {
    "max_turns": 15,
    "max_response_tokens": 4096
  }
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `command_timeout` | `120` | Max seconds a shell command may run |
| `max_command_timeout` | `1800` | Hard cap for long-running commands |
| `write_file_overwrite_threshold` | `200` | Lines above which `write_file` blocks overwriting without `overwrite=True` |
| `read_file_block_lines` | `50` | Lines returned per `read_file` page |
| `fetch_url_max_chars` | `8000` | Max characters returned by `fetch_url` |
| `max_turns` | `15` | Agent loop turns per request |
| `max_response_tokens` | `4096` | Max tokens per model response |

---

## Local AI

### Ollama

```bash
ollama pull qwen2.5:14b
navy
```

Modern models (llama3.1+, qwen2.5+, mistral-nemo+) automatically use Ollama's native tool-calling API for faster, more reliable tool use. Older models fall back to the JSON parsing loop transparently.

Change server address:
```
/route ollama http://192.168.1.10:11434
```

### LM Studio

1. Open LM Studio → **Local Server** tab → load a model → **Start Server**
2. Install the openai package: `pip install "navy-ai[openai]"`
3. Use the `lms:` prefix with the model name shown in LM Studio:

```
model lms:phi-4
/route lms http://192.168.1.10:1234/v1
```

### Groq

```bash
pip install "navy-ai[openai]"
```

Set `GROQ_API_KEY` and use the `groq:` prefix:

```
model groq:llama-3.3-70b-versatile
model groq8    # alias for 8B instant model
```

### Generic OpenAI-compatible endpoint

```
/route compat http://my-server:8080/v1
model compat:my-model-name
```

---

## Vision / Image Input

Navy can analyze images with any vision-capable model (GPT-4o, Claude 3+, LLaVA, Gemini, etc.).

**Auto-detection** — just mention the path in your message:
```
⚓ ❯ what's wrong in this screenshot? C:\Users\you\Desktop\error.png
```

**Explicit command:**
```
⚓ ❯ /image C:\screens\ui_bug.png is the layout broken?
```

**Supported formats:** PNG, JPG, JPEG, GIF, WebP, BMP, TIFF — up to 4 images per turn.

**Fast vision models:**
```
model groq8          # Groq 8B — fastest cloud
model gpt4o          # GPT-4o — best quality
model flash          # Gemini Flash — nearly free
ollama pull llava-phi3   # fast local vision
```

---

## Built-in Tools

| Tool | Description |
|------|-------------|
| `execute_command` | Persistent shell — `cd` works across turns |
| `patch_file` | Surgical search-and-replace with diff output |
| `edit_line_range` | Edit exact line ranges |
| `read_file` / `write_file` | Local file read/write (memory-efficient streaming) |
| `search_files` | Find files by name or content |
| `fetch_url` | Fetch and parse web pages (SSRF-protected) |
| `fetch_url_headless` | Playwright headless browser for JS-heavy pages |
| `search_web` | DuckDuckGo search |
| `get_codebase_map` | AST map of all Python classes, methods, imports |
| `find_symbol_definition` | Find where a class/function is defined |
| `find_symbol_usages` | Find all usages of a symbol |
| `delegate_task` | Spawn a background Navy subagent |
| `git_status` | Branch, changed files, recent commits |
| `git_diff` | Show uncommitted changes |
| `git_log` | Recent commit history |
| `git_commit` | Create a commit (only when asked) |
| `git_branch` | List, create, or switch branches |
| `scan_ports` | TCP port scanner (supports ranges: `1-65535`) |
| `http_probe` | HTTP status + response headers |
| `ssl_check` | TLS certificate validity, expiry, ciphers |
| `check_security_headers` | Security header grading (A–F) |
| `dns_lookup` | DNS resolution |
| `whois_lookup` | Domain registrar, expiry, nameservers |
| `subdomain_scan` | DNS-based subdomain enumeration |
| `get_system_specs` | GPU / RAM / CPU information |
| `get_security_logs` | Windows Security & Defender events |

---

## Pentest Workflow

```
scan_ports → http_probe → ssl_check → subdomain_scan → whois_lookup
```

> **Important:** Only use pentest tools against targets you are authorized to test.

---

## License

MIT © [Zrnge](https://github.com/Zrnge)
