feat: abstract embedding and LLM providers

Added abstract base classes for embedding and LLM providers.
Therefore, contributors can now implement their own embedding and LLM
providers by extending the abstract base classes.

Also, I changed the dotenv loading to use the new config class. This
works more like a traditional package structure and leaves the opinionated
decisions to the application layer.

Author: pa-arth

.env.example

@@ -5,7 +5,7 @@
 # Embedding Service Configuration
 # =============================================================================
 
-# Provider selection: "local" (Ollama) or "openai"
+# Provider selection: "local" (Ollama), "openai", "cohere", or "huggingface"
 # Default: local
 EMBED_PROVIDER=local
 
@@ -24,14 +24,41 @@ OPENAI_API_KEY=your-openai-api-key-here
 
 # OpenAI embedding model
 # Default: text-embedding-3-small
-# Options: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
+# Options: text-embedding-3-small (1536 dims), text-embedding-3-large (3072 dims), text-embedding-ada-002 (1536 dims)
 OPENAI_EMBED_MODEL=text-embedding-3-small
 
+# Cohere Configuration (when EMBED_PROVIDER=cohere)
+# Required if using Cohere provider
+COHERE_API_KEY=your-cohere-api-key-here
+
+# Cohere embedding model
+# Default: embed-v4.0
+# Options: embed-v4.0 (1536 dims default, configurable 256-1536), embed-v3
+COHERE_EMBED_MODEL=embed-v4.0
+
+# HuggingFace Configuration (when EMBED_PROVIDER=huggingface)
+# Required if using HuggingFace provider
+HUGGINGFACE_API_KEY=your-huggingface-api-key-here
+
+# HuggingFace embedding model
+# Default: sentence-transformers/all-MiniLM-L6-v2
+# Options: any embedding model from HuggingFace Hub
+# Examples:
+#   - sentence-transformers/all-MiniLM-L6-v2 (384 dims)
+#   - sentence-transformers/all-mpnet-base-v2 (768 dims)
+#   - BAAI/bge-small-en-v1.5 (384 dims)
+HUGGINGFACE_EMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
+
+# HuggingFace Inference Endpoint URL (optional)
+# Default: auto-generated from HUGGINGFACE_EMBED_MODEL
+# Use this if you have a custom Inference Endpoint URL
+# HUGGINGFACE_EMBED_URL=https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2
+
 # =============================================================================
 # LLM Service Configuration (for keyword extraction)
 # =============================================================================
 
-# Provider selection: "local" (Ollama) or "openai"
+# Provider selection: "local" (Ollama), "openai", "anthropic", or "gemini"
 # Default: local
 LLM_PROVIDER=local
 
@@ -46,9 +73,30 @@ LLM_MODEL=qwen3:8b
 
 # OpenAI LLM model (when LLM_PROVIDER=openai)
 # Default: gpt-4o-mini
-# Options: gpt-4o-mini, gpt-3.5-turbo, gpt-4, etc.
+# Options: gpt-4o-mini, gpt-4o, gpt-3.5-turbo, gpt-4-turbo
 OPENAI_LLM_MODEL=gpt-4o-mini
 
+# Anthropic Configuration (when LLM_PROVIDER=anthropic)
+# Required if using Anthropic provider
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# Anthropic Claude model
+# Default: claude-3-5-haiku-latest
+# Options:
+#   - claude-3-5-haiku-latest (fastest)
+#   - claude-sonnet-4-5 (best for agents and coding)
+#   - claude-opus-4-5 (most capable)
+ANTHROPIC_LLM_MODEL=claude-3-5-haiku-latest
+
+# Google Gemini Configuration (when LLM_PROVIDER=gemini)
+# Required if using Gemini provider
+GEMINI_API_KEY=your-gemini-api-key-here
+
+# Google Gemini model
+# Default: gemini-2.5-flash
+# Options: gemini-2.5-flash (fast), gemini-2.5-pro (more capable), gemini-3-pro (latest)
+GEMINI_LLM_MODEL=gemini-2.5-flash
+
 # =============================================================================
 # Quick Setup Guide
 # =============================================================================
@@ -65,4 +113,41 @@ OPENAI_LLM_MODEL=gpt-4o-mini
 # 3. Set OPENAI_API_KEY=your-key-here
 # 4. Optionally customize model names above
 #
+# For Cohere Setup:
+# 1. Set EMBED_PROVIDER=cohere
+# 2. Set COHERE_API_KEY=your-key-here
+# 3. Get API key from: https://dashboard.cohere.com/api-keys
+#
+# For HuggingFace Setup:
+# 1. Set EMBED_PROVIDER=huggingface
+# 2. Set HUGGINGFACE_API_KEY=your-key-here
+# 3. Get API key from: https://huggingface.co/settings/tokens
+# 4. Optionally set HUGGINGFACE_EMBED_MODEL to your preferred model
+#
+# For Anthropic Setup:
+# 1. Set LLM_PROVIDER=anthropic
+# 2. Set ANTHROPIC_API_KEY=your-key-here
+# 3. Get API key from: https://console.anthropic.com/
+#
+# For Google Gemini Setup:
+# 1. Set LLM_PROVIDER=gemini
+# 2. Set GEMINI_API_KEY=your-key-here
+# 3. Get API key from: https://aistudio.google.com/app/apikey
+#
+# =============================================================================
+# Important: LanceDB Dimension Requirements
+# =============================================================================
+#
+# LanceDB doesn't require specific dimensions - it only requires that query
+# embeddings match stored embeddings in dimension. Different providers return
+# different dimensions:
+#
+# - OpenAI: 1536 (text-embedding-3-small)
+# - Cohere: 1536 (embed-v4.0 default)
+# - HuggingFace: Varies (384-768 typically)
+# - Local: 4096 (qwen3-embedding default)
+#
+# If you switch providers, you'll need to re-embed all products with the new
+# provider's dimensions. See docs/PROVIDERS.md for details.
+#
 # =============================================================================

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 VKRA
+Copyright (c) 2026 VKRA
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,13 +1,13 @@
 # VKRA Protocol
 
-> Open Source LLMA Framework for Contextual Product Matching in LLM Applications
+> VKRA - Open Source Marketing Framework for Contextual Product Matching in LLM Applications
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Vision
 
-**Revolutionizing accessible advertisements in LLMs.** VKRA Protocol provides a modular, open-source framework for contextual product matching that enables developers to build monetization into their LLM applications while maintaining user trust and conversation quality.
+**Revolutionizing accessible advertisements in LLMs.** VKRA is an open-source marketing framework that provides a modular approach to contextual product matching, enabling developers to build monetization into their LLM applications while maintaining user trust and conversation quality.
 
 ## What is VKRA Protocol?
 
@@ -72,7 +72,7 @@ pip install vkra-protocol
 Or install from source:
 
 ```bash
-git clone https://github.com/vkra/vkra-protocol.git
+git clone https://github.com/vkra-project/vkra-python
 cd vkra-protocol
 pip install -e .
 ```
@@ -134,6 +134,8 @@ class MyUserProfileStore(UserProfileStore):
 ollama pull qwen3-embedding
 ```
 
+**Option A: Simple Service Usage (Environment Variables)**
+
 ```python
 from vkra_protocol import LLMAOrchestrator, EmbeddingService, LLMService
 
@@ -148,6 +150,59 @@ llm_service = LLMService()  # Uses local Ollama by default
 # OPENAI_API_KEY=your-key
 ```
 
+**Option B: Advanced Provider Usage (Dependency Injection)**
+
+For more control and better testability, use providers directly:
+
+```python
+from vkra_protocol import LLMAOrchestrator
+from vkra_protocol.providers import (
+    EmbeddingService,
+    LLMService,
+    EmbeddingProviderFactory,
+    LLMProviderFactory,
+)
+from vkra_protocol.providers.embedding import OpenAIEmbeddingProvider
+from vkra_protocol.providers.llm import OpenAILLMProvider
+
+# Method 1: Use factory with config dict
+embedding_provider = EmbeddingProviderFactory.create("openai", {
+    "api_key": "sk-...",
+    "model": "text-embedding-3-small"
+})
+llm_provider = LLMProviderFactory.create("openai", {
+    "api_key": "sk-...",
+    "model": "gpt-4o-mini"
+})
+
+# Method 2: Create providers directly
+embedding_provider = OpenAIEmbeddingProvider(
+    api_key="sk-...",
+    model="text-embedding-3-small"
+)
+llm_provider = OpenAILLMProvider(
+    api_key="sk-...",
+    model="gpt-4o-mini"
+)
+
+# Wrap in services (or use providers directly if orchestrator supports it)
+embedding_service = EmbeddingService(provider=embedding_provider)
+llm_service = LLMService(provider=llm_provider)
+
+# Method 3: Factory from environment (same as Option A)
+embedding_provider = EmbeddingProviderFactory.create_from_env()
+llm_provider = LLMProviderFactory.create_from_env()
+embedding_service = EmbeddingService(provider=embedding_provider)
+llm_service = LLMService(provider=llm_provider)
+```
+
+**Benefits of Provider Pattern:**
+- ✅ Dependency injection for better testability
+- ✅ No hardcoded environment variables
+- ✅ Easy to mock in tests
+- ✅ Programmatic configuration
+- ✅ Consistent error handling (`ProviderError`, `ProviderConfigurationError`, `ProviderAPIError`)
+
 ### 3. Initialize Orchestrator
 
 ```python
@@ -211,6 +266,28 @@ for result in response.results:
 - `OPENAI_EMBED_MODEL=text-embedding-3-small` (default)
 - `OPENAI_LLM_MODEL=gpt-4o-mini` (default)
 
+**Optional (Other Providers):**
+- `EMBED_PROVIDER=cohere` → `COHERE_API_KEY`, `COHERE_EMBED_MODEL`
+- `EMBED_PROVIDER=huggingface` → `HUGGINGFACE_API_KEY`, `HUGGINGFACE_EMBED_MODEL`
+- `LLM_PROVIDER=anthropic` → `ANTHROPIC_API_KEY`, `ANTHROPIC_LLM_MODEL`
+- `LLM_PROVIDER=gemini` → `GEMINI_API_KEY`, `GEMINI_LLM_MODEL`
+
+## Supported Providers
+
+### Embedding Providers
+- **OpenAI**: `text-embedding-3-small` (1536 dims, auto-detected)
+- **Cohere**: `embed-v4.0` (1024-1536 dims, auto-detected)
+- **HuggingFace**: Various models (dims vary, auto-detected)
+- **Local (Ollama/vLLM)**: Any local model (dims vary, auto-detected)
+
+### LLM Providers
+- **OpenAI**: `gpt-4o-mini`, `gpt-4o`, etc.
+- **Anthropic**: `claude-3-5-haiku-latest`, `claude-sonnet-4-5`, etc.
+- **Google Gemini**: `gemini-2.5-flash`, `gemini-2.5-pro`, etc.
+- **Local (Ollama/vLLM)**: Any local model
+
+**Note on Dimensions**: Embedding dimensions are detected automatically from the first API call. No need to hardcode dimension values!
+
 ## Module Configuration
 
 Customize module behavior per request: