SkillVector

Intelligent Semantic Search API with Vector Database & RAG

A production-ready semantic search engine powered by vector embeddings, multiple AI providers, and RAG (Retrieval Augmented Generation) pattern.

Features • Quick Start • API Usage • Architecture • Roadmap

Features

Core Capabilities

• Semantic Search: Find relevant results based on meaning, not just keywords
• Complex Query Support: Handles multi-criteria queries (experience + location, skills + role)
• Multi-AI Provider Support: OpenAI, Anthropic, Google Gemini, Ollama, HuggingFace
• Vector Database Integration: Qdrant for high-performance similarity search
• RAG Pattern: Retrieval Augmented Generation for context-aware AI responses
• Multi-Format Data Parsing: CSV, JSON, and TXT file support
• Pagination: Efficient result pagination with metadata
• Lightning Fast: Built on Bun runtime for maximum performance

Technical Features

• Type-Safe: Full TypeScript implementation
• RESTful API: Clean and intuitive Hono-based endpoints
• Flexible Embeddings: Support for multiple embedding models
• Vector Similarity: Cosine similarity search with 3072-dimensional vectors
• Health Monitoring: Built-in health check endpoints
• Environment Config: Secure credential management

Quick Start

Prerequisites

• Bun 1.0+
• Qdrant running locally or remote instance
• API keys for AI providers (OpenAI, Anthropic, etc.)

Installation

# Clone the repository
git clone https://github.com/MarkAronov/SkillVector.git
cd SkillVector

# Install dependencies
bun install

# Configure environment variables
cp .env.example .env
# Add your API keys to .env

# Start Qdrant (if running locally)
docker run -p 6333:6333 qdrant/qdrant

# Start the development server
bun run dev

# In a new terminal, start the frontend (optional)
cd frontend
bun install
bun run dev

Access the app at http://localhost:5173

SDKs

We provide a TypeScript SDK for easy integration with SkillVector's API.

Install and use the SDK:

# from project root
npm run build:sdk
# or
cd sdk/typescript && npm run build

Once built you can publish or use the compiled package, or use the SkillVectorClient in your projects as shown in sdk/typescript/README.md.

There's also a frontend SDK docs page available in the running app at /sdk that provides quick examples and links.

API Usage- Bun 1.0+

Search Endpoint

GET /api/search?query=<search_term>&limit=<num>&offset=<num>&provider=<ai_provider>

Parameters

Parameter	Type	Default	Description
query	string	required	Search query (semantic search)
limit	number	5	Results per page (1-50)
offset	number	0	Skip N results (pagination)
provider	string	openai	AI provider for answer generation

Example Request

curl "http://localhost:3000/api/search?query=senior+backend+developer&limit=10&offset=0&provider=openai"

Example Response

{
  "answer": "Based on the search results, here are the senior backend developers...",
  "sources": [
    {
      "pageContent": "John Doe - Senior Backend Engineer with 8 years of experience...",
      "metadata": {
        "name": "John Doe",
        "skills": "Node.js, TypeScript, PostgreSQL",
        "location": "USA"
      }
    }
  ],
  "pagination": {
    "total": 25,
    "returned": 10,
    "limit": 10,
    "offset": 0
  }
}

Health Check

GET /health

Architecture

Tech Stack

• Runtime: Bun (faster Node.js alternative)
• Framework: Hono (lightweight web framework)
• Vector DB: Qdrant (similarity search)
• AI Orchestration: LangChain.js
• Embeddings: OpenAI text-embedding-3-large (3072 dimensions)
• LLM Providers: OpenAI, Anthropic, Gemini, Ollama, HuggingFace

How It Works

1. User Query → Converted to vector embedding (3072 dimensions)
2. Vector Search → Qdrant finds similar documents via cosine similarity
3. Context Retrieval → Top K relevant documents retrieved
4. AI Generation → LLM generates answer using retrieved context (RAG)
5. Response → JSON with answer, sources, and pagination metadata

Configuration

Backend (.env)

OPENAI_API_KEY=<key>
QDRANT_HOST=localhost              # or <cluster>.qdrant.io
QDRANT_API_KEY=                    # only for cloud
QDRANT_PROTOCOL=http               # or https
PORT=3000
OPENAI_MODEL=gpt-4o-mini
EMBEDDING_MODEL=text-embedding-3-large

Frontend (.env)

VITE_API_URL=http://localhost:3000  # or production URL

Deployment

Free Tier Stack ($0/month + OpenAI usage)

Service	Tier	Purpose
Qdrant Cloud	1GB free	Vector database
Render	750hrs/month	Backend API
Vercel	100GB bandwidth	Frontend

Verification

curl https://<app>.onrender.com/health
curl "https://<app>.onrender.com/api/search?query=developer"

Limitations

Render Free Tier

• Hibernates after 15min inactivity
• Cold start: ~30s
• Mitigation: UptimeRobot (ping every 14min)

Qdrant Free Tier

• 1GB RAM (~100k-500k vectors)
• Single node

Costs

• Hosting: $0/month
• OpenAI API: ~$1-5/month (usage-based)

Contributing

Contributions are welcome! Please see our CONTRIBUTING.md for detailed guidelines on how to contribute to SkillVector.

Code of Conduct

Please follow our Code of Conduct to help keep the community welcoming and inclusive.

Security

If you discover a security vulnerability, please see our Security Policy for details on responsible disclosure.

License

This project is licensed under the MIT License - see the LICENSE file for details.