go-chatbot

August 25, 2025 · View on GitHub

📖 Documentation: Contributing · Security · Changelog · Funding

go-chatbot is a modern, framework-agnostic Go package for integrating AI-powered chat functionality into any web application. It features out-of-the-box support for popular Go web frameworks, a flexible model abstraction for using OpenAI, Anthropic, xAI, Google Gemini, Meta, and more, and is designed for easy customization and extension. Build your own UI or use the provided minimal frontend as a starting point. High test coverage, static analysis, and coding standards are included.

About

A modern, framework-agnostic Go package for adding customizable, AI-powered chat functionality to any web application. Includes adapters for popular Go web frameworks, supports multiple AI providers, and is easy to extend.

Project Inspiration

This project is inspired by and related to the php-chatbot project, bringing similar AI-powered chat functionality to the Go ecosystem with enhanced enterprise features and modern architecture patterns.

✨ Key Features

Core Functionality

Plug-and-play chat API and UI components (minimal frontend dependencies)
Go web framework support via adapters/middleware (Gin, Echo, Fiber, Chi, etc.)
AI model abstraction via interfaces (swap models easily)
Customizable prompts, tone, language, and scope
Emoji and multi-script support (Cyrillic, Greek, Armenian, Asian, etc.)
Security safeguards against abuse
High test coverage (Go standard testing + testify)
Static analysis (golangci-lint, staticcheck) & Go coding standards (gofmt, goimports)
Structured logging with slog
Context-aware operations with cancellation support
Graceful error handling and recovery

🚀 Advanced Features

Real-time Streaming: Server-Sent Events (SSE) for live response streaming
Vector Embeddings: OpenAI embeddings integration with similarity search capabilities
Database Persistence: Full conversation history with SQLite/PostgreSQL support
Knowledge Base: Context-aware responses using embedded knowledge
Session Management: Multi-user conversation tracking and persistence

📚 Documentation & Wiki

Comprehensive documentation and guides are available in our GitHub Wiki:

🚀 Getting Started

Installation Guide - Step-by-step installation for all environments
Quick Start Guide - Get up and running in minutes
Configuration - Complete configuration reference

🔧 Implementation Guides

Framework Integration - Gin, Echo, Fiber, Chi, and vanilla net/http setup
Frontend Integration - React, Vue, Angular components and examples
AI Models - Provider comparison and configuration

📖 Examples & Best Practices

Examples - Real-world implementations and use cases
Best Practices - Production deployment and security guidelines
Security & Filtering - Content filtering and abuse prevention

🛠️ Development & Support

API Reference - Complete API documentation
Troubleshooting - Common issues and solutions
Contributing - How to contribute to the project
FAQ - Frequently asked questions

💡 Tip: The wiki contains production-ready examples, troubleshooting guides, and comprehensive API documentation that goes beyond this README.

📋 Technical Documentation

For detailed technical summaries and architectural overviews, see the docs/ directory:

Project Summary - Complete project overview and capabilities
Advanced Features - Streaming, embeddings, and database implementation details
AI Providers Guide - Provider comparison and integration guide

Supported AI Providers & Models

Provider	Models	API Key Required	Type
OpenAI	gpt-4.1, gpt-4o, gpt-4o-mini, gpt-3.5-turbo, etc.	Yes	Remote
Anthropic	Claude 3 Sonnet, 3.7, 4, etc.	Yes	Remote
xAI	Grok-1, Grok-1.5, etc.	Yes	Remote
Google	Gemini 1.5 Pro, Gemini 1.5 Flash, etc.	Yes	Remote
Meta	Llama 3 (8B, 70B), etc.	Yes	Remote
Ollama	llama2, mistral, phi3, and any local Ollama model	No (local) / Opt	Local/Remote
Free model	Simple fallback, no API key required	No	Local

Framework Adapters

The package includes built-in adapters for popular Go web frameworks, providing consistent API patterns and easy integration:

Available Adapters

Framework	Package	Adapter Type	Features
Gin	`github.com/gin-gonic/gin`	`adapters.GinAdapter`	Route setup, middleware, context extraction
Echo	`github.com/labstack/echo/v4`	`adapters.EchoAdapter`	Handler functions, middleware, context extraction
Fiber	`github.com/gofiber/fiber/v2`	`adapters.FiberAdapter`	Fast HTTP handlers, middleware, context extraction
Chi	`github.com/go-chi/chi/v5`	`adapters.ChiAdapter`	Standard net/http compatible, middleware, context extraction

Common Adapter Features

All adapters provide:

Chat Handler: POST /chat/ - Process chat messages
Health Handler: GET /chat/health - Health check endpoint
Stream Handler: POST /chat/stream - Streaming responses (placeholder)
Middleware: Inject chatbot instance into request context
Route Setup: Easy route configuration with optional custom prefixes
Timeout Support: Configurable request timeouts
Error Handling: Consistent JSON error responses

Basic Usage Pattern

// 1. Create chatbot instance
chatbot, err := gochatbot.New(config)

// 2. Create framework-specific adapter
adapter := adapters.NewGinAdapter(chatbot)        // or NewEchoAdapter, NewFiberAdapter, NewChiAdapter

// 3. Setup routes
adapter.SetupRoutes(router)                       // Default: /chat/*, /chat/health, /chat/stream
adapter.SetupRoutesWithPrefix(router, "/api/v1") // Custom prefix: /api/v1/*, /api/v1/health, /api/v1/stream

// 4. Optional: Use middleware for context injection
router.Use(adapter.Middleware())

Installation

go get go.rumenx.com/chatbot

Gin Framework

package main

import (
    "github.com/gin-gonic/gin"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/adapters"
    "go.rumenx.com/chatbot/config"
)

func main() {
    // Create configuration and chatbot
    cfg := config.Default()
    chatbot, err := gochatbot.New(cfg)
    if err != nil {
        panic(err)
    }

    // Create Gin router and adapter
    r := gin.Default()
    adapter := adapters.NewGinAdapter(chatbot)

    // Setup chatbot routes
    adapter.SetupRoutes(r)
    // Or with custom prefix: adapter.SetupRoutesWithPrefix(r, "/api/v1/bot")

    r.Run(":8080")
}

Echo Framework

package main

import (
    "github.com/labstack/echo/v4"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/adapters"
    "go.rumenx.com/chatbot/config"
)

func main() {
    // Create configuration and chatbot
    cfg := config.Default()
    chatbot, err := gochatbot.New(cfg)
    if err != nil {
        panic(err)
    }

    // Create Echo server and adapter
    e := echo.New()
    adapter := adapters.NewEchoAdapter(chatbot)

    // Setup chatbot routes
    adapter.SetupRoutes(e)
    // Or with custom prefix: adapter.SetupRoutesWithPrefix(e, "/api/v1/bot")

    e.Logger.Fatal(e.Start(":8080"))
}

Fiber Framework

package main

import (
    "github.com/gofiber/fiber/v2"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/adapters"
    "go.rumenx.com/chatbot/config"
)

func main() {
    // Create configuration and chatbot
    cfg := config.Default()
    chatbot, err := gochatbot.New(cfg)
    if err != nil {
        panic(err)
    }

    // Create Fiber app and adapter
    app := fiber.New()
    adapter := adapters.NewFiberAdapter(chatbot)

    // Setup chatbot routes
    adapter.SetupRoutes(app)
    // Or with custom prefix: adapter.SetupRoutesWithPrefix(app, "/api/v1/bot")

    app.Listen(":8080")
}

Chi Framework

package main

import (
    "net/http"
    "github.com/go-chi/chi/v5"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/adapters"
    "go.rumenx.com/chatbot/config"
)

func main() {
    // Create configuration and chatbot
    cfg := config.Default()
    chatbot, err := gochatbot.New(cfg)
    if err != nil {
        panic(err)
    }

    // Create Chi router and adapter
    r := chi.NewRouter()
    adapter := adapters.NewChiAdapter(chatbot)

    // Setup chatbot routes
    adapter.SetupRoutes(r)
    // Or with custom prefix: adapter.SetupRoutesWithPrefix(r, "/api/v1/bot")

    http.ListenAndServe(":8080", r)
}

Vanilla net/http

import (
    "net/http"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/config"
)

func main() {
    cfg := config.Default()
    chatbot := gochatbot.New(cfg)

    http.HandleFunc("/api/chat", chatbot.HandleHTTP)
    http.ListenAndServe(":8080", nil)
}

Usage

Add the chat endpoint to your web application using one of the framework adapters.
Configure your preferred AI model and prompts in the config.
Optionally, customize the frontend (CSS/JS) in /web.

API Keys & Credentials

Never hardcode API keys or secrets in your codebase.

Use environment variables or your infrastructure's secret management.
The config will check for environment variables (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) first.
See .env.example for reference.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/config"
    "go.rumenx.com/chatbot/models"
)

func main() {
    // Create configuration
    cfg := config.Default()
    cfg.Model = "openai" // or "anthropic", "gemini", etc.
    cfg.OpenAI.APIKey = "your-api-key"

    // Create model and chatbot
    model, err := models.NewFromConfig(cfg)
    if err != nil {
        log.Fatal(err)
    }

    chatbot := gochatbot.New(cfg, gochatbot.WithModel(model))

    // Ask a question
    ctx := context.Background()
    reply, err := chatbot.Ask(ctx, "Hello!")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Reply:", reply)
}

�️ Advanced Features Implementation

The package includes three enterprise-level features that elevate it beyond basic chatbot functionality:

Real-time Streaming Responses

Server-Sent Events (SSE) streaming for live response delivery:

import "go.rumenx.com/chatbot/streaming"

// Create stream handler
streamHandler := streaming.NewStreamHandler()

// Start streaming
err := chatbot.AskStream(ctx, "Tell me a story", func(chunk string) error {
    return streamHandler.WriteChunk(chunk)
})

Features:

Real-time token streaming with SSE
Automatic chunk processing and error handling
Context cancellation support
Browser and curl compatible

Vector Embeddings & Knowledge Base

OpenAI embeddings integration with semantic search:

import "go.rumenx.com/chatbot/embeddings"

// Create embedding provider
provider := embeddings.NewOpenAIEmbeddingProvider(apiKey, "text-embedding-3-small")

// Create knowledge base
vectorStore := embeddings.NewInMemoryVectorStore()

// Add knowledge
err := vectorStore.Add(ctx, provider, "id1", "Go is a programming language...")

// Search for relevant context
results, err := vectorStore.Search(ctx, provider, "What is Go?", 5)

Features:

OpenAI text-embedding-3-small/large support
Vector similarity search with cosine distance
In-memory vector store with search capabilities
Context enhancement for intelligent responses

Database Persistence & Conversation History

Full SQL-based conversation management:

import "go.rumenx.com/chatbot/database"

// Create conversation store
store, err := database.NewSQLConversationStore("sqlite", "./chat.db")

// Create conversation
convID, err := store.CreateConversation(ctx, "user123", "Chat Title")

// Save messages
err = store.SaveMessage(ctx, convID, "user", "Hello!")
err = store.SaveMessage(ctx, convID, "assistant", "Hi there!")

// Get conversation history
history, err := store.GetConversation(ctx, convID)

Features:

SQLite and PostgreSQL support
Complete conversation and message CRUD operations
User session management
Conversation history and search functionality

Complete Integration Example

See examples/advanced_demo.go for a comprehensive implementation that combines all three features:

Streaming responses with real-time UI updates
Knowledge base integration for context-aware answers
Persistent conversation history across sessions
Full REST API with web interface

# Run the advanced demo
go run examples/advanced_demo.go
# Visit http://localhost:8080 for web interface

Example .env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...
XAI_API_KEY=...

API Endpoint Contract

Endpoint: /api/chat
Method: POST
Request:
```
{ "message": "Hello" }
```
Response:
```
{ "reply": "Hi! How can I help you?" }
```

Testing

go test ./...

Running Tests with Coverage

go test -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Static Analysis

golangci-lint run

Security

Input validation and abuse prevention built-in.
Rate limiting and content filtering available via config.
Context-aware operations with timeout support.

Rate Limiting & Abuse Prevention

You can implement rate limiting and abuse prevention using middleware:

// Example with Gin
import "github.com/gin-contrib/ratelimit"

r.Use(ratelimit.RateLimiter(store, &ratelimit.Options{
    ErrorHandler: ratelimit.DefaultErrorHandler,
    KeyFunc:      ratelimit.KeyByIP,
}))

JavaScript Framework Components

You can use the provided chat popup as a plain HTML/JS snippet, or integrate a modern component for Vue, React, or Angular:

Vue: web/components/GoChatbotVue.vue
React: web/components/GoChatbotReact.jsx
Angular: web/components/GoChatbotAngular.html (with TypeScript logic)

JS Component Usage

Copy the component into your app's source tree.
Import and register it in your app (see your framework's docs).
Customize the backend endpoint (/api/chat) as needed.
Build your assets (e.g. with Vite, Webpack, or your framework's CLI).

Example (Vue)

// main.js
import GoChatbotVue from './components/GoChatbotVue.vue';
app.component('GoChatbotVue', GoChatbotVue);

Example (React)

import GoChatbotReact from './components/GoChatbotReact.jsx';
<GoChatbotReact />

Example (Angular)

Copy the HTML, TypeScript, and CSS into your Angular component files.
Register and use <go-chatbot-angular></go-chatbot-angular> in your template.

JS Component Customization

You can style or extend the components as needed.
You may add your own framework component in a similar way.
The backend endpoint is framework-agnostic; you can point it to any Go route/handler.

TypeScript Example (React)

A modern TypeScript React chatbot component is provided as an example in web/components/GoChatbotTs.tsx.

How to use:

Copy GoChatbotTs.tsx into your React app's components folder.

Import and use it in your app:

import GoChatbotTs from './components/GoChatbotTs';
// ...
<GoChatbotTs />

Make sure your backend endpoint /api/chat is set up as described above.
Style as needed (the component uses inline styles for demo purposes, but you can use your own CSS/SCSS).

This component is a minimal, framework-agnostic starting point. You are encouraged to extend or restyle it to fit your app.

Backend Integration Example

To handle chat requests, add a route/handler in your backend that receives POST requests at /api/chat and returns a JSON response.

Example for Gin:

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "go.rumenx.com/chatbot"
    "go.rumenx.com/chatbot/config"
    "go.rumenx.com/chatbot/models"
)

func ChatHandler(cfg *config.Config) gin.HandlerFunc {
    model, _ := models.NewFromConfig(cfg)
    chatbot := gochatbot.New(cfg, gochatbot.WithModel(model))

    return func(c *gin.Context) {
        var req struct {
            Message string `json:"message"`
        }

        if err := c.ShouldBindJSON(&req); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }

        reply, err := chatbot.Ask(c.Request.Context(), req.Message)
        if err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
            return
        }

        c.JSON(http.StatusOK, gin.H{"reply": reply})
    }
}

Frontend Styles (SCSS)

The chat popup styles are written in modern SCSS for maintainability. You can find the source in web/css/chatbot.scss.

To compile SCSS to CSS:

Install Sass (if you haven't already):
```
npm install --save-dev sass
```

Add this script to your package.json:

"scripts": {
  "scss": "sass web/css/chatbot.scss web/css/chatbot.css --no-source-map"
}

Compile SCSS:
```
npm run scss
```

Or use the Sass CLI directly:

sass web/css/chatbot.scss web/css/chatbot.css --no-source-map

To watch for changes automatically:

sass --watch web/css/chatbot.scss:web/css/chatbot.css --no-source-map

Only commit the compiled chatbot.css for production/deployment. For more options, see Sass documentation.

Customizing Frontend Styles & Views (Best Practice)

The provided CSS/SCSS and view files (web/css/, web/views/) are optional and basic. They are meant as a starting point for your own implementation. You are encouraged to build your own UI and styles on top of or instead of these defaults.

How to Safely Override Views and Styles

Copy the provided view files (e.g. web/views/popup.html) into your own application's views directory. Update your app to use your custom view.
Copy and modify the SCSS/CSS (web/css/chatbot.scss or chatbot.css) into your own asset pipeline. Import, extend, or replace as needed.
For Go applications: Embed the views using Go's embed package or copy them to your static files directory.

Principle

Treat the package's frontend as a reference implementation.
Override or extend in your own codebase for all customizations.
Never edit vendor files directly.

Configuration Best Practices

Always use environment variables for secrets and API keys.
Use Go's embed package for embedding static assets.
Keep your customizations outside the package directory for upgrade safety.

Example usage:

package main

import (
    "os"
    "go.rumenx.com/chatbot/config"
)

func main() {
    cfg := &config.Config{
        Model: "openai",
        OpenAI: config.OpenAIConfig{
            APIKey: os.Getenv("OPENAI_API_KEY"),
            Model:  "gpt-4o",
        },
        Prompt:   "You are a helpful, friendly chatbot.",
        Language: "en",
        Tone:     "neutral",
    }

    // Use configuration...
}

This approach ensures your configuration is safe and easy to manage in any deployment environment.

Best Practices

Use environment variables for secrets
Leverage Go's context package for cancellation and timeouts
Use the provided JS/TS components as a starting point, not as production code
Keep your customizations outside the package directory for upgrade safety
Follow Go coding standards (gofmt, goimports, golint)
Use structured logging with slog
Handle errors gracefully and provide meaningful error messages

What's Included

Feature	Location/Example	Optional/Required
Go Core Package	`./`	Required
Framework Adapters
Gin Adapter	`adapters/gin/`	Optional
Echo Adapter	`adapters/echo/`	Optional
Fiber Adapter	`adapters/fiber/`	Optional
Chi Adapter	`adapters/chi/`	Optional
Core Packages
Config Package	`config/`	Required
Models Package	`models/`	Required
Middleware Package	`middleware/`	Required
Advanced Features
Streaming Package	`streaming/`	Optional
Embeddings Package	`embeddings/`	Optional
Database Package	`database/`	Optional
Frontend Assets
HTML Views	`web/views/`	Optional
CSS/SCSS	`web/css/chatbot.scss`/`chatbot.css`	Optional
JS/TS Components	`web/components/`	Optional
Examples & Config
Advanced Demo	`examples/advanced_demo.go`	Optional
Basic Examples	`examples/basic/`, `examples/providers/`	Optional
Example .env	`.env.example`	Optional
Tests	`*_test.go`	Optional

Chat Message Filtering Middleware

The package includes a configurable chat message filtering middleware to help ensure safe, appropriate, and guideline-aligned AI responses. This middleware:

Filters and optionally rephrases user-submitted messages before they reach the AI model.
Appends hidden system instructions (not visible in chat history) to the AI context, enforcing safety and communication guidelines.
All filtering rules (profanities, aggression patterns, link regex) and system instructions are fully configurable.

Example configuration:

cfg := &config.Config{
    MessageFiltering: config.MessageFilteringConfig{
        Instructions: []string{
            "Avoid sharing external links.",
            "Refrain from quoting controversial sources.",
            "Use appropriate language.",
            "Reject harmful or dangerous requests.",
            "De-escalate potential conflicts and calm aggressive or rude users.",
        },
        Profanities:        []string{"badword1", "badword2"},
        AggressionPatterns: []string{"hate", "kill", "stupid", "idiot"},
        LinkPattern:        `https?://[\w\.-]+`,
    },
}

Example usage:

import "go.rumenx.com/chatbot/middleware"

filter := middleware.NewChatMessageFilter(cfg.MessageFiltering)

// Before sending to the AI model:
filtered, err := filter.Handle(ctx, userMessage)
if err != nil {
    // Handle error
}

reply, err := chatbot.Ask(ctx, filtered.Message, filtered.Context)

Purpose:

Promotes safe, respectful, and effective communication.
Prevents misuse, abuse, and unsafe outputs.
All rules are transparent and configurable—no hidden censorship or manipulation.