# Deepground
<div align=center>
[](https://www.python.org/)
Deepground – Clearnet + Darknet Search & Fetcher
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/evilfeonix/deepground)
[](https://github.com/evilfeonix/deepground)
[](https://github.com/evilfeonix/deepground/stargazers)
[](https://github.com/evilfeonix/deepground/network/members)
</div>
Deepground - this is a Python library that empowers LLM agents with real-time data access from buth the clearnet and darknet.\
This library is design for developers, hackers, pentesters, researchers, and AI agents who need real-time datas from both the clearnet and darknet to their CLI.
## Overview
The deepground project was developed by evilfeonix and designed to evaluate the performance of llm and their applications. It gives your LLM the power to access and monitor real-time data from the net for free without limitation or restriction.
<!-- gpt: add more overview of the grounder project here -->
## Features
- Support sync / async(parallel fetching) mode, depending on your workflow.
- Fetch context and extract sources (raw HTML/code/text) from URLs.
- Integrate seamlessly with LangChain and other LLM frameworks.
- Searches across clearnet/darknet sources with ease.
- Built-in caching + logging
- Error handling
## Installation
```bash
pip install deepground
```
For dev:
```bash
git clone https://github.com/evilfeonix/deepground.git
cd deepground
pip install -e .
python3 run.py
```
## Usage
### Simple Usage:
```py
from deepground.core import Grounder
g = Grounder()
print(g.search("latest AI news"))
g_tor = Grounder(use_tor=True)
print(g_tor.dark_search("leaked databases"))
```
### Synchronous:
```py
from deepground.core import Grounder
# Clearnet search
g = Grounder(use_tor=False)
r = g.search("Python hacking", limit=3)
print(r)
# Darknet search
g_tor = Grounder(use_tor=True)
d_r = g_tor.dark_search("market", limit=3)
print(d_r)
# Fetch readable content (page)
p = g.fetch_context("https://example.com")
print(p["content"])
# Fetch row source (code/text)
s = g_tor.fetch_source("https://somesite.onion/ABCDEF.txt")
print(s["source"])
```
### Asynchronous:
```py
import asyncio
from deepground.core import GrounderAsync
async def main():
async with GrounderAsync(use_tor=False) as g:
results = await g.search("cybersecurity news", limit=3)
print(results)
source = await g.multi-fetch("https://example.com,https://example.net", context=False)
print(source["source"][:300])
asyncio.run(main())
```
### LangChain Integration:
```py
from deepground.core import GrounderTool
tool = GrounderTool(use_tor=True)
print(tool._run("search:latest AI news"))
print(tool._run("dark_search:proxies combo list"))
print(tool._run("fetch_context:https://github.com"))
print(tool._run("fetch_source:https://somesite.onion"))
print(tool._run("multi-fetch:https://ss1.onion,https://ss2.onion"))
```
## Langchain Agent
Feed results directly into your LLM agents for grounded, real-world context:
```py
from deepground.core import Grounder
# Clearnet search
g = Grounder()
res = g.search("naija latest tech news")
ctx = g.fetch_context("https://example.com/article")
# Darknet search with Tor
g_tor = Grounder(use_tor=True)
d_res = g_tor.dark_search("fresh proxies list")
d_ctx = g_tor.fetch_context("http://somesite.onion/article")
# Feed into LLM
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
answer = llm.invoke(f"Summarize:\n\n{ctx}")
print(answer)
```
## For darknet features:
TOR running locally (socks5://127.0.0.1:9050)
```bash
pip install requests[socks]
```
## Logging & Caching
```bash
Cache stored at: ~/.deepground/cache
Log file: ~/.deepground/deepground.log
```
## Documentation
Detailed documentation includeing full guides, and examples can be found at our official website https://evilfeonix.eu.org
## Contrubuting
Contributors are welcome to this journey, feel free to :
- Report bugs via github issues.
- Suggest feature with use cases.
- Submit PRs with clear description.
## Disclaimer
> _This library is for educational and research purposes only. Authors will never ever be responsible for any misuse or damage cause by this project._
## LICENSE
Use MIT license:
```text
MIT License
Copyright (c) 2025 Evilfeonix
Permission is hereby granted, free of charge...
```
## Powered by
This project is made posibly thanks to those infrastructure with their generous supports.
[](https://www.python.org/)
[](LICENSE)
[](https://www.python.org/)
[](LICENSE)
[](https://www.python.org/)
[](LICENSE)
[](https://www.python.org/)
[](https://pypi.org/project/deepground-evilfeonix/)
[](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/evilfeonix/deepground",
"name": "deepground",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "LLM, real-time, darknet, search, osint, tor, ai, darkweb, groundX, groundnet, deepground, grounder, evilfeonix, grounding info, information gathering",
"author": "Evilfeonix",
"author_email": "Evilfeonix <evilfeonix@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/54/96/a5d2a9ad1c8165f4dfa41d3603ad84689d1c6522a8442c38af2e91e7623f/deepground-0.8.2.tar.gz",
"platform": null,
"description": "# Deepground\r\n<div align=center>\r\n\r\n[](https://www.python.org/)\r\n\r\nDeepground \u2013 Clearnet + Darknet Search & Fetcher\r\n\r\n[](https://www.python.org/)\r\n[](LICENSE)\r\n\r\n[](https://github.com/evilfeonix/deepground) \r\n[](https://github.com/evilfeonix/deepground) \r\n[](https://github.com/evilfeonix/deepground/stargazers) \r\n[](https://github.com/evilfeonix/deepground/network/members) \r\n</div>\r\n\r\nDeepground - this is a Python library that empowers LLM agents with real-time data access from buth the clearnet and darknet.\\\r\nThis library is design for developers, hackers, pentesters, researchers, and AI agents who need real-time datas from both the clearnet and darknet to their CLI.\r\n\r\n\r\n## Overview\r\nThe deepground project was developed by evilfeonix and designed to evaluate the performance of llm and their applications. It gives your LLM the power to access and monitor real-time data from the net for free without limitation or restriction.\r\n<!-- gpt: add more overview of the grounder project here -->\r\n\r\n\r\n## Features\r\n- Support sync / async(parallel fetching) mode, depending on your workflow.\r\n- Fetch context and extract sources (raw HTML/code/text) from URLs.\r\n- Integrate seamlessly with LangChain and other LLM frameworks.\r\n- Searches across clearnet/darknet sources with ease.\r\n- Built-in caching + logging\r\n- Error handling\r\n\r\n \r\n## Installation\r\n```bash\r\npip install deepground\r\n```\r\n\r\nFor dev:\r\n```bash\r\ngit clone https://github.com/evilfeonix/deepground.git\r\ncd deepground\r\npip install -e .\r\npython3 run.py\r\n```\r\n\r\n## Usage\r\n### Simple Usage:\r\n```py\r\nfrom deepground.core import Grounder\r\n\r\ng = Grounder()\r\nprint(g.search(\"latest AI news\"))\r\n\r\ng_tor = Grounder(use_tor=True)\r\nprint(g_tor.dark_search(\"leaked databases\"))\r\n```\r\n\r\n### Synchronous:\r\n```py\r\nfrom deepground.core import Grounder\r\n\r\n\r\n# Clearnet search\r\ng = Grounder(use_tor=False)\r\nr = g.search(\"Python hacking\", limit=3)\r\nprint(r)\r\n\r\n# Darknet search\r\ng_tor = Grounder(use_tor=True)\r\nd_r = g_tor.dark_search(\"market\", limit=3)\r\nprint(d_r)\r\n\r\n# Fetch readable content (page)\r\np = g.fetch_context(\"https://example.com\")\r\nprint(p[\"content\"])\r\n\r\n# Fetch row source (code/text)\r\ns = g_tor.fetch_source(\"https://somesite.onion/ABCDEF.txt\")\r\nprint(s[\"source\"])\r\n```\r\n\r\n### Asynchronous:\r\n```py\r\nimport asyncio\r\nfrom deepground.core import GrounderAsync\r\n\r\nasync def main():\r\n async with GrounderAsync(use_tor=False) as g:\r\n results = await g.search(\"cybersecurity news\", limit=3)\r\n print(results)\r\n\r\n source = await g.multi-fetch(\"https://example.com,https://example.net\", context=False)\r\n print(source[\"source\"][:300])\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### LangChain Integration:\r\n```py\r\nfrom deepground.core import GrounderTool\r\n\r\ntool = GrounderTool(use_tor=True)\r\n\r\nprint(tool._run(\"search:latest AI news\"))\r\nprint(tool._run(\"dark_search:proxies combo list\"))\r\nprint(tool._run(\"fetch_context:https://github.com\"))\r\nprint(tool._run(\"fetch_source:https://somesite.onion\"))\r\nprint(tool._run(\"multi-fetch:https://ss1.onion,https://ss2.onion\"))\r\n```\r\n\r\n## Langchain Agent\r\nFeed results directly into your LLM agents for grounded, real-world context:\r\n```py\r\nfrom deepground.core import Grounder\r\n\r\n# Clearnet search\r\ng = Grounder()\r\nres = g.search(\"naija latest tech news\")\r\nctx = g.fetch_context(\"https://example.com/article\")\r\n\r\n# Darknet search with Tor\r\ng_tor = Grounder(use_tor=True)\r\nd_res = g_tor.dark_search(\"fresh proxies list\")\r\nd_ctx = g_tor.fetch_context(\"http://somesite.onion/article\")\r\n\r\n# Feed into LLM\r\n\r\nfrom langchain_openai import ChatOpenAI\r\nllm = ChatOpenAI(model=\"gpt-4o-mini\", temperature=0)\r\n\r\nanswer = llm.invoke(f\"Summarize:\\n\\n{ctx}\")\r\nprint(answer)\r\n\r\n```\r\n\r\n## For darknet features:\r\n\r\nTOR running locally (socks5://127.0.0.1:9050)\r\n```bash\r\npip install requests[socks]\r\n```\r\n\r\n## Logging & Caching\r\n```bash\r\nCache stored at: ~/.deepground/cache\r\nLog file: ~/.deepground/deepground.log\r\n```\r\n\r\n## Documentation\r\nDetailed documentation includeing full guides, and examples can be found at our official website https://evilfeonix.eu.org \r\n\r\n## Contrubuting\r\nContributors are welcome to this journey, feel free to :\r\n- Report bugs via github issues.\r\n- Suggest feature with use cases.\r\n- Submit PRs with clear description.\r\n\r\n## Disclaimer\r\n\r\n> _This library is for educational and research purposes only. Authors will never ever be responsible for any misuse or damage cause by this project._\r\n\r\n\r\n\r\n## LICENSE\r\nUse MIT license:\r\n```text\r\nMIT License\r\nCopyright (c) 2025 Evilfeonix\r\nPermission is hereby granted, free of charge...\r\n```\r\n\r\n## Powered by\r\nThis project is made posibly thanks to those infrastructure with their generous supports.\r\n\r\n[](https://www.python.org/)\r\n[](LICENSE)\r\n[](https://www.python.org/)\r\n[](LICENSE)\r\n[](https://www.python.org/)\r\n[](LICENSE)\r\n\r\n[](https://www.python.org/) \r\n[](https://pypi.org/project/deepground-evilfeonix/) \r\n[](LICENSE) \r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Deepground - A Python library that empowers LLM agents with real-time data access from both the clear and dark net.",
"version": "0.8.2",
"project_urls": {
"Homepage": "https://github.com/evilfeonix/deepground",
"Issues": "https://github.com/evilfeonix/deepground/issues"
},
"split_keywords": [
"llm",
" real-time",
" darknet",
" search",
" osint",
" tor",
" ai",
" darkweb",
" groundx",
" groundnet",
" deepground",
" grounder",
" evilfeonix",
" grounding info",
" information gathering"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e9dcdda1fc25b603bb3a84b7aaa5a63cad444387e23bb42b18056f84eade721",
"md5": "589189d14b55b36a702838988756969f",
"sha256": "ab6d8dd3044b192e32424e106f3af6e68bda43b406bc646303028f0ad69dfda2"
},
"downloads": -1,
"filename": "deepground-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "589189d14b55b36a702838988756969f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10525,
"upload_time": "2025-10-19T22:59:27",
"upload_time_iso_8601": "2025-10-19T22:59:27.838791Z",
"url": "https://files.pythonhosted.org/packages/3e/9d/cdda1fc25b603bb3a84b7aaa5a63cad444387e23bb42b18056f84eade721/deepground-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5496a5d2a9ad1c8165f4dfa41d3603ad84689d1c6522a8442c38af2e91e7623f",
"md5": "788447887a96285ee9371a6a3b3450ac",
"sha256": "ae5667036f6145ed4163ee04660d39c31206486966f4222bfd2f31fa35e0bad3"
},
"downloads": -1,
"filename": "deepground-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "788447887a96285ee9371a6a3b3450ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13983,
"upload_time": "2025-10-19T22:59:33",
"upload_time_iso_8601": "2025-10-19T22:59:33.404433Z",
"url": "https://files.pythonhosted.org/packages/54/96/a5d2a9ad1c8165f4dfa41d3603ad84689d1c6522a8442c38af2e91e7623f/deepground-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 22:59:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evilfeonix",
"github_project": "deepground",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "ssl",
"specs": []
},
{
"name": "bs4",
"specs": []
},
{
"name": "ddgs",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "aiohttp",
"specs": []
},
{
"name": "aiohttp-socks",
"specs": []
},
{
"name": "langchain",
"specs": []
},
{
"name": "typing-extensions",
"specs": []
}
],
"lcname": "deepground"
}
JSON
