llm-img-cat 0.1.2
LLM-based image categorization tool with focus on book cover detection
Requires Python: >=3.9
Keywords: llm, image, categorization, ai, book cover, vision, machine learning

# LLM Book Cover Detector

A Python package for detecting and analyzing book covers using Qwen Vision-Language model.

## Features

- Accurate book cover detection
- Similarity scoring (0-100%)
- Concise reasoning
- Beautiful CLI interface
- JSON response format
- Raw API response display
- Rich output formatting
- Comprehensive error handling

## Installation

```bash
pip install llm_img_cat
```

## API Key Setup

You need a DashScope API key to use this package. Here are three ways to set it up:

1. **Using Environment Variable (Recommended for Development)**
   ```bash
   export DASHSCOPE_API_KEY="your-api-key-here"
   ```

2. **Using .env File (Recommended for Projects)**
   Create a `.env` file in your project directory:
   ```
   DASHSCOPE_API_KEY=your-api-key-here
   DEFAULT_MODEL=qwen-vl-plus  # Optional
   ```
   The package will automatically load the API key from this file.

3. **Setting Programmatically (For Testing)**
   ```python
   import os
   os.environ['DASHSCOPE_API_KEY'] = 'your-api-key-here'
   from llm_img_cat import ImageCategorizer
   ```

⚠️ **Security Note**: Never commit your API key to version control. Always use environment variables or `.env` files, and keep your API key secure.

## Usage

### CLI Usage

The simplest way to use the book cover detector is through the CLI:

```bash
python scripts/llm_img_cat_cli.py path/to/image.jpg
```

This will:
1. Analyze if the image is a book cover
2. Provide a similarity score (0-100%)
3. Give a concise 5-word reasoning
4. Show raw API response

### Python API Usage

```python
from llm_img_cat import ImageCategorizer

# Initialize the categorizer (will automatically load API key from environment or .env)
categorizer = ImageCategorizer()

# Analyze an image
result = categorizer.categorize_image("path/to/image.jpg")

print(f"Is book cover: {result['is_category']}")
print(f"Similarity score: {result['confidence']}%")
print(f"Reasoning: {result['reasoning']}")
```

### Rich Console Demo

For a more sophisticated example with beautiful console output and error handling, check out the rich demo:

```bash
# Install required packages
pip install llm_img_cat rich

# Run the demo
python examples/rich_demo.py
```

The rich demo showcases:
- Beautiful console output with colors and panels
- Proper environment setup
- Comprehensive error handling
- Test summary reporting
- Multiple image processing

Example output:
```
╭───────────────────────────────╮
│ Environment Setup             │
│ API Key: ✓ Set                │
│ Model: qwen2.5-vl-3b-instruct │
╰───────────────────────────────╯

Analyzing image: Book cover example
╭──────────────────────────────────────╮
│ Analysis Results                     │
│ Is Book Cover: True                  │
│ Confidence: 95%                      │
│ Reasoning: Classic book cover design │
╰──────────────────────────────────────╯
```

## Example Output

```
╭── Book Cover Detection Results ───╮
│ Is Book Cover    │ Yes           │
│ Similarity Score │ 90%           │
╰────────────────────────────────╯
╭── Reasoning ──────────────────────╮
│ Text and design typical of books  │
╰────────────────────────────────╯
```

## Configuration

Required environment variables:
- `DASHSCOPE_API_KEY`: Your DashScope API key
- `DEFAULT_MODEL`: Model to use (default: "qwen-vl-plus")

## Development

- Run tests: `./run_qwen_tests.sh`
- Check code: `scripts/lint.sh`
- Build docs: `scripts/build_docs.sh`

## License

MIT License

## Contributing

See CONTRIBUTING.md for guidelines.