Metadata-Version: 2.3
Name: bean-lens
Version: 0.1.0
Summary: Extract structured coffee bean info from package or card images using Vision LLM
Keywords: coffee,ocr,vision,llm,bean,gemini
Author: Yuncheol Kwak
Author-email: Yuncheol Kwak <89392516+YunDo-Gi@users.noreply.github.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Dist: google-genai>=1.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pillow>=11.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0 ; extra == 'dev'
Requires-Dist: ruff>=0.9.0 ; extra == 'dev'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/YunDo-Gi/bean-lens
Project-URL: Repository, https://github.com/YunDo-Gi/bean-lens
Project-URL: Issues, https://github.com/YunDo-Gi/bean-lens/issues
Provides-Extra: dev
Description-Content-Type: text/markdown

# bean-lens

Extract structured coffee bean info from package or card images using Vision LLM.

## Installation

```bash
pip install bean-lens
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add bean-lens
```

## Setup

Get a Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey) and set it as an environment variable:

```bash
export GEMINI_API_KEY=your-api-key
```

## Usage

### Python

```python
from bean_lens import extract

result = extract("coffee_package.jpg")

print(result.roastery)        # "Fritz Coffee"
print(result.origin.country)  # "Ethiopia"
print(result.flavor_notes)    # ["Citrus", "Jasmine", "Honey"]
```

### CLI

```bash
bean-lens image.jpg
```

Output:
```
  bean-lens

  Roastery:      Fritz Coffee
  Name:          Ethiopia Yirgacheffe
  Origin:        Ethiopia / Yirgacheffe / Konga
  Variety:       Heirloom
  Process:       Washed
  Roast Level:   Light
  Flavor Notes:  Citrus, Jasmine, Honey
  Roast Date:    2024.01.15
  Altitude:      1,800-2,000m
```

JSON output:
```bash
bean-lens image.jpg --json
```

## Extracted Fields

| Field | Description |
|-------|-------------|
| `roastery` | Roastery or brand name |
| `name` | Coffee bean name |
| `origin` | Origin info (country, region, farm) |
| `variety` | Coffee varieties (e.g., Geisha, Typica) |
| `process` | Processing method (e.g., Washed, Natural) |
| `roast_level` | Roast level (e.g., Light, Medium, Dark) |
| `flavor_notes` | Flavor notes list |
| `roast_date` | Roast date |
| `altitude` | Growing altitude |

## License

MIT
