[](https://badge.fury.io/py/findora)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/findora)
[](https://www.linkedin.com/in/eugene-evstafev-716669181/)
# findora
`findora` is an LLM-assisted search utility.
Give it a plain-text query and it returns a curated list of links with titles and descriptions, after:
* validating the query with a small language-model prompt
* **optionally** enhancing that query for better recall/precision
* running iterative searches while:
* deduplicating URLs
* honouring language & geo preferences
* respecting result and iteration caps
It is ideal for chat-bots, data-gathering pipelines, academic tooling, or anywhere you need a “few good links” rather than an HTML page of unstructured results.
---
## Installation
```bash
pip install findora
```
Python ≥ 3.8 is required.
---
## Quick start
```python
from findora import findora
results = findora(
search_query="Eugene Evstafev",
n=10,
enhance=False,
verbose=False,
language="en-US",
location="UK",
)
print(results)
```
Example output (truncated/pretty-printed):
```python
[
{
"title": "Eugene Evstafev – Google Scholar",
"url": "https://scholar.google.com/citations?user=cYLfW7QAAAAJ&hl=en",
"desc": "Eugene Evstafev, University of Cambridge. Topics include computer science …",
},
{
"title": "How A24 Changed Contemporary Cinema – Medium",
"url": "https://medium.com/@chigwel/how-a24-changed-contemporary-cinema-5dc69c0b00c2",
"desc": "Article discussing the impact of A24 films and the 2023 Oscars success …",
},
…
]
```
---
## API
```python
findora(
search_query: str,
llm: Optional[Any] = None, # custom ChatLLM7-compatible object
n: int = 10, # max results (1 – 10)
enhance: bool = True, # turn query rewriting on/off
verbose: bool = False, # print prompt/response trace
max_retries: int = 15, # LLM retry budget
language: str = "en-US", # BCP-47 tag passed to the search prompt
location: str = "World", # free-text geographical hint
max_iterations: int = 55, # safety stop for the search loop
) -> list[dict]
```
Raises `ValueError` for:
* empty or > 1024-char queries
* `n > 10`
* invalid query as judged by the model.
---
## Features
* 🔍 **LLM-powered query understanding** – prevents garbage queries early.
* ✨ **Optional query enhancement** – adds synonyms, context and localised terms.
* 🗺 **Language & region control** – pass `language`/`location` and let the model obey.
* 🚫 **Deduplication & “exclude” list** – zero duplicated links across iterations.
* 🧪 **Deterministic unit-tested core** – 100 % tests pass with mocked LLMs.
---
## Contributing
Bug reports, pull requests and feature ideas are welcome!
Head over to the [issue tracker](https://github.com/chigwell/findora/issues) to get started.
1. Fork the repository
2. Create a feature branch
3. Run the test suite with **pytest**
4. Open a PR
Please run `black` and `isort` before submitting.
---
## License
`findora` is distributed under the [MIT License](https://choosealicense.com/licenses/mit/).
---
## Links
* 🐙 GitHub → <https://github.com/chigwell/findora>
* 📦 PyPI → <https://pypi.org/project/findora/>
* 👤 Author → [Eugene Evstafev](https://www.linkedin.com/in/eugene-evstafev-716669181/)
Raw data
{
"_id": null,
"home_page": "https://github.com/chigwell/findora",
"name": "findora",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Eugene Evstafev",
"author_email": "chigwel@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/67/9d/fb11ee263a6564004c9a4508020560b8358bebfb6969fd540e2c26ac50d7/findora-2025.7.131053.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/findora)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/findora)\n[](https://www.linkedin.com/in/eugene-evstafev-716669181/)\n\n# findora\n\n`findora` is an LLM-assisted search utility. \nGive it a plain-text query and it returns a curated list of links with titles and descriptions, after:\n\n* validating the query with a small language-model prompt\n* **optionally** enhancing that query for better recall/precision\n* running iterative searches while:\n * deduplicating URLs\n * honouring language & geo preferences\n * respecting result and iteration caps\n\nIt is ideal for chat-bots, data-gathering pipelines, academic tooling, or anywhere you need a \u201cfew good links\u201d rather than an HTML page of unstructured results.\n\n---\n\n## Installation\n\n```bash\npip install findora\n```\n\nPython \u2265 3.8 is required.\n\n---\n\n## Quick start\n\n```python\nfrom findora import findora\n\nresults = findora(\n search_query=\"Eugene Evstafev\",\n n=10,\n enhance=False,\n verbose=False,\n language=\"en-US\",\n location=\"UK\",\n)\n\nprint(results)\n```\n\nExample output (truncated/pretty-printed):\n\n```python\n[\n {\n \"title\": \"Eugene Evstafev \u2013 Google Scholar\",\n \"url\": \"https://scholar.google.com/citations?user=cYLfW7QAAAAJ&hl=en\",\n \"desc\": \"Eugene Evstafev, University of Cambridge. Topics include computer science \u2026\",\n },\n {\n \"title\": \"How A24 Changed Contemporary Cinema \u2013 Medium\",\n \"url\": \"https://medium.com/@chigwel/how-a24-changed-contemporary-cinema-5dc69c0b00c2\",\n \"desc\": \"Article discussing the impact of A24 films and the 2023 Oscars success \u2026\",\n },\n \u2026\n]\n```\n\n---\n\n## API\n\n```python\nfindora(\n search_query: str,\n llm: Optional[Any] = None, # custom ChatLLM7-compatible object\n n: int = 10, # max results (1 \u2013 10)\n enhance: bool = True, # turn query rewriting on/off\n verbose: bool = False, # print prompt/response trace\n max_retries: int = 15, # LLM retry budget\n language: str = \"en-US\", # BCP-47 tag passed to the search prompt\n location: str = \"World\", # free-text geographical hint\n max_iterations: int = 55, # safety stop for the search loop\n) -> list[dict]\n```\n\nRaises `ValueError` for:\n\n* empty or > 1024-char queries \n* `n > 10` \n* invalid query as judged by the model.\n\n---\n\n## Features\n\n* \ud83d\udd0d **LLM-powered query understanding** \u2013 prevents garbage queries early. \n* \u2728 **Optional query enhancement** \u2013 adds synonyms, context and localised terms. \n* \ud83d\uddfa **Language & region control** \u2013 pass `language`/`location` and let the model obey. \n* \ud83d\udeab **Deduplication & \u201cexclude\u201d list** \u2013 zero duplicated links across iterations. \n* \ud83e\uddea **Deterministic unit-tested core** \u2013 100 % tests pass with mocked LLMs. \n\n---\n\n## Contributing\n\nBug reports, pull requests and feature ideas are welcome! \nHead over to the [issue tracker](https://github.com/chigwell/findora/issues) to get started.\n\n1. Fork the repository \n2. Create a feature branch \n3. Run the test suite with **pytest** \n4. Open a PR\n\nPlease run `black` and `isort` before submitting.\n\n---\n\n## License\n\n`findora` is distributed under the [MIT License](https://choosealicense.com/licenses/mit/).\n\n---\n\n## Links\n\n* \ud83d\udc19 GitHub \u2192 <https://github.com/chigwell/findora> \n* \ud83d\udce6 PyPI \u2192 <https://pypi.org/project/findora/> \n* \ud83d\udc64 Author \u2192 [Eugene Evstafev](https://www.linkedin.com/in/eugene-evstafev-716669181/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Search engine",
"version": "2025.7.131053",
"project_urls": {
"Homepage": "https://github.com/chigwell/findora"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8dc59ae6f35159e5036dd2cab5648679869efde37e5d4a17dd4ebb3bdab5bd6f",
"md5": "66482dd9ea65516c3f32010beb74abe7",
"sha256": "7a7e73cf1582c81441ab60e6355b6f1dc11970779a14dc785d97e53e5e9fa4d4"
},
"downloads": -1,
"filename": "findora-2025.7.131053-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66482dd9ea65516c3f32010beb74abe7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 13151,
"upload_time": "2025-07-13T09:54:03",
"upload_time_iso_8601": "2025-07-13T09:54:03.157655Z",
"url": "https://files.pythonhosted.org/packages/8d/c5/9ae6f35159e5036dd2cab5648679869efde37e5d4a17dd4ebb3bdab5bd6f/findora-2025.7.131053-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "679dfb11ee263a6564004c9a4508020560b8358bebfb6969fd540e2c26ac50d7",
"md5": "11a6e4f71c32566c2a84f5b3a93b4d6c",
"sha256": "fb79a9f5dea8b3b168d9741f617b88834a591bfbe06d56aa0f6ea962c15d1703"
},
"downloads": -1,
"filename": "findora-2025.7.131053.tar.gz",
"has_sig": false,
"md5_digest": "11a6e4f71c32566c2a84f5b3a93b4d6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12114,
"upload_time": "2025-07-13T09:54:05",
"upload_time_iso_8601": "2025-07-13T09:54:05.540596Z",
"url": "https://files.pythonhosted.org/packages/67/9d/fb11ee263a6564004c9a4508020560b8358bebfb6969fd540e2c26ac50d7/findora-2025.7.131053.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 09:54:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chigwell",
"github_project": "findora",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "findora"
}
JSON
