Metadata-Version: 2.4
Name: finder-enrichment-ai-client
Version: 0.3.1
Summary: Lightweight AI client package for managing API calls to various AI providers
Project-URL: Homepage, https://github.com/giacomokavanagh/finder-enrichment-orchestrator
Project-URL: Bug Tracker, https://github.com/giacomokavanagh/finder-enrichment-orchestrator/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: build
Requires-Dist: build>=1.0.3; extra == "build"
Requires-Dist: twine>=6.1.0; extra == "build"

# Finder Enrichment AI Client

A lightweight Python package for managing AI API calls to various providers. Supports **Google Gemini AI** and **OpenRouter** (providing access to 100+ models from Anthropic, OpenAI, Meta, Google, and more).

## Features

- **Multi-Provider Support**: Google Gemini and OpenRouter (Claude, GPT, Llama, etc.)
- **Lightweight**: Minimal dependencies, just HTTP requests and YAML parsing
- **Simple**: Easy-to-use interface for AI API calls
- **Extensible**: Designed to support multiple AI providers
- **Configurable**: Support for both environment variables and config files
- **Model Mapping**: Friendly model names with config-based ID translation

## Installation

```bash
pip install finder-enrichment-ai-client
```

## Quick Start

### Google Gemini AI

```python
from finder_enrichment_ai_client import FinderEnrichmentGoogleAIClient

# Initialize with environment variable
client = FinderEnrichmentGoogleAIClient()

# Or initialize with direct API key
client = FinderEnrichmentGoogleAIClient(api_key="your-api-key-here", model="gemini-2.0-flash-exp")

# Generate text
response = client.generate_content("Hello! How are you?")
if response['success']:
    print(response['text'])
else:
    print(f"Error: {response['error']}")

# Analyze image (base64 encoded)
response = client.analyze_image(
    image_data="base64_encoded_image_data",
    prompt="Describe this image",
    image_content_type="image/webp"
)
if response['success']:
    print(response['text'])
```

### OpenRouter (Claude, GPT, Llama, etc.)

```python
from finder_enrichment_ai_client import FinderEnrichmentOpenRouterClient

# Initialize with environment variable
# Requires OPENROUTER_API_KEY environment variable
client = FinderEnrichmentOpenRouterClient(model="claude-3-5-sonnet")

# Or initialize with direct API key
client = FinderEnrichmentOpenRouterClient(
    api_key="your-openrouter-api-key",
    model="claude-3-5-sonnet"
)

# Generate text
response = client.generate_content("Explain quantum computing")
if response['success']:
    print(response['text'])

# Analyze image with vision models
response = client.analyze_image(
    image_data="base64_encoded_image_data",
    prompt="What's in this image?",
    image_content_type="image/jpeg"
)
if response['success']:
    print(response['text'])
```

### Model Configuration (config.yaml)

Create a `config.yaml` file to map friendly model names to provider-specific IDs:

```yaml
models:
  - name: "claude-3-5-sonnet"
    model_id: "anthropic/claude-3.5-sonnet"
    provider: "openrouter"
    
  - name: "gpt-4o"
    model_id: "openai/gpt-4o"
    provider: "openrouter"
```

Then use the config loader:

```python
from finder_enrichment_ai_client import get_openrouter_model_id

model_id = get_openrouter_model_id("claude-3-5-sonnet")
# Returns: "anthropic/claude-3.5-sonnet"
```

## Environment Variables

### For Google Gemini
```bash
export GOOGLE_GEMINI_API_KEY="your-google-api-key"
```

### For OpenRouter
```bash
export OPENROUTER_API_KEY="your-openrouter-api-key"
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"  # Optional, defaults to this
```

Get your OpenRouter API key at: https://openrouter.ai/keys

## API Reference

### FinderEnrichmentGoogleAIClient

#### Methods

- `generate_content(prompt, model=None, temperature=0.7, max_tokens=1000)`: Generate text content
- `analyze_image(image_data, prompt, image_content_type="image/webp", model=None)`: Analyze images with text prompts
- `set_model(model)`: Change the default model
- `set_temperature(temperature)`: Set the default temperature (0.0 to 1.0)
- `get_available_models(page_size=100)`: Get list of available models

### FinderEnrichmentOpenRouterClient

#### Methods

- `generate_content(prompt, model=None, temperature=0.7, max_tokens=1000)`: Generate text content
- `analyze_image(image_data, prompt, image_content_type="image/webp", model=None)`: Analyze images with vision models
- `set_model(model)`: Change the default model
- `set_temperature(temperature)`: Set the default temperature (0.0 to 2.0)

### Config Loader Functions

- `load_model_config()`: Load config.yaml file
- `get_model_config_by_name(model_name)`: Get full model configuration
- `get_openrouter_model_id(model_name)`: Translate model name to OpenRouter model ID
- `get_openrouter_base_url()`: Get OpenRouter base URL from config

#### Response Format

All API methods return a dictionary with:
- `success`: Boolean indicating if the call was successful
- `text`: Generated text (if successful)
- `raw_response`: Full API response
- `error`: Error message (if not successful)

## Development

```bash
# Install in development mode
pip install -e .

# Run tests
pytest

# Format code
black .
isort .
```

## License

MIT License
