---
title: Snowman AI
emoji: โ
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
license: mit
tags:
- mcp-in-action-track-consumer
- building-mcp-track-consumer
- mcp
- literature-review
- langgraph
- academic-research
- openai
short_description: Autonomous Literature Review Agent with MCP
---
# โ๏ธ Snowman AI
> **Autonomous Literature Review Agent powered by LangGraph + Gradio MCP Server**
โ Snowman AI
[](https://huggingface.co/MCP-1st-Birthday)
[](https://openai.com)
[](https://gradio.app)
[](https://langchain-ai.github.io/langgraph/)
[](https://python.org)
---
## ๐ Hackathon Submission
**Tracks:**
- ๐ค **Track 2: MCP in Action - Consumer** (`mcp-in-action-track-consumer`)
- ๐ง **Track 1: Building MCP - Consumer** (`building-mcp-track-consumer`)
> โ This app qualifies for both tracks: it's an **autonomous agent** with planning, reasoning, and execution (Track 2) that also exposes a **fully functional MCP Server with 6 tools** (Track 1).
**Team Members:**
- [@nextmarte](https://huggingface.co/nextmarte) - Marcus Antonio Cardoso Ramalho
**Social Media Post:** [LinkedIn Post](https://www.linkedin.com/feed/update/urn:li:ugcPost:7400685631669964800/)
**๐
Sponsor Integration:**
- โ
**OpenAI GPT-4o** - Powers intelligent reference parsing and SLR relevance evaluation
---
## ๐ฅ Demo Video
> ๐น **[Click to watch the full demo](https://youtu.be/8v8o5zes9h4)** (2 minutes) - See Snowman extract 100+ references from a PDF and search them across 6 databases!
---
## ๐ What is Snowman?
**Snowman AI** is an autonomous AI agent that revolutionizes systematic literature reviews (SLR) by automating the tedious process of reference extraction and abstract retrieval.
### The Problem
Researchers spend **hundreds of hours** manually:
1. Reading PDFs to extract bibliographic references
2. Searching multiple databases for each reference
3. Finding and reading abstracts
4. Evaluating relevance for inclusion/exclusion
### The Solution
Snowman is a **multi-agent system** that:
```
๐ PDF Upload โ ๐ค AI Reference Extraction โ ๐ Cascade Search โ โ
SLR Evaluation
```
1. **PDF Extractor Agent**: Intelligently finds the References section in academic PDFs
2. **Parser Agent**: Uses GPT-4o to identify and clean bibliographic references
3. **Cascade Search Agent**: Searches 6 academic APIs in parallel
4. **Deduplication Agent**: Removes duplicates by DOI and title similarity
5. **SLR Evaluation Agent**: Automatically evaluates papers against your inclusion/exclusion criteria
---
## โจ Key Features
### ๐ค Autonomous Agent Behavior
- **Planning**: Analyzes PDF structure to find references
- **Reasoning**: Uses LLM to parse unstructured reference text
- **Execution**: Parallel searches across multiple APIs
- **Self-correction**: Falls back to alternative sources if primary fails
### ๐ Cascade Search Strategy
Searches multiple academic databases in order of reliability:
| Priority | Source | Type | Features |
|----------|--------|------|----------|
| 1๏ธโฃ | CrossRef | Free API | DOI resolution, metadata |
| 2๏ธโฃ | Semantic Scholar | Free API | Best abstracts, citations |
| 3๏ธโฃ | OpenAlex | Open API | Comprehensive coverage |
| 4๏ธโฃ | DuckDuckGo | Web Search | Fallback web scraping |
| 5๏ธโฃ | Tavily | Paid API | Last resort, high quality |
### ๐ Smart Caching
- SQLite-based persistent cache
- Avoids redundant API calls
- Caches both positive and negative results
- PDF parsing cache for repeated uploads
### โ
RSL Evaluation
- Define inclusion/exclusion criteria
- AI evaluates each paper automatically
- Export decisions with justifications
- Excel/JSON export for further analysis
---
## ๐ ๏ธ Technology Stack
| Component | Technology |
|-----------|------------|
| **Orchestration** | LangGraph (StateGraph) |
| **LLM** | OpenAI GPT-4o |
| **UI Framework** | Gradio 6 |
| **PDF Processing** | PyMuPDF |
| **APIs** | CrossRef, Semantic Scholar, OpenAlex, Tavily |
| **Caching** | SQLite |
| **Parallelism** | ThreadPoolExecutor |
---
## ๐ Quick Start
### Prerequisites
- Python 3.12+
- OpenAI API Key
- (Optional) Tavily API Key for enhanced search
### Installation
```bash
# Clone the repository
git clone https://github.com/nextmarte/snowball.git
cd snowball
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e .
```
### Configuration
Create a `.env` file:
```env
OPENAI_API_KEY=sk-your-key-here
TAVILY_API_KEY=tvly-your-key-here # Optional
```
### Run
```bash
uv run app.py
```
Open http://localhost:7860 in your browser.
---
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ GRADIO UI โ
โ โโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโโ โ
โ โ Upload โ โ Pipeline โ โ Results โ โ RSL Eval โ โ
โ โ Tab โ โ View โ โ Table โ โ Tab โ โ
โ โโโโโโฌโโโโโ โโโโโโฌโโโโโโ โโโโโโโฌโโโโโโ โโโโโโโฌโโโโโโโ โ
โโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโผโโโโโโโโโโโ
โ โ โ โ
โผ โผ โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ LANGGRAPH WORKFLOW โ
โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโโโ โ
โ โ Extractorโโโโโบโ Parser โโโโโบโ Researcher โโโโโบ END โ
โ โ Node โ โ Node โ โ Node โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโโโ โ
โ โ โ โ โ
โ โผ โผ โผ โ
โ PyMuPDF GPT-4o LLM ThreadPool โ
โ Executor โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ CASCADE SEARCH SERVICES โ
โ โ
โ CrossRef โ Semantic Scholar โ OpenAlex โ DDG โ Tavily โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ SQLITE CACHE โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ Search Cache โ โ PDF Parse Cache โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
---
## ๐ฏ Use Cases
### ๐ Academic Researchers
- Conduct systematic literature reviews faster
- Find abstracts for hundreds of references in minutes
- Export to Excel for further analysis
### ๐ซ Graduate Students
- Speed up thesis literature review
- Ensure comprehensive coverage of references
- Automatic relevance evaluation
### ๐ Research Teams
- Batch process multiple PDFs
- Collaborative review workflows
- Consistent evaluation criteria
---
## ๐ฎ Roadmap
- [x] MCP Server integration for AI tools (Claude Desktop, Cursor, etc.)
- [x] HuggingFace Papers API integration
- [ ] Citation network visualization
- [ ] Full-text PDF analysis
- [ ] Multi-language support (PT-BR, ES)
- [ ] Zotero/Mendeley export
---
## ๐ MCP Server Integration
This app exposes an MCP (Model Context Protocol) server that can be consumed by AI tools like Claude Desktop, Cursor, and other MCP-compatible clients.
### Available MCP Tools
| Tool | Description |
|------|-------------|
| `search_reference` | Search academic databases for a reference |
| `get_doi_abstract` | Get abstract and metadata by DOI |
| `classify_reference` | Classify reference type (article, book, etc.) |
| `evaluate_relevance` | Evaluate paper relevance for a research topic |
| `batch_search` | Search multiple references at once |
| `cache_stats` | Get cache statistics |
### MCP Server URL
When running the app, the MCP server is available at:
```
http://127.0.0.1:7860/gradio_api/mcp/
```
### Connecting Claude Desktop
Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"snowman": {
"url": "http://127.0.0.1:7860/gradio_api/mcp/sse"
}
}
}
```
---
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
---
## ๐ License
MIT License - see [LICENSE](LICENSE) for details.
---
## ๐ Acknowledgments
- [LangChain](https://langchain.com) for LangGraph
- [Gradio](https://gradio.app) for the amazing UI framework
- [Anthropic](https://anthropic.com) for MCP protocol
- [HuggingFace](https://huggingface.co) for hosting the hackathon
- All the open academic APIs: CrossRef, Semantic Scholar, OpenAlex
---
Built with โค๏ธ for the MCP 1st Birthday Hackathon
November 2025