Imported from rodrigobnogueira/faker-ai-provider (AGENTS.md). Install upstream with npx skills add rodrigobnogueira/faker-ai-provider. Copyright stays with the author.

Agent Guidance

This repository contains a Faker provider for generating AI and machine-learning test data. Keep changes small, data-focused, and easy to verify.

Project Conventions

• Use the existing provider API shape in faker_ai/provider.py.
• Keep model metadata in faker_ai/model_correlations.py as plain structured data.
• Prefer adding focused tests in tests/test_provider.py when changing catalog behavior.
• Run python -m pytest before opening a PR when dependencies are available.
• Do not include local environment files such as .venv/, .pytest_cache/, or editor files in commits.

Tooling and CI

• CI must run every tool the dev extra declares. A tool that is declared but never invoked by .github/workflows/tests.yml is either wired into the workflow or dropped from the extra.

Repository and Package Renames

• After any repository or package rename, update every metadata surface that still carries the old name in the same change: [project.urls] in pyproject.toml, README badges and links, the GitHub repo About, and the docs. For PyPI, pair the URL fix with a patch release — the registry keeps serving the links from the last published version.

Model Catalog Updates

• Model catalog updates should be additive by default.
• Do not remove an existing model when adding newer models unless the user clearly asks for removal, or unless there is a verified reason such as a duplicate, typo, or demonstrably invalid/speculative entry.
• When replacing a model name with a more accurate current name, consider keeping the older verified model too if it is a real historical, legacy, deprecated, or superseded model.
• If a vendor does not publish parameter counts, use undisclosed instead of inventing a value.
• Prefer official vendor documentation, model cards, or release notes when checking model names and capabilities.
• Preserve useful historical coverage. This provider is for realistic fake data, so it may include current, legacy, deprecated, and open historical models.

Publishing a Release

The primary path is automated: pushing a vX.Y.Z tag triggers .github/workflows/release.yml, which runs the tests, builds fresh distributions, verifies the tag matches the pyproject.toml version, and publishes to PyPI via Trusted Publishing (OIDC — no token or secret; the publisher is registered on PyPI under project → Settings → Publishing for release.yml, environment pypi). The workflow also supports workflow_dispatch to (re)run a release for an already-pushed tag. The checklist below still applies — the workflow automates the build/upload steps, not the judgment ones; the manual twine upload flow remains a valid fallback.

• Publish only from an up-to-date main branch after all intended PRs are merged.
• Check PyPI for the latest published faker-ai-provider version before choosing the next version.
• Update both pyproject.toml and faker_ai/__init__.py to the same release version.
• Run the test suite and build checks before uploading: python -m pytest, python -m build, and python -m twine check dist/*.
• Build fresh artifacts for the version being published. Do not upload stale files from an old dist/ directory.
• Commit the version bump before publishing.
• Always create and push a matching git tag for every published version, using the format vX.Y.Z.
• Upload the checked wheel and source distribution to PyPI with Twine or the repository's configured trusted-publishing workflow.
• After publishing, verify the new version is visible on PyPI and that the git tag points at the release commit.
• Download the published package from PyPI into a fresh environment and run a smoke test against the installed package.