# llmdb

llmdb is a handy python package you can use to access the [models.dev](https://models.dev) comprehensive open-source database of AI model specifications, pricing and capabilities.

The database is not curated by me and all the data is retrieved from the models.dev API which you can also use directly.

## Installation

```bash
pip install llmdb
```

## Usage

The package exposes a `db` singleton that lazily fetches data from the API on first access.

```python
from llmdb import db

# Get a specific model by ID
model = db.models.get("gpt-4o")
print(f"{model.name}: {model.cost.input}$/M input tokens")

# Get a provider
provider = db.providers.get("openai")
print(f"{provider.name} has {len(provider.models)} models")
```

### Filtering

Filter models using field equality or custom predicates.

```python
# Filter by field values
reasoning_models = db.models.filter(reasoning=True).all()
open_source = db.models.filter(open_weights=True, reasoning=True).all()

# Filter with a custom predicate
cheap_models = db.models.filter_by(lambda m: m.cost and m.cost.input < 1.0).all()
```

### Sorting

Sort results by any field, including nested fields using dot notation.

```python
# Get newest models first
newest = db.models.sort_by("release_date", desc=True).all()

# Sort by input cost
by_cost = db.models.filter_by(lambda m: m.cost is not None).sort_by("cost.input").all()
```

### Indexed Lookups

Models are indexed by provider and family for fast access.

```python
# All models from a specific provider
openai_models = db.models.by_provider("openai").all()

# All models in a family
gpt_models = db.models.by_family("gpt").all()
```

### Chaining Queries

All query methods return a query builder, so you can chain them.

```python
result = (
    db.models
    .filter(reasoning=True, open_weights=True)
    .sort_by("release_date", desc=True)
    .first()
)
```

### Query Terminators

Queries are lazy until you call a terminator method.

```python
.all()    # Returns list of all matching items
.first()  # Returns first item or None
.count()  # Returns the count of matching items
```

### Refreshing Data

Data is fetched once and cached. Force a refresh from the API when needed.

```python
db.refresh()
print(f"Data fetched at: {db.fetched_at}")
```

## Acknowledgments

This package is a wrapper around the [models.dev](https://models.dev) database, created and maintained by [Anomaly](https://github.com/anomalyco/models.dev). All credit for the data goes to them.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
