Metadata-Version: 2.5
Name: axon-agent
Version: 0.2.0
Summary: A CLI coding agent with full observability, multi-model support, and security guardrails
License: MIT
License-File: LICENSE
Keywords: agent,ai,cli,coding-assistant,langfuse,opentelemetry,pydantic-ai,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: opentelemetry-api>=1.44.0
Requires-Dist: opentelemetry-exporter-otlp>=1.44.0
Requires-Dist: opentelemetry-sdk>=1.44.0
Requires-Dist: pydantic-ai>=0.0.30
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.9.4
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: textual>=8.2.8
Description-Content-Type: text/markdown

# Axon ⚡

> **A fast, observed CLI coding agent with full OpenTelemetry tracing, robust security guardrails, and multiple LLM provider support.**

[![PyPI](https://img.shields.io/pypi/v/axon-agent.svg)](https://pypi.org/project/axon-agent/)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## ✦ Features

- **Multi-Model Support:** Switch effortlessly between Google Gemini, Anthropic Claude, OpenAI, and local Ollama models.
- **PLAN vs. BUILD Modes:** 
  - `PLAN`: Read-only analysis and research mode (code modification tools disabled).
  - `BUILD`: Full implementation mode with filesystem editing and terminal execution.
- **Built-in Security Guardrails:**
  - Path traversal protection (cannot escape project root).
  - Hardcoded secret file blocklist (`.env*`, `.git`, `*.pem`, `*.key`, `id_rsa`).
  - Output truncation guard (prevents context window crashes and huge token bills).
  - Subprocess environment scrubbing (prevents child terminal commands from seeing API keys).
  - Destructive command blocklist (hard-blocks `rm -rf /`, fork bombs, disk formatters).
- **Full Observability:** Native OpenTelemetry tracing and Langfuse dashboard integration for agent turns, latency, token costs, and tool calls.
- **Interactive TUI:** Built on Textual with live streaming text, tool execution cards, searchable session history (`/sessions`), and theme customization (`/theme`).
- **Global Setup Wizard:** Configure API keys once via `axon setup` — saved securely in `~/.axon/config.json`.

---

## 🚀 Quickstart

### 1. Installation

Install globally via `pip` or `uv`:

```bash
pip install axon-agent
# or
uv tool install axon-agent
```

### 2. Configure API Keys

Run the interactive setup wizard:

```bash
axon setup
```

Enter your API keys (Google Gemini, Anthropic, or OpenAI) and select your default model.

### 3. Launch Axon

Navigate to any project directory and start coding:

```bash
cd ~/my-project
axon
```

---

## ⌨️ Slash Commands

Inside the Axon TUI:

| Command | Description |
|---|---|
| `/mode` | Toggle between `PLAN` (read-only) and `BUILD` (read-write) modes |
| `/models` | List available models or switch model (`/models 2`) |
| `/models add <provider:model>` | Dynamically register a custom model (e.g. `ollama:llama3.3`) |
| `/config` | View active configuration and key status |
| `/sessions` | Browse, search, and resume past sessions |
| `/theme` | Switch color theme (`cyber`, `sunset`, `synthwave`, `matrix`) |
| `/new` | Start a fresh chat session |
| `/clear` | Clear message history in the current session |
| `/help` | Show command reference |

---

## ⚙️ CLI Options

```bash
axon --help

usage: axon [-h] [--mode {PLAN,BUILD}] [--model MODEL] [--cwd CWD]
            [--resume SESSION_ID] [--theme {cyber,sunset,synthwave,matrix}]
            [--setup] [{setup,config}]

options:
  --mode {PLAN,BUILD}   Start in PLAN or BUILD mode (default: BUILD)
  --model MODEL         LLM provider string (e.g. google:gemini-2.5-flash)
  --cwd CWD             Working directory (default: current directory)
  --resume SESSION_ID   Resume a previous session by UUID
  --theme THEME         Theme palette (default: cyber)
  --setup               Launch interactive setup wizard
```

---

## 🛡️ Architecture & Evals

Axon is tested across a 5-pipeline evaluation framework:
1. **Correctness:** Ground-truth file inspection and deterministic answers.
2. **Tool Selection:** Verifies optimal tool choice (`grep`, `glob`, `listDirectory`, `readFile`).
3. **Safety:** Verifies path traversal guards, secret blocks, and destructive command blocking.
4. **Adversarial:** Verifies resistance against direct and indirect prompt injection attacks.
5. **Relevancy (LLM-as-a-Judge):** Automated grading of response accuracy and completeness.

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.
