pyproject.toml

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=64", "setuptools_scm>=8"]

[dependency-groups]
codeflash = [
    "codeflash>=0.8",  # Pin for --verify-setup checking formatter-cmds
    "fhaviary[dev]",
]
dev = [
    "fhaviary[dev]",
]

[project]
authors = [
    {email = "hello@futurehouse.org", name = "FutureHouse technical staff"},
]
# Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers = [
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python",
]
dependencies = [
    "docstring_parser>=0.16",  # Pin for description addition
    "httpx",
    "pydantic~=2.0",
]
description = "Gymnasium framework for training language model agents on constructive tasks"
dynamic = ["version"]
license = {file = "LICENSE"}
name = "fhaviary"
readme = "README.md"
requires-python = ">=3.11"

[project.optional-dependencies]
cloud = [
    "boto3",
]
dev = [
    "aviary.gsm8k[typing]",
    "aviary.hotpotqa",
    "aviary.lfrqa",
    "aviary.litqa",
    "fhaviary[image,llm,server,typing,xml]",
    "httpx<0.28",  # Pin until we remove app argument in clients that was deprecated in 0.28
    "ipython>=8",  # Pin to keep recent
    "mypy>=1.8",  # Pin for mutable-override
    "numpy>=1",  # Pin to keep recent
    "pre-commit>=3.4",  # Pin to keep recent
    "pydantic~=2.9",  # Pydantic 2.9 changed JSON schema exports 'allOf', so ensure tests match
    "pylint-pydantic",
    "pylint>=3.2",  # Pin to keep recent
    "pytest-asyncio",
    "pytest-recording",
    "pytest-subtests",
    "pytest-sugar",
    "pytest-timer[colorama]",
    "pytest-xdist",
    "pytest>=8",  # Pin to keep recent
    "refurb>=2",  # Pin to keep recent
    "typeguard",
    "vcrpy>=6",  # Pin for https://github.com/kevin1024/vcrpy/issues/884
]
gsm8k = ["aviary.gsm8k"]
hotpotqa = ["aviary.hotpotqa"]
image = [
    "Pillow",
]
lfrqa = ["aviary.lfrqa"]
litqa = ["aviary.litqa"]
llm = [
    "fhlmi",
    'litellm; python_version < "3.13"',  # NOTE: paper-qa==5.3 doesn't support 3.13 yet
    'litellm>=1.49.1; python_version >= "3.13"',  # For removal of imghdr
]
server = [
    "click",
    "cloudpickle",
    "fastapi",
    "uvicorn",
]
typing = [
    "boto3-stubs[s3]",
    "numpy",
    "pandas-stubs",
    "types-Pillow",
]
xml = [
    "dicttoxml",
]

[project.scripts]
aviary = "aviary.main:cli"

[project.urls]
issues = "https://github.com/Future-House/aviary/issues"
repository = "https://github.com/Future-House/aviary"

[tool.black]
preview = true

[tool.codeflash]
disable-imports-sorting = true
disable-telemetry = true
formatter-cmds = ["uv tool run ruff check --exit-zero --fix $file", "uv tool run ruff format $file"]
module-root = "src/aviary"
test-framework = "pytest"
tests-root = "tests"

[tool.codespell]
check-filenames = true
check-hidden = true
ignore-words-list = "astroid,ser"

[tool.mypy]
# Type-checks the interior of functions without type annotations.
check_untyped_defs = true
# Allows enabling one or multiple error codes globally. Note: This option will
# override disabled error codes from the disable_error_code option.
enable_error_code = [
    "ignore-without-code",
    "mutable-override",
    "redundant-cast",
    "redundant-expr",
    "redundant-self",
    "truthy-bool",
    "truthy-iterable",
    "unimported-reveal",
    "unreachable",
    "unused-awaitable",
    "unused-ignore",
]
# Shows a short summary line after error messages.
error_summary = false
# A regular expression that matches file names, directory names and paths which mypy
# should ignore while recursively discovering files to check. Use forward slashes (/) as
# directory separators on all platforms.
exclude = [
    "^\\.?venv",  # SEE: https://regex101.com/r/0rp5Br/1
]
# This flag tells mypy that top-level packages will be based in either the current
# directory, or a member of the MYPYPATH environment variable or mypy_path config
# option. This option is only useful in the absence of __init__.py. See Mapping file
# paths to modules for details.
explicit_package_bases = true
# Specifies the paths to use, after trying the paths from MYPYPATH environment variable.
# Useful if you'd like to keep stubs in your repo, along with the config file.
# Multiple paths are always separated with a : or , regardless of the platform.
# User home directory and environment variables will be expanded.
mypy_path = "$MYPY_CONFIG_FILE_DIR/src,$MYPY_CONFIG_FILE_DIR/packages/gsm8k/src,$MYPY_CONFIG_FILE_DIR/packages/hotpotqa/src,$MYPY_CONFIG_FILE_DIR/packages/lfrqa/src,$MYPY_CONFIG_FILE_DIR/packages/litqa/src"
# Specifies the OS platform for the target program, for example darwin or win32
# (meaning OS X or Windows, respectively). The default is the current platform
# as revealed by Python’s sys.platform variable.
platform = "linux"
# Comma-separated list of mypy plugins.
plugins = ["pydantic.mypy"]
# Use visually nicer output in error messages: use soft word wrap, show source
# code snippets, and show error location markers.
pretty = true
# Shows column numbers in error messages.
show_column_numbers = true
# Shows error codes in error messages.
# SEE: https://mypy.readthedocs.io/en/stable/error_codes.html#error-codes
show_error_codes = true
# Prefixes each error with the relevant context.
show_error_context = true
# Warns about casting an expression to its inferred type.
warn_redundant_casts = true
# Shows a warning when encountering any code inferred to be unreachable or
# redundant after performing type analysis.
warn_unreachable = true
# Warns about per-module sections in the config file that do not match any
# files processed when invoking mypy.
warn_unused_configs = true
# Warns about unneeded `# type: ignore` comments.
warn_unused_ignores = true

[[tool.mypy.overrides]]
# Suppresses error messages about imports that cannot be resolved.
ignore_missing_imports = true
# Per-module configuration options
module = [
    "cloudpickle",  # SEE: https://github.com/cloudpipe/cloudpickle/issues/541
    "datasets",  # SEE: https://github.com/huggingface/datasets/issues/3841
    "dicttoxml",  # SEE: https://github.com/quandyfactory/dicttoxml/issues/106
    "vcr.*",  # SEE: https://github.com/kevin1024/vcrpy/issues/780
]

[tool.pylint]

[tool.pylint.design]
# Maximum number of attributes for a class (see R0902).
max-attributes = 12

[tool.pylint.format]
# Maximum number of characters on a single line.
max-line-length = 88  # Match ruff line-length

[tool.pylint.main]
# Use multiple processes to speed up Pylint. Specifying 0 will auto-detect the
# number of processors available to use, and will cap the count on Windows to
# avoid hangs.
jobs = 0
# List of plugins (as comma separated values of python module names) to load,
# usually to register additional checkers.
load-plugins = [
    "pylint_pydantic",
]

[tool.pylint.messages_control]
# Disable the message, report, category or checker with the given id(s).
disable = [
    "arguments-differ",  # Ops intentionally differ arguments
    "attribute-defined-outside-init",  # Disagrees with reset pattern
    "bare-except",  # Rely on ruff E722 for this
    "broad-exception-caught",  # Don't care to enforce this
    "broad-exception-raised",  # Rely on ruff TRY002 for this
    "cyclic-import",  # Let Python blow up
    "dangerous-default-value",  # Rely on ruff W0102 for this
    "empty-docstring",  # Let pep257 take care of docstrings
    "expression-not-assigned",  # Rely on mypy func-returns-value for this
    "fixme",  # codetags are useful
    "function-redefined",  # Rely on mypy no-redef for this
    "import-outside-toplevel",  # Rely on ruff PLC0415 for this
    "invalid-name",  # Don't care to enforce this
    "keyword-arg-before-vararg",  # Rely on ruff B026 for this
    "line-too-long",  # Rely on ruff E501 for this
    "logging-fstring-interpolation",  # f-strings are convenient
    "logging-too-many-args",  # Rely on ruff PLE1205 for this
    "missing-docstring",  # Let docformatter and ruff take care of docstrings
    "missing-final-newline",  # Rely on ruff W292 for this
    "no-else-return",  # Rely on ruff RET506 for this
    "no-member",  # Buggy, SEE: https://github.com/pylint-dev/pylint/issues/8138
    "no-value-for-parameter",  # Rely on mypy call-arg for this
    "not-callable",  # Don't care to enforce this
    "protected-access",  # Don't care to enforce this
    "raise-missing-from",  # Rely on ruff B904 for this
    "redefined-builtin",  # Rely on ruff A002 for this
    "redefined-outer-name",
    "super-init-not-called",  # Don't care to enforce this
    "too-few-public-methods",  # Don't care to enforce this
    "too-many-ancestors",  # Don't care to enforce this
    "too-many-arguments",  # Don't care to enforce this
    "too-many-branches",  # Rely on ruff PLR0912 for this
    "too-many-instance-attributes",  # Don't care to enforce this
    "too-many-lines",  # Don't care to enforce this
    "too-many-locals",  # Rely on ruff PLR0914 for this
    "too-many-positional-arguments",  # Don't care to enforce this
    "too-many-public-methods",  # Rely on ruff PLR0904 for this
    "too-many-return-statements",  # Rely on ruff PLR0911 for this
    "too-many-statements",  # Rely on ruff PLR0915 for this
    "ungrouped-imports",  # Rely on ruff I001 for this
    "unidiomatic-typecheck",  # Rely on ruff E721 for this
    "unreachable",  # Rely on mypy unreachable for this
    "unspecified-encoding",  # Don't care to enforce this
    "unsubscriptable-object",  # Buggy, SEE: https://github.com/pylint-dev/pylint/issues/3637
    "unsupported-membership-test",  # Buggy, SEE: https://github.com/pylint-dev/pylint/issues/3045
    "unused-argument",  # Rely on ruff ARG002 for this
    "unused-import",  # Rely on ruff F401 for this
    "unused-variable",  # Rely on ruff F841 for this
    "wrong-import-order",  # Rely on ruff I001 for this
    "wrong-import-position",  # Rely on ruff E402 for this
]
# Enable the message, report, category or checker with the given id(s).
enable = [
    "useless-suppression",  # Print unused `pylint: disable` comments
]

[tool.pylint.reports]
# Set true to activate the evaluation score.
score = false

[tool.pylint.similarities]
# Minimum lines number of a similarity.
min-similarity-lines = 12

[tool.pytest.ini_options]
# Add the specified OPTS to the set of command line arguments as if they had been
# specified by the user.
addopts = "--typeguard-packages=aviary --doctest-modules"
# Sets a list of filters and actions that should be taken for matched warnings.
# By default all warnings emitted during the test session will be displayed in
# a summary at the end of the test session.
filterwarnings = [
    "ignore:Support for class-based `config` is deprecated, use ConfigDict instead",  # SEE: https://github.com/BerriAI/litellm/issues/5648
    'ignore:open_text is deprecated. Use files\(\) instead:DeprecationWarning',  # SEE: https://github.com/BerriAI/litellm/issues/5647
]
# List of directories that should be searched for tests when no specific directories,
# files or test ids are given in the command line when executing pytest from the rootdir
# directory. File system paths may use shell-style wildcards, including the recursive **
# pattern.
testpaths = ["packages/gsm8k/tests", "packages/hotpotqa/tests", "packages/lfrqa/tests", "packages/litqa/tests", "src", "tests"]

[tool.refurb]
enable_all = true
ignore = [
    "FURB101",  # Rely on ruff FURB101 for this
    "FURB103",  # Rely on ruff FURB103 for this
    "FURB141",  # Rely on ruff PTH110 for this
    "FURB144",  # Rely on ruff PTH107 for this
    "FURB146",  # Rely on ruff PTH113 for this
    "FURB147",  # Rely on ruff PTH118 for this
    "FURB150",  # Rely on ruff PTH102 for this
    "FURB155",  # Rely on ruff PTH202 for this
]

[tool.ruff]
# Line length to use when enforcing long-lines violations (like `E501`).
line-length = 88
# Enable application of unsafe fixes.
unsafe-fixes = true

[tool.ruff.format]
# Enable reformatting of code snippets in docstrings.
docstring-code-format = true
# Enable preview style formatting.
preview = true

[tool.ruff.lint]
explicit-preview-rules = true
extend-select = [
    "AIR301",
    "AIR302",
    "AIR303",
    "ASYNC116",
    "B901",
    "B903",
    "B909",
    "B911",
    "C420",
    "CPY001",
    "DOC201",
    "DOC202",
    "DOC402",
    "DOC403",
    "DOC501",
    "DOC502",
    "DTZ901",
    "E111",
    "E112",
    "E113",
    "E114",
    "E115",
    "E116",
    "E117",
    "E201",
    "E202",
    "E203",
    "E204",
    "E211",
    "E221",
    "E222",
    "E223",
    "E224",
    "E225",
    "E226",
    "E227",
    "E228",
    "E231",
    "E241",
    "E242",
    "E251",
    "E252",
    "E261",
    "E262",
    "E265",
    "E266",
    "E271",
    "E272",
    "E273",
    "E274",
    "E275",
    "E301",
    "E302",
    "E303",
    "E304",
    "E305",
    "E306",
    "E502",
    "FAST003",
    "FURB101",
    "FURB103",
    "FURB110",
    "FURB113",
    "FURB116",
    "FURB118",
    "FURB122",
    "FURB131",
    "FURB132",
    "FURB140",
    "FURB142",
    "FURB145",
    "FURB148",
    "FURB152",
    "FURB154",
    "FURB156",
    "FURB157",
    "FURB162",
    "FURB164",
    "FURB166",
    "FURB171",
    "FURB180",
    "FURB189",
    "FURB192",
    "LOG004",
    "LOG014",
    "LOG015",
    "PLC0415",
    "PLC1802",
    "PLC1901",
    "PLC2701",
    "PLC2801",
    "PLE0304",
    "PLE1141",
    "PLE4703",
    "PLR0202",
    "PLR0203",
    "PLR0904",
    "PLR0914",
    "PLR0916",
    "PLR0917",
    "PLR1702",
    "PLR1733",
    "PLR6104",
    "PLR6201",
    "PLR6301",
    "PLW0108",
    "PLW0177",
    "PLW0244",
    "PLW1507",
    "PLW1514",
    "PLW1641",
    "PLW3201",
    "PT028",
    "PT029",
    "PT030",
    "PT031",
    "PTH208",
    "PTH210",
    "PYI059",
    "PYI061",
    "RUF027",
    "RUF028",
    "RUF029",
    "RUF031",
    "RUF035",
    "RUF036",
    "RUF037",
    "RUF038",
    "RUF039",
    "RUF040",
    "RUF041",
    "RUF043",
    "RUF045",
    "RUF046",
    "RUF047",
    "RUF048",
    "RUF049",
    "RUF051",
    "RUF052",
    "RUF053",
    "RUF054",
    "RUF055",
    "RUF056",
    "RUF057",
    "RUF058",
    "SIM905",
    "TC006",
    "TC007",
    "TC008",
    "UP042",
    "UP044",
    "UP045",
    "UP046",
    "UP047",
    "UP049",
    "W391",
]
external = [
    "FURB",  # refurb
]
# List of rule codes that are unsupported by Ruff, but should be preserved when
# (e.g.) validating # noqa directives. Useful for retaining # noqa directives
# that cover plugins not yet implemented by Ruff.
ignore = [
    "ANN",  # Don't care to enforce typing
    "ARG002",  # Thrown all the time when we are subclassing
    "ARG003",  # Thrown all the time when we are subclassing
    "ASYNC109",  # Buggy, SEE: https://github.com/astral-sh/ruff/issues/12353
    "BLE001",  # Don't care to enforce blind exception catching
    "C901",  # Don't care to enforce complex functions
    "COM812",  # Trailing comma with black leads to wasting lines
    "CPY001",  # Don't care to require copyright notices in every file
    "D100",  # D100, D101, D102, D103, D104, D105, D106, D107: don't always need docstrings
    "D101",
    "D102",
    "D103",
    "D104",
    "D105",
    "D106",
    "D107",
    "D203",  # Keep docstring next to the class definition (covered by D211)
    "D212",  # Summary should be on second line (opposite of D213)
    "D402",  # It's nice to reuse the method name
    "D406",  # Google style requires ":" at end
    "D407",  # We aren't using numpy style
    "D413",  # Blank line after last section. -> No blank line
    "DOC201",  # Don't care to require Returns in docstrings
    "DOC402",  # Don't care to require Yields in docstrings
    "DOC501",  # Don't care to enforce this
    "DTZ",  # Don't care to have timezone safety
    "E501",  # Overly pedantic for Tool.__doc__
    "EM",  # Overly pedantic
    "ERA001",  # Don't care to prevent commented code
    "FBT001",  # FBT001, FBT002: overly pedantic
    "FBT002",
    "FIX",  # Don't care to prevent TODO, FIXME, etc.
    "FLY002",  # Can be less readable
    "G004",  # f-strings are convenient
    "INP001",  # Can use namespace packages
    "ISC001",  # For ruff format compatibility
    "N803",  # Allow matching math formula names/conventions
    "N806",  # Allow matching math formula names/conventions
    "PLC0415",  # Don't care to prevent imports outside of top-level
    "PLR0912",  # Allow us to have lots of branches
    "PLR0913",
    "PLR0917",  # Don't care to enforce this
    "PLR6301",  # Environment.reset or Environment.export_frame can not use self
    "PLW2901",  # Allow modifying loop variables
    "PTH",  # Overly pedantic
    "RUF027",  # Prompt templates may not be f-strings
    "S101",  # Don't care to prevent asserts
    "S105",  # Duplicates Yelp/detect-secrets in pre-commit
    "S311",  # Ok to use python random
    "SLF001",  # Overly pedantic
    "T201",  # Overly pedantic
    "TC001",  # TC001, TC002, TC003: don't care to enforce type checking blocks
    "TC002",
    "TC003",
    "TD002",  # Don't care for TODO author
    "TD003",  # Don't care for TODO links
    "TRY003",  # Overly pedantic
    "W505",  # Overly pedantic for Tool.__doc__
]
preview = true
select = ["ALL"]
unfixable = [
    "B007",  # While debugging, unused loop variables can be useful
    "B905",  # Default fix is zip(strict=False), but that can hide bugs
    "ERA001",  # While debugging, temporarily commenting code can be useful
    "F401",  # While debugging, unused imports can be useful
    "F841",  # While debugging, unused locals can be useful
    "TC004",  # While debugging, it can be nice to keep TYPE_CHECKING in-tact
]

[tool.ruff.lint.flake8-annotations]
mypy-init-return = true

[tool.ruff.lint.per-file-ignores]
"**/tests/*.py" = [
    "F841",  # Tests can have unused locals
    "N802",  # Tests function names can match class names
    "PLR2004",  # Tests can have magic values
    "PLR6301",  # Test classes can ignore self
    "S101",  # Tests can have assertions
]
"docs/**.ipynb" = [
    "PLE1142",  # allow async
    "PLR2004",  # allow magic values
    "S307",  # allow eval
]

[tool.ruff.lint.pycodestyle]
# The maximum line length to allow for line-length violations within
# documentation (W505), including standalone comments.
max-doc-length = 120
# The maximum line length to allow for line-too-long violations. By default,
# this is set to the value of the line-length option.
max-line-length = 120

[tool.ruff.lint.pydocstyle]
# Whether to use Google-style or NumPy-style conventions or the PEP257
# defaults when analyzing docstring sections.
convention = "google"

[tool.ruff.lint.pylint]
allow-dunder-method-names = [
    "__get_pydantic_core_schema__",  # Pydantic built-in: https://docs.pydantic.dev/latest/concepts/types/#customizing-validation-with-__get_pydantic_core_schema__
]

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools_scm]
version_file = "src/aviary/version.py"

[tool.tomlsort]
all = true
in_place = true
spaces_before_inline_comment = 2  # Match Python PEP 8
spaces_indent_inline_array = 4  # Match Python PEP 8
trailing_comma_inline_array = true

[tool.uv.sources]
"aviary.gsm8k" = {workspace = true}
"aviary.hotpotqa" = {workspace = true}
"aviary.lfrqa" = {workspace = true}
"aviary.litqa" = {workspace = true}
fhaviary = {workspace = true}

[tool.uv.workspace]
members = ["packages/*"]