Metadata-Version: 2.4
Name: alithia
Version: 0.2.8
Summary: Your ultimate research companion
Author-email: Xiaming Chen <chenxm35@gmail.com>
Maintainer-email: Xiaming Chen <chenxm35@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/caesar0301/alithia
Project-URL: Repository, https://github.com/caesar0301/alithia
Project-URL: Issues, https://github.com/caesar0301/alithia/issues
Keywords: research assistant,academic,arxiv,ai agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: noesium[agents,llm]>=0.2.2
Requires-Dist: supabase>=2.0.0
Provides-Extra: default
Requires-Dist: arxiv>=2.1.3; extra == "default"
Requires-Dist: pyzotero>=1.5.25; extra == "default"
Requires-Dist: scikit-learn>=1.5.2; extra == "default"
Requires-Dist: gitignore-parser>=0.1.11; extra == "default"
Requires-Dist: tiktoken>=0.8.0; extra == "default"
Requires-Dist: feedparser>=6.0.11; extra == "default"
Requires-Dist: sentence-transformers>=3.0.0; extra == "default"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "default"
Requires-Dist: lxml>=5.0.0; extra == "default"
Provides-Extra: docling
Requires-Dist: docling>=2.58.0; extra == "docling"
Requires-Dist: onnxruntime>=1.23.2; extra == "docling"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115; extra == "dashboard"
Requires-Dist: uvicorn>=0.34; extra == "dashboard"
Requires-Dist: websockets>=14.0; extra == "dashboard"
Requires-Dist: httpx>=0.27; extra == "dashboard"
Requires-Dist: scholarly>=1.7; extra == "dashboard"
Requires-Dist: google-search-results>=2.4; extra == "dashboard"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: all
Requires-Dist: alithia[dashboard,default,docling,postgres]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.1.0; extra == "dev"
Requires-Dist: pytest-tornasync>=0.6.0.post2; extra == "dev"
Requires-Dist: pytest-trio>=0.8.0; extra == "dev"
Requires-Dist: pytest-twisted>=1.14.3; extra == "dev"
Requires-Dist: twisted>=25.5.0; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: flake8>=7.3.0; extra == "dev"
Requires-Dist: autoflake>=2.3.1; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="docs/logos/alithia-logo.jpg" alt="Alithia Logo" width="200" />
</div>

# Alithia Research Companion

[![PyPI version](https://img.shields.io/pypi/v/alithia.svg)](https://pypi.org/project/alithia/)

![Alithia Overview](docs/screenshots/ss-overview.jpg)

**Time**, is one of the most valuable resources for a human researcher, best spent
on thinking, exploring, and creating in the world of ideas. With Alithia, we
aim to open a new frontier in research assistance. Alithia aspires to be your
powerful research companion: from reading papers to pursuing interest-driven
deep investigations, from reproducing experiments to detecting fabricated
results, from tracking down relevant papers to monitoring industrial
breakthroughs. At its core, Alithia forges a strong and instant link between your personal
research profile, the latest state-of-the-art developments, and pervasive cloud
resources, ensuring you stay informed, empowered, and ahead.

## Features

Alithia connects your personal research profile with publicly available academic resources, leveraging cloud infrastructure to automate the research workflow.

### AI Agents

* **PaperScout** — Personalized ArXiv paper recommendations delivered via email
  * Analyzes your Zotero library to understand research interests
  * Monitors ArXiv for new papers matching your profile
  * Ranks papers by relevance using embeddings + LLM
  * Sends daily curated digests with TLDR summaries

* **PaperLens** — Deep paper interaction and analysis
  * Parses PDFs using Docling with IBM Granite VLM
  * Extracts text, figures, tables, and equations
  * Semantic search across your paper collection
  * Interactive Q&A for paper exploration

### Researcher Profile

* Research interests, expertise, and preferences
* Connected services:
  * LLM (OpenAI compatible APIs)
  * Zotero personal library
  * Email notifications (SMTP)
  * GitHub profile
  * Google Scholar profile
* Gems — Save and organize research ideas and digests

### Academic Data Sources

* **arXiv** — Latest papers from cs.AI, cs.CV, cs.LG, and more
* **Google Scholar** — Profile sync and publication tracking
* **Web search** — Tavily and other search engines
* **Researcher homepages** — Automated discovery

## Usage

### Docker (Recommended)

The easiest way to run Alithia is using Docker:

```bash
docker pull ghcr.io/caesar0301/alithia:latest
```

Run the dashboard:

```bash
docker run -d -p 8080:8080 \
  -v $(pwd)/alithia_config.json:/app/config.json \
  ghcr.io/caesar0301/alithia:latest \
  python -m alithia.run dashboard --config /app/config.json
```

### Running from Source

#### Installation

Alithia uses optional dependencies to keep the base installation lightweight. The default installation includes PaperScout agent dependencies.

**Recommended: Default Installation**

For most users, install with default dependencies (includes PaperScout agent: ArXiv fetching, Zotero integration, email notifications, etc.):

```bash
pip install alithia[default]
```

**Optional Features:**

Install with PaperLens support (PDF analysis and deep paper interaction):

```bash
pip install alithia[docling]
```

Install all features:

```bash
pip install alithia[all]
```

#### Configuration

Create a JSON configuration with your credentials. See [alithia_config_example.json](alithia_config_example.json) for a complete example.

#### Running the Dashboard

Production mode:

```bash
python -m alithia.run dashboard --config alithia_config.json
```

Open http://localhost:8080 in your browser.

Development mode (with auto-reload):

```bash
python -m alithia.run dashboard --config alithia_config.json --dev
```

For frontend development, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## Storage Backend

Alithia supports three storage backends for persistent data storage with automatic fallback support. By default, **SQLite** is used for local development, while **Supabase** or **PostgreSQL** can be configured for production use. This enables:

- **Persistent caching** of Zotero libraries and parsed papers
- **Continuous paper feeding** that handles ArXiv indexing delays
- **Deduplication** to prevent duplicate email notifications
- **Query history** tracking for PaperLens interactions
- **Google Scholar profile synchronization**
- **Dashboard background task management**

See [docs/STORAGE_SETUP.md](docs/STORAGE_SETUP.md) for storage details.

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
