Leaderboard Summarizer

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

pip install leaderboard_summarizer

---

Quick Start

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

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

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

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

from leaderboard_summarizer import leaderboard_summarizer

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

---

API Reference

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
• GitHub: https://github.com/chigwell

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