FoamAI - Natural Language CFD Assistant

AI-powered computational fluid dynamics (CFD) assistant that converts natural language descriptions into OpenFOAM simulations with ParaView visualization.

✨ Key Features

• 🗣️ Natural Language Interface - Describe simulations in plain English
• 🤖 AI-Powered Workflow - LangGraph orchestrated multi-agent system
• 🔧 Automated Mesh Generation - Intelligent mesh creation with validation
• 🎨 3D Visualization - Integrated ParaView for real-time results
• 🖥️ Desktop & Server Modes - GUI application and headless server deployment
• ☁️ Cloud Ready - AWS infrastructure with Terraform automation
• 📦 Containerized - Docker deployment for consistent environments
• 🚀 Production Ready - FastAPI backend with Celery task processing

🏗️ Project Structure

FoamAI/
├── src/                     # Core application code
│   ├── foamai-core/        # Core simulation logic
│   ├── foamai-server/      # FastAPI backend server
│   ├── foamai-client/      # Client library
│   └── foamai-desktop/     # Desktop application
├── infra/                  # AWS infrastructure (Terraform)
├── docker/                 # Container definitions
├── tests/                  # Test files
├── examples/               # Demo scripts and examples
├── dev/                    # Development utilities
├── docs/                   # Project documentation
└── .github/               # CI/CD workflows

🚀 Quick Start

📋 Prerequisites

• Python 3.12+
• OpenFOAM 10
• ParaView 6.0+
• Docker & Docker Compose
• UV package manager

💻 Development Setup

1. Clone and setup environment:

git clone https://github.com/bbaserdem/FoamAI.git
cd FoamAI
uv sync

2. Start local development:

# Start local services
docker-compose -f dev/docker-compose.local.yml up -d

# Run the desktop application
uv run python -m foamai_desktop.main

# Or run examples
uv run python examples/demo_user_approval.py

3. Run tests:

uv run pytest tests/

☁️ Production Deployment

1. Deploy infrastructure with Terraform:

cd infra
terraform init
terraform apply

2. Pre-built container images available:

• ghcr.io/bbaserdem/foamai/api:latest
• ghcr.io/bbaserdem/foamai/openfoam:latest
• ghcr.io/bbaserdem/foamai/pvserver:latest

3. Or use the quick deployment script:

./infra/deploy-fresh-instance.sh

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• 🤖 LangGraph Agents System - AI agent architecture and workflow orchestration
• 🔗 Backend API Reference - REST API endpoints and integration guide
• 🧠 Brainlift Guide - Advanced AI capabilities and features
• 🛠️ Contributing Guide - Development setup, workflows, and testing
• 🖥️ Desktop Application Setup - GUI installation and usage guide
• 🚀 DevOps Guide - Infrastructure deployment and monitoring

🏛️ Architecture

Component	Technology	Purpose
🔗 Backend	FastAPI + Celery	REST API and async task processing
🧠 AI Engine	LangGraph + OpenAI	Multi-agent workflow orchestration
⚙️ CFD Engine	OpenFOAM 10	Computational fluid dynamics solver
🎨 Visualization	ParaView 6.0	3D rendering and data visualization
🖥️ Desktop App	PySide6 + Qt	Cross-platform GUI application
☁️ Infrastructure	AWS EC2 + Terraform	Cloud deployment automation
🚀 CI/CD	GitHub Actions	Automated testing and deployment
📦 Containers	Docker + Docker Compose	Service orchestration

🤝 Contributing

Welcome to FoamAI! To get started with development:

1. Read the Contributing Guide - Complete development setup and workflows
2. Check Desktop Setup - GUI application development
3. Review DevOps Guide - Infrastructure and deployment
4. Explore API Documentation - Backend development
5. Run tests from the tests/ directory
6. Try examples from the examples/ directory
7. Use development tools from dev/ directory

Quick Development Setup

# Clone and setup
git clone https://github.com/bbaserdem/FoamAI.git
cd FoamAI
uv sync

# Run tests
uv run pytest

# Start local development
cd dev && ./local-test.sh

License

See LICENSE for details.