pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "nullrun"
# Version bump: 0.11.0 → 0.12.0 in `feat(sdk)` (server-minted
# execution_id default + capability probe). The previous commit
# updated `src/nullrun/__version__.py` but missed this field, so
# `python -m build` was producing a wheel named `nullrun-0.11.0-*`
# that collided with the 0.11.0 artifact already on TestPyPI
# (causing the publish-test workflow to fail with HTTP 400
# "File already exists").
version = "0.12.0"
# Long form used by PyPI page meta-description and search snippets.
# Kept under the 200-char preview threshold so the full line is visible
# without an "expand" click. Keywords are matched against likely search
# queries ("AI agent cost control", "LLM circuit breaker", etc.).
description = "NullRun Python SDK — enforcement gateway for AI agents. Circuit-breaker, policy enforcement and observability for OpenAI, Anthropic, LangGraph, LlamaIndex, CrewAI, AutoGen."
readme = "README.md"
license = { text = "Apache-2.0" }
requires-python = ">=3.10"

# Authors and maintainers are populated dynamically by the custom
# metadata hook in ``hatch_build.py``. Declaring ``authors`` here as a
# dynamic field is what triggers hatchling to call
# ``MetadataHookInterface.update()`` at all — without at least one
# field in ``dynamic``, the hook is configured but never invoked.
#
# Why dynamic in the first place: PEP 621 maps the ``authors`` array to
# PKG-INFO's ``Author-email:`` line but NOT to the legacy single
# ``Author:`` line that ``pip show`` renders. Worse, hatchling's
# authors parser (core.py, ``authors`` property) only populates the
# legacy ``Author:`` field when an inline-table has a ``name`` and NO
# ``email``; if both are present the name is folded into the email's
# display_name and ``Author:`` is suppressed. The hook splits the
# author into two inline-tables (name-only + email-only) so both lines
# appear in the wheel METADATA.
dynamic = ["authors", "maintainers"]

keywords = [
    "circuit-breaker", "agent", "llm", "observability",
    "ai-safety", "rate-limiting", "nullrun"
]

classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Intended Audience :: System Administrators",
    "License :: OSI Approved :: Apache Software License",
    "Operating System :: OS Independent",
    "Operating System :: POSIX :: Linux",
    "Operating System :: Microsoft :: Windows",
    "Operating System :: MacOS",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: Implementation :: CPython",
    "Topic :: Software Development :: Libraries :: Python Modules",
    # The SDK is positioned as a safety/cost-control layer for AI agents,
    # so the Security and AI topics help PyPI search surface it for the
    # queries developers actually run when shopping for these tools.
    "Topic :: Security",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Topic :: Internet :: WWW/HTTP",
    "Typing :: Typed",
]

dependencies = [
    "httpx>=0.27.0,<1.0",
]

[project.optional-dependencies]
opentelemetry = [
    "opentelemetry-api>=1.26.0,<2.0",
    "opentelemetry-sdk>=1.26.0,<2.0",
]
langgraph = [
    "langgraph>=0.2.0,<1.0",
]
# Phase E1: per-vendor auto-instrumentation dependencies.
# Each patch in `nullrun.instrumentation.auto` wraps its vendor import in
# `try/except ImportError` so a user who installs only one extras group
# does not crash on SDK init. This matches the plan: zero glue code for
# `nullrun.init(api_key=...)` to track all common LLM vendors.
openai = ["openai>=1.0,<2.0"]
anthropic = ["anthropic>=0.20,<1.0"]
mistral = ["mistralai>=0.4,<1.0"]
gemini = ["google-genai>=1.0,<2.0"]
cohere = ["cohere>=5.0,<6.0"]
bedrock = ["boto3>=1.34,<2.0"]
agents = ["openai-agents>=0.1,<1.0"]
langchain = ["langchain-core>=0.3,<1.0"]
# Phase 7: new framework auto-instrumentation dependencies.
# Each patch in `nullrun.instrumentation.llama_index`, `crewai`, and
# `autogen` wraps its framework import in `try/except ImportError` so
# `nullrun.init()` never crashes when the optional package is missing.
llama-index = ["llama-index-core>=0.10.20,<1.0"]
crewai = ["crewai>=0.80,<2.0"]
autogen = [
    "autogen-agentchat>=0.4,<1.0",
    "autogen-ext[openai]>=0.4,<1.0",
]
# Server-framework integrations. Each one pulls the framework so the
# corresponding ``nullrun.integrations.<framework>`` module can be
# imported. ``nullrun.integrations.__init__`` does NOT eager-import
# these (the submodules are loaded lazily on first ``from
# nullrun.integrations import <framework>``), so users who don't use
# a given framework don't pay its install cost.
fastapi = [
    "fastapi>=0.100,<1.0",
]
all = [
    "openai>=1.0,<2.0",
    "anthropic>=0.20,<1.0",
    "mistralai>=0.4,<1.0",
    "google-genai>=1.0,<2.0",
    "cohere>=5.0,<6.0",
    "boto3>=1.34,<2.0",
    "openai-agents>=0.1,<1.0",
    "langchain-core>=0.3,<1.0",
    "llama-index-core>=0.10.20,<1.0",
    "crewai>=0.80,<2.0",
    "autogen-agentchat>=0.4,<1.0",
    "autogen-ext[openai]>=0.4,<1.0",
]
dev = [
    "pytest>=8.0",
    "pytest-asyncio>=0.23",
    "respx>=0.21",
    "mypy>=1.10",
    "ruff>=0.5",
    "coverage[toml]>=7.0",
    "httpx>=0.27.0,<1.0",
    # The SDK eagerly imports `nullrun.instrumentation.langgraph`
    # (from `nullrun.decorators`, imported by `nullrun.__init__` at
    # collection time), which itself does `from langchain_core.callbacks
    # import BaseCallbackHandler`. Without this dep, *every* test in
    # the suite errors at pytest collection, not at a specific test.
    # CI installs `[dev]` only, so the test extras need to cover the
    # import chain. `langchain-core` is the smallest dep that makes
    # the import succeed; the `langgraph` and `langchain` extras pull
    # in heavier stacks that the unit tests don't need.
    "langchain-core>=0.3,<1.0",
    # `tests/test_integrations_fastapi.py` does `from fastapi import ...`
    # at module top-level, so pytest collection aborts the entire suite
    # with ModuleNotFoundError if FastAPI isn't installed. Same import-
    # time contract as `langchain-core` above; pin to the same lower
    # bound as the `[fastapi]` extra so CI and end users agree on the
    # minimum. `httpx` (already a core dep) covers `TestClient`.
    "fastapi>=0.100,<1.0",
]

[project.urls]
# The homepage, docs and repository are the three links PyPI surfaces on
# the project sidebar. The rest are convenience links that appear under
# the "Project links" expander — they help users jump straight to the
# issue tracker, release notes, or security policy without going through
# the GitHub repo root first.
Homepage = "https://nullrun.io"
Documentation = "https://docs.nullrun.io"
Repository = "https://github.com/nullrunio/nullrun-sdk-python"
"Bug Tracker" = "https://github.com/nullrunio/nullrun-sdk-python/issues"
Discussions = "https://github.com/nullrunio/nullrun-sdk-python/discussions"
Changelog = "https://github.com/nullrunio/nullrun-sdk-python/blob/master/CHANGELOG.md"
Releases = "https://github.com/nullrunio/nullrun-sdk-python/releases"
"Source" = "https://github.com/nullrunio/nullrun-sdk-python"
"Security Policy" = "https://github.com/nullrunio/nullrun-sdk-python/security/policy"
Organization = "https://github.com/nullrunio"
Examples = "https://github.com/nullrunio/nullrun-examples"

[tool.hatch.build.targets.wheel]
packages = ["src/nullrun"]
include = [
    "src/nullrun/py.typed",
]

# Custom metadata hook: rewrites ``project.authors`` into name-only +
# email-only inline tables so hatchling's authors parser populates both
# the legacy ``Author:`` field and the ``Author-email:`` field. See
# ``hatch_build.py`` for the full rationale. The hook lives at the repo
# root because hatchling discovers it by import path, not via the wheel
# ``packages`` list above (which only covers the runtime package).
[tool.hatch.metadata.hooks.custom]
path = "hatch_build.py"

[tool.hatch.build.targets.sdist]
exclude = [
    "tests/",
    ".github/",
    "*.pyc",
    "__pycache__",
]

[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_any_generics = true
# Pre-existing mypy errors in master / wip/working-tree code:
# 102 errors across 12 files. Categories include:
#   - union-attr: Optional types not narrowed (Transport | None)
#   - no-any-return: not-yet-typed returns
#   - arg-type: str | None passed where str expected
#   - no-untyped-def: missing return type annotations
#   - unused-ignore: stale "# type: ignore" comments
#   - assignment: implicit Optional in default values
#   - import-not-found: langgraph.pregel stub missing
# Per-file ignores would be more precise but 102 individual
# overrides across 12 files is out of scope for this follow-up.
# Track in a dedicated typing pass after the SDK is on a stable
# mypy --strict baseline (this PR only turns CI green today).
ignore_errors = true

[tool.ruff]
target-version = "py310"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "S"]
ignore = [
    "S101",
    # Pre-existing violations in master / wip/working-tree: tracked
    # for follow-up cleanup in a dedicated PR rather than blocking CI.
    # Categories:
    #   S110 (try/except/pass) - 14 sites; needs logging, not blanket
    #                               noqa
    #   E501 (line too long)    - 13 sites; long descriptive comments
    #   F841 (unused variable)  - 6 sites; one is the timestamp var
    #                               in the legacy-code fallback path
    #   E402 (import order)     - 5 sites; TYPE_CHECKING blocks
    #   F401 (unused import)    - 2 sites
    #   F821 (undefined name)   - 1 site; needs investigation
    "S110",
    "E501",
    "F841",
    "E402",
    "F401",
    "F821",
    # S311 (suspicious random) - 1 site, in circuit_breaker jitter.
    # random.uniform is correct for jitter (we want non-cryptographic
    # randomness to spread reconnection timing across workers).
    "S311",
]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S", "B"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
addopts = "--tb=short -q"
# Make the tests/ directory importable as a top-level package so
# tests can use `from tests.conftest import BASE_URL`. Without this,
# `from tests.conftest` raises ModuleNotFoundError on Python 3.10/3.11
# because pytest's rootdir discovery lands on the repo root rather
# than the tests/ directory.
pythonpath = ["."]

[tool.coverage.run]
source = ["src/nullrun"]
omit = ["tests/*"]
# Branch coverage: every if/else, try/except, ternary contributes two
# branches instead of one. Disabled by default in the stdlib config;
# the SDK has too many error / fallback paths to leave these invisible.
branch = true

[tool.coverage.report]
fail_under = 82
show_missing = true
# Branch coverage makes the report noisier; precision=2 keeps the
# numbers readable. skip_empty drops files with no statements.
precision = 2
skip_empty = true
exclude_lines = [
    "pragma: no cover",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
]