🔍 Search_Net

Search_Net is a high-performance, asynchronous hybrid search engine built with FastAPI and PostgreSQL (pgvector). It features automated asynchronous data ingestion pipelines via Wikipedia, entity extraction using Groq Cloud LLMs, zero-RAM semantic embeddings via Hugging Face Inference APIs, and sub-5ms fuzzy search autocomplete.

💡 Low-Memory Footprint: The system architecture is strictly Cloud-API driven, optimizing local memory utilization to under 50 MB. This makes it fully compatible with low-memory hosting tiers, such as Render Free or Starter 512MB instances.

---

🚀 Architectural Highlights

• Async-First Architecture: Powered by FastAPI and SQLAlchemy 2.0 AsyncIO with an asyncpg driver for non-blocking concurrent request handling.
• Hybrid Search Engine: Combines dense 384-dimensional vector embeddings (cosine similarity) with hard relational filters and PostgreSQL JSONB metadata traversal.
• Zero-RAM Embedding Generation: Leverages the hosted Hugging Face Inference API over HTTP rather than loading heavy local model weights (torch / transformers) into server memory.
• Intelligent Query Decomposition: Utilizes Groq Cloud API (llama-3.1-8b-instant) to parse natural language search inputs and dynamically extract implicit metadata filters (e.g., parsing "Marvel genius inventor" into semantic text + a {"universe": "Marvel"} query layer).
• High-Speed Autocomplete: Utilizes a trigram GIN index (pg_trgm) directly on the database to serve prefix/fuzzy character queries in under 5ms.
• Robust Ingest Pipeline: Atomic upserts handled via PostgreSQL ON CONFLICT DO UPDATE, mapped safely around internal SQLAlchemy metadata properties.

---

🛠️ Tech Stack

Component	Technology
Backend Framework	FastAPI, Uvicorn
Database & Extensions	PostgreSQL 16+, pgvector, pg_trgm
ORM & Migrations	SQLAlchemy 2.0 (Async) + Alembic / Raw initialization
LLM Engine	Groq Cloud API (llama-3.1-8b-instant)
Vector Model Engine	Hugging Face Inference API (all-MiniLM-L6-v2)
HTTP Client	HTTPX (Async client with connection pooling)

---

📋 Directory Structure

Search_Net/
├── app/
│   ├── __init__.py
│   ├── main.py          # Application initialization & lifespan setup
│   ├── database.py      # Async engine configuration & raw index bootstrap
│   ├── models.py        # SQLAlchemy 2.0 Unified Entity model 
│   ├── schemas.py       # Pydantic v2 validation models
│   ├── auth.py          # Basic Admin Authentication layer
│   ├── etl_worker.py    # Background ETL pipeline orchestration
│   └── routers/
│       ├── admin.py     # Ingestion endpoints (Protected)
│       └── search.py    # Search and suggestion routes (Public)
├── .env                 # Local environment configuration
├── requirements.txt     # Production dependencies (Lightweight)
└── README.md

---

🔑 Environment Variables

Create a .env file in the root directory and populate it with your credentials:

# Database Connection (must use the asyncpg driver)
DATABASE_URL=postgresql+asyncpg://<user>:<password>@<host>:<port>/<dbname>

# Groq Cloud API Configuration
GROQ_API_KEY=your_groq_api_key_here

# Hugging Face Inference API Configuration
HF_API_KEY=your_huggingface_api_key_here

# Admin Security 
ADMIN_SECRET_TOKEN=your_secure_admin_token_here

---

🏠 Local Optimization (Offline Capability)

If you prefer to run Search_Net entirely locally without relying on external cloud APIs, you can swap out the components for a self-hosted stack. Note that local execution will increase RAM usage beyond the 50 MB production target.

1. Database (Docker Setup)

Spin up a local PostgreSQL instance pre-configured with pgvector and pg_trgm:

docker run --name search_net_db -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=search_net -p 5432:5432 -d ankane/pgvector:latest

2. Local LLM (via Ollama)

Instead of Groq Cloud, install Ollama and run Llama 3 locally:

ollama run llama3

Update your code's HTTP base URL from Groq (https://api.groq.com) to Ollama (http://localhost:11434/v1).

3. Local Embeddings

To eliminate the Hugging Face Inference API, install sentence-transformers directly. Warning: This will increase memory usage by ~500MB to 1GB to hold the model in RAM.

pip install sentence-transformers torch

Modify your embedding utility to load the model locally:

from sentence_transformers import SentenceTransformer
model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
# map embeddings synchronously or wrap in asyncio.to_thread

---

⚡ Scaling Up: Upgrading to Premium APIs

For production environments requiring complex query handling, higher contextual awareness, and greater multi-lingual search precision, swap the default lightweight models for production-grade enterprise APIs:

1. Advanced Query Decomposition (LLM Upgrade)

The current llama-3.1-8b-instant model is built for speed. For highly nested queries, complex intent extraction, or massive metadata filtering schemas, upgrade to:

• Groq Scale: llama-3.3-70b-specdec or mixtral-8x7b-32768 (Highly complex entities, maintained low-latency).
• OpenAI API: gpt-4o or gpt-4o-mini (For world-class structured JSON outputs via Tool Calling / Structured Outputs feature).

2. Enterprise Semantic Search (Embeddings Upgrade)

The 384-dimensional all-MiniLM-L6-v2 can suffer from performance degradation on long-form text or diverse domain vocabularies. You can swap it for:

• Cohere Embed v3: (embed-english-v3.0 / embed-multilingual-v3.0). Features compression-aware embeddings specifically trained for production search index quality.
• OpenAI Embeddings v3: text-embedding-3-large (Configure for 1536 or 3072 dimensions). Offers deeper nuances, though it requires modifying your database vector schema column definition to support higher dimensions (e.g., Vector(1536)).