pyproject.toml

# RM-G2.5 (audit SUP-01/02/03): pyproject.toml is the single source
# of truth for this package's dependencies. The legacy `setup.py`
# and `requirements.txt` were removed in this sprint — they
# independently re-declared a subset of these deps with weaker
# version bounds, so a `pip install -r requirements.txt` could
# silently pin an older incompatible web3 (e.g., 6.x against the
# 7.15 the SDK actually targets). PEP 621 says pyproject is canonical;
# this package now follows that.

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "citrate-labs-sdk"
version = "0.6.3"
description = "Python SDK for the Citrate distributed AI network (chain 40204). The canonical TypeScript SDK is @citratelabs/sdk on npm; this Python client is opt-in and may lag it."
readme = "README.md"
requires-python = ">=3.10"
license = {text = "Apache-2.0"}
authors = [
    {name = "Citrate Team", email = "developers@citrate.ai"}
]
maintainers = [
    {name = "Citrate Team", email = "developers@citrate.ai"}
]
keywords = ["citrate", "distributed-ai", "ai", "dag", "web3", "machine-learning"]
classifiers = [
    "Development Status :: 2 - Pre-Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Topic :: System :: Distributed Computing",
]
# RM-G2.5 (audit SUP-02): numpy bumped from ~=1.21 to ~=2.0.
# numpy 1.x went into security-only mode mid-2024; new pip resolvers
# would still resolve to 1.26 against the old bound, but downstream
# packages (pandas 2.2+, web3 7.15's transitive eth-tester) have
# started rejecting 1.x. Pinning ~=2.0 avoids drift the user can't
# easily override.
#
# RM-G2.5 (audit SUP-03): web3 + eth-account already match the
# canonical bounds — kept here for future audit reference.
# SPY-B-008: `cryptography~=46.0` means `>=46.0,<47.0`, which STRUCTURALLY
# excludes every fixed release (advisories PYSEC-2026-3552/3553/3554,
# GHSA-537c-gmf6-5ccf are fixed in 48.0.1 / 49.0.0 / 50.0.0). A pin no fixed
# version can satisfy means `pip install -U` keeps selecting a vulnerable build
# forever. Widened to admit the fixed line. `cryptography` backs the AES-GCM /
# HKDF envelope (crypto.py) and RSA ID-token verification (identity/jwt.py).
dependencies = [
    "requests~=2.33",
    # PBA-L6b-026: the transport gate parses URLs with urllib3 (what requests
    # connects with) to rule out parser differentials; pinned explicitly.
    "urllib3>=2.0,<3",
    "cryptography>=48.0.1,<51",
    "eth-account~=0.9",
    "web3~=7.15",
    "numpy~=2.0",
    "typing-extensions~=4.0",
]

[project.optional-dependencies]
# RM-K / WP-K1.8 (Codex M-08): pre-K1.8 the dev extra pinned
# `isort>=8.0.1`, but the published isort line stops at 5.x — the
# 8.x constraint silently broke `pip install '.[dev]'`. Aligned to
# `isort>=5.13,<7` (5.x is the stable line; 6.x is the imminent
# next major). `ruff` already covers the import-sort lint via
# the "I" rule (see [tool.ruff.lint] block below) so keeping a
# loose isort range avoids constraining the dev environment.
dev = [
    "pytest>=7.0",
    "pytest-asyncio>=0.21",
    "black>=23.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
    "isort>=5.13,<7",
    "coverage>=7.0",
    # CI runs `mypy .` (org reusable python workflow). charts.py guards its
    # matplotlib import at runtime, but mypy still needs the package to check it;
    # tomli backs the `tomllib` fallback the pyproject tests use on Python 3.10.
    "matplotlib>=3.7",
    "tomli>=2.0",
    # The runner's preinstalled setuptools (79.0.1 in the py3.11 toolcache) carries
    # PYSEC-2026-3447, which fails the blocking pip-audit step. Pull the fixed release
    # into the dev env explicitly rather than ignoring the advisory.
    "setuptools>=83",
]
docs = [
    "sphinx>=8.1.3",
    "sphinx-rtd-theme>=1.0",
    "myst-parser>=2.0",
    "sphinx-autodoc-typehints>=1.20",
]

# 2026-08-01: the PUBLISHED 0.6.0 points Repository/Bug Tracker/Changelog at the
# private pre-split monorepo on a personal account (SaulBuilds/citrate), so every
# link 404s for the public. 0.6.1 names the canonical federation repo. The repo
# went public (2026-09-24), so issues and the changelog link there directly.
[project.urls]
Homepage = "https://citrate.ai"
Documentation = "https://docs.citrate.ai"
Repository = "https://github.com/CitrateNetwork/citrate-sdk-python"
"Bug Tracker" = "https://github.com/CitrateNetwork/citrate-sdk-python/issues"
Changelog = "https://github.com/CitrateNetwork/citrate-sdk-python/blob/main/CHANGELOG.md"

[project.scripts]
citrate = "citrate_sdk.cli:main"

[tool.setuptools.packages.find]
where = ["."]
include = ["citrate_sdk*"]
exclude = ["tests*"]

[tool.setuptools.package-data]
citrate_sdk = ["py.typed", "*.pyi"]
# The vendored federation contract artifact (DEVX-S0) must ship in the wheel; contract.py
# reads it at runtime via importlib/Path, so it is not importable Python and needs package-data.
"citrate_sdk._generated" = ["*.json"]

# Black formatting
[tool.black]
line-length = 88
target-version = ['py310', 'py311', 'py312']
include = '\.pyi?$'
extend-exclude = '''
/(
  # directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | build
  | dist
)/
'''

# Ruff linting
[tool.ruff]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # pyflakes
    "I",  # isort
    "B",  # flake8-bugbear
    "C4", # flake8-comprehensions
    "UP", # pyupgrade
]
ignore = [
    "E501",  # line too long, handled by black
    "B008",  # do not perform function calls in argument defaults
    "C901",  # too complex
    # Deferred style/quality cleanups (2026-09-23): the real bugs (F821 undefined name,
    # F811 duplicate class) were fixed in code; these remaining lints are non-correctness
    # style the existing code doesn't yet follow. Ignored to establish a green baseline;
    # tighten (and remove) incrementally.
    "B904",  # raise ... from err (exception chaining)
    "UP031", # printf-style %-formatting -> str.format / f-string
    "B007",  # unused loop control variable
    "B017",  # pytest.raises(Exception) too broad (tests)
    "E702",  # multiple statements on one line (semicolon)
]
line-length = 88
target-version = "py310"

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]

# MyPy type checking
[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
disallow_untyped_decorators = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
warn_unreachable = true
strict_equality = true

# The org reusable CI runs `mypy .`, which also reaches tests/. Test bodies are
# still type-checked (check_untyped_defs above); only the annotate-every-test-
# function requirement is relaxed there. The package itself stays fully strict.
[[tool.mypy.overrides]]
module = ["tests.*"]
disallow_untyped_defs = false
disallow_incomplete_defs = false

# Pytest configuration
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = [
    "--strict-markers",
    "--strict-config",
    "--verbose",
    "--tb=short",
]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "integration: marks tests as integration tests (requires running node)",
    "unit: marks tests as unit tests",
    "testnet: marks tests for testnet environment",
    "devnet: marks tests for devnet environment",
]
filterwarnings = [
    "ignore::DeprecationWarning",
]
# NOTE: Set CITRATE_RPC_URL and CITRATE_CHAIN_ID via shell env or .env file.
# The pytest-env plugin key was removed because it requires an optional dependency.

# Coverage configuration
[tool.coverage.run]
source = ["citrate_sdk"]
omit = [
    "*/tests/*",
    "*/test_*",
    "*/__pycache__/*",
    "*/site-packages/*",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "if self.debug:",
    "if settings.DEBUG",
    "raise AssertionError",
    "raise NotImplementedError",
    "if 0:",
    "if __name__ == .__main__.:",
    "class .*\\bProtocol\\):",
    "@(abc\\.)?abstractmethod",
]