Foam-Agent AGENTS.md

AGENTS.md

This file helps AI agents (Codex, Cursor, Claude Code, Copilot, etc.) understand and work with this codebase.

What is Foam-Agent?

Foam-Agent is a multi-agent framework that automates CFD (Computational Fluid Dynamics) simulations in Foundation OpenFOAM v10 (openfoam.org) from natural language prompts. It uses LangChain/LangGraph for orchestration, FAISS for RAG-based tutorial retrieval, and supports multiple LLM providers (OpenAI, Anthropic, Bedrock, Ollama).

Important: All generated case files, dictionary names, and solver binaries follow Foundation OpenFOAM v10 conventions. ESI OpenFOAM (openfoam.com, e.g., v2312, v2406, v2512) is not compatible.

Build and Run

# Environment setup
conda env create -n FoamAgent -f environment.yml
conda activate FoamAgent

# Run a simulation
python foambench_main.py --output ./output --prompt_path ./user_requirement.txt

# Run with custom mesh
python foambench_main.py --output ./output --prompt_path ./user_requirement.txt --custom_mesh_path ./mesh.msh

# Run tests
pytest tests/ -v

# Start MCP server
python -m src.mcp.fastmcp_server --transport http --host 0.0.0.0 --port 7860

Requires Foundation OpenFOAM v10 (openfoam.org) at runtime ($WM_PROJECT_DIR must be set). ESI OpenFOAM (openfoam.com) is not compatible. Python 3.12.9 via Conda.

Architecture

Workflow Pipeline (LangGraph StateGraph)

Defined in src/main.py:

PLANNER -> [mesh routing] -> MESHING (if needed) -> INPUT_WRITER -> [HPC/local routing]
-> RUNNER -> [error check] -> REVIEWER -> INPUT_WRITER (retry loop, max 25 iterations)
-> VISUALIZATION (if requested) -> END

All routing decisions (mesh type, HPC vs local, visualization) are LLM calls in src/router_func.py.

Directory Structure

src/
  main.py              # LangGraph workflow definition and entry point
  config.py            # Config dataclass with env var overrides
  utils.py             # GraphState (TypedDict), LLMService (unified LLM interface)
  models.py            # Pydantic models for generated files and plans
  router_func.py       # LLM-based routing decisions
  logger.py            # Structured XML-tagged logging
  nodes/               # LangGraph node functions (thin wrappers calling services)
    planner_node.py
    input_writer_node.py
    meshing_node.py
    local_runner_node.py
    hpc_runner_node.py
    reviewer_node.py
    visualization_node.py
  services/            # Business logic (where the real work happens)
    plan.py            # Case planning and analysis
    input_writer.py    # OpenFOAM file generation via LLM + RAG
    mesh.py            # Mesh generation (blockMesh / Gmsh conversion)
    run_local.py       # Local OpenFOAM execution
    run_hpc.py         # HPC job submission
    review.py          # Error diagnosis and fix planning
    visualization.py   # PyVista-based post-processing
  mcp/                 # FastMCP server exposing workflow as tools
database/
  faiss/               # Pre-built FAISS vector indices (do NOT regenerate unless necessary)
  raw/                 # Raw OpenFOAM tutorial data
tests/                 # pytest tests (service layer + MCP integration)
docker/                # Dockerfile for containerized deployment