Metadata-Version: 2.1
Name: localgrid
Version: 0.1.1
Summary: A library for inspecting local LLM providers and tokenizers.
Author-email: Alan Mackiewicz <alanmackiewicz03@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Alan Mackiewicz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/AlanM03/LocalGrid
Project-URL: Source, https://github.com/AlanM03/LocalGrid
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tiktoken
Requires-Dist: httpx
Requires-Dist: transformers
Requires-Dist: protobuf
Requires-Dist: sentencepiece
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: anyio; extra == "dev"

# LocalGrid

A simple Python library to inspect and get metadata for local LLMs, like token limits and token counts.

I built this because I needed a way to get accurate info for local models without having to make any web calls. All the data and tokenizers are bundled directly into the package.

#### [localgrid on PyPI](https://pypi.org/project/localgrid/)

> *Supports Python >=3.8*

## Key Features

* **Fully Local:** No internet connection needed after installation.
* **Accurate Token Counting:** Uses the real tokenizer for a given model, not just a guess.
* **Bundled Tokenizers:** All the necessary tokenizer files are included in the package.
* **Simple API:** Just a few functions to get what you need.

## Data Source

The model data (like context limits) was gathered by scraping and formatting information from Ollama and lm-studios public model library's. This data is saved in a JSON file (`localgrid_cache.json`) inside the package.

[view the models](https://local-grid-hub.vercel.app/)

or just visit [ollama](https://ollama.com/search) and [lm-studio](https://lmstudio.ai/models)

## Installation

```bash
pip install localgrid
```

## Quick Start & Usage

The library has three main functions you'll probably use.

### 1. `get_context_limit`

Gets the total context size (token limit) for a model.


```python
from localgrid import get_context_limit

# Get the context limit for llama3.1:latest
limit = get_context_limit("llama3.1:latest")#ollama format

print(f"llama3.1:latest limit: {limit}")
# Output: llama3.1:latest limit: 131072
```

### 2. `count_tokens`

Counts the number of tokens in a string for a specific model. It loads the correct tokenizer to give you an accurate count.

```python
from localgrid import count_tokens

text = "This is a test sentence for my model."
model = "google/gemma-3-12b"#lm-studio format

token_count = count_tokens(text, model)

print(f"The text has {token_count} tokens according to {model}.")
# The text has 9 tokens according to google/gemma-3-12b.
```

### 3. `preload_tokenizers` (optional async)

Due to the decision to keep this package fully offline capable there
is a little delay when initially loading tokenizers from disk.

If you're using this in a server and want to avoid a tiny delay on the first call, you can preload the tokenizers into memory when your app starts.

```python
import asyncio
from localgrid import preload_tokenizers

async def main():
    # Preloads all 25 base tokenizers
    await preload_tokenizers()
    
    # Or just preload specific ones
    await preload_tokenizers(families=["llama", "gemma"])

if __name__ == "__main__":
    asyncio.run(main())
```

## Licensing & Included Tokenizers

All included tokenizer files are bundled with their original licenses (ex: `LICENSE` and `tokenizer_config.json`). You can find these within the installed package.

**Note:** Due to licensing restrictions, the following tokenizer families are **not** included in this package:

* `command-r`
* `stablelm2`
* `codestral`

*As a result they default to generic tokenizers*

> *If someone knows more about me than this please let me know and I will add them ASAP*
