pyproject.toml

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

[project]
name = "unified-kg-rag-on-aws"
# Version is sourced from unified_kg_rag.__version__ via [tool.hatch.version].
dynamic = ["version"]
description = "AWS-native Knowledge Graph RAG on Bedrock, Neptune & OpenSearch — GraphRAG and LightRAG over one hexagonal ingestion, indexing, and hybrid-search stack."
readme = "README.md"
requires-python = ">=3.10, <3.13"
license = {text = "Apache-2.0"}
authors = [
    {name = "Amazon.com, Inc. or its affiliates"},
]
keywords = ["aws", "bedrock", "graphrag", "hexagonal-architecture", "knowledge-graph", "lightrag", "neptune", "opensearch", "rag"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "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 :: Text Processing :: Linguistic",
]
dependencies = [
    "asyncio-throttle>=1.0.2",
    "aws-assume-role-lib>=2.10.0",
    "bokeh>=3.9.2",
    "boto3>=1.43.66",
    # Only used for `Dataset.from_dict` in the ragas evaluator. The previous
    # <4.0.0 ceiling held ragas back to 0.3.2, which imports a module that
    # langchain-community removed in 0.4 — see the ragas floor below.
    "datasets>=4.0.0",
    "datasketch>=2.0.0",
    "graspologic>=3.4.1",
    # Pinned below 3.8: that release added the `discard()` step and routes
    # `Cardinality.single` property writes through it, which Neptune (engine
    # 1.4.7.0, TinkerPop 3.6/3.7) rejects with
    # `InternalFailureException: Could not locate method:
    # NeptuneGraphTraversal.discard()`. Every vertex and edge write fails, so a
    # real ingest indexes 0 entities. Unit tests use a fake Neptune client and
    # cannot see this. Raise only once Neptune's engine reports TinkerPop 3.8.
    "gremlinpython>=3.6.3,<3.8.0",
    # LangChain 1.x. The floors are the releases that carry the fixes for
    # GHSA-qh6h-p6c9-ff54 (langchain-core path traversal), GHSA-gr75-jv2w-4656
    # (langchain loader path traversal), GHSA-fv5p-p927-qmxr (splitter SSRF) and
    # GHSA-2g6r-c272-w58r; none of them were backported to 0.3.x, so the old
    # `<1.0.0` ceiling made them unreachable. langchain-classic supplies the
    # legacy `langchain.*` modules that 1.x removed (evaluation, memory,
    # OutputFixingParser) and is a direct import, so it is declared here.
    "langchain>=1.3.9,<2.0.0",
    "langchain-aws>=1.7.0,<2.0.0",
    "langchain-classic>=1.0.0,<2.0.0",
    # Held at 0.3.x: ragas imports langchain_community.chat_models.vertexai
    # unconditionally, and 0.4 removed that module — 0.4 also puts the whole
    # package into sunset, so the document loaders used by the parser should move
    # to standalone packages rather than follow it forward.
    "langchain-community>=0.3.27,<0.4.0",
    "langchain-core>=1.5.3,<2.0.0",
    "langchain-text-splitters>=1.1.2,<2.0.0",
    "llvmlite>=0.48.0",
    "lxml>=6.0.0",
    "nest-asyncio>=1.6.0",
    "networkx>=3.4",
    "numpy>=1.26.4",
    "opensearch-py>=3.0.0",
    "pandas>=2.3.1",
    "pillow>=12.3.0",
    "pydantic>=2.11.7",
    "pypdf>=6.15.0",
    "python-dotenv>=1.1.1",
    "pyvis>=0.3.2",
    "pyyaml>=6.0.2",
    # ragas 0.3.2 imports langchain_community.chat_models.vertexai, removed in
    # community 0.4, so it cannot coexist with LangChain 1.x. Every ragas that
    # can requires datasets>=4.0.0.
    "ragas>=0.4.3,<0.5.0",
    "rapidfuzz>=3.13.0",
    "rich>=15.0.0",
    "scikit-learn>=1.7.1",
    "structlog>=25.4.0",
    "tenacity>=9.1.2",
    "tqdm>=4.70.0",
    "umap-learn>=0.5.6",
]

[project.scripts]
run-ingestion = "unified_kg_rag.application.cli.run_ingestion_pipeline:main"
run-rag = "unified_kg_rag.application.cli.run_rag_chain:main"
run-eval = "unified_kg_rag.application.cli.run_evaluation:main"
run-visualization = "unified_kg_rag.application.cli.run_visualization:main"
run-prompt-tuning = "unified_kg_rag.application.cli.run_prompt_tuning:main"

[project.optional-dependencies]
dev = [
    "black>=25.9.0",
    "hypothesis>=6.165.2",
    "isort>=5.12.0",
    "moto[dynamodb,s3]>=5.2.2",
    "mypy>=2.3.0",
    "pre-commit>=4.6.1",
    "pytest>=9.1.1",
    "pytest-asyncio>=1.0.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.12.0",
    "ruff>=0.16.1",
    # boto3 type stubs (mypy only): boto3-stubs covers the top-level boto3
    # package; types-boto3 covers the per-service clients used under TYPE_CHECKING.
    "boto3-stubs~=1.43.66",
    "types-boto3[full]>=1.43.66",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.7.7",
    "mkdocstrings[python]>=1.0.6",
]
# Optional: enables .md/.markdown/.html/.htm source parsing (heavy transitive
# deps, so not installed by default). The ParserFactory registers those formats
# only when this is importable; .txt/.csv/.json/.pdf work without it.
unstructured = [
    "unstructured>=0.14.0",
]

[project.urls]
Repository = "https://github.com/awslabs/unified-kg-rag-on-aws"

[tool.hatch.version]
path = "unified_kg_rag/__init__.py"

[tool.hatch.build.targets.wheel]
packages = ["unified_kg_rag"]

[tool.hatch.build.targets.sdist]
# Ship only the package + top-level project files; never bundle build/venv
# artifacts (IaC CDK venvs, caches, references) into the source distribution.
only-include = ["unified_kg_rag", "README.md", "LICENSE", "pyproject.toml"]

[tool.black]
line-length = 88
# Match requires-python's floor. These were py311, which let ruff's pyupgrade
# rewrite `timezone.utc` to the 3.11-only `datetime.UTC` and broke every install
# on the declared minimum.
target-version = ['py310', 'py311', 'py312']
include = '\.pyi?$'
extend-exclude = '''
/(
    \.eggs
    | \.git
    | \.hg
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
)/
'''

[tool.isort]
profile = "black"
multi_line_output = 3
line_length = 88
known_first_party = ["unified_kg_rag"]
skip_gitignore = true

[tool.ruff]
line-length = 88
# Must track requires-python's floor: pyupgrade (UP) rewrites code to the target
# version's idioms, so py311 here actively introduced 3.11-only syntax into a
# package that claims 3.10 support.
target-version = "py310"

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # pyflakes
    "I",  # isort
    "B",  # flake8-bugbear
    "C4", # flake8-comprehensions
    "UP", # pyupgrade
    "G",  # flake8-logging-format (enforce %-style lazy logging, no f-strings)
]
ignore = [
    "E501",  # line too long, handled by black
    "B008",  # do not perform function calls in argument defaults
    "UP042", # str+Enum is intentional (StrEnum changes str()/format semantics)
    # ~507 logging calls were converted to %-style lazy logging; the ~45 G004 +
    # 7 G201 that remain carry format specs (e.g. %.2f) or conversions that need
    # case-by-case handling. Ignored for now so the rest of the G ruleset
    # (G002/G010/G101/...) stays active and guards new code.
    "G004",  # f-string in logging call
    "G201",  # logging.error(..., exc_info=True) vs logging.exception()
]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/**/*.py" = ["B018"]

[tool.mypy]
# Type-check against the oldest supported interpreter, so stdlib symbols added
# after it are reported here rather than at a user's import time.
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
show_error_codes = true

[[tool.mypy.overrides]]
module = [
    "gremlin_python.*",
    "datasketch.*",
    "networkx.*",
    "pandas.*",
    "pyvis.*",
    "ragas.*",
    "sklearn.*",
    "umap.*",
    "datasets.*",
    "lxml.*",
    "nest_asyncio.*",
    "tqdm.*",
    "yaml.*",
    "bokeh.*",
]
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --tb=short --strict-markers"
asyncio_mode = "auto"
markers = [
    "unit: Unit tests",
    "integration: Integration tests",
    "property: Property-based tests (hypothesis)",
    "aws: Tests requiring real AWS services (skipped by default)",
    "slow: Slow tests",
]
filterwarnings = [
    "ignore::DeprecationWarning",
    "ignore::PendingDeprecationWarning",
]

[tool.coverage.run]
source = ["unified_kg_rag"]
omit = [
    "tests/*",
    "*/test_*.py",
    "*/__init__.py",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
]

[dependency-groups]
# Mirrors [project.optional-dependencies].dev so `uv sync` installs the full
# dev toolchain without an extra flag. Keep the two lists in sync.
dev = [
    "black>=25.9.0",
    "hypothesis>=6.165.2",
    "isort>=5.12.0",
    "moto[dynamodb,s3]>=5.2.2",
    "mypy>=2.3.0",
    "pre-commit>=4.6.1",
    "pytest>=9.1.1",
    "pytest-asyncio>=1.0.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.12.0",
    "ruff>=0.16.1",
    # boto3 type stubs (mypy only): boto3-stubs covers the top-level boto3
    # package; types-boto3 covers the per-service clients used under TYPE_CHECKING.
    "boto3-stubs~=1.43.66",
    "types-boto3[full]>=1.43.66",
]