axonwork 0.2.0__tar.gz

axonwork-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: axonwork
+Version: 0.2.0
+Summary: Axon mining CLI for the Proof of Useful Work platform
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.15.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: litellm>=1.60.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: eth-account>=0.13.0
+Requires-Dist: simple-term-menu>=1.6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"

axonwork-0.2.0/README.md

@@ -0,0 +1,167 @@
+# axon-cli
+
+Command-line miner for the Axon USDC bounty platform. Connects to an axon-server instance, selects tasks, runs AI backends to generate solutions, submits them for evaluation, and iterates until the score improves or the task is completed.
+
+## What is this?
+
+The CLI is the miner's interface to Axon. It generates an Ethereum wallet, authenticates with the server via signature, then enters a mining loop: pick a task, generate an answer via one of three backends (litellm API, Claude Code CLI, or Codex CLI), submit the answer, read the eval feedback, and try again.
+
+## Quick Start
+
+```bash
+# Prerequisites: Python 3.11+, uv
+uv venv && uv pip install -e .
+
+# First-time setup (generates wallet, picks backend + LLM provider)
+.venv/bin/axon onboard
+
+# Start mining
+.venv/bin/axon mine
+
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `axon onboard` | First-time setup: generate wallet, configure server + backend + LLM |
+| `axon mine` | Start mining loop (interactive task selection; defaults to 5 rounds with a 10 minute hard timeout per CLI backend call) |
+| `axon mine --max-rounds 10` | Limit mining to N rounds |
+| `axon mine --timeout 180` | Override the hard timeout for each CLI backend call in this run |
+| `axon mine --yolo` | Disable hard timeout and round limit for this run; stop manually with `Ctrl+C` |
+| `axon mine -yolo` | Alias for `axon mine --yolo` |
+| `axon balance` | Show USDC balance (platform + on-chain Base) |
+| `axon wallet` | Show wallet address |
+| `axon model` | Show or switch LLM model (interactive picker) |
+| `axon model NAME` | Set model directly (e.g. `anthropic/claude-sonnet-4-20250514`) |
+| `axon backend` | Show or switch mining backend (interactive picker) |
+| `axon backend NAME` | Set backend directly (`auto`, `litellm`, `claude-cli`, `codex-cli`) |
+| `axon stats` | Mining statistics (earned, improvements) |
+| `axon tasks` | Browse open tasks |
+| `axon tasks --status-filter completed` | Filter tasks by status |
+
+## Mining Backends
+
+The CLI supports three backends for generating solutions. The `auto` backend (default) picks the first available in order: `claude-cli` > `codex-cli` > `litellm`.
+
+| Backend | Description | Requirements |
+|---------|-------------|--------------|
+| **litellm** | Call LLM APIs (Anthropic, OpenAI, DeepSeek, Ollama) via litellm | API key in config |
+| **claude-cli** | Agentic mining via Claude Code CLI (tools, search, code exec) | `claude` binary in PATH |
+| **codex-cli** | Agentic mining via OpenAI Codex CLI (code exec, search) | `codex` binary in PATH |
+
+CLI backends (`claude-cli`, `codex-cli`) manage their own API keys and model selection. The `litellm` backend uses the model and API keys configured in `~/.axon/config.json`.
+
+## Mining Loop
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    Mining Round                       │
+│                                                      │
+│  1. Build prompt (task + best answer + feedback)     │
+│  2. Call mining backend (litellm / claude / codex)   │
+│  3. Parse <thinking> and <answer> tags               │
+│  4. Submit to server                                 │
+│  5. Server evaluates, returns score + reward         │
+│  6. Update prompt with feedback                      │
+│  7. Repeat until threshold reached or interrupted    │
+│                                                      │
+│  Session auto-saved after each round.                │
+│  Ctrl+C to stop. Run again to resume.                │
+└──────────────────────────────────────────────────────┘
+```
+
+Features during mining:
+- **Live status panel** with current score, pool, earned USDC, token usage, and cost
+- **Community context** -- top submissions from other miners are included in the prompt
+- **Duplicate detection** -- stops after 3 consecutive identical answers
+- **Rate limit handling** -- auto-waits on 429 responses
+- **Command defaults** -- `axon mine` runs 5 rounds with a 10 minute hard timeout per CLI backend call; `axon mine --timeout 180` changes that timeout for the current run; `axon mine --yolo` disables both limits for the current run
+- **Ctrl+O** to toggle detailed round view; arrow keys to browse history
+
+## Supported LLM Providers (litellm backend)
+
+| Provider | Prefix | Example Model |
+|----------|--------|---------------|
+| Anthropic | `anthropic/` | `anthropic/claude-sonnet-4-20250514` |
+| OpenAI | `openai/` | `openai/gpt-4o` |
+| DeepSeek | `deepseek/` | `deepseek/deepseek-chat` |
+| Ollama | `ollama/` | `ollama/llama3` |
+
+API keys are stored in `~/.axon/config.json`. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`) also work.
+
+## Configuration
+
+All config is stored in `~/.axon/`:
+
+| File | Purpose |
+|------|---------|
+| `~/.axon/config.json` | Server URL, backend, default model, API keys |
+| `~/.axon/wallet.json` | Ethereum wallet (private key, address) |
+| `~/.axon/sessions/<task_id>.json` | Mining session state (resume after disconnect) |
+| `~/.axon/history/` | Mining history per task |
+| `~/.axon/logs/` | Debug logs |
+
+Config keys:
+
+| Key | Default |
+|-----|---------|
+| `server_url` | `http://localhost:8000` |
+| `default_model` | `anthropic/claude-sonnet-4-20250514` |
+| `backend` | `auto` |
+| `cli_timeout` | `600` (seconds, for CLI backends; set `0` or `null` to disable the hard timeout) |
+| `claude_cli_model` | *(empty — uses CLI default)* |
+| `codex_cli_model` | *(empty — uses CLI default)* |
+
+## Authentication Flow
+
+The CLI uses wallet-based auth (Ethereum signatures, no passwords):
+
+```
+1. axon onboard         → generates ETH keypair → ~/.axon/wallet.json
+2. GET /api/auth/nonce  → server returns challenge nonce
+3. Sign nonce with private key
+4. POST /api/auth/verify → server returns JWT
+5. All API calls use Authorization: Bearer <JWT>
+```
+
+Authentication is automatic. The CLI re-authenticates transparently when the token expires.
+
+## Project Structure
+
+```
+cli/
+├── axon/
+│   ├── cli.py          Typer app, all commands
+│   ├── config.py       Config load/save (~/.axon/config.json)
+│   ├── wallet.py       ETH wallet generation + signing
+│   ├── api.py          HTTP client (httpx) with auto-auth
+│   ├── llm.py          LLM integration via litellm
+│   ├── mining.py       Mining loop + Rich Live display
+│   ├── session.py      Session persistence (resume mining)
+│   ├── display.py      Rich tables, panels, formatting
+│   ├── providers.py    Model list fetching per provider
+│   ├── history.py      Mining history tracking
+│   ├── log.py          Logging setup
+│   ├── backends/       Mining backend system
+│   │   ├── base.py         Abstract backend interface
+│   │   ├── litellm_backend.py   LiteLLM API backend
+│   │   ├── claude_cli.py        Claude Code CLI backend
+│   │   ├── codex_cli.py         Codex CLI backend
+│   │   └── registry.py          Auto-detection + registration
+├── tests/
+└── pyproject.toml
+```
+
+## Dependencies
+
+- **typer** -- CLI framework
+- **rich** -- Terminal formatting
+- **litellm** -- Unified LLM API
+- **httpx** -- HTTP client
+- **eth-account** -- Wallet generation + signing
+- **simple-term-menu** -- Arrow-key selection menus
+
+## License
+
+MIT

axonwork-0.2.0/axon/api.py

@@ -0,0 +1,83 @@
+"""Backend HTTP client with automatic wallet auth."""
+import httpx
+from axon.config import load_config, get_token, save_config
+
+
+def _ensure_auth():
+    """Auto-authenticate with wallet if no valid token."""
+    transport = httpx.HTTPTransport(proxy=None)
+
+    token = get_token()
+    if token:
+        config = load_config()
+        try:
+            with httpx.Client(base_url=config["server_url"], timeout=5, transport=transport) as c:
+                resp = c.get("/api/auth/me", headers={"Authorization": f"Bearer {token}"})
+            if resp.status_code == 200:
+                return  # Token still valid
+        except httpx.ConnectError:
+            raise
+        except Exception:
+            pass  # Token expired or invalid, try re-auth below
+
+    # Token missing or expired — re-auth with wallet
+    from axon.wallet import load_wallet, sign_message
+    wallet = load_wallet()
+    if not wallet:
+        return
+
+    config = load_config()
+    with httpx.Client(base_url=config["server_url"], timeout=10, transport=transport) as c:
+        # Get nonce
+        resp = c.get(f"/api/auth/nonce?address={wallet['address']}")
+        if resp.status_code != 200:
+            return
+        nonce_data = resp.json()
+
+        # Sign
+        signature = sign_message(nonce_data["message"], wallet["private_key"])
+
+        # Verify
+        resp = c.post("/api/auth/verify", json={
+            "address": wallet["address"],
+            "signature": signature,
+        })
+        if resp.status_code == 200:
+            save_config({"auth_token": resp.json()["access_token"]})
+
+
+def _client(auth: bool = True, timeout: int = 120) -> httpx.Client:
+    if auth:
+        _ensure_auth()
+    config = load_config()
+    headers = {"Content-Type": "application/json"}
+    token = get_token()
+    if auth and token:
+        headers["Authorization"] = f"Bearer {token}"
+    return httpx.Client(
+        base_url=config["server_url"],
+        headers=headers,
+        timeout=timeout,
+        transport=httpx.HTTPTransport(proxy=None),
+    )
+
+
+def api_get(path: str, auth: bool = True) -> dict | list:
+    with _client(auth=auth) as c:
+        resp = c.get(path)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def api_post(path: str, body: dict, auth: bool = True) -> dict:
+    with _client(auth=auth) as c:
+        resp = c.post(path, json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def api_patch(path: str, body: dict | None = None, auth: bool = True) -> dict:
+    with _client(auth=auth) as c:
+        resp = c.patch(path, json=body) if body else c.patch(path)
+        resp.raise_for_status()
+        return resp.json()

axonwork-0.2.0/axon/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Axon mining backends — litellm, claude-cli, codex-cli."""
+from axon.backends.base import Backend, BackendResult
+from axon.backends.registry import auto_detect_backend, create_backend
+
+__all__ = ["Backend", "BackendResult", "auto_detect_backend", "create_backend"]

axonwork-0.2.0/axon/backends/base.py

@@ -0,0 +1,23 @@
+"""Backend protocol and result type for mining LLM calls."""
+from __future__ import annotations
+
+from typing import Protocol, TypedDict, runtime_checkable
+
+
+class BackendResult(TypedDict):
+    thinking: str
+    answer: str
+    usage: dict  # {billing_mode, tokens, cost_usd, total_tokens, prompt_tokens, completion_tokens, cost}
+
+
+@runtime_checkable
+class Backend(Protocol):
+    name: str
+
+    def call(self, prompt: str, task: dict) -> BackendResult:
+        """Call the backend with a prompt and task context. Returns structured result."""
+        ...
+
+    def display_name(self) -> str:
+        """Human-readable name for display in status lines."""
+        ...

axonwork-0.2.0/axon/backends/claude_cli.py

@@ -0,0 +1,290 @@
+"""Claude Code CLI backend — runs `claude -p` as subprocess."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shlex
+import signal
+import subprocess
+import time
+from datetime import datetime
+
+from axon.backends.base import BackendResult
+from axon.backends.registry import register
+from axon.config import resolve_cli_timeout
+
+log = logging.getLogger("axon.backend.claude")
+_STREAM_SAMPLE_LIMIT = 20
+_STREAM_SAMPLE_BYTES = 240
+_SUBSCRIPTION_USAGE = {
+    "billing_mode": "subscription",
+    "tokens": None,
+    "cost_usd": None,
+    "total_tokens": None,
+    "prompt_tokens": None,
+    "completion_tokens": None,
+    "cost": None,
+}
+
+
+def _now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def _normalize_output(output: str | bytes | None) -> str:
+    if output is None:
+        return ""
+    if isinstance(output, bytes):
+        return output.decode("utf-8", errors="replace")
+    return output
+
+
+def _log_output_sample(stream_name: str, output: str):
+    if not output:
+        return
+    lines = output.splitlines()
+    for line_count, line in enumerate(lines[:_STREAM_SAMPLE_LIMIT], start=1):
+        log.info("Claude CLI %s[%d]: %s", stream_name, line_count, line[:_STREAM_SAMPLE_BYTES])
+    if len(lines) > _STREAM_SAMPLE_LIMIT:
+        log.info("Claude CLI %s: further output truncated after %d lines", stream_name, _STREAM_SAMPLE_LIMIT)
+
+# Tool sets by eval_type
+_TOOLS_BY_EVAL_TYPE = {
+    "code_output": "Bash,Read,Write,Grep,Glob",
+    "llm_judge": "Read,WebSearch,WebFetch,Grep,Glob",
+}
+_DEFAULT_TOOLS = "Read,WebSearch,Grep,Glob"
+
+# System prompts include output format instructions (no --json-schema, which
+# conflicts with agentic multi-turn tool use and can cause infinite retries).
+_SYSTEM_PROMPTS = {
+    "code_output": (
+        "You are solving a coding task. Write executable code that produces the correct output. "
+        "Use Bash to test your code before submitting your final answer. "
+        "Iterate until tests pass.\n\n"
+        "YOUR FINAL MESSAGE must contain ONLY raw executable Python code.\n"
+        "Do NOT wrap it in <answer> tags. Do NOT use markdown fences. Do NOT add explanation.\n"
+        "The evaluator writes your submission directly to solution.py and executes it."
+    ),
+    "llm_judge": (
+        "You are solving a research/reasoning task. Use WebSearch and WebFetch to find "
+        "accurate information. Verify facts before submitting. "
+        "Provide a thorough, well-reasoned answer in your final message."
+    ),
+}
+_DEFAULT_SYSTEM = (
+    "You are solving a task. Use available tools to research and verify your answer. "
+    "Be thorough and accurate. Put your final answer in your last message."
+)
+
+
+@register("claude-cli")
+class ClaudeCLIBackend:
+    name = "claude-cli"
+
+    def __init__(self, config: dict):
+        self._timeout = resolve_cli_timeout(config)
+        self._model = config.get("claude_cli_model", "")
+
+    def call(self, prompt: str, task: dict) -> BackendResult:
+        eval_type = task.get("eval_type", "")
+        tools = _TOOLS_BY_EVAL_TYPE.get(eval_type, _DEFAULT_TOOLS)
+        system_prompt = _SYSTEM_PROMPTS.get(eval_type, _DEFAULT_SYSTEM)
+
+        # Prompt is passed via stdin (no positional arg) to avoid OS arg-length limits.
+        # No --json-schema: it conflicts with agentic tool-use and causes hangs.
+        cmd = [
+            "claude", "-p",
+            "--output-format", "json",
+            "--allowedTools", tools,
+            "--system-prompt", system_prompt,
+            "--dangerously-skip-permissions",
+        ]
+        if self._model:
+            cmd.extend(["--model", self._model])
+
+        started_at = _now_iso()
+        started_mono = time.monotonic()
+        timeout_label = "none" if self._timeout is None else f"{self._timeout}s"
+        log.info(
+            "Claude CLI start started_at=%s eval_type=%s tools=%s timeout=%s prompt_chars=%d cmd=%s",
+            started_at,
+            eval_type,
+            tools,
+            timeout_label,
+            len(prompt),
+            shlex.join(cmd),
+        )
+
+        # Clear env vars that make Claude CLI refuse to run inside another session
+        _blocked_env = {"CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"}
+        env = {k: v for k, v in os.environ.items() if k not in _blocked_env}
+
+        # start_new_session creates a process group so we can kill all children
+        proc = subprocess.Popen(
+            cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, start_new_session=True, env=env,
+        )
+        try:
+            stdout, stderr = proc.communicate(input=prompt, timeout=self._timeout)
+        except subprocess.TimeoutExpired as exc:
+            stdout = _normalize_output(exc.stdout)
+            stderr = _normalize_output(exc.stderr)
+            _kill_process_group(proc)
+            _log_output_sample("stdout", stdout)
+            _log_output_sample("stderr", stderr)
+            log.error(
+                "Claude CLI timeout started_at=%s finished_at=%s duration_s=%.2f cmd=%s",
+                started_at,
+                _now_iso(),
+                time.monotonic() - started_mono,
+                shlex.join(cmd),
+            )
+            raise TimeoutError(f"Claude CLI timed out after {self._timeout}s") from None
+
+        _log_output_sample("stdout", stdout)
+        _log_output_sample("stderr", stderr)
+        if proc.returncode != 0:
+            log.error(
+                "Claude CLI failed started_at=%s finished_at=%s duration_s=%.2f returncode=%s cmd=%s stderr=%s",
+                started_at,
+                _now_iso(),
+                time.monotonic() - started_mono,
+                proc.returncode,
+                shlex.join(cmd),
+                stderr[:1000],
+            )
+            raise RuntimeError(f"Claude CLI exited with code {proc.returncode}: {stderr[:500]}")
+
+        if stderr:
+            log.debug("Claude CLI stderr: %s", stderr[:500])
+
+        log.info(
+            "Claude CLI finished started_at=%s finished_at=%s duration_s=%.2f returncode=%s stdout_chars=%d stderr_chars=%d",
+            started_at,
+            _now_iso(),
+            time.monotonic() - started_mono,
+            proc.returncode,
+            len(stdout),
+            len(stderr),
+        )
+
+        return _parse_response(stdout)
+
+    def display_name(self) -> str:
+        return f"claude-cli{f' ({self._model})' if self._model else ''}"
+
+
+def _kill_process_group(proc: subprocess.Popen):
+    """Kill the process and its entire process group."""
+    try:
+        pgid = os.getpgid(proc.pid)
+        os.killpg(pgid, signal.SIGTERM)
+    except (ProcessLookupError, OSError):
+        try:
+            proc.kill()
+        except OSError:
+            pass
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        try:
+            pgid = os.getpgid(proc.pid)
+            os.killpg(pgid, signal.SIGKILL)
+        except (ProcessLookupError, OSError):
+            try:
+                proc.kill()
+            except OSError:
+                pass
+        try:
+            proc.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            log.warning("Process %d did not exit after SIGKILL", proc.pid)
+
+
+def _parse_response(stdout: str) -> BackendResult:
+    """Parse Claude CLI JSON output.
+
+    `claude -p --output-format json` returns a single JSON object:
+      {type: "result", result: "...", total_cost_usd: ..., usage: {...}}
+    """
+    stdout = stdout.strip()
+    if not stdout:
+        raise RuntimeError("Claude CLI returned empty output")
+
+    data = json.loads(stdout)
+
+    # Extract the result text and usage from the response envelope
+    if isinstance(data, dict) and data.get("type") == "result":
+        content = data.get("result", "")
+        usage = _extract_usage(data)
+    elif isinstance(data, list):
+        # Fallback: older array format [{type:"system",...}, {type:"result",...}]
+        result_block = None
+        for block in data:
+            if isinstance(block, dict) and block.get("type") == "result":
+                result_block = block
+                break
+        if result_block is None:
+            raise RuntimeError("No result block found in Claude CLI output")
+        content = result_block.get("result", "")
+        usage = _extract_usage(result_block)
+    elif isinstance(data, dict):
+        # Direct dict with thinking/answer keys
+        return BackendResult(
+            thinking=data.get("thinking", ""),
+            answer=data.get("answer", str(data)),
+            usage=dict(_SUBSCRIPTION_USAGE),
+        )
+    else:
+        raise RuntimeError(f"Unexpected Claude CLI output type: {type(data)}")
+
+    return _extract_answer(content, usage)
+
+
+def _extract_usage(envelope: dict) -> dict:
+    """Return subscription usage — Claude CLI is subscription-based, not metered."""
+    return dict(_SUBSCRIPTION_USAGE)
+
+
+def _extract_answer(content, usage: dict) -> BackendResult:
+    """Parse the result field into thinking + answer."""
+    # If content is already a dict, extract fields
+    if isinstance(content, dict):
+        return BackendResult(
+            thinking=content.get("thinking", ""),
+            answer=content.get("answer", str(content)),
+            usage=usage,
+        )
+
+    text = str(content).strip()
+
+    # Try 1: Parse as JSON object with thinking/answer
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict) and "answer" in parsed:
+            return BackendResult(
+                thinking=parsed.get("thinking", ""),
+                answer=parsed["answer"],
+                usage=usage,
+            )
+    except (json.JSONDecodeError, TypeError):
+        pass
+
+    # Try 2: Extract <thinking> and <answer> XML tags
+    think_match = re.search(r"<thinking>(.*?)</thinking>", text, re.DOTALL)
+    answer_match = re.search(r"<answer>(.*?)</answer>", text, re.DOTALL)
+    if answer_match:
+        return BackendResult(
+            thinking=think_match.group(1).strip() if think_match else "",
+            answer=answer_match.group(1).strip(),
+            usage=usage,
+        )
+
+    # Try 3: Strip markdown fences (common in code responses)
+    cleaned = re.sub(r"^```[\w]*\s*\n?", "", text)
+    cleaned = re.sub(r"\n?\s*```\s*$", "", cleaned)
+
+    return BackendResult(thinking="", answer=cleaned.strip(), usage=usage)