Metadata-Version: 2.4
Name: Grimmerie
Version: 0.1.2
Summary: Functions for Prototyping, QOL and Sanity checking
Author: Joe Petrecca
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.38
Requires-Dist: adapters>=1.0
Requires-Dist: numpy>=1.23
Requires-Dist: sentencepiece

# Grimmerie

A spellbook for Python.

Grimmerie is a collection of high-level utilities (“spells”) designed for rapid prototyping, sanity checking, and reducing friction in experimentation.

Each spell performs a **non-trivial amount of work under the hood**.  
They are intentionally designed to trade fine-grained control for speed, clarity, and momentum.

Use them when you want to move fast.  
Understand them before you rely on them.

---

## Installation

```bash
pip install grimmerie
```

---

## The Idea

Instead of wiring together pipelines every time, Grimmerie gives you:

- One function call  
- Sensible defaults  
- Heavy lifting handled internally  

Example philosophy:

```python
embeddings = specterize(papers)
```

Behind this single call:
- Model loading  
- Tokenization  
- Batching  
- Device handling  
- Adapter loading  
- Output formatting  

All handled for you.

---

## Spells

### `specterize`

Generate SPECTER2 embeddings from text or paper-like inputs.

```python
from specterize import specterize

papers = [
    {'abstract': 'We introduce a new language representation model called BERT'},
    {'abstract': 'The dominant sequence transduction models are based on neural networks'},
]

embeddings = specterize(papers, return_type='numpy')
```

---

## API

```python
specterize(input_data, return_type='list', max_length=512)
```

- `input_data`: `str`, `dict`, `list`, or iterable  
- `return_type`: `"list"`, `"numpy"`, `"tensor"`  
- `max_length`: tokenizer truncation length (default `512`)  

---

## Design Principles

### 1. Abstraction over configuration  
You should not need to think about setup for common workflows.

### 2. Strong defaults  
Spells are opinionated. They are built to “just work” for most cases.

### 3. Hidden complexity  
A spell may do significantly more than it appears.

### 4. Use with awareness  
Because complexity is hidden, you should understand what a spell does before using it in critical systems.

---

## When to Use Grimmerie

- Rapid experimentation  
- Prototyping ML/NLP pipelines  
- Sanity checking ideas  
- Building quick demos  

---

## When *Not* to Use It

- When you need full control over every step  
- When reproducibility requires explicit pipelines  
- When debugging low-level behavior  

---

## Notes

- First call may be slower due to model downloads  
- Models are cached locally after first use  
- Subsequent calls reuse loaded resources within the same process  

---

## Direction

Grimmerie will expand into a broader system of spells for:

- Vectorization  
- Dimensionality reduction  
- Visualization  
- Data inspection  
- ML prototyping utilities  

Each designed to compress multi-step workflows into a single, intentional call.
