AGENTS.md

AGENTS.md

This file is the canonical instruction set for AI agents working in this repo. Follow it. The human is in charge; the agent assists. Prioritize small, reviewable changes and help users succeed with CI.

Golden rules (never break)

• Never commit directly to develop or main.
• Never skip pre-commit hooks (--no-verify) or force push.
• Never commit secrets, credentials, or .env files.
• Never self-approve agent-generated code. Independent review is required.
• Never make sweeping refactors or introduce new patterns without prior human discussion in the issue.

Accountability: The person who submits the PR is 100% responsible for its contents. Responsibility never transfers to the agent.

Commands (run early)

Run these after editing. Replace <file> with the path(s) you changed.

# Style and format (run before commit)
pre-commit run --files <file>
# Or all files:
pre-commit run --all-files

# Python lint (pre-commit uses --errors-only; for full output)
pylint <file>

# Python unit tests — targeted or full
pytest tests/unittests/<path>/ -v
# Or broader:
pytest tests/unittests/ -v

# App tests
cd app && yarn test

# E2E tests
cd e2e-pw && yarn e2e

Environment setup

If the environment is not set up:

1. Python 3.9–3.12 (3.10+ recommended). Node and Yarn needed for App work.
2. Run: bash install.sh -d
3. Run: pre-commit install
4. Verify: pre-commit run --all-files then e.g. pytest tests/unittests/utils/ -v

What to do every time

• Prefer the smallest change that fixes the issue. Use rg to locate files.
• After editing: run pre-commit run --files <changed_files> and the relevant test subset (see Commands / Testing).
• Follow existing patterns; do not introduce new ones without human agreement.

Recommended workflow (human + agent)

1. Give the agent access to this file and relevant FiftyOne Skills/MCP. Start in planning or read-only mode.
2. Agent explores and proposes a plan. Human reviews the plan before any edits. Adjust scope early if needed.
3. Edit only after the plan is approved. Keep changes small; human reviews as you go.
4. Before the human opens a PR: apply code style (use fiftyone-code-style for Python, fiftyone-voodo-design for App UI; see Code style), add or update tests, run tests locally.
5. Human opens the PR. In the description: state that an agent was used and how you tested.

Example flows

Change type	Edit → then run
Python	pre-commit run --files <file> → pytest tests/unittests/<relevant>/ -v
App	pre-commit run --files <file> → cd app && yarn test
Docs	Follow STYLE_GUIDE.md. No pre-commit on RST. Optionally build: bash docs/generate_docs.bash (see docs/README.md).
New feature	Same as above + add/update tests

---

Repo map

Path	Purpose
fiftyone/	Core Python SDK (data, datasets, model zoo, operators)
fiftyone/server/	Backend server (GraphQL to App)
app/	TypeScript/React App (modular packages)
tests/	Python tests: unittests/, integration, isolated/, no_wrapper
e2e-pw/	Playwright E2E tests
docs/	Sphinx/RST documentation
plugins/	Plugin ecosystem (sandbox; see below)

Boundaries

• Always: Minimal diffs, follow existing patterns, targeted tests.
• Ask first: New dependencies, CI changes, public API changes, large refactors. Discuss significant changes in the issue (e.g. needs design).
• Never: See Golden rules.

Code style (authoritative)

Follow the repo’s style standards. They are the source of truth.

• Python: STYLE_GUIDE.md — Google style, black, pylint, 79-char line, no type annotations. Use the fiftyone-code-style skill when writing or editing Python so the agent follows FiftyOne conventions.
• App: app/CODING_STANDARDS.md and STYLE_GUIDE.md — TypeScript, Prettier, ESLint, Biome, Jotai for new state. Use the fiftyone-voodo-design skill for UI/React components and VOODO design tokens.
• Docs: RST in docs/, 79-char line; do not edit existing anchor links.

Do not guess style. When in doubt, read the files above or use the matching skill.

Tech stack

• Python: pytest; CI uses wrapper (see Testing).
• App: Vitest (yarn test). Docs: Sphinx, RST.
• API/usage: https://docs.voxel51.com/llms.txt — do not guess APIs.

Branching and commits

• Branch from develop (default branch; not main).
• Branch prefixes: feature/, bugfix/, release/, hotfix/.
• Small, logical commits; explain “why” not “what”.

Testing

• Targeted Python: pytest tests/unittests/<module>/ -v or pytest tests/unittests/<module>/test_<name>.py -v (e.g. pytest tests/unittests/map/ -v).

• Full Python (wrapper): Same as CI. Run:

  python tests/utils/pytest_wrapper.py tests/ --verbose \
    --ignore tests/benchmarking/ --ignore tests/isolated/ --ignore tests/utils/ \
    --ignore tests/intensive/ --ignore tests/no_wrapper

• No-wrapper: pytest tests/no_wrapper --verbose

• App: cd app && yarn test (Vitest; see app/README).

• E2E: cd e2e-pw && yarn e2e (Playwright).

CI also runs isolated tests separately (tests/isolated/ via wrapper, one file at a time). Use the full wrapper + no_wrapper for local parity with CI.

New features require tests. Agent-generated code must have the same coverage as hand-written code.

Plugins (safe sandbox)

• Create: fiftyone plugins create <name> (e.g. under ~/fiftyone/__plugins__/).
• Move fast in plugins; be deliberate in core. Use develop-plugin skill for guided workflows.
• Nothing in the sandbox affects fiftyone/ or app/ without a full PR and review.

Pull requests

• Agents do not create or open PRs. The human opens the PR. The agent prepares changes, runs tests, and reports back; the human submits.
• When opening a PR (as the human): use .github/pull_request_template.md, target develop, state that an agent was used and how you tested.
• Keep PRs small and focused. At least one human approval; all CI must pass.

Security-sensitive areas

Extra care in: auth, secrets/key management, infra/CI-CD, customer data/telemetry/logging. In these areas: small PRs, explicit human review, do not rely on the agent alone for security reasoning. When in doubt, discuss with the team first.

Troubleshooting

Problem	Action
Pre-commit failed	Read hook output. Fix style/pylint; re-run pre-commit run --files <file>.
Pylint	Pre-commit uses --errors-only. Run pylint <file> for full output. Use # pylint: disable=rule sparingly.
Test failed	Run failing test with -v; confirm your change didn’t break behavior.
Import after install	Use editable install: bash install.sh -d.
CI tests failed	Run same subset locally (e.g. pytest tests/unittests/... or wrapper with same ignores).
App build/test failed	cd app && yarn install && yarn test; check Node/yarn version.

When you report back

Use this format: what you changed, what you ran, and that it passes.

Good: “Edited fiftyone/core/dataset.py, ran pre-commit run --files fiftyone/core/dataset.py, ran pytest tests/unittests/ -v for the relevant module. All pass.”

Toolbox

Use FiftyOne Skills and FiftyOne MCP Server for official workflows and style. Code style: see Code style.

FiftyOne Skills

curl -sL skil.sh | sh -s -- voxel51/fiftyone-skills

Repo: fiftyone-skills. Key for this repo: fiftyone-code-style, fiftyone-voodo-design, fiftyone-develop-plugin; plus dataset import/export, duplicates, embeddings, inference, evaluation, issue triage.

FiftyOne MCP Server

Required for dataset/operator skills (import, export, duplicates, inference, etc.). Install:

pip install fiftyone-mcp-server

Configure your AI tool with fiftyone-mcp (same Python env).
Repo: fiftyone-mcp-server

References: CONTRIBUTING.md, STYLE_GUIDE.md, app/CODING_STANDARDS.md, CODE_OF_CONDUCT.md, ISSUE_POLICY.md. Claude: ln -s AGENTS.md CLAUDE.md.