nlweb-core

Core framework for NLWeb - Natural Language Web interface with config-driven provider architecture.

Overview

nlweb-core provides the foundational framework for building natural language interfaces to web services. It implements:

• Config-driven provider architecture for LLMs, embeddings, and vector databases
• Dynamic module loading based on configuration
• Unified interfaces for retrieval, ranking, and LLM operations
• HTTP server with Server-Sent Events (SSE) streaming support
• NLWeb Protocol v0.5 implementation

Installation

pip install nlweb-core

Note: You also need to install provider packages. See examples below.

Provider Packages

nlweb-core uses a plugin architecture. Install provider packages separately:

Bundle Packages (recommended for getting started)

# All retrieval providers
pip install nlweb-retrieval

# All LLM and embedding providers
pip install nlweb-models

Individual Provider Packages (coming soon)

# Azure-specific providers
pip install nlweb-azure-vectordb nlweb-azure-models

Quick Start

1. Create a configuration file

Create config.yaml:

# LLM Configuration
llm:
  provider: openai
  import_path: nlweb_models.llm.openai_client
  class_name: OpenAIClient
  api_key_env: OPENAI_API_KEY
  models:
    high: gpt-4
    low: gpt-3.5-turbo

# Embedding Configuration
embedding:
  provider: openai
  import_path: nlweb_models.embedding.openai_embedding
  class_name: get_openai_embeddings
  api_key_env: OPENAI_API_KEY
  model: text-embedding-3-small

# Retrieval Configuration
retrieval:
  provider: elasticsearch
  import_path: nlweb_retrieval.elasticsearch_client
  class_name: ElasticsearchClient
  api_endpoint_env: ELASTICSEARCH_URL
  index_name: my_index

2. Set environment variables

export OPENAI_API_KEY=your_key_here
export ELASTICSEARCH_URL=http://localhost:9200

3. Use in your application

import nlweb_core

# Initialize with your config
nlweb_core.init(config_path="./config.yaml")

# Use the framework
from nlweb_core.simple_server import run_server
run_server()

Configuration

The config file supports three main sections:

LLM Configuration

• provider: Provider name (used for identification)
• import_path: Python module path to provider
• class_name: Class or function name to import
• api_key_env: Environment variable containing API key
• models: Model IDs for high/low tiers

Embedding Configuration

• provider: Provider name
• import_path: Python module path
• class_name: Class or function name
• model: Embedding model ID

Retrieval Configuration

• provider: Provider name
• import_path: Python module path
• class_name: Client class name
• api_endpoint_env: Environment variable for endpoint URL
• index_name: Index/collection name

Architecture

nlweb-core provides orchestration layers:

• retriever.py: Vector database operations
• llm.py: LLM provider dispatch
• embedding.py: Embedding generation
• ranking.py: LLM-based result ranking
• simple_server.py: HTTP server with SSE streaming

All provider-specific code lives in separate packages.

License

MIT License - Copyright (c) 2025 Microsoft Corporation