alleycat 0.5.0

A command line tool for chat conversations with LLMs

AlleyCat - A command line tool for AI text processing

Alleycat is a command-line text processing utility that transforms input text using Large Language Models (LLMs). Like traditional Unix tools such as awk or sed, alleycat reads from standard input or command arguments and writes transformed text to standard output. Instead of using pattern matching or scripted transformations, alleycat leverages AI to interpret and modify text based on natural language instructions.

For comprehensive documentation, see Alleycat Guide.

Warning: This is primarily a test project for my working with AI tools. As such it is probably not suitable for production use.

There are other cool tools available:

• openai - if you install the sdk there is a command line which allows API calls to be made. This is works and is definitive but not very friendly.
• claude code - lots of features and integration with the terminal and machine, can be used as a pipe or interactively. But its main purpose is a coding assistant.
• warp terminal - not a cli an entire terminal with AI built in - great for asking for what you want.

Project Structure

The project follows a modern Python package structure with a src layout:

alleycat/
├── src/
│   ├── alleycat_apps/      # Application code
│   │   └── cli/           # CLI interface
│   └── alleycat_core/     # Core functionality
├── tests/                 # Test files
├── pyproject.toml         # Project configuration
└── setup.py              # Development installation

Package Organization

• alleycat_apps: Contains application-specific code
  • cli: Command-line interface implementation
• alleycat_core: Core functionality and business logic
  • config: Configuration management
  • llm: LLM integration and API handling

Installation

AlleyCat can be installed in several ways depending on your needs:

From PyPI (Recommended)

Install using pip with UV:

uv pip install alleycat

Or using pipx for isolated CLI tool installation (recommended for command-line tools):

pipx install alleycat

From Source

Install directly from the GitHub repository:

uv pip install git+https://github.com/avowkind/alleycat.git

Local Installation

If you've cloned the repository or downloaded the source:

cd alleycat
uv pip install .

After installation, you can run AlleyCat from anywhere with:

alleycat --help

Development Setup

This project uses uv as the package manager for faster and more reliable Python package management.

Prerequisites

• Python 3.12 or higher
• uv package manager

Installation

1. Clone the repository:

   git clone <repository-url>
   cd alleycat
   

2. Create and activate a virtual environment with uv:

   uv venv
   source .venv/bin/activate  # On Unix/macOS
   # or
   .venv\Scripts\activate     # On Windows
   

3. Install the package in development mode:

   uv pip install -e .
   

4. Install development dependencies:

   uv pip install -e ".[dev]"
   

Usage

After installation, you can run AlleyCat directly from the command line:

# Show help
alleycat --help

# Basic usage
alleycat "Your prompt here"

# With options
alleycat --mode markdown --temperature 0.7 "Your prompt here"

Note for developers: When working on the codebase, you can use uv run alleycat during development to ensure the correct Python environment is used. or use make activate to setup the virtual environment (venv) and then run any of the make functions.

First-time Setup

When you run AlleyCat for the first time (or if no configuration file is found), you'll automatically be guided through an interactive setup process that will:

1. Create necessary configuration directories following XDG standards
2. Prompt for your OpenAI API key
3. Let you select your preferred default model
4. Configure other settings like temperature and web search defaults

You can revisit this setup at any time using:

# Run the setup wizard from the separate command
alleycat-init

# Or use the --init flag with the main command
alleycat --init

To remove all AlleyCat configuration files:

# Remove config using the dedicated command
alleycat-init --remove

# Or with the main command
alleycat --remove-config

Command Line Options

# Basic usage
alleycat "Your prompt here"
# note prompte does not need to be quoted
alleycat what is a cat

# Pipe input
echo "Your prompt" | alleycat

# With formatting options
alleycat --mode markdown --temperature 1.7 "invent a creative list of 2050 era programming languages"

# Using system instructions
alleycat -i "You are a helpful assistant" "Your prompt here"
alleycat -i prompts/custom-style.txt "Your prompt here"

# Initialize or reconfigure settings
alleycat --init

# Remove configuration and data files
alleycat --remove-config

# Analyze a file
alleycat -f docs/alleyfacts.pdf "Summarize this document"
# Note: Currently only PDF files are supported

# Use web search tool
alleycat --tool web "What is the latest news about Python?"
# Or use the simpler alias
alleycat --web "What is the latest news about Python?"
alleycat -w "What one new thing I should know about Python"

# Use file search with vector store
alleycat --tool file-search --vector-store alleycat_kb "Find information about neural networks"
# Or use the simpler aliases
alleycat --knowledge --vector-store alleycat_kb "Find information about neural networks"
alleycat -k --vector-store alleycat_kb "Find information about neural networks"

# Interactive chat mode
alleycat --chat "Hello, how are you today?"
# or start with no initial prompt
alleycat --chat
# or talk to dr johnson
alleycat --chat -i prompts/johnson.txt

Available options:

• --model: Choose LLM model (default: gpt-4o-mini, env: ALLEYCAT_MODEL)
• --temperature, -t: Sampling temperature 0.0-2.0 (default: 0.7)
• --mode, -m: Output format - text, markdown, or json (default: text)
• --file, -f: Upload and reference a PDF file in your conversation (currently only PDF format is supported)
• --tool: Enable specific tools (available: web, file-search)
• --web, -w: Enable web search (alias for --tool web)
• --knowledge, -k: Enable file search (alias for --tool file-search)
• --vector-store: Vector store ID for file search tool (env: ALLEYCAT_VECTOR_STORE)
• --api-key: OpenAI API key (env: ALLEYCAT_OPENAI_API_KEY)
• --instructions, -i: System instructions (string or file path)
• --verbose, -v: Enable verbose debug output
• --stream, -s: Stream the response as it's generated
• --chat, -c: Enter interactive chat mode with continuous conversation
• --init: Run the configuration wizard to set up or update settings
• --remove-config: Remove AlleyCat configuration and data files

Environment variables:

• ALLEYCAT_MODEL: Default model to use
• ALLEYCAT_OPENAI_API_KEY: OpenAI API key
• ALLEYCAT_TEMPERATURE: Default temperature setting
• ALLEYCAT_VECTOR_STORE: Default vector store ID for file search tool

Package Management

The project uses setuptools for package management, configured in pyproject.toml:

[build-system]
requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
package-dir = {"" = "src"}
packages = ["alleycat_apps", "alleycat_core"]

This configuration:

• Uses the src layout for better package isolation
• Explicitly declares packages to include
• Supports development installation with pip install -e .

Development Tools

• Testing: pytest with async support

  uv run pytest
  

• Linting: ruff

  uv run ruff check .
  

• Type Checking: mypy

  uv run mypy src
  

Continuous Integration and Deployment

AlleyCat uses GitHub Actions for automated testing and deployment:

CI Workflow

A CI workflow runs on all pull requests and pushes to the main branch:

• Runs tests on Python 3.12
• Lints code with Ruff
• Type checks with mypy
• Verifies the package builds correctly

Release Process

AlleyCat uses semantic versioning with a 2-step manual-bump and automated-release process:

1. Manual Version Bump (before creating PR):

   • Run make bump-version to increment patch version (default)
   • Or specify version type: make bump-version BUMP=minor
   • Commit the version change with your other changes
   • Create a PR to main

2. Automated Release (after PR is merged):

   • When the PR is merged, a GitHub Action:
     • Reads the current version from pyproject.toml
     • Creates a Git tag for the version
     • Builds and publishes the package to PyPI
     • Creates a GitHub release with release notes

This approach ensures compliance with branch protection rules while maintaining a streamlined release process.

License

MIT License - see LICENSE file for details.

Why "Alleycat"?

The name "Alleycat" draws inspiration from Unix tradition and the tool's nature:

• Like the classic Unix tools cat and tac, it processes text through standard I/O
• Like an alley cat, it's agile and adaptable, transforming text in various ways
• It prowls through your text, hunting for meaning and responding with feline grace

Future Features - Coming Soon (perhaps)

• Support for multiple LLM providers beyond OpenAI
• Chat history management with local storage
• Custom prompt templates
• Streaming responses
• Context window management
• Model parameter presets
• Command completion for shells