Metadata-Version: 2.4
Name: alleycat
Version: 0.5.0
Summary: A command line tool for chat conversations with LLMs
Author-email: Andrew <andrew@groat.nz>
License: MIT
Project-URL: Homepage, https://github.com/avowkind/alleycat
Project-URL: Bug Tracker, https://github.com/avowkind/alleycat/issues
Project-URL: Documentation, https://github.com/avowkind/alleycat/tree/main/docs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.12.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.6.1
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: platformdirs>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.5; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: ruff>=0.2.1; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.12; extra == "dev"
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# AlleyCat - A command line tool for AI text processing

![AlleyCat](docs/alleycat.svg)

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](docs/alleycat-guide.md).

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:

```plaintext
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:

```bash
uv pip install alleycat
```

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

```bash
pipx install alleycat
```

### From Source

Install directly from the GitHub repository:

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

### Local Installation

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

```bash
cd alleycat
uv pip install .
```

After installation, you can run AlleyCat from anywhere with:

```bash
alleycat --help
```

## Development Setup

This project uses [uv](https://github.com/astral-sh/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:

   ```bash
   git clone <repository-url>
   cd alleycat
   ```

2. Create and activate a virtual environment with uv:

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

3. Install the package in development mode:

   ```bash
   uv pip install -e .
   ```

4. Install development dependencies:

   ```bash
   uv pip install -e ".[dev]"
   ```

## Usage

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

```bash
# 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:

```bash
# 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:

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

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

### Command Line Options

```bash
# 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`:

```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

  ```bash
  uv run pytest
  ```

- **Linting**: ruff

  ```bash
  uv run ruff check .
  ```

- **Type Checking**: mypy

  ```bash
  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
