Metadata-Version: 2.4
Name: lutz-research
Version: 0.4.1
Summary: AI-powered academic article screening and analysis tool
Project-URL: Repository, https://github.com/jooguilhermesc/lutz
Project-URL: Issues, https://github.com/jooguilhermesc/lutz/issues
License: MIT
License-File: LICENSE
Keywords: ai,nlp,pdf,research,screening,systematic-review
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.13.4
Requires-Dist: anthropic>=0.28
Requires-Dist: certifi>=2024.7.4
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=46.0.7
Requires-Dist: duckdb>=1.0
Requires-Dist: fastapi>=0.111
Requires-Dist: gitpython>=3.1
Requires-Dist: lancedb>=0.8
Requires-Dist: lxml>=6.1.0
Requires-Dist: numpy>=1.26
Requires-Dist: openai>=1.30
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: pdfplumber>=0.11
Requires-Dist: pillow>=12.2.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: pymupdf>=1.24
Requires-Dist: pypdf>=4.0
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: python-pptx>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: scikit-learn>=1.4
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: sqlglot>=23.0
Requires-Dist: tantivy>=0.22
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.40
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: weasyprint>=60
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: layout
Requires-Dist: layoutparser[layoutmodels]>=0.3.4; extra == 'layout'
Requires-Dist: pdf2image>=1.16; extra == 'layout'
Provides-Extra: marker
Requires-Dist: marker-pdf<2.0,>=0.2; extra == 'marker'
Provides-Extra: security
Requires-Dist: google-re2>=1.1; extra == 'security'
Description-Content-Type: text/markdown

# Lutz

<p align="center">
  <img src="https://raw.githubusercontent.com/jooguilhermesc/lutz/main/lutz.png" alt="Lutz logo" width="160"/>
</p>

**Languages:** **English** | [Português](README.pt-BR.md) | [Español](README.es.md)

> AI-powered tool for screening and analyzing academic PDF articles — browser interface and CLI.

[![DOI](https://zenodo.org/badge/1227342715.svg)](https://doi.org/10.5281/zenodo.19982571)
![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![Version](https://img.shields.io/badge/Version-0.3.1-blueviolet)
![License](https://img.shields.io/badge/License-MIT-green)

---

## Install

```bash
pip install lutz-research
```

Requires Python 3.10+. A virtual environment is recommended:

```bash
python -m venv .venv && source .venv/bin/activate
pip install lutz-research
```

---

## Quick start

```bash
# Create a project
mkdir my-review && cd my-review
lutz init

# Configure your AI model (see .env section below)
cp .env.example .env

# Add PDFs
lutz load --f ~/Downloads/articles --so linux

# Open the browser interface
lutz web
```

The interface opens at `http://localhost:8765`. From there you can vectorize articles, run analyses, and generate reports.

---

## Configure your model (.env)

Edit `.env` in the project root. Choose one provider:

**OpenRouter** (recommended — access to hundreds of models)
```dotenv
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-...

LLM_PROVIDER=openai
LLM_MODEL=google/gemini-flash-1.5-8b
```

**OpenAI**
```dotenv
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini
```

**Anthropic**
```dotenv
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=all-MiniLM-L6-v2

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
LLM_MODEL=claude-haiku-4-5-20251001
```

**Local — Ollama**
```dotenv
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=all-MiniLM-L6-v2

LLM_PROVIDER=openai
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama
LLM_MODEL=llama3.2
```

You can also configure everything from the **Settings** page inside the web interface.

---

## Documentation

Full guides, CLI reference, and screenshots at **[jooguilhermesc.github.io/lutz](https://jooguilhermesc.github.io/lutz/)**.

---

## How to cite

```bibtex
@software{cabral2026lutz,
  author  = {Cabral, João Guilherme Silva and Azevedo Farias, Anna Karoline},
  title   = {{Lutz: AI-powered academic article screening and analysis tool}},
  year    = {2026},
  version = {0.3.1},
  doi     = {10.5281/zenodo.19982571},
  url     = {https://github.com/jooguilhermesc/lutz}
}
```

---

## License

MIT
