README.md

---
title: Church Fathers Commentary Search API
emoji: ✝️
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit
---

# Church Fathers Commentary Search API

Semantic search over Church Fathers' New Testament commentaries using BGE-large embeddings. This API keeps the model and embeddings in memory for fast responses (~50-100ms after initial load).

## Features

- ✅ Fast semantic search with BGE-large-en-v1.5 embeddings
- ✅ Model stays loaded in memory (no cold starts)
- ✅ Searches commentaries from 9 prominent Church Fathers
- ✅ Filter by book or father
- ✅ CORS enabled for easy integration
- ✅ RESTful JSON API with FastAPI
- ✅ Automatic API documentation at `/docs`

## API Endpoints

### `GET /`
Health check and API information

### `GET /health`
Detailed health status, available books, and fathers

### `POST /search`
Perform semantic search over commentaries

**Request Body:**
```json
{
  "query": "What did the fathers say about baptism?",
  "limit": 10,
  "books": ["matthew", "john"],  // Optional: filter by books
  "fathers": ["Augustine of Hippo"]  // Optional: filter by fathers
}
```

**Response:**
```json
{
  "query": "What did the fathers say about baptism?",
  "results": [
    {
      "book": "matthew",
      "father_name": "Augustine of Hippo",
      "source_title": "Tractates on the Gospel of John",
      "content": "Commentary text here...",
      "similarity": 0.892,
      "location_start": "Mt 3:13",
      "location_end": "Mt 3:17"
    }
  ],
  "total_searched": 4523,
  "execution_time_ms": 87.3
}
```

## Available Church Fathers

- Augustine of Hippo
- Athanasius of Alexandria
- Basil of Caesarea
- Gregory of Nazianzus
- Gregory of Nyssa
- Cyril of Alexandria
- Irenaeus
- Cyprian
- Origen of Alexandria

## Available Books

All 27 New Testament books: matthew, mark, luke, john, acts, romans, 1corinthians, 2corinthians, galatians, ephesians, philippians, colossians, 1thessalonians, 2thessalonians, 1timothy, 2timothy, titus, philemon, hebrews, james, 1peter, 2peter, 1john, 2john, 3john, jude, revelation

## Quick Start

### Using cURL
```bash
curl -X POST https://dssjon-biblos-cf-api.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "grace and faith",
    "limit": 5
  }'
```

### Using JavaScript
```javascript
const response = await fetch('https://dssjon-biblos-cf-api.hf.space/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'grace and faith',
    limit: 5,
    books: ['romans', 'ephesians']
  })
})

const data = await response.json()
console.log(data.results)
```

### Using Python
```python
import requests

response = requests.post(
    'https://dssjon-biblos-cf-api.hf.space/search',
    json={
        'query': 'grace and faith',
        'limit': 5,
        'fathers': ['Augustine of Hippo']
    }
)

data = response.json()
print(data['results'])
```

## Interactive Documentation

Visit `/docs` on your deployed Space for interactive Swagger UI documentation where you can test the API directly.

## Performance

- First request: ~2-3 seconds (model loading)
- Subsequent requests: **50-100ms** (model already in memory)
- No cold starts after initial load
- Supports concurrent requests

## Model Information

- **Model:** BAAI/bge-large-en-v1.5
- **Embedding dimensions:** 1024
- **Commentary sources:** Historical Christian Faith Commentaries Database

## Data Source

The commentaries are sourced from the [Historical Christian Faith Commentaries Database](https://github.com/HistoricalChristianFaith/Commentaries-Database), an open-source collection of manually curated commentary texts from early Church Fathers.

## Deployment

This Space uses Docker SDK with FastAPI. The model and embeddings are loaded once at startup and kept in memory for fast responses.

## Local Development

1. Prepare data:
```bash
python prepare_data.py --source ../church-fathers/commentary_embeddings
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Run locally:
```bash
uvicorn app:app --reload
```

4. Visit http://localhost:8000/docs for interactive API documentation

## License

MIT License - Free to use for any purpose

## Acknowledgments

- [Historical Christian Faith Commentaries Database](https://github.com/HistoricalChristianFaith/Commentaries-Database) for the original commentary data
- Hugging Face and the BGE team for the embedding model
- Anthropic Claude for assisting with development