metabuilder/cadquerywrapper/AGENTS.md

AGENTS.md

🧠 Project Overview

This project is a Python-based application. Agents working in this directory must adhere to Python 3.11+ best practices, with clear module separation, test coverage, security hygiene, and readable documentation.

---

📁 Project Structure

Agents must follow the directory structure below:

project-root/
│
├── src/                # Application source code
│   └── <package_name>/ # Python modules/packages
│
├── tests/              # Unit + integration tests
│   └── __init__.py
│
├── scripts/            # Utility and CLI scripts
│
├── docs/               # Documentation (Markdown or reStructuredText)
│
├── .github/            # GitHub Actions workflows
│
├── pyproject.toml      # Project metadata & tool configs (preferred)
├── requirements.txt    # Legacy dependency spec (optional)
├── .env.example        # Environment variable template
└── AGENTS.md           # Agent configuration (this file)

Do not create files outside this structure unless explicitly instructed.

---

🧪 Testing & Validation

Before submitting changes, agents must ensure all tests and linters pass:

# Set up environment (once)
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# Run unit tests
pytest --cov=src --cov-report=term --cov-report=xml

# Run linters
ruff check src/ tests/
mypy src/
black --check src/

✅ Required Quality Gates

• Code coverage: ≥ 90%
• Type coverage: 100% via mypy
• No linter errors (ruff + mypy)
• No black formatting issues

Agents must not commit code that fails these checks.

---

🧹 Code Style

• Use PEP8 + PEP257 standards.
• Prefer pyproject.toml for tool configuration (Black, Ruff, Mypy, etc.).
• Function names: snake_case
• Class names: PascalCase
• Constant names: UPPER_SNAKE_CASE
• Use f-strings, not % or .format() for string interpolation.
• Keep function length under 50 lines where possible.

---

🔒 Security Guidelines

Agents must:

• Never commit .env files, secrets, or tokens.
• Use dotenv to load secrets during local execution.
• Avoid using eval(), exec(), or subprocess calls unless sandboxed and essential.
• Avoid external internet access during execution unless configured via API keys.

---

🧪 Testing Philosophy

• Use pytest with fixtures, mocking (unittest.mock or pytest-mock), and parameterized tests.
• Aim for 1:1 parity between modules and test modules.
• Include boundary cases and exception tests.

---

🧾 Commit & PR Conventions

Agents must format commits using Conventional Commits:

feat: add user authentication module
fix: correct path handling in file parser
docs: update README with usage example

Pull Requests should include:

• A concise title (≤ 72 chars)
• A summary of what changed and why
• Before/after behavior (if applicable)
• Testing evidence (CI, screenshots, coverage)

---

📦 Dependency Management

• Use pyproject.toml (via Poetry or PEP 621 standard)
• Prefer pip install .[dev] over requirements.txt
• Dev dependencies go under [tool.poetry.group.dev.dependencies] or similar
• Avoid pip freeze output for lockfiles — use poetry.lock or requirements.lock if necessary

---

🤖 Agent Behavior Summary

• Respect the file and folder structure
• Never break existing tests
• Follow Pythonic style and formatting
• Automate validation where possible
• Explain large changes via commit messages and PR descriptions
• Use comments where logic is non-obvious

---

Happy coding! 🐍

---

⚙️ Setup Script Requirement

Every project must include a setup.sh script at the root level that ensures:

• Python 3.11+ is installed
• Poetry is installed (via install.python-poetry.org)
• All dependencies are installed using poetry install

If this script does not exist, the agent must create it. It should be idempotent and safe to re-run.

Run it like this:

chmod +x setup.sh
./setup.sh

---

🖥 OS-Specific Setup Scripts (Expanded)

Agents must maintain the following OS-specific setup scripts:

• setup_linux.sh
• setup_mac.sh
• setup_windows.ps1

These scripts must:

• Ensure Python 3.11+ is present (install if missing)
• Install Poetry (if not already installed)
• Run poetry install to install dependencies
• Be idempotent and safe to re-run

A user must be able to simply clone the repo, run the appropriate script, and be ready to work.

Refer to README.md for user-friendly execution instructions.

---

🖥 OS-Specific Setup Scripts (Expanded)

Agents must maintain the following OS-specific setup scripts in the project root:

• setup_linux.sh – for Ubuntu, Debian, Fedora, Arch, etc.
• setup_mac.sh – for macOS (Intel/ARM); must auto-install Homebrew if missing
• setup_windows.ps1 – for Windows 10+ using PowerShell

Each script must:

• Ensure Python 3.11+ is installed
• Install Poetry if missing
• Run poetry install to fetch dependencies
• Be idempotent and safe to re-run
• Provide clear terminal output

These scripts should allow a contributor to clone the project, run one script, and be ready to develop.

---

🐧 setup_linux.sh

#!/bin/bash
set -e

echo "🔍 Checking Python 3.11+..."
if ! python3 --version | grep -q "3.11"; then
  echo "Installing Python 3.11..."
  if command -v apt &>/dev/null; then
    sudo apt update
    sudo apt install -y python3.11 python3.11-venv python3.11-dev
    sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
  elif command -v dnf &>/dev/null; then
    sudo dnf install -y python3.11
  elif command -v pacman &>/dev/null; then
    sudo pacman -S --noconfirm python
  else
    echo "❌ Unsupported Linux package manager."
    exit 1
  fi
fi

echo "✅ Python version: $(python3 --version)"

echo "🔍 Checking for Poetry..."
if ! command -v poetry &>/dev/null; then
  echo "📦 Installing Poetry..."
  curl -sSL https://install.python-poetry.org | python3 -
  export PATH="$HOME/.local/bin:$PATH"
else
  echo "✅ Poetry is installed: $(poetry --version)"
fi

echo "📦 Installing dependencies..."
poetry install

echo "✅ Linux setup complete. Use 'poetry shell' to activate environment."

---

🍎 setup_mac.sh

#!/bin/bash
set -e

echo "🔍 Checking Python 3.11+..."
if ! python3 --version | grep -q "3.11"; then
  echo "Installing Python 3.11 using Homebrew..."
  if ! command -v brew &>/dev/null; then
    echo "📦 Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    export PATH="/opt/homebrew/bin:$PATH"
  fi
  brew install python@3.11
  brew link python@3.11 --force
fi

echo "✅ Python version: $(python3 --version)"

echo "🔍 Checking for Poetry..."
if ! command -v poetry &>/dev/null; then
  echo "📦 Installing Poetry..."
  curl -sSL https://install.python-poetry.org | python3 -
  export PATH="$HOME/.local/bin:$PATH"
else
  echo "✅ Poetry is installed: $(poetry --version)"
fi

echo "📦 Installing dependencies..."
poetry install

echo "✅ macOS setup complete. Use 'poetry shell' to activate environment."

---

🪟 setup_windows.ps1

# PowerShell script
Write-Host "🔍 Checking Python 3.11+..."
$pythonVersion = python --version
if (-not ($pythonVersion -like "*3.11*")) {
    Write-Host "Installing Python 3.11..."
    Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.11.5/python-3.11.5-amd64.exe" -OutFile "python_installer.exe"
    Start-Process -Wait -FilePath "./python_installer.exe" -ArgumentList "/quiet InstallAllUsers=1 PrependPath=1"
    Remove-Item "python_installer.exe"
}

Write-Host "✅ Python version: $(python --version)"

Write-Host "🔍 Checking for Poetry..."
if (-not (Get-Command poetry -ErrorAction SilentlyContinue)) {
    Write-Host "📦 Installing Poetry..."
    (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
    $env:Path += ";$env:USERPROFILE\.poetry\bin"
}

Write-Host "📦 Installing dependencies..."
poetry install

Write-Host "✅ Windows setup complete. Run 'poetry shell' to activate environment."

---

📘 Instructing Users in README.md

Also ensure README.md includes this section:

## 🖥 Setup Instructions

Run the setup script for your operating system:

**Linux:**
```bash
chmod +x setup_linux.sh
./setup_linux.sh

macOS:

chmod +x setup_mac.sh
./setup_mac.sh

Windows (PowerShell):

.\setup_windows.ps1

After installation:

poetry shell