Add complete RAG-powered OSINT investigation assistant

Implements Gradio app with Supabase PGVector and HuggingFace Inference API for generating structured OSINT investigation methodologies. Features include semantic tool retrieval from 344+ tools, chat interface, and REST API endpoints.

Key components:
- Gradio ChatInterface with auto-generated API
- Supabase PGVector for 768-dim semantic search
- HuggingFace Inference Provider (Llama-3.1-8B)
- RAG pipeline with LangChain-style architecture
- Low-hallucination prompts (temp=0.2, max_tokens=600)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.env.example

@@ -0,0 +1,55 @@
+# OSINT Investigation Assistant - Environment Variables
+
+# =============================================================================
+# REQUIRED: Supabase Database Connection
+# =============================================================================
+# PostgreSQL connection string for your Supabase database
+# Format: postgresql://[user]:[password]@[host]:[port]/[database]
+# Get this from: Supabase Dashboard > Project Settings > Database > Connection String
+SUPABASE_CONNECTION_STRING=postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres
+
+# =============================================================================
+# REQUIRED: Hugging Face API Token
+# =============================================================================
+# Get your token from: https://huggingface.co/settings/tokens
+# This is used for Inference Providers API access
+HF_TOKEN=hf_your_token_here
+
+# =============================================================================
+# OPTIONAL: LLM Configuration
+# =============================================================================
+# Model to use for generation (default: meta-llama/Llama-3.1-8B-Instruct)
+# Other options:
+#   - meta-llama/Meta-Llama-3-8B-Instruct
+#   - Qwen/Qwen2.5-72B-Instruct
+#   - mistralai/Mistral-7B-Instruct-v0.3
+LLM_MODEL=meta-llama/Llama-3.1-8B-Instruct
+
+# Temperature for LLM generation (0.0 to 1.0, default: 0.7)
+# Lower = more focused/deterministic, Higher = more creative/diverse
+LLM_TEMPERATURE=0.7
+
+# Maximum tokens to generate (default: 2000)
+LLM_MAX_TOKENS=2000
+
+# =============================================================================
+# OPTIONAL: Vector Store Configuration
+# =============================================================================
+# Number of tools to retrieve for context (default: 5)
+RETRIEVAL_K=5
+
+# Embedding model for vector search (default: sentence-transformers/all-mpnet-base-v2)
+# Note: Database uses 768-dimensional embeddings
+EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
+
+# =============================================================================
+# OPTIONAL: Gradio Configuration
+# =============================================================================
+# Port for Gradio app (default: 7860)
+GRADIO_PORT=7860
+
+# Server name (default: 0.0.0.0 for all interfaces)
+GRADIO_SERVER_NAME=0.0.0.0
+
+# Enable Gradio sharing link (default: False)
+GRADIO_SHARE=False

.gitignore

@@ -0,0 +1,50 @@
+# Environment variables (contains secrets)
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# macOS
+.DS_Store
+
+# Gradio
+gradio_cached_examples/
+flagged/
+
+# Logs
+*.log

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "supabase": {
+      "type": "http",
+      "url": "https://mcp.supabase.com/mcp?project_ref=zhprqpnxpdcmsjukpurx"
+    }
+  }
+}

QUICKSTART.md

@@ -0,0 +1,15 @@
+# OSINT RAG App Quickstart
+
+## Stack
+- **Frontend**: Gradio 4.0+ (ChatInterface with auto API endpoints)
+- **Database**: Supabase PGVector (768-dim embeddings, HNSW index)
+- **LLM**: HuggingFace Inference API (Llama-3.1-8B-Instruct)
+- **Embeddings**: HuggingFace Inference API (all-mpnet-base-v2, 768-dim)
+- **Client**: Supabase Python client + InferenceClient (huggingface_hub)
+
+## Key Parameters
+- **Temperature**: 0.2 (low hallucination)
+- **Max Tokens**: 600 (short responses)
+- **Retrieval K**: 5 tools
+- **Match Threshold**: 0.5 (cosine similarity)
+- **Connection**: Transaction Pooler (port 6543)

README.md

@@ -1,13 +1,282 @@
 ---
-title: Cojournalist Investigate
-emoji: 🔥
-colorFrom: red
-colorTo: green
+title: OSINT Investigation Assistant
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
 sdk: gradio
 sdk_version: 5.49.1
 app_file: app.py
 pinned: false
-short_description: Investigator LLM for coJournalist
+short_description: RAG-powered OSINT investigation assistant with 344+ tools
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🔍 OSINT Investigation Assistant
+
+A RAG-powered AI assistant that helps investigators develop structured methodologies for open-source intelligence (OSINT) investigations. Built with LangChain, Supabase PGVector, and Hugging Face Inference Providers.
+
+## ✨ Features
+
+- **🎯 Structured Methodologies**: Generate step-by-step investigation plans tailored to your query
+- **🛠️ 344+ OSINT Tools**: Access recommendations from a comprehensive database of curated OSINT tools
+- **🔍 Context-Aware Retrieval**: Semantic search finds the most relevant tools for your investigation
+- **🚀 API Access**: Built-in REST API for integration with external applications
+- **💬 Chat Interface**: User-friendly conversational interface
+- **🔌 MCP Support**: Can be extended to work with AI agents via MCP protocol
+
+## 🏗️ Architecture
+
+```
+┌──────────────────────────────────────┐
+│      Gradio UI + API Endpoints       │
+└──────────────┬───────────────────────┘
+               │
+┌──────────────▼───────────────────────┐
+│     LangChain RAG Pipeline           │
+│  • Query Understanding               │
+│  • Tool Retrieval (PGVector)         │
+│  • Response Generation (LLM)         │
+└──────────────┬───────────────────────┘
+               │
+    ┌──────────┴──────────┐
+    │                     │
+┌───▼───────────┐  ┌─────▼────────────┐
+│ Supabase      │  │ HF Inference     │
+│ PGVector DB   │  │ Providers        │
+│ (344 tools)   │  │ (Llama 3.1)      │
+└───────────────┘  └──────────────────┘
+```
+
+## 🚀 Quick Start
+
+### Local Development
+
+1. **Clone the repository**
+   ```bash
+   git clone <your-repo-url>
+   cd osint-llm
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your credentials
+   ```
+
+   Required variables:
+   - `SUPABASE_CONNECTION_STRING`: Your Supabase PostgreSQL connection string
+   - `HF_TOKEN`: Your Hugging Face API token
+
+4. **Run the application**
+   ```bash
+   python app.py
+   ```
+
+   The app will be available at `http://localhost:7860`
+
+### Hugging Face Spaces Deployment
+
+1. **Create a new Space** on Hugging Face
+2. **Push this repository** to your Space
+3. **Set environment variables** in Space settings:
+   - `SUPABASE_CONNECTION_STRING`
+   - `HF_TOKEN`
+4. **Deploy** - The Space will automatically build and launch
+
+## 📚 Usage
+
+### Chat Interface
+
+Simply ask your investigation questions:
+
+```
+"How do I investigate a suspicious domain?"
+"What tools can I use to verify an image's authenticity?"
+"How can I trace the origin of a social media account?"
+```
+
+The assistant will provide:
+1. Investigation overview
+2. Step-by-step methodology
+3. Recommended tools with descriptions and URLs
+4. Best practices and safety considerations
+5. Expected outcomes
+
+### Tool Search
+
+Use the "Tool Search" tab to directly search for OSINT tools by category or purpose.
+
+### API Access
+
+This app automatically exposes REST API endpoints for external integration.
+
+**Python Client:**
+
+```python
+from gradio_client import Client
+
+client = Client("your-space-url")
+result = client.predict(
+    "How do I investigate a domain?",
+    api_name="/investigate"
+)
+print(result)
+```
+
+**JavaScript Client:**
+
+```javascript
+import { Client } from "@gradio/client";
+
+const client = await Client.connect("your-space-url");
+const result = await client.predict("/investigate", {
+  message: "How do I investigate a domain?"
+});
+console.log(result.data);
+```
+
+**cURL:**
+
+```bash
+curl -X POST "https://your-space.hf.space/call/investigate" \
+     -H "Content-Type: application/json" \
+     -d '{"data": ["How do I investigate a domain?"]}'
+```
+
+**Available Endpoints:**
+- `/call/investigate` - Main investigation assistant
+- `/call/search_tools` - Direct tool search
+- `/gradio_api/openapi.json` - OpenAPI specification
+
+## 🗄️ Database
+
+The app uses Supabase with PGVector extension to store and retrieve OSINT tools.
+
+**Database Schema:**
+```sql
+CREATE TABLE bellingcat_tools (
+  id BIGINT PRIMARY KEY,
+  name TEXT,
+  category TEXT,
+  content TEXT,
+  url TEXT,
+  cost TEXT,
+  details TEXT,
+  embedding VECTOR,
+  created_at TIMESTAMP WITH TIME ZONE
+);
+```
+
+**Tool Categories:**
+- Archiving & Preservation
+- Social Media Investigation
+- Image & Video Analysis
+- Domain & Network Investigation
+- Geolocation
+- Data Extraction
+- Verification & Fact-Checking
+- And more...
+
+## 🛠️ Technology Stack
+
+- **UI/API**: [Gradio](https://gradio.app/) - Automatic API generation
+- **RAG Framework**: [LangChain](https://langchain.com/) - Retrieval pipeline
+- **Vector Database**: [Supabase](https://supabase.com/) with PGVector extension
+- **Embeddings**: HuggingFace sentence-transformers
+- **LLM**: [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/) - Llama 3.1
+- **Language**: Python 3.9+
+
+## 📁 Project Structure
+
+```
+osint-llm/
+├── app.py                    # Main Gradio application
+├── requirements.txt          # Python dependencies
+├── .env.example             # Environment variables template
+├── README.md                # This file
+└── src/
+    ├── __init__.py
+    ├── vectorstore.py       # Supabase PGVector connection
+    ├── rag_pipeline.py      # LangChain RAG logic
+    ├── llm_client.py        # Inference Provider client
+    └── prompts.py           # Investigation prompt templates
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+See `.env.example` for all available configuration options.
+
+**Required:**
+- `SUPABASE_CONNECTION_STRING` - PostgreSQL connection string
+- `HF_TOKEN` - Hugging Face API token
+
+**Optional:**
+- `LLM_MODEL` - Model to use (default: meta-llama/Llama-3.1-8B-Instruct)
+- `LLM_TEMPERATURE` - Generation temperature (default: 0.7)
+- `LLM_MAX_TOKENS` - Max tokens to generate (default: 2000)
+- `RETRIEVAL_K` - Number of tools to retrieve (default: 5)
+- `EMBEDDING_MODEL` - Embedding model (default: sentence-transformers/all-MiniLM-L6-v2)
+
+### Supported LLM Models
+
+- `meta-llama/Llama-3.1-8B-Instruct` (recommended)
+- `meta-llama/Meta-Llama-3-8B-Instruct`
+- `Qwen/Qwen2.5-72B-Instruct`
+- `mistralai/Mistral-7B-Instruct-v0.3`
+
+## 💰 Cost Considerations
+
+### Hugging Face Inference Providers
+- Free tier: $0.10/month credits
+- PRO tier: $2.00/month credits + pay-as-you-go
+- Typical cost: ~$0.001-0.01 per query
+- Recommended budget: $10-50/month for moderate usage
+
+### Supabase
+- Free tier sufficient for most use cases
+- PGVector operations are standard database queries
+
+### Hugging Face Spaces
+- Free CPU hosting available
+- GPU upgrade: ~$0.60/hour (optional, not required)
+
+## 🔮 Future Enhancements
+
+- [ ] MCP server integration for AI agent tool use
+- [ ] Multi-turn conversation with memory
+- [ ] User authentication and query logging
+- [ ] Additional tool databases and sources
+- [ ] Export methodologies as PDF/markdown
+- [ ] Tool usage examples and tutorials
+- [ ] Community-contributed tool reviews
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+## 🙏 Acknowledgments
+
+- Tool data sourced from [Bellingcat's Online Investigation Toolkit](https://www.bellingcat.com/)
+- Built with support from the OSINT community
+
+## 📞 Support
+
+For issues or questions:
+- Open an issue on GitHub
+- Check the [Hugging Face Spaces documentation](https://huggingface.co/docs/hub/spaces)
+- Review the [Gradio documentation](https://gradio.app/docs/)
+
+---
+
+Built with ❤️ for the OSINT community

app.py

@@ -0,0 +1,257 @@
+"""
+OSINT Investigation Assistant - Gradio App
+
+A RAG-powered assistant that helps investigators develop methodologies
+for OSINT investigations using a database of 344+ OSINT tools.
+"""
+
+import os
+import gradio as gr
+from dotenv import load_dotenv
+from src.rag_pipeline import create_pipeline
+
+# Load environment variables
+load_dotenv()
+
+# Initialize the RAG pipeline
+print("Initializing OSINT Investigation Pipeline...")
+try:
+    pipeline = create_pipeline(
+        retrieval_k=5,
+        model=os.getenv("LLM_MODEL", "meta-llama/Llama-3.1-8B-Instruct"),
+        temperature=float(os.getenv("LLM_TEMPERATURE", "0.7"))
+    )
+    print("✓ Pipeline initialized successfully")
+except Exception as e:
+    print(f"✗ Error initializing pipeline: {e}")
+    raise
+
+
+def investigate(message: str, history: list) -> str:
+    """
+    Main chat function for investigation queries
+
+    Args:
+        message: User's investigation query
+        history: Chat history (list of [user_msg, bot_msg] pairs)
+
+    Returns:
+        Generated investigation methodology
+    """
+    try:
+        # Generate response (non-streaming for simplicity)
+        response = pipeline.generate_methodology(message, stream=False)
+        return response
+    except Exception as e:
+        return f"Error generating response: {str(e)}\n\nPlease check your environment variables (HF_TOKEN, SUPABASE_CONNECTION_STRING) and try again."
+
+
+def investigate_stream(message: str, history: list):
+    """
+    Streaming version of investigation function
+
+    Args:
+        message: User's investigation query
+        history: Chat history
+
+    Yields:
+        Response chunks
+    """
+    try:
+        response_stream = pipeline.generate_methodology(message, stream=True)
+        full_response = ""
+        for chunk in response_stream:
+            full_response += chunk
+            yield full_response
+    except Exception as e:
+        yield f"Error generating response: {str(e)}\n\nPlease check your environment variables (HF_TOKEN, SUPABASE_CONNECTION_STRING) and try again."
+
+
+def get_tool_recommendations(query: str, k: int = 5) -> str:
+    """
+    Get tool recommendations for a query
+
+    Args:
+        query: Investigation query
+        k: Number of tools to recommend
+
+    Returns:
+        Formatted tool recommendations
+    """
+    try:
+        tools = pipeline.get_tool_recommendations(query, k=k)
+
+        if not tools:
+            return "No relevant tools found."
+
+        output = f"## Top {len(tools)} Recommended Tools\n\n"
+
+        for i, tool in enumerate(tools, 1):
+            output += f"### {i}. {tool['name']}\n"
+            output += f"- **Category**: {tool['category']}\n"
+            output += f"- **Cost**: {tool['cost']}\n"
+            output += f"- **URL**: {tool['url']}\n"
+            output += f"- **Description**: {tool['description']}\n"
+            if tool['details'] and tool['details'] != 'N/A':
+                output += f"- **Details**: {tool['details']}\n"
+            output += "\n"
+
+        return output
+    except Exception as e:
+        return f"Error retrieving tools: {str(e)}"
+
+
+# Custom CSS for better appearance
+custom_css = """
+.gradio-container {
+    max-width: 900px !important;
+}
+#component-0 {
+    max-width: 900px;
+}
+"""
+
+# Create Gradio interface
+with gr.Blocks(
+    title="OSINT Investigation Assistant",
+    theme=gr.themes.Soft(),
+    css=custom_css
+) as demo:
+    gr.Markdown("""
+    # 🔍 OSINT Investigation Assistant
+
+    Ask me how to investigate anything using open-source intelligence methods.
+    I'll provide you with a structured methodology and recommend specific OSINT tools
+    from a database of 344+ tools.
+
+    **Examples:**
+    - "How do I investigate a suspicious domain?"
+    - "What tools can I use to verify an image's authenticity?"
+    - "How can I trace the origin of a social media account?"
+    """)
+
+    # Main chat interface
+    chatbot = gr.ChatInterface(
+        fn=investigate_stream,
+        type="messages",
+        examples=[
+            "How do I investigate a suspicious domain?",
+            "What tools can I use to verify an image's authenticity?",
+            "How can I trace the origin of a social media account?",
+            "What's the best way to archive web content for investigation?",
+            "How do I geolocate an image from social media?"
+        ],
+        cache_examples=False,
+        title="Chat Interface",
+        description="Ask your investigation questions here",
+        api_name="investigate"  # This creates the /call/investigate API endpoint
+    )
+
+    # Additional tab for direct tool search
+    with gr.Tab("Tool Search"):
+        gr.Markdown("### Search for OSINT Tools")
+        with gr.Row():
+            tool_query = gr.Textbox(
+                label="Search Query",
+                placeholder="e.g., social media analysis, image verification, domain investigation",
+                lines=2
+            )
+            tool_count = gr.Slider(
+                minimum=1,
+                maximum=20,
+                value=5,
+                step=1,
+                label="Number of Tools"
+            )
+
+        tool_search_btn = gr.Button("Search Tools", variant="primary")
+        tool_output = gr.Markdown(label="Recommended Tools")
+
+        tool_search_btn.click(
+            fn=get_tool_recommendations,
+            inputs=[tool_query, tool_count],
+            outputs=tool_output,
+            api_name="search_tools"  # This creates the /call/search_tools API endpoint
+        )
+
+    # Information tab
+    with gr.Tab("About"):
+        gr.Markdown("""
+        ## About This Assistant
+
+        This OSINT Investigation Assistant helps researchers and investigators develop
+        structured methodologies for open-source intelligence investigations.
+
+        ### Features
+        - 🎯 **Structured Methodologies**: Get step-by-step investigation plans
+        - 🛠️ **Tool Recommendations**: Access a database of 344+ OSINT tools
+        - 🔍 **Context-Aware**: Tools are recommended based on your specific needs
+        - 🚀 **API Access**: Use this app via API for integration with other tools
+
+        ### Technology Stack
+        - **Vector Database**: Supabase with PGVector (344 OSINT tools)
+        - **LLM**: Hugging Face Inference Providers (Llama 3.1)
+        - **RAG Framework**: LangChain for retrieval-augmented generation
+        - **UI/API**: Gradio with automatic API generation
+
+        ### API Usage
+
+        This app automatically exposes API endpoints. You can access them using:
+
+        **Python Client:**
+        ```python
+        from gradio_client import Client
+
+        client = Client("your-space-url")
+        result = client.predict("How do I investigate a domain?", api_name="/investigate")
+        print(result)
+        ```
+
+        **cURL:**
+        ```bash
+        curl -X POST "https://your-space.hf.space/call/investigate" \\
+             -H "Content-Type: application/json" \\
+             -d '{"data": ["How do I investigate a domain?"]}'
+        ```
+
+        View the full API documentation at the bottom of this page (click "Use via API").
+
+        ### Environment Variables Required
+        - `SUPABASE_CONNECTION_STRING`: PostgreSQL connection string for Supabase
+        - `HF_TOKEN`: Hugging Face API token for Inference Providers
+        - `LLM_MODEL` (optional): Model to use (default: meta-llama/Llama-3.1-8B-Instruct)
+        - `LLM_TEMPERATURE` (optional): Temperature for generation (default: 0.7)
+
+        ### Data Source
+        The tool recommendations are based on the Bellingcat OSINT Toolkit and other
+        curated sources, with 344+ tools across categories including:
+        - Social Media Investigation
+        - Image and Video Analysis
+        - Domain and Network Investigation
+        - Geolocation
+        - Archiving and Preservation
+        - And more...
+
+        ---
+
+        Built with ❤️ for the OSINT community
+        """)
+
+# Launch configuration
+if __name__ == "__main__":
+    # Check for required environment variables
+    required_vars = ["SUPABASE_CONNECTION_STRING", "HF_TOKEN"]
+    missing_vars = [var for var in required_vars if not os.getenv(var)]
+
+    if missing_vars:
+        print(f"⚠️  Warning: Missing environment variables: {', '.join(missing_vars)}")
+        print("Please set these in your .env file or as environment variables")
+
+    # Launch the app
+    # Set mcp_server=True to enable MCP protocol for agent integration
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_api=True  # Show API documentation
+    )

requirements.txt

@@ -0,0 +1,14 @@
+# Gradio for UI and API
+gradio>=4.0.0
+
+# Supabase client for vector store
+supabase>=2.0.0
+
+# Hugging Face Inference (for LLM and embeddings)
+huggingface-hub>=0.20.0
+
+# Environment variables
+python-dotenv>=1.0.0
+
+# Utilities
+pydantic>=2.0.0

src/__init__.py

@@ -0,0 +1,3 @@
+"""OSINT Investigation Assistant - Core modules"""
+
+__version__ = "0.1.0"

src/llm_client.py

@@ -0,0 +1,195 @@
+"""LLM client for Hugging Face Inference API"""
+
+import os
+from typing import Iterator, Optional
+from huggingface_hub import InferenceClient
+
+
+class InferenceProviderClient:
+    """Client for Hugging Face Inference API"""
+
+    def __init__(
+        self,
+        model: str = "meta-llama/Llama-3.1-8B-Instruct",
+        api_key: Optional[str] = None,
+        temperature: float = 0.2,
+        max_tokens: int = 600
+    ):
+        """
+        Initialize the Inference client
+
+        Args:
+            model: Model identifier (default: Llama-3.1-8B-Instruct)
+            api_key: HuggingFace API token (defaults to HF_TOKEN env var)
+            temperature: Sampling temperature (0.0 to 1.0)
+            max_tokens: Maximum tokens to generate
+        """
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+        # Get API key from parameter or environment
+        api_key = api_key or os.getenv("HF_TOKEN")
+        if not api_key:
+            raise ValueError("HF_TOKEN environment variable must be set or api_key provided")
+
+        # Initialize Hugging Face Inference Client
+        self.client = InferenceClient(token=api_key)
+
+    def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None
+    ) -> str:
+        """
+        Generate a response from the LLM
+
+        Args:
+            prompt: User prompt
+            system_prompt: Optional system prompt
+            temperature: Override default temperature
+            max_tokens: Override default max tokens
+
+        Returns:
+            Generated text response
+        """
+        messages = []
+
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat_completion(
+            model=self.model,
+            messages=messages,
+            temperature=temperature or self.temperature,
+            max_tokens=max_tokens or self.max_tokens
+        )
+
+        return response.choices[0].message.content
+
+    def generate_stream(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None
+    ) -> Iterator[str]:
+        """
+        Generate a streaming response from the LLM
+
+        Args:
+            prompt: User prompt
+            system_prompt: Optional system prompt
+            temperature: Override default temperature
+            max_tokens: Override default max tokens
+
+        Yields:
+            Text chunks as they are generated
+        """
+        messages = []
+
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({"role": "user", "content": prompt})
+
+        stream = self.client.chat_completion(
+            model=self.model,
+            messages=messages,
+            temperature=temperature or self.temperature,
+            max_tokens=max_tokens or self.max_tokens,
+            stream=True
+        )
+
+        for chunk in stream:
+            try:
+                if hasattr(chunk, 'choices') and len(chunk.choices) > 0:
+                    if hasattr(chunk.choices[0], 'delta') and hasattr(chunk.choices[0].delta, 'content'):
+                        if chunk.choices[0].delta.content is not None:
+                            yield chunk.choices[0].delta.content
+            except (IndexError, AttributeError) as e:
+                # Gracefully handle malformed chunks
+                continue
+
+    def chat(
+        self,
+        messages: list[dict],
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stream: bool = False
+    ):
+        """
+        Multi-turn chat completion
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            temperature: Override default temperature
+            max_tokens: Override default max tokens
+            stream: Whether to stream the response
+
+        Returns:
+            Response text (or iterator if stream=True)
+        """
+        response = self.client.chat_completion(
+            model=self.model,
+            messages=messages,
+            temperature=temperature or self.temperature,
+            max_tokens=max_tokens or self.max_tokens,
+            stream=stream
+        )
+
+        if stream:
+            def stream_generator():
+                for chunk in response:
+                    try:
+                        if hasattr(chunk, 'choices') and len(chunk.choices) > 0:
+                            if hasattr(chunk.choices[0], 'delta') and hasattr(chunk.choices[0].delta, 'content'):
+                                if chunk.choices[0].delta.content is not None:
+                                    yield chunk.choices[0].delta.content
+                    except (IndexError, AttributeError):
+                        # Gracefully handle malformed chunks
+                        continue
+            return stream_generator()
+        else:
+            return response.choices[0].message.content
+
+
+def create_llm_client(
+    model: str = "meta-llama/Llama-3.1-8B-Instruct",
+    temperature: float = 0.7,
+    max_tokens: int = 2000
+) -> InferenceProviderClient:
+    """
+    Factory function to create and return a configured LLM client
+
+    Args:
+        model: Model identifier
+        temperature: Sampling temperature
+        max_tokens: Maximum tokens to generate
+
+    Returns:
+        Configured InferenceProviderClient
+    """
+    return InferenceProviderClient(
+        model=model,
+        temperature=temperature,
+        max_tokens=max_tokens
+    )
+
+
+# Available models (commonly used for OSINT tasks)
+AVAILABLE_MODELS = {
+    "llama-3.1-8b": "meta-llama/Llama-3.1-8B-Instruct",
+    "llama-3-8b": "meta-llama/Meta-Llama-3-8B-Instruct",
+    "qwen-32b": "Qwen/Qwen2.5-72B-Instruct",
+    "mistral-7b": "mistralai/Mistral-7B-Instruct-v0.3",
+}
+
+
+def get_model_identifier(model_name: str) -> str:
+    """Get full model identifier from short name"""
+    return AVAILABLE_MODELS.get(model_name, AVAILABLE_MODELS["llama-3.1-8b"])

src/prompts.py

@@ -0,0 +1,105 @@
+"""Prompt templates for OSINT investigation assistant"""
+
+from langchain_core.prompts import PromptTemplate
+
+
+SYSTEM_PROMPT = """You are an OSINT investigation assistant. Your responses must be SHORT and FOCUSED.
+
+STRICT RULES:
+1. ONLY recommend tools from the provided database - DO NOT suggest tools not in the list
+2. Keep your response under 300 words
+3. List 3-5 steps maximum
+4. Include tool names and URLs from the database
+5. NO lengthy explanations
+6. NO additional tools beyond what's provided
+
+Format:
+**Investigation Steps:**
+1. [Step] - Use [Tool Name] ([URL])
+2. [Step] - Use [Tool Name] ([URL])
+3. [Step] - Use [Tool Name] ([URL])
+
+**Why these tools:** [1-2 sentences max]"""
+
+
+INVESTIGATION_PROMPT_TEMPLATE = """USER QUESTION: {query}
+
+AVAILABLE TOOLS FROM DATABASE:
+{context}
+
+INSTRUCTIONS:
+- Provide 3-5 investigation steps ONLY
+- Use ONLY tools from the list above
+- Include tool name + URL for each step
+- Keep response under 300 words
+- Be specific and direct
+- NO lengthy explanations
+
+Respond with:
+**Steps:**
+1. [Action] using [Tool Name] ([URL])
+2. [Action] using [Tool Name] ([URL])
+3. [Action] using [Tool Name] ([URL])
+
+**Notes:** [1-2 sentences explaining why these specific tools]"""
+
+
+INVESTIGATION_PROMPT = PromptTemplate(
+    template=INVESTIGATION_PROMPT_TEMPLATE,
+    input_variables=["query", "context"]
+)
+
+
+FOLLOWUP_PROMPT_TEMPLATE = """You are an expert OSINT investigation assistant continuing a conversation.
+
+CONVERSATION HISTORY:
+{chat_history}
+
+USER FOLLOW-UP QUESTION:
+{query}
+
+RELEVANT OSINT TOOLS FROM DATABASE:
+{context}
+
+Based on the conversation history and the user's follow-up question, provide a helpful response. If they're asking for clarification or more details about a specific tool or technique, provide that information. If they're asking a new question, follow the structured investigation methodology format."""
+
+
+FOLLOWUP_PROMPT = PromptTemplate(
+    template=FOLLOWUP_PROMPT_TEMPLATE,
+    input_variables=["chat_history", "query", "context"]
+)
+
+
+TOOL_RECOMMENDATION_TEMPLATE = """Based on this investigation need: {query}
+
+Available tools:
+{context}
+
+Recommend the top 3-5 most relevant tools and explain why each is suitable. Format as:
+
+1. **Tool Name** ([URL])
+   - Category: [category]
+   - Cost: [cost]
+   - Why it's useful: [explanation]
+"""
+
+
+TOOL_RECOMMENDATION_PROMPT = PromptTemplate(
+    template=TOOL_RECOMMENDATION_TEMPLATE,
+    input_variables=["query", "context"]
+)
+
+
+def get_investigation_prompt(include_system: bool = True) -> PromptTemplate:
+    """Get the main investigation prompt template"""
+    return INVESTIGATION_PROMPT
+
+
+def get_followup_prompt() -> PromptTemplate:
+    """Get the follow-up conversation prompt template"""
+    return FOLLOWUP_PROMPT
+
+
+def get_tool_recommendation_prompt() -> PromptTemplate:
+    """Get the tool recommendation prompt template"""
+    return TOOL_RECOMMENDATION_PROMPT

src/rag_pipeline.py

@@ -0,0 +1,195 @@
+"""RAG pipeline for OSINT investigation assistant"""
+
+from typing import Iterator, Optional, List, Tuple
+from .vectorstore import OSINTVectorStore, create_vectorstore
+from .llm_client import InferenceProviderClient, create_llm_client
+from .prompts import (
+    SYSTEM_PROMPT,
+    INVESTIGATION_PROMPT,
+    get_investigation_prompt
+)
+
+
+class OSINTInvestigationPipeline:
+    """RAG pipeline for generating OSINT investigation methodologies"""
+
+    def __init__(
+        self,
+        vectorstore: Optional[OSINTVectorStore] = None,
+        llm_client: Optional[InferenceProviderClient] = None,
+        retrieval_k: int = 5
+    ):
+        """
+        Initialize the RAG pipeline
+
+        Args:
+            vectorstore: Vector store instance (creates default if None)
+            llm_client: LLM client instance (creates default if None)
+            retrieval_k: Number of tools to retrieve for context
+        """
+        self.vectorstore = vectorstore or create_vectorstore()
+        self.llm_client = llm_client or create_llm_client()
+        self.retrieval_k = retrieval_k
+
+    def retrieve_tools(self, query: str, k: Optional[int] = None) -> List:
+        """
+        Retrieve relevant OSINT tools for a query
+
+        Args:
+            query: User's investigation query
+            k: Number of tools to retrieve (uses default if None)
+
+        Returns:
+            List of relevant tool documents
+        """
+        k = k or self.retrieval_k
+        return self.vectorstore.similarity_search(query, k=k)
+
+    def generate_methodology(
+        self,
+        query: str,
+        stream: bool = False
+    ) -> str | Iterator[str]:
+        """
+        Generate investigation methodology for a query
+
+        Args:
+            query: User's investigation query
+            stream: Whether to stream the response
+
+        Returns:
+            Generated methodology (string or iterator)
+        """
+        # Retrieve relevant tools
+        relevant_tools = self.retrieve_tools(query)
+
+        # Format tools for context
+        context = self.vectorstore.format_tools_for_context(relevant_tools)
+
+        # Generate prompt
+        prompt_template = get_investigation_prompt()
+        full_prompt = prompt_template.format(query=query, context=context)
+
+        # Generate response
+        if stream:
+            return self.llm_client.generate_stream(
+                prompt=full_prompt,
+                system_prompt=SYSTEM_PROMPT
+            )
+        else:
+            return self.llm_client.generate(
+                prompt=full_prompt,
+                system_prompt=SYSTEM_PROMPT
+            )
+
+    def chat(
+        self,
+        message: str,
+        history: Optional[List[Tuple[str, str]]] = None,
+        stream: bool = False
+    ) -> str | Iterator[str]:
+        """
+        Handle a chat message with conversation history
+
+        Args:
+            message: User's message
+            history: Conversation history as list of (user_msg, assistant_msg) tuples
+            stream: Whether to stream the response
+
+        Returns:
+            Generated response (string or iterator)
+        """
+        # For now, treat each message as a new investigation query
+        # In the future, could implement follow-up handling
+        return self.generate_methodology(message, stream=stream)
+
+    def get_tool_recommendations(
+        self,
+        query: str,
+        k: int = 5
+    ) -> List[dict]:
+        """
+        Get tool recommendations with metadata
+
+        Args:
+            query: Investigation query
+            k: Number of tools to recommend
+
+        Returns:
+            List of tool dictionaries with metadata
+        """
+        docs = self.retrieve_tools(query, k=k)
+
+        tools = []
+        for doc in docs:
+            tool = {
+                "name": doc.metadata.get("name", "Unknown"),
+                "category": doc.metadata.get("category", "N/A"),
+                "cost": doc.metadata.get("cost", "N/A"),
+                "url": doc.metadata.get("url", "N/A"),
+                "description": doc.page_content,
+                "details": doc.metadata.get("details", "N/A")
+            }
+            tools.append(tool)
+
+        return tools
+
+    def search_tools_by_category(
+        self,
+        category: str,
+        k: int = 10
+    ) -> List[dict]:
+        """
+        Search tools by category
+
+        Args:
+            category: Tool category (e.g., "Archiving", "Social Media")
+            k: Number of tools to return
+
+        Returns:
+            List of tool dictionaries
+        """
+        docs = self.vectorstore.similarity_search(
+            query=category,
+            k=k,
+            filter_category=category
+        )
+
+        tools = []
+        for doc in docs:
+            tool = {
+                "name": doc.metadata.get("name", "Unknown"),
+                "category": doc.metadata.get("category", "N/A"),
+                "cost": doc.metadata.get("cost", "N/A"),
+                "url": doc.metadata.get("url", "N/A"),
+                "description": doc.page_content
+            }
+            tools.append(tool)
+
+        return tools
+
+
+def create_pipeline(
+    retrieval_k: int = 5,
+    model: str = "meta-llama/Llama-3.1-8B-Instruct",
+    temperature: float = 0.2
+) -> OSINTInvestigationPipeline:
+    """
+    Factory function to create a configured RAG pipeline
+
+    Args:
+        retrieval_k: Number of tools to retrieve
+        model: LLM model identifier
+        temperature: LLM temperature
+
+    Returns:
+        Configured OSINTInvestigationPipeline
+    """
+    vectorstore = create_vectorstore()
+    llm_client = create_llm_client(model=model, temperature=temperature)
+
+    return OSINTInvestigationPipeline(
+        vectorstore=vectorstore,
+        llm_client=llm_client,
+        retrieval_k=retrieval_k
+    )

src/vectorstore.py

@@ -0,0 +1,280 @@
+"""Supabase PGVector connection and retrieval functionality"""
+
+import os
+from typing import List, Dict, Any, Optional
+from supabase import create_client, Client
+from huggingface_hub import InferenceClient
+
+
+class Document:
+    """Simple document class to match LangChain interface"""
+
+    def __init__(self, page_content: str, metadata: dict):
+        self.page_content = page_content
+        self.metadata = metadata
+
+
+class OSINTVectorStore:
+    """Manages connection to Supabase PGVector database with OSINT tools"""
+
+    def __init__(
+        self,
+        supabase_url: Optional[str] = None,
+        supabase_key: Optional[str] = None,
+        hf_token: Optional[str] = None,
+        embedding_model: str = "sentence-transformers/all-mpnet-base-v2"
+    ):
+        """
+        Initialize the vector store connection
+
+        Args:
+            supabase_url: Supabase project URL (defaults to SUPABASE_URL env var)
+            supabase_key: Supabase anon key (defaults to SUPABASE_KEY env var)
+            hf_token: HuggingFace API token (defaults to HF_TOKEN env var)
+            embedding_model: HuggingFace model for embeddings
+        """
+        # Get credentials from parameters or environment
+        self.supabase_url = supabase_url or os.getenv("SUPABASE_URL")
+        self.supabase_key = supabase_key or os.getenv("SUPABASE_KEY")
+        self.hf_token = hf_token or os.getenv("HF_TOKEN")
+
+        if not self.supabase_url or not self.supabase_key:
+            raise ValueError("SUPABASE_URL and SUPABASE_KEY environment variables must be set")
+
+        if not self.hf_token:
+            raise ValueError("HF_TOKEN environment variable must be set")
+
+        # Initialize Supabase client
+        self.supabase: Client = create_client(self.supabase_url, self.supabase_key)
+
+        # Initialize HuggingFace Inference client for embeddings
+        self.embedding_model = embedding_model
+        self.hf_client = InferenceClient(token=self.hf_token)
+
+    def _generate_embedding(self, text: str) -> List[float]:
+        """
+        Generate embedding for text using HuggingFace Inference API
+
+        Args:
+            text: Text to embed
+
+        Returns:
+            List of floats representing the embedding vector (768 dimensions)
+        """
+        try:
+            # Use feature extraction to get embeddings
+            # Note: We rely on the API's default model which returns 768-dim embeddings
+            result = self.hf_client.feature_extraction(text=text)
+
+            # Convert to list (handles numpy arrays and nested lists)
+            import numpy as np
+
+            # If it's a numpy array, convert to list
+            if isinstance(result, np.ndarray):
+                if result.ndim > 1:
+                    result = result[0]  # Take first row if 2D
+                return result.tolist()
+
+            # If it's a nested list, flatten if needed
+            if isinstance(result, list) and len(result) > 0:
+                if isinstance(result[0], list):
+                    return result[0]  # Take first embedding if batched
+                # Handle nested numpy arrays in list
+                if isinstance(result[0], np.ndarray):
+                    return result[0].tolist()
+                return result
+
+            return result
+        except Exception as e:
+            raise Exception(f"Error generating embedding: {str(e)}")
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = 5,
+        filter_category: Optional[str] = None,
+        filter_cost: Optional[str] = None,
+        match_threshold: float = 0.5
+    ) -> List[Document]:
+        """
+        Perform similarity search on the OSINT tools database
+
+        Args:
+            query: Search query
+            k: Number of results to return
+            filter_category: Optional category filter
+            filter_cost: Optional cost filter (e.g., 'Free', 'Paid')
+            match_threshold: Minimum similarity threshold (0.0 to 1.0)
+
+        Returns:
+            List of Document objects with relevant OSINT tools
+        """
+        # Generate embedding for query
+        query_embedding = self._generate_embedding(query)
+
+        # Call RPC function
+        try:
+            response = self.supabase.rpc(
+                'match_bellingcat_tools',
+                {
+                    'query_embedding': query_embedding,
+                    'match_threshold': match_threshold,
+                    'match_count': k,
+                    'filter_category': filter_category,
+                    'filter_cost': filter_cost
+                }
+            ).execute()
+
+            # Convert results to Document objects
+            documents = []
+            for item in response.data:
+                doc = Document(
+                    page_content=item.get('content', ''),
+                    metadata={
+                        'id': item.get('id'),
+                        'name': item.get('name'),
+                        'category': item.get('category'),
+                        'url': item.get('url'),
+                        'cost': item.get('cost'),
+                        'details': item.get('details'),
+                        'similarity': item.get('similarity')
+                    }
+                )
+                documents.append(doc)
+
+            return documents
+
+        except Exception as e:
+            raise Exception(f"Error performing similarity search: {str(e)}")
+
+    def similarity_search_with_score(
+        self,
+        query: str,
+        k: int = 5
+    ) -> List[tuple]:
+        """
+        Perform similarity search and return documents with relevance scores
+
+        Args:
+            query: Search query
+            k: Number of results to return
+
+        Returns:
+            List of tuples (Document, score)
+        """
+        # Generate embedding for query
+        query_embedding = self._generate_embedding(query)
+
+        # Call RPC function
+        try:
+            response = self.supabase.rpc(
+                'match_bellingcat_tools',
+                {
+                    'query_embedding': query_embedding,
+                    'match_threshold': 0.0,  # Get all matches
+                    'match_count': k,
+                    'filter_category': None,
+                    'filter_cost': None
+                }
+            ).execute()
+
+            # Convert results to Document objects with scores
+            results = []
+            for item in response.data:
+                doc = Document(
+                    page_content=item.get('content', ''),
+                    metadata={
+                        'id': item.get('id'),
+                        'name': item.get('name'),
+                        'category': item.get('category'),
+                        'url': item.get('url'),
+                        'cost': item.get('cost'),
+                        'details': item.get('details')
+                    }
+                )
+                score = item.get('similarity', 0.0)
+                results.append((doc, score))
+
+            return results
+
+        except Exception as e:
+            raise Exception(f"Error performing similarity search: {str(e)}")
+
+    def get_retriever(self, k: int = 5):
+        """
+        Get a retriever-like object for LangChain compatibility
+
+        Args:
+            k: Number of results to return
+
+        Returns:
+            Simple retriever object with get_relevant_documents method
+        """
+        class SimpleRetriever:
+            def __init__(self, vectorstore, k):
+                self.vectorstore = vectorstore
+                self.k = k
+
+            def get_relevant_documents(self, query: str) -> List[Document]:
+                return self.vectorstore.similarity_search(query, k=self.k)
+
+        return SimpleRetriever(self, k)
+
+    def format_tools_for_context(self, documents: List[Document]) -> str:
+        """
+        Format retrieved tools for inclusion in LLM context
+
+        Args:
+            documents: List of retrieved Document objects
+
+        Returns:
+            Formatted string with tool information
+        """
+        formatted_tools = []
+
+        for i, doc in enumerate(documents, 1):
+            metadata = doc.metadata
+            tool_info = f"""
+Tool {i}: {metadata.get('name', 'Unknown')}
+Category: {metadata.get('category', 'N/A')}
+Cost: {metadata.get('cost', 'N/A')}
+URL: {metadata.get('url', 'N/A')}
+Description: {doc.page_content}
+Details: {metadata.get('details', 'N/A')}
+"""
+            formatted_tools.append(tool_info.strip())
+
+        return "\n\n---\n\n".join(formatted_tools)
+
+    def get_tool_categories(self) -> List[str]:
+        """Get list of available tool categories from database"""
+        try:
+            response = self.supabase.table('bellingcat_tools')\
+                .select('category')\
+                .execute()
+
+            # Extract unique categories
+            categories = set()
+            for item in response.data:
+                if item.get('category'):
+                    categories.add(item['category'])
+
+            return sorted(list(categories))
+
+        except Exception as e:
+            # Return common categories as fallback
+            return [
+                "Archiving",
+                "Social Media",
+                "Geolocation",
+                "Image Analysis",
+                "Domain Investigation",
+                "Network Analysis",
+                "Data Extraction",
+                "Verification"
+            ]
+
+
+def create_vectorstore() -> OSINTVectorStore:
+    """Factory function to create and return a configured vector store"""
+    return OSINTVectorStore()