pyproject.toml

[build-system]
# The build backend is pinned to an EXACT version on purpose.
#
# SDK-3 (security audit 2026-11-06) found ``requires = ["hatchling"]``
# with no constraint. The publish job resolves this list fresh, inside
# the job that holds the PyPI Trusted Publishing token
# (``permissions: id-token: write``). An unpinned backend means the
# version that builds and uploads the wheel is chosen at publish time,
# not at commit time, so a new upstream release lands inside the
# trusted-publishing job without a review.
#
# An exact pin makes that resolution deterministic. Bump it explicitly
# (with a test run) rather than letting the range float.
requires = ["hatchling==1.32.4"]
build-backend = "hatchling.build"

[project]
name = "nullrun"
# Full release history lives in CHANGELOG.md; only the current version
# is pinned here.
version = "0.24.0"
# Kept under the 200-char preview threshold so the full line is visible
# without an "expand" click. The headline is the canonical §1 statement
# from positioning.md — "runtime decision layer for tool-using AI agents"
# (not "enforcement gateway", which undersells Phase 1 typed action
# predicates and 3 MCP-aware enforcement). Vendor list kept for
# searchability; "BusinessImpact" + "MCP-aware" surface the two newest
# differentiators. Keywords below match the likely search queries.
description = "NullRun Python SDK — runtime decision layer for tool-using AI agents."
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 is an observability standard (not a vendor framework);
# auto-detected at runtime when installed.
opentelemetry = [
    "opentelemetry-api>=1.26.0,<2.0",
    "opentelemetry-sdk>=1.26.0,<2.0",
]
# DEF-SDK-16 (RUN_ID 20261015T1809). ``transport_websocket.connect``
# raises ``ImportError("… Install with: pip install nullrun[websocket]")``
# when the ``websockets`` import fails — but no ``websocket`` extra was
# ever declared, so the command in the error message did not exist and
# pip rejected it. The extra below makes the message true.
#
# The floor is 14.0, not "any version": the transport calls
# ``websockets.connect(url, additional_headers=...)``. The
# ``additional_headers`` spelling belongs to the asyncio client that
# became the default ``websockets.connect`` in 14.0; earlier releases
# spelled the same argument ``extra_headers``, so a lower floor
# resolves and then fails at connect time with a TypeError instead of
# at import time.
websocket = [
    "websockets>=14.0,<17.0",
]
dev = [
    # ``tests/test_ws_push.py`` imports ``websockets`` at module scope
    # and spins up a real local WS server. It used to pass only because
    # ``langchain-core`` -> ``langsmith`` -> ``websockets`` happened to
    # pull it in transitively; a langchain/langsmith release that drops
    # that edge would turn the whole module into a collection error.
    # Declared directly so the test suite's WS coverage depends on the
    # websocket extra existing, not on someone else's dependency graph.
    "websockets>=14.0,<17.0",
    "pytest>=8.0",
    "pytest-asyncio>=0.23",
    # Sprint 0 (coverage): ``pytest-rerunfailures`` is used on a
    # single rare-flaky test under pytest-xdist on linux. Pin the
    # lower bound at the version that confirmed working with the
    # ``max_retries`` keyword (>=14.0) and the upper bound below
    # the next major (16.x).
    "pytest-rerunfailures>=14.0,<16.0",
    "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",
    # pytest-cov starts coverage inside every xdist worker and combines
    # their data. Wrapping ``pytest -n auto`` in ``coverage run`` only
    # traces the coordinator process and produces a false 0% report.
    "pytest-cov>=5.0",
    # `langchain-core` is a dev dep so CI exercises the REAL LangChain
    # path, not the SDK's `object` fallback.
    #
    # It was originally here for a different reason, and that reason
    # stopped being true: the SDK used to import
    # `nullrun.instrumentation.langgraph` eagerly (reached from
    # `nullrun.__init__` at collection time), which did an unguarded
    # `from langchain_core.callbacks import BaseCallbackHandler`. With
    # no such dep, *every* test in the suite errored at pytest
    # collection. That import is now guarded — DEF-MP-TS12-SDK-05
    # (RUN_ID 20260929T1338) made it degrade to an `object` base
    # instead, and collection without langchain-core now succeeds
    # (verified: 1449 tests collected, exit 0, with `langchain_core`,
    # `langchain` and `langgraph` all blocked at import).
    #
    # The dep is still required, because the guarded fallback is a
    # DEGRADED mode: with langchain-core absent, the tests that pin
    # `BaseCallbackHandler is the real BaseCallbackHandler`
    # (`test_langgraph_optional`) and that pin LangChain's
    # swallow-exceptions contract (`test_langchain_enforcement`) would
    # SKIP rather than run, and the real integration would go untested.
    # `langchain-core` is the smallest dep that covers both; the
    # `langgraph` and `langchain` extras pull in heavier stacks 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",
    # `tests/test_websocket_extra_is_declared.py` parses
    # `pyproject.toml` at collection time to pin the general
    # "every `nullrun[<extra>]` install hint under `src/` names
    # an extra `pyproject.toml` actually declares" property.
    # `tomllib` is stdlib from 3.11; on 3.10 the test must fall
    # back to `tomli`, and the fallback is only safe if the dep
    # is declared. Conditional on `<3.11` so the upper-bound
    # environments do not pull a redundant package.
    "tomli>=2.0; python_version < '3.11'",
]

# PEP 735 dependency groups. A group is a developer-side install set: it
# never lands in the wheel metadata and it never reaches an end user.
#
# SDK-3 (security audit 2026-11-06) found the publish workflow running
# ``pip install --upgrade build`` and ``pip install twine`` inside the job
# that holds the PyPI Trusted Publishing token. Both resolved at run time,
# inside the trusted-publishing job. The group below puts them in
# ``uv.lock`` with exact pins, so the publish job installs the same bytes
# every run.
#
# The versions are exact on purpose: the lock is the contract, and an
# exact pin says which bytes the lock carries.
#
# These are NOT project extras. ``tests/test_websocket_extra_is_declared.py``
# pins the set of ``[project.optional-dependencies]`` extras to exactly
# {opentelemetry, websocket, dev}, and a build tool has no business in an
# end user's extra.
[dependency-groups]
publish = [
    "build==1.6.1",
    # twine 7.0.0 is the version that understands ``Metadata-Version: 2.5``,
    # which is what hatchling >= 1.30 writes and what nullrun 0.23.0 on
    # PyPI already ships. twine 6.2.0 rejects it ("2.5 is not a valid
    # metadata version"), so ``twine check`` would fail on the project's
    # own artifact.
    "twine==7.0.0",
]

[project.scripts]
# `nullrun-wal` inspects and replays the local write-ahead log. It exists
# because the DLQ holds events the SDK could not deliver and nothing else
# ever reads them: without a supported path to re-submit or at least export
# them, "quarantined" is a polite word for "lost, but on disk".
nullrun-wal = "nullrun.wal_admin:main"

[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",
    # `call-arg` — runtime.execute typed-catalog dispatch path passes
    # kwargs into `typed_cls(...)` where typed_cls is selected at runtime
    # (DEF-NR-RUNTIME-BLOCK-TYPED, introduced in 2e77902). mypy narrows
    # typed_cls to Exception and reports 5 Unexpected keyword argument
    # errors at runtime.py:3213 (workflow_id, reason, action, tool_name,
    # details). The kwargs are catalog-aware via _TYPED_KWARGS_BY_CLASS
    # lookup, so the call is correct at runtime. Concrete fixes would
    # require either (a) a Protocol for typed_cls or (b) splitting the
    # call site per catalog class — both invasive. Tracked here per
    # the comment block above; revisit when the typed-catalog surface
    # stabilises.
    "call-arg",
]

[[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. Tracked for follow-up cleanup
    # in a dedicated PR rather than blocking CI. Categories:
    #   S110 (try/except/pass) - blanket noqa would hide bugs; needs
    #                              logging, not blanket noqa
    #   E501 (line too long)   - long descriptive comments
    #   E402 (import order)    - TYPE_CHECKING blocks
    "S110",
    "E501",
    "E402",
    # S311 (suspicious random) 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 = ["."]
# Sprint 0 (coverage): ``slow_sleep`` opts a test out of the
# conftest autouse ``_fast_sleep`` cap so it can use the real wall
# clock (e.g. for thread-scheduler iterations). Tests that need
# the cap disabled mark themselves with ``@pytest.mark.slow_sleep``.
markers = [
    "slow_sleep: opt out of the conftest autouse time.sleep cap",
    # Sprint 0 (coverage): marks a single test as rare-flaky on
    # pytest-xdist on CI (linux, Python 3.12) — typically a
    # thread-scheduling race between pytest-xdist worker
    # collection and the test's own background thread. The
    # ``pytest-rerunfailures`` plugin (already in dev-deps via the
    # pip install line in ci.yml) retries up to ``max_retries``
    # times. Local pytest on Windows is unaffected.
    "rerunfailures: opt a test into automatic retry via pytest-rerunfailures",
]

[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 = 80
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__.:",
]