Upload README.md

README.md

@@ -0,0 +1,373 @@
+# qwen_OSINT
+
+<p align="center">
+  <strong>Open-Source Intelligence (OSINT) Fine-Tuned Model</strong><br>
+  Built on Qwen3-4B-Thinking-2507 &middot; GGUF Quantized &middot; Ready for Local Deployment
+</p>
+
+<p align="center">
+  <a href="https://huggingface.co/aab20abdullah/qwen_OSINT">
+    <img src="https://img.shields.io/badge/HuggingFace-Model_Card-yellow?logo=huggingface&logoColor=white" alt="HuggingFace Model">
+  </a>
+  <a href="https://huggingface.co/datasets/aab20abdullah/OSINT">
+    <img src="https://img.shields.io/badge/Dataset-OSINT-blue?logo=huggingface&logoColor=white" alt="Dataset">
+  </a>
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
+  <img src="https://img.shields.io/badge/Parameters-4B-purple" alt="Parameters: 4B">
+  <img src="https://img.shields.io/badge/Context-256K-orange" alt="Context: 256K">
+  <img src="https://img.shields.io/badge/Architecture-Qwen3-red" alt="Architecture: Qwen3">
+</p>
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Model Variants](#model-variants)
+- [Use Cases](#use-cases)
+- [Installation & Usage](#installation--usage)
+  - [llama.cpp](#llamacpp)
+  - [Ollama](#ollama)
+  - [Python (llama-cpp-python)](#python-llama-cpp-python)
+  - [LM Studio](#lm-studio)
+  - [Jan](#jan)
+- [Hardware Requirements](#hardware-requirements)
+- [Prompting Guide](#prompting-guide)
+- [Dataset](#dataset)
+- [Model Architecture](#model-architecture)
+- [Limitations & Responsible Use](#limitations--responsible-use)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
+---
+
+## Overview
+
+**qwen_OSINT** is a specialized 4-billion parameter language model fine-tuned for **Open-Source Intelligence (OSINT)** operations. It is built on top of [Qwen3-4B-Thinking-2507](https://huggingface.co/Qwen/Qwen3-4B-Thinking-2507), a state-of-the-art small language model featuring explicit chain-of-thought reasoning. This specialized variant has been trained on a curated OSINT dataset to deliver expert-level guidance on intelligence gathering techniques, digital investigation methods, and reconnaissance workflows.
+
+The model produces structured reasoning outputs with step-by-step analysis, making it ideal for cybersecurity professionals, threat intelligence analysts, digital investigators, and security researchers who need transparent, explainable intelligence assistance.
+
+> **Note:** This model operates exclusively in **thinking mode** and automatically generates visible reasoning traces within `<think>` blocks, allowing you to audit its decision-making process before the final answer.
+
+---
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Specialized OSINT Knowledge** | Fine-tuned on 768 curated OSINT examples covering digital investigation, reconnaissance, and intelligence analysis |
+| **Chain-of-Thought Reasoning** | Transparent step-by-step reasoning process visible in `<think>` blocks |
+| **Native 256K Context** | Process extremely long inputs -- full reports, multi-document analysis, and extended dialogues |
+| **Multiple Quantization Options** | Available in Q4_K_M, Q5_K_M, and Q8_0 for flexible deployment across hardware |
+| **Local-First Deployment** | Runs entirely offline on consumer hardware -- no API keys or cloud dependencies |
+| **Broad Tooling Support** | Compatible with llama.cpp, Ollama, LM Studio, Jan, and other GGUF inference engines |
+| **Efficient Architecture** | 4B parameters with Group Query Attention (GQA) for optimal memory usage and fast inference |
+| **MIT Licensed** | Free for personal, academic, and commercial use |
+
+---
+
+## Model Variants
+
+| Variant | File | Size | Best For |
+|---------|------|------|----------|
+| **Q4_K_M** | `qwen3-4b-thinking-2507.Q4_K_M.gguf` | 2.5 GB | Maximum speed, lower VRAM usage, minimal quality loss |
+| **Q5_K_M** | `qwen3-4b-thinking-2507.Q5_K_M.gguf` | 2.89 GB | Balanced quality and performance |
+| **Q8_0** | `qwen3-4b-thinking-2507.Q8_0.gguf` | 4.28 GB | Maximum quality, near-lossless quantization |
+
+---
+
+## Use Cases
+
+This model excels at providing structured guidance on OSINT methodologies including:
+
+- **Digital Identity Investigation** -- Email correlation, username cross-platform enumeration, social media account discovery
+- **Network Reconnaissance** -- IP geolocation, subdomain enumeration, DNS analysis, certificate transparency log monitoring
+- **Domain & Website Intelligence** -- WHOIS lookups, historical snapshots, technology stack fingerprinting
+- **Image & Media Verification** -- Reverse image search guidance, EXIF metadata analysis, deepfake detection techniques
+- **Cryptocurrency Tracing** -- Blockchain transaction analysis, wallet clustering, fund flow investigation
+- **Dark Web Monitoring** -- Leaked database identification, breach notification procedures
+- **Corporate Intelligence** -- Employee enumeration, organizational structure mapping, asset discovery
+- **Mobile & Telephony** -- Phone number validation, carrier identification, SIM-swapping prevention
+- **Geolocation & Physical Intel** -- Address verification, property record queries, geolocation tag analysis
+- **Document Forensics** -- Metadata extraction, authorship attribution, file provenance analysis
+- **Social Media Analysis** -- Bot detection, influence network mapping, disinformation campaign identification
+
+---
+
+## Installation & Usage
+
+### Prerequisites
+
+Ensure you have one of the supported inference engines installed. The model is distributed in **GGUF** format for maximum compatibility.
+
+### llama.cpp
+
+**Install via Homebrew (macOS/Linux):**
+```bash
+brew install llama.cpp
+```
+
+**Install via WinGet (Windows):**
+```bash
+winget install llama.cpp
+```
+
+**Start a local OpenAI-compatible server:**
+```bash
+llama-server -hf aab20abdullah/qwen_OSINT:Q4_K_M
+```
+
+**Run inference in terminal:**
+```bash
+llama-cli -hf aab20abdullah/qwen_OSINT:Q4_K_M --jinja
+```
+
+**Build from source:**
+```bash
+git clone https://github.com/ggerganov/llama.cpp.git
+cd llama.cpp
+cmake -B build
+cmake --build build -j --target llama-server llama-cli
+
+./build/bin/llama-server -hf aab20abdullah/qwen_OSINT:Q4_K_M
+```
+
+### Ollama
+
+An Ollama Modelfile is included for easy deployment.
+
+```bash
+ollama run hf.co/aab20abdullah/qwen_OSINT:Q4_K_M
+```
+
+Or create a custom Modelfile:
+```dockerfile
+FROM ./qwen3-4b-thinking-2507.Q4_K_M.gguf
+
+SYSTEM """You are an expert OSINT (Open-Source Intelligence) analyst. Provide detailed, step-by-step investigative guidance. Always explain your reasoning process before delivering conclusions."""
+
+PARAMETER temperature 0.6
+PARAMETER top_p 0.95
+PARAMETER top_k 20
+```
+
+### Python (llama-cpp-python)
+
+```bash
+pip install llama-cpp-python
+```
+
+```python
+from llama_cpp import Llama
+
+llm = Llama.from_pretrained(
+    repo_id="aab20abdullah/qwen_OSINT",
+    filename="qwen3-4b-thinking-2507.Q4_K_M.gguf",
+    n_ctx=32768,      # Context window size
+    verbose=False
+)
+
+response = llm.create_chat_completion(
+    messages=[
+        {
+            "role": "system",
+            "content": "You are an expert OSINT analyst specializing in digital investigations and open-source intelligence gathering."
+        },
+        {
+            "role": "user",
+            "content": "How would you approach investigating a potentially fraudulent website?"
+        }
+    ],
+    temperature=0.6,
+    top_p=0.95,
+    max_tokens=4096
+)
+
+print(response["choices"][0]["message"]["content"])
+```
+
+### LM Studio
+
+1. Open LM Studio
+2. Search for `aab20abdullah/qwen_OSINT` in the model browser
+3. Download your preferred quantization variant
+4. Load the model and start chatting
+
+### Jan
+
+1. Open Jan application
+2. Navigate to **Hub** or **Models**
+3. Add Hugging Face model: `aab20abdullah/qwen_OSINT`
+4. Select your preferred GGUF variant and download
+5. Start a new conversation with the loaded model
+
+### Docker
+
+```bash
+docker model run hf.co/aab20abdullah/qwen_OSINT:Q4_K_M
+```
+
+---
+
+## Hardware Requirements
+
+| Variant | Minimum RAM | Recommended RAM | GPU VRAM (Optional) |
+|---------|-------------|-----------------|---------------------|
+| **Q4_K_M** | 4 GB | 8 GB | 3 GB+ |
+| **Q5_K_M** | 5 GB | 10 GB | 4 GB+ |
+| **Q8_0** | 6 GB | 12 GB | 5 GB+ |
+
+> **Tip:** This model can run on a **4GB Raspberry Pi** with the Q4_K_M variant. For full 256K context utilization, approximately 65 GB of system RAM is required.
+
+---
+
+## Prompting Guide
+
+### Recommended Sampling Parameters
+
+| Parameter | Value |
+|-----------|-------|
+| Temperature | 0.6 |
+| Top P | 0.95 |
+| Top K | 20 |
+| Max Tokens | 4,096 (standard) / 8,192 (complex analysis) |
+
+### System Prompt
+
+For optimal OSINT performance, use a system prompt that establishes the model's expertise:
+
+```
+You are an expert OSINT (Open-Source Intelligence) analyst and investigator. 
+You specialize in digital reconnaissance, threat intelligence, social media 
+analysis, and open-source information gathering. Provide structured, 
+step-by-step investigative guidance. Always explain your reasoning process 
+before delivering conclusions. Cite specific tools, techniques, and 
+methodologies where applicable. Maintain ethical boundaries and emphasize 
+legal compliance in all investigative recommendations.
+```
+
+### Example Prompts
+
+**Domain Investigation:**
+```
+What techniques can I use to map the infrastructure of a suspicious domain, 
+including subdomains, hosting providers, and historical changes?
+```
+
+**Person of Interest Research:**
+```
+Walk me through a systematic approach to locating someone's professional 
+history using only publicly available sources and without violating privacy laws.
+```
+
+**Incident Response:**
+```
+A company suspects their employee data has been leaked. Outline a comprehensive 
+OSINT workflow to identify the source, scope, and current availability of the 
+leaked information on the open web and dark web.
+```
+
+---
+
+## Dataset
+
+This model was fine-tuned on the [OSINT Dataset](https://huggingface.co/datasets/aab20abdullah/OSINT), a curated collection of 768 training examples specifically designed for intelligence analysis education and training.
+
+### Dataset Structure
+
+Each example contains three fields:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **Question** | The OSINT inquiry or scenario | "How to verify a website's registration date and owner information?" |
+| **Thinking** | Step-by-step analytical reasoning | "Domain registration information contains key data such as creation date, expiration date, and registrant details..." |
+| **Solution** | Concrete tools, techniques, and actionable guidance | "Use WHOIS lookup (who.is, whois.domaintools.com); check domain history records (WHOIS History)." |
+
+### Dataset Coverage
+
+The dataset spans 25+ OSINT domains including digital identity verification, network reconnaissance, geolocation analysis, cryptocurrency tracing, corporate intelligence gathering, social media investigation, and forensic document analysis.
+
+> **Access:** [aab20abdullah/OSINT on Hugging Face Datasets](https://huggingface.co/datasets/aab20abdullah/OSINT)
+
+---
+
+## Model Architecture
+
+```yaml
+Base Model: Qwen/Qwen3-4B-Thinking-2507
+Parameters: 4.0B (3.6B non-embedding)
+Architecture: Dense Transformer
+Layers: 36
+Attention: Group Query Attention (GQA)
+Attention Heads: 32 Query / 8 Key-Value
+Context Length: 262,144 tokens (native)
+Vocabulary Size: 151,936
+Fine-tuning Framework: Unsloth
+Quantization: GGUF (Q4_K_M, Q5_K_M, Q8_0)
+Training Data: 768 OSINT examples
+License: MIT
+```
+
+### Base Model Capabilities
+
+Qwen3-4B-Thinking-2507 delivers exceptional reasoning performance for a 4B parameter model:
+
+| Benchmark | Score |
+|-----------|-------|
+| AIME25 (Mathematics) | 81.3% |
+| HMMT25 (Science) | 55.5% |
+| GPQA (General QA) | 65.8% |
+| LiveCodeBench (Coding) | 55.2% |
+| BFCL-v3 (Tool Usage) | 71.2% |
+
+---
+
+## Limitations & Responsible Use
+
+### Known Limitations
+
+- **Knowledge Cutoff:** The model's knowledge is current only up to the base model's training data cutoff date. Always verify tool availability, URL validity, and service existence before use.
+- **No Live Access:** This model cannot browse the live internet, execute queries, or access real-time data. It provides methodological guidance only.
+- **Hallucination Risk:** Like all LLMs, it may occasionally suggest tools or techniques that no longer exist or recommend incorrect procedures. Always cross-reference with current documentation.
+- **Jurisdiction Variations:** OSINT laws and regulations vary significantly by country. Users are responsible for ensuring compliance with local legal frameworks.
+- **No Guarantees:** The model provides educational guidance on OSINT methodologies. Results in real-world investigations depend on target visibility, data availability, and operator skill.
+
+### Responsible Use Policy
+
+This model is intended for **legitimate security research, educational purposes, authorized penetration testing, journalism, law enforcement, and corporate security operations only**.
+
+**Prohibited uses include:**
+- Stalking, harassment, or unauthorized surveillance of individuals
+- Doxxing or publishing private information without consent
+- Identity theft or financial fraud
+- Corporate espionage against non-consenting entities
+- Any activity violating applicable laws or regulations
+
+By using this model, you agree to deploy it ethically and in full compliance with all applicable laws, including GDPR, CCPA, and local privacy regulations.
+
+---
+
+## License
+
+This model is licensed under the **MIT License**.
+
+The base model [Qwen3-4B-Thinking-2507](https://huggingface.co/Qwen/Qwen3-4B-Thinking-2507) is licensed under Apache 2.0. This fine-tuned derivative adds no additional restrictions beyond those of the underlying licenses.
+
+You are free to use, modify, distribute, and sublicense this model for personal, academic, and commercial purposes, provided that the license terms are included in all copies or substantial portions.
+
+---
+
+## Acknowledgments
+
+- **Alibaba Qwen Team** for the exceptional Qwen3-4B-Thinking-2507 base model
+- **Unsloth** for the 2x faster fine-tuning framework and GGUF quantization pipeline
+- **llama.cpp** team for the efficient GGUF inference engine
+- **Hugging Face** for model hosting, dataset infrastructure, and the Transformers ecosystem
+
+---
+
+<p align="center">
+  <sub>Built with care for the cybersecurity and OSINT community.</sub><br>
+  <sub>For questions or contributions, open a discussion on the <a href="https://huggingface.co/aab20abdullah/qwen_OSINT/discussions">Hugging Face Community tab</a>.</sub>
+</p>