Metadata-Version: 2.4
Name: navaia-code
Version: 1.0.64
Summary: Navaia Code — AI coding agent, built in Python
Requires-Python: >=3.12
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: arabic-reshaper>=3.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-bidi>=0.6.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: textual>=0.80.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# Navaia Code – AI‑Powered Coding Assistant

## Overview

Navaia Code is a **self‑hosted, extensible AI coding agent** written in pure Python. It provides a full‑featured tool‑driven workflow where the model can read, write, execute, and reason over files, run shell commands, fetch web content, interact with external services, and more—all from a terminal UI built with **Textual** (Rich‑based). The architecture is deliberately modular so you can swap the LLM provider, add new tools, or embed Navaia in other Python programs.

---

## Key Features

| Feature | Description |
|---------|-------------|
| **LLM‑agnostic** | Works with any OpenAI‑compatible endpoint (OpenAI, OpenRouter, Ollama, Groq, Together, etc.) – just set a `base_url` and an API key. |
| **Rich tool ecosystem** | 50+ built‑in tools (bash, file‑read/write/edit, glob, grep, web‑fetch, MCP, task manager, …). |
| **Fine‑grained permission model** | Allow/deny rules based on glob patterns, tool‑specific checks, and interactive user prompts. |
| **Streaming & concurrent tool use** | Async generators stream partial model responses while tools run concurrently. |
| **Memory & automatic compaction** | Long‑term memory files, token‑budget‑aware compaction, and restore of lost context. |
| **Background task system** | Create, list, update, and retrieve long‑running tasks (e.g. scripts, builds). |
| **MCP integration** | Direct access to Model‑Context‑Protocol resources. |
| **Extensible CLI** | Slash commands (`/help`, `/config`, `/think`, `/bug`, …) and a plug‑in system for custom commands. |
| **Rich terminal UI** | Textual UI with markdown rendering, syntax highlighting, spinners, and permission prompts. |

---

## Quick Start

### One-liner setup

```bash
git clone https://github.com/NavaiaSolutions/navaia-code-main.git
cd navaia-code-main
./setup.sh              # creates .venv, installs navaia, copies .env.example -> .env
```

Then edit `.env` to pick a provider and drop in your key:

```bash
./bin/navaia            # launch interactive UI (works from any directory)
./bin/navaia -p "hi"    # one-shot print mode
```

### Make `navaia` work globally

```bash
./setup.sh --global     # symlinks bin/navaia into ~/.local/bin
```

If `~/.local/bin` isn't on your PATH yet, setup prints the exact line to add to `~/.zshrc` / `~/.bashrc`. After that, `navaia` works from any directory, just like `claude`.

### Prerequisites

* **Python 3.12+** — only hard requirement.
* **Git** — to clone the repo.

> **Windows users:** `setup.sh` runs in Git Bash (included with [Git for Windows](https://gitforwindows.org/)).  
> Make sure Python 3.12+ is installed (Anaconda or python.org) and on your PATH.  
> After setup, activate the virtual environment with `.venv\Scripts\activate` in CMD, or  
> `source .venv/Scripts/activate` in Git Bash.
* **A provider** — one of:
  * **OpenRouter** (cloud, easiest): grab a key, set `OPENROUTER_API_KEY`.
  * **Ollama** (local): `ollama pull qwen2.5:7b && ollama serve`, then `NAVAIA_PROVIDER=ollama`.
  * **vLLM / llama.cpp / LM Studio / SGLang** (self-hosted): start the server, then `NAVAIA_PROVIDER=qwen` and point `NAVAIA_QWEN_BASE_URL` at it.
  * **Internal vLLM deployment**: `NAVAIA_PROVIDER=internal`.

### Picking a provider (`.env`)

All four providers are pre-wired in `.env.example` — uncomment the block you want:

```dotenv
# Provider: openrouter | internal | qwen | ollama
NAVAIA_PROVIDER=openrouter

# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# ...or local Qwen via vLLM / llama.cpp / LM Studio
# NAVAIA_PROVIDER=qwen
# NAVAIA_QWEN_BASE_URL=http://localhost:8000/v1
# NAVAIA_QWEN_MODEL=Qwen/Qwen2.5-7B-Instruct

# ...or Ollama
# NAVAIA_PROVIDER=ollama
# NAVAIA_OLLAMA_MODEL=qwen2.5:7b
```

Precedence is **env vars > `~/.navaia/config.json` > built-in defaults**, so you can commit a team default and let individual devs override locally.

### Manual install (if you skip setup.sh)

**macOS / Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env    # then edit
navaia                  # inside the venv, 'navaia' is on PATH
```

**Windows (CMD):**
```cmd
python -m venv .venv
.venv\Scripts\activate
pip install -e .
copy .env.example .env
navaia
```

## Using a Local Ollama Server

Ollama provides a **self‑hosted LLM** that implements the OpenAI API schema.

1. **Install Ollama** (see https://ollama.com for platform‑specific instructions).  
2. **Pull a model** (e.g. `llama3.1:8b`):

   ```bash
   ollama pull llama3.1:8b
   ```

3. **Start the Ollama server** (default listens on `127.0.0.1:11434`):

   ```bash
   ollama serve
   ```

4. **Configure Navaia** to point at Ollama:

   ```dotenv
   NAVAIA_BASE_URL=http://127.0.0.1:11434/v1
   NAVAIA_MODEL=llama3.1:8b
   # Ollama does not require an API key, but the variable can be left empty.
   NAVAIA_OPENAI_API_KEY=
   ```

5. **Run** as usual (`navaia chat` or `navaia ask …`). All tool‑loop, streaming, and permission handling work unchanged.

---

## Connecting Through an NGINX (NGX) Proxy

You may want to expose the Ollama (or any OpenAI‑compatible) server behind a reverse proxy for TLS termination, authentication, or path rewriting.

### Example NGINX configuration

```nginx
server {
    listen 443 ssl;
    server_name navaia.example.com;

    # TLS certificates
    ssl_certificate     /etc/letsencrypt/live/navaia.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/navaia.example.com/privkey.pem;

    # Forward all /v1/* API calls to the local Ollama instance
    location /v1/ {
        proxy_pass http://127.0.0.1:11434/v1/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Optional basic auth
    auth_basic "Navaia API";
    auth_basic_user_file /etc/nginx/.htpasswd;
}
```

### Point Navaia at the NGX endpoint

1. **Update `.env`** (or your environment) with the public URL:

   ```dotenv
   NAVAIA_BASE_URL=https://navaia.example.com/v1
   NAVAIA_MODEL=llama3.1:8b          # model name as known to Ollama
   NAVAIA_OPENAI_API_KEY=YOUR_KEY   # if you added basic auth, use the password here
   ```

2. **If you use basic auth**, you can pass the credentials via the `NAVAIA_OPENAI_API_KEY` variable (the OpenAI client treats it as a bearer token). For more complex header needs, set `NAVAIA_HEADERS` to a JSON string containing custom headers.

3. **Test the connection**:

   ```bash
   curl -s https://navaia.example.com/v1/models | jq .
   ```

   You should see a JSON list of available models (including the Ollama model you pulled).

4. **Run Navaia** – everything else stays the same.

---

## Advanced Configuration

All settings are consolidated in `navaia/config/settings.py` and can be overridden via:

| Source | Precedence (high → low) |
|--------|------------------------|
| Environment variables (`NAVAIA_*`) |
| `~/.navaia/config.json` (user‑wide) |
| `.claude/config.json` in the current project (project‑specific) |
| Defaults in the source code |

Key configurable sections include:

* **`permissions`** – glob‑based allow/deny rules for each tool.  
* **`tool_defaults`** – default arguments (e.g., `bash.max_output_lines`).  
* **`streaming`** – token budget, temperature, top‑p, etc.  
* **`memory`** – directory locations, compaction thresholds.  

You can edit the JSON files directly or use the built‑in CLI command:

```bash
navaia config edit   # opens your $EDITOR
```

---

## Development & Contributing

1. **Fork the repo** and create a feature branch.  
2. **Run tests** (pytest is used):

   ```bash
   pytest -q
   ```

3. **Lint / type‑check** (optional but recommended):

   ```bash
   ruff check .
   mypy .
   ```

4. **Submit a PR** – the CI pipeline runs the full test suite and checks formatting.

Please follow the existing code style (black‑compatible formatting, type hints, docstrings in Google style).

---

## License

Navaia Code is released under the **MIT License**. See `LICENSE` for details.

---

### TL;DR

* Install Python 3.12+, create a venv, `pip install -e .`.  
* Set `NAVAIA_BASE_URL` and `NAVAIA_MODEL` (Ollama → `http://127.0.0.1:11434/v1`).  
* Run `navaia chat` (interactive) or `navaia ask …` (single query).  
* To expose Ollama behind NGINX, configure the proxy and point `NAVAIA_BASE_URL` at the public URL.  

Enjoy coding with an AI that runs **entirely on your machine** (or any OpenAI‑compatible endpoint you control)!
