Merge pull request #11 from h9zdev/documentation-update-17072038356578099895

Add Documentation and API Transparency
2026-04-25 17:25:10 +02:00 · 2026-02-09 22:59:38 +05:30
parent 7e7b958848 0a7dcfcacf
commit 8bb45bc272
3 changed files with 131 additions and 6 deletions
--- a/README.md
+++ b/README.md
@@ -33,6 +33,12 @@ Stay updated with the latest **Geo Sentinel AI** releases and announcements.
 👉 **Subscribe here:**  
 https://docs.google.com/forms/d/e/1FAIpQLSe3qBh6r1orih2MkLf5DjdolX0jv5Abct02363lLxpXEute-Q/viewform

+## 📚 Documentation
+
+Detailed guides on how to use GeoSentinel's advanced features:
+- 🤖 [GeoSential AI Guide](docs/geosential_ai.md) - Learn how to use the AI assistant and its commands.
+- 🔍 [Search & Dark Web Guide](docs/search_options.md) - Instructions for OSINT and dark web searching.
+
 ## 🌟 Features

 -   🗺️ Access to GeoJSON data and surveillance grid tiles.
@@ -224,12 +230,25 @@ ollama serve

 ## 🙏 API TO USE

-   [OpenStreetMap](https://www.openstreetmap.org/)
-   [ADSB.one](https://adsb.one/)
-   [AISstream.io](https://aisstream.io/)
-   [CoinGecko](https://www.coingecko.com/)
-   [NewsAPI](https://newsapi.org/)
-   [tomtom](https://developer.tomtom.com)
+Below is a list of APIs used in GeoSentinel and where to obtain your API keys:
+
+-   🌍 [OpenStreetMap](https://www.openstreetmap.org/) - Geocoding and map data.
+-   ✈️ [ADSB.one](https://adsb.one/) - Real-time flight tracking data.
+-   🚢 [AISstream.io](https://aisstream.io/) - Real-time vessel tracking (AIS).
+-   📊 [CoinGecko](https://www.coingecko.com/) - Cryptocurrency market data.
+-   📰 [NewsAPI](https://newsapi.org/) - Global news feeds.
+-   🗺️ [TomTom Maps](https://developer.tomtom.com) - Mapping and routing services.
+-   📶 [OpenCellID](https://opencellid.org/) - Cell tower location data.
+-   🤗 [Hugging Face](https://huggingface.co/) - AI models and inference.
+-   🤖 [OpenRouter](https://openrouter.ai/) - Unified AI model gateway.
+-   📡 [OpenSky Network](https://opensky-network.org/) - Flight metadata and routing.
+-   🌐 [MyMemory Translation](https://mymemory.translated.net/) - Free translation services.
+-   🐦 [Twitter/X API](https://developer.twitter.com/) - Social media OSINT.
+-   🔍 [DuckDuckGo](https://duckduckgo.com/) - Web search integration.
+-   🌐 [Google Search](https://www.google.com/) - Web search integration.
+-   🅱️ [Bing Search](https://www.bing.com/) - Web search integration.
+-   🔒 [Ahmia](https://ahmia.fi/) - Dark web search services.
+-   🦙 [Ollama](https://ollama.com/) - Local LLM processing.

 ## 🗺️ Images of GeoSentinel UI
 ![GeoSentinel Screenshot](images/Screenshot%20From%202026-01-08%2001-01-15.png)
--- a/docs/geosential_ai.md
+++ b/docs/geosential_ai.md
@@ -0,0 +1,57 @@
+# 🤖 GeoSential AI Documentation
+
+Welcome to the **GeoSential AI** manual! GeoSential AI is your high-tech Geospatial Intelligence (GEOINT) and OSINT assistant, designed to automate tracking and provide real-time global briefings. 🌍🛰️
+
+## 🚀 Overview
+
+GeoSential AI integrates real-time web data, map functionality, and semantic memory to assist in monitoring global activities. It can track flights, vessels, scan sectors for signals, and provide up-to-the-minute news and market data.
+
+## 🛠️ How to Use
+
+### 🖥️ Interface
+You can interact with GeoSential AI directly through the **Earth View** dashboard in the GeoSentinel UI. Look for the AI chat panel to start a conversation.
+
+### 🔌 API Endpoint
+For developers, the AI is accessible via the following endpoint:
+- **URL**: `/api/geosentialai/chat`
+- **Method**: `POST`
+- **Payload**:
+```json
+{
+  "message": "Track flight UAE202",
+  "web_search": true,
+  "human_mode": false,
+  "engine": "huggingface",
+  "context": {}
+}
+```
+
+## 📜 Commands & Tags
+
+GeoSential AI can trigger specific actions in the UI by outputting special tags. These tags allow the AI to interact directly with the map:
+
+| Command | Action |
+| :--- | :--- |
+| `[TRACK_FLIGHT: <icao>]` | ✈️ Zooms the map to a specific flight using its ICAO hex code. |
+| `[TRACK_VESSEL: <mmsi>]` | 🚢 Zooms the map to a specific vessel using its MMSI number. |
+| `[SHOW_WEATHER: <lat>, <lng>]` | 🌦️ Opens the meteorology/environment GUI for the specified coordinates. |
+| `[SCAN_MAP: <lat>, <lng>]` | 📡 Zooms to coordinates and initiates a sector-wide signal scan. |
+
+## 🔍 Search Integration
+
+GeoSential AI is equipped with a powerful web search capability 🕵️‍♂️.
+- **Auto-Trigger**: The AI automatically enables web search if your message contains keywords like *news, stock, price, market, update, latest,* or *happening*.
+- **DuckDuckGo Integration**: It uses DuckDuckGo to pull real-time snippets from the web to ground its answers in current events.
+
+## 🧠 Memory System
+
+The AI uses **ChromaDB** to maintain a "Memory Stream" 🧠. It remembers previous interactions and can recall relevant context to provide more personalized and consistent assistance.
+
+## ⚙️ AI Engines
+
+You can choose between two processing engines:
+1. **Cloud (Hugging Face)**: Uses `Llama-3.1-8B-Instruct` for high-performance reasoning (Default).
+2. **Local (Ollama)**: Uses the `phi` model running locally on your machine for enhanced privacy and offline use.
+
+---
+*Stay informed, stay ahead with GeoSential AI. 🚀*
--- a/docs/search_options.md
+++ b/docs/search_options.md
@@ -0,0 +1,49 @@
+# 🔍 Search Options & Dark Web Documentation
+
+Explore the powerful search capabilities of GeoSentinel, from surface web OSINT to the depths of the dark web. 🕵️‍♂️🔒
+
+## 🌐 Advanced Web Scan
+
+The Advanced Web Scan tool allows you to perform deep OSINT searches across multiple platforms and search engines simultaneously.
+
+### 🛠️ How to Use
+- **URL**: `/api/tools/web_scan`
+- **Method**: `POST`
+- **Parameters**:
+    - `query`: Your search term or target.
+    - `type`: `text`, `images`, or `all`.
+    - `sources`: A list of platforms to target.
+    - `aggressive`: Set to `true` for deep scraping of result pages.
+
+### 📱 Supported Sources
+You can restrict your search to specific high-value OSINT sources:
+- **Social Media**: Twitter, Reddit, Instagram, LinkedIn.
+- **Communication**: Telegram, Discord.
+- **Developer/Code**: GitHub, StackOverflow.
+- **Leaks/Dumps**: Pastebin, BreachForums.
+- **General Web**: Multi-engine aggregation (Google, Bing, DuckDuckGo).
+
+### 🚀 Aggressive Mode
+When **Aggressive Mode** is enabled, GeoSentinel goes beyond simple search results. It attempts to visit the top result links and extract the actual page content to provide a more comprehensive intelligence briefing.
+
+---
+
+## 🔒 Dark Web Search
+
+GeoSentinel provides integrated access to the dark web, allowing you to search across multiple `.onion` search engines anonymously. 🕶️
+
+### 🛡️ How it Works
+1. **Tor Network**: If a Tor proxy is running locally (port 9050), GeoSentinel routes queries through the Tor network to access `.onion` sites directly.
+2. **Onion Aggregation**: It queries a vast list of dark web engines, including:
+    - Ahmia
+    - OnionLand
+    - Torgle
+    - Torch
+    - ...and many others.
+3. **Clearnet Fallback**: If Tor is not available locally, the system automatically falls back to the Ahmia clearnet proxy to fetch results.
+
+### 🕵️‍♂️ Accessing Dark Web Results
+Results from the dark web are flagged with the `TOR_NETWORK` or `Ahmia_Clearnet` source tag. These links typically end in `.onion` and require a Tor-enabled browser (like Tor Browser) to open.
+
+---
+*Unlock the hidden layers of the web with GeoSentinel. 🔍🔒*