leaderboard-summarizer 2025.12.21232414
Extracts and organizes leaderboard/ranking data from text via smart pattern matching and retries, delivering clean, structured summaries effortlessly.
License: MIT
Requires Python: >=3.9

# Leaderboard Summarizer
[![PyPI version](https://badge.fury.io/py/leaderboard-summarizer.svg)](https://badge.fury.io/py/leaderboard-summarizer)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/leaderboard-summarizer)](https://pepy.tech/project/leaderboard-summarizer)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-blue)](https://www.linkedin.com/in/eugene-evstafev-716669181/)


**leaderboard-summarizer** is a lightweight Python package that extracts structured summaries and analyses from free‑form text describing leaderboards, rankings, or score tables.  
It leverages LLM pattern matching (via `llmatch`) to ensure the extracted data matches a predefined regular expression, providing reliable, machine‑readable output without the need to manually parse raw documents.

---

## Features

- **One‑function API** – just call `leaderboard_summarizer(...)`.
- **Built‑in LLM7 support** – defaults to `ChatLLM7` from the `langchain_llm7` package.
- **Pluggable LLMs** – pass any LangChain‑compatible `BaseChatModel` (OpenAI, Anthropic, Google, etc.).
- **Robust pattern matching** – uses a compiled regex to validate and extract the result.
- **Zero‑configuration fallback** – works out‑of‑the‑box with a free LLM7 API key.

---

## Installation

```bash
pip install leaderboard_summarizer
```

---

## Quick Start

```python
from leaderboard_summarizer import leaderboard_summarizer

# Minimal usage – LLM7 will be used automatically (API key read from LLM7_API_KEY)
text = """
Top players this week:
1️⃣ Alice – 1500 pts
2️⃣ Bob – 1450 pts
3️⃣ Carol – 1400 pts
"""

summary = leaderboard_summarizer(user_input=text)
print(summary)
```

### Using a custom LLM

You can provide any LangChain `BaseChatModel` instance that follows the same interface.

#### OpenAI

```python
from langchain_openai import ChatOpenAI
from leaderboard_summarizer import leaderboard_summarizer

llm = ChatOpenAI(model="gpt-4o-mini")
summary = leaderboard_summarizer(user_input="...", llm=llm)
```

#### Anthropic

```python
from langchain_anthropic import ChatAnthropic
from leaderboard_summarizer import leaderboard_summarizer

llm = ChatAnthropic(model="claude-3-haiku-20240307")
summary = leaderboard_summarizer(user_input="...", llm=llm)
```

#### Google Gemini

```python
from langchain_google_genai import ChatGoogleGenerativeAI
from leaderboard_summarizer import leaderboard_summarizer

llm = ChatGoogleGenerativeAI(model="gemini-1.5-flash")
summary = leaderboard_summarizer(user_input="...", llm=llm)
```

### Supplying an explicit LLM7 API key

```python
from leaderboard_summarizer import leaderboard_summarizer

summary = leaderboard_summarizer(
    user_input="...",
    api_key="your_llm7_api_key"
)
```

---

## API Reference

```python
leaderboard_summarizer(
    user_input: str,
    llm: Optional[BaseChatModel] = None,
    api_key: Optional[str] = None
) -> List[str]
```

| Parameter   | Type                     | Description |
|-------------|--------------------------|-------------|
| `user_input`| `str`                    | Free‑form text that contains leaderboard or ranking information. |
| `llm`       | `Optional[BaseChatModel]`| A LangChain‑compatible chat model. If omitted, the function creates a `ChatLLM7` instance automatically. |
| `api_key`   | `Optional[str]`         | LLM7 API key. If not provided, the function looks for the `LLM7_API_KEY` environment variable, falling back to a placeholder `"None"` (which triggers an error from the service). |

**Return value** – a list of strings extracted from the input text that match the internal regex pattern defined in `leaderboard_summarizer.prompts.pattern`.

---

## How It Works

1. **Prompt Construction** – System and human prompts (defined in `leaderboard_summarizer.prompts`) guide the LLM to produce output that conforms to a strict regex.
2. **LLM Call** – `llmatch` sends the prompts to the chosen LLM.
3. **Pattern Validation** – The raw LLM response is checked against the compiled regular expression.
4. **Extraction** – If the response matches, the captured groups are returned as a list; otherwise a `RuntimeError` is raised.

---

## Environment Variables

- `LLM7_API_KEY` – API key for the default LLM7 service. You can obtain a free key at https://token.llm7.io/.

---

## License

This project is licensed under the MIT License.

---

## Contributing & Support

- **Issue Tracker:** https://github.com/chigwell/leaderboard-summarizer/issues  
- **Author:** Eugene Evstafev – [hi@eugene.plus](mailto:hi@eugene.plus)  
- **GitHub:** https://github.com/chigwell

Feel free to open issues, submit pull requests, or contact the author for feature requests and bug reports.