Qarīn.ai

Overview

Qarīn.ai lets you create unlimited AI chatbot agents for your websites — no coding required. It works with any LLM provider that supports the OpenAI-Compatible API, including self-hosted providers like llama.cpp or Ollama.

With Qarīn.ai, you can:

• Define an agent's name, identity, and instructions.
• Instantly generate a chat bubble widget to embed on your site.
• Enhance agents by connecting to MCP Servers or importing your own API specs.
• Build vector stores from documents for retrieval-augmented generation (RAG).
• Expose vector stores or MCP Servers to external AI agents.

Project Status: On Hold

Active development on Qarīn.ai is currently paused. The project reached a working end-to-end state — agents, vector stores, MCP generation, and the embeddable chat widget all function — but it stops short of the polish and hardening a production release needs.

Where it stands today:

• ✅ Agent creation, identity, and instruction management
• ✅ Embeddable chat bubble widget
• ✅ Vector stores with RAG retrieval on pgvector
• ✅ MCP server generation from OpenAPI/Swagger specs
• ✅ Docker / Docker Compose deployment
• ⏸️ User management, ACL, and scoped access tokens
• ⏸️ Conversation tracking and inspection UI
• ⏸️ Agent widget theming and branding options

Why it's paused: my attention has shifted to other projects, and doing the remaining security and multi-user work properly needs a bigger block of focused time than I can give it right now.

The repository stays public and open source — feel free to fork it, run it, or open issues and PRs. I plan to pick it back up when time allows, and the roadmap below is where it would resume.

Key Features

• No Coding Needed!
• Supports RAG & MCP out of the box.
• Works with any OpenAI-Compatible LLM provider (including self-hosted).
• One-click MCP Server generation from existing REST API specs (Swagger/OpenAPI).
• Native vector storage with optional MCP Server exposure for each store.
• Easy-to-use chat bubble widget for quick website integration.
• Simple Docker or Kubernetes deployment.

Technical Implementation

Architecture Overview

Qarīn.ai is built as a full-stack web application with a modern frontend and robust backend, designed for easy deployment and scalability. It leverages containerization for simplified deployment and supports integration with various AI providers through OpenAI-compatible APIs.

Frontend

• Angular for the main web application framework
• PrimeNG for rich UI components and data visualization
• TailwindCSS for utility-first styling and responsive design
• ngx-markdown for markdown rendering and documentation display

Backend

• NestJS for scalable Node.js backend with modular architecture
• TypeORM for database ORM with PostgreSQL integration
• pgvector for vector storage and similarity search capabilities
• MCP SDK for Model Context Protocol integration
• OpenAI SDK for LLM provider connectivity
• Zod for runtime type validation and schema definition

AI & Data Processing

• LangChain text splitters for document processing and chunking
• HuggingFace transformers integration for advanced NLP tasks
• Vector stores with RAG (Retrieval-Augmented Generation) support
• MCP Server generation from OpenAPI/Swagger specifications

Infrastructure/DevOps

• Docker & Docker Compose for containerized deployment
• PostgreSQL as the primary database with vector extensions
• Webpack & Gulp for build tooling and asset processing
• Kubernetes-ready deployment configurations

Challenges & Solutions

1. Multi-LLM Provider Integration: Supporting various OpenAI-compatible providers with different capabilities

   • Solution: Abstracted provider interface with standardized API calls and fallback mechanisms

2. Vector Database Performance: Efficient storage and retrieval of high-dimensional vectors for RAG

   • Solution: PostgreSQL with pgvector extension for native vector operations and indexing

3. MCP Server Generation: Automatic conversion of REST APIs to MCP servers

   • Solution: OpenAPI/Swagger parsing with dynamic MCP server creation and tool binding

4. Real-time Chat Widget: Seamless integration of chat bubbles across different websites

   • Solution: iframe-based widgets with cross-origin communication and secure API endpoints

Performance Optimizations

• Vector Indexing: Optimized pgvector indexes for fast similarity searches
• Lazy Loading: Component and module lazy loading in Angular for improved initial load times
• Caching: Database query caching and API response caching for frequently accessed data
• Container Optimization: Multi-stage Docker builds for minimal production images

Security Features

• Access Control Lists (ACL) planned for multi-user support
• Personal Access Tokens with scoped permissions (in development)
• Secure API Endpoints for chat widget communication
• Input Validation using Zod schemas for all API inputs
• Cross-origin Security for embedded widgets

What I Learned

• Advanced full-stack development with Angular and NestJS
• Vector database implementation and RAG systems
• MCP (Model Context Protocol) integration and server generation
• Multi-provider LLM abstraction and API standardization
• Container orchestration and deployment strategies
• Real-time widget development and cross-origin communication
• OpenAPI/Swagger specification parsing and conversion

Roadmap (When Development Resumes)

• Complete existing CRUD operations and missing use cases for all resources
• Enhanced security with user management, ACL, and scoped access tokens
• Conversation tracking UI for inspecting agent conversations
• Agent UI customization (styling, colors, branding)
• Additional quality-of-life improvements and feature stabilization
• Expanded LLM provider support and advanced AI capabilities

---

🙏 Acknowledgements

Qarīn.ai would not have been possible without the incredible work of the open-source community. This project stands on the shoulders of countless developers and contributors who make their tools, libraries, and frameworks available for everyone to learn from and build upon.

A special thanks to the maintainers of the amazing technologies powering Qarīn.ai, including Angular, PrimeNG, TailwindCSS, NestJS, TypeORM, PostgreSQL, and many more.