pyproject.toml

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

[project]
name = "nullrun"
# Version bump: 0.12.2 → 0.13.0 in `release(0.13.0)` (drift-fixes
# release: idempotency_key on /track + status_code on every
# decision exception + fail-CLOSED/OPEN honesty in module docstring).
# No on-wire breaking change; backends on 1.0.0 keep working
# unchanged. See docs/drift.md for the full audit trail.
# 0.13.1 (2026-07-04): drift-fixes release — see __version__.py
# for the four BLOCKER closes (B1 check_v3, B2 track_single
# docstring, B3 chain_end, M3 approximate_budget query param).
# 0.13.2 (2026-07-06): typing-debt sweep — per-file mypy overrides
# (no more blanket `ignore_errors`), split nullrun singleton state into
# nullrun._singleton (the metaclass-backing descriptor) and
# nullrun._registry (the runtime registry) so runtime.py stays the
# orchestrator only. See __version__.py for the full changelog.
# 0.13.3 (2026-07-07): developer-ergonomics — `langgraph` import
# semantics + cleanup of dead `protos/` target. See __version__.py.
# 0.13.4 (2026-07-08): bug-fix — flatten the LangChain usage-
# extraction elif-chain so every attribute source is read (not just
# the first one with ``hasattr`` truthy). Pairs with PR #59.
# 0.13.5 (2026-07-08): perf — make ``Transport._flush_loop`` sleep
# cancellable (``threading.Event.wait`` instead of ``time.sleep``)
# so ``runtime.shutdown()`` returns in ms instead of waiting out
# the full ``flush_interval`` (5s default). Plus CI hygiene:
# pip cache, ``fail-fast`` matrix, ``pytest-xdist -n auto``. No
# on-wire change; backends on 1.0.0 keep working unchanged.
version = "0.13.5"
# 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",
    # xdist pins the parallel runner as a first-class dev dep so
    # `pip install -e ".[dev]"` brings it in for local runs and
    # CI both. The CI workflow also installs it explicitly to
    # survive a future pyproject prune. ``-n auto`` is set in
    # the workflow rather than ``addopts`` so single-CPU local
    # runs (e.g. ``pytest tests/test_one.py``) don't accidentally
    # spawn a worker pool.
    "pytest-xdist>=3.6",
    # 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
# Vendor SDKs ship with weak / missing type stubs (websockets,
# langgraph.pregel, autogen_agentchat, llama_index.core, etc.). We
# want strict checking on OUR code regardless, so the missing-
# import filter applies to imports only — every signature we
# construct against the vendor API is still type-checked against
# whatever stubs (or stub-free Any) the vendor publishes. Without
# this flag, CI fails on the first try/except ImportError path
# in `auto.py`, which is the exact place we DO want strictness on
# our own logic.
ignore_missing_imports = true
# Pre-existing typing debt is tracked per-file below. The goal is
# to keep new files / new code on a strict baseline while legacy
# modules converge. Categories tracked (12 files, ~120 sites):
#   - 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
# Converge via per-file `[[tool.mypy.overrides]]` entries below —
# each file gets explicit ignore codes so CI breaks when a NEW code
# appears in that file (rather than the previous blanket
# `ignore_errors = true` that swallowed everything).
#
# Important: this block stays in lockstep with the per-file table.
# When the count in a file drops to 0, remove its override row.

[[tool.mypy.overrides]]
module = [
    "nullrun.capabilities",
    "nullrun.messages",
    "nullrun.tracing",
    "nullrun.uuid7",
    "nullrun.observability",
    "nullrun.observability.error_hooks",
    "nullrun.observability.status",
    "nullrun.breaker",
    "nullrun.breaker.circuit_breaker",
    "nullrun.breaker.exceptions",
    "nullrun.instrumentation._safe_patch",
    "nullrun.context",
    "nullrun._singleton",
    "nullrun._registry",
]
strict = true
disable_error_code = ["unused-ignore", "no-untyped-def"]

[[tool.mypy.overrides]]
# `__init__.py` — module-level `__getattr__` (PEP 562) needs
# Any-typed returns, and `_LAZY_EXPORTS` maps name strings to
# (mod, attr) tuples which mypy cannot resolve statically.
module = ["nullrun"]
disable_error_code = [
    "no-untyped-def",  # __getattr__ / shutdown / status return Any
    "arg-type",        # name strings vs. attribute lookup
    "return-value",    # dynamic attribute resolution
    "union-attr",      # runtime._runtime | None
    "unused-ignore",   # legacy `# type: ignore` markers still in tree
]

[[tool.mypy.overrides]]
# `_handle.py` — context manager / decorator generators. mypy
# struggles with contextmanager yields returning Generator types
# when the underlying callable raises.
module = ["nullrun._handle"]
disable_error_code = ["no-untyped-def", "unused-ignore"]

[[tool.mypy.overrides]]
# `runtime.py` — the orchestrator. The legacy Any-typed
# `_seen_track_fingerprints` LRU, the singleton `_instance: Optional`
# plus thread-locking around it, and the dict[str, Any] event
# envelopes all add up. Targeted fixes only.
module = ["nullrun.runtime"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `transport.py` — typing debt is concentrated in the WS / HMAC
# paths where httpx response objects are Any. transport.py also
# holds the historical pre-strict code that the codebase grew up
# around; per the comment block above, fix sites individually
# rather than expanding the override list.
module = ["nullrun.transport"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `transport_websocket.py` — `websockets` library has incomplete
# stubs; explicit Any in receive loop is unavoidable.
module = ["nullrun.transport_websocket"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "import-not-found",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `actions.py` — webhook handlers + dataclasses with Optional
# fields. ~6 sites.
module = ["nullrun.actions"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `decorators.py` — sync_wrapper / async_wrapper Any-typed by
# design (decorator preserves arbitrary return). The `Any`
# contract is the whole point of `@protect`.
module = ["nullrun.decorators"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "return-value",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `integrations/fastapi.py` — Starlette/FastAPI request types are
# loosely-typed unions; the JSONResponse helpers are Any-shaped
# by FastAPI's own API.
module = ["nullrun.integrations.fastapi"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `instrumentation/auto.py` — vendor-typed bodies (json.loads
# returns Any, vendor-specific OpenAI/Anthropic shapes). The
# extractor functions read untyped JSON; the dicts they return
# are intentionally Any.
module = ["nullrun.instrumentation.auto"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `instrumentation/auto_requests.py` — vendor SDK shape.
module = ["nullrun.instrumentation.auto_requests"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `instrumentation/langgraph.py` — langchain_core callback hooks
# are Any-typed by design.
module = ["nullrun.instrumentation.langgraph"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `instrumentation/autogen.py`, `crewai.py`, `llama_index.py` —
# vendor SDKs with weak typings, all guarded by try/except ImportError.
module = [
    "nullrun.instrumentation.autogen",
    "nullrun.instrumentation.crewai",
    "nullrun.instrumentation.llama_index",
]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "import-not-found",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `toolbox/langgraph.py` — same as langgraph instrumentation.
module = ["nullrun.toolbox.langgraph"]
disable_error_code = [
    "no-untyped-def",
    "union-attr",
    "no-any-return",
    "arg-type",
    "assignment",
    "unused-ignore",
]

[[tool.mypy.overrides]]
# `integrations/__init__.py` — pure re-export module.
module = ["nullrun.integrations"]
disable_error_code = ["no-untyped-def"]

# Tests are excluded from the strict run — pytest fixtures,
# monkeypatch, and MagicMock patterns defeat mypy's strict
# checking and would only produce noise.
[[tool.mypy.overrides]]
module = ["tests.*"]
ignore_errors = true
ignore_missing_imports = 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
    "S110",
    "E501",
    "F841",
    "E402",
    "F401",
    # 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"]
# 2026-07-08: dropped the global ``-q`` so CI logs surface the
# full PASSED line for each test (handy when scanning a red run).
# Per-test verbosity stays low because ``--tb=short`` keeps the
# tracebacks compact. ``-n auto`` lives in the workflow file, not
# here, so a developer running ``pytest tests/test_x.py`` locally
# gets a single process — the worker pool is only worth it on
# the full suite, and some single-file debug sessions actively
# want serial execution.
addopts = "--tb=short"
# 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__.:",
]