NLWebNet 0.1.0-alpha.5

NLWebNet

A .NET implementation of the NLWeb protocol for building natural language web interfaces. This project provides both a reusable library and a demo application showcasing the NLWeb standard.

⚠️ PROOF OF CONCEPT - NOT PRODUCTION READY

This is an experimental implementation created for testing and evaluation purposes only. While functional, this library is not intended for production use and should be considered a proof of concept to demonstrate NLWeb protocol capabilities in .NET environments.

Use cases:

• 🧪 Protocol evaluation and experimentation
• 📚 Learning and understanding NLWeb concepts
• 🔬 Research and development prototyping
• 🎯 Testing integration patterns with AI services

Not recommended for:

• ❌ Production applications
• ❌ Critical business systems
• ❌ Public-facing services
• ❌ Applications requiring enterprise support

📋 Overview

NLWeb is a protocol for creating conversational interfaces to web content and data. It enables natural language querying with three main modes:

• List: Returns ranked search results
• Summarize: Provides AI-generated summaries with supporting results
• Generate: Full RAG (Retrieval-Augmented Generation) responses

This implementation follows the official NLWeb specification and includes Model Context Protocol (MCP) support for enhanced AI integration.

🏗️ Repository Structure

NLWebNet/
├── src/NLWebNet/              # 📦 Core library (published NuGet package)
│   ├── Models/                # Request/response data models
│   ├── Services/              # Business logic interfaces and implementations
│   ├── Endpoints/             # Minimal API endpoints (/ask, /mcp)
│   ├── MCP/                   # Model Context Protocol integration
│   ├── Extensions/            # DI and middleware extensions
│   └── Middleware/            # Request processing middleware
├── samples/                   # 🎯 Sample applications and usage examples
│   ├── Demo/                  # 🎮 .NET 9 Blazor Web App demo application  
│   └── AspireHost/            # 🏗️ .NET Aspire orchestration host  
├── doc/                       # � Documentation and setup guides
│   ├── demo-setup-guide.md    # 🔧 Complete AI integration setup guide
│   ├── manual-testing-guide.md # 🧪 API testing instructions
│   └── todo.md                # 📋 Implementation status and roadmap
├── tests/                     # 🧪 Unit and integration tests
│   └── NLWebNet.Tests/        # 📋 MSTest test project (39 tests)
├── helm/                      # ⚙️ Helm charts for Kubernetes
├── k8s/                       # ⚙️ Kubernetes manifests
├── deploy/                    # 🚀 Azure deployment templates
└── scripts/                   # �️ Build and deployment scripts

🔄 NLWeb Protocol Flow

sequenceDiagram
    participant Client
    participant NLWebNet
    participant DataBackend
    participant LLM as AI Service
    
    Client->>NLWebNet: POST /ask
    Note over Client,NLWebNet: query, mode, site, streaming, etc.
    
    NLWebNet->>NLWebNet: Generate query_id (if not provided)
    NLWebNet->>NLWebNet: Process/decontextualize query
    
    alt mode = "list"
        NLWebNet->>DataBackend: Search query
        DataBackend-->>NLWebNet: Ranked results
    else mode = "summarize"
        NLWebNet->>DataBackend: Search query
        DataBackend-->>NLWebNet: Ranked results
        NLWebNet->>LLM: Generate summary
        LLM-->>NLWebNet: Summary text
    else mode = "generate"
        NLWebNet->>DataBackend: Search query
        DataBackend-->>NLWebNet: Context documents
        NLWebNet->>LLM: Generate RAG response
        LLM-->>NLWebNet: Generated response
    end
    
    NLWebNet-->>Client: JSON response with results
    Note over Client,NLWebNet: query_id, results[], summary?, etc.

🎯 API Endpoints

/ask - Primary NLWeb Endpoint

Natural language query interface supporting all NLWeb protocol features.

Required Parameters:

• query - Natural language query string

Optional Parameters:

• site - Target site/domain subset
• prev - Comma-separated previous queries for context
• decontextualized_query - Pre-processed query (skips decontextualization)
• streaming - Enable streaming responses (default: true)
• query_id - Custom query identifier (auto-generated if not provided)
• mode - Query mode: list (default), summarize, or generate

/mcp - Model Context Protocol Endpoint

MCP-compatible interface with additional methods:

• list_tools - Available tools
• list_prompts - Available prompts
• call_tool - Execute tools
• get_prompt - Retrieve prompt templates

🏛️ Architecture Overview

graph TB
    subgraph "NLWebNet Library"
        API[Minimal APIs<br>/ask, /mcp]
        MW[Middleware<br>Pipeline]
        EXT[Extensions<br>DI & Config]
        SVC[Business Logic<br>Services]
        MCP[MCP Integration]
        MODELS[Data Models]
    end
      subgraph "Demo Application"
        BLAZOR[.NET 9 Blazor Web App UI]
        DEMO[Modern Blazor Components]
    end
    
    subgraph "External Services"
        AI[AI/LLM Service<br>Azure OpenAI, etc.]
        DATA[Data Backend<br>Search Index, DB, etc.]
    end
    
    CLIENT[HTTP Clients<br>Web, Mobile, etc.] --> API
    BLAZOR --> API
    API --> MW
    MW --> SVC
    SVC --> MCP
    SVC --> AI
    SVC --> DATA
    
    DEMO --> BLAZOR
    
    classDef library fill:#e1f5fe
    classDef demo fill:#f3e5f5
    classDef external fill:#fff3e0
    
    class API,MW,SVC,MCP,MODELS library
    class BLAZOR,DEMO demo
    class AI,DATA external

🚀 Quick Start

📋 Note: This library is provided for testing and evaluation purposes only. This is alpha-quality software that may contain bugs or incomplete features. Please review the development status section before integrating into any project.

Using the Library in Your Project

1. Add the NLWebNet library to your ASP.NET Core project:

// Program.cs
using NLWebNet;

// Add NLWebNet services
builder.Services.AddNLWebNet(options =>
{
    // Configure options
    options.DefaultMode = NLWebNet.Models.QueryMode.List;
    options.EnableStreaming = true;
});

// Later in the pipeline configuration
app.UseNLWebNet();     // Add NLWebNet middleware (optional)
app.MapNLWebNet();     // Map NLWebNet minimal API endpoints

Prerequisites

• .NET 9.0 SDK
• Visual Studio 2022 or VS Code

Running the Demo

1. Clone the repository

   git clone https://github.com/jongalloway/NLWebNet.git
   cd NLWebNet
   

2. Build the solution

   dotnet build
   

3. Run the demo application

   cd samples/Demo
   dotnet run
   

4. Open your browser

   • Demo UI: http://localhost:5037
   • OpenAPI Spec: http://localhost:5037/openapi/v1.json

5. Test the demo features

   • Home Page: Overview and navigation to demo features
   • Interactive Demo (/nlweb): UI for testing NLWeb queries with enhanced data source visualization
     • Smart Data Source Management: Automatic routing between RSS feeds (.NET content), Schema.org static data (science fiction), and mock placeholders
     • Visual Data Source Indicators: Top-level Bootstrap cards showing which sources are active
     • User Guidance Prompts: Contextual examples of what content is available to search
     • Query input with natural language questions: Try ".NET 9 features" for RSS data or "space movies" for sci-fi content
     • Mode selection: List, Summarize, Generate modes with streaming support
     • Color-coded result badges: Each result shows its source (RSS/Schema.org/Mock) with visual indicators
     • HTML tag removal: Clean display of RSS feed content
     • API testing interface: Direct endpoint testing with request/response inspection
   • API Documentation: OpenAPI specification for /ask and /mcp endpoints

🔧 Real AI Integration: The demo uses mock responses by default. For actual AI-powered responses, see the Complete Setup Guide for Azure OpenAI and OpenAI API integration.

Using the Library

⚠️ Alpha software - for evaluation and testing only

Install the NuGet package:

dotnet add package NLWebNet

Or via Package Manager Console:

Install-Package NLWebNet

Configure in your ASP.NET Core application:

// Program.cs
using NLWebNet;

builder.Services.AddNLWebNet(options =>
{
    options.DefaultMode = QueryMode.List;
    options.EnableStreaming = true;
});

app.MapNLWebNet();

Testing NLWeb Features

The demo application at http://localhost:5037 provides testing of core NLWeb protocol features:

Interactive Demo Pages:

• Home Page (/): Project overview and navigation to demo features
• NLWeb Demo (/nlweb): Interactive query interface with tabbed sections:
  • Query Tab: Interactive form with all NLWeb parameters (query, mode, site, etc.)
  • Streaming Tab: Real-time streaming response demonstration
  • API Test Tab: Raw HTTP request/response testing
• API Test (/api-test): API testing interface with request configuration
• MCP Demo (/mcp-demo): Model Context Protocol demonstration with tools and prompts

Query Modes Supported:

• List Mode: Returns ranked search results with relevance scoring
• Summarize Mode: AI-generated summaries with supporting results
• Generate Mode: Full RAG responses with context-aware answers
• Streaming: Real-time response delivery with Server-Sent Events

API Testing:

• Direct HTTP calls to /ask endpoint with various parameters
• MCP protocol testing via /mcp endpoint with tool and prompt support
• OpenAPI specification available at /openapi/v1.json
• Manual testing guides in /doc/manual-testing-guide.md

Example API Usage:

# List mode query
curl -X GET "http://localhost:5037/ask?query=find+recent+updates&mode=list"

# POST request with full parameters
curl -X POST "http://localhost:5037/ask" \
  -H "Content-Type: application/json" \
  -d '{"query": "find recent updates", "mode": "list", "site": "docs", "streaming": false}'

# Streaming summarize query  
curl -X POST "http://localhost:5037/ask" \
  -H "Content-Type: application/json" \
  -d '{"query": "what are the main features?", "mode": "summarize", "streaming": true}'

# MCP tool listing
curl -X POST "http://localhost:5037/mcp" \
  -H "Content-Type: application/json" \  -d '{"method": "list_tools"}'

🔧 Real AI Integration

The demo application works with mock responses by default, but can be configured for real AI-powered responses using Azure OpenAI or OpenAI API.

Quick Setup

1. Choose Your AI Provider: Azure OpenAI (recommended) or OpenAI API

2. Install Provider Package:

   cd samples/Demo
   dotnet add package Microsoft.Extensions.AI.AzureAIInference  # For Azure OpenAI
   # OR
   dotnet add package Microsoft.Extensions.AI.OpenAI           # For OpenAI API
   

3. Configure API Keys: Update samples/Demo/appsettings.json or use user secrets

4. Add Service Registration: Update Program.cs with AI service registration

Complete Setup Guide

📖 Complete AI Integration Guide - Step-by-step instructions for:

• Azure OpenAI and OpenAI API configuration
• Enhanced data source features and testing scenarios
• Security best practices for API key management
• Service registration and dependency injection
• Troubleshooting common setup issues
• Configuration options
• Production deployment considerations

The guide includes examples, FAQ, troubleshooting, and detailed documentation of the enhanced data source visualization features.

⚙️ Configuration

NLWebNet uses standard ASP.NET Core configuration patterns for managing settings and external service credentials.

Non-Secret Configuration (appsettings.json)

Configure basic NLWebNet settings in your appsettings.json:

{
  "NLWebNet": {
    "DefaultMode": "List",
    "EnableStreaming": true,
    "DefaultTimeoutSeconds": 30,
    "MaxResultsPerQuery": 50
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "NLWebNet": "Debug"
    }
  }
}

Secret Configuration (User Secrets)

For sensitive data like API keys, use ASP.NET Core User Secrets in development:

1. Initialize user secrets for your project:

   dotnet user-secrets init
   

2. Set AI service credentials (example for Azure OpenAI):

   dotnet user-secrets set "AzureOpenAI:ApiKey" "your-api-key-here"
   dotnet user-secrets set "AzureOpenAI:Endpoint" "https://your-resource.openai.azure.com/"
   dotnet user-secrets set "AzureOpenAI:DeploymentName" "gpt-4"
   

3. Set data backend credentials (example for Azure Search):

   dotnet user-secrets set "AzureSearch:ApiKey" "your-search-api-key"
   dotnet user-secrets set "AzureSearch:ServiceName" "your-search-service"
   dotnet user-secrets set "AzureSearch:IndexName" "your-index-name"
   

Production Configuration

For production deployments, use:

• Azure Key Vault - For secrets in Azure environments
• Environment Variables - For containerized deployments
• Configuration Providers - Custom providers for other cloud platforms

Example environment variables for production:

NLWebNet__DefaultMode=List
NLWebNet__EnableStreaming=true
AzureOpenAI__ApiKey=your-production-api-key
AzureSearch__ApiKey=your-production-search-key

Configuration in Code

Access configuration in your application:

// Program.cs
using NLWebNet;

builder.Services.AddNLWebNet(options =>
{
    // Bind from configuration
    builder.Configuration.GetSection("NLWebNet").Bind(options);
});

// Configure AI services
builder.Services.Configure<AzureOpenAIOptions>(
    builder.Configuration.GetSection("AzureOpenAI"));

// Configure data backend
builder.Services.Configure<AzureSearchOptions>(
    builder.Configuration.GetSection("AzureSearch"));

🚀 Deployment

NLWebNet supports multiple deployment options for different environments:

🐳 Docker Deployment

# Quick start with Docker Compose
git clone https://github.com/jongalloway/NLWebNet.git
cd NLWebNet
cd deployment/docker && docker-compose up --build

☁️ Azure Cloud Deployment

# Deploy to Azure Container Apps
./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t container-apps

# Deploy to Azure App Service
./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t app-service

⚙️ Kubernetes Deployment

# Deploy to any Kubernetes cluster
kubectl apply -f deployment/kubernetes/manifests/

📦 Container Registry

Pre-built images available soon. For now, build locally:

./deployment/scripts/deploy/build-docker.sh -t latest

📖 Complete Deployment Guide - Comprehensive instructions for all deployment scenarios.

🛠️ Development Status

This is an alpha implementation of the NLWeb protocol, provided as an experimental package for testing and evaluation purposes.

⚠️ ALPHA SOFTWARE - EXPERIMENTAL RELEASE

✅ Current Implementation Status:

• Core Library: Basic NLWeb protocol implementation with Minimal API endpoints
• Data Models: Essential request/response models with validation and JSON serialization
• Business Logic: Service layer with Microsoft.Extensions.AI integration
• MCP Integration: Basic Model Context Protocol support with tools and prompts
• Demo Application: .NET 9 Blazor Web App with interactive components for testing
• AI Integration: Setup guides for Azure OpenAI and OpenAI API (experimental)
• Testing: Unit tests and manual testing guides (basic coverage)
• Configuration: CORS, AI services, and multi-environment support
• Documentation: API documentation and setup guides (evolving)
• CI/CD: Basic automated build, test, and validation pipeline
• NuGet Package: Alpha prerelease at nuget.org/packages/NLWebNet

🎯 Suitable For:

• Protocol evaluation and experimentation
• Learning NLWeb concepts and implementation patterns
• Research and development prototyping
• Testing integration patterns with AI services
• Exploring .NET AI abstractions and Model Context Protocol

⚠️ Alpha Release Limitations:

• Experimental software - may contain bugs or incomplete features
• API surface may change in future releases without notice
• Not recommended for production use - suitable for evaluation and experimentation only
• Limited support - community-driven development with no guarantees
• Performance and reliability not yet optimized for production workloads
• Feature completeness varies - some advanced NLWeb features may be basic implementations

🤝 Contributing

This project follows the NLWeb specification. Contributions are welcome!

1. Review the implementation plan
2. Check open issues
3. Submit pull requests with tests

📖 Related Resources

• NLWeb Official Repository - Specification and reference implementation
• Complete Demo Setup Guide - Step-by-step AI integration instructions
• Model Context Protocol - MCP documentation
• Microsoft.Extensions.AI - .NET AI abstractions
• Manual Testing Guide - API testing with curl examples

📄 License

This project is licensed under the MIT License.

🏷️ Version

- Alpha experimental release

Basic NLWeb protocol implementation with AI integration support for testing and evaluation purposes.

Key Features (Alpha Quality):

• ✅ Basic NLWeb protocol implementation (/ask, /mcp endpoints)
• ✅ AI integration support (Azure OpenAI, OpenAI API) - experimental
• ✅ .NET 9 Blazor demo application for testing
• ✅ Model Context Protocol (MCP) support - basic implementation
• ✅ Streaming responses with Server-Sent Events
• ✅ Documentation and setup guides (evolving)
• ✅ Alpha NuGet package with working extension methods