penpal-cli 0.1.0__tar.gz

penpal_cli-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: penpal-cli
+Version: 0.1.0
+Summary: Async Claude CLI via Batch API — half the cost, none of the rush.
+Author: JNalv
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JNalv/penpal-cli
+Project-URL: Repository, https://github.com/JNalv/penpal-cli
+Project-URL: Issues, https://github.com/JNalv/penpal-cli/issues
+Keywords: claude,anthropic,batch-api,cli,llm,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.89.0
+Requires-Dist: click>=8.3.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: textual>=8.2.0
+Requires-Dist: rich>=14.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+
+# penpal
+
+Async Claude via the Batch API. Half the cost, none of the rush.
+
+Penpal is a CLI for sending prompts to Claude through Anthropic's [Batch API](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing), which processes requests asynchronously at **50% off**. Submit a prompt, go do something else, come back and read the response.
+
+## Install
+
+```bash
+pipx install penpal-cli
+```
+
+Or with pip:
+
+```bash
+pip install penpal-cli
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+# 1. Store your API key (one-time setup)
+penpal auth
+
+# 2. Submit a prompt
+penpal ask "Explain the CAP theorem in plain English"
+
+# 3. Check if it's done
+penpal status
+
+# 4. Read the response
+penpal read --latest
+```
+
+Batch requests typically complete in minutes. Use `penpal status --watch` to auto-refresh.
+
+## Features
+
+### Model aliases
+
+Use short names instead of full model identifiers:
+
+| Alias    | Model                          |
+|----------|--------------------------------|
+| `haiku`  | `claude-haiku-4-5-20251001`    |
+| `sonnet` | `claude-sonnet-4-20250514`     |
+| `opus`   | `claude-opus-4-20250514`       |
+
+```bash
+penpal ask -m haiku "Quick question"
+```
+
+### File attachments
+
+Attach images, PDFs, and text files directly:
+
+```bash
+penpal ask -f screenshot.png "What's in this image?"
+penpal ask -f paper.pdf "Summarize this paper"
+penpal ask -f main.py -f utils.py "Review these files"
+```
+
+### Batch mode
+
+Process an entire directory of files in a single batch:
+
+```bash
+penpal ask -b ./documents/ "Summarize this document"
+```
+
+Each file becomes a separate request. Use `penpal read <id> -i <N>` to read individual results.
+
+### Skills (reusable system prompts)
+
+Create and reuse system prompts as named skills:
+
+```bash
+penpal skills add code-review    # Opens $EDITOR
+penpal ask --skill code-review -f app.py "Review this"
+penpal skills                    # List all skills
+```
+
+### Code extraction
+
+Extract fenced code blocks from responses directly to files:
+
+```bash
+penpal read --latest --extract
+```
+
+### TUI dashboard
+
+Launch an interactive terminal dashboard with live status updates, cost tracking, manual request creation, and more:
+
+```bash
+penpal session
+```
+
+### History and cost tracking
+
+```bash
+penpal history                   # Browse past requests
+penpal history --cost            # See spending summary
+penpal history --since 7d        # Filter by time
+penpal history --search "CAP"    # Search prompts
+```
+
+### Raw output for piping
+
+`--raw` strips all formatting, ideal for piping into other tools or feeding back to an AI coding agent:
+
+```bash
+penpal read --latest --raw | pbcopy
+penpal read --latest --raw > response.md
+```
+
+## Claude Code integration
+
+Teach [Claude Code](https://docs.anthropic.com/en/docs/claude-code) about penpal so it can use cheaper batch requests:
+
+```bash
+penpal setup-claude-code
+```
+
+This appends a small instruction block to `~/.claude/CLAUDE.md`. Remove it with `penpal uninstall-claude-code`.
+
+### AGENTS.md (cross-agent standard)
+
+For projects using multiple AI coding agents (Copilot, Cursor, OpenCode, Codex, etc.), add penpal instructions to the [AGENTS.md](https://github.com/anthropics/agents-md) standard:
+
+```bash
+penpal setup-agents-md
+```
+
+This writes to `./AGENTS.md` in the current directory. Remove it with `penpal uninstall-agents-md`.
+
+## Configuration
+
+Penpal uses XDG directories. Config file location:
+
+```bash
+penpal config --path   # ~/.config/penpal/config.toml
+penpal config --edit   # Open in $EDITOR
+penpal config          # Show resolved settings
+```
+
+Example `config.toml`:
+
+```toml
+model = "sonnet"
+max_tokens = 4096
+poll_interval = 180
+preview_lines = 40
+```
+
+### Environment variables
+
+| Variable             | Description                      |
+|----------------------|----------------------------------|
+| `ANTHROPIC_API_KEY`  | API key (overrides stored key)   |
+| `PENPAL_MODEL`       | Default model                    |
+| `PENPAL_MAX_TOKENS`  | Default max output tokens        |
+| `PENPAL_POLL_INTERVAL` | Status polling interval (seconds) |
+
+## License
+
+MIT

penpal_cli-0.1.0/README.md

@@ -0,0 +1,169 @@
+# penpal
+
+Async Claude via the Batch API. Half the cost, none of the rush.
+
+Penpal is a CLI for sending prompts to Claude through Anthropic's [Batch API](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing), which processes requests asynchronously at **50% off**. Submit a prompt, go do something else, come back and read the response.
+
+## Install
+
+```bash
+pipx install penpal-cli
+```
+
+Or with pip:
+
+```bash
+pip install penpal-cli
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+# 1. Store your API key (one-time setup)
+penpal auth
+
+# 2. Submit a prompt
+penpal ask "Explain the CAP theorem in plain English"
+
+# 3. Check if it's done
+penpal status
+
+# 4. Read the response
+penpal read --latest
+```
+
+Batch requests typically complete in minutes. Use `penpal status --watch` to auto-refresh.
+
+## Features
+
+### Model aliases
+
+Use short names instead of full model identifiers:
+
+| Alias    | Model                          |
+|----------|--------------------------------|
+| `haiku`  | `claude-haiku-4-5-20251001`    |
+| `sonnet` | `claude-sonnet-4-20250514`     |
+| `opus`   | `claude-opus-4-20250514`       |
+
+```bash
+penpal ask -m haiku "Quick question"
+```
+
+### File attachments
+
+Attach images, PDFs, and text files directly:
+
+```bash
+penpal ask -f screenshot.png "What's in this image?"
+penpal ask -f paper.pdf "Summarize this paper"
+penpal ask -f main.py -f utils.py "Review these files"
+```
+
+### Batch mode
+
+Process an entire directory of files in a single batch:
+
+```bash
+penpal ask -b ./documents/ "Summarize this document"
+```
+
+Each file becomes a separate request. Use `penpal read <id> -i <N>` to read individual results.
+
+### Skills (reusable system prompts)
+
+Create and reuse system prompts as named skills:
+
+```bash
+penpal skills add code-review    # Opens $EDITOR
+penpal ask --skill code-review -f app.py "Review this"
+penpal skills                    # List all skills
+```
+
+### Code extraction
+
+Extract fenced code blocks from responses directly to files:
+
+```bash
+penpal read --latest --extract
+```
+
+### TUI dashboard
+
+Launch an interactive terminal dashboard with live status updates, cost tracking, manual request creation, and more:
+
+```bash
+penpal session
+```
+
+### History and cost tracking
+
+```bash
+penpal history                   # Browse past requests
+penpal history --cost            # See spending summary
+penpal history --since 7d        # Filter by time
+penpal history --search "CAP"    # Search prompts
+```
+
+### Raw output for piping
+
+`--raw` strips all formatting, ideal for piping into other tools or feeding back to an AI coding agent:
+
+```bash
+penpal read --latest --raw | pbcopy
+penpal read --latest --raw > response.md
+```
+
+## Claude Code integration
+
+Teach [Claude Code](https://docs.anthropic.com/en/docs/claude-code) about penpal so it can use cheaper batch requests:
+
+```bash
+penpal setup-claude-code
+```
+
+This appends a small instruction block to `~/.claude/CLAUDE.md`. Remove it with `penpal uninstall-claude-code`.
+
+### AGENTS.md (cross-agent standard)
+
+For projects using multiple AI coding agents (Copilot, Cursor, OpenCode, Codex, etc.), add penpal instructions to the [AGENTS.md](https://github.com/anthropics/agents-md) standard:
+
+```bash
+penpal setup-agents-md
+```
+
+This writes to `./AGENTS.md` in the current directory. Remove it with `penpal uninstall-agents-md`.
+
+## Configuration
+
+Penpal uses XDG directories. Config file location:
+
+```bash
+penpal config --path   # ~/.config/penpal/config.toml
+penpal config --edit   # Open in $EDITOR
+penpal config          # Show resolved settings
+```
+
+Example `config.toml`:
+
+```toml
+model = "sonnet"
+max_tokens = 4096
+poll_interval = 180
+preview_lines = 40
+```
+
+### Environment variables
+
+| Variable             | Description                      |
+|----------------------|----------------------------------|
+| `ANTHROPIC_API_KEY`  | API key (overrides stored key)   |
+| `PENPAL_MODEL`       | Default model                    |
+| `PENPAL_MAX_TOKENS`  | Default max output tokens        |
+| `PENPAL_POLL_INTERVAL` | Status polling interval (seconds) |
+
+## License
+
+MIT

penpal_cli-0.1.0/penpal/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

penpal_cli-0.1.0/penpal/auth.py

@@ -0,0 +1,118 @@
+"""API key storage and retrieval via keyring with file fallback."""
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+import keyring
+import keyring.errors
+
+from penpal.config import credentials_file
+
+KEYRING_SERVICE = "penpal"
+KEYRING_USERNAME = "anthropic_api_key"
+
+
+class AuthError(Exception):
+    pass
+
+
+def _file_creds_path() -> Path:
+    return credentials_file()
+
+
+def _store_in_file(key: str) -> None:
+    path = _file_creds_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(key)
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def _read_from_file() -> str | None:
+    path = _file_creds_path()
+    if path.exists():
+        return path.read_text().strip() or None
+    return None
+
+
+def store_api_key(key: str) -> str:
+    """Store the API key. Returns 'keyring' or 'file' indicating storage method."""
+    try:
+        keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, key)
+        return "keyring"
+    except (keyring.errors.NoKeyringError, Exception):
+        _store_in_file(key)
+        return "file"
+
+
+def get_api_key() -> str:
+    """Retrieve stored API key. Raises AuthError if not configured."""
+    # Env var takes precedence
+    key = os.environ.get("ANTHROPIC_API_KEY")
+    if key:
+        return key
+
+    # Try keyring
+    try:
+        key = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
+        if key:
+            return key
+    except (keyring.errors.NoKeyringError, Exception):
+        pass
+
+    # Try file fallback
+    key = _read_from_file()
+    if key:
+        return key
+
+    raise AuthError(
+        "No API key configured. Run `penpal auth` or set ANTHROPIC_API_KEY."
+    )
+
+
+def delete_api_key() -> bool:
+    """Remove the stored API key. Returns True if something was deleted."""
+    deleted = False
+    try:
+        existing = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
+        if existing:
+            keyring.delete_password(KEYRING_SERVICE, KEYRING_USERNAME)
+            deleted = True
+    except (keyring.errors.NoKeyringError, Exception):
+        pass
+
+    path = _file_creds_path()
+    if path.exists():
+        path.unlink()
+        deleted = True
+
+    return deleted
+
+
+def get_key_status() -> dict:
+    """Return info about the stored key without revealing it."""
+    env_key = os.environ.get("ANTHROPIC_API_KEY")
+
+    keyring_key = None
+    try:
+        keyring_key = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
+    except (keyring.errors.NoKeyringError, Exception):
+        pass
+
+    file_key = _read_from_file()
+
+    active_key = env_key or keyring_key or file_key
+
+    def mask(k: str | None) -> str:
+        if not k:
+            return "(not set)"
+        return k[:12] + "..." + k[-4:]
+
+    return {
+        "env_var": mask(env_key) if env_key else "(not set)",
+        "keyring": mask(keyring_key) if keyring_key else "(not set)",
+        "file": mask(file_key) if file_key else "(not set)",
+        "active": mask(active_key) if active_key else "(not set)",
+        "source": "env" if env_key else ("keyring" if keyring_key else ("file" if file_key else "none")),
+    }

penpal_cli-0.1.0/penpal/builder.py

@@ -0,0 +1,166 @@
+"""Constructs Messages API payloads from CLI inputs."""
+from __future__ import annotations
+
+import base64
+import mimetypes
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from penpal.config import MODEL_ALIASES
+
+# Supported file types
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
+PDF_EXTENSIONS = {".pdf"}
+TEXT_EXTENSIONS = {
+    ".txt", ".csv", ".tsv", ".md", ".html", ".json", ".xml",
+    ".yaml", ".yml", ".py", ".js", ".ts", ".java", ".c", ".cpp",
+    ".rs", ".go", ".rb", ".sh", ".sql", ".r", ".swift", ".kt",
+    ".log", ".rtf",
+}
+
+MAX_IMAGE_SIZE = 5 * 1024 * 1024   # 5 MB
+MAX_PDF_SIZE = 32 * 1024 * 1024    # 32 MB
+MAX_TEXT_SIZE = 512 * 1024          # 512 KB
+
+
+def resolve_model(name: str) -> str:
+    """Resolve alias to full model string. Pass through if already full."""
+    return MODEL_ALIASES.get(name.lower(), name)
+
+
+def build_file_content_block(file_path: Path) -> tuple[str | None, dict]:
+    """
+    Build a content block for the given file.
+    Returns (text_prefix, content_block) where text_prefix is non-None only for
+    text files (to be prepended to the user prompt string).
+    Raises ValueError for unsupported or oversized files.
+    """
+    suffix = file_path.suffix.lower()
+
+    if suffix in IMAGE_EXTENSIONS:
+        data = file_path.read_bytes()
+        if len(data) > MAX_IMAGE_SIZE:
+            raise ValueError(
+                f"Image '{file_path.name}' is {len(data) / 1024 / 1024:.1f} MB "
+                f"(max 5 MB)."
+            )
+        media_type, _ = mimetypes.guess_type(str(file_path))
+        if not media_type:
+            media_type = "image/jpeg"
+        encoded = base64.standard_b64encode(data).decode()
+        return (None, {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": media_type,
+                "data": encoded,
+            },
+        })
+
+    elif suffix in PDF_EXTENSIONS:
+        data = file_path.read_bytes()
+        if len(data) > MAX_PDF_SIZE:
+            raise ValueError(
+                f"PDF '{file_path.name}' is {len(data) / 1024 / 1024:.1f} MB "
+                f"(max 32 MB)."
+            )
+        encoded = base64.standard_b64encode(data).decode()
+        return (None, {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": "application/pdf",
+                "data": encoded,
+            },
+            "title": file_path.name,
+        })
+
+    elif suffix in TEXT_EXTENSIONS:
+        data = file_path.read_bytes()
+        if len(data) > MAX_TEXT_SIZE:
+            raise ValueError(
+                f"Text file '{file_path.name}' is {len(data) / 1024:.1f} KB "
+                f"(max 512 KB)."
+            )
+        text = data.decode("utf-8", errors="replace")
+        size_str = f"{len(data) / 1024:.1f} KB"
+        prefix = (
+            f"--- Attached file: {file_path.name} ({size_str}) ---\n"
+            f"{text}\n"
+            f"--- End of attachment ---\n\n"
+        )
+        return (prefix, {})  # Empty dict signals text file (no block needed)
+
+    else:
+        supported = sorted(IMAGE_EXTENSIONS | PDF_EXTENSIONS | TEXT_EXTENSIONS)
+        raise ValueError(
+            f"Unsupported file type '{suffix}'. Supported: {', '.join(supported)}"
+        )
+
+
+def build_batch_requests(
+    template_prompt: str,
+    files: list[Path],
+    model: str,
+    max_tokens: int,
+    system_prompt: Optional[str] = None,
+) -> list[dict]:
+    """Build one batch request per file, applying template_prompt to each."""
+    requests = []
+    for fp in files:
+        requests.append(
+            build_single_request(
+                prompt=template_prompt,
+                model=model,
+                max_tokens=max_tokens,
+                system_prompt=system_prompt,
+                custom_id=fp.name,
+                files=[fp],
+            )
+        )
+    return requests
+
+
+def build_single_request(
+    prompt: str,
+    model: str,
+    max_tokens: int,
+    system_prompt: Optional[str] = None,
+    custom_id: Optional[str] = None,
+    files: Optional[list[Path]] = None,
+) -> dict:
+    """Build a single batch request object."""
+    if custom_id is None:
+        custom_id = f"req-{uuid.uuid4().hex[:8]}"
+
+    # Build content blocks
+    content: list[dict] | str
+    text_prefixes: list[str] = []
+    content_blocks: list[dict] = []
+
+    for fp in (files or []):
+        text_prefix, block = build_file_content_block(fp)
+        if text_prefix is not None:
+            text_prefixes.append(text_prefix)
+        else:
+            content_blocks.append(block)
+
+    full_prompt = "".join(text_prefixes) + prompt
+
+    if content_blocks:
+        # Mixed content: blocks first, then the text prompt
+        content_blocks.append({"type": "text", "text": full_prompt})
+        content = content_blocks
+    else:
+        content = full_prompt
+
+    params: dict = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [{"role": "user", "content": content}],
+    }
+    if system_prompt:
+        params["system"] = system_prompt
+
+    return {"custom_id": custom_id, "params": params}