axon-agent 0.1.0__tar.gz

axon_agent-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# .env.example (commit this)
+OPENAI_API_KEY=your-openai-key-here
+GEMINI_API_KEY=your-gemini-key-here
+AXON_DEFAULT_MODEL=openai:gpt-4o   # or google-gla:gemma-3-27b-it

axon_agent-0.1.0/.github/workflows/evals.yml

@@ -0,0 +1,90 @@
+name: Axon CI & Evals
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      pipeline:
+        description: "Which eval pipeline to run"
+        required: true
+        default: "deterministic"
+        type: choice
+        options:
+          - deterministic
+          - all
+          - correctness
+          - tool_selection
+          - safety
+          - adversarial
+          - relevancy
+
+jobs:
+  code-quality:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Ruff Linter
+        run: uv run ruff check .
+
+  evals:
+    name: Agent Evaluations
+    runs-on: ubuntu-latest
+    # Only run evals if repository secrets are configured (avoids failure on external PR forks without secrets)
+    if: ${{ secrets.GOOGLE_API_KEY != '' }}
+    env:
+      GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+      LANGFUSE_PUBLIC_KEY: ${{ secrets.LANGFUSE_PUBLIC_KEY }}
+      LANGFUSE_SECRET_KEY: ${{ secrets.LANGFUSE_SECRET_KEY }}
+      LANGFUSE_HOST: ${{ secrets.LANGFUSE_HOST || 'https://cloud.langfuse.com' }}
+      AXON_DEFAULT_MODEL: "google:gemini-2.5-flash"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Eval Suite
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            if [ "${{ inputs.pipeline }}" = "all" ]; then
+              echo "Running full eval suite (including LLM Judge)..."
+              uv run pytest tests/ -v -s
+            elif [ "${{ inputs.pipeline }}" = "deterministic" ]; then
+              echo "Running all deterministic pipelines..."
+              uv run pytest tests/ -m "not relevancy" -v -s
+            else
+              echo "Running pipeline: ${{ inputs.pipeline }}..."
+              uv run pytest tests/ -m "${{ inputs.pipeline }}" -v -s
+            fi
+          else
+            echo "Running deterministic eval pipelines for PR/push..."
+            uv run pytest tests/ -m "not relevancy" -v -s
+          fi

axon_agent-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+.axon/

axon_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

axon_agent-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: axon-agent
+Version: 0.1.0
+Summary: A CLI coding agent with full observability, multi-model support, and security guardrails
+License: MIT
+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 (`nightfox`, `catppuccin`, `dracula`, `gruvbox`) |
+| `/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 {nightfox,catppuccin,dracula,gruvbox}]
+            [--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: nightfox)
+  --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.

axon_agent-0.1.0/README.md

@@ -0,0 +1,113 @@
+# 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 (`nightfox`, `catppuccin`, `dracula`, `gruvbox`) |
+| `/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 {nightfox,catppuccin,dracula,gruvbox}]
+            [--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: nightfox)
+  --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.

axon_agent-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "axon-agent"
+version = "0.1.0"
+description = "A CLI coding agent with full observability, multi-model support, and security guardrails"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+keywords = ["ai", "agent", "coding-assistant", "cli", "tui", "opentelemetry", "langfuse", "pydantic-ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pydantic-ai>=0.0.30",
+    "python-dotenv>=1.0.1",
+    "sqlmodel>=0.0.22",
+    "rich>=13.9.4",
+    "textual>=8.2.8",
+    "opentelemetry-api>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+    "opentelemetry-exporter-otlp>=1.44.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "langfuse",
+    "ruff",
+    "pyright",
+    "hatch",
+    "twine",
+    "build",
+]
+
+[project.scripts]
+axon = "axon.main:main"   # creates the `axon` CLI command
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axon"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.pyright]
+pythonVersion = "3.12"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "correctness: Tests that verify the agent produces the right answer",
+    "tool_selection: Tests that verify the agent picks the correct tool",
+    "safety: Tests that verify the agent respects guardrails",
+    "adversarial: Tests that verify the agent resists prompt injection",
+    "relevancy: Tests that use LLM-as-a-Judge to grade response quality",
+]

axon_agent-0.1.0/src/axon/__init__.py

@@ -0,0 +1,7 @@
+"""
+Axon — A CLI coding agent with full observability.
+"""
+from axon.config import __version__
+from axon.agent import create_agent
+
+__all__ = ["__version__", "create_agent"]

axon_agent-0.1.0/src/axon/agent.py

@@ -0,0 +1,31 @@
+"""
+Axon agent factory.
+
+Instantiates and configures a PydanticAI Agent with:
+- Dynamic system prompt (PLAN vs BUILD mode)
+- OpenTelemetry instrumentation for Langfuse tracing
+- Modular tool registration (filesystem + shell)
+"""
+from pydantic_ai import Agent
+from pydantic_ai.capabilities import Instrumentation
+
+from axon.system_prompt import build_system_prompt
+from axon.tools import register_tools
+
+
+def create_agent(mode: str, model_str: str, cwd: str) -> Agent:
+    """
+    Create an agent instance configured for the given mode, model, and directory.
+
+    Args:
+        mode: "PLAN" (read-only) or "BUILD" (read-write).
+        model_str: Model provider string (e.g. "google:gemini-2.5-flash").
+        cwd: Working directory root for filesystem and shell operations.
+
+    Returns:
+        Configured PydanticAI Agent ready for execution.
+    """
+    prompt = build_system_prompt(mode)
+    agent = Agent(model_str, system_prompt=prompt, capabilities=[Instrumentation()])
+    register_tools(agent, mode=mode, cwd=cwd)
+    return agent

axon_agent-0.1.0/src/axon/config.py

@@ -0,0 +1,194 @@
+"""
+Central configuration and persistent user settings for Axon.
+
+Manages:
+- Constants, defaults, and paths (~/.axon/config.json)
+- Automatic loading of global user API keys into os.environ
+- Dynamic model lists (default models + user-added custom models)
+- Secure config saving with restricted file permissions (0600)
+"""
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+# Version
+__version__ = "0.1.0"
+
+# Defaults
+DEFAULT_FALLBACK_MODEL = "google:gemini-2.5-flash"
+DEFAULT_THEME = "nightfox"
+DEFAULT_MODE = "BUILD"
+
+# Standard default models
+DEFAULT_MODELS = [
+    "google:gemini-2.5-flash",
+    "google:gemini-1.5-pro",
+    "google:gemma-4-31b-it",
+    "anthropic:claude-3-5-haiku-latest",
+    "anthropic:claude-opus-4-5",
+    "openai:gpt-4o-mini",
+    "openai:gpt-4o",
+]
+
+# Paths
+AXON_DIR = Path.home() / ".axon"
+AXON_DIR.mkdir(parents=True, exist_ok=True)
+CONFIG_PATH = AXON_DIR / "config.json"
+DB_PATH = AXON_DIR / "sessions.db"
+DATABASE_URL = f"sqlite:///{DB_PATH}"
+
+# Known API key environment variable names
+KNOWN_KEY_NAMES = [
+    "GOOGLE_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGFUSE_HOST",
+]
+
+
+def get_default_config() -> Dict[str, Any]:
+    """Return initial default configuration dictionary."""
+    return {
+        "default_model": DEFAULT_FALLBACK_MODEL,
+        "default_theme": DEFAULT_THEME,
+        "default_mode": DEFAULT_MODE,
+        "models": list(DEFAULT_MODELS),
+        "keys": {
+            "GOOGLE_API_KEY": "",
+            "ANTHROPIC_API_KEY": "",
+            "OPENAI_API_KEY": "",
+            "LANGFUSE_PUBLIC_KEY": "",
+            "LANGFUSE_SECRET_KEY": "",
+            "LANGFUSE_HOST": "https://cloud.langfuse.com",
+        },
+    }
+
+
+def load_config() -> Dict[str, Any]:
+    """Load configuration from ~/.axon/config.json or return defaults."""
+    if not CONFIG_PATH.exists():
+        return get_default_config()
+
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        # Ensure all required top-level keys exist
+        default_cfg = get_default_config()
+        for k, v in default_cfg.items():
+            if k not in data:
+                data[k] = v
+        if isinstance(data.get("keys"), dict):
+            for key_name, default_val in default_cfg["keys"].items():
+                if key_name not in data["keys"]:
+                    data["keys"][key_name] = default_val
+        return data
+    except Exception:
+        return get_default_config()
+
+
+def save_config(config_data: Dict[str, Any]) -> None:
+    """Save configuration to ~/.axon/config.json with secure 0600 file permissions."""
+    AXON_DIR.mkdir(parents=True, exist_ok=True)
+    temp_path = CONFIG_PATH.with_suffix(".tmp")
+    
+    # Write JSON formatted
+    temp_path.write_text(json.dumps(config_data, indent=2), encoding="utf-8")
+    
+    # Set restricted permissions (owner read/write only) on non-Windows platforms
+    try:
+        if os.name != "nt":
+            temp_path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except Exception:
+        pass
+
+    temp_path.replace(CONFIG_PATH)
+
+
+def inject_env_keys() -> None:
+    """
+    Inject keys from ~/.axon/config.json into os.environ.
+    Does NOT overwrite keys already set in the active shell environment.
+    """
+    cfg = load_config()
+    keys = cfg.get("keys", {})
+    for key_name, key_val in keys.items():
+        if key_val and not os.getenv(key_name):
+            os.environ[key_name] = str(key_val).strip()
+
+
+def get_api_key(name: str) -> Optional[str]:
+    """Get an API key by name from os.environ or config.json."""
+    if os.getenv(name):
+        return os.getenv(name)
+    cfg = load_config()
+    return cfg.get("keys", {}).get(name) or None
+
+
+def set_api_key(name: str, value: str) -> None:
+    """Save an API key into ~/.axon/config.json and update os.environ."""
+    cfg = load_config()
+    if "keys" not in cfg:
+        cfg["keys"] = {}
+    cfg["keys"][name] = value.strip()
+    save_config(cfg)
+    os.environ[name] = value.strip()
+
+
+def get_models() -> List[str]:
+    """Get full list of available models (defaults + user custom models)."""
+    cfg = load_config()
+    models = cfg.get("models", DEFAULT_MODELS)
+    return list(models) if isinstance(models, list) else list(DEFAULT_MODELS)
+
+
+def add_custom_model(model_str: str) -> bool:
+    """
+    Add a custom model identifier string (e.g. 'ollama:llama3.3' or 'openai:gpt-4o')
+    to ~/.axon/config.json. Returns True if added, False if already present.
+    """
+    model_clean = model_str.strip()
+    if not model_clean:
+        return False
+
+    cfg = load_config()
+    models = cfg.get("models", list(DEFAULT_MODELS))
+    if model_clean not in models:
+        models.append(model_clean)
+        cfg["models"] = models
+        save_config(cfg)
+        return True
+    return False
+
+
+def has_valid_key() -> bool:
+    """
+    Check if the user has configured at least one LLM provider key
+    (Google Gemini, Anthropic, or OpenAI).
+    """
+    # Check env first
+    if os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY"):
+        return True
+    if os.getenv("ANTHROPIC_API_KEY"):
+        return True
+    if os.getenv("OPENAI_API_KEY"):
+        return True
+
+    # Check config.json
+    cfg = load_config()
+    keys = cfg.get("keys", {})
+    return bool(
+        keys.get("GOOGLE_API_KEY")
+        or keys.get("ANTHROPIC_API_KEY")
+        or keys.get("OPENAI_API_KEY")
+    )
+
+
+# Automatically inject stored keys on module import
+inject_env_keys()
+
+# Active defaults resolved after injection
+DEFAULT_MODEL = os.getenv("AXON_DEFAULT_MODEL", load_config().get("default_model", DEFAULT_FALLBACK_MODEL))
+SUPPORTED_MODELS = get_models()