pyproject.toml

[project]
name = "agentflow-runtime"
version = "2.1.0"
description = "Real-time data platform serving context to AI agents"
readme = "README.md"
requires-python = ">=3.11"
license = { text = "MIT" }

dependencies = [
    "argon2-cffi>=23,<26",
    "bcrypt>=5,<6",
    "confluent-kafka>=2.5,<3",
    "fastapi>=0.111,<1",
    "uvicorn[standard]>=0.30,<1",
    "dagster>=1.13.1,<2",
    "duckdb>=1.1,<2",
    "httpx>=0.27,<1",
    "opentelemetry-exporter-otlp-proto-grpc>=1.41,<2",
    "opentelemetry-instrumentation-fastapi>=0.62b0,<1",
    "opentelemetry-instrumentation-httpx>=0.62b0,<1",
    "opentelemetry-sdk>=1.41,<2",
    "pandera>=0.20,<1",
    "prometheus-client>=0.21,<1",
    "pyarrow>=17,<26",
    "pydantic>=2.9,<3",
    "pydantic-settings>=2.5,<3",
    "pyyaml>=6,<7",
    "redis>=5,<9",
    "sqlglot>=30,<31",
    "structlog>=24.4,<27",
]

[project.optional-dependencies]
# There is deliberately no [flink] extra. apache-flink 2.3.0 -> apache-beam
# <=2.61 caps pyarrow<17 while the core dependencies pin pyarrow>=17, so an
# extra could never resolve in one environment (a fresh
# `pip install .[flink]` fails outright). The Flink job runs in its own
# interpreter inside the cluster image and imports nothing from agentflow;
# its manifest is src/agentflow_runtime/processing/flink_jobs/requirements.txt.
cloud = [
    "boto3>=1.35,<2",
    "pyiceberg>=0.7,<1",
    # PyIceberg 0.11 write paths require native transforms, and 0.7 is the
    # only core release that can serve them here. PyIceberg 0.11.1 declares
    # pyiceberg-core>=0.5.1,<0.9.0, so 0.8.0 is the only step up inside the
    # pairing upstream supports -- and 0.8.0 is the one release in the line
    # published as requires-python <3.13, which the 3.11-3.13 resolution
    # environments below rule out. (0.9+ restored 3.13 but sits outside
    # PyIceberg's declared window; nothing in that window is installable.)
    # The ceiling moves when PyIceberg raises its own, not before.
    "pyiceberg-core>=0.7,<0.8",
]
postgres = [
    # ADR 0010 slice 5: PostgresControlPlaneStore (scale profile). Optional
    # because the embedded default profile needs none of it, and
    # control_plane/postgres.py degrades to a clear boot error without it.
    # The pool extra ships psycopg_pool: the store's connections come from a
    # bounded ConnectionPool (audit P1-1), not one connect() per method call.
    "psycopg[binary,pool]>=3.2,<4",
]
load = [
    "locust>=2.29,<3",
    # benchmark_freshness.py: production QueryCache semantics (TTL + key
    # invalidation) without a Redis server on the benchmark host.
    "fakeredis>=2.21,<3",
]
integrations = [
    # langchain-core >=1.2.22 closes CVE-2026-26013 (SSRF via image_url) and
    # CVE-2026-34070 (path traversal in legacy load_prompt). Bumping the
    # langchain umbrella forces a transitive resolve of langchain-core that
    # satisfies these floors. langchain-text-splitters >=1.1.2 closes
    # GHSA-fv5p-p927-qmxr (SSRF redirect bypass). See audit p9.
    "langchain>=0.3.30,<2",
    "langchain-core>=1.2.22,<2",
    "langchain-text-splitters>=1.1.2,<2",
    # langgraph powers the vendored NL->SQL generation pipeline
    # (src/agentflow_runtime/serving/semantic_layer/nl_sql_engine, ADR 0008). It is an *optional*
    # dependency, not core: the shipped demo default is the rule-based
    # translator (GRACEKELLY_URL unset), and nl_engine lazy-imports the engine
    # only on the opt-in LLM path — so a core install needs no langgraph.
    "langgraph>=1,<2",
    "langsmith>=0.7.31,<1",
    "llama-index-core>=0.12,<1",
    # Mirrors integrations/pyproject.toml [mcp]: locking it here lets CI
    # install the editable integrations package with --no-deps from the
    # frozen root resolution (audit F-05). The ceiling is load-bearing:
    # mcp 2.x's lowlevel Server no longer defines list_tools or call_tool
    # (checked against 2.2.0), and integrations/.../mcp/server.py builds its
    # whole surface out of @server.list_tools() and @server.call_tool().
    # Taking mcp 2 means porting that module first, not moving this pin.
    "mcp>=1.0,<2",
]
contract = [
    "schemathesis==4.25.2",
]
dev = [
    "bandit>=1.9,<2",
    "build>=1.2,<2",
    "diff-cover>=9,<11",
    "hatchling>=1.25,<2",
    "hypothesis>=6,<7",
    "jsonschema>=4,<5",
    "mkdocs>=1.6,<2",
    "mkdocs-material>=9.6,<10",
    # NumPy 2.5.0 requires Python >=3.12; 3.11 is a supported floor here, so
    # the ceiling is what keeps the lock resolvable across 3.11-3.13 rather
    # than a preference. (The ceiling was <2.4 from 2026-07-23, recorded as
    # "NumPy 2.4+ bundles PEP 695 syntax in its stubs" -- the released 2.4.0
    # and 2.4.6 wheels ship 264 stub files with no PEP 695 syntax in any of
    # them, so that reason does not hold for the 2.4 line. The mypy half is
    # still true and still worth watching: mypy 2.2.0 at --python-version 3.11
    # rejects a `type` statement outright, so a future stub release that uses
    # one turns lint red rather than degrading.) This is a dev/type-checking
    # constraint, not an application runtime dependency.
    "numpy>=2,<2.5",
    "pandas>=2.2,<4",
    "pytest>=8.3,<10",
    "pytest-asyncio>=0.24,<2",
    "pytest-cov>=5,<8",
    # Previously installed ad hoc by e2e.yml / chaos.yml / mutation.yml
    # outside any lock; declaring them here brings those lanes onto the
    # frozen resolution (audit F-05).
    "pytest-timeout>=2.3,<3",
    "pytest-json-report>=1.5,<2",
    "mutmut>=3,<4",
    "testcontainers[kafka]>=4.9,<5",
    "ruff>=0.6,<1",
    "mypy>=1.11,<3",
    "types-PyYAML>=6,<7",
    "types-redis>=4.6,<6",
]

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

# The runtime ships as `agentflow_runtime` (audit F-09 / P2-6 Phase 1-2);
# the repository `src/` directory is a plain container, not a package. The
# deprecated one-file `src` shim (packaging/src_shim) aliases `src.*` onto
# `agentflow_runtime.*` with a DeprecationWarning and is removed in the next
# major release. Explicit only-include + sources maps (not the `packages`
# shorthand) because the shorthand's implied `src/` strip would also rewrite
# the shim's target path.
[tool.hatch.build.targets.wheel]
only-include = ["src/agentflow_runtime", "packaging/src_shim/src"]

[tool.hatch.build.targets.wheel.sources]
"src/agentflow_runtime" = "agentflow_runtime"
"packaging/src_shim/src" = "src"

[tool.hatch.build.targets.sdist]
include = [
    "/src",
    "/packaging",
    "/README.md",
    "/LICENSE",
    "/CHANGELOG.md",
    "/pyproject.toml",
    "/requirements.txt",
]
exclude = [
    "/config/webhooks.yaml",
    "/config/api_keys.yaml",
    "/config/tenants.yaml",
    "/docker/**/secrets/**",
    "/.github/**",
    "/.tmp*/",
    "/notebooks/**",
    "/audit_*.md",
    "/audit_codex/**",
    "/.env*",
    "/k8s/**",
    "/helm/**",
    "/examples/**",
    "/integrations/**",
    "/sdk/**",
    "/sdk-ts/**",
    "/tests/**",
    "/docs/**",
    "/mutants/**",
    "/.dora/**",
]

[tool.uv]
# Audit P1-3: `requires-python = ">=3.11"` above has no upper bound, so a
# plain `uv lock` builds one universal resolution covering every Python
# version that floor implies — including hypothetical future interpreters.
# Restrict resolution to the versions README/CI actually ship and test
# (3.11-3.13) so the lock stays scoped to what is real.
environments = [
    "python_version == '3.11'",
    "python_version == '3.12'",
    "python_version == '3.13'",
]
# A `constraint-dependencies = ["jsonschema-rs<0.50"]` pin lived here from
# schemathesis 4.24.x, which declared jsonschema-rs>=0.49.0 with no ceiling
# while calling CanonicalSchema.is_satisfiable — removed in jsonschema-rs
# 0.50.0, so tests/contract failed with AttributeError on 0.50.x. It was
# written to last "until schemathesis fixes its range upstream", and 4.25.0
# does: it declares jsonschema-rs>=0.51.0,<0.52.0, a pairing upstream tests.
# Keeping the old ceiling now makes the two ranges disjoint, which is what
# blocked the 4.25.2 bump. Do not re-add it without a new reason.

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

[tool.ruff.format]
# The golden-soak source pack is byte-pinned by MANIFEST.json; formatting it
# would invalidate the immutable runtime identity. The legacy source file
# below is predominantly CRLF with small LF-only blocks. (The former
# control_plane/embedded.py entry left with the audit F-08 split — the
# rewritten facade and capability modules are ordinary LF files.)
exclude = [
    "scripts/golden_soak/pack/*.py",
    "src/agentflow_runtime/quality/validators/semantic_validator.py",
]

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "PT"]
ignore = ["S101", "S311"]

[tool.ruff.lint.per-file-ignores]
# Operational tooling: sys.path bootstrap before imports (E402) and
# fixed-argv subprocess calls to git/npm/mutmut (S603/S607) are the
# intentional script idiom, same as the tests/** allowance below.
"scripts/**/*.py" = [
    "E402",
    "S603",
    "S607",
]
# Keep meaningful lint coverage on the immutable pack while waiving only its
# recorded formatting and controlled operational-input findings.
"scripts/golden_soak/pack/*.py" = [
    "E501",
    "I001",
    "S110",
    "S112",
    "S310",
    "S608",
]
# Benchmark harness builds ClickHouse SQL from internal literals only
# (band cut points, table names from the checked-in DDL list) and opens a
# fixed http:// endpoint given on the CLI — S608/S310 have no external input.
"scripts/benchmark_scale_own_data.py" = [
    "S608",
    "S310",
]
"tests/**/*.py" = [
    "S603",
    "S607",
    "S608",
    "S310",
    "S104",
    "S106",
    "N802",
    "N805",
    "E402",
    "B017",
    "PT011",
    "A002",
    "E501",
]
"src/agentflow_runtime/orchestration/dags/daily_batch.py" = [
    "S608",
]
"src/agentflow_runtime/serving/api/routers/lineage.py" = [
    "S608",
]
# Interpolations are internal literals only (the _replace_record_set
# table-name constant — audit F-08 moved it here from postgres.py); all
# values bind via %s.
"src/agentflow_runtime/serving/control_plane/postgres_base.py" = [
    "S608",
]
"src/agentflow_runtime/serving/api/routers/slo.py" = [
    "S608",
]
"src/agentflow_runtime/serving/api/routers/stream.py" = [
    "S608",
]
"src/agentflow_runtime/serving/backends/clickhouse_backend.py" = [
    "S310",
    "S608",
    "E501",
]
"src/agentflow_runtime/serving/backends/duckdb_backend.py" = [
    "S608",
    "E501",
]
# Serving-store mirror for the local pipeline: table/column identifiers are
# module constants, values are single-quote-escaped literals that the backend's
# sqlglot round-trip re-escapes structurally (see ClickHouseBackend docstring).
"src/agentflow_runtime/processing/clickhouse_sink.py" = [
    "S608",
]
# fetch_pipeline_events: selected columns come from the backend schema probe
# (fixed allowlist), values are `?`-bound on DuckDB and _quote_literal-escaped
# on external backends — same convention as entity_queries.py.
"src/agentflow_runtime/serving/semantic_layer/query/engine.py" = [
    "S608",
]
"src/agentflow_runtime/serving/semantic_layer/nl_engine.py" = [
    "S608",
]
"src/agentflow_runtime/serving/semantic_layer/query/entity_queries.py" = [
    "S608",
]
"src/agentflow_runtime/serving/semantic_layer/query/nl_queries.py" = [
    "S608",
]
"src/agentflow_runtime/serving/semantic_layer/search_index.py" = [
    "S608",
]
# Raw-vault INSERT builder: table/column names are internal constants (vault
# table names + pydantic model fields / the curated VAULT_DB_COLUMNS map), and
# every value is parameter-bound (%s). Safe-by-construction interpolation of
# identifiers, which placeholders cannot carry.
"warehouse/agentflow/dv2/loaders/pg_vault_writer.py" = [
    "S608",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = ["-p", "no:schemathesis"]
cache_dir = ".tmp/pytest-cache"
markers = [
    "integration: marks tests requiring Docker services",
    "requires_docker: marks tests that require local Docker",
]
asyncio_mode = "auto"

[tool.mutmut]
# This list is the *declared* mutation-target policy, enforced by
# tests/unit/test_mutmut_policy.py (paths exist, define real logic, cover the
# security-critical surfaces). It is a superset of what the CI gate actually
# mutates: scripts/mutation_report.py drives the gate from its own
# MODULE_TARGETS, which now mutates sdk/agentflow/retry.py,
# src/agentflow_runtime/serving/semantic_layer/sql_guard.py,
# src/agentflow_runtime/serving/api/rate_limiter.py, src/agentflow_runtime/serving/semantic_layer/query/sql_builder.py,
# src/agentflow_runtime/serving/semantic_layer/query/nl_queries.py, src/agentflow_runtime/serving/api/auth/manager.py
# AND src/agentflow_runtime/serving/api/auth/key_rotation.py live -- every declared serving surface
# is now mutated. The serving modules are mutated as a top-level `serving` package
# against duckdb-free narrow tests: mutmut's trampoline rejects a module name
# starting with `src.`, which (not duckdb) was the real blocker. (The gate runner
# keeps mutmut workspaces free of relative pytest --basetemp overrides because
# under py3.11 they break coverage->mutant mapping for file-I/O targets like
# key_rotation; see scripts/mutation_report.py.) manager.py gates at 0.90 like
# the other serving modules; scripts/mutation_report.py gives its measured
# score and names its nine equivalent survivors.
paths_to_mutate = [
    "src/agentflow_runtime/serving/api/auth/manager.py",
    "src/agentflow_runtime/serving/api/auth/key_rotation.py",
    "src/agentflow_runtime/serving/semantic_layer/query/engine.py",
    "src/agentflow_runtime/serving/semantic_layer/query/entity_queries.py",
    "src/agentflow_runtime/serving/semantic_layer/query/metric_queries.py",
    "src/agentflow_runtime/serving/semantic_layer/query/nl_queries.py",
    "src/agentflow_runtime/serving/semantic_layer/query/sql_builder.py",
    "src/agentflow_runtime/serving/semantic_layer/sql_guard.py",
    "src/agentflow_runtime/processing/outbox.py",
    "src/agentflow_runtime/serving/api/rate_limiter.py",
]
also_copy = [
    "src",
    "config",
    "sdk",
]
tests_dir = [
    "tests/unit",
    "tests/property",
    "tests/integration/test_outbox.py",
]
mutate_only_covered_lines = true

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
# Strict-by-default: every function under src/ must carry full type
# annotations, with ZERO per-module relaxations (the last one, the formerly
# PyFlink-stub-gated flink_jobs package, was hand-annotated 2026-06-05). A
# new untyped def anywhere in src/ now fails mypy. The strict invariant is
# gated by tests/unit/test_typing_policy.py.
disallow_untyped_defs = true
check_untyped_defs = true
ignore_missing_imports = true

[tool.agentflow.dependency-profiles.profiles.runtime]
editable-installs = ["."]

[tool.agentflow.dependency-profiles.profiles.dev-tools]
editable-installs = [".[dev]"]

[tool.agentflow.dependency-profiles.profiles.test]
editable-installs = [".[dev,cloud]"]

[tool.agentflow.dependency-profiles.profiles.test-sdk]
# postgres: the CI integration job drives the PostgresControlPlaneStore live
# suite against its postgres:17 service (ADR 0010 slice 5), so it needs the
# optional psycopg extra.
editable-installs = [".[dev,cloud,postgres]", "./sdk"]

[tool.agentflow.dependency-profiles.profiles.test-integrations]
editable-installs = [".[dev,cloud]", "./sdk", "./integrations[mcp]"]

[tool.agentflow.dependency-profiles.profiles.load]
editable-installs = [".[load,cloud]"]

[tool.agentflow.dependency-profiles.profiles.perf]
editable-installs = [".[dev,load,cloud]"]

[tool.agentflow.dependency-profiles.profiles.contract]
editable-installs = [".[dev,cloud,contract]", "./sdk"]

[tool.agentflow.dependency-profiles.profiles.e2e]
editable-installs = [".[dev]", "./sdk"]

[[tool.agentflow.dependency-profiles.targets]]
name = "backup.backup"
kind = "workflow"
path = ".github/workflows/backup.yml"
job = "backup"
profile = "dev-tools"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.lint"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "lint"
profile = "dev-tools"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.local-duckdb-smoke"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "local-duckdb-smoke"
profile = "runtime"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.schema-check"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "schema-check"
profile = "dev-tools"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.test-unit"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "test-unit"
profile = "test-integrations"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.test-integration"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "test-integration"
profile = "test-sdk"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.helm-schema-live"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "helm-schema-live"
profile = "dev-tools"

[[tool.agentflow.dependency-profiles.targets]]
name = "ci.perf-check"
kind = "workflow"
path = ".github/workflows/ci.yml"
job = "perf-check"
profile = "perf"

[[tool.agentflow.dependency-profiles.targets]]
name = "benchmark-arm.benchmark-arm"
kind = "workflow"
path = ".github/workflows/benchmark-arm.yml"
job = "benchmark-arm"
profile = "perf"

[[tool.agentflow.dependency-profiles.targets]]
name = "chaos.chaos-smoke"
kind = "workflow"
path = ".github/workflows/chaos.yml"
job = "chaos-smoke"
profile = "test"

[[tool.agentflow.dependency-profiles.targets]]
name = "chaos.chaos-full"
kind = "workflow"
path = ".github/workflows/chaos.yml"
job = "chaos-full"
profile = "test"

[[tool.agentflow.dependency-profiles.targets]]
name = "contract.contract"
kind = "workflow"
path = ".github/workflows/contract.yml"
job = "contract"
profile = "contract"

[[tool.agentflow.dependency-profiles.targets]]
name = "e2e.e2e"
kind = "workflow"
path = ".github/workflows/e2e.yml"
job = "e2e"
profile = "e2e"

[[tool.agentflow.dependency-profiles.targets]]
name = "load-test.load-test"
kind = "workflow"
path = ".github/workflows/load-test.yml"
job = "load-test"
profile = "load"

[[tool.agentflow.dependency-profiles.targets]]
name = "mutation.mutation"
kind = "workflow"
path = ".github/workflows/mutation.yml"
job = "mutation"
profile = "test"

[[tool.agentflow.dependency-profiles.targets]]
name = "performance.perf-baseline"
kind = "workflow"
path = ".github/workflows/performance.yml"
job = "perf-baseline"
profile = "perf"

[[tool.agentflow.dependency-profiles.targets]]
name = "perf-regression.perf-smoke"
kind = "workflow"
path = ".github/workflows/perf-regression.yml"
job = "perf-smoke"
profile = "perf"

[[tool.agentflow.dependency-profiles.targets]]
name = "staging-deploy.staging"
kind = "workflow"
path = ".github/workflows/staging-deploy.yml"
job = "staging"
profile = "e2e"