liquid-ai

🎯 What is Liquid AI Docker?

Liquid AI Docker is a full-stack, production-ready AI agent platform that combines cutting-edge V4 agent architecture with biomimetic memory, intelligent routing, and a modern React UI. Built for developers who want to deploy intelligent AI agents at scale.

✨ Why Liquid AI Docker?

• 🚀 Production-Ready - Battle-tested architecture deployed in production
• 🧠 V4 Agent Architecture - Lazy loading, biomimetic memory, hybrid retrieval, complete tracing
• ⚡ Intelligent Routing - Semantic classification with 95-99% accuracy
• 🔍 Vector-Powered Memory - PostgreSQL + pgvector for semantic search and RAG
• 🎨 Modern UI - Cyberpunk-themed React interface with real-time agent feedback
• 🧩 Multi-Agent System - 35+ specialized agents for different domains
• 🛠️ 55+ Integrated Tools - Database, APIs, image generation, OCR, and more
• 🐳 Docker Ready - One-command deployment with Docker Compose

🎬 Demo

Live Demo: https://liquid-ai-frontend-new.fly.dev

Key Features Showcase

• Intelligent Chat Interface - Natural language interaction with specialized AI agents
• Real-time Agent Status - Visual feedback during agent processing
• Streaming Responses - Fast, responsive chat experience
• Multi-Agent Coordination - Agents work together on complex tasks
• Vector Memory System - Long-term context retention and retrieval

✨ Features

🤖 AI & Intelligence

🆕 What’s New

Highlights added between December 2025 and January 2026 to help new contributors understand the current platform:

• V4 Agent Architecture (Stable): lazy loading, hybrid retrieval, biomimetic memory types, complete tracing, and workflow reuse
• Google ADK Automations: parallel and optimized automation workflows alongside LangChain chat
• Unified Chat Improvements: streaming responses, slash commands, and higher routing accuracy
• Cyberpunk UI + UX Pass: refined visuals, real-time agent feedback, and responsiveness upgrades
• Expanded Tooling: 55+ tools (documents, OCR, web research, image generation, memory, automations)
• Production Reliability: Fly.io deploy hardening, health checks, and improved observability

💻 Technical Stack

Frontend

• ⚛️ React 18 + TypeScript
• ⚡ Vite for blazing-fast builds
• 🎨 TailwindCSS + shadcn/ui components
• 🔄 React Query for server state
• 🎭 Framer Motion for animations

Backend

• 🟢 Node.js 20 + Express + TypeScript
• 🗄️ PostgreSQL 15 + pgvector extension
• 🤖 LangChain 1.2 for agent orchestration
• 🧠 Google Gemini 3.0 Pro / 2.5 Flash
• 🔐 JWT authentication

Infrastructure

• 🐳 Docker + Docker Compose
• ☁️ Fly.io for production deployment
• 📊 Health checks and monitoring
• 🔄 Automated backups

🛠️ Available Agents

See AGENTS.md for complete list

🚀 Quick Start

Prerequisites

• 🐳 Docker & Docker Compose
• 📦 Node.js 20+ (for local tooling)
• 🔑 Google AI API Key (Get one here)

Installation

1. Clone the repository

git clone https://github.com/criptogus/liquid-ai-docker.git
cd liquid-ai-docker

2. Configure environment

cp .env.example .env
# Edit .env and add your GOOGLE_AI_API_KEY

3. Start the application

# Using Make (Linux/Mac)
make

# Using PowerShell (Windows)
./start.ps1

# Or Docker Compose directly
docker-compose up

4. Access the application

• 🌐 Frontend: http://localhost:3000
• 🔌 Backend API: http://localhost:5000
• 📊 Health Check: http://localhost:5000/health

First Steps

1. Create an account at http://localhost:3000
2. Start chatting - Try: "Create a task to learn TypeScript"
3. Explore agents - Use slash commands like /tasks, /goals, /research
4. Read the docs - Start with AGENTS.md and docs/README.md

📚 Documentation

📖 Core Documentation

• AGENTS.md - Complete development guide, tooling, testing, and standards
• ARCHITECTURE.md - System architecture (V4 + ADK + routing)
• TOOLS.md - Complete tools catalog (55+ tools)
• CHANGELOG.md - Release history and changes
• START_HERE.md - Orientation and onboarding entry point

🧠 AI/LLM Documentation

• GEMINI_3_PRO_GUIDE.md - Complete guide to using Gemini models
• GEMINI_FILE_SEARCH.md - File search with Gemini
• docs/GEMINI_IMAGE_GENERATION_GUIDE.md - Image generation guide

🚢 Deployment & Operations

• DEPLOY.md - Deployment guide
• DEPLOY-REFERENCE.md - Fly.io configuration reference
• DATABASE-MIGRATIONS.md - Database migration guide

📋 Additional Resources

• CONTRIBUTING.md - How to contribute
• CODE_OF_CONDUCT.md - Community guidelines
• SECURITY.md - Security policy

🏗️ Project Structure

liquid-ai-docker/
├── backend/              # Node.js + Express + TypeScript
│   ├── src/
│   │   ├── routes/       # API endpoints
│   │   ├── services/
│   │   │   └── langchain/ # AI agents & tools (core)
│   │   ├── middleware/   # Auth, validation, CORS
│   │   └── db/           # PostgreSQL client
│   └── package.json
├── src/                  # React + Vite frontend
│   ├── components/       # UI components (shadcn/ui)
│   ├── pages/            # Route pages
│   ├── services/         # API client, state management
│   └── lib/              # Utilities, helpers
├── migrations/           # Database migrations (73 files)
├── cypress/              # E2E tests
├── docs/                 # Documentation
├── docker-compose.yml     # Local development
├── fly.*.toml            # Fly.io production configs
└── Makefile              # Dev shortcuts

🧪 Testing

Quick Test

# Run linting
npm run lint

# Run tests
npm test

Full Test Suite

# E2E Tests
./run-e2e-tests.sh

# Agent Tests
./test-agents-tools-online.sh

# Production Tests
./test-flyio-production.sh

See AGENTS.md for complete testing guide

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Reporting bugs
• 💡 Suggesting features
• 📝 Improving documentation
• 🔧 Submitting pull requests
• 🎨 Enhancing the UI

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Quick Contribution Guide

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📊 Performance

🌟 Use Cases

• Personal Productivity - Task management, goal tracking, note-taking
• Content Creation - Generate documents, presentations, images
• Research & Analysis - Web research, document analysis, data extraction
• Business Automation - Workflow automation, CRM, sales pipelines
• Financial Planning - Budget tracking, investment advice, crypto planning
• Customer Support - Intelligent chatbots, FAQ automation

🔒 Security

• 🔐 JWT authentication on all protected routes
• 🛡️ Input validation with Zod schemas
• 🔒 Parameterized database queries (SQL injection prevention)
• 🔑 Environment variables for sensitive data
• 🚫 Never commit secrets or API keys

See SECURITY.md for security policy and reporting

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• LangChain - AI orchestration framework
• Google Gemini - Advanced AI models
• shadcn/ui - Beautiful UI components
• PostgreSQL - Robust database
• pgvector - Vector similarity search

📞 Support & Community

• 🐛 GitHub Issues - Bug reports and features
• 📖 Documentation - Full docs