Alfanous provides a powerful Arabic search engine API for the Holy Qur'an, enabling developers to build applications with advanced search capabilities. It offers simple and complex querying, rich metadata access, and flexible integration options for developers working with Quranic text.

How It Works

The system functions as both a Python library and a RESTful web service, leveraging a sophisticated query parser and an indexing backend to handle complex search operations. It supports standard Arabic, Buckwalter transliteration, and advanced syntax including Boolean logic, fielded search, wildcards, and root/lemma analysis. Results can be aggregated via faceted search and customized through various output views.

Quick Start & Requirements

Installation is straightforward via pip: pip install alfanous3. For the web service, additional dependencies (fastapi, uvicorn) are required, with setup involving cd src/ and running uvicorn alfanous_webapi.web_api:app --reload. A separate alfanous3-mcp package enables integration with AI assistants. Development requires cloning the repository, installing pyparsing, whoosh, pytest, and running make build. Official documentation links are available within the README.

Highlighted Details

• Advanced Query Syntax: Supports phrases, Boolean operators (AND, OR, NOT), fielded search (e.g., سورة:يس), wildcards (*, ?), ranges, root/lemma analysis (>>, >), and tuples.
• Faceted Search & Filtering: Allows aggregation of results by fields like sura_id, juz, chapter, and filtering by specific values (e.g., filter={"sura_id": "2"}).
• Rich Metadata & Extensibility: Provides access to translations, recitations, linguistic data, and allows adding custom translations via .trans.zip files.
• AI Integration (MCP): Includes an MCP server for direct integration with AI assistants like Claude and Copilot.
• Web Interface: Offers a FastAPI-based RESTful API with interactive Swagger UI documentation.

Maintenance & Community

Support is primarily channeled through GitHub Issues and a Google Groups mailing list. Contribution guidelines are detailed in CONTRIBUTING.md, with contributor lists in AUTHORS.md and THANKS.md. No specific community chat platforms (like Discord/Slack) or active sponsorships are highlighted.

Licensing & Compatibility

The project is licensed under the GNU Lesser General Public License v3 or later (LGPLv3+). This license permits commercial use and linking with closed-source applications, provided that modifications to the LGPL-licensed components themselves are made available under the same license.

Limitations & Caveats

The README does not explicitly detail technical limitations, performance benchmarks, or known bugs. It emphasizes respectful handling of the sacred text data. A legacy branch exists for older versions.