### Setup and Run InvestigatorAI API

Source: https://github.com/ovokpus/investigatorai/blob/main/README.md

Instructions for setting up the InvestigatorAI project, including starting Docker containers, installing dependencies, configuring environment variables, and running the API server and frontend.

```bash
# 1. Start infrastructure containers
docker-compose up -d

# 2. Install dependencies
pip install -e .

# 3. Configure environment
cp config.env.template config.env
# Edit config.env with your API keys

# 4. Run API server
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# 5. Run frontend (in separate terminal)
cd frontend && npm install && npm run dev
```

--------------------------------

### Install Dependencies and Start Development Server (npm)

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

These commands are used to install project dependencies and start the local development server for the Next.js application. Ensure Node.js 18+ is installed.

```bash
npm install
npm run dev
```

--------------------------------

### Bash Local Development Setup Commands

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Provides the sequence of bash commands to set up the local development environment for the InvestigatorAI project. This includes installing dependencies, starting Redis via Docker Compose, configuring Qdrant Cloud, and running the API server with Uvicorn.

```bash
# 1. Install dependencies
uv sync

# 2. Start services (Redis only - Qdrant Cloud is remote)
docker-compose up -d redis

# 3. Configure environment for Qdrant Cloud
export QDRANT_URL="your_qdrant_cloud_url"
export QDRANT_PROVIDER="cloud"
export OPENAI_API_KEY="your_openai_key"

# 4. Start API server
cd api && uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Environment Setup (Python)

Source: https://github.com/ovokpus/investigatorai/blob/main/data/README.md

Install project dependencies using pip and configure API keys by copying and editing the environment template file.

```bash
# Install dependencies
pip install -r requirements.txt

# Configure API keys in config.env
cp config.env.template config.env
# Edit config.env with your API keys
```

--------------------------------

### GitHub Actions Workflow for Test Suite

Source: https://github.com/ovokpus/investigatorai/blob/main/api/tests/README.md

An example GitHub Actions YAML configuration to set up a CI/CD pipeline that checks out the code, sets up Python, installs dependencies, and runs the LangSmith tests.

```yaml
name: Test Suite
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: PYTHONPATH=$PWD python api/tests/run_langsmith_tests.py
        env:
          LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
          LANGSMITH_TRACING: true
```

--------------------------------

### Vector Document Search Endpoint (Python Example)

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Demonstrates a Python example of calling the '/search' GET endpoint for vector document search. It shows how to query for specific terms like 'AML compliance' and retrieve a list of relevant document snippets along with their metadata and relevance scores. This is used for finding information within indexed regulatory documents.

```Python
GET /search?query=AML%20compliance&max_results=5

# Response: List[VectorSearchResult]
[
    {
        "content": "Banks must comply with 31 CFR 1020.320...",
        "metadata": {
            "filename": "FFIEC_BSA_Manual.pdf",
            "content_category": "sar_guidance"
        },
        "score": 0.89
    }
]
```

--------------------------------

### Start Production Server (npm)

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

Starts the production server for the application using npm. This command is typically used after the application has been built.

```bash
npm start
```

--------------------------------

### Frontend Log Examples (JavaScript)

Source: https://github.com/ovokpus/investigatorai/blob/main/docs/application/LOGGING_IMPLEMENTATION.md

Shows examples of frontend log output, including console logs with timestamps and levels, and structured JSON log entries with detailed context. These examples highlight different logging formats used by the frontend.

```javascript
// Console output
[2025-08-23T14:18:47.000Z] INFO: Investigation Event: investigation_completed | {"investigationId":"INV_123","duration_ms":62186}

// Structured log entry
{
  "timestamp": "2025-08-23T14:18:47.000Z",
  "level": 1,
  "message": "Investigation Event: investigation_completed",
  "context": {
    "investigationId": "INV_123",
    "duration_ms": 62186,
    "component": "investigation"
  },
  "sessionId": "session_1692800327_abc123"
}
```

--------------------------------

### Backend Log Examples (Text)

Source: https://github.com/ovokpus/investigatorai/blob/main/docs/application/LOGGING_IMPLEMENTATION.md

Illustrates the format of backend log entries, including timestamp, log level, module, message, and file information. These examples show both INFO level application logs and performance metrics.

```text
2025-08-23 14:18:47,157 | INFO | api.middleware.logging_middleware | POST /investigate - 200 (62186.67ms) | logging_config.py:194
2025-08-23 14:18:47,152 | INFO | api.services.memory_optimizer | 💾 Process Memory: 254.8MB | memory_optimizer.py:210
```

--------------------------------

### Vercel CLI Deployment Commands

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/VERCEL_DEPLOYMENT.md

Commands to deploy the frontend application using the Vercel Command Line Interface. This includes installing the CLI, logging in, navigating to the project directory, and initiating a production deployment. It also covers adding and setting environment variables for the deployment.

```bash
npm i -g vercel
vercel login
cd frontend
vercel --prod
vercel env add NEXT_PUBLIC_API_URL production
vercel --prod
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ovokpus/investigatorai/blob/main/rag/README.md

Installs all necessary Python packages for the InvestigatorAI project, including libraries for interacting with OpenAI, Qdrant, and PDF processing. It uses 'uv pip' for efficient dependency management.

```bash
uv pip install --system langchain langchain-openai qdrant-client python-dotenv PyPDF2 langchain-text-splitters
```

--------------------------------

### Tavily Web Intelligence Search Endpoint (Python Example)

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Provides a Python example for querying the '/web-search' GET endpoint, utilizing Tavily for web intelligence. It illustrates how to search for topics like 'FATF high risk jurisdictions' and receive a structured response containing the search result summary, the source, and a timestamp. This endpoint is for gathering external web-based information.

```Python
GET /web-search?query=FATF%20high%20risk%20jurisdictions&max_results=5

# Response: AgentToolResponse
{
    "result": "1. Current FATF High-Risk Jurisdictions...",
    "source": "Tavily",
    "timestamp": "2025-01-04T10:30:00Z"
}
```

--------------------------------

### ArXiv Academic Research Search Endpoint (Python Example)

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Shows a Python example of using the '/arxiv-search' GET endpoint to query academic research on ArXiv. It demonstrates how to search for terms like 'fraud detection' and receive a response containing the research summary, source ('ArXiv'), and timestamp. This is useful for accessing scholarly articles and research papers.

```Python
GET /arxiv-search?query=fraud%20detection&max_results=4

# Response: AgentToolResponse  
{
    "result": "1. Advanced ML Techniques for Fraud Detection...",
    "source": "ArXiv",
    "timestamp": "2025-01-04T10:30:00Z"
}
```

--------------------------------

### Start Jupyter Notebook Server

Source: https://github.com/ovokpus/investigatorai/blob/main/notebooks/README.md

Starts the Jupyter Notebook server, allowing access to the notebooks through a web browser.

```bash
jupyter notebook
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ovokpus/investigatorai/blob/main/api/tests/README.md

Bash commands to install necessary Python packages using `pip`. This includes installing specific libraries like `langsmith` and `requests`, and installing the project itself in development mode.

```bash
# Install missing packages
pip install langsmith requests
pip install -e .  # Install project in development mode
```

--------------------------------

### Frontend Development Server Command

Source: https://github.com/ovokpus/investigatorai/blob/main/docs/DEMO_GUIDE.md

Command to start the frontend development server. This command is used to build and serve the InvestigatorAI user interface during development.

```bash
npm run dev
```

--------------------------------

### Troubleshooting Missing Dependencies

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/VERCEL_DEPLOYMENT.md

Command to resolve build failures caused by missing project dependencies. It ensures that all necessary packages are installed by running `npm install`.

```bash
# Solution: Ensure all dependencies are in package.json
npm install
```

--------------------------------

### InvestigatorAI API Startup Logs

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/railway/README.md

Example log output indicating a successful startup of the InvestigatorAI API on Railway. Shows successful connections to Redis and Qdrant Cloud, confirming the API is ready to serve requests.

```bash
# Railway logs should show:
# 🚂 Starting InvestigatorAI API on Railway...
# ✅ Connected to Redis successfully
# ☁️ Connected to Qdrant Cloud successfully  
# 🎉 InvestigatorAI API ready on port 8000!
```

--------------------------------

### Start Multi-Agent Investigation API Endpoint

Source: https://github.com/ovokpus/investigatorai/blob/main/README.md

Example of how to call the API endpoint to initiate a multi-agent investigation for a suspicious wire transfer. It includes the request payload and expected response structure.

```bash
# Start multi-agent investigation (returns comprehensive analysis)
curl -X POST http://localhost:8000/investigate \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 75000,
    "currency": "USD",
    "description": "International wire transfer",
    "customer_name": "John Doe",
    "account_type": "Personal",
    "risk_rating": "High",
    "country_to": "Romania"
  }'

# Expected response includes:
# - investigation_id: "INV_20250131_XXXXXX_XXXX" 
# - final_decision: "requires_review" | "suspicious_activity" | "proceed_with_caution" 
# - agents_completed: 4 (regulatory_research, evidence_collection, compliance_check, report_generation)
# - full_results: {comprehensive investigation data from all agents}
```

--------------------------------

### Local Development Environment Configuration

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/README.md

Steps and configuration for setting up the local development environment. Includes cloning the repository, configuring environment variables, and starting services using Docker Compose and Uvicorn.

```bash
# Clone repository
git clone https://github.com/ovokpus/InvestigatorAI.git
cd InvestigatorAI

# Configure environment for Qdrant Cloud
cp config.env.template .env
# Edit .env with your API keys and Qdrant Cloud URL

# Start local Redis (Qdrant Cloud is remote)
docker-compose up -d redis

# Start API locally
cd api
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Start frontend locally (new terminal)
cd frontend
npm install
npm run dev

# Start all local services
docker-compose up -d

# Access applications
# Frontend: http://localhost:3000
# API: http://localhost:8000
# API Docs: http://localhost:8000/docs
```

--------------------------------

### Qdrant Provider Configuration Options

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/README.md

Demonstrates how to configure the QDRANT_PROVIDER environment variable to switch between different Qdrant deployment types (Cloud, Railway, Local).

```bash
# Qdrant Provider Settings
QDRANT_PROVIDER=cloud    # For Qdrant Cloud
QDRANT_PROVIDER=railway  # For Railway Qdrant (deprecated)
QDRANT_PROVIDER=local    # For local Docker Qdrant
```

--------------------------------

### Troubleshoot Frontend Loading Issues

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/README.md

Commands and steps to troubleshoot frontend loading problems. This includes checking Vercel deployment status, API connectivity, and environment variables.

```bash
# Check Vercel deployment status
# Visit: https://vercel.com/dashboard

# Check API connectivity
curl https://investigatorai-production.up.railway.app/health

# Check environment variables
# Vercel dashboard → Project → Settings → Environment Variables
```

--------------------------------

### Troubleshoot Vector Database Issues

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/README.md

Commands and steps to troubleshoot vector database issues. This includes testing Qdrant Cloud connection, checking GitHub Actions logs, and verifying environment variables.

```bash
# Test Qdrant Cloud connection
curl "https://your-qdrant-url/collections"

# Check GitHub Actions logs
# GitHub → Actions → Update Vector Database → Latest run

# Verify environment variables
echo $QDRANT_URL
echo $QDRANT_PROVIDER
```

--------------------------------

### GitHub Actions Workflow Success Log

Source: https://github.com/ovokpus/investigatorai/blob/main/rag/README.md

Example log output from a successful GitHub Actions workflow execution, indicating successful dependency installation, PDF processing, chunk uploading, and vector database initialization. This serves as a confirmation of a successful update.

```bash
# Workflow logs should show:
✅ Dependencies installed successfully
📚 Processing 23 PDF documents...
📦 Uploading batch 15/15 (312 chunks)
🎉 Vector database initialization complete!
📊 Total: 3,312 chunks uploaded to Qdrant Cloud
```

--------------------------------

### Vercel Configuration (vercel.json)

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/VERCEL_DEPLOYMENT.md

The vercel.json file configures Vercel-specific build and deployment settings for the Next.js application. It specifies build commands, output directories, framework, installation commands, and environment variables, including the crucial NEXT_PUBLIC_API_URL.

```json
{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "framework": "nextjs",
  "installCommand": "npm install",
  "env": {
    "NEXT_PUBLIC_API_URL": "@api_url"
  }
}
```

--------------------------------

### Manually Initialize Vector Database

Source: https://github.com/ovokpus/investigatorai/blob/main/rag/README.md

Provides commands to manually trigger the vector database initialization process, which can be used as a fallback if GitHub Actions fail. It includes options for local execution and execution on the Railway platform.

```bash
# If GitHub Actions fails, run locally:
python rag/init_vector_database.py
```

```bash
# Or use Railway CLI to run on production:
railway run python rag/init_vector_database.py
```

--------------------------------

### System Health Check Endpoint (JSON Example)

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Illustrates the JSON response from the '/health' GET endpoint, which provides a system health check. It indicates the operational status of the system, including the vector store and Redis connection status, along with the current timestamp and software version. This is crucial for monitoring the overall health of the InvestigatorAI services.

```JSON
{
    "status": "healthy",
    "vector_store_initialized": true,
    "redis_connected": true,
    "timestamp": "2025-01-04T10:30:00Z",
    "version": "1.0.0"
}
```

--------------------------------

### Display Qdrant API Key

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/railway/README.md

Command to display the Qdrant API key from the environment. This is a manual check to confirm that the API key is accessible and correctly formatted for Qdrant Cloud authentication.

```bash
echo $QDRANT_API_KEY
```

--------------------------------

### Deploy Frontend (Vercel)

Source: https://github.com/ovokpus/investigatorai/blob/main/deploy/README.md

Commands for deploying the frontend application. Automatic deployment is triggered by pushing to the 'deploy' branch. Manual deployment can be initiated using the Vercel CLI.

```bash
# Automatic deployment
git push origin deploy  # Triggers Vercel build

# Manual deployment
cd frontend
vercel --prod
```

--------------------------------

### Install Jupyter and InvestigatorAI Dependencies

Source: https://github.com/ovokpus/investigatorai/blob/main/notebooks/README.md

Installs Jupyter Notebook, ipykernel, and the InvestigatorAI package. This is a prerequisite for running the provided notebooks.

```bash
pip install jupyter notebook ipykernel
pip install -e .
```

--------------------------------

### Setup and Dependency Loading in Python

Source: https://github.com/ovokpus/investigatorai/blob/main/notebooks/investigator_ai_enhanced_notebook.ipynb

This Python script loads necessary dependencies, including libraries for API interaction, document processing, and AI model integration. It also handles environment variable loading and checks for required API keys before initializing the OpenAI LLM and embeddings.

```python
# SECTION 1: DEPENDENCIES AND SETUP
import os
import uuid
import requests
from datetime import datetime
from pathlib import Path
from typing import List, Dict, Any, Optional
from dotenv import load_dotenv

# LangChain and LangGraph imports
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.document_loaders import PyMuPDFLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_qdrant import QdrantVectorStore
from langchain_core.messages import HumanMessage, BaseMessage
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langgraph.graph import END, StateGraph
from typing import TypedDict
import fitz  # PyMuPDF
import re
import time

# Environment variable loading
print("📦 Loading dependencies and environment variables...")
start_time = time.time()
load_dotenv()
load_time = time.time() - start_time
print(f"✅ All dependencies loaded successfully! ({load_time:.2f}s)")
print()

# Check API keys
def check_api_keys():
    """Check if required API keys are available"""
    required_keys = ['OPENAI_API_KEY', 'TAVILY_SEARCH_API_KEY']
    missing_keys = []
    
    for key in required_keys:
        if not os.getenv(key):
            missing_keys.append(key)
    
    if missing_keys:
        print(f"⚠️  Missing API keys: {', '.join(missing_keys)}")
        print("💡 Set these in your environment or .env file")
        return False
    else:
        print("✅ All required API keys found")
        return True

# Initialize components
api_keys_available = check_api_keys()

if api_keys_available:
    # Initialize LLM and embeddings
    embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
    llm = ChatOpenAI(model="gpt-4", temperature=0)
    print("✅ OpenAI LLM and embeddings initialized")
else:
    embeddings = None
    llm = None
    print("❌ Cannot initialize LLM - API keys missing")

print("\n🔧 InvestigatorAI initialization complete!")

```

--------------------------------

### Build for Local Production (npm)

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

Builds the application for local production. This command optimizes the code for deployment and typically precedes starting the production server.

```bash
npm run build
npm start
```

--------------------------------

### Install Core Dependencies for RAGAS Evaluation

Source: https://github.com/ovokpus/investigatorai/blob/main/notebooks/investigator_ai_ragas_evaluation.ipynb

Installs essential Python libraries for conducting RAGAS evaluations, including core RAGAS components, Langchain integrations, document loaders, and environment variable management.

```python
import os
import sys
import asyncio
from getpass import getpass
from datetime import datetime
from typing import List, Dict, Any, Callable
import pandas as pd
import json

from ragas.llms import LangchainLLMWrapper
from ragas.embeddings import LangchainEmbeddingsWrapper
from ragas.testset import TestsetGenerator
from langchain_openai import ChatOpenAI
from langchain_openai import OpenAIEmbeddings

from langchain_community.document_loaders import DirectoryLoader
from langchain_community.document_loaders import PyMuPDFLoader
from dotenv import load_dotenv
```

--------------------------------

### YAML Troubleshooting Memory Issues

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Example snippet from a docker-compose.yml file showing how to increase memory allocation for a service, specifically the `init-docs` service, to resolve Out-Of-Memory errors during document processing.

```yaml
# Solution: Increase memory allocation
docker-compose.yml:
  init-docs:
    deploy:
      resources:
        limits:
          memory: 4G
```

--------------------------------

### Create Next.js Project (npx)

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

Initializes a new Next.js project with specific configurations including TypeScript, Tailwind CSS, ESLint, and the App Router. It also sets up source directory and import aliases, while disabling Turbopack.

```bash
npx create-next-app@latest frontend \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias="@/*" \
  --no-turbopack
```

--------------------------------

### Get Exchange Rates

Source: https://github.com/ovokpus/investigatorai/blob/main/README.md

Retrieves the current exchange rate between two currencies.

```APIDOC
## GET /exchange-rate

### Description
Retrieves the current exchange rate between two currencies.

### Method
GET

### Endpoint
/exchange-rate

### Parameters
#### Query Parameters
- **from_currency** (string) - Required - The currency to convert from (e.g., "USD").
- **to_currency** (string) - Required - The currency to convert to (e.g., "EUR").

### Request Example
`curl "http://localhost:8000/exchange-rate?from_currency=USD&to_currency=EUR"`

### Response
#### Success Response (200)
- **from_currency** (string) - The source currency.
- **to_currency** (string) - The target currency.
- **rate** (number) - The exchange rate.

#### Response Example
```json
{
  "from_currency": "USD",
  "to_currency": "EUR",
  "rate": 0.92
}
```
```

--------------------------------

### GET /cache/stats

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

Retrieves statistics about the API cache.

```APIDOC
## GET /cache/stats

### Description
Retrieves statistics about the API cache.

### Method
GET

### Endpoint
/cache/stats

### Parameters
#### Query Parameters
None

### Request Example
```
GET /cache/stats
```

### Response
#### Success Response (200)
- **cache** (object) - Cache statistics.
  - **hit_rate** (number) - The cache hit rate.
  - **total_calls** (integer) - The total number of cache calls.
  - **cache_size** (integer) - The current size of the cache.
- **timestamp** (string) - The timestamp of the statistics.
- **endpoints** (array) - A list of endpoints and their cache statistics.

#### Response Example
```json
{
  "cache": {
    "hit_rate": 0.85,
    "total_calls": 1000,
    "cache_size": 500
  },
  "timestamp": "2023-10-27T10:00:00Z",
  "endpoints": []
}
```
```

--------------------------------

### Vector Store Service Interface (Python)

Source: https://github.com/ovokpus/investigatorai/blob/main/api/README.md

Defines the Python interface for the VectorStoreManager class, which integrates with Qdrant for optimized search capabilities. It includes methods for initializing the store from documents, connecting to an existing store, and performing hybrid searches. This service is fundamental for managing and querying indexed regulatory documents.

```Python
class VectorStoreManager:
    def initialize_from_documents(documents: List[Document]):
        """Process and index regulatory documents"""
        
    def connect_existing() -> 'VectorStoreManager':
        """Connect to pre-initialized vector store"""
        
    def search(query: str, k: int = 5) -> List[VectorSearchResult]:
        """Hybrid BM25 + Dense vector search"""
```

--------------------------------

### Configure Environment Variables for InvestigatorAI

Source: https://github.com/ovokpus/investigatorai/blob/main/rag/README.md

Ensures that the necessary environment variables, OPENAI_API_KEY and QDRANT_URL, are correctly set in the .env file for the project to function. This is crucial for authentication with OpenAI and connection to Qdrant.

```bash
# Check .env file exists and contains required keys
cat .env | grep -E "(OPENAI_API_KEY|QDRANT_URL)"
```

--------------------------------

### GET /search

Source: https://github.com/ovokpus/investigatorai/blob/main/frontend/README.md

Searches for documents based on a query.

```APIDOC
## GET /search

### Description
Searches for documents based on a query.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
- **max_results** (integer) - Optional - The maximum number of results to return.

### Request Example
```
GET /search?query=AML%20compliance%20requirements&max_results=5
```

### Response
#### Success Response (200)
- **results** (array) - An array of document search results.
  - **content** (string) - The content of the document.
  - **metadata** (object) - Metadata associated with the document.
  - **score** (number) - The relevance score of the document.
  - **source** (string) - The source of the document.

#### Response Example
```json
[
  {
    "content": "Document content here...",
    "metadata": {},
    "score": 0.95,
    "source": "example.com"
  }
]
```
```