FastAPI + Gradio + src

.dockerignore

@@ -0,0 +1,84 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+venv/
+env/
+.env
+.venv/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Project Specific Outputs
+*.md
+!README.md
+*_only_used_entry.bib
+
+# LaTeX and Bibliography (User Data)
+*.tex
+*.bib
+*.pdf
+*.aux
+*.out
+*.bbl
+*.blg
+*.synctex.gz
+*.fls
+*.fdb_latexmk
+
+# cache
+.cache
+
+# Logs
+logs/
+*.log
+
+# Gradio
+.gradio/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Test coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Temporary files
+*.tmp
+*.temp
+temp/
+
+# Docker
+.dockerignore

.env.example

@@ -0,0 +1,44 @@
+# Application Settings
+APP_NAME=CiteScan
+APP_VERSION=1.0.0
+ENVIRONMENT=development  # development, staging, production
+
+# Server Configuration
+API_HOST=0.0.0.0
+API_PORT=8000
+GRADIO_HOST=0.0.0.0
+GRADIO_PORT=7860
+
+# API Rate Limiting
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_REQUESTS=100
+RATE_LIMIT_PERIOD=60  # seconds
+
+# Cache Configuration
+CACHE_ENABLED=true
+CACHE_TTL=3600  # seconds (1 hour)
+CACHE_MAX_SIZE=1000  # max number of cached items
+
+# Fetcher Configuration
+ARXIV_RATE_LIMIT_DELAY=3.0  # seconds between requests
+CROSSREF_RATE_LIMIT_DELAY=1.0
+SEMANTIC_SCHOLAR_RATE_LIMIT_DELAY=1.0
+DBLP_RATE_LIMIT_DELAY=1.0
+OPENALEX_RATE_LIMIT_DELAY=1.0
+SCHOLAR_RATE_LIMIT_DELAY=5.0
+
+# API Timeouts (seconds)
+REQUEST_TIMEOUT=30
+MAX_WORKERS=10  # max concurrent workers for verification
+
+# Logging
+LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_FORMAT=json  # json or text
+LOG_FILE=logs/citescan.log
+
+# CORS Settings (comma-separated origins)
+CORS_ORIGINS=http://localhost:3000,http://localhost:8080
+
+# Optional: API Keys (if needed in future)
+# SEMANTIC_SCHOLAR_API_KEY=
+# CROSSREF_API_KEY=

CiteScan

@@ -0,0 +1 @@
+Subproject commit 5386ca09348bfbdd78ef2b97feb106ebd6c575cd

Dockerfile

@@ -0,0 +1,37 @@
+# Dockerfile for CiteScan
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create logs directory
+RUN mkdir -p logs
+
+# Expose ports
+EXPOSE 7860 8000
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1
+ENV ENVIRONMENT=production
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:8000/api/v1/health', timeout=5)"
+
+# Default command (can be overridden)
+CMD ["python", "main.py"]

README.md

@@ -1,49 +1,249 @@
+---
+title: CiteScan
+emoji: 📚
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: "4.44.0"
+app_file: app.py
+pinned: false
+---
+
 # CiteScan: Check References, Confirm Truth.
 
-<!-- - **🎉 CiteScan is now available online. [https://huggingface.co/spaces/thinkwee/CiteScan](https://huggingface.co/spaces/thinkwee/CiteScan)!  🎉** -->
+**CiteScan** is an open-source and free tool designed to detect hallucinated references in academic writing. As AI coding assistants and writing tools become more prevalent, they sometimes generate plausible-sounding citations that do not actually exist. **CiteScan** addresses this issue by validating every bibliography entry against multiple authoritative academic databases—including arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar—to confirm their authenticity.
+
+Going beyond simple verification, **CiteScan** uses rule-based algorithms to analyze whether the cited papers genuinely support the claims made in your text. Thanks to the free accessibility for academic databases across CS and AI areas, our system will **cost $0 for maintenance after development**.
+
+## 🚀 Quick Start
+
+### Option 1: Web Interface (Gradio)
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run Gradio interface
+python app.py
+```
+
+Access at `http://localhost:7860`
+
+### Option 2: API Service (FastAPI)
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
 
+# Run API service
+python main.py
+```
+
+Access API at `http://localhost:8000`
+API Documentation at `http://localhost:8000/docs`
+
+### Option 3: Docker
 
-**CiteScan**  is an open-source and free tool designed to detect hallucinated references in academic writing. As AI coding assistants and writing tools become more prevalent, they sometimes generate plausible-sounding citations that do not actually exist. **CiteScan**  addresses this issue by validating every bibliography entry against multiple authoritative academic databases—including arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar—to confirm their authenticity.
+```bash
+# Run both services with Docker Compose
+docker-compose up -d
+
+# Gradio: http://localhost:7860
+# API: http://localhost:8000
+```
 
-Going beyond simple verification, **CiteScan** used rule-based algorithms to analyze whether the cited papers genuinely support the claims made in your text. Thanks to the free accessibility for academic databases across CS and AI areas, our system will **cost $0 for maintenance after development**. 
+## 📚 Documentation
 
+- **[API Documentation](API_DOCS.md)** - Complete API reference and examples
+- **[Deployment Guide](DEPLOYMENT.md)** - Production deployment instructions
 
 ## 🛡 Why CiteScan?
 
--   **🚫 NO Hallucinations**: Annotate citations that don't exist or have mismatched metadata across year, authors, and title. 
+- **🚫 NO Hallucinations**: Annotate citations that don't exist or have mismatched metadata across year, authors, and title.
+
+- **📋 Ground Truth Reference**: Provide the link if the citations are flagged to *issued entry*. You can click the **Open paper** or **DOI** button to access the real-world metadata, and then cite the BibTeX from the press website.
 
--   **📋 Ground Truth Reference**: Provide the link if the citations are flagged to *issued entry*. You can click the **Open paper** or **DOI** button to access the real-world metadata, and Then cite the BibTex from the press website.
- 
 ![Functions](assets/screenshot_performance_zh.png)
 
--   **🏠 Top-tier Research Organizations**: Cooperate with National University of Singapore (NUS) and Shanghai Jiao Tong University (SJTU). 
+- **🏠 Top-tier Research Organizations**: Cooperate with National University of Singapore (NUS) and Shanghai Jiao Tong University (SJTU).
+
+- **🔌 RESTful API**: Production-ready API for integration with other tools and services.
+
+## ✨ Features
+
+### Web Interface (Gradio)
+- User-friendly interface for manual verification
+- Real-time progress tracking
+- Interactive filtering by verification status
+- Visual presentation of results
+
+### API Service (FastAPI)
+- RESTful API for programmatic access
+- Automatic OpenAPI documentation
+- JSON responses for easy integration
+- Health checks and monitoring endpoints
+- Structured logging
+- Caching for improved performance
 
-## References Validation
--   **Multi-Source Verification**: Validates metadata against arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar
+## 🔍 References Validation
 
+- **Multi-Source Verification**: Validates metadata against arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar.
 
+- **Covert citation from pre-print version to official version**: After clicking the blue button (`Open paper` or `DOI`), the official website will display. Click the `cite` button, you can copy the official BibTex.
 
 ![Citation](assets/screenshot_semantic_scholar.png)
 
+### Verification Workflow
+
+1. **Parse BibTeX**: Extract entries and metadata
+2. **Priority-based Search**: Query databases in priority order
+3. **Metadata Comparison**: Compare title, authors, year, venue
+4. **Duplicate Detection**: Identify duplicate entries
+5. **Result Generation**: Provide detailed verification report
+
+## 📖 API Usage Examples
+
+### Python
+
+```python
+import requests
+
+url = "http://localhost:8000/api/v1/verify"
+bibtex = """
+@article{vaswani2017attention,
+  title={Attention is all you need},
+  author={Vaswani, Ashish and Shazeer, Noam},
+  year={2017}
+}
+"""
+
+response = requests.post(url, json={"bibtex_content": bibtex})
+result = response.json()
+
+print(f"Verified: {result['verified_count']}/{result['total_count']}")
+```
+
+### cURL
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/verify" \
+  -H "Content-Type: application/json" \
+  -d '{"bibtex_content": "@article{example,title={Test},year={2023}}"}'
+```
+
+See [API_DOCS.md](API_DOCS.md) for complete API documentation.
+
+## ⚙️ Configuration
+
+Create a `.env` file from the template:
+
+```bash
+cp .env.example .env
+```
+
+Key configuration options:
+
+```bash
+# Server ports
+API_PORT=8000
+GRADIO_PORT=7860
+
+# Performance
+MAX_WORKERS=10
+CACHE_ENABLED=true
+CACHE_TTL=3600
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+```
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for complete configuration guide.
+
+## 🏗️ Architecture
+
+```
+CiteScan/
+├── src/
+│   ├── api/              # FastAPI routes and schemas
+│   ├── services/         # Business logic layer
+│   ├── core/             # Configuration, logging, cache
+│   ├── fetchers/         # Database API clients
+│   ├── analyzers/        # Metadata comparison
+│   ├── parsers/          # BibTeX parsing
+│   └── utils/            # Utilities
+├── app.py                # Gradio interface
+├── main.py               # FastAPI application
+├── Dockerfile            # Container configuration
+└── docker-compose.yml    # Multi-service setup
+```
+
+## 🔧 Development
+
+### Setup Development Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy environment template
+cp .env.example .env
+
+# Run in development mode
+ENVIRONMENT=development python main.py
+```
+
+### Project Structure
+
+- **Services Layer**: Reusable business logic
+- **API Layer**: RESTful endpoints with FastAPI
+- **UI Layer**: Gradio interface
+- **Core**: Configuration, logging, caching
+- **Fetchers**: Database API integrations
+
+## 📊 Monitoring
+
+### Health Check
+
+```bash
+curl http://localhost:8000/api/v1/health
+```
+
+### Statistics
 
-### *Case Study for False Positive*
+```bash
+curl http://localhost:8000/api/v1/stats
+```
+
+### Logs
+
+Logs are stored in `logs/citescan.log` in JSON format:
+
+```bash
+tail -f logs/citescan.log | jq '.'
+```
 
-1.  **Authors Mismatch**:
-    - *Reason*: Different databases deal with a longer list of  authors with different strategies, like truncation.
-    - *Action*: Verify if main authors match
+## ⚠️ Case Study for False Positives
 
-2.  **Venues Mismatch**:
-    - *Reason*: Abbreviations vs. full names, such as "ICLR" v.s. "International Conference on Learning Representations"
-    - *Action*: Both are correct.
+1. **Authors Mismatch**:
+   - *Reason*: Different databases deal with a longer list of authors with different strategies, like truncation.
+   - *Action*: Verify if main authors match
 
-3.  **Year GAP (±1 Year)**:
-    - *Reason*: Delay between preprint (arXiv) and final version publication 
-    - *Action*: Verify which version you intend to cite, We recommend you to cite the version from the official press website. Lower pre-print version bib will make your submission more confidence. 
+2. **Venues Mismatch**:
+   - *Reason*: Abbreviations vs. full names, such as "ICLR" vs. "International Conference on Learning Representations"
+   - *Action*: Both are correct.
 
-4.  **Non-academic Sources**:
-    - *Reason*: Blogs, and APIs are not indexed in academic databases.
-    - *Action*: Verify URL, year, and title manually.
+3. **Year GAP (±1 Year)**:
+   - *Reason*: Delay between preprint (arXiv) and final version publication
+   - *Action*: Verify which version you intend to cite. We recommend citing the version from the official press website. Lower pre-print version bib will make your submission more convincing.
 
+4. **Non-academic Sources**:
+   - *Reason*: Blogs and APIs are not indexed in academic databases.
+   - *Action*: Verify URL, year, and title manually.
 
 ## 🙏 Acknowledgments
 
@@ -53,30 +253,63 @@ CiteScan uses multiple data sources:
 - Semantic Scholar API
 - DBLP API
 - OpenAlex API
+- Google Scholar (web scraping)
 
+## 📝 License
 
-### Push
-```shell
+[Add your license here]
 
-# 如果已经添加过 modelscope 远程，先删掉再加：
-git remote remove modelscope
-git remote add modelscope "http://oauth2:ms-28735aa7-04b6-4b21-b4e0-cfb464f3587f@www.modelscope.cn/studios/aivolcano/CiteScan.git"
+## 🤝 Contributing
 
-# 添加 ModelScope 为远程仓库
-git remote add modelscope "http://oauth2:ms-28735aa7-04b6-4b21-b4e0-cfb464f3587f@www.modelscope.cn/studios/aivolcano/CiteScan.git"
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-# 推送到创空间(主分支是 main 时)
-git push modelscope main
+## 📧 Contact
 
-# 推送到创空间(主分支是 master 时)
-git push modelscope master
+For questions and support:
+- Email: e1143641@u.nus.edu
+- GitHub Issues: [Repository URL]
 
+---
 
-# 若推送时报错
-git push modelscope main --force
+## 🚀 ModelScope Deployment
+
+To deploy on ModelScope 创空间:
+
+```bash
+# Add ModelScope remote
+git remote add modelscope "http://oauth2:YOUR_TOKEN@www.modelscope.cn/studios/YOUR_USERNAME/CiteScan.git"
+
+# Push to ModelScope
+git push modelscope main
 
-# 推送成功后
-https://www.modelscope.cn/studios/aivolcano/CiteScan
-# 创空间里点 「上线空间展示」 或 「立即发布」，等部署完成即可访问 Gradio 应用。
+# Or force push if needed
+git push modelscope main --force
 ```
 
+After pushing, visit your ModelScope studio and click "上线空间展示" or "立即发布" to deploy the Gradio application.
+
+---
+
+## 🚀 Hugging Face Spaces 部署
+
+将代码推送到 [Hugging Face Spaces](https://huggingface.co/spaces/yancan/CiteScan/)：
+
+1. **安装 Hugging Face CLI 并登录**（如未安装）：
+   ```bash
+   pip install huggingface_hub
+   huggingface-cli login
+   ```
+
+2. **添加 Hugging Face 远程仓库**：
+   ```bash
+   git remote add hf https://huggingface.co/spaces/yancan/CiteScan
+   ```
+
+3. **推送到 Spaces**（HF 不允许普通 git 推送二进制文件，需用无图片分支 `hf-main`）：
+   - **重要**：HF 上显示的是 **已提交到 main 的代码**。若本地有未提交的修改（如 `main.py`、`src/` 等），需先提交到 `main`，再更新并推送 `hf-main`。
+   - 一键脚本：`./scripts/push_to_hf.sh`（会提示先提交未提交的修改，再重建 `hf-main` 并推送）。
+   - 或手动：先 `git add -A && git commit -m "说明"`，再运行脚本或按脚本内步骤重建 `hf-main` 并 `git push hf hf-main:main --force`。
+
+4. 推送完成后，在 [Space 页面](https://huggingface.co/spaces/yancan/CiteScan) 等待构建结束即可访问 Gradio 应用。
+
+**注意**：README 顶部的 YAML 配置（`title`、`sdk`、`app_file` 等）为 Spaces 必需，请勿删除。

docker-compose.yml

@@ -0,0 +1,50 @@
+version: '3.8'
+
+services:
+  # FastAPI service
+  api:
+    build: .
+    container_name: citescan-api
+    command: python main.py
+    ports:
+      - "8000:8000"
+    environment:
+      - ENVIRONMENT=development
+      - API_HOST=0.0.0.0
+      - API_PORT=8000
+      - LOG_LEVEL=INFO
+      - CACHE_ENABLED=true
+    volumes:
+      - ./logs:/app/logs
+      - ./.env:/app/.env
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests; requests.get('http://localhost:8000/api/v1/health')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  # Gradio service
+  gradio:
+    build: .
+    container_name: citescan-gradio
+    command: python app.py
+    ports:
+      - "7860:7860"
+    environment:
+      - ENVIRONMENT=development
+      - GRADIO_HOST=0.0.0.0
+      - GRADIO_PORT=7860
+      - LOG_LEVEL=INFO
+      - CACHE_ENABLED=true
+    volumes:
+      - ./logs:/app/logs
+      - ./.env:/app/.env
+    restart: unless-stopped
+    depends_on:
+      - api
+
+networks:
+  default:
+    name: citescan-network

main.py

@@ -0,0 +1,115 @@
+"""FastAPI application entry point."""
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+import time
+
+from src.core.config import settings
+from src.core.logging import setup_logging, get_logger
+from src.api.routes import verification, health
+
+# Setup logging
+setup_logging()
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+    logger.info(f"Environment: {settings.environment}")
+    logger.info(f"API running on {settings.api_host}:{settings.api_port}")
+    yield
+    logger.info("Shutting down application")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="API for verifying BibTeX references against academic databases",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Request timing middleware
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    """Add processing time to response headers."""
+    start_time = time.time()
+    response = await call_next(request)
+    process_time = time.time() - start_time
+    response.headers["X-Process-Time"] = str(process_time)
+    return response
+
+
+# Exception handlers
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Handle validation errors."""
+    logger.warning(f"Validation error: {exc}")
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "error": "ValidationError",
+            "message": "Invalid request data",
+            "details": exc.errors(),
+        },
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    """Handle general exceptions."""
+    logger.exception(f"Unhandled exception: {exc}")
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "error": "InternalServerError",
+            "message": "An unexpected error occurred",
+        },
+    )
+
+
+# Include routers
+app.include_router(verification.router)
+app.include_router(health.router)
+
+
+# Root endpoint
+@app.get("/", tags=["root"])
+async def root():
+    """Root endpoint."""
+    return {
+        "name": settings.app_name,
+        "version": settings.app_version,
+        "environment": settings.environment,
+        "docs": "/docs",
+        "health": "/api/v1/health",
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "main:app",
+        host=settings.api_host,
+        port=settings.api_port,
+        reload=settings.is_development,
+        log_level=settings.log_level.lower(),
+    )

scripts/push_to_hf.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# 把当前最新代码推到 Hugging Face Space（先提交到 main，再更新 hf-main 并推送）
+set -e
+cd "$(dirname "$0")/.."
+
+echo "=== 1. 检查未提交的修改 ==="
+if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git status --porcelain)" ]; then
+  echo "当前有未提交的修改。请先提交到 main："
+  echo "  git add -A"
+  echo "  git commit -m '你的提交说明'"
+  echo "  git push origin main   # 可选：同步到 GitHub"
+  echo ""
+  read -p "是否现在执行 git add -A && git commit？(y/N) " -n 1 -r
+  echo
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    read -p "请输入 commit message: " msg
+    git add -A
+    git commit -m "${msg:-Update for HF Spaces}"
+  else
+    echo "已取消。请先提交后再运行此脚本。"
+    exit 1
+  fi
+fi
+
+echo ""
+echo "=== 2. 用当前 main 重建 hf-main（并移除二进制文件）==="
+# 备份当前 hf-main 的 ref（可选）
+git branch -D hf-main 2>/dev/null || true
+git checkout -b hf-main main
+
+FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --index-filter \
+  'git rm -q --cached --ignore-unmatch \
+    assets/logo_nus.png \
+    assets/logo_sjtu.png \
+    assets/screenshot_performance.png \
+    assets/screenshot_performance_zh.png \
+    assets/screenshot_semantic_scholar.png' -- hf-main
+
+git checkout main
+echo ""
+echo "=== 3. 推送到 Hugging Face ==="
+git push hf hf-main:main --force
+echo ""
+echo "完成。请到 https://huggingface.co/spaces/yancan/CiteScan 查看构建状态。"

src/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

src/api/dependencies.py

@@ -0,0 +1,29 @@
+"""API dependencies and dependency injection."""
+from typing import Annotated
+from fastapi import Depends
+
+from src.services import VerificationService
+from src.core.cache import cache_manager
+
+
+def get_verification_service() -> VerificationService:
+    """Get verification service instance.
+
+    Returns:
+        VerificationService instance
+    """
+    return VerificationService()
+
+
+def get_cache_manager():
+    """Get cache manager instance.
+
+    Returns:
+        CacheManager instance
+    """
+    return cache_manager
+
+
+# Type aliases for dependency injection
+VerificationServiceDep = Annotated[VerificationService, Depends(get_verification_service)]
+CacheManagerDep = Annotated[type(cache_manager), Depends(get_cache_manager)]

src/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes package."""

src/api/routes/health.py

@@ -0,0 +1,54 @@
+"""Health check and system routes."""
+from fastapi import APIRouter
+
+from src.api.schemas import HealthResponse, StatsResponse
+from src.api.dependencies import CacheManagerDep
+from src.core.config import settings
+from src.core.logging import get_logger
+
+logger = get_logger(__name__)
+router = APIRouter(prefix="/api/v1", tags=["system"])
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Health check",
+    description="Check if the service is running and healthy",
+)
+async def health_check() -> HealthResponse:
+    """Health check endpoint.
+
+    Returns:
+        Health status
+    """
+    return HealthResponse(
+        status="healthy",
+        version=settings.app_version,
+        environment=settings.environment,
+    )
+
+
+@router.get(
+    "/stats",
+    response_model=StatsResponse,
+    summary="Get statistics",
+    description="Get system statistics including cache information",
+)
+async def get_stats(cache: CacheManagerDep) -> StatsResponse:
+    """Get system statistics.
+
+    Args:
+        cache: Cache manager instance
+
+    Returns:
+        System statistics
+    """
+    cache_stats = cache.get_stats()
+
+    return StatsResponse(
+        cache_enabled=cache_stats["enabled"],
+        cache_size=cache_stats["size"],
+        cache_max_size=cache_stats["max_size"],
+        cache_ttl=cache_stats["ttl"],
+    )

src/api/routes/verification.py

@@ -0,0 +1,143 @@
+"""Verification API routes."""
+from fastapi import APIRouter, HTTPException, status
+from fastapi.responses import JSONResponse
+
+from src.api.schemas import (
+    BibTeXVerifyRequest,
+    BibTeXVerifyResponse,
+    EntryComparisonResponse,
+    DuplicateGroupResponse,
+    ErrorResponse,
+)
+from src.api.dependencies import VerificationServiceDep
+from src.core.logging import get_logger
+from src.core.exceptions import ParserException, FetcherException
+
+logger = get_logger(__name__)
+router = APIRouter(prefix="/api/v1", tags=["verification"])
+
+
+def _get_entry_status(comparison) -> str:
+    """Determine entry status from comparison result."""
+    if comparison and comparison.is_match:
+        return "verified"
+    elif comparison and comparison.has_issues:
+        return "warning"
+    return "error"
+
+
+@router.post(
+    "/verify",
+    response_model=BibTeXVerifyResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Verify BibTeX entries",
+    description="Verify BibTeX entries against multiple academic databases",
+    responses={
+        200: {"description": "Verification completed successfully"},
+        400: {"model": ErrorResponse, "description": "Invalid BibTeX content"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+)
+async def verify_bibtex(
+    request: BibTeXVerifyRequest,
+    service: VerificationServiceDep,
+) -> BibTeXVerifyResponse:
+    """Verify BibTeX entries.
+
+    Args:
+        request: BibTeX verification request
+        service: Verification service instance
+
+    Returns:
+        Verification results
+
+    Raises:
+        HTTPException: If verification fails
+    """
+    try:
+        logger.info("Received BibTeX verification request")
+
+        # Verify BibTeX
+        result = service.verify_bibtex_string(request.bibtex_content)
+
+        # Convert entry reports to response format
+        entries = []
+        for entry_report in result.entry_reports:
+            entry = entry_report.entry
+            comparison = entry_report.comparison
+
+            # Format original BibTeX
+            bibtex_str = f"@{entry.entry_type}{{{entry.key},\n"
+            for field, value in (entry.raw_entry or {}).items():
+                if field in ("ID", "ENTRYTYPE"):
+                    continue
+                if value is not None and str(value).strip():
+                    bibtex_str += f"  {field}={{{value}}},\n"
+            bibtex_str = bibtex_str.rstrip(",\n") + "\n}"
+
+            entry_response = EntryComparisonResponse(
+                key=entry.key,
+                status=_get_entry_status(comparison),
+                is_match=comparison.is_match if comparison else False,
+                has_issues=comparison.has_issues if comparison else False,
+                source=getattr(comparison, "source", None) if comparison else None,
+                confidence=getattr(comparison, "confidence", 0.0) if comparison else 0.0,
+                title_match=comparison.title_match if comparison else False,
+                author_match=comparison.author_match if comparison else False,
+                year_match=comparison.year_match if comparison else False,
+                venue_match=getattr(comparison, "venue_match", None) if comparison else None,
+                fetched_title=getattr(comparison, "fetched_title", None) if comparison else None,
+                fetched_authors=getattr(comparison, "fetched_authors", None) if comparison else None,
+                fetched_year=getattr(comparison, "fetched_year", None) if comparison else None,
+                fetched_doi=getattr(comparison, "fetched_doi", None) if comparison else None,
+                fetched_url=getattr(comparison, "fetched_url", None) if comparison else None,
+                original_bibtex=bibtex_str,
+            )
+            entries.append(entry_response)
+
+        # Convert duplicate groups
+        duplicate_groups = [
+            DuplicateGroupResponse(
+                entry_keys=group.entry_keys,
+                reason=group.reason,
+            )
+            for group in result.duplicate_groups
+        ]
+
+        response = BibTeXVerifyResponse(
+            success=True,
+            message="Verification completed successfully",
+            total_count=result.total_count,
+            verified_count=result.verified_count,
+            warning_count=result.warning_count,
+            error_count=result.error_count,
+            success_rate=result.success_rate,
+            entries=entries,
+            duplicate_groups=duplicate_groups,
+        )
+
+        logger.info(
+            f"Verification completed: {result.verified_count}/{result.total_count} verified"
+        )
+        return response
+
+    except ParserException as e:
+        logger.error(f"Parser error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "ParserError", "message": str(e)},
+        )
+
+    except FetcherException as e:
+        logger.error(f"Fetcher error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"error": "FetcherError", "message": str(e)},
+        )
+
+    except Exception as e:
+        logger.exception(f"Unexpected error during verification: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"error": "InternalError", "message": "An unexpected error occurred"},
+        )

src/api/schemas/__init__.py

@@ -0,0 +1,94 @@
+"""Pydantic schemas for API requests and responses."""
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class BibTeXVerifyRequest(BaseModel):
+    """Request model for BibTeX verification."""
+
+    bibtex_content: str = Field(
+        ...,
+        description="BibTeX content to verify",
+        min_length=1,
+        examples=[
+            """@article{example2023,
+  title={Example Paper Title},
+  author={Smith, John and Doe, Jane},
+  journal={Example Journal},
+  year={2023}
+}"""
+        ],
+    )
+
+
+class EntryComparisonResponse(BaseModel):
+    """Response model for a single entry comparison."""
+
+    key: str = Field(..., description="BibTeX entry key")
+    status: str = Field(..., description="Verification status: verified, warning, or error")
+    is_match: bool = Field(..., description="Whether entry matches a database record")
+    has_issues: bool = Field(..., description="Whether entry has metadata issues")
+    source: Optional[str] = Field(None, description="Data source that verified the entry")
+    confidence: float = Field(..., description="Confidence score (0-1)")
+    title_match: bool = Field(..., description="Whether title matches")
+    author_match: bool = Field(..., description="Whether authors match")
+    year_match: bool = Field(..., description="Whether year matches")
+    venue_match: Optional[bool] = Field(None, description="Whether venue matches")
+    fetched_title: Optional[str] = Field(None, description="Title from database")
+    fetched_authors: Optional[list[str]] = Field(None, description="Authors from database")
+    fetched_year: Optional[str] = Field(None, description="Year from database")
+    fetched_doi: Optional[str] = Field(None, description="DOI from database")
+    fetched_url: Optional[str] = Field(None, description="URL from database")
+    original_bibtex: str = Field(..., description="Original BibTeX entry")
+
+
+class DuplicateGroupResponse(BaseModel):
+    """Response model for duplicate entry groups."""
+
+    entry_keys: list[str] = Field(..., description="Keys of duplicate entries")
+    reason: str = Field(..., description="Reason for duplicate detection")
+
+
+class BibTeXVerifyResponse(BaseModel):
+    """Response model for BibTeX verification."""
+
+    success: bool = Field(..., description="Whether verification completed successfully")
+    message: str = Field(..., description="Status message")
+    total_count: int = Field(..., description="Total number of entries")
+    verified_count: int = Field(..., description="Number of verified entries")
+    warning_count: int = Field(..., description="Number of entries with warnings")
+    error_count: int = Field(..., description="Number of entries with errors")
+    success_rate: float = Field(..., description="Success rate percentage")
+    entries: list[EntryComparisonResponse] = Field(..., description="Verification results for each entry")
+    duplicate_groups: list[DuplicateGroupResponse] = Field(
+        default_factory=list, description="Groups of duplicate entries"
+    )
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Verification timestamp")
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check."""
+
+    status: str = Field(..., description="Service status")
+    version: str = Field(..., description="Application version")
+    environment: str = Field(..., description="Runtime environment")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Current timestamp")
+
+
+class StatsResponse(BaseModel):
+    """Response model for statistics."""
+
+    cache_enabled: bool = Field(..., description="Whether cache is enabled")
+    cache_size: int = Field(..., description="Current cache size")
+    cache_max_size: int = Field(..., description="Maximum cache size")
+    cache_ttl: int = Field(..., description="Cache TTL in seconds")
+
+
+class ErrorResponse(BaseModel):
+    """Response model for errors."""
+
+    error: str = Field(..., description="Error type")
+    message: str = Field(..., description="Error message")
+    details: Optional[dict] = Field(None, description="Additional error details")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="Error timestamp")

src/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core configuration and utilities."""
+from .config import settings
+from .logging import setup_logging, get_logger
+from .cache import cache_manager
+from .exceptions import (
+    CiteScanException,
+    FetcherException,
+    ParserException,
+    ValidationException,
+)
+
+__all__ = [
+    "settings",
+    "setup_logging",
+    "get_logger",
+    "cache_manager",
+    "CiteScanException",
+    "FetcherException",
+    "ParserException",
+    "ValidationException",
+]

src/core/cache.py

@@ -0,0 +1,163 @@
+"""Cache management for CiteScan."""
+import hashlib
+import json
+from typing import Any, Callable, Optional
+from functools import wraps
+from cachetools import TTLCache
+import threading
+
+from .config import settings
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class CacheManager:
+    """Thread-safe cache manager using TTLCache."""
+
+    def __init__(self):
+        """Initialize cache manager."""
+        self._cache: Optional[TTLCache] = None
+        self._lock = threading.Lock()
+        self._initialize_cache()
+
+    def _initialize_cache(self) -> None:
+        """Initialize the cache based on settings."""
+        if settings.cache_enabled:
+            self._cache = TTLCache(
+                maxsize=settings.cache_max_size,
+                ttl=settings.cache_ttl
+            )
+            logger.info(
+                f"Cache initialized: max_size={settings.cache_max_size}, "
+                f"ttl={settings.cache_ttl}s"
+            )
+        else:
+            logger.info("Cache disabled")
+
+    def _generate_key(self, *args, **kwargs) -> str:
+        """Generate a cache key from arguments.
+
+        Args:
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Cache key as hex string
+        """
+        # Create a stable string representation
+        key_data = {
+            "args": args,
+            "kwargs": sorted(kwargs.items())
+        }
+        key_str = json.dumps(key_data, sort_keys=True, default=str)
+        return hashlib.md5(key_str.encode()).hexdigest()
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found
+        """
+        if not settings.cache_enabled or self._cache is None:
+            return None
+
+        with self._lock:
+            value = self._cache.get(key)
+            if value is not None:
+                logger.debug(f"Cache hit: {key}")
+            return value
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        if not settings.cache_enabled or self._cache is None:
+            return
+
+        with self._lock:
+            self._cache[key] = value
+            logger.debug(f"Cache set: {key}")
+
+    def delete(self, key: str) -> None:
+        """Delete value from cache.
+
+        Args:
+            key: Cache key
+        """
+        if not settings.cache_enabled or self._cache is None:
+            return
+
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                logger.debug(f"Cache deleted: {key}")
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        if not settings.cache_enabled or self._cache is None:
+            return
+
+        with self._lock:
+            self._cache.clear()
+            logger.info("Cache cleared")
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache stats
+        """
+        if not settings.cache_enabled or self._cache is None:
+            return {
+                "enabled": False,
+                "size": 0,
+                "max_size": 0,
+                "ttl": 0
+            }
+
+        with self._lock:
+            return {
+                "enabled": True,
+                "size": len(self._cache),
+                "max_size": self._cache.maxsize,
+                "ttl": self._cache.ttl
+            }
+
+    def cached(self, key_prefix: str = "") -> Callable:
+        """Decorator to cache function results.
+
+        Args:
+            key_prefix: Optional prefix for cache key
+
+        Returns:
+            Decorator function
+        """
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                # Generate cache key
+                cache_key = f"{key_prefix}:{func.__name__}:{self._generate_key(*args, **kwargs)}"
+
+                # Try to get from cache
+                cached_value = self.get(cache_key)
+                if cached_value is not None:
+                    return cached_value
+
+                # Call function and cache result
+                result = func(*args, **kwargs)
+                self.set(cache_key, result)
+                return result
+
+            return wrapper
+        return decorator
+
+
+# Global cache manager instance
+cache_manager = CacheManager()

src/core/config.py

@@ -0,0 +1,88 @@
+"""Application configuration using Pydantic Settings."""
+from typing import Literal
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+
+    # Application Settings
+    app_name: str = Field(default="CiteScan", description="Application name")
+    app_version: str = Field(default="1.0.0", description="Application version")
+    environment: Literal["development", "staging", "production"] = Field(
+        default="development",
+        description="Runtime environment"
+    )
+
+    # Server Configuration
+    api_host: str = Field(default="0.0.0.0", description="API server host")
+    api_port: int = Field(default=8000, description="API server port")
+    gradio_host: str = Field(default="0.0.0.0", description="Gradio server host")
+    gradio_port: int = Field(default=7860, description="Gradio server port")
+
+    # API Rate Limiting
+    rate_limit_enabled: bool = Field(default=True, description="Enable rate limiting")
+    rate_limit_requests: int = Field(default=100, description="Max requests per period")
+    rate_limit_period: int = Field(default=60, description="Rate limit period in seconds")
+
+    # Cache Configuration
+    cache_enabled: bool = Field(default=True, description="Enable caching")
+    cache_ttl: int = Field(default=3600, description="Cache TTL in seconds")
+    cache_max_size: int = Field(default=1000, description="Max cached items")
+
+    # Fetcher Configuration
+    arxiv_rate_limit_delay: float = Field(default=3.0, description="arXiv rate limit delay")
+    crossref_rate_limit_delay: float = Field(default=1.0, description="CrossRef rate limit delay")
+    semantic_scholar_rate_limit_delay: float = Field(default=1.0, description="Semantic Scholar rate limit delay")
+    dblp_rate_limit_delay: float = Field(default=1.0, description="DBLP rate limit delay")
+    openalex_rate_limit_delay: float = Field(default=1.0, description="OpenAlex rate limit delay")
+    scholar_rate_limit_delay: float = Field(default=5.0, description="Google Scholar rate limit delay")
+
+    # API Timeouts
+    request_timeout: int = Field(default=30, description="Request timeout in seconds")
+    max_workers: int = Field(default=10, description="Max concurrent workers")
+
+    # Logging
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO",
+        description="Logging level"
+    )
+    log_format: Literal["json", "text"] = Field(default="json", description="Log format")
+    log_file: str = Field(default="logs/citescan.log", description="Log file path")
+
+    # CORS Settings
+    cors_origins: str = Field(
+        default="http://localhost:3000,http://localhost:8080",
+        description="Comma-separated CORS origins"
+    )
+
+    # Optional API Keys
+    semantic_scholar_api_key: str | None = Field(default=None, description="Semantic Scholar API key")
+    crossref_api_key: str | None = Field(default=None, description="CrossRef API key")
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        """Parse CORS origins into a list."""
+        return [origin.strip() for origin in self.cors_origins.split(",") if origin.strip()]
+
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production."""
+        return self.environment == "production"
+
+    @property
+    def is_development(self) -> bool:
+        """Check if running in development."""
+        return self.environment == "development"
+
+
+# Global settings instance
+settings = Settings()

src/core/exceptions.py

@@ -0,0 +1,74 @@
+"""Custom exceptions for CiteScan."""
+
+
+class CiteScanException(Exception):
+    """Base exception for CiteScan."""
+
+    def __init__(self, message: str, details: dict | None = None):
+        """Initialize exception.
+
+        Args:
+            message: Error message
+            details: Optional additional details
+        """
+        self.message = message
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class FetcherException(CiteScanException):
+    """Exception raised by fetchers."""
+
+    def __init__(self, message: str, source: str, details: dict | None = None):
+        """Initialize fetcher exception.
+
+        Args:
+            message: Error message
+            source: Fetcher source (e.g., 'arxiv', 'crossref')
+            details: Optional additional details
+        """
+        self.source = source
+        super().__init__(message, details)
+
+
+class ParserException(CiteScanException):
+    """Exception raised by parsers."""
+
+    pass
+
+
+class ValidationException(CiteScanException):
+    """Exception raised during validation."""
+
+    pass
+
+
+class RateLimitException(FetcherException):
+    """Exception raised when rate limit is exceeded."""
+
+    def __init__(self, source: str, retry_after: int | None = None):
+        """Initialize rate limit exception.
+
+        Args:
+            source: Fetcher source
+            retry_after: Seconds to wait before retry
+        """
+        self.retry_after = retry_after
+        message = f"Rate limit exceeded for {source}"
+        if retry_after:
+            message += f". Retry after {retry_after} seconds"
+        super().__init__(message, source)
+
+
+class TimeoutException(FetcherException):
+    """Exception raised when request times out."""
+
+    def __init__(self, source: str, timeout: int):
+        """Initialize timeout exception.
+
+        Args:
+            source: Fetcher source
+            timeout: Timeout value in seconds
+        """
+        message = f"Request to {source} timed out after {timeout} seconds"
+        super().__init__(message, source)

src/core/logging.py

@@ -0,0 +1,107 @@
+"""Logging configuration for CiteScan."""
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+import json
+from datetime import datetime
+
+from .config import settings
+
+
+class JSONFormatter(logging.Formatter):
+    """Custom JSON formatter for structured logging."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record as JSON."""
+        log_data: dict[str, Any] = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        # Add extra fields
+        if hasattr(record, "extra"):
+            log_data.update(record.extra)
+
+        return json.dumps(log_data, ensure_ascii=False)
+
+
+class TextFormatter(logging.Formatter):
+    """Custom text formatter with colors for console output."""
+
+    COLORS = {
+        "DEBUG": "\033[36m",      # Cyan
+        "INFO": "\033[32m",       # Green
+        "WARNING": "\033[33m",    # Yellow
+        "ERROR": "\033[31m",      # Red
+        "CRITICAL": "\033[35m",   # Magenta
+    }
+    RESET = "\033[0m"
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with colors."""
+        color = self.COLORS.get(record.levelname, self.RESET)
+        record.levelname = f"{color}{record.levelname}{self.RESET}"
+        return super().format(record)
+
+
+def setup_logging() -> None:
+    """Setup logging configuration based on settings."""
+    # Create logs directory if it doesn't exist
+    log_file_path = Path(settings.log_file)
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, settings.log_level))
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(getattr(logging, settings.log_level))
+
+    if settings.log_format == "json":
+        console_formatter = JSONFormatter()
+    else:
+        console_formatter = TextFormatter(
+            fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S"
+        )
+
+    console_handler.setFormatter(console_formatter)
+    root_logger.addHandler(console_handler)
+
+    # File handler (always JSON for easier parsing)
+    file_handler = logging.FileHandler(log_file_path, encoding="utf-8")
+    file_handler.setLevel(getattr(logging, settings.log_level))
+    file_handler.setFormatter(JSONFormatter())
+    root_logger.addHandler(file_handler)
+
+    # Reduce noise from third-party libraries
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("asyncio").setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance with the given name.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

src/services/__init__.py

@@ -0,0 +1,4 @@
+"""Business logic services."""
+from .verification_service import VerificationService
+
+__all__ = ["VerificationService"]

src/services/verification_service.py

@@ -0,0 +1,273 @@
+"""Verification service for BibTeX entries.
+
+This service extracts the core verification logic from app.py,
+making it reusable for both Gradio UI and FastAPI endpoints.
+"""
+import tempfile
+import threading
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Optional
+
+from src.parsers import BibParser
+from src.fetchers import (
+    ArxivFetcher,
+    ScholarFetcher,
+    CrossRefFetcher,
+    SemanticScholarFetcher,
+    OpenAlexFetcher,
+    DBLPFetcher,
+)
+from src.analyzers import MetadataComparator, DuplicateDetector
+from src.report.generator import EntryReport
+from src.config.workflow import get_default_workflow
+from src.utils.normalizer import TextNormalizer
+from src.core.config import settings
+from src.core.logging import get_logger
+from src.core.exceptions import ParserException, FetcherException
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class VerificationResult:
+    """Result of BibTeX verification."""
+
+    entry_reports: list[EntryReport]
+    duplicate_groups: list
+    verified_count: int
+    warning_count: int
+    error_count: int
+    total_count: int
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate."""
+        if self.total_count == 0:
+            return 0.0
+        return (self.verified_count / self.total_count) * 100
+
+
+class VerificationService:
+    """Service for verifying BibTeX entries against academic databases."""
+
+    def __init__(self):
+        """Initialize verification service."""
+        self.parser = BibParser()
+        self.arxiv_fetcher = ArxivFetcher()
+        self.crossref_fetcher = CrossRefFetcher()
+        self.scholar_fetcher = ScholarFetcher()
+        self.semantic_scholar_fetcher = SemanticScholarFetcher()
+        self.openalex_fetcher = OpenAlexFetcher()
+        self.dblp_fetcher = DBLPFetcher()
+        self.comparator = MetadataComparator()
+        self.duplicate_detector = DuplicateDetector()
+        logger.info("VerificationService initialized")
+
+    def verify_bibtex_string(
+        self,
+        bibtex_content: str,
+        progress_callback: Optional[callable] = None,
+    ) -> VerificationResult:
+        """Verify BibTeX content from string.
+
+        Args:
+            bibtex_content: BibTeX content as string
+            progress_callback: Optional callback for progress updates (progress, desc)
+
+        Returns:
+            VerificationResult with all verification data
+
+        Raises:
+            ParserException: If BibTeX parsing fails
+            FetcherException: If fetching fails
+        """
+        if not bibtex_content.strip():
+            raise ParserException("Empty BibTeX content provided")
+
+        logger.info("Starting BibTeX verification")
+
+        # Parse BibTeX
+        try:
+            if progress_callback:
+                progress_callback(0, "Parsing BibTeX...")
+
+            # Write to temporary file
+            with tempfile.NamedTemporaryFile(
+                mode="w", suffix=".bib", delete=False, encoding="utf-8"
+            ) as f:
+                f.write(bibtex_content)
+                temp_bib_path = f.name
+
+            entries = self.parser.parse_file(temp_bib_path)
+            Path(temp_bib_path).unlink()  # Delete temp file
+
+            if not entries:
+                raise ParserException("No valid BibTeX entries found")
+
+            logger.info(f"Parsed {len(entries)} BibTeX entries")
+
+        except Exception as e:
+            logger.error(f"BibTeX parsing failed: {e}")
+            raise ParserException(f"Failed to parse BibTeX: {str(e)}")
+
+        # Detect duplicates
+        duplicate_groups = self.duplicate_detector.find_duplicates(entries)
+        if duplicate_groups:
+            logger.warning(f"Found {len(duplicate_groups)} duplicate groups")
+
+        # Get workflow configuration
+        workflow_config = get_default_workflow()
+
+        # Process entries
+        entry_reports = []
+        progress_lock = threading.Lock()
+        verified_count = 0
+        warning_count = 0
+        error_count = 0
+
+        if progress_callback:
+            progress_callback(0.1, "Initializing fetchers...")
+
+        def process_single_entry(entry, idx, total):
+            """Process a single BibTeX entry."""
+            comparison_result = None
+            all_results = []
+
+            for step in workflow_config.get_enabled_steps():
+                result = None
+
+                try:
+                    if step.name == "arxiv_id" and entry.has_arxiv and self.arxiv_fetcher:
+                        arxiv_meta = self.arxiv_fetcher.fetch_by_id(entry.arxiv_id)
+                        if arxiv_meta:
+                            result = self.comparator.compare_with_arxiv(entry, arxiv_meta)
+
+                    elif step.name == "crossref_doi" and entry.doi and self.crossref_fetcher:
+                        crossref_result = self.crossref_fetcher.search_by_doi(entry.doi)
+                        if crossref_result:
+                            result = self.comparator.compare_with_crossref(entry, crossref_result)
+
+                    elif step.name == "semantic_scholar" and entry.title and self.semantic_scholar_fetcher:
+                        ss_result = (
+                            self.semantic_scholar_fetcher.fetch_by_doi(entry.doi)
+                            if entry.doi
+                            else None
+                        )
+                        if not ss_result:
+                            ss_result = self.semantic_scholar_fetcher.search_by_title(entry.title)
+                        if ss_result:
+                            result = self.comparator.compare_with_semantic_scholar(entry, ss_result)
+
+                    elif step.name == "dblp" and entry.title and self.dblp_fetcher:
+                        dblp_result = self.dblp_fetcher.search_by_title(entry.title)
+                        if dblp_result:
+                            result = self.comparator.compare_with_dblp(entry, dblp_result)
+
+                    elif step.name == "openalex" and entry.title and self.openalex_fetcher:
+                        oa_result = (
+                            self.openalex_fetcher.fetch_by_doi(entry.doi)
+                            if entry.doi
+                            else None
+                        )
+                        if not oa_result:
+                            oa_result = self.openalex_fetcher.search_by_title(entry.title)
+                        if oa_result:
+                            result = self.comparator.compare_with_openalex(entry, oa_result)
+
+                    elif step.name == "arxiv_title" and entry.title and self.arxiv_fetcher:
+                        results = self.arxiv_fetcher.search_by_title(entry.title, max_results=3)
+                        if results:
+                            best_result = None
+                            best_sim = 0.0
+                            norm1 = TextNormalizer.normalize_for_comparison(entry.title)
+                            for r in results:
+                                sim = TextNormalizer.similarity_ratio(
+                                    norm1,
+                                    TextNormalizer.normalize_for_comparison(r.title),
+                                )
+                                if sim > best_sim:
+                                    best_sim, best_result = sim, r
+                            if best_result and best_sim > 0.5:
+                                result = self.comparator.compare_with_arxiv(entry, best_result)
+
+                    elif step.name == "crossref_title" and entry.title and self.crossref_fetcher:
+                        crossref_result = self.crossref_fetcher.search_by_title(entry.title)
+                        if crossref_result:
+                            result = self.comparator.compare_with_crossref(entry, crossref_result)
+
+                    elif step.name == "google_scholar" and entry.title and self.scholar_fetcher:
+                        scholar_result = self.scholar_fetcher.search_by_title(entry.title)
+                        if scholar_result:
+                            result = self.comparator.compare_with_scholar(entry, scholar_result)
+
+                except Exception as e:
+                    logger.warning(f"Error in step {step.name} for entry {entry.key}: {e}")
+                    continue
+
+                if result:
+                    all_results.append(result)
+                    if result.is_match:
+                        comparison_result = result
+                        break
+
+            # Select best result if no perfect match
+            if not comparison_result and all_results:
+                all_results.sort(key=lambda r: r.confidence, reverse=True)
+                comparison_result = all_results[0]
+            elif not comparison_result:
+                comparison_result = self.comparator.create_unable_result(
+                    entry, "Unable to find this paper in any data source"
+                )
+
+            return EntryReport(entry=entry, comparison=comparison_result)
+
+        # Process entries concurrently
+        max_workers = min(settings.max_workers, len(entries))
+        logger.info(f"Processing {len(entries)} entries with {max_workers} workers")
+
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            future_to_entry = {
+                executor.submit(process_single_entry, e, i, len(entries)): (e, i)
+                for i, e in enumerate(entries)
+            }
+
+            for future in as_completed(future_to_entry):
+                entry, idx = future_to_entry[future]
+                try:
+                    entry_report = future.result()
+                    with progress_lock:
+                        entry_reports.append(entry_report)
+
+                        if entry_report.comparison and entry_report.comparison.is_match:
+                            verified_count += 1
+                        elif entry_report.comparison and entry_report.comparison.has_issues:
+                            warning_count += 1
+                        else:
+                            error_count += 1
+
+                        if progress_callback:
+                            progress_callback(
+                                0.1 + (0.9 * (idx + 1) / len(entries)),
+                                f"Verifying entries {idx + 1}/{len(entries)}...",
+                            )
+
+                except Exception as e:
+                    with progress_lock:
+                        error_count += 1
+                        logger.error(f"Error processing entry {entry.key}: {e}")
+
+        logger.info(
+            f"Verification complete: {verified_count} verified, "
+            f"{warning_count} warnings, {error_count} errors"
+        )
+
+        return VerificationResult(
+            entry_reports=entry_reports,
+            duplicate_groups=duplicate_groups,
+            verified_count=verified_count,
+            warning_count=warning_count,
+            error_count=error_count,
+            total_count=len(entries),
+        )

start.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Startup script for running both Gradio and API services
+
+set -e
+
+# Load environment variables
+if [ -f .env ]; then
+    export $(cat .env | grep -v '^#' | xargs)
+fi
+
+# Default mode
+MODE=${1:-"both"}
+
+case "$MODE" in
+    "api")
+        echo "Starting FastAPI service..."
+        python main.py
+        ;;
+    "gradio")
+        echo "Starting Gradio service..."
+        python app.py
+        ;;
+    "both")
+        echo "Starting both services..."
+        python main.py &
+        API_PID=$!
+        python app.py &
+        GRADIO_PID=$!
+
+        # Wait for both processes
+        wait $API_PID
+        wait $GRADIO_PID
+        ;;
+    *)
+        echo "Usage: $0 {api|gradio|both}"
+        exit 1
+        ;;
+esac