Scrapegraph-ai: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (Claude Code, Codex, Cursor, Copilot agents, …) working on ScrapeGraphAI. Human contributors should read CONTRIBUTING.md; everything here is in addition to it.

---

1. Golden rule: everything goes to pre/beta

main is never written to directly. All work is based on and merged into pre/beta.

pre/beta is the prerelease branch: pushes to it publish a beta prerelease via semantic-release (see .releaserc.yml). main only receives releases when a maintainer promotes pre/beta.

# 1. always start from an up-to-date pre/beta
git fetch origin
git checkout -b feat/my-change origin/pre/beta

# 2. commit your work
git add <only the files you touched>
git commit -m "feat(nodes): add X"

# 3. push and open the PR against pre/beta
git push -u origin feat/my-change
gh pr create --base pre/beta --title "feat(nodes): add X" --body "..."

Checklist before you commit:

• The branch is based on origin/pre/beta (git merge-base --is-ancestor origin/pre/beta HEAD).
• The PR base is pre/beta, not main.
• No commits directly on main or pre/beta, no force-push to either.
• One logical change per branch/PR.

If a task genuinely requires targeting main (e.g. a hotfix on a released version), stop and ask a maintainer first.

2. Environment setup

Python >=3.12, dependencies managed with uv:

uv sync                     # create the venv and install deps
uv run pre-commit install   # install the git hooks

Never hand-edit uv.lock; regenerate it with uv lock / uv sync and commit the result only when you actually changed dependencies in pyproject.toml.

3. Checks to run before pushing

make lint         # ruff + black --check + isort --check-only
make type-check   # mypy (strict)
make test         # pytest with coverage
make pre-commit   # run all hooks on all files

Run at least make lint and the tests covering what you touched. Report the real result: if something fails or you skipped a step, say so in the PR description instead of implying a clean run.